1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)signal.3 8.3 (Berkeley) 04/19/94 7.\" 8.Dd 9.Dt SIGNAL 3 10.Os BSD 4 11.Sh NAME 12.Nm signal 13.Nd simplified software signal facilities 14.Sh SYNOPSIS 15.Fd #include <signal.h> 16.Ft void 17.Fn *signal sig func\*(lp\*(rp 18.Ft void 19.\" can not do this with .Fn yet 20.br 21\*(lp\|\*(fN*func\*(rp\*(lp\|\*(rp\fR 22.Sh DESCRIPTION 23This 24.Fn signal 25facility 26is a simplified interface to the more general 27.Xr sigaction 2 28facility. 29.Pp 30Signals allow the manipulation of a process from outside its 31domain as well as allowing the process to manipulate itself or 32copies of itself (children). There are two general types of signals: 33those that cause termination of a process and those that do not. 34Signals which cause termination of a program might result from 35an irrecoverable error or might be the result of a user at a terminal 36typing the `interrupt' character. 37Signals are used when a process is stopped because it wishes to access 38its control terminal while in the background (see 39.Xr tty 4 ) . 40Signals are optionally generated 41when a process resumes after being stopped, 42when the status of child processes changes, 43or when input is ready at the control terminal. 44Most signals result in the termination of the process receiving them 45if no action 46is taken; some signals instead cause the process receiving them 47to be stopped, or are simply discarded if the process has not 48requested otherwise. 49Except for the 50.Dv SIGKILL 51and 52.Dv SIGSTOP 53signals, the 54.Fn signal 55function allows for a signal to be caught, to be ignored, or to generate 56an interrupt. 57These signals are defined in the file 58.Aq Pa signal.h : 59.Bl -column SIGVTALARMXX "create core imagexxx" 60.It Sy " Name " " Default Action " " Description" 61.It Dv SIGHUP No " terminate process" " terminal line hangup" 62.It Dv SIGINT No " terminate process" " interrupt program" 63.It Dv SIGQUIT No " create core image" " quit program" 64.It Dv SIGILL No " create core image" " illegal instruction" 65.It Dv SIGTRAP No " create core image" " trace trap" 66.It Dv SIGABRT No " create core image" Xr abort 2 67call (formerly 68.Dv SIGIOT ) 69.It Dv SIGEMT No " create core image" " emulate instruction executed" 70.It Dv SIGFPE No " create core image" " floating-point exception" 71.It Dv SIGKILL No " terminate process" " kill program" 72.It Dv SIGBUS No " create core image" " bus error" 73.It Dv SIGSEGV No " create core image" " segmentation violation" 74.It Dv SIGSYS No " create core image" " system call given invalid argument" 75.It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" 76.It Dv SIGALRM No " terminate process" " real-time timer expired" 77.It Dv SIGTERM No " terminate process" " software termination signal" 78.It Dv SIGURG No " discard signal" " urgent condition present on socket" 79.It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" 80.It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" 81.It Dv SIGCONT No " discard signal" " continue after stop" 82.It Dv SIGCHLD No " discard signal" " child status has changed" 83.It Dv SIGTTIN No " stop process" " background read attempted from control terminal" 84.It Dv SIGTTOU No " stop process" " background write attempted to control terminal" 85.It Dv SIGIO No " discard signal" Tn " I/O" 86is possible on a descriptor (see 87.Xr fcntl 2 ) 88.It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" 89.Xr setrlimit 2 ) 90.It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" 91.Xr setrlimit 2 ) 92.It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" 93.Xr setitimer 2 ) 94.It Dv SIGPROF No " terminate process" " profiling timer alarm (see" 95.Xr setitimer 2 ) 96.It Dv SIGWINCH No " discard signal" " Window size change" 97.It Dv SIGINFO No " discard signal" " status request from keyboard" 98.It Dv SIGUSR1 No " terminate process" " User defined signal 1" 99.It Dv SIGUSR2 No " terminate process" " User defined signal 2" 100.El 101.Pp 102The 103.Fa func 104procedure allows a user to choose the action upon receipt of a signal. 105To set the default action of the signal to occur as listed above, 106.Fa func 107should be 108.Dv SIG_DFL . 109A 110.Dv SIG_DFL 111resets the default action. 112To ignore the signal 113.Fa func 114should be 115.Dv SIG_IGN . 116This will cause subsequent instances of the signal to be ignored 117and pending instances to be discarded. If 118.Dv SIG_IGN 119is not used, 120further occurrences of the signal are 121automatically blocked and 122.Fa func 123is called. 124.Pp 125The handled signal is unblocked with the 126function returns and 127the process continues from where it left off when the signal occurred. 128.Bf -symbolic 129Unlike previous signal facilities, the handler 130func() remains installed after a signal has been delivered. 131.Ef 132.Pp 133For some system calls, if a signal is caught while the call is 134executing and the call is prematurely terminated, 135the call is automatically restarted. 136(The handler is installed using the 137.Dv SA_RESTART 138flag with 139.Xr sigaction 2 . ) 140The affected system calls include 141.Xr read 2 , 142.Xr write 2 , 143.Xr sendto 2 , 144.Xr recvfrom 2 , 145.Xr sendmsg 2 146and 147.Xr recvmsg 2 148on a communications channel or a low speed device 149and during a 150.Xr ioctl 2 151or 152.Xr wait 2 . 153However, calls that have already committed are not restarted, 154but instead return a partial success (for example, a short read count). 155.Pp 156When a process which has installed signal handlers forks, 157the child process inherits the signals. 158All caught signals may be reset to their default action by a call 159to the 160.Xr execve 2 161function; 162ignored signals remain ignored. 163.Sh RETURN VALUES 164The previous action is returned on a successful call. 165Otherwise, \-1 is returned and the global variable 166.Va errno 167is set to indicate the error. 168.Sh ERRORS 169.Xr Signal 170will fail and no action will take place if one of the 171following occur: 172.Bl -tag -width [EINVAL] 173.It Bq Er EINVAL 174.Em Sig 175is not a valid signal number. 176.It Bq Er EINVAL 177An attempt is made to ignore or supply a handler for 178.Dv SIGKILL 179or 180.Ev SIGSTOP . 181.Sh SEE ALSO 182.Xr kill 1 , 183.Xr ptrace 2 , 184.Xr kill 2 , 185.Xr sigaction 2 , 186.Xr sigaltstack 2 , 187.Xr sigprocmask 2 , 188.Xr sigsuspend 2 , 189.Xr setjmp 3 , 190.Xr tty 4 191.Sh HISTORY 192This 193.Nm signal 194facility appeared in 195.Bx 4.0 . 196