diff options
| author | Kir Kolyshkin <kolyshkin@gmail.com> | 2025-10-13 12:10:48 -0700 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2025-10-29 12:17:47 +0100 |
| commit | 2650af2a073cc68daef344d08d4da6d59224dd7c (patch) | |
| tree | 415ba2dca78704dee720540e1633c911a266c7f5 | |
| parent | ec1e7fdf368ea0ef21fb3f576d28fbebc6eb26aa (diff) | |
| download | man-pages-2650af2a073cc68daef344d08d4da6d59224dd7c.tar.gz | |
man/man2/pidfd_open.2: Document PIDFD_THREAD
PIDFD_THREAD flag for pidfd_open(2) was added in Linux 6.9 (see [1]).
Add a TODO to describe the nuances of using poll/epoll/select
with a pidfd referring to a process vs a thread.
[1]: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=64bef697d33b>
Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
Message-ID: <20251013191049.193375-2-kolyshkin@gmail.com>
Cc: Christian Brauner <brauner@kernel.org>
Cc: Oleg Nesterov <oleg@redhat.com>
[alx: ffix]
Signed-off-by: Alejandro Colomar <alx@kernel.org>
| -rw-r--r-- | man/man2/pidfd_open.2 | 42 |
1 files changed, 36 insertions, 6 deletions
diff --git a/man/man2/pidfd_open.2 b/man/man2/pidfd_open.2 index 3c7c568c2a..04077d5598 100644 --- a/man/man2/pidfd_open.2 +++ b/man/man2/pidfd_open.2 @@ -4,7 +4,7 @@ .\" .TH pidfd_open 2 (date) "Linux man-pages (unreleased)" .SH NAME -pidfd_open \- obtain a file descriptor that refers to a process +pidfd_open \- obtain a file descriptor that refers to a task .SH LIBRARY Standard C library .RI ( libc ,\~ \-lc ) @@ -25,24 +25,32 @@ necessitating the use of The .BR pidfd_open () system call creates a file descriptor that refers to -the process whose PID is specified in +the task referenced by .IR pid . The file descriptor is returned as the function result; the close-on-exec flag is set on the file descriptor. .P The .I flags -argument either has the value 0, or contains the following flag: +argument either has the value 0, or contains the following flags: .TP .BR PIDFD_NONBLOCK " (since Linux 5.10)" .\" commit 4da9af0014b51c8b015ed8c622440ef28912efe6 Return a nonblocking file descriptor. -If the process referred to by the file descriptor has not yet terminated, +If the task referred to by the file descriptor has not yet terminated, then an attempt to wait on the file descriptor using .BR waitid (2) will immediately return the error .B EAGAIN rather than blocking. +.TP +.BR PIDFD_THREAD " (since Linux 6.9)" +.\" commit 64bef697d33b75fc06c5789b3f8108680271529f +Create a file descriptor that refers to a specific thread, +rather than a process (thread-group leader). +If this flag is not set, +.I pid +must refer to a process. .SH RETURN VALUE On success, .BR pidfd_open () @@ -155,13 +163,35 @@ A PID file descriptor can be monitored using .BR select (2), and .BR epoll (7). -When the process that it refers to terminates, -these interfaces indicate the file descriptor as readable. +.IP +When the task that it refers to terminates and becomes a zombie, +these interfaces indicate the file descriptor as readable +.RB ( EPOLLIN ). +When the task is reaped, these interfaces produce a hangup event +.\" commit 43f0df54c96f +.RB ( EPOLLHUP ). +.IP Note, however, that in the current implementation, nothing can be read from the file descriptor .RB ( read (2) on the file descriptor fails with the error .BR EINVAL ). +The polling behavior depends on whether +.B PIDFD_THREAD +flag was used when obtaining the file descriptor: +.RS +.IP \[bu] 3 +With +.BR PIDFD_THREAD , +the file descriptor becomes readable +when the task exits and becomes a zombie, +even if the thread-group is not empty. +.IP \[bu] +Without +.BR PIDFD_THREAD , +the file descriptor becomes readable +only when the last thread in the thread group exits. +.RE .IP \[bu] If the PID file descriptor refers to a child of the calling process, then it can be waited on using |