[src/trunk]: src/share/man/man9 Overhaul documentation of the kernel signal f...

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

details:   https://anonhg.NetBSD.org/src/rev/139a2a0600b6
branches:  trunk
changeset: 533756:139a2a0600b6
user:      thorpej <thorpej%NetBSD.org@localhost>
date:      Tue Jul 09 02:28:08 2002 +0000

description:
Overhaul documentation of the kernel signal facilities.  Some text
liberally borrowed from Paul's psignal(9) manpage.

More work can be done here, but there's more here than before, at least.

diffstat:

 share/man/man9/Makefile  |   30 ++-
 share/man/man9/psignal.9 |  143 -------------
 share/man/man9/signal.9  |  501 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 527 insertions(+), 147 deletions(-)

diffs (truncated from 711 to 300 lines):

diff -r dc36c9e219da -r 139a2a0600b6 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Tue Jul 09 02:25:57 2002 +0000
+++ b/share/man/man9/Makefile   Tue Jul 09 02:28:08 2002 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.112 2002/06/24 22:45:41 gmcgarry Exp $
+#       $NetBSD: Makefile,v 1.113 2002/07/09 02:28:10 thorpej Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -21,9 +21,9 @@
        panic.9 pci.9 pci_configure_bus.9 pci_intr.9 \
        pcmcia.9 pfil.9 physio.9 \
        pmap.9 pool.9 powerhook_establish.9 ppsratecheck.9 properties.9 \
-       psignal.9 radio.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 rt_timer.9 \
+       radio.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 rt_timer.9 \
        scsipi.9 setjmp.9 setrunqueue.9 shutdownhook_establish.9 \
-       sleep.9 softintr.9 \
+       signal.9 sleep.9 softintr.9 \
        spl.9 store.9 suser.9 tc.9 time.9 todr.9 uiomove.9 ucom.9 \
        vattr.9 vfs.9 vfsops.9 vme.9 vnode.9 vnodeops.9 vnsubr.9 \
        usbdi.9 uvm.9 wdc.9 wscons.9 wsdisplay.9 wsfont.9 wskbd.9 wsmouse.9
@@ -266,7 +266,6 @@
        properties.9 prop_list.9 \
        properties.9 prop_objs.9 \
        properties.9 prop_set.9
-MLINKS+=psignal.9 pgsignal.9 psignal.9 gsignal.9
 MLINKS+=rasops.9 rasops_init.9 \
        rasops.9 rasops_reconfig.9
 MLINKS+=rnd.9 rnd_attach_source.9 rnd.9 rnd_detach_source.9 \
@@ -277,6 +276,29 @@
 MLINKS+=setjmp.9 longjmp.9
 MLINKS+=setrunqueue.9 remrunqueue.9
 MLINKS+=shutdownhook_establish.9 shutdownhook_disestablish.9
+MLINKS+=signal.9 siginit.9 \
+       signal.9 sigactsinit.9 \
+       signal.9 sigactsunshare.9 \
+       signal.9 sigactsfree.9 \
+       signal.9 execsigs.9 \
+       signal.9 sigaction1.9 \
+       signal.9 sigprocmask1.9 \
+       signal.9 sigpending1.9 \
+       signal.9 sigsuspend1.9 \
+       signal.9 sigaltstack1.9 \
+       signal.9 gsignal.9 \
+       signal.9 pgsignal.9 \
+       signal.9 trapsignal.9 \
+       signal.9 psignal.9 \
+       signal.9 sched_psignal.9 \
+       signal.9 issignal.9 \
+       signal.9 postsig.9 \
+       signal.9 killproc.9 \
+       signal.9 sigexit.9 \
+       signal.9 sigmasked.9 \
+       signal.9 sendsig.9 \
+       signal.9 sigcode.9 \
+       signal.9 sigtramp.9
 MLINKS+=sleep.9 wakeup.9 sleep.9 tsleep.9 sleep.9 ltsleep.9
 MLINKS+=softintr.9 softintr_establish.9 softintr.9 softintr_disestablish.9 \
        softintr.9 softintr_schedule.9
diff -r dc36c9e219da -r 139a2a0600b6 share/man/man9/psignal.9
--- a/share/man/man9/psignal.9  Tue Jul 09 02:25:57 2002 +0000
+++ /dev/null   Thu Jan 01 00:00:00 1970 +0000
@@ -1,143 +0,0 @@
-.\"    $NetBSD: psignal.9,v 1.5 1999/03/16 00:40:47 garbled Exp $
-.\"
-.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
-.\" All rights reserved.
-.\"
-.\" This code is derived from software contributed to The NetBSD Foundation
-.\" by Paul Kranenburg.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"        This product includes software developed by the NetBSD
-.\"        Foundation, Inc. and its contributors.
-.\" 4. Neither the name of The NetBSD Foundation nor the names of its
-.\"    contributors may be used to endorse or promote products derived
-.\"    from this software without specific prior written permission.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
-.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
-.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
-.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-.\" POSSIBILITY OF SUCH DAMAGE.
-.\"
-.Dd June 22, 1996
-.Dt PSIGNAL 9
-.Os
-.Sh NAME
-.Nm psignal ,
-.Nm pgsignal ,
-.Nm gsignal
-.Nd post signal to a process
-.Sh SYNOPSIS
-.Ft void
-.Fn "psignal" "struct proc *p" "int signum"
-.Ft void
-.Fn "pgsignal" "struct pgrp *pgrp" "int signum" "int checkctty"
-.Ft void
-.Fn "gsignal" "int pgid" "int signum"
-.Sh DESCRIPTION
-These functions post a signal to one or more processes.
-The argument
-.Fa signum
-common to all three functions should be in the range
-.Bq 1- Ns Dv NSIG .
-.Pp
-The
-.Fn psignal
-function posts signal number
-.Fa signum
-to the process represented by the process structure
-.Fa p .
-With a few exceptions noted below, the target process signal disposition is
-updated and is marked as runnable, so further handling of the signal is done
-in the context of the target process after a context switch.
-Note that
-.Fn psignal
-does not by itself cause a context switch to happen.
-.Pp
-The target process is not marked as runnable in the following cases:
-.Bl -bullet -offset indent
-.It
-The target process is sleeping uninterruptibly.
-The signal will be
-noticed when the process returns from the system call or trap.
-.It
-The target process is currently ignoring the signal.
-.It
-If a stop signal is sent to a sleeping process that takes the
-default action
-.Pq see Xr sigaction 2 ,
-the process is stopped without awakening it.
-.It
-.Dv SIGCONT
-restarts a stopped process
-.Pq or puts them back to sleep
-regardless of the signal action
-.Pq e.g., blocked or ignored .
-.El
-.Pp
-If the target process is being traced
-.Fn psignal
-behaves as if the target process were taking the default action for
-.Fa signum .
-This allows the tracing process to be notified of the signal.
-.Pp
-The
-.Fn pgsignal
-function posts signal number
-.Fa signum
-to each member of the process group described by
-.Fa pgrp .
-If
-.Fa checkctty
-is non-zero, the signal will be posted only to processes that have
-a controlling terminal.
-.Fn pgsignal
-is implemented by walking along the process list headed by the field
-.Li pg_members
-of the process group structure
-pointed at by
-.Fa pgrp
-and calling
-.Fn psignal
-as appropriate.
-If
-.Fa pgrp
-is
-.Dv NULL
-no action is taken.
-.Pp
-The
-.Fn gsignal
-function posts signal number
-.Fa signum
-to each member of the process group identified by the group id
-.Fa pgid .
-.Fn gsignal
-first finds the group structure associated with
-.Fa pgid ,
-then invokes
-.Fn pgsignal
-with the argument
-.Fa checkctty
-set to zero.
-If
-.Fa pgid
-is zero no action is taken.
-.Sh SEE ALSO
-.Xr sigaction 2 ,
-.Xr tsleep 9
diff -r dc36c9e219da -r 139a2a0600b6 share/man/man9/signal.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/signal.9   Tue Jul 09 02:28:08 2002 +0000
@@ -0,0 +1,501 @@
+.\"    $NetBSD: signal.9,v 1.1 2002/07/09 02:28:08 thorpej Exp $
+.\"
+.\" Copyright (c) 1996, 2002 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Paul Kranenburg and Jason R. Thorpe.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd July 8, 2002
+.Dt SIGNAL 9
+.Os
+.Sh NAME
+.Nm signal ,
+.Nm siginit ,
+.Nm sigactsinit ,
+.Nm sigactsunshare ,
+.Nm sigactsfree ,
+.Nm execsigs ,
+.Nm sigaction1 ,
+.Nm sigprocmask1 ,
+.Nm sigpending1 ,
+.Nm sigsuspend1 ,
+.Nm sigaltstack1 ,
+.Nm gsignal ,
+.Nm pgsignal ,
+.Nm trapsignal ,
+.Nm psignal ,
+.Nm sched_psignal ,
+.Nm issignal ,
+.Nm postsig ,
+.Nm killproc ,
+.Nm sigexit ,
+.Nm sigmasked ,
+.Nm sendsig ,
+.Nm sigcode ,
+.Nm sigtramp ,
+.Nd software signal facilities
+.Sh SYNOPSIS
+.Fd #include \*[Lt]sys/signal.h\*[Gt]
+.Fd #include \*[Lt]sys/signalvar.h\*[Gt]
+.Ft void
+.Fn siginit "struct proc *p"
+.Ft void
+.Fn sigactsinit "struct proc *np" "struct proc *pp" "int share"
+.Ft void
+.Fn sigactsunsuare "struct proc *p"
+.Ft void
+.Fn sigactsfree "struct proc *p"
+.Ft void
+.Fn execsigs "struct proc *p"
+.Ft int
+.Fn sigaction1 "struct proc *p" "int signum" "const struct sigaction *nsa" \
+    "struct sigaction *osa" "void *tramp" "int vers"
+.Ft int
+.Fn sigprocmask1 "struct proc *p" "int how" "const sigset_t *nss" \
+    "sigset_t *oss"
+.Ft void
+.Fn sigpending1 "struct proc *p" "sigset_t *ss"
+.Ft int
+.Fn sigsuspend1 "struct proc *p" "const sigset_t *ss"
+.Ft int
+.Fn sigaltstack1 "struct proc *p" "const struct sigaltstack *nss" \