From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Mon, 10 Sep 2018 09:26:34 +0000 (+0200)
Subject: clone.2: Clarify the discussion of threads and signals
X-Git-Tag: man-pages-5.00~388
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=f957eebd2d9320564e9fcd13037f3e96fd5d4d34;p=thirdparty%2Fman-pages.git

clone.2: Clarify the discussion of threads and signals

And explicitly introduce the terms "process-directed" and
"thread-directed" signals.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---

diff --git a/man2/clone.2 b/man2/clone.2
index e4fa3a911b..c7874fa59c 100644
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -722,28 +722,40 @@ also requires
 .BR CLONE_VM
 to be included).
 .IP
-Signals may be sent to a thread group as a whole (i.e., a TGID) using
-.BR kill (2),
-or to a specific thread (i.e., TID) using
-.BR tgkill (2).
-.IP
 Signal dispositions and actions are process-wide:
 if an unhandled signal is delivered to a thread, then
 it will affect (terminate, stop, continue, be ignored in)
 all members of the thread group.
 .IP
 Each thread has its own signal mask, as set by
-.BR sigprocmask (2),
-but signals can be pending either: for the whole process
-(i.e., deliverable to any member of the thread group),
-when sent with
-.BR kill (2);
-or for an individual thread, when sent with
-.BR tgkill (2).
+.BR sigprocmask (2).
+.IP
+A signal may be process-directed or thread-directed.
+A process-directed signal is targeted at a thread group (i.e., a TGID),
+and is delivered to an arbitrarily selected thread from among those
+that are not blocking the signal.
+A signal may be process directed because it is was generated by the kernel
+for reasons other than a hardware exception, or because it was sent using
+.BR kill (2)
+or
+.BR sigqueue (3).
+A thread-directed signal is targeted at (i.e., delivered to)
+a specific thread.
+A signal may be thread directed because it was sent using
+.BR tgkill (2)
+or
+.BR pthread_sigqueue (3),
+or because the thread executed a machine language instruction that triggered
+a hardware exception
+(e.g., invalid memory access triggering
+.BR SIGSEGV
+or a floating-point exception triggering
+.BR SIGFPE ).
+.IP
 A call to
 .BR sigpending (2)
-returns a signal set that is the union of the signals pending for the
-whole process and the signals that are pending for the calling thread.
+returns a signal set that is the union of the pending process-directed
+signals and the signals that are pending for the calling thread.
 .IP
 If a process-directed signal is delivered to a thread group,
 and the thread group has installed a handler for the signal, then