BSD 4_4 release

[unix-history] / usr / src / lib / libc / gen / signal.3

diff --git a/usr/src/lib/libc/gen/signal.3 b/usr/src/lib/libc/gen/signal.3
index af0cb9d..ff38fd7 100644 (file)
--- a/usr/src/lib/libc/gen/signal.3
+++ b/usr/src/lib/libc/gen/signal.3
@@ -1,228 +1,221 @@
-.\" Copyright (c) 1980 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1980, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\"    @(#)signal.3    6.5 (Berkeley) 7/1/90
+.\" 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 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.

 .\"
 .\"

-.TH SIGNAL 3C "July 1, 1990"
-.UC 4
-.ie t .ds d \(dg
-.el .ds d \z'|+'
-.ie t .ds b \(bu
-.el .ds b @
-.SH NAME
-signal \- simplified software signal facilities
-.SH SYNOPSIS
-.nf
-.B #include <signal.h>
-.PP
-.B void (*signal(sig, func))()
-.B void (*func)();
-.fi
-.SH DESCRIPTION
-.I Signal
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
+.\"
+.\"     @(#)signal.3   8.1 (Berkeley) 6/4/93
+.\"
+.Dd June 4, 1993
+.Dt SIGNAL 3
+.Os BSD 4
+.Sh NAME
+.Nm signal
+.Nd simplified software signal facilities
+.Sh SYNOPSIS
+.Fd #include <signal.h>
+.Ft void
+.Fn *signal sig func\*(lp\*(rp
+.Ft void
+.\" can not do this with .Fn yet
+.br
+\*(lp\|\*(fN*func\*(rp\*(lp\|\*(rp\fR
+.Sh DESCRIPTION
+This
+.Fn signal
+facility

 is a simplified interface to the more general
 is a simplified interface to the more general

-.IR sigaction (2)
+.Xr sigaction 2

 facility.
 facility.

-.PP
-A signal
-is generated by some abnormal event,
-initiated by a user at a terminal (quit, interrupt, stop),
-by a program error (bus error, etc.),
-by request of another program (kill),
-or when a process is stopped because it wishes to access
+.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:
+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
+typing the `interrupt' character.
+Signals are used when a process is stopped because it wishes to access

 its control terminal while in the background (see
 its control terminal while in the background (see

-.IR tty (4)).
+.Xr tty 4 ) .

 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.
 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 cause termination of the receiving process if no action
+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.
 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 SIGKILL and SIGSTOP
+Except for the
+.Dv SIGKILL
+and
+.Dv SIGSTOP

 signals, the
 signals, the

-.I signal
-call allows signals either to be ignored
-or to cause an interrupt to a specified location.
-The following is a list of all signals with
-names as in the include file
-.RI < signal.h >:
-.LP
-.nf
-.ta \w'SIGVTALRM 'u +\w'15*  'u
-SIGHUP 1       hangup
-SIGINT 2       interrupt
-SIGQUIT        3*      quit
-SIGILL 4*      illegal instruction
-SIGTRAP        5*      trace trap
-SIGABRT        6*      \fIabort\fP() call (formerly SIGIOT)
-SIGEMT 7*      EMT instruction
-SIGFPE 8*      floating point exception
-SIGKILL        9       kill (cannot be caught or ignored)
-SIGBUS 10*     bus error
-SIGSEGV        11*     segmentation violation
-SIGSYS 12*     bad argument to system call
-SIGPIPE        13      write on a pipe with no one to read it
-SIGALRM        14      alarm clock
-SIGTERM        15      software termination signal
-SIGURG 16\*b   urgent condition present on socket
-SIGSTOP        17\*d   stop (cannot be caught or ignored)
-SIGTSTP        18\*d   stop signal generated from keyboard
-SIGCONT        19\*b   continue after stop
-SIGCHLD        20\*b   child status has changed
-SIGTTIN        21\*d   background read attempted from control terminal
-SIGTTOU        22\*d   background write attempted to control terminal
-SIGIO  23\*b   i/o is possible on a descriptor (see \fIfcntl\fP(2))
-SIGXCPU        24      cpu time limit exceeded (see \fIsetrlimit\fP(2))
-SIGXFSZ        25      file size limit exceeded (see \fIsetrlimit\fP(2))
-SIGVTALRM      26      virtual time alarm (see \fIsetitimer\fP(2))
-SIGPROF        27      profiling timer alarm (see \fIsetitimer\fP(2))
-SIGWINCH       28\*b   Window size change
-SIGINFO        29\*b   status request from keyboard
-SIGUSR1        30      User defined signal 1
-SIGUSR2        31      User defined signal 2
-.fi
-.PP
-The starred signals in the list above cause a core image
-if not caught or ignored.
-.PP
-If
-.I func
-is SIG_DFL, the default action
-for signal
-.I sig
-is reinstated; this default is termination
-(with a core image for starred signals)
-except for signals marked with \*b or \*d.
-Signals marked with \*b are discarded if the action
-is SIG_DFL; signals marked
-with \*d cause the process to stop.
-If
-.I func
-is SIG_IGN the signal is subsequently ignored
-and pending instances of the signal are discarded.
-Otherwise, when the signal occurs
+.Fn signal
+function allows for a signal to be caught, to be ignored, or to generate
+an interupt.
+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 No "     terminate process" "    terminal line hangup"
+.It Dv SIGINT No "     terminate process" "    interrupt program"
+.It Dv SIGQUIT No "    create core image" "    quit program"
+.It Dv SIGILL No "     create core image" "    illegal instruction"
+.It Dv SIGTRAP No "    create core image" "    trace trap"
+.It Dv SIGABRT No "    create core image" Xr   abort 2
+call (formerly
+.Dv SIGIOT )
+.It Dv SIGEMT No "     create core image" "    emulate instruction executed"
+.It Dv SIGFPE No "     create core image" "    floating-point exception"
+.It Dv SIGKILL No "    terminate process" "    kill program"
+.It Dv SIGBUS No "     create core image" "    bus error"
+.It Dv SIGSEGV No "    create core image" "    segmentation violation"
+.It Dv SIGSYS No "     create core image" "    system call given invalid argument"
+.It Dv SIGPIPE No "    terminate process" "    write on a pipe with no reader"
+.It Dv SIGALRM No "    terminate process" "    real-time timer expired"
+.It Dv SIGTERM No "    terminate process" "    software termination signal"
+.It Dv SIGURG No "     discard signal" "       urgent condition present on socket"
+.It Dv SIGSTOP No "    stop process" " stop (cannot be caught or ignored)"
+.It Dv SIGTSTP No "    stop process" " stop signal generated from keyboard"
+.It Dv SIGCONT No "    discard signal" "       continue after stop"
+.It Dv SIGCHLD No "    discard signal" "       child status has changed"
+.It Dv SIGTTIN No "    stop process" " background read attempted from control terminal"
+.It Dv SIGTTOU No "    stop process" " background write attempted to control terminal"
+.It Dv SIGIO No "      discard signal" Tn "    I/O"
+is possible on a descriptor (see
+.Xr fcntl 2 )
+.It Dv SIGXCPU No "    terminate process" "    cpu time limit exceeded (see"
+.Xr setrlimit 2 )
+.It Dv SIGXFSZ No "    terminate process" "    file size limit exceeded (see"
+.Xr setrlimit 2 )
+.It Dv SIGVTALRM No "  terminate process" "    virtual time alarm (see"
+.Xr setitimer 2 )
+.It Dv SIGPROF No "    terminate process" "    profiling timer alarm (see"
+.Xr setitimer 2 )
+.It Dv SIGWINCH No "   discard signal" "       Window size change"
+.It Dv SIGINFO No "    discard signal" "       status request from keyboard"
+.It Dv SIGUSR1 No "    terminate process" "    User defined signal 1"
+.It Dv SIGUSR2 No "    terminate process" "    User defined signal 2"
+.El
+.Pp
+The
+.Fa func
+procedure allows a user to choose the action upon receipt of a signal.
+To set the default action of the signal to occur as listed above,
+.Fa func
+should be
+.Dv SIG_DFL .
+A
+.Dv SIG_DFL
+resets the default action.
+To ignore the signal
+.Fa func
+should be
+.Dv SIG_IGN .
+This will cause subsequent instances of the signal to be ignored
+and pending instances to be discarded. If
+.Dv SIG_IGN
+is not used,

 further occurrences of the signal are
 automatically blocked and
 further occurrences of the signal are
 automatically blocked and

-.I func
+.Fa func

 is called.
 is called.

-.PP
-A return from the function unblocks
-the handled signal and
-continues the process at the point it was interrupted.
-\fBUnlike previous signal facilities, the handler \fIfunc\fP
-remains installed after a signal has been delivered.\fP
-.PP
-If a caught signal occurs
-during certain system calls, causing
-the call to terminate prematurely, the call
-is automatically restarted
-(the handler is installed using the SA_RESTART flag with
-.IR sigaction (2)).
+.Pp
+The handled signal is unblocked with the
+function returns and
+the process continues from where it left off when the signal occured.
+.Bf -symbolic
+Unlike previous signal facilities, the handler
+func() remains installed after a signal has been delivered.
+.Ef
+.Pp
+For some system calls, if a signal is caught while the call is
+executing and the call is permaturely terminated,
+the call is automatically restarted.
+(The handler is installed using the
+.Dv SA_RESTART
+flag with
+.Xr sigaction 2 . )

 The affected system calls include
 The affected system calls include

-.IR read (2),
-.IR write (2),
-.IR sendto (2),
-.IR recvfrom (2),
-.IR sendmsg (2)
+.Xr read 2 ,
+.Xr write 2 ,
+.Xr sendto 2 ,
+.Xr recvfrom 2 ,
+.Xr sendmsg 2

 and
 and

-.IR recvmsg (2)
-on a communications channel or a slow device (such as a terminal,
-but not a regular file)
+.Xr recvmsg 2
+on a communications channel or a low speed device

 and during a
 and during a

-.IR wait (2)
+.Xr ioctl 2

 or
 or

-.IR ioctl (2).
+.Xr wait 2 .

 However, calls that have already committed are not restarted,
 but instead return a partial success (for example, a short read count).
 However, calls that have already committed are not restarted,
 but instead return a partial success (for example, a short read count).

-.PP
-The value of
-.I signal
-is the previous (or initial)
-value of
-.I func
-for the particular signal.
-.PP
-After a
-.IR fork (2)
-or
-.IR vfork (2)
-the child inherits
-all signals.
-.IR  Execve (2)
-resets all caught signals to the default action;
+.Pp
+When a process which has installed signal handlers forks,
+the child process inherits the signals.
+All caught signals may be reset to their default action by a call
+to the
+.Xr execve 2
+function;

 ignored signals remain ignored.
 ignored signals remain ignored.

-.SH "RETURN VALUE
+.Sh RETURN VALUES

 The previous action is returned on a successful call.
 The previous action is returned on a successful call.

-Otherwise, \-1 is returned and 
-.I errno
+Otherwise, \-1 is returned and  the global variable
+.Va errno

 is set to indicate the error.
 is set to indicate the error.

-.SH ERRORS
-.I Signal
+.Sh ERRORS
+.Xr Signal

 will fail and no action will take place if one of the
 following occur:
 will fail and no action will take place if one of the
 following occur:

-.TP 15
-[EINVAL]
-.I Sig
+.Bl -tag -width [EINVAL]
+.It Bq Er EINVAL
+.Em Sig

 is not a valid signal number.
 is not a valid signal number.

-.TP 15
-[EINVAL]
-An attempt is made to ignore or supply a handler for SIGKILL
-or SIGSTOP.
-.SH "SEE ALSO"
-kill(1), ptrace(2), kill(2),
-sigaction(2), sigprocmask(2), sigsuspend(2),
-sigstack(2), setjmp(3), tty(4)
-.SH "NOTES  (VAX-11)"
-The handler routine can be declared:
-.PP
-    void handler(sig, code, scp)
-.PP
-Here
-.I sig
-is the signal number, into which the hardware faults and traps are
-mapped as defined below.  Code is a parameter which is either a constant
-as given below or, for compatibility mode faults, the code provided by
-the hardware. 
-.I Scp
-is a pointer to the
-.I "struct sigcontext"
-used by the system to restore the process context from before
-the signal.
-Compatibility mode faults are distinguished from the
-other SIGILL traps by having PSL_CM set in the psl.
-.PP
-The following defines the mapping of hardware traps to signals
-and codes.  All of these symbols are defined in
-.RI < signal.h >:
-.LP
-.ta \w'     Floating/decimal divide by zero   'u +\w'15*  'u +8n
-.nf
-   Hardware condition  Signal  Code
-
-Arithmetic traps:
-   Integer overflow    SIGFPE  FPE_INTOVF_TRAP
-   Integer division by zero    SIGFPE  FPE_INTDIV_TRAP
-   Floating overflow trap      SIGFPE  FPE_FLTOVF_TRAP
-   Floating/decimal division by zero   SIGFPE  FPE_FLTDIV_TRAP
-   Floating underflow trap     SIGFPE  FPE_FLTUND_TRAP
-   Decimal overflow trap       SIGFPE  FPE_DECOVF_TRAP
-   Subscript-range     SIGFPE  FPE_SUBRNG_TRAP
-   Floating overflow fault     SIGFPE  FPE_FLTOVF_FAULT
-   Floating divide by zero fault       SIGFPE  FPE_FLTDIV_FAULT
-   Floating underflow fault    SIGFPE  FPE_FLTUND_FAULT
-Length access control  SIGSEGV
-Protection violation   SIGBUS
-Reserved instruction   SIGILL  ILL_RESAD_FAULT
-Customer-reserved instr.       SIGEMT
-Reserved operand       SIGILL  ILL_PRIVIN_FAULT
-Reserved addressing    SIGILL  ILL_RESOP_FAULT
-Trace pending  SIGTRAP
-Bpt instruction        SIGTRAP
-Compatibility-mode     SIGILL  hardware supplied code
-Chme   SIGSEGV
-Chms   SIGSEGV
-Chmu   SIGSEGV
-.fi
+.It Bq Er EINVAL
+An attempt is made to ignore or supply a handler for
+.Dv SIGKILL
+or
+.Ev SIGSTOP .
+.Sh SEE ALSO
+.Xr kill 1 ,
+.Xr ptrace 2 ,
+.Xr kill 2 ,
+.Xr sigaction 2 ,
+.Xr sigaltstack 2 ,
+.Xr sigprocmask 2 ,
+.Xr sigsuspend 2 ,
+.Xr setjmp 3 ,
+.Xr tty 4
+.Sh HISTORY
+This
+.Nm signal
+facility appeared in 
+.Bx 4.0 .