[PATCH 2/3] pidfd_open.2: add PIDFD_THREAD and poll nuances

[Kir Kolyshkin <kolyshkin@gmail.com>]

PIDFD_THREAD flag for pidfd_open(2) was added in Linux 6.9 (see [1]).
The nuances of using poll/epoll/select with a pidfd referring to a
process vs a thread are described in the merge commit [2].

[1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=64bef697d33b
[2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=b5683a37c881

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 man/man2/pidfd_open.2 | 36 ++++++++++++++++++++++++++++++------
 1 file changed, 30 insertions(+), 6 deletions(-)

diff --git a/man/man2/pidfd_open.2 b/man/man2/pidfd_open.2
index c027afe67..c0c0809f4 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 @@ .SH DESCRIPTION
 The
 .BR pidfd_open ()
 system call creates a file descriptor that refers to
-the process whose PID is specified in
+the task whose PID is specified in
 .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 v6.9)"
+.\" commit 64bef697d33b75fc06c5789b3f8108680271529f
+Create a pidfd 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.
+.P
 .SH RETURN VALUE
 On success,
 .BR pidfd_open ()
@@ -155,13 +163,29 @@ .SS Use cases for PID file descriptors
 .BR select (2),
 and
 .BR epoll (7).
-When the process that it refers to terminates,
-these interfaces indicate the file descriptor as readable.
+These interfaces indicate the PID file descriptor as readable
+when the task has exited.
 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 ).
+.IP
+The behavior depends on whether the file descriptor refers
+to a process (thread-group leader) or a thread (see
+.B PIDFD_THREAD
+above):
+.RS
+.IP \[bu] 3
+For a thread-group leader, the polling task is woken if the
+thread-group is empty. In other words, if the thread-group
+leader task exits when there are still threads alive in its
+thread-group, the polling task will not be woken when the
+thread-group leader exits, but rather when the last thread in the
+thread-group exits.
+.IP \[bu]
+For a thread, the polling task is woken if the thread exits.
+.RE
 .IP \[bu]
 If the PID file descriptor refers to a child of the calling process,
 then it can be waited on using
-- 
2.45.2