svn commit: r255296 - head/lib/libc/sys

Fri Sep 6 09:08:42 UTC 2013

Author: jilles
Date: Fri Sep  6 09:08:40 2013
New Revision: 255296
URL: http://svnweb.freebsd.org/changeset/base/255296

Log:
  Update some signal man pages for multithreading.

Modified:
  head/lib/libc/sys/sigaction.2
  head/lib/libc/sys/sigpending.2
  head/lib/libc/sys/sigreturn.2
  head/lib/libc/sys/sigwait.2

Modified: head/lib/libc/sys/sigaction.2
==============================================================================

--- head/lib/libc/sys/sigaction.2	Fri Sep  6 08:21:55 2013	(r255295)
+++ head/lib/libc/sys/sigaction.2	Fri Sep  6 09:08:40 2013	(r255296)
@@ -28,7 +28,7 @@
 .\"	From: @(#)sigaction.2	8.2 (Berkeley) 4/3/94
 .\" $FreeBSD$
 .\"
-.Dd June 8, 2013
+.Dd September 6, 2013
 .Dt SIGACTION 2
 .Os
 .Sh NAME
@@ -55,7 +55,7 @@ struct  sigaction {
 .Sh DESCRIPTION
 The system defines a set of signals that may be delivered to a process.
 Signal delivery resembles the occurrence of a hardware interrupt:
-the signal is normally blocked from further occurrence, the current process
+the signal is normally blocked from further occurrence, the current thread
 context is saved, and a new one is built.
 A process may specify a
 .Em handler
@@ -64,13 +64,14 @@ to which a signal is delivered, or speci
 A process may also specify that a default action is to be taken
 by the system when a signal occurs.
 A signal may also be
-.Em blocked ,
-in which case its delivery is postponed until it is
+.Em blocked
+for a thread,
+in which case it will not be delivered to that thread until it is
 .Em unblocked .
 The action to be taken on delivery is determined at the time
 of delivery.
 Normally, signal handlers execute on the current stack
-of the process.
+of the thread.
 This may be changed, on a per-handler basis,
 so that signals are taken on a special
 .Em "signal stack" .
@@ -82,20 +83,30 @@ but other signals may yet occur.
 A global
 .Em "signal mask"
 defines the set of signals currently blocked from delivery
-to a process.
-The signal mask for a process is initialized
+to a thread.
+The signal mask for a thread is initialized
 from that of its parent (normally empty).
 It may be changed with a
 .Xr sigprocmask 2
-call, or when a signal is delivered to the process.
+or
+.Xr pthread_sigmask 3
+call, or when a signal is delivered to the thread.
 .Pp
 When a signal
-condition arises for a process, the signal is added to a set of
-signals pending for the process.
-If the signal is not currently
+condition arises for a process or thread, the signal is added to a set of
+signals pending for the process or thread.
+Whether the signal is directed at the process in general or at a specific
+thread depends on how it is generated.
+For signals directed at a specific thread,
+if the signal is not currently
 .Em blocked
-by the process then it is delivered to the process.
-Signals may be delivered any time a process enters the operating system
+by the thread then it is delivered to the thread.
+For signals directed at the process,
+if the signal is not currently
+.Em blocked
+by all threads then it is delivered to one thread that does not have it blocked
+(the selection of which is unspecified).
+Signals may be delivered any time a thread enters the operating system
 (e.g., during a system call, page fault or trap, or clock interrupt).
 If multiple signals are ready to be delivered at the same time,
 any signals that could be caused by traps are delivered first.
@@ -106,17 +117,17 @@ The set of pending signals is returned b
 .Xr sigpending 2
 system call.
 When a caught signal
-is delivered, the current state of the process is saved,
+is delivered, the current state of the thread is saved,
 a new signal mask is calculated (as described below),
 and the signal handler is invoked.
 The call to the handler
 is arranged so that if the signal handling routine returns
-normally the process will resume execution in the context
+normally the thread will resume execution in the context
 from before the signal's delivery.
-If the process wishes to resume in a different context, then it
+If the thread wishes to resume in a different context, then it
 must arrange to restore the previous context itself.
 .Pp
-When a signal is delivered to a process a new signal mask is
+When a signal is delivered to a thread a new signal mask is
 installed for the duration of the process' signal handler
 (or until a
 .Xr sigprocmask 2
@@ -218,7 +229,7 @@ to
 If this bit is set, the system will deliver the signal to the process
 on a
 .Em "signal stack" ,
-specified with
+specified by each thread with
 .Xr sigaltstack 2 .
 .It Dv SA_NODEFER
 If this bit is set, further occurrences of the delivered signal are
@@ -272,6 +283,11 @@ However, calls that have already committ
 but instead return a partial success (for example, a short read count).
 .Pp
 After a
+.Xr pthread_create 3
+the signal mask is inherited by the new thread and
+the set of pending signals and the signal stack for the new thread are empty.
+.Pp
+After a
 .Xr fork 2
 or
 .Xr vfork 2

Modified: head/lib/libc/sys/sigpending.2
==============================================================================
--- head/lib/libc/sys/sigpending.2	Fri Sep  6 08:21:55 2013	(r255295)
+++ head/lib/libc/sys/sigpending.2	Fri Sep  6 09:08:40 2013	(r255296)
@@ -31,7 +31,7 @@
 .\"	@(#)sigpending.2	8.3 (Berkeley) 1/12/94
 .\" $FreeBSD$
 .\"
-.Dd January 12, 1994
+.Dd September 6, 2013
 .Dt SIGPENDING 2
 .Os
 .Sh NAME
@@ -47,7 +47,7 @@
 The
 .Fn sigpending
 system call returns a mask of the signals pending for delivery
-to the calling process in the location indicated by
+to the calling thread or the calling process in the location indicated by
 .Fa set .
 Signals may be pending because they are currently masked,
 or transiently before delivery (although the latter case is not

Modified: head/lib/libc/sys/sigreturn.2
==============================================================================
--- head/lib/libc/sys/sigreturn.2	Fri Sep  6 08:21:55 2013	(r255295)
+++ head/lib/libc/sys/sigreturn.2	Fri Sep  6 09:08:40 2013	(r255296)
@@ -28,7 +28,7 @@
 .\"     @(#)sigreturn.2	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd June 4, 1993
+.Dd September 6, 2013
 .Dt SIGRETURN 2
 .Os
 .Sh NAME
@@ -46,7 +46,7 @@ The
 system call
 allows users to atomically unmask, switch stacks,
 and return from a signal context.
-The processes signal mask and stack status are
+The thread's signal mask and stack status are
 restored from the context structure pointed to by
 .Fa scp .
 The system call does not return;
@@ -65,7 +65,7 @@ is set to indicate the error.
 The
 .Fn sigreturn
 system call
-will fail and the process context will remain unchanged
+will fail and the thread context will remain unchanged
 if one of the following occurs.
 .Bl -tag -width Er
 .It Bq Er EFAULT

Modified: head/lib/libc/sys/sigwait.2
==============================================================================
--- head/lib/libc/sys/sigwait.2	Fri Sep  6 08:21:55 2013	(r255295)
+++ head/lib/libc/sys/sigwait.2	Fri Sep  6 09:08:40 2013	(r255296)
@@ -27,7 +27,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd September 27, 2012
+.Dd September 6, 2013
 .Dt SIGWAIT 2
 .Os
 .Sh NAME
@@ -50,7 +50,7 @@ waits until one or more of the selected 
 Then
 .Fn sigwait
 atomically clears one of the selected signals from the set of pending signals
-for the process and sets the location pointed to by
+(for the process or for the current thread) and sets the location pointed to by
 .Fa sig
 to the signal number that was cleared.
 .Pp
