pidfd_open(2)

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  SA_NOCLDWAIT flag was not specified while establishing a handler
80         for SIGCHLD or while  setting  the  disposition  of  that  signal  to
81         SIG_DFL (see sigaction(2)); and
82
83       • the zombie process was not reaped elsewhere in the program (e.g., ei‐
84         ther by an asynchronously executed signal handler or  by  wait(2)  or
85         similar in another thread).
86
87       If any of these conditions does not hold, then the child process (along
88       with a PID file descriptor that refers to it) should instead be created
89       using clone(2) with the CLONE_PIDFD flag.
90
91   Use cases for PID file descriptors
92       A PID file descriptor returned by pidfd_open() (or by clone(2) with the
93       CLONE_PID flag) can be used for the following purposes:
94
95       • The pidfd_send_signal(2) system call can be used to send a signal  to
96         the process referred to by a PID file descriptor.
97
98       • A  PID file descriptor can be monitored using poll(2), select(2), and
99         epoll(7).  When the process that it refers to terminates,  these  in‐
100         terfaces  indicate  the  file descriptor as readable.  Note, however,
101         that in the current implementation, nothing can be read from the file
102         descriptor  (read(2) on the file descriptor fails with the error EIN‐
103         VAL).
104
105       • If the PID file descriptor refers to a child of the calling  process,
106         then it can be waited on using waitid(2).
107
108       • The pidfd_getfd(2) system call can be used to obtain a duplicate of a
109         file descriptor of another process referred to by a PID file descrip‐
110         tor.
111
112       • A  PID file descriptor can be used as the argument of setns(2) in or‐
113         der to move into one or more of the same namespaces  as  the  process
114         referred to by the file descriptor.
115
116       • A  PID  file  descriptor  can be used as the argument of process_mad‐
117         vise(2) in order to provide advice on the memory  usage  patterns  of
118         the process referred to by the file descriptor.
119
120       The  pidfd_open()  system  call is the preferred way of obtaining a PID
121       file descriptor for an already existing process.  The alternative is to
122       obtain  a file descriptor by opening a /proc/[pid] directory.  However,
123       the latter technique is possible only  if  the  proc(5)  filesystem  is
124       mounted;  furthermore,  the file descriptor obtained in this way is not
125       pollable and can't be waited on with waitid(2).
126

EXAMPLES

128       The program below opens a PID file descriptor for the process whose PID
129       is  specified  as  its  command-line argument.  It then uses poll(2) to
130       monitor the file descriptor  for  process  exit,  as  indicated  by  an
131       EPOLLIN event.
132
133   Program source
134
135       #define _GNU_SOURCE
136       #include <sys/types.h>
137       #include <sys/syscall.h>
138       #include <unistd.h>
139       #include <poll.h>
140       #include <stdlib.h>
141       #include <stdio.h>
142
143       #ifndef __NR_pidfd_open
144       #define __NR_pidfd_open 434   /* System call # on most architectures */
145       #endif
146
147       static int
148       pidfd_open(pid_t pid, unsigned int flags)
149       {
150           return syscall(__NR_pidfd_open, pid, flags);
151       }
152
153       int
154       main(int argc, char *argv[])
155       {
156           struct pollfd pollfd;
157           int pidfd, ready;
158
159           if (argc != 2) {
160               fprintf(stderr, "Usage: %s <pid>\n", argv[0]);
161               exit(EXIT_SUCCESS);
162           }
163
164           pidfd = pidfd_open(atoi(argv[1]), 0);
165           if (pidfd == -1) {
166               perror("pidfd_open");
167               exit(EXIT_FAILURE);
168           }
169
170           pollfd.fd = pidfd;
171           pollfd.events = POLLIN;
172
173           ready = poll(&pollfd, 1, -1);
174           if (ready == -1) {
175               perror("poll");
176               exit(EXIT_FAILURE);
177           }
178
179           printf("Events (%#x): POLLIN is %sset\n", pollfd.revents,
180                   (pollfd.revents & POLLIN) ? "" : "not ");
181
182           close(pidfd);
183           exit(EXIT_SUCCESS);
184       }
185

COLOPHON

191       This page is part of release 5.13 of the Linux  man-pages  project.   A
192       description  of  the project, information about reporting bugs, and the
193       latest    version    of    this    page,    can     be     found     at
194       https://www.kernel.org/doc/man-pages/.
195
196
197
198Linux                             2021-08-27                     PIDFD_OPEN(2)