On Wed, Oct 15, 2025 at 2:16 PM Alejandro Colomar [off-list ref] wrote:

Hi Kir,

On Mon, Oct 13, 2025 at 12:10:48PM -0700, Kir Kolyshkin wrote:

quoted

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

As far as I can see, the only change in v3 compared to v2 is that the
commit message is smaller now.  Is that correct?

Not quite; I have answered to your earlier concern, let me quote it here:

quoted

 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

Should this say TID (thread ID)?  Or is it correct as PID?  I don't know
which is appropriate here.

So I removed the PID and TID usage:

quoted

-the process whose PID is specified in
+the task referenced by

In my opinion, as the function is named pidfd_open, it's hard to remove
the term PID entirely, but in some cases we can rephrase the text to
not use it. This is what v3 does.

I'm not entirely against using the term TID, but here it may result in
even more confusion.

Have a lovely night!
Alex

quoted

 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

--
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).