[PATCH v2 0/3] man2: document Linux v6.9 pidfd-related changes

[PATCH v2 0/3] man2: document Linux v6.9 pidfd-related changes

[Kir Kolyshkin]

Linux 6.9 added support for PID file descriptors related to threads
(rather than processes). This adds the appropriate bits and pieces,
mostly taken from the https://github.com/brauner/man-pages-md project,
but also from the kernel commit messages.

For v1 of this patchset, see https://lore.kernel.org/linux-man/20240709021335.158849-1-kolyshkin@gmail.com/

[v2: added EPOLLHUP to pidfd_open.2, addressed Oleg's comments on v1]

Kir Kolyshkin (3):
  clone.2: document CLONE_PIDFD | CLONE_THREAD
  pidfd_open.2: add PIDFD_THREAD and poll nuances
  pidfd_send_signal.2: describe flags

 man/man2/clone.2             | 22 +++++++--------
 man/man2/pidfd_open.2        | 35 ++++++++++++++++++++----
 man/man2/pidfd_send_signal.2 | 53 ++++++++++++++++++++++++++++++++++--
 3 files changed, 89 insertions(+), 21 deletions(-)

-- 
2.51.0

[PATCH 1/3] clone.2: document CLONE_PIDFD | CLONE_THREAD

[Kir Kolyshkin]

Available since Linux 6.9 [1]. Documented in [2] (added by [3]).

[1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=83b290c9e3b5d95891f
[2]: https://github.com/brauner/man-pages-md/blob/main/clone.md
[3]: https://github.com/brauner/man-pages-md/pull/4

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 man/man2/clone.2 | 22 ++++++++++------------
 1 file changed, 10 insertions(+), 12 deletions(-)

diff --git a/man/man2/clone.2 b/man/man2/clone.2
index 68f86a934..edccde742 100644
--- a/man/man2/clone.2
+++ b/man/man2/clone.2
@@ -864,10 +864,16 @@ .SS The flags mask
 .BR clone ().
 .RE
 .IP
-It is currently not possible to use this flag together with
-.B CLONE_THREAD.
-This means that the process identified by the PID file descriptor
-will always be a thread group leader.
+If
+.B CLONE_PIDFD
+is specified together with
+.BR CLONE_THREAD ,
+the obtained PID file descriptor refers to a specific thread,
+as opposed to a thread-group leader if
+.B CLONE_THREAD
+is not specified.
+This feature is available since Linux 6.9.
+.\" commit 83b290c9e3b5d95891f43a4aeadf6071cbff25d3
 .IP
 If the obsolete
 .B CLONE_DETACHED
@@ -1386,14 +1392,6 @@ .SH ERRORS
 .I flags
 mask.
 .TP
-.B EINVAL
-.B CLONE_PIDFD
-was specified together with
-.B CLONE_THREAD
-in the
-.I flags
-mask.
-.TP
 .BR "EINVAL " "("  clone "() only)"
 .B CLONE_PIDFD
 was specified together with
-- 
2.51.0

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

[Kir Kolyshkin]

PIDFD_THREAD flag for pidfd_open(2) was added in Linux 6.9 (see [1]).
EPOLLHUP was added in Linux 6.9 (see [2]).

This adds description of both, mostly taken from kernel commit
messages and previous discussions in linux-man (see [3]).

[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=43f0df54c96f
[3]: https://lore.kernel.org/linux-man/20240709021335.158849-3-kolyshkin@gmail.com/

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..e8b61ec3e 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 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

[PATCH 3/3] pidfd_send_signal.2: describe flags

[Kir Kolyshkin]

Those flags were added in Linux 6.9 (see [1]), and are documented in
[2].

The text added is a modified version of [3], removing some repetition
and adapting from markdown to mandoc.

[1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=e1fb1dc08e73
[2]: https://github.com/brauner/man-pages-md/blob/main/pidfd_send_signal.md
[3]: https://github.com/brauner/man-pages-md/pull/2

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
---
 man/man2/pidfd_send_signal.2 | 53 ++++++++++++++++++++++++++++++++++--
 1 file changed, 50 insertions(+), 3 deletions(-)

diff --git a/man/man2/pidfd_send_signal.2 b/man/man2/pidfd_send_signal.2
index c4a9ce40e..70eaaa34f 100644
--- a/man/man2/pidfd_send_signal.2
+++ b/man/man2/pidfd_send_signal.2
@@ -78,8 +78,55 @@ .SH DESCRIPTION
 .P
 The
 .I flags
-argument is reserved for future use;
-currently, this argument must be specified as 0.
+argument allows to modify the scope of the signal. By
+default, the scope of the signal will be inferred from the
+. I pidfd
+argument. For example, if
+.I pidfd
+refers to a specific thread, i.e., the
+.I pidfd
+was created through
+.BR pidfd_open (2)
+passing the
+.B PIDFD_THREAD
+flag
+or through
+.BR clone3 (2)
+using the
+.B CLONE_PIDFD
+flag together with the
+.B CLONE_THREAD
+flag, then passing
+.I pidfd to
+.BR pidfd_send_signal (2)
+and leaving the
+.I flags argument as
+.B 0
+will cause the signal to be sent to the specific thread referenced by the
+.I pidfd.
+.TP
+.BR PIDFD_SIGNAL_THREAD " (since Linux 6.9)"
+.\" commit e1fb1dc08e73466830612bcf2f9f72180965c9ba
+Ensure that the signal is sent to the specific thread referenced by
+.I pidfd.
+.TP
+.BR PIDFD_SIGNAL_THREAD_GROUP " (since Linux 6.9)"
+.\" commit e1fb1dc08e73466830612bcf2f9f72180965c9ba
+If
+.I pidfd
+refers to a thread-group leader, ensure that the signal is
+sent to the thread-group, even if
+.I pidfd
+was created to refer to a specific thread.
+.TP
+.BR PIDFD_SIGNAL_PROCESS_GROUP " (since Linux 6.9)"
+.\" commit e1fb1dc08e73466830612bcf2f9f72180965c9ba
+If
+.I pidfd
+refers to a process-group leader, ensure that the signal is
+sent to the process-group, even if
+.I pidfd
+was created to refer to a specific thread or to a thread-group leader.
 .SH RETURN VALUE
 On success,
 .BR pidfd_send_signal ()
@@ -103,7 +150,7 @@ .SH ERRORS
 .TP
 .B EINVAL
 .I flags
-is not 0.
+is not valid.
 .TP
 .B EPERM
 The calling process does not have permission to send the signal
-- 
2.51.0

Re: [PATCH 1/3] clone.2: document CLONE_PIDFD | CLONE_THREAD

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2059 bytes --]

Hi Kir,

On Tue, Oct 07, 2025 at 07:00:28PM -0700, Kir Kolyshkin wrote:
> Available since Linux 6.9 [1]. Documented in [2] (added by [3]).
> 
> [1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=83b290c9e3b5d95891f
> [2]: https://github.com/brauner/man-pages-md/blob/main/clone.md
> [3]: https://github.com/brauner/man-pages-md/pull/4
> 
> Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>

Thanks!  I've applied the patch.  However, I've amended it to keep the
ERRORS entry, and noted that it can only happen before Linux 6.9.
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=ac6f5c32b3fae7549c5a42d96a3273adc24e5023>
(Use port 80.)


Have a lovely night!
Alex

> ---
>  man/man2/clone.2 | 22 ++++++++++------------
>  1 file changed, 10 insertions(+), 12 deletions(-)
> 
> diff --git a/man/man2/clone.2 b/man/man2/clone.2
> index 68f86a934..edccde742 100644
> --- a/man/man2/clone.2
> +++ b/man/man2/clone.2
> @@ -864,10 +864,16 @@ .SS The flags mask
>  .BR clone ().
>  .RE
>  .IP
> -It is currently not possible to use this flag together with
> -.B CLONE_THREAD.
> -This means that the process identified by the PID file descriptor
> -will always be a thread group leader.
> +If
> +.B CLONE_PIDFD
> +is specified together with
> +.BR CLONE_THREAD ,
> +the obtained PID file descriptor refers to a specific thread,
> +as opposed to a thread-group leader if
> +.B CLONE_THREAD
> +is not specified.
> +This feature is available since Linux 6.9.
> +.\" commit 83b290c9e3b5d95891f43a4aeadf6071cbff25d3
>  .IP
>  If the obsolete
>  .B CLONE_DETACHED
> @@ -1386,14 +1392,6 @@ .SH ERRORS
>  .I flags
>  mask.
>  .TP
> -.B EINVAL
> -.B CLONE_PIDFD
> -was specified together with
> -.B CLONE_THREAD
> -in the
> -.I flags
> -mask.
> -.TP
>  .BR "EINVAL " "("  clone "() only)"
>  .B CLONE_PIDFD
>  was specified together with
> -- 
> 2.51.0
> 

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 2/3] pidfd_open.2: add PIDFD_THREAD

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4065 bytes --]

Hi Kir,

On Tue, Oct 07, 2025 at 07:00:29PM -0700, Kir Kolyshkin wrote:
> PIDFD_THREAD flag for pidfd_open(2) was added in Linux 6.9 (see [1]).
> EPOLLHUP was added in Linux 6.9 (see [2]).
> 
> This adds description of both, mostly taken from kernel commit
> messages and previous discussions in linux-man (see [3]).
> 
> [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=43f0df54c96f
> [3]: https://lore.kernel.org/linux-man/20240709021335.158849-3-kolyshkin@gmail.com/
> 
> 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..e8b61ec3e 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

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


Have a lovely night!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Kir Kolyshkin]

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

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3826 bytes --]

Hi Kir,

On Mon, Oct 13, 2025 at 12:10:48PM -0700, Kir Kolyshkin wrote:
> 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>
> ---

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?


Have a lovely night!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Kirill Kolyshkin]

On Wed, Oct 15, 2025 at 2:16 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Kir,
>
> On Mon, Oct 13, 2025 at 12:10:48PM -0700, Kir Kolyshkin wrote:
> > 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>
> > ---
>
> 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:

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

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

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 6865 bytes --]

Hi Kir,

On Wed, Oct 15, 2025 at 05:06:29PM -0700, Kirill Kolyshkin wrote:
> On Wed, Oct 15, 2025 at 2:16 PM Alejandro Colomar <alx@kernel.org> wrote:
> >
> > Hi Kir,
> >
> > On Mon, Oct 13, 2025 at 12:10:48PM -0700, Kir Kolyshkin wrote:
> > > 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>
> > > ---
> >
> > 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:
> 
> > >  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:
> 
> > > -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.

Ahh, thanks!  That makes sense.

I was eyeballing the two emails to find the differences, but I missed
that difference.  It's hard to do eyeball-diff.  :)

That's why I recommend contributors to use the --range-diff feature of
git-format-patch(1).  See the contributing guidelines about it (below).


Have a lovely day!
Alex

	$ cat CONTRIBUTING.d/patches/range-diff 
	Name
		patches/range-diff - instructions for producing a range-diff

	Description
		We recommend using git-format-patch(1) to prepare the patches.
		Please use --range-diff to document the differences between
		revisions of the patch set, even in the first revision.

		To prepare a git(1) branch to be sent as a patch set (v1):

			$ git format-patch -o ./patches master..HEAD \
				--range-diff=master -v1 \
				--cover-letter;

		The range diff will be included in the cover letter (or in a
		single patch, if there is only one):

			$ tail -n7 ./patches/v1-0000-cover-letter.patch;
			Range-diff against v0:
			-:  --------- > 1:  7ec952012 foo.3: tfix
			-:  --------- > 2:  d80376b08 bar.3: ffix
			-:  --------- > 3:  892a12470 foo.3: wfix
			--
			2.43.0

		To send a v2 after some feedback:

			$ git format-patch -o ./patches master..HEAD \
				--range-diff=old_master..old_HEAD -v2 \
				--cover-letter;

		The values for 'old_master' and 'old_HEAD' can be consulted in
		the previous cover letter.  In this example, it would be
		'--range-diff=7ec952012^..892a12470'.

	See also
		<https://inbox.sourceware.org/gcc/ZiV5unTogyI7rPJA@debian/>

> 
> > Have a lovely night!
> > Alex
> >
> > >  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/>).

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 5194 bytes --]

Hi Kir,

On Mon, Oct 13, 2025 at 12:10:48PM -0700, Kir Kolyshkin wrote:
> 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>

Thanks!  I've applied the patch.

For posterity, here's the range-diff comparing to v2:

	$ git range-diff old^..old HEAD^..HEAD 
	1:  efaf8c056 ! 1:  b0b6040f9 pidfd_open.2: add PIDFD_THREAD
	    @@ Commit message
		 pidfd_open.2: add PIDFD_THREAD
	     
		 PIDFD_THREAD flag for pidfd_open(2) was added in Linux 6.9 (see [1]).
	    -    EPOLLHUP was added in Linux 6.9 (see [2]).
	     
	    -    This adds description of both, mostly taken from kernel commit
	    -    messages and previous discussions in linux-man (see [3]).
	    +    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
	    -    [2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=43f0df54c96f
	    -    [3]: https://lore.kernel.org/linux-man/20240709021335.158849-3-kolyshkin@gmail.com/
	     
		 Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
	     
	      ## man/man2/pidfd_open.2 ##
	    @@ man/man2/pidfd_open.2: .SH DESCRIPTION
	      .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
	    ++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.

Have a lovely day!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 3/3] pidfd_send_signal.2: describe flags

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3002 bytes --]

Hi Kir,

On Tue, Oct 07, 2025 at 07:00:30PM -0700, Kir Kolyshkin wrote:
> Those flags were added in Linux 6.9 (see [1]), and are documented in
> [2].
> 
> The text added is a modified version of [3], removing some repetition
> and adapting from markdown to mandoc.
> 
> [1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=e1fb1dc08e73
> [2]: https://github.com/brauner/man-pages-md/blob/main/pidfd_send_signal.md
> [3]: https://github.com/brauner/man-pages-md/pull/2
> 
> Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>

Thanks!  I've applied the patch (amending some formatting issues).


Have a lovely day!
Alex

> ---
>  man/man2/pidfd_send_signal.2 | 53 ++++++++++++++++++++++++++++++++++--
>  1 file changed, 50 insertions(+), 3 deletions(-)
> 
> diff --git a/man/man2/pidfd_send_signal.2 b/man/man2/pidfd_send_signal.2
> index c4a9ce40e..70eaaa34f 100644
> --- a/man/man2/pidfd_send_signal.2
> +++ b/man/man2/pidfd_send_signal.2
> @@ -78,8 +78,55 @@ .SH DESCRIPTION
>  .P
>  The
>  .I flags
> -argument is reserved for future use;
> -currently, this argument must be specified as 0.
> +argument allows to modify the scope of the signal. By
> +default, the scope of the signal will be inferred from the
> +. I pidfd
> +argument. For example, if
> +.I pidfd
> +refers to a specific thread, i.e., the
> +.I pidfd
> +was created through
> +.BR pidfd_open (2)
> +passing the
> +.B PIDFD_THREAD
> +flag
> +or through
> +.BR clone3 (2)
> +using the
> +.B CLONE_PIDFD
> +flag together with the
> +.B CLONE_THREAD
> +flag, then passing
> +.I pidfd to
> +.BR pidfd_send_signal (2)
> +and leaving the
> +.I flags argument as
> +.B 0
> +will cause the signal to be sent to the specific thread referenced by the
> +.I pidfd.
> +.TP
> +.BR PIDFD_SIGNAL_THREAD " (since Linux 6.9)"
> +.\" commit e1fb1dc08e73466830612bcf2f9f72180965c9ba
> +Ensure that the signal is sent to the specific thread referenced by
> +.I pidfd.
> +.TP
> +.BR PIDFD_SIGNAL_THREAD_GROUP " (since Linux 6.9)"
> +.\" commit e1fb1dc08e73466830612bcf2f9f72180965c9ba
> +If
> +.I pidfd
> +refers to a thread-group leader, ensure that the signal is
> +sent to the thread-group, even if
> +.I pidfd
> +was created to refer to a specific thread.
> +.TP
> +.BR PIDFD_SIGNAL_PROCESS_GROUP " (since Linux 6.9)"
> +.\" commit e1fb1dc08e73466830612bcf2f9f72180965c9ba
> +If
> +.I pidfd
> +refers to a process-group leader, ensure that the signal is
> +sent to the process-group, even if
> +.I pidfd
> +was created to refer to a specific thread or to a thread-group leader.
>  .SH RETURN VALUE
>  On success,
>  .BR pidfd_send_signal ()
> @@ -103,7 +150,7 @@ .SH ERRORS
>  .TP
>  .B EINVAL
>  .I flags
> -is not 0.
> +is not valid.
>  .TP
>  .B EPERM
>  The calling process does not have permission to send the signal
> -- 
> 2.51.0
> 
> 

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]