[src/trunk]: src/lib/libc/sys - Document NO_DEFER

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/62db3cdb01c3
branches:  trunk
changeset: 555705:62db3cdb01c3
user:      christos <christos%NetBSD.org@localhost>
date:      Tue Nov 25 21:09:14 2003 +0000

description:
- Document NO_DEFER
- Turn sa_flags into a list to make it easier to find/read
- Sort the sa_flags lists.

diffstat:

 lib/libc/sys/sigaction.2 |  104 ++++++++++++++++++++++++----------------------
 1 files changed, 54 insertions(+), 50 deletions(-)

diffs (158 lines):

diff -r aa5de01e1fb4 -r 62db3cdb01c3 lib/libc/sys/sigaction.2
--- a/lib/libc/sys/sigaction.2  Tue Nov 25 21:03:15 2003 +0000
+++ b/lib/libc/sys/sigaction.2  Tue Nov 25 21:09:14 2003 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sigaction.2,v 1.38 2003/10/14 14:59:03 wiz Exp $
+.\"    $NetBSD: sigaction.2,v 1.39 2003/11/25 21:09:14 christos Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"    @(#)sigaction.2 8.2 (Berkeley) 4/3/94
 .\"
-.Dd September 10, 2003
+.Dd November 25, 2003
 .Dt SIGACTION 2
 .Os
 .Sh NAME
@@ -152,10 +152,6 @@
 .Fa sa_handler
 to
 .Dv SIG_DFL .
-Alternately, if the
-.Dv SA_RESETHAND
-bit is set the default action will be reinstated when the signal
-is first posted.
 The defaults are process termination, possibly with core dump;
 no action; stopping the process; or continuing the process.
 See the signal list below for each signal's default action.
@@ -175,9 +171,21 @@
 .Pp
 Options may be specified by setting
 .Em sa_flags .
-If the
-.Dv SA_NOCLDSTOP
-bit is set when installing a catching function
+.Bl -tag -width SA_NOCLDSTOP
+.It Dv SA_NODEFER
+If set, then the signal that caused the handler to be executed is not added
+to the list of block signals.
+Please note that
+.Fa sa_mask
+takes precedence over
+.Dv SA_NODEFER ,
+so that if the specified signal is blocked in
+.Fa sa_mask ,
+then
+.Dv SA_NODEFER
+will have no effect.
+.It Dv SA_NOCLDSTOP
+If set when installing a catching function
 for the
 .Dv SIGCHLD
 signal,
@@ -185,44 +193,19 @@
 .Dv SIGCHLD
 signal will be generated only when a child process exits,
 not when a child process stops.
-Further, if the
-.Dv SA_ONSTACK
-bit is set in
-.Em sa_flags ,
-the system will deliver the signal to the process on a
+.It Dv SA_NOCLDWAIT
+If set, the system will not create a zombie when the child exits,
+but the child process will be automatically waited for.
+.It Dv SA_ONSTACK
+If set, the system will deliver the signal to the process on a
 .Em "signal stack" ,
 specified with
 .Xr sigaltstack 2 .
-Finally, if the
-.Dv SA_NOCLDWAIT
-bit is set in
-.Em sa_flags ,
-the system will not create a zombie when the child exits, but the child
-process will be automatically waited for.
-.Pp
-A user can receive additional information about a caught signal by
-setting the
-.Dv SA_SIGINFO
-flag.
-An alternative handler that gets passed additional arguments will
-be called which is named
-.Fa sa_sigaction .
-The
-.Ar sig
-argument of this handler contains the signal number that was caught.
-The
-.Ar info
-argument contains additional signal specific information which
-is listed in
-.Xr siginfo 2 .
-The
-.Ar ctx
-argument
-is a pointer to the
-.Xr ucontext 2
-context where the signal handler will return to.
-.Pp
-If a signal is caught during the system calls listed below,
+.It Dv SA_RESETHAND
+If set, the default action will be reinstated when the signal
+is first posted.
+.It Dv SA_RESTART
+Normally, if a signal is caught during the system calls listed below,
 the call may be forced to terminate
 with the error
 .Er EINTR ,
@@ -270,6 +253,27 @@
 See
 .Xr signal 7
 for comprehensive list of supported signals.
+.It Dv SA_SIGINFO
+If set, the signal handler function will receive additional information
+about the caught signal.
+An alternative handler that gets passed additional arguments will
+be called which is named
+.Fa sa_sigaction .
+The
+.Ar sig
+argument of this handler contains the signal number that was caught.
+The
+.Ar info
+argument contains additional signal specific information which
+is listed in
+.Xr siginfo 2 .
+The
+.Ar ctx
+argument
+is a pointer to the
+.Xr ucontext 2
+context where the signal handler will return to.
+.El
 .Sh NOTES
 The mask specified in
 .Fa act
@@ -307,14 +311,14 @@
 The
 .Em sa_flags
 word contains bits other than
-.Dv SA_ONSTACK ,
-.Dv SA_RESTART ,
-.Dv SA_RESETHAND ,
+.Dv SA_NOCLDSTOP ,
+.Dv SA_NOCLDWAIT ,
 .Dv SA_NODEFER ,
-.Dv SA_SIGINFO ,
-.Dv SA_NOCLDWAIT ,
+.Dv SA_ONSTACK ,
+.Dv SA_RESETHAND ,
+.Dv SA_RESTART ,
 and
-.Dv SA_NOCLDSTOP .
+.Dv SA_SIGINFO .
 .El
 .Sh SEE ALSO
 .Xr kill 1 ,