| 1 | .\" Copyright (c) 1980 Regents of the University of California. |
| 2 | .\" All rights reserved. The Berkeley software License Agreement |
| 3 | .\" specifies the terms and conditions for redistribution. |
| 4 | .\" |
| 5 | .\" @(#)signal.3 6.4 (Berkeley) %G% |
| 6 | .\" |
| 7 | .TH SIGNAL 3C "" |
| 8 | .UC 4 |
| 9 | .ie t .ds d \(dg |
| 10 | .el .ds d \z'|+' |
| 11 | .ie t .ds b \(bu |
| 12 | .el .ds b @ |
| 13 | .SH NAME |
| 14 | signal \- simplified software signal facilities |
| 15 | .SH SYNOPSIS |
| 16 | .nf |
| 17 | .B #include <signal.h> |
| 18 | .PP |
| 19 | .B (*signal(sig, func))() |
| 20 | .B int (*func)(); |
| 21 | .fi |
| 22 | .SH DESCRIPTION |
| 23 | .I Signal |
| 24 | is a simplified interface to the more general |
| 25 | .IR sigvec (2) |
| 26 | facility. |
| 27 | .PP |
| 28 | A signal |
| 29 | is generated by some abnormal event, |
| 30 | initiated by a user at a terminal (quit, interrupt, stop), |
| 31 | by a program error (bus error, etc.), |
| 32 | by request of another program (kill), |
| 33 | or when a process is stopped because it wishes to access |
| 34 | its control terminal while in the background (see |
| 35 | .IR tty (4)). |
| 36 | Signals are optionally generated |
| 37 | when a process resumes after being stopped, |
| 38 | when the status of child processes changes, |
| 39 | or when input is ready at the control terminal. |
| 40 | Most signals cause termination of the receiving process if no action |
| 41 | is taken; some signals instead cause the process receiving them |
| 42 | to be stopped, or are simply discarded if the process has not |
| 43 | requested otherwise. |
| 44 | Except for the SIGKILL and SIGSTOP |
| 45 | signals, the |
| 46 | .I signal |
| 47 | call allows signals either to be ignored |
| 48 | or to cause an interrupt to a specified location. |
| 49 | The following is a list of all signals with |
| 50 | names as in the include file |
| 51 | .RI < signal.h >: |
| 52 | .LP |
| 53 | .nf |
| 54 | .ta \w'SIGVTALRM 'u +\w'15* 'u |
| 55 | SIGHUP 1 hangup |
| 56 | SIGINT 2 interrupt |
| 57 | SIGQUIT 3* quit |
| 58 | SIGILL 4* illegal instruction |
| 59 | SIGTRAP 5* trace trap |
| 60 | SIGIOT 6* IOT instruction |
| 61 | SIGEMT 7* EMT instruction |
| 62 | SIGFPE 8* floating point exception |
| 63 | SIGKILL 9 kill (cannot be caught or ignored) |
| 64 | SIGBUS 10* bus error |
| 65 | SIGSEGV 11* segmentation violation |
| 66 | SIGSYS 12* bad argument to system call |
| 67 | SIGPIPE 13 write on a pipe with no one to read it |
| 68 | SIGALRM 14 alarm clock |
| 69 | SIGTERM 15 software termination signal |
| 70 | SIGURG 16\*b urgent condition present on socket |
| 71 | SIGSTOP 17\*d stop (cannot be caught or ignored) |
| 72 | SIGTSTP 18\*d stop signal generated from keyboard |
| 73 | SIGCONT 19\*b continue after stop |
| 74 | SIGCHLD 20\*b child status has changed |
| 75 | SIGTTIN 21\*d background read attempted from control terminal |
| 76 | SIGTTOU 22\*d background write attempted to control terminal |
| 77 | SIGIO 23\*b i/o is possible on a descriptor (see \fIfcntl\fP(2)) |
| 78 | SIGXCPU 24 cpu time limit exceeded (see \fIsetrlimit\fP(2)) |
| 79 | SIGXFSZ 25 file size limit exceeded (see \fIsetrlimit\fP(2)) |
| 80 | SIGVTALRM 26 virtual time alarm (see \fIsetitimer\fP(2)) |
| 81 | SIGPROF 27 profiling timer alarm (see \fIsetitimer\fP(2)) |
| 82 | SIGWINCH 28\*b Window size change |
| 83 | SIGUSR1 30 User defined signal 1 |
| 84 | SIGUSR2 31 User defined signal 2 |
| 85 | .fi |
| 86 | .PP |
| 87 | The starred signals in the list above cause a core image |
| 88 | if not caught or ignored. |
| 89 | .PP |
| 90 | If |
| 91 | .I func |
| 92 | is SIG_DFL, the default action |
| 93 | for signal |
| 94 | .I sig |
| 95 | is reinstated; this default is termination |
| 96 | (with a core image for starred signals) |
| 97 | except for signals marked with \*b or \*d. |
| 98 | Signals marked with \*b are discarded if the action |
| 99 | is SIG_DFL; signals marked |
| 100 | with \*d cause the process to stop. |
| 101 | If |
| 102 | .I func |
| 103 | is SIG_IGN the signal is subsequently ignored |
| 104 | and pending instances of the signal are discarded. |
| 105 | Otherwise, when the signal occurs |
| 106 | further occurrences of the signal are |
| 107 | automatically blocked and |
| 108 | .I func |
| 109 | is called. |
| 110 | .PP |
| 111 | A return from the function unblocks |
| 112 | the handled signal and |
| 113 | continues the process at the point it was interrupted. |
| 114 | \fBUnlike previous signal facilities, the handler \fIfunc\fP |
| 115 | remains installed after a signal has been delivered.\fP |
| 116 | .PP |
| 117 | If a caught signal occurs |
| 118 | during certain system calls, causing |
| 119 | the call to terminate prematurely, the call |
| 120 | is automatically restarted. |
| 121 | In particular this can occur |
| 122 | during a |
| 123 | .I read |
| 124 | or |
| 125 | .IR write (2) |
| 126 | on a slow device (such as a terminal; but not a file) |
| 127 | and during a |
| 128 | .IR wait (2). |
| 129 | .PP |
| 130 | The value of |
| 131 | .I signal |
| 132 | is the previous (or initial) |
| 133 | value of |
| 134 | .I func |
| 135 | for the particular signal. |
| 136 | .PP |
| 137 | After a |
| 138 | .IR fork (2) |
| 139 | or |
| 140 | .IR vfork (2) |
| 141 | the child inherits |
| 142 | all signals. |
| 143 | .IR Execve (2) |
| 144 | resets all caught signals to the default action; |
| 145 | ignored signals remain ignored. |
| 146 | .SH "RETURN VALUE |
| 147 | The previous action is returned on a successful call. |
| 148 | Otherwise, \-1 is returned and |
| 149 | .I errno |
| 150 | is set to indicate the error. |
| 151 | .SH ERRORS |
| 152 | .I Signal |
| 153 | will fail and no action will take place if one of the |
| 154 | following occur: |
| 155 | .TP 15 |
| 156 | [EINVAL] |
| 157 | .I Sig |
| 158 | is not a valid signal number. |
| 159 | .TP 15 |
| 160 | [EINVAL] |
| 161 | An attempt is made to ignore or supply a handler for SIGKILL |
| 162 | or SIGSTOP. |
| 163 | .TP 15 |
| 164 | [EINVAL] |
| 165 | An attempt is made to ignore SIGCONT (by default SIGCONT |
| 166 | is ignored). |
| 167 | .SH "SEE ALSO" |
| 168 | kill(1), |
| 169 | ptrace(2), kill(2), |
| 170 | sigvec(2), sigblock(2), sigsetmask(2), sigpause(2), |
| 171 | sigstack(2), setjmp(3), tty(4) |
| 172 | .SH "NOTES (VAX-11)" |
| 173 | The handler routine can be declared: |
| 174 | .PP |
| 175 | handler(sig, code, scp) |
| 176 | .PP |
| 177 | Here |
| 178 | .I sig |
| 179 | is the signal number, into which the hardware faults and traps are |
| 180 | mapped as defined below. Code is a parameter which is either a constant |
| 181 | as given below or, for compatibility mode faults, the code provided by |
| 182 | the hardware. |
| 183 | .I Scp |
| 184 | is a pointer to the |
| 185 | .I "struct sigcontext" |
| 186 | used by the system to restore the process context from before |
| 187 | the signal. |
| 188 | Compatibility mode faults are distinguished from the |
| 189 | other SIGILL traps by having PSL_CM set in the psl. |
| 190 | .PP |
| 191 | The following defines the mapping of hardware traps to signals |
| 192 | and codes. All of these symbols are defined in |
| 193 | .RI < signal.h >: |
| 194 | .LP |
| 195 | .ta \w' Floating/decimal divide by zero 'u +\w'15* 'u +8n |
| 196 | .nf |
| 197 | Hardware condition Signal Code |
| 198 | |
| 199 | Arithmetic traps: |
| 200 | Integer overflow SIGFPE FPE_INTOVF_TRAP |
| 201 | Integer division by zero SIGFPE FPE_INTDIV_TRAP |
| 202 | Floating overflow trap SIGFPE FPE_FLTOVF_TRAP |
| 203 | Floating/decimal division by zero SIGFPE FPE_FLTDIV_TRAP |
| 204 | Floating underflow trap SIGFPE FPE_FLTUND_TRAP |
| 205 | Decimal overflow trap SIGFPE FPE_DECOVF_TRAP |
| 206 | Subscript-range SIGFPE FPE_SUBRNG_TRAP |
| 207 | Floating overflow fault SIGFPE FPE_FLTOVF_FAULT |
| 208 | Floating divide by zero fault SIGFPE FPE_FLTDIV_FAULT |
| 209 | Floating underflow fault SIGFPE FPE_FLTUND_FAULT |
| 210 | Length access control SIGSEGV |
| 211 | Protection violation SIGBUS |
| 212 | Reserved instruction SIGILL ILL_RESAD_FAULT |
| 213 | Customer-reserved instr. SIGEMT |
| 214 | Reserved operand SIGILL ILL_PRIVIN_FAULT |
| 215 | Reserved addressing SIGILL ILL_RESOP_FAULT |
| 216 | Trace pending SIGTRAP |
| 217 | Bpt instruction SIGTRAP |
| 218 | Compatibility-mode SIGILL hardware supplied code |
| 219 | Chme SIGSEGV |
| 220 | Chms SIGSEGV |
| 221 | Chmu SIGSEGV |
| 222 | .fi |