pidfd_getfd(2)

1pidfd_getfd(2)                System Calls Manual               pidfd_getfd(2)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/syscall.h>      /* Definition of SYS_* constants */
13       #include <unistd.h>
14
15       int syscall(SYS_pidfd_getfd, int pidfd, int targetfd,
16                   unsigned int flags);
17
18       Note:  glibc  provides  no wrapper for pidfd_getfd(), necessitating the
19       use of syscall(2).
20

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

STANDARDS

72       Linux.
73

HISTORY

75       Linux 5.6.
76

NOTES

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