Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags; formatting fixes

man2/sigaction.2

@@ -32,10 +32,14 @@
 .\" Modified 2004-11-11 by Michael Kerrisk <mtk-manpages@gmx.net>
 .\"	Added mention of SIGCONT under SA_NOCLDSTOP
 .\"	Added SA_NOCLDWAIT
+.\" Modified 2004-11-17 by Michael Kerrisk <mtk-manpages@gmx.net>
+.\"	Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags.
+.\"	Formatting fixes
 .\"
 .TH SIGACTION 2 2004-11-11 "Linux 2.6.9" "Linux Programmer's Manual"
 .SH NAME
-sigaction, sigprocmask, sigpending, sigsuspend \- POSIX signal handling functions
+sigaction, sigprocmask, sigpending, sigsuspend \-
+POSIX signal handling API
 .SH SYNOPSIS
 .B #include <signal.h>
 .sp 2
@@ -50,7 +54,7 @@ sigaction, sigprocmask, sigpending, sigsuspend \- POSIX signal handling function
 .BI "int sigsuspend(const sigset_t *" mask );
 .SH DESCRIPTION
 The
-.B sigaction
+.BR sigaction ()
 system call is used to change the action taken by a process on
 receipt of a specific signal.
 .PP
@@ -72,7 +76,7 @@ is non\-null, the previous action is saved in
 .IR oldact .
 .PP
 The
-.B sigaction
+.I sigaction
 structure is defined as something like
 .sp
 .RS
@@ -124,9 +128,7 @@ gives a mask of signals which should be blocked during execution of
 the signal handler.  In addition, the signal which triggered the handler
 will be blocked, unless the
 .B SA_NODEFER
-or
+flag is used.
-.B SA_NOMASK
-flags are used.
 .PP
 .I sa_flags
 specifies a set of flags which modify the behaviour of the signal handling
@@ -157,7 +159,7 @@ is
 .BR SIGCHLD ,
 do not transform children into zombies when they terminate.
 See also
-.BR wait (2).
+.BR waitpid (2).
 .TP
 .B SA_RESETHAND
 Restore the signal action to the default state once the signal handler
@@ -185,7 +187,9 @@ The signal handler takes 3 arguments, not one.  In this case,
 .I sa_sigaction
 should be set instead of
 .IR sa_handler .
-(The sa_sigaction field was added in Linux 2.1.86.)
+(The
+.I sa_sigaction
+field was added in Linux 2.1.86.)
 .RE
 .PP
 The
@@ -220,21 +224,29 @@ siginfo_t {
 are defined for all signals.
 The rest of the struct may be a union, so that one should only
 read the fields that are meaningful for the given signal.
-.BR kill (2),
+POSIX.1b signals and
-POSIX.1b signals and SIGCHLD fill in
+.B SIGCHLD
+fill in
 .IR si_pid " and " si_uid .
 .BR 
-SIGCHLD also fills in
+.B SIGCHLD
+also fills in
 .IR si_status ", " si_utime " and " si_stime .
 .IR si_int " and " si_ptr
 are specified by the sender of the POSIX.1b signal.
 .\" See
 .\" .BR sigqueue (2)
 .\" for more details.
-SIGILL, SIGFPE, SIGSEGV and SIGBUS fill in
+.BR SIGILL , 
+.BR SIGFPE ,
+.BR SIGSEGV , 
+and
+.B SIGBUS
+fill in
 .I si_addr
 with the address of the fault.
-SIGPOLL fills in
+.B SIGPOLL
+fills in
 .IR si_band " and " si_fd .
 
 .I si_code
@@ -341,7 +353,7 @@ POLL_HUP:device disconnected
 
 .PP
 The
-.B sigprocmask
+.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 ,
@@ -370,28 +382,26 @@ is non\-null, the previous value of the signal mask is stored in
 .IR oldset .
 .PP
 The
-.B sigpending
+.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
-.B sigsuspend
+.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"
-The functions
+.BR sigaction (),
-.BR sigaction ,
+.BR sigprocmask (),
-.BR sigprocmask ,
 and
-.B sigpending
+.BR sigpending ()
 return 0 on success and \-1 on error.
-The function
+.BR sigsuspend ()
-.B sigsuspend
 always returns \-1, normally with the error
 .BR EINTR .
 
@@ -417,22 +427,55 @@ It is not possible to block
 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 SIGFPE, SIGILL, or SIGSEGV signal that was not generated
+ignores a
-by the \fIkill()\fP or the \fIraise()\fP functions.
+.BR SIGFPE ,
+.BR SIGILL ,
+or
+.BR SIGSEGV
+signal that was not generated by
+.BR kill ()
+or
+.BR raise ().
 Integer division by zero has undefined result.
-On some architectures it will generate a SIGFPE signal.
+On some architectures it will generate a
+.B SIGFPE
+signal.
 (Also dividing the most negative integer by \-1 may generate SIGFPE.)
 Ignoring this signal might lead to an endless loop.
 .PP
-POSIX (B.3.3.1.3) disallows setting the action for SIGCHLD to SIG_IGN.
+POSIX.1-1990 disallowed setting the action for
-The BSD and SYSV behaviours differ, causing BSD software
+.B SIGCHLD
-that sets the action for SIGCHLD to SIG_IGN to fail on Linux.
+to
+.BR SIG_IGN .
+POSIX.1-2001 allows this possibility, so that ignoring
+.B SIGCHLD
+can be used to prevent the creation of zombies (see
+.BR wait (2)).
+Nevertheless, the historical BSD and System V behaviours for ignoring
+.B SIGCHLD
+differ, so that the only completely portable method of ensuring that
+terminated children do not become zombies is to catch the
+.B SIGCHLD
+signal and perform a
+.BR wait (2)
+or similar.
 .PP
-The POSIX spec only defines
+POSIX.1-1990 only specified
 .BR SA_NOCLDSTOP .
-Use of other
+POSIX.1-2001 added
+.BR SA_NOCLDWAIT ,
+.BR SA_RESETHAND ,
+.BR SA_NODEFER ,
+and
+.BR SA_SIGINFO .
+Use of these latter values in
 .I sa_flags
-is non\-portable.
+may be less portable in applications intended for older
+Unix implementations.
+.PP
+Support for
+.B SA_SIGINFO
+was added in Linux 2.2.
 .PP
 The
 .B SA_RESETHAND
@@ -447,16 +490,13 @@ allowed the receipt of any signal, not just the one we are installing
 .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 sigaction ()
-.B SA_SIGINFO
-flag is specified by POSIX.1b.  Support for it was added in Linux 2.2.
-.PP
-.B 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.
@@ -471,7 +511,9 @@ POSIX, SVr4.  SVr4 does not document the EINTR condition.
 Before the introduction of
 .B SA_SIGINFO
 it was also possible to get some additional information,
-namely by using a sa_handler with second argument of type
+namely by using a
+.I sa_handler
+with second argument of type
 .IR "struct sigcontext".
 See the relevant kernel sources for details.
 This use is obsolete now.
@@ -484,6 +526,7 @@ This use is obsolete now.
 .BR signal (2),
 .BR sigqueue (2),
 .BR sigvec (2),
+.BR wait (2),
 .BR killpg (3),
 .BR raise (3),
 .BR siginterrupt (3),