Debian Codegraph @

upstream/debian-trixie/man2/pidfd_open.2

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