X-Git-Url: https://git.subgeniuskitty.com/unix-history/.git/blobdiff_plain/1c15e88899094343f75aeba04122cd96a96b428e..ad7871609881e73855d0b04da49b486cd93efca7:/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 af0cb9d2a1..ff38fd7dd0 100644 --- 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 -.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 +.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 -.IR sigaction (2) +.Xr sigaction 2 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 -.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. -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. -Except for the SIGKILL and SIGSTOP +Except for the +.Dv SIGKILL +and +.Dv SIGSTOP 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 -.I func +.Fa func 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 -.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 -.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 -.IR wait (2) +.Xr ioctl 2 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). -.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. -.SH "RETURN VALUE +.Sh RETURN VALUES 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. -.SH ERRORS -.I Signal +.Sh ERRORS +.Xr Signal 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. -.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 .