| 1 | .\" Copyright (c) 1980, 1990 The Regents of the University of California. |
| 2 | .\" All rights reserved. |
| 3 | .\" |
| 4 | .\" %sccs.include.redist.roff% |
| 5 | .\" |
| 6 | .\" @(#)sigaction.2 6.3 (Berkeley) %G% |
| 7 | .\" |
| 8 | .Dd |
| 9 | .Dt SIGACTION 2 |
| 10 | .Os |
| 11 | .Sh NAME |
| 12 | .Nm sigaction |
| 13 | .Nd software signal facilities |
| 14 | .Sh SYNOPSIS |
| 15 | .Fd #include <signal.h> |
| 16 | .Bd -literal |
| 17 | struct sigaction { |
| 18 | void (*sa_handler)(); |
| 19 | sigset_t sa_mask; |
| 20 | int sa_flags; |
| 21 | }; |
| 22 | .Ed |
| 23 | .Fn sigaction "int sig" "struct sigaction *act" "struct sigaction *oact" |
| 24 | .Sh DESCRIPTION |
| 25 | The system defines a set of signals that may be delivered to a process. |
| 26 | Signal delivery resembles the occurence of a hardware interrupt: |
| 27 | the signal is blocked from further occurrence, the current process |
| 28 | context is saved, and a new one is built. A process may specify a |
| 29 | .Em handler |
| 30 | to which a signal is delivered, or specify that a signal is to be |
| 31 | .Em ignored . |
| 32 | A process may also specify that a default action is to be taken |
| 33 | by the system when a signal occurs. |
| 34 | A signal may also be |
| 35 | .Em blocked , |
| 36 | in which case its delivery is postponed until it is |
| 37 | .Em unblocked . |
| 38 | The action to be taken on delivery is determined at the time |
| 39 | of delivery. |
| 40 | Normally, signal handlers execute on the current stack |
| 41 | of the process. This may be changed, on a per-handler basis, |
| 42 | so that signals are taken on a special |
| 43 | .Em "signal stack" . |
| 44 | .Pp |
| 45 | Signal routines execute with the signal that caused their |
| 46 | invocation |
| 47 | .Em blocked , |
| 48 | but other signals may yet occur. |
| 49 | A global |
| 50 | .Em "signal mask" |
| 51 | defines the set of signals currently blocked from delivery |
| 52 | to a process. The signal mask for a process is initialized |
| 53 | from that of its parent (normally empty). It |
| 54 | may be changed with a |
| 55 | .Xr sigprocmask 2 |
| 56 | call, or when a signal is delivered to the process. |
| 57 | .Pp |
| 58 | When a signal |
| 59 | condition arises for a process, the signal is added to a set of |
| 60 | signals pending for the process. |
| 61 | If the signal is not currently |
| 62 | .Em blocked |
| 63 | by the process then it is delivered to the process. |
| 64 | Signals may be delivered any time a process enters the operating system |
| 65 | (e.g., during a system call, page fault or trap, or clock interrupt). |
| 66 | If multiple signals are ready to be delivered at the same time, |
| 67 | any signals that could be caused by traps are delivered first. |
| 68 | Additional signals may be processed at the same time, with each |
| 69 | appearing to interrupt the handlers for the previous signals |
| 70 | before their first instructions. |
| 71 | The set of pending signals is returned by the |
| 72 | .Xr sigpending 2 |
| 73 | function. |
| 74 | When a caught signal |
| 75 | is delivered, the current state of the process is saved, |
| 76 | a new signal mask is calculated (as described below), |
| 77 | and the signal handler is invoked. The call to the handler |
| 78 | is arranged so that if the signal handling routine returns |
| 79 | normally the process will resume execution in the context |
| 80 | from before the signal's delivery. |
| 81 | If the process wishes to resume in a different context, then it |
| 82 | must arrange to restore the previous context itself. |
| 83 | .Pp |
| 84 | When a signal is delivered to a process a new signal mask is |
| 85 | installed for the duration of the process' signal handler |
| 86 | (or until a |
| 87 | .Xr sigprocmask |
| 88 | call is made). |
| 89 | This mask is formed by taking the union of the current signal mask set, |
| 90 | the signal to be delivered, and |
| 91 | the signal mask associated with the handler to be invoked. |
| 92 | .Pp |
| 93 | .Fn Sigaction |
| 94 | assigns an action for a specific signal. |
| 95 | If |
| 96 | .Fa act |
| 97 | is non-zero, it |
| 98 | specifies an action |
| 99 | .Pf ( Dv SIG_DFL , |
| 100 | .Dv SIG_IGN , |
| 101 | or a handler routine) and mask |
| 102 | to be used when delivering the specified signal. |
| 103 | If |
| 104 | .Fa oact |
| 105 | is non-zero, the previous handling information for the signal |
| 106 | is returned to the user. |
| 107 | .Pp |
| 108 | Once a signal handler is installed, it remains installed |
| 109 | until another |
| 110 | .Fn sigaction |
| 111 | call is made, or an |
| 112 | .Xr execve 2 |
| 113 | is performed. |
| 114 | A signal-specific default action may be reset by |
| 115 | setting |
| 116 | .Fa sa_handler |
| 117 | to |
| 118 | .Dv SIG_DFL . |
| 119 | The defaults are process termination, possibly with core dump; |
| 120 | no action; stopping the process; or continuing the process. |
| 121 | See the signal list below for each signal's default action. |
| 122 | If |
| 123 | .Fa sa_handler |
| 124 | is |
| 125 | .Dv SIG_IGN |
| 126 | current and pending instances |
| 127 | of the signal are ignored and discarded. |
| 128 | .Pp |
| 129 | Options may be specified by setting |
| 130 | .Em sa_flags . |
| 131 | If the |
| 132 | .Dv SA_NOCLDSTOP |
| 133 | bit is set when installing a catching function |
| 134 | for the |
| 135 | .Dv SIGCHLD |
| 136 | signal, |
| 137 | the |
| 138 | .Dv SIGCHLD |
| 139 | signal will be generated only when a child process exits, |
| 140 | not when a child process stops. |
| 141 | Further, if the |
| 142 | .Dv SA_ONSTACK |
| 143 | bit is set in |
| 144 | .Em sa_flags , |
| 145 | the system will deliver the signal to the process on a |
| 146 | .Em "signal stack" , |
| 147 | specified with |
| 148 | .Xr sigstack 2 . |
| 149 | .Pp |
| 150 | If a signal is caught during the system calls listed below, |
| 151 | the call may be forced to terminate |
| 152 | with the error |
| 153 | .Dv EINTR , |
| 154 | or the call may be restarted. |
| 155 | Restart of pending calls is requested |
| 156 | by setting the |
| 157 | .Dv SA_RESTART |
| 158 | bit in |
| 159 | .Ar sa_flags . |
| 160 | The affected system calls include |
| 161 | .Xr read 2 , |
| 162 | .Xr write 2 , |
| 163 | .Xr sendto 2 , |
| 164 | .Xr recvfrom 2 , |
| 165 | .Xr sendmsg 2 |
| 166 | and |
| 167 | .Xr recvmsg 2 |
| 168 | on a communications channel or a slow device (such as a terminal, |
| 169 | but not a regular file) |
| 170 | and during a |
| 171 | .Xr wait 2 |
| 172 | or |
| 173 | .Xr ioctl 2 . |
| 174 | However, calls that have already committed are not restarted, |
| 175 | but instead return a partial success (for example, a short read count). |
| 176 | .Pp |
| 177 | After a |
| 178 | .Xr fork 2 |
| 179 | or |
| 180 | .Xr vfork 2 |
| 181 | all signals, the signal mask, the signal stack, |
| 182 | and the restart/interrupt flags are inherited by the child. |
| 183 | .Pp |
| 184 | .Xr Execve 2 |
| 185 | reinstates the default |
| 186 | action for all signals which were caught and |
| 187 | resets all signals to be caught on the user stack. |
| 188 | Ignored signals remain ignored; |
| 189 | the signal mask remains the same; |
| 190 | signals that restart pending system calls continue to do so. |
| 191 | .Pp |
| 192 | The following is a list of all signals |
| 193 | with names as in the include file |
| 194 | .Aq Pa signal.h : |
| 195 | .Bl -column SIGVTALARMXX "create core imagexxx" |
| 196 | .It Sy " NAME " " Default Action " " Description" |
| 197 | .It Dv SIGHUP No " terminate process" " terminal line hangup" |
| 198 | .It Dv SIGINT No " terminate process" " interrupt program" |
| 199 | .It Dv SIGQUIT No " create core image" " quit program" |
| 200 | .It Dv SIGILL No " create core image" " illegal instruction" |
| 201 | .It Dv SIGTRAP No " create core image" " trace trap" |
| 202 | .It Dv SIGABRT No " create core image" Xr abort 2 |
| 203 | call (formerly |
| 204 | .Dv SIGIOT ) |
| 205 | .It Dv SIGEMT No " create core image" " emulate instruction executed" |
| 206 | .It Dv SIGFPE No " create core image" " floating-point exception" |
| 207 | .It Dv SIGKILL No " terminate process" " kill program" |
| 208 | .It Dv SIGBUS No " create core image" " bus error" |
| 209 | .It Dv SIGSEGV No " create core image" " segmentation violation" |
| 210 | .It Dv SIGSYS No " create core image" " system call given invalid argument" |
| 211 | .It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" |
| 212 | .It Dv SIGALRM No " terminate process" " real-time timer expired" |
| 213 | .It Dv SIGTERM No " terminate process" " software termination signal" |
| 214 | .It Dv SIGURG No " discard signal" " urgent condition present on socket" |
| 215 | .It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" |
| 216 | .It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" |
| 217 | .It Dv SIGCONT No " discard signal" " continue after stop" |
| 218 | .It Dv SIGCHLD No " discard signal" " child status has changed" |
| 219 | .It Dv SIGTTIN No " stop process" " background read attempted from control terminal" |
| 220 | .It Dv SIGTTOU No " stop process" " background write attempted to control terminal" |
| 221 | .It Dv SIGIO No " discard signal" Tn " I/O" |
| 222 | is possible on a descriptor (see |
| 223 | .Xr fcntl 2 ) |
| 224 | .It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" |
| 225 | .Xr setrlimit 2 ) |
| 226 | .It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" |
| 227 | .Xr setrlimit 2 ) |
| 228 | .It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" |
| 229 | .Xr setitimer 2 ) |
| 230 | .It Dv SIGPROF No " terminate process" " profiling timer alarm (see" |
| 231 | .Xr setitimer 2 ) |
| 232 | .It Dv SIGWINCH No " discard signal" " Window size change" |
| 233 | .It Dv SIGINFO No " discard signal" " status request from keyboard" |
| 234 | .It Dv SIGUSR1 No " terminate process" " User defined signal 1" |
| 235 | .It Dv SIGUSR2 No " terminate process" " User defined signal 2" |
| 236 | .El |
| 237 | .Sh NOTE |
| 238 | The mask specified in |
| 239 | .Fa act |
| 240 | is not allowed to block |
| 241 | .Dv SIGKILL |
| 242 | or |
| 243 | .Dv SIGSTOP |
| 244 | This is done silently by the system. |
| 245 | .Sh RETURN VALUES |
| 246 | A 0 value indicated that the call succeeded. A \-1 return value |
| 247 | indicates an error occurred and |
| 248 | .Va errno |
| 249 | is set to indicated the reason. |
| 250 | .Sh ERROR |
| 251 | .Fn Sigaction |
| 252 | will fail and no new signal handler will be installed if one |
| 253 | of the following occurs: |
| 254 | .Tw Er |
| 255 | .Tl Bq Er EFAULT |
| 256 | Either |
| 257 | .Fa act |
| 258 | or |
| 259 | .Fa oact |
| 260 | points to memory that is not a valid part of the process |
| 261 | address space. |
| 262 | .Tl Bq Er EINVAL |
| 263 | .Fa Sig |
| 264 | is not a valid signal number. |
| 265 | .Tl Bq Er EINVAL |
| 266 | An attempt is made to ignore or supply a handler for |
| 267 | .Em SIGKIL |
| 268 | or |
| 269 | .Dv SIGSTOP |
| 270 | .Tl |
| 271 | .Sh STANDARD |
| 272 | The |
| 273 | .Nm sigaction |
| 274 | function is defined by |
| 275 | .St -p1003.1-88 . |
| 276 | The |
| 277 | .Dv SA_ONSTACK |
| 278 | and |
| 279 | .Dv SA_RESTART |
| 280 | flags are Berkeley extensions, |
| 281 | as are the signals, |
| 282 | .Dv SIGTRAP , |
| 283 | .Dv SIGEMT , |
| 284 | .Dv SIGBUS , |
| 285 | .Dv SIGSYS , |
| 286 | .Dv SIGURG , |
| 287 | .Dv SIGIO , |
| 288 | .Dv SIGXCPU , |
| 289 | .Dv SIGXFSZ , |
| 290 | .Dv SIGVTALRM , |
| 291 | .Dv SIGPROF , |
| 292 | .Dv SIGWINCH , |
| 293 | and |
| 294 | .Dv SIGINFO . |
| 295 | Most of those signals are available on most |
| 296 | .Tn BSD Ns \-derived |
| 297 | systems. |
| 298 | .Sh SEE ALSO |
| 299 | .Xr kill 1 , |
| 300 | .Xr ptrace 2 , |
| 301 | .Xr kill 2 , |
| 302 | .Xr sigaction 2 , |
| 303 | .Xr sigprocmask 2 , |
| 304 | .Em sigsetops 2 , |
| 305 | .Xr sigsuspend 2 , |
| 306 | .Xr sigblock 2 , |
| 307 | .Xr sigsetmask 2 , |
| 308 | .Xr sigpause 2 , |
| 309 | .Xr sigstack 2 , |
| 310 | .Xr sigvec 2 , |
| 311 | .Xr setjmp 3 , |
| 312 | .Em siginterrupt 3 , |
| 313 | .Xr tty 4 |
| 314 | .Sh EXAMPLE |
| 315 | On a |
| 316 | .Tn VAX\-11, |
| 317 | the handler routine can be declared: |
| 318 | .Bd -literal -offset indent |
| 319 | void handler(sig, code, scp) |
| 320 | int sig, code; |
| 321 | struct sigcontext *scp; |
| 322 | .Ed |
| 323 | .Pp |
| 324 | Here |
| 325 | .Fa sig |
| 326 | is the signal number, into which the hardware faults and traps are |
| 327 | mapped as defined below. |
| 328 | .Em Code |
| 329 | is a parameter that is either a constant |
| 330 | as given below or the code provided by |
| 331 | the hardware (Compatibility mode faults are distinguished from the |
| 332 | other |
| 333 | .Dv SIGILL |
| 334 | traps by having |
| 335 | .Dv PSL_CM |
| 336 | set in the psl). |
| 337 | .Fa Scp |
| 338 | is a pointer to the |
| 339 | .Fa sigcontext |
| 340 | structure (defined in |
| 341 | .Aq Pa signal.h ) , |
| 342 | used to restore the context from before the signal. |