1 .\" Copyright (c) 2019 by Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .TH PIDFD_OPEN 2 2021-08-27 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
7 pidfd_open \- obtain a file descriptor that refers to a process
10 .RI ( libc ", " \-lc )
13 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
14 .B #include <unistd.h>
16 .BI "int syscall(SYS_pidfd_open, pid_t " pid ", unsigned int " flags );
20 glibc provides no wrapper for
22 necessitating the use of
27 system call creates a file descriptor that refers to
28 the process whose PID is specified in
30 The file descriptor is returned as the function result;
31 the close-on-exec flag is set on the file descriptor.
35 argument either has the value 0, or contains the following flag:
37 .BR PIDFD_NONBLOCK " (since Linux 5.10)"
38 .\" commit 4da9af0014b51c8b015ed8c622440ef28912efe6
39 Return a nonblocking file descriptor.
40 If the process referred to by the file descriptor has not yet terminated,
41 then an attempt to wait on the file descriptor using
43 will immediately return the error
49 returns a file descriptor (a nonnegative integer).
50 On error, \-1 is returned and
52 is set to indicate the error.
64 The per-process limit on the number of open file descriptors has been reached
65 (see the description of
71 The system-wide limit on the total number of open files has been reached.
74 The anonymous inode filesystem is not available in this kernel.
77 Insufficient kernel memory was available.
80 The process specified by
85 first appeared in Linux 5.3.
90 The following code sequence can be used to obtain a file descriptor
97 if (pid > 0) { /* If parent */
98 pidfd = pidfd_open(pid, 0);
104 Even if the child has already terminated by the time of the
106 call, its PID will not have been recycled and the returned
107 file descriptor will refer to the resulting zombie process.
108 Note, however, that this is guaranteed only if the following
109 conditions hold true:
113 has not been explicitly set to
120 flag was not specified while establishing a handler for
122 or while setting the disposition of that signal to
128 the zombie process was not reaped elsewhere in the program
129 (e.g., either by an asynchronously executed signal handler or by
131 or similar in another thread).
133 If any of these conditions does not hold,
134 then the child process (along with a PID file descriptor that refers to it)
135 should instead be created using
141 .SS Use cases for PID file descriptors
142 A PID file descriptor returned by
148 flag) can be used for the following purposes:
151 .BR pidfd_send_signal (2)
152 system call can be used to send a signal to the process referred to by
153 a PID file descriptor.
155 A PID file descriptor can be monitored using
160 When the process that it refers to terminates,
161 these interfaces indicate the file descriptor as readable.
162 Note, however, that in the current implementation,
163 nothing can be read from the file descriptor
165 on the file descriptor fails with the error
168 If the PID file descriptor refers to a child of the calling process,
169 then it can be waited on using
174 system call can be used to obtain a duplicate of a file descriptor
175 of another process referred to by a PID file descriptor.
177 A PID file descriptor can be used as the argument of
179 in order to move into one or more of the same namespaces as the process
180 referred to by the file descriptor.
182 A PID file descriptor can be used as the argument of
183 .BR process_madvise (2)
184 in order to provide advice on the memory usage patterns of the process
185 referred to by the file descriptor.
189 system call is the preferred way of obtaining a PID file descriptor
190 for an already existing process.
191 The alternative is to obtain a file descriptor by opening a
194 However, the latter technique is possible only if the
196 filesystem is mounted;
197 furthermore, the file descriptor obtained in this way is
199 pollable and can't be waited on with
202 The program below opens a PID file descriptor for the
203 process whose PID is specified as its command-line argument.
206 to monitor the file descriptor for process exit, as indicated by an
212 .\" SRC BEGIN (pidfd_open.c)
218 #include <sys/syscall.h>
222 pidfd_open(pid_t pid, unsigned int flags)
224 return syscall(SYS_pidfd_open, pid, flags);
228 main(int argc, char *argv[])
230 struct pollfd pollfd;
234 fprintf(stderr, "Usage: %s <pid>\en", argv[0]);
238 pidfd = pidfd_open(atoi(argv[1]), 0);
240 perror("pidfd_open");
245 pollfd.events = POLLIN;
247 ready = poll(&pollfd, 1, \-1);
253 printf("Events (%#x): POLLIN is %sset\en", pollfd.revents,
254 (pollfd.revents & POLLIN) ? "" : "not ");
265 .BR pidfd_send_signal (2),
267 .BR process_madvise (2),