Debian Codegraph @

upstream/debian-unstable/man2/pidfd_open.2

raw
1 .\" Copyright 2019, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pidfd_open 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 pidfd_open \- obtain a file descriptor that refers to a task
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
15 .B #include <unistd.h>
16 .P
17 .BI "int syscall(SYS_pidfd_open, pid_t " pid ", unsigned int " flags );
18 .fi
19 .P
20 .IR Note :
21 glibc provides no wrapper for
22 .BR pidfd_open (),
23 necessitating the use of
24 .BR syscall (2).
25 .SH DESCRIPTION
26 The
27 .BR pidfd_open ()
28 system call creates a file descriptor that refers to
29 the task referenced by
30 .IR pid .
31 The file descriptor is returned as the function result;
32 the close-on-exec flag is set on the file descriptor.
33 .P
34 The
35 .I flags
36 argument either has the value 0, or contains the following flags:
37 .TP
38 .BR PIDFD_NONBLOCK " (since Linux 5.10)"
39 .\" commit 4da9af0014b51c8b015ed8c622440ef28912efe6
40 Return a nonblocking file descriptor.
41 If the task referred to by the file descriptor has not yet terminated,
42 then an attempt to wait on the file descriptor using
43 .BR waitid (2)
44 will immediately return the error
45 .B EAGAIN
46 rather than blocking.
47 .TP
48 .BR PIDFD_THREAD " (since Linux 6.9)"
49 .\" commit 64bef697d33b75fc06c5789b3f8108680271529f
50 Create a file descriptor that refers to a specific thread,
51 rather than a process (thread-group leader).
52 If this flag is not set,
53 .I pid
54 must refer to a process.
55 .SH RETURN VALUE
56 On success,
57 .BR pidfd_open ()
58 returns a file descriptor (a nonnegative integer).
59 On error, \-1 is returned and
60 .I errno
61 is set to indicate the error.
62 .SH ERRORS
63 .TP
64 .B EINVAL
65 .I flags
66 is not valid.
67 .TP
68 .B EINVAL
69 .I pid
70 is not valid.
71 .TP
72 .B EMFILE
73 The per-process limit on the number of open file descriptors has been reached
74 (see the description of
75 .B RLIMIT_NOFILE
76 in
77 .BR getrlimit (2)).
78 .TP
79 .B ENFILE
80 The system-wide limit on the total number of open files has been reached.
81 .TP
82 .B ENODEV
83 The anonymous inode filesystem is not available in this kernel.
84 .TP
85 .B ENOMEM
86 Insufficient kernel memory was available.
87 .TP
88 .B ESRCH
89 The process specified by
90 .I pid
91 does not exist.
92 .SH STANDARDS
93 Linux.
94 .SH HISTORY
95 Linux 5.3.
96 .SH NOTES
97 The following code sequence can be used to obtain a file descriptor
98 for the child of
99 .BR fork (2):
100 .P
101 .in +4n
102 .EX
103 pid = fork();
104 if (pid > 0) { /* If parent */
105 pidfd = pidfd_open(pid, 0);
106 ...
107 }
108 .EE
109 .in
110 .P
111 Even if the child has already terminated by the time of the
112 .BR pidfd_open ()
113 call, its PID will not have been recycled and the returned
114 file descriptor will refer to the resulting zombie process.
115 Note, however, that this is guaranteed only if the following
116 conditions hold true:
117 .IP \[bu] 3
118 the disposition of
119 .B SIGCHLD
120 has not been explicitly set to
121 .B SIG_IGN
122 (see
123 .BR sigaction (2));
124 .IP \[bu]
125 the
126 .B SA_NOCLDWAIT
127 flag was not specified while establishing a handler for
128 .B SIGCHLD
129 or while setting the disposition of that signal to
130 .B SIG_DFL
131 (see
132 .BR sigaction (2));
133 and
134 .IP \[bu]
135 the zombie process was not reaped elsewhere in the program
136 (e.g., either by an asynchronously executed signal handler or by
137 .BR wait (2)
138 or similar in another thread).
139 .P
140 If any of these conditions does not hold,
141 then the child process (along with a PID file descriptor that refers to it)
142 should instead be created using
143 .BR clone (2)
144 with the
145 .B CLONE_PIDFD
146 flag.
147 .\"
148 .SS Use cases for PID file descriptors
149 A PID file descriptor returned by
150 .BR pidfd_open ()
151 (or by
152 .BR clone (2)
153 with the
154 .B CLONE_PID
155 flag) can be used for the following purposes:
156 .IP \[bu] 3
157 The
158 .BR pidfd_send_signal (2)
159 system call can be used to send a signal to the process referred to by
160 a PID file descriptor.
161 .IP \[bu]
162 A PID file descriptor can be monitored using
163 .BR poll (2),
164 .BR select (2),
165 and
166 .BR epoll (7).
167 .IP
168 When the task that it refers to terminates and becomes a zombie,
169 these interfaces indicate the file descriptor as readable
170 .RB ( EPOLLIN ).
171 When the task is reaped, these interfaces produce a hangup event
172 .\" commit 43f0df54c96f
173 .RB ( EPOLLHUP ).
174 .IP
175 Note, however, that in the current implementation,
176 nothing can be read from the file descriptor
177 .RB ( read (2)
178 on the file descriptor fails with the error
179 .BR EINVAL ).
180 The polling behavior depends on whether
181 .B PIDFD_THREAD
182 flag was used when obtaining the file descriptor:
183 .RS
184 .IP \[bu] 3
185 With
186 .BR PIDFD_THREAD ,
187 the file descriptor becomes readable
188 when the task exits and becomes a zombie,
189 even if the thread-group is not empty.
190 .IP \[bu]
191 Without
192 .BR PIDFD_THREAD ,
193 the file descriptor becomes readable
194 only when the last thread in the thread group exits.
195 .RE
196 .IP \[bu]
197 If the PID file descriptor refers to a child of the calling process,
198 then it can be waited on using
199 .BR waitid (2).
200 .IP \[bu]
201 The
202 .BR pidfd_getfd (2)
203 system call can be used to obtain a duplicate of a file descriptor
204 of another process referred to by a PID file descriptor.
205 .IP \[bu]
206 A PID file descriptor can be used as the argument of
207 .BR setns (2)
208 in order to move into one or more of the same namespaces as the process
209 referred to by the file descriptor.
210 .IP \[bu]
211 A PID file descriptor can be used as the argument of
212 .BR process_madvise (2)
213 in order to provide advice on the memory usage patterns of the process
214 referred to by the file descriptor.
215 .P
216 The
217 .BR pidfd_open ()
218 system call is the preferred way of obtaining a PID file descriptor
219 for an already existing process.
220 The alternative is to obtain a file descriptor by opening a
221 .IR /proc/ pid
222 directory.
223 However, the latter technique is possible only if the
224 .BR proc (5)
225 filesystem is mounted;
226 furthermore, the file descriptor obtained in this way is
227 .I not
228 pollable and can't be waited on with
229 .BR waitid (2).
230 .SH EXAMPLES
231 The program below opens a PID file descriptor for the
232 process whose PID is specified as its command-line argument.
233 It then uses
234 .BR poll (2)
235 to monitor the file descriptor for process exit, as indicated by an
236 .B EPOLLIN
237 event.
238 .\"
239 .SS Program source
240 \&
241 .\" SRC BEGIN (pidfd_open.c)
242 .EX
243 #define _GNU_SOURCE
244 #include <poll.h>
245 #include <stdio.h>
246 #include <stdlib.h>
247 #include <sys/syscall.h>
248 #include <sys/types.h>
249 #include <unistd.h>
250 \&
251 static int
252 pidfd_open(pid_t pid, unsigned int flags)
253 {
254 return syscall(SYS_pidfd_open, pid, flags);
255 }
256 \&
257 int
258 main(int argc, char *argv[])
259 {
260 int pidfd, ready;
261 struct pollfd pollfd;
262 \&
263 if (argc != 2) {
264 fprintf(stderr, "Usage: %s <pid>\[rs]n", argv[0]);
265 exit(EXIT_SUCCESS);
266 }
267 \&
268 pidfd = pidfd_open(atoi(argv[1]), 0);
269 if (pidfd == \-1) {
270 perror("pidfd_open");
271 exit(EXIT_FAILURE);
272 }
273 \&
274 pollfd.fd = pidfd;
275 pollfd.events = POLLIN;
276 \&
277 ready = poll(&pollfd, 1, \-1);
278 if (ready == \-1) {
279 perror("poll");
280 exit(EXIT_FAILURE);
281 }
282 \&
283 printf("Events (%#x): POLLIN is %sset\[rs]n", pollfd.revents,
284 (pollfd.revents & POLLIN) ? "" : "not ");
285 \&
286 close(pidfd);
287 exit(EXIT_SUCCESS);
288 }
289 .EE
290 .\" SRC END
291 .SH SEE ALSO
292 .BR clone (2),
293 .BR kill (2),
294 .BR pidfd_getfd (2),
295 .BR pidfd_send_signal (2),
296 .BR poll (2),
297 .BR process_madvise (2),
298 .BR select (2),
299 .BR setns (2),
300 .BR waitid (2),
301 .BR epoll (7)