[src/trunk]: src/share/man/man7 Document all the signals properly. Please rev...

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

details:   https://anonhg.NetBSD.org/src/rev/56ba9424d5cf
branches:  trunk
changeset: 346358:56ba9424d5cf
user:      dholland <dholland%NetBSD.org@localhost>
date:      Sat Jul 09 23:12:27 2016 +0000

description:
Document all the signals properly. Please review.

Kick out the list of async-signal-safe functions (it is now in
sigaction(2)) because this is not a programmer-facing document.

XXX: if anyone knows definitively whether SIGEMT is actually used by
XXX: anything, please update the weasel words I put in.

diffstat:

 share/man/man7/signal.7 |  762 +++++++++++++++++++++++++++++++++++------------
 1 files changed, 558 insertions(+), 204 deletions(-)

diffs (truncated from 799 to 300 lines):

diff -r b3079dcf5a04 -r 56ba9424d5cf share/man/man7/signal.7
--- a/share/man/man7/signal.7   Sat Jul 09 23:10:05 2016 +0000
+++ b/share/man/man7/signal.7   Sat Jul 09 23:12:27 2016 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: signal.7,v 1.17 2014/07/19 14:53:22 roy Exp $
+.\"    $NetBSD: signal.7,v 1.18 2016/07/09 23:12:27 dholland Exp $
 .\"
 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -24,213 +24,569 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd July 18, 2014
+.Dd July 9, 2016
 .Dt SIGNAL 7
 .Os
 .Sh NAME
 .Nm signal
 .Nd signal facilities
 .Sh DESCRIPTION
-The
-.In signal.h
-header file defines the following signals:
+A
+.Nm
+is a system-level notification delivered to a process.
+Signals may be generated as the result of process activity, by certain
+user inputs, by kernel facilities or subsystems, or sent
+programmatically by other processes or by users.
+There is a small fixed set of signals, each with a symbolic name and a
+number.
+For historical reasons many of the numbers are ``well-known values'',
+which are in practice the same on all implementations and
+realistically can never be changed.
+(Nonetheless, compiled code should always use only the symbolic
+names.)
+Many/most signals also have specific semantics, both in how they can
+be generated and in their effects.
+Some are special cases in ways that have quite far-reaching
+consequences.
+.Pp
+When a signal is
+.Em posted
+.Pq Dq sent
+to a process, in general any of several things can happen.
+If the process has elected to
+.Em ignore
+the signal, it is discarded and nothing happens.
+(Some signals may not be ignored, however.)
+If the process has elected to
+.Em block
+the signal temporarily, delivery is postponed until the process
+later unblocks that signal.
+Otherwise, the signal is
+.Em delivered,
+meaning that whatever the process is doing is interrupted in order to
+react to the signal.
+(Note that processes that are waiting in the kernel must unwind what
+they are doing for signals to be delivered.
+This can sometimes be expensive.
+See
+.Xr sigaction 2
+for further information.)
+.Pp
+If the process has elected to
+.Em catch
+the signal, which means that the process has installed a handler to
+react to the signal in some process-specific way, the kernel arranges
+for the process's handler logic to be invoked.
+This is always done in a way that allows the process to resume if
+desired.
+(Note, however, that some signals may not be caught.)
+Otherwise, the default action for the signal is taken.
+For most signals the default action is a core dump.
+See the table below.
+Note that the term
+.Em delivery
+is also used for the specific process of arranging for a signal
+handler to be invoked.
 .Pp
-.Bl -column ".Sy Value" ".Dv SIGVTALARM" "terminate process" -compact
-.It Sy "Value" Ta Sy "Name" Ta Sy "Default Action" Ta Sy "Description"
-.It 1 Ta Dv SIGHUP Ta "terminate process" Ta "terminal line hangup"
-.It 2 Ta Dv SIGINT Ta "terminate process" Ta "interrupt program"
-.It 3 Ta Dv SIGQUIT Ta "create core image" Ta "quit program"
-.It 4 Ta Dv SIGILL Ta "create core image" Ta "illegal instruction"
-.It 5 Ta Dv SIGTRAP Ta "create core image" Ta "trace trap"
-.It 6 Ta Dv SIGABRT Ta "create core image" Ta Xr abort 3
-call (formerly
-.Dv SIGIOT )
-.It 7 Ta Dv SIGEMT Ta "create core image" Ta "emulate instruction executed"
-.It 8 Ta Dv SIGFPE Ta "create core image" Ta "floating-point exception"
-.It 9 Ta Dv SIGKILL Ta "terminate process" Ta "kill program (cannot be caught or ignored)"
-.It 10 Ta Dv SIGBUS Ta "create core image" Ta "bus error"
-.It 11 Ta Dv SIGSEGV Ta "create core image" Ta "segmentation violation"
-.It 12 Ta Dv SIGSYS Ta "create core image" Ta "invalid system call argument"
-.It 13 Ta Dv SIGPIPE Ta "terminate process" Ta "write to a pipe with no reader"
-.It 14 Ta Dv SIGALRM Ta "terminate process" Ta "real-time timer expired"
-.It 15 Ta Dv SIGTERM Ta "terminate process" Ta "software termination signal"
-.It 16 Ta Dv SIGURG Ta "discard signal" Ta "urgent condition present on socket"
-.It 17 Ta Dv SIGSTOP Ta "stop process" Ta "stop (cannot be caught or ignored)"
-.It 18 Ta Dv SIGTSTP Ta "stop process" Ta "stop signal generated from keyboard"
-.It 19 Ta Dv SIGCONT Ta "discard signal" Ta "continue after stop (even if blocked or ignored)"
-.It 20 Ta Dv SIGCHLD Ta "discard signal" Ta "child status has changed"
-.It 21 Ta Dv SIGTTIN Ta "stop process" Ta "background read attempted from control terminal"
-.It 22 Ta Dv SIGTTOU Ta "stop process" Ta "background write attempted to control terminal"
-.It 23 Ta Dv SIGIO Ta "discard signal" Ta "I/O is possible on a descriptor (see"
-.Xr fcntl 2 )
-.It 24 Ta Dv SIGXCPU Ta "terminate process" Ta "CPU time limit exceeded (see"
-.Xr setrlimit 2 )
-.It 25 Ta Dv SIGXFSZ Ta "terminate process" Ta "file size limit exceeded (see"
-.Xr setrlimit 2 )
-.It 26 Ta Dv SIGVTALRM Ta "terminate process" Ta "virtual time alarm (see"
-.Xr setitimer 2 )
-.It 27 Ta Dv SIGPROF Ta "terminate process" Ta "profiling timer alarm (see"
-.Xr setitimer 2 )
-.It 28 Ta Dv SIGWINCH Ta "discard signal" Ta "window size change"
-.It 29 Ta Dv SIGINFO Ta "discard signal" Ta "status request from keyboard"
-.It 30 Ta Dv SIGUSR1 Ta "terminate process" Ta "user-defined signal 1"
-.It 31 Ta Dv SIGUSR2 Ta "terminate process" Ta "user-defined signal 2"
-.It 32 Ta Dv SIGPWR Ta "discard signal" Ta "power failure/restart"
+In general, signals are delivered as soon as they are posted.
+(Some delays may occur due to scheduling.)
+However, in some cases a process that has been sleeping in the kernel
+may need to do slow things as part of unwinding its state; this can
+sometimes lead to human-perceptible delays.
+.Pp
+Also, some sleep states within the kernel are
+.Em uninterruptible
+meaning that signals posted will have no effect until the state
+clears.
+These states are supposed to be short-term only, but sometimes kernel
+bugs make this not the case and one can end up with unkillable
+processes.
+Such processes appear in state "D" in
+.Xr ps 1 .
+In general the only way to get rid of them is to reboot.
+(However, when the "wchan" reported is "tstile", it means the process
+is waiting for some other process to release resources; sometimes if
+one can find and kill that process the situation is recoverable.)
+.Ss Signal list
+The following signals are defined in
+.Nx :
+.Pp
+.Bl -column ".Sy SIGVTALRM" "Profiling timer expired blablabla" -compact
+.\".It Sy "Symbol" Ta Sy "Descriptive name"
+.It Dv SIGHUP Ta "Hangup"
+.It Dv SIGINT Ta "Interrupt"
+.It Dv SIGQUIT Ta "Quit"
+.It Dv SIGILL Ta "Illegal instruction"
+.It Dv SIGTRAP Ta "Trace/BPT trap"
+.It Dv SIGABRT Ta "Abort trap"
+.It Dv SIGEMT Ta "EMT trap"
+.It Dv SIGFPE Ta "Floating point exception"
+.It Dv SIGKILL Ta "Killed"
+.It Dv SIGBUS Ta "Bus error"
+.It Dv SIGSEGV Ta "Segmentation fault"
+.It Dv SIGSYS Ta "Bad system call"
+.It Dv SIGPIPE Ta "Broken pipe"
+.It Dv SIGALRM Ta "Alarm clock"
+.It Dv SIGTERM Ta "Terminated"
+.It Dv SIGURG Ta "Urgent I/O condition"
+.It Dv SIGSTOP Ta "Suspended (signal)"
+.It Dv SIGTSTP Ta "Suspended"
+.It Dv SIGCONT Ta "Continued"
+.It Dv SIGCHLD Ta "Child exited"
+.It Dv SIGTTIN Ta "Stopped (tty input)"
+.It Dv SIGTTOU Ta "Stopped (tty output)"
+.It Dv SIGIO Ta "I/O possible"
+.It Dv SIGXCPU Ta "CPU time limit exceeded"
+.It Dv SIGXFSZ Ta "File size limit exceeded"
+.It Dv SIGVTALRM Ta "Virtual timer expired"
+.It Dv SIGPROF Ta "Profiling timer expired"
+.It Dv SIGWINCH Ta "Window size changed"
+.It Dv SIGINFO Ta "Information request"
+.It Dv SIGUSR1 Ta "User defined signal 1"
+.It Dv SIGUSR2 Ta "User defined signal 2"
+.It Dv SIGPWR Ta "Power fail/restart"
 .El
 .Pp
-A function that is async-signal-safe is either reentrant or
-non-interruptible by signals.
-This means that they can be used in
-signal handlers
-and in the child of threaded programs after doing
-.Xr fork 2 .
+These are numbered 1 to 32.
+(There is no signal 0; 0 is a reserved value that can be used as a
+no-op with some signal operations.)
+.Pp
+Detailed descriptions of these signals follow.
 .Pp
-The following functions are async-signal-safe.
-Any function not listed
-below is unsafe to use in signal handlers.
-.Pp
-.Xr _Exit 2 ,
-.Xr _exit 2 ,
-.Xr abort 3 ,
-.Xr accept 2 ,
-.Xr access 2 ,
-.\" .Xr aio_error
-.\" .Xr aio_return
-.\" .Xr aio_suspend
+.Bl -tag -width "aaa"
+.\" ************
+.It Dv SIGHUP (Hangup)
+This signal is generated by the tty driver
+.Xr tty 4
+to indicate a hangup condition on a process's controlling terminal:
+the user has disconnected.
+Accordingly, the default action is to terminate the process.
+This signal is also used by many daemons,
+such as
+.Xr inetd 8 ,
+as a cue to reload configuration.
+The number for
+.Dv SIGHUP
+is 1, which is quite well known.
+.\" ************
+.It Dv SIGINT (Interrupt)
+This signal is generated by the tty driver
+.Xr tty 4
+when the user presses the interrupt character, normally control-C.
+The default action is to terminate the process.
+The number for
+.Dv SIGINT
+is 2.
+.\" ************
+.It Dv SIGQUIT Ta (Quit)
+This signal is generated by the tty driver
+.Xr tty 4
+when the user presses the quit character, normally control-backspace.
+The default action is to terminate the process and dump core.
+The number for
+.Dv SIGQUIT
+is 3.
+.\" ************
+.It Dv SIGILL Ta (Illegal instruction)
+This signal is generated synchronously by the kernel when the process
+executes an invalid instruction.
+The default action is to terminate the process and dump core.
+Note: the results of executing an illegal instruction when
+.Dv SIGILL
+is blocked or ignored are formally unspecified.
+The number for
+.Dv SIGILL
+is 4.
+.\" ************
+.It Dv SIGTRAP Ta (Trace/BPT trap)
+This signal is used when a process is being traced
+(see
+.Xr ptrace 2 )
+to indicate that the process has stopped at a breakpoint or after
+single-stepping.
+It is normally intercepted by the debugger and not exposed to the
+debuggee.
+The default action is to terminate the process and dump core.
+The number for
+.Dv SIGTRAP
+is 5.
+.\" ************
+.It Dv SIGABRT Ta (Abort trap)
+This signal is generated when the
+.Xr abort 3
+standard library function is called.
+The default action is to terminate the process and dump core.
+The number for
+.Dv SIGABRT
+is 6.
+This number was also formerly used for
+.Dv SIGIOT ,
+which is no longer defined.
+.\" ************
+.It Dv SIGEMT Ta (EMT trap)
+In theory this signal is generated when an instruction needs to be
+emulated.
+.\"   XXX expand this -- I don't know, grep isn't helping much and
+.\"   information seems pretty thin on the ground on the net.
+The default action is to terminate the process and dump core.
+The number for
+.Dv SIGEMT
+is 7.
+.\" ************
+.It Dv SIGFPE Ta (Floating point exception)
+This signal is generated when an invalid floating point operation is
+detected by hardware or by a soft-float library.
+The default action is to terminate the process and dump core.
+The number for
+.Dv SIGFPE
+is 8.
+.\" ************
+.It Dv SIGKILL Ta (Killed)
+This signal cannot be caught or ignored.
+The (unconditional) action is to terminate the process.
+It is most often sent by system administrators, but is also generated
+by the kernel in response to running completely out of memory and
+swap space.
+Note that because many processes need to perform cleanup before