X-Git-Url: https://git.saurik.com/apple/libc.git/blobdiff_plain/9385eb3d10ebe5eb398c52040ec3dbfba9b0cdcf..ad3c9f2af814c84582fdd1649e49ec4f68572c5a:/gen/FreeBSD/signal.3

diff --git a/gen/FreeBSD/signal.3 b/gen/FreeBSD/signal.3
index 9984726..f18d1cf 100644
--- a/gen/FreeBSD/signal.3
+++ b/gen/FreeBSD/signal.3
@@ -9,10 +9,6 @@
 .\" 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 University of
-.\"	California, Berkeley and its contributors.
 .\" 4. Neither the name of the University nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
@@ -30,9 +26,9 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)signal.3	8.3 (Berkeley) 4/19/94
-.\" $FreeBSD: src/lib/libc/gen/signal.3,v 1.32 2002/12/19 09:40:21 ru Exp $
+.\" $FreeBSD: src/lib/libc/gen/signal.3,v 1.43 2008/07/17 21:54:23 simon Exp $
 .\"
-.Dd April 19, 1994
+.Dd June 7, 2004
 .Dt SIGNAL 3
 .Os
 .Sh NAME
@@ -42,15 +38,23 @@
 .Lb libc
 .Sh SYNOPSIS
 .In signal.h
-.\" The following is Quite Ugly, but syntactically correct.  Don't try to
-.\" fix it.
-.Ft void \*(lp*
-.Fn signal "int sig" "void \*(lp*func\*(rp\*(lpint\*(rp\*(rp\*(rp\*(lpint"
+.\" XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX
+.\" The prototype for signal(3) cannot be cleanly marked up in -mdoc
+.\" without the following lower-level tweak.
+.nr in-synopsis-section 0
 .Pp
-or in
-.Fx Ns 's
-equivalent but easier to read typedef'd version:
+.Ft "void \*(lp*" Ns
+.Fo signal
+.Fa "int sig"
+.Fa "void \*(lp*func\*(rp\*(lpint\*(rp"
+.Fc Ns
+.Ft "\*(rp\*(lpint\*(rp" ;
+.Pp
+.nr in-synopsis-section 1
+.\" XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX
+or in the equivalent but easier to read typedef'd version:
 .Ft typedef "void \*(lp*sig_t\*(rp \*(lpint\*(rp" ;
+.Pp
 .Ft sig_t
 .Fn signal "int sig" "sig_t func"
 .Sh DESCRIPTION
@@ -61,9 +65,10 @@ is a simplified interface to the more general
 .Xr sigaction 2
 facility.
 .Pp
-Signals allow the manipulation of a process from outside its
-domain as well as allowing the process to manipulate itself or
-copies of itself (children). There are two general types of signals:
+Signals allow the manipulation of a process from outside its domain,
+as well as allowing the process to manipulate itself
+or copies of itself (children).
+There are two general types of signals:
 those that cause termination of a process and those that do not.
 Signals which cause termination of a program might result from
 an irrecoverable error or might be the result of a user at a terminal
@@ -75,11 +80,10 @@ Signals are optionally generated
 when a process resumes after being stopped,
 when the status of child processes changes,
 or when input is ready at the control terminal.
-Most signals result in the termination of the process receiving them
-if no action
-is taken; some signals instead cause the process receiving them
-to be stopped, or are simply discarded if the process has not
-requested otherwise.
+Most signals result in the termination of the process receiving them,
+if no action is taken;
+some signals instead cause the process receiving them to be stopped,
+or are simply discarded if the process has not requested otherwise.
 Except for the
 .Dv SIGKILL
 and
@@ -89,48 +93,50 @@ signals, the
 function allows for a signal to be caught, to be ignored, or to generate
 an interrupt.
 These signals are defined in the file
-.Aq Pa signal.h :
-.Bl -column SIGVTALARMXX "create core imagexxx"
-.It Sy "Name	Default Action	Description"
-.It Dv SIGHUP Ta "terminate process" Ta "terminal line hangup"
-.It Dv SIGINT Ta "terminate process" Ta "interrupt program"
-.It Dv SIGQUIT Ta "create core image" Ta "quit program"
-.It Dv SIGILL Ta "create core image" Ta "illegal instruction"
-.It Dv SIGTRAP Ta "create core image" Ta "trace trap"
-.It Dv SIGABRT Ta "create core image" Ta "abort program"
+.In signal.h :
+.Bl -column No ".Dv SIGVTALRM" "create core image"
+.It Sy "No	Name	Default Action	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 "abort program"
 (formerly
 .Dv SIGIOT )
-.It Dv SIGEMT Ta "create core image" Ta "emulate instruction executed"
-.It Dv SIGFPE Ta "create core image" Ta "floating-point exception"
-.It Dv SIGKILL Ta "terminate process" Ta "kill program"
-.It Dv SIGBUS Ta "create core image" Ta "bus error"
-.It Dv SIGSEGV Ta "create core image" Ta "segmentation violation"
-.It Dv SIGSYS Ta "create core image" Ta "non-existent system call invoked"
-.It Dv SIGPIPE Ta "terminate process" Ta "write on a pipe with no reader"
-.It Dv SIGALRM Ta "terminate process" Ta "real-time timer expired"
-.It Dv SIGTERM Ta "terminate process" Ta "software termination signal"
-.It Dv SIGURG Ta "discard signal" Ta "urgent condition present on socket"
-.It Dv SIGSTOP Ta "stop process" Ta "stop (cannot be caught or ignored)"
-.It Dv SIGTSTP Ta "stop process" Ta "stop signal generated from keyboard"
-.It Dv SIGCONT Ta "discard signal" Ta "continue after stop"
-.It Dv SIGCHLD Ta "discard signal" Ta "child status has changed"
-.It Dv SIGTTIN Ta "stop process" Ta "background read attempted from control terminal"
-.It Dv SIGTTOU Ta "stop process" Ta "background write attempted to control terminal"
-.It Dv SIGIO Ta "discard signal" Ta Tn "I/O"
+.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"
+.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 "non-existent system call invoked"
+.It 13 Ta Dv SIGPIPE Ta "terminate process" Ta "write on 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"
+.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 Tn "I/O"
 is possible on a descriptor (see
 .Xr fcntl 2 )
-.It Dv SIGXCPU Ta "terminate process" Ta "cpu time limit exceeded (see"
+.It 24 Ta Dv SIGXCPU Ta "terminate process" Ta "cpu time limit exceeded (see"
 .Xr setrlimit 2 )
-.It Dv SIGXFSZ Ta "terminate process" Ta "file size limit exceeded (see"
+.It 25 Ta Dv SIGXFSZ Ta "terminate process" Ta "file size limit exceeded (see"
 .Xr setrlimit 2 )
-.It Dv SIGVTALRM Ta "terminate process" Ta "virtual time alarm (see"
+.It 26 Ta Dv SIGVTALRM Ta "terminate process" Ta "virtual time alarm (see"
 .Xr setitimer 2 )
-.It Dv SIGPROF Ta "terminate process" Ta "profiling timer alarm (see"
+.It 27 Ta Dv SIGPROF Ta "terminate process" Ta "profiling timer alarm (see"
 .Xr setitimer 2 )
-.It Dv SIGWINCH Ta "discard signal" Ta "Window size change"
-.It Dv SIGINFO Ta "discard signal" Ta "status request from keyboard"
-.It Dv SIGUSR1 Ta "terminate process" Ta "User defined signal 1"
-.It Dv SIGUSR2 Ta "terminate process" Ta "User defined signal 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"
 .El
 .Pp
 The
@@ -146,7 +152,7 @@ should be
 A
 .Dv SIG_DFL
 resets the default action.
-To ignore the signal
+To ignore the signal,
 .Fa func
 should be
 .Dv SIG_IGN .
@@ -171,16 +177,18 @@ func() remains installed after a signal has been delivered.
 For some system calls, if a signal is caught while the call is
 executing and the call is prematurely terminated,
 the call is automatically restarted.
-(The handler is installed using the
+Any handler installed with
+.Xr signal 3
+will have the
 .Dv SA_RESTART
-flag with
-.Xr sigaction 2 . )
+flag set, meaning that any restartable system call will not return on
+receipt of a signal.
 The affected system calls include
 .Xr read 2 ,
 .Xr write 2 ,
 .Xr sendto 2 ,
 .Xr recvfrom 2 ,
-.Xr sendmsg 2
+.Xr sendmsg 2 ,
 and
 .Xr recvmsg 2
 on a communications channel or a low speed device
@@ -201,13 +209,29 @@ to the
 function;
 ignored signals remain ignored.
 .Pp
+If a process explicitly specifies
+.Dv SIG_IGN
+as the action for the signal
+.Dv SIGCHLD ,
+the system will not create zombie processes when children
+of the calling process exit.
+As a consequence, the system will discard the exit status
+from the child processes.
+If the calling process subsequently issues a call to
+.Xr wait 2
+or equivalent, it will block until all of the calling process's
+children terminate, and then return a value of \-1 with
+.Va errno
+set to
+.Er ECHILD .
+.Pp
 See
 .Xr sigaction 2
 for a list of functions
 that are considered safe for use in signal handlers.
 .Sh RETURN VALUES
 The previous action is returned on a successful call.
-Otherwise, SIG_ERR is returned and  the global variable
+Otherwise, SIG_ERR is returned and the global variable
 .Va errno
 is set to indicate the error.
 .Sh ERRORS
@@ -226,7 +250,7 @@ is not a valid signal number.
 An attempt is made to ignore or supply a handler for
 .Dv SIGKILL
 or
-.Ev SIGSTOP .
+.Dv SIGSTOP .
 .El
 .Sh SEE ALSO
 .Xr kill 1 ,
@@ -236,12 +260,17 @@ or
 .Xr sigaltstack 2 ,
 .Xr sigprocmask 2 ,
 .Xr sigsuspend 2 ,
+.Xr wait 2 ,
 .Xr fpsetmask 3 ,
 .Xr setjmp 3 ,
 .Xr siginterrupt 3 ,
 .Xr tty 4
 .Sh HISTORY
-This
-.Fn signal
+The
+.Nm
 facility appeared in
 .Bx 4.0 .
+The option to avoid the creation of child zombies through ignoring
+.Dv SIGCHLD
+appeared in
+.Fx 5.0 .