| 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) |