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

NAME

6       pidfd_open - obtain a file descriptor that refers to a process
7

SYNOPSIS

9       #include <sys/syscall.h>      /* Definition of SYS_* constants */
10       #include <unistd.h>
11
12       int syscall(SYS_pidfd_open, pid_t pid, unsigned int flags);
13
14       Note: glibc provides no wrapper for pidfd_open(), necessitating the use
15       of syscall(2).
16

DESCRIPTION

18       The pidfd_open() system call creates a file descriptor that  refers  to
19       the  process whose PID is specified in pid.  The file descriptor is re‐
20       turned as the function result; the close-on-exec flag  is  set  on  the
21       file descriptor.
22
23       The  flags  argument  either has the value 0, or contains the following
24       flag:
25
26       PIDFD_NONBLOCK (since Linux 5.10)
27              Return a nonblocking file descriptor.  If the  process  referred
28              to  by  the  file descriptor has not yet terminated, then an at‐
29              tempt to wait on the file descriptor using waitid(2) will  imme‐
30              diately return the error EAGAIN rather than blocking.
31

RETURN VALUE

33       On success, pidfd_open() returns a file descriptor (a nonnegative inte‐
34       ger).  On error, -1 is returned and errno is set to indicate the error.
35

ERRORS

37       EINVAL flags is not valid.
38
39       EINVAL pid is not valid.
40
41       EMFILE The per-process limit on the number of open file descriptors has
42              been  reached  (see  the  description  of RLIMIT_NOFILE in getr‐
43              limit(2)).
44
45       ENFILE The system-wide limit on the total number of open files has been
46              reached.
47
48       ENODEV The anonymous inode filesystem is not available in this kernel.
49
50       ENOMEM Insufficient kernel memory was available.
51
52       ESRCH  The process specified by pid does not exist.
53

VERSIONS

55       pidfd_open() first appeared in Linux 5.3.
56

CONFORMING TO

58       pidfd_open() is Linux specific.
59

NOTES

61       The following code sequence can be used to obtain a file descriptor for
62       the child of fork(2):
63
64           pid = fork();
65           if (pid > 0) {     /* If parent */
66               pidfd = pidfd_open(pid, 0);
67               ...
68           }
69
70       Even  if  the  child  has  already  terminated  by  the  time  of   the
71       pidfd_open() call, its PID will not have been recycled and the returned
72       file descriptor will refer to the resulting zombie process.  Note, how‐
73       ever,  that  this  is  guaranteed only if the following conditions hold
74       true:
75
76       • the disposition of SIGCHLD has not been  explicitly  set  to  SIG_IGN
77         (see sigaction(2));
78
79       • the