pidfd_getfd(2)

1PIDFD_GETFD(2)             Linux Programmer's Manual            PIDFD_GETFD(2)
2
3
4

NAME

6       pidfd_getfd - obtain a duplicate of another process's file descriptor
7

SYNOPSIS

9       int pidfd_getfd(int pidfd, int targetfd, unsigned int flags);
10

DESCRIPTION

12       The  pidfd_getfd()  system  call allocates a new file descriptor in the
13       calling process.  This new file descriptor is a duplicate of an  exist‐
14       ing  file  descriptor,  targetfd, in the process referred to by the PID
15       file descriptor pidfd.
16
17       The duplicate file descriptor refers to the same open file  description
18       (see  open(2))  as the original file descriptor in the process referred
19       to by pidfd.  The two file descriptors thus share file status flags and
20       file  offset.   Furthermore,  operations  on the underlying file object
21       (for example, assigning an address to a socket  object  using  bind(2))
22       can equally be performed via the duplicate file descriptor.
23
24       The  close-on-exec  flag  (FD_CLOEXEC; see fcntl(2)) is set on the file
25       descriptor returned by pidfd_getfd().
26
27       The flags argument is reserved for future use.  Currently, it  must  be
28       specified as 0.
29
30       Permission  to  duplicate another process's file descriptor is governed
31       by  a  ptrace  access  mode  PTRACE_MODE_ATTACH_REALCREDS  check   (see
32       ptrace(2)).
33

RETURN VALUE

35       On  success,  pidfd_getfd()  returns  a  file descriptor (a nonnegative
36       integer).  On error, -1 is returned and errno is set  to  indicate  the
37       cause of the error.
38

ERRORS

40       EBADF  pidfd is not a valid PID file descriptor.
41
42       EBADF  targetfd  is not an open file descriptor in the process referred
43              to by pidfd.
44
45       EINVAL flags is not 0.
46
47       EMFILE The per-process limit on the number of open file descriptors has
48              been  reached  (see  the  description  of RLIMIT_NOFILE in getr‐
49              limit(2)).
50
51       ENFILE The system-wide limit on the total number of open files has been
52              reached.
53
54       EPERM  The  calling  process  did not have PTRACE_MODE_ATTACH_REALCREDS
55              permissions (see ptrace(2)) over  the  process  referred  to  by
56              pidfd.
57
58       ESRCH  The  process  referred  to by pidfd does not exist (i.e., it has
59              terminated and been waited on).
60

VERSIONS

62       pidfd_getfd() first appeared in Linux 5.6.
63

CONFORMING TO

65       pidfd_getfd() is Linux specific.
66

NOTES

68       Currently, there is no glibc wrapper for  this  system  call;  call  it
69       using syscall(2).
70
71       For a description of PID file descriptors, see pidfd_open(2).
72
73       The  effect  of  pidfd_getfd() is similar to the use of SCM_RIGHTS mes‐
74       sages described in unix(7), but differs in the following respects:
75
76       · In order to pass a file descriptor using an SCM_RIGHTS  message,  the
77         two processes must first establish a UNIX domain socket connection.
78
79       · The use of SCM_RIGHTS requires cooperation on the part of the process
80         whose file descriptor is being copied.  By contrast, no such coopera‐
81         tion is necessary when using pidfd_getfd().
82
83       · The    ability    to   use   pidfd_getfd()   is   restricted   by   a
84         PTRACE_MODE_ATTACH_REALCREDS ptrace  access  mode check.
85

COLOPHON

90       This page is part of release 5.07 of the Linux  man-pages  project.   A
91       description  of  the project, information about reporting bugs, and the
92       latest    version    of    this    page,    can     be     found     at
93       https://www.kernel.org/doc/man-pages/.
94
95
96
97Linux                             2020-03-31                    PIDFD_GETFD(2)