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

[Kir Kolyshkin <kolyshkin@gmail.com>]

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 c7aecbf96..11d81dbe2 100644
--- a/man/man2/pidfd_send_signal.2
+++ b/man/man2/pidfd_send_signal.2
@@ -77,8 +77,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 v6.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 v6.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 v6.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 ()
@@ -102,7 +149,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.45.2