[PATCH v3 2/3] pidfd_open.2: add PIDFD_THREAD

[Kir Kolyshkin <kolyshkin@gmail.com>]

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>
---
 man/man2/pidfd_open.2 | 35 +++++++++++++++++++++++++++++------
 1 file changed, 29 insertions(+), 6 deletions(-)

diff --git a/man/man2/pidfd_open.2 b/man/man2/pidfd_open.2
index 3c7c568c2..60cac6fdd 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 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.
+.P
 .SH RETURN VALUE
 On success,
 .BR pidfd_open ()
@@ -155,13 +163,28 @@ .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.
+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 ).
 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 \fBPIDFD_THREAD\fR, the file descriptor becomes readable when the task
+exits and becomes a zombie, even if the thread-group is not empty.
+.IP \[bu] 3
+Without \fBPIDFD_THREAD\fR, 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
-- 
2.51.0