Split sigpending(), sigprocmask(), and sigsuspend() out

into separate new pages.

Other minor changes

NOTES: described SA_NODER / sa_mask bug which was present in
                all kernels up to and including 2.6.13.
See http://marc.theaimsgroup.com/?l=linux-kernel&m=112360948603171&w=2
and http://marc.theaimsgroup.com/?l=linux-kernel&m=112362164911432&w=2
List:       linux-kernel
Subject:    Signal handling possibly wrong
From:       Bodo Stroesser
Date:       2005-08-09 17:44:06

1 files changed, 42 insertions, 84 deletions

diff --git a/man2/sigaction.2 b/man2/sigaction.2
index 63b775d6..3de0ad1b 100644
--- a/man2/sigaction.2
+++ b/man2/sigaction.2
@@ -1,5 +1,6 @@
 '\" t
 .\" Copyright (c) 1994,1995 Mike Battersby <mib@deakin.edu.au>
+.\"           and 2004, 2005 Michael Kerrisk <mtk-manpages@gmx.net>
 .\" based on work by faith@cs.unc.edu
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
@@ -36,23 +37,17 @@
 .\"	Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags.
 .\"	Formatting fixes
 .\" 2004-12-09, mtk, added SI_TKILL + other minor changes
+.\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend()
+.\"	out of this page into separate pages.
 .\"
-.TH SIGACTION 2 2004-11-11 "Linux 2.6.9" "Linux Programmer's Manual"
+.TH SIGACTION 2 2005-09-15 "Linux 2.6.14" "Linux Programmer's Manual"
 .SH NAME
-sigaction, sigprocmask, sigpending, sigsuspend \-
-POSIX signal handling API
+sigaction \- examine and change a signal action
 .SH SYNOPSIS
 .B #include <signal.h>
-.sp 2
+.sp 
 .BI "int sigaction(int " signum ", const struct sigaction *" act ,
 .BI "struct sigaction *" oldact );
-.sp
-.BI "int sigprocmask(int " how ", const sigset_t *" set ,
-.BI "sigset_t *" oldset );
-.sp
-.BI "int sigpending(sigset_t *" set );
-.sp
-.BI "int sigsuspend(const sigset_t *" mask );
 .SH DESCRIPTION
 The
 .BR sigaction ()
@@ -114,8 +109,15 @@ for the default action,
 to ignore this signal, or a pointer to a signal handling function.
 This function receives the signal number as its only argument.
 .PP
+If
+.B SA_SIGINFO
+is specified in
+.IR sa_flags , 
+then
 .I sa_sigaction
-also specifies the action to be associated with
+(instead of
+.IR sa_handler )
+specifies the signal-handling function for
 .IR signum .
 This function receives the signal number as its first argument, a
 pointer to a
@@ -355,80 +357,21 @@ POLL_PRI:high priority input available
 POLL_HUP:device disconnected
 .TE
 
-.PP
-The
-.BR sigprocmask ()
-call is used to change the list of currently blocked signals. The 
-behaviour of the call is dependent on the value of
-.IR how ,
-as follows.
-.RS
-.TP
-.B SIG_BLOCK
-The set of blocked signals is the union of the current set and the
-.I set
-argument.
-.TP
-.B SIG_UNBLOCK
-The signals in
-.I set
-are removed from the current set of blocked signals.  It is legal to
-attempt to unblock a signal which is not blocked.
-.TP
-.B SIG_SETMASK
-The set of blocked signals is set to the argument
-.IR set .
-.RE
-.PP
-If
-.I oldset
-is non\-null, the previous value of the signal mask is stored in
-.IR oldset .
-.PP
-The
-.BR sigpending ()
-call allows the examination of pending signals (ones which have been
-raised while blocked).  The signal mask of pending signals is stored
-in
-.IR set .
-.PP
-The
-.BR sigsuspend ()
-call temporarily replaces the signal mask for the process with that
-given by 
-.I mask
-and then suspends the process until a signal is received.
-
 .SH "RETURN VALUE"
-.BR sigaction (),
-.BR sigprocmask (),
-and
-.BR sigpending ()
-return 0 on success and \-1 on error.
-.BR sigsuspend ()
-always returns \-1, normally with the error
-.BR EINTR .
-
+.BR sigaction ()
+returns 0 on success and \-1 on error.
 .SH ERRORS
 .TP
 .B EFAULT
-.IR act ", " oldact ", " set ", " oldset
-or 
-.I mask
-point to memory which is not a valid part of the process address space.
-.TP
-.B EINTR
-System call was interrupted.
+.IR act " or " oldact
+points to memory which is not a valid part of the process address space.
 .TP
 .B EINVAL
 An invalid signal was specified.  This will also be generated if an attempt
 is made to change the action for
 .BR SIGKILL " or " SIGSTOP ", "
-which cannot be caught.
+which cannot be caught or ignored.
 .SH NOTES
-It is not possible to block 
-.BR SIGKILL " or " SIGSTOP
-with the sigprocmask call.  Attempts to do so will be silently ignored.
 .PP
 According to POSIX, the behaviour of a process is undefined after it
 ignores a
@@ -493,24 +436,37 @@ allowed the receipt of any signal, not just the one we are installing
 (effectively overriding any
 .I sa_mask
 settings).
-.PP
-.\" FIXME What "library" is being referred to in the following sentence?
-The
-.BR SA_RESETHAND " and " SA_NODEFER
-names for SVr4 compatibility are present only in library versions 3.0.9
-and greater.
+.\".PP
+.\"The
+.\".BR SA_RESETHAND " and " SA_NODEFER
+.\"names for SVr4 compatibility are present only in library versions 3.0.9
+.\"and greater.
 .PP
 .BR sigaction ()
 can be called with a null second argument to query the current signal
 handler. It can also be used to check whether a given signal is valid for
 the current machine by calling it with null second and third arguments.
 .PP
+It is not possible to block 
+.BR SIGKILL " or " SIGSTOP
+(by specifying them in
+.IR sa_mask ).
+Attempts to do so are silently ignored.
+.PP
 See
 .BR sigsetops (3)
 for details on manipulating signal sets.
+.SH BUGS
+In kernels up to and including 2.6.13, specifying
+.B SA_NODEFER
+in
+.I sa_flags
+preventing not only the delivered signal from being masked during 
+execution of the handler, but also the signals specified in
+.IR sa_mask .
+This bug is was fixed in kernel 2.6.14.
 .SH "CONFORMING TO"
 POSIX, SVr4.  SVr4 does not document the EINTR condition.
-
 .SH UNDOCUMENTED
 Before the introduction of
 .B SA_SIGINFO
@@ -521,14 +477,16 @@ with second argument of type
 .IR "struct sigcontext".
 See the relevant kernel sources for details.
 This use is obsolete now.
-
 .SH "SEE ALSO"
 .BR kill (1),
 .BR kill (2),
 .BR pause (2),
 .BR sigaltstack (2),
 .BR signal (2),
+.BR sigpending (2),
+.BR sigprocmask (2),
 .BR sigqueue (2),
+.BR sigsuspend (2),
 .BR sigvec (2),
 .BR wait (2),
 .BR killpg (3),