From 75b1cda430eedddf6559015ebdcc4bedd3a85c7c Mon Sep 17 00:00:00 2001 From: Jilles Tjoelker Date: Fri, 6 Sep 2013 09:08:40 +0000 Subject: [PATCH] Update some signal man pages for multithreading. --- lib/libc/sys/sigaction.2 | 52 +++++++++++++++++++++++++-------------- lib/libc/sys/sigpending.2 | 4 +-- lib/libc/sys/sigreturn.2 | 6 ++--- lib/libc/sys/sigwait.2 | 4 +-- 4 files changed, 41 insertions(+), 25 deletions(-) diff --git a/lib/libc/sys/sigaction.2 b/lib/libc/sys/sigaction.2 index d975ef931653..5c784f64475d 100644 --- a/lib/libc/sys/sigaction.2 +++ b/lib/libc/sys/sigaction.2 @@ -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 specify that a signal is to be 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 by the .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 committed are not restarted, 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 diff --git a/lib/libc/sys/sigpending.2 b/lib/libc/sys/sigpending.2 index 37f92d89d155..06ecc004501d 100644 --- a/lib/libc/sys/sigpending.2 +++ b/lib/libc/sys/sigpending.2 @@ -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 diff --git a/lib/libc/sys/sigreturn.2 b/lib/libc/sys/sigreturn.2 index 13d76f68d48b..1b76468a84ec 100644 --- a/lib/libc/sys/sigreturn.2 +++ b/lib/libc/sys/sigreturn.2 @@ -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 diff --git a/lib/libc/sys/sigwait.2 b/lib/libc/sys/sigwait.2 index 525bffb2689f..4da64a99dddd 100644 --- a/lib/libc/sys/sigwait.2 +++ b/lib/libc/sys/sigwait.2 @@ -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 signals has been generated. 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