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       #include <sys/syscall.h>      /* Definition of SYS_* constants */
10       #include <unistd.h>
11
12       int syscall(SYS_pidfd_getfd, int pidfd, int targetfd,
13                   unsigned int flags);
14
15       Note:  glibc  provides  no wrapper for pidfd_getfd(), necessitating the
16       use of syscall(2).
17

DESCRIPTION

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

RETURN VALUE

42       On success, pidfd_getfd() returns a file descriptor (a nonnegative  in‐
43       teger).   On error, -1 is returned and errno is set to indicate the er‐
44       ror.
45

ERRORS

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

VERSIONS

69       pidfd_getfd() first appeared in Linux 5.6.
70

CONFORMING TO

72       pidfd_getfd() is Linux specific.
73

NOTES

75       For a description of PID file descriptors, see pidfd_open(2).
76
77       The  effect  of  pidfd_getfd() is similar to the use of SCM_RIGHTS mes‐
78       sages described in unix(7), but differs in the following respects:
79
80       • In order to pass a file descriptor using an SCM_RIGHTS  message,  the
81         two processes must first establish a UNIX domain socket connection.
82
83       • The use of SCM_RIGHTS requires cooperation on the part of the process
84         whose file descriptor is being copied.  By contrast, no such coopera‐
85         tion is necessary when using pidfd_getfd().
86
87       • The  ability  to use pidfd_getfd() is restricted by a PTRACE_MODE_AT‐
88         TACH_REALCREDS ptrace  access  mode check.
89

COLOPHON

94       This page is part of release 5.13 of the Linux  man-pages  project.   A
95       description  of  the project, information about reporting bugs, and the
96       latest    version    of    this    page,    can     be     found     at
97       https://www.kernel.org/doc/man-pages/.
98
99
100
101Linux                             2021-03-22                    PIDFD_GETFD(2)