1 .\" Copyright (c) 1980, 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" From: @(#)sigaction.2 8.2 (Berkeley) 4/3/94
29 .\" $FreeBSD: src/lib/libc/sys/sigaction.2,v 1.22.2.10 2002/12/29 16:35:34 schweikh Exp $
36 .Nd software signal facilities
43 void (*sa_handler)(int);
44 void (*sa_sigaction)(int, siginfo_t *, void *);
45 int sa_flags; /* see signal options below */
46 sigset_t sa_mask; /* signal mask to apply */
52 .Fa "const struct sigaction * restrict act"
53 .Fa "struct sigaction * restrict oact"
56 The system defines a set of signals that may be delivered to a process.
57 Signal delivery resembles the occurrence of a hardware interrupt:
58 the signal is normally blocked from further occurrence, the current thread
59 context is saved, and a new one is built.
60 A process may specify a
62 to which a signal is delivered, or specify that a signal is to be
64 A process may also specify that a default action is to be taken
65 by the system when a signal occurs.
69 in which case it will not be delivered to that thread until it is
71 The action to be taken on delivery is determined at the time
73 Normally, signal handlers execute on the current stack
75 This may be changed, on a per-handler basis,
76 so that signals are taken on a special
79 Signal routines normally execute with the signal that caused their
82 but other signals may yet occur.
85 defines the set of signals currently blocked from delivery
87 The signal mask for a thread is initialized
88 from that of its parent (normally empty).
89 It may be changed with a
93 call, or when a signal is delivered to the thread.
96 condition arises for a process or thread, the signal is added to a set of
97 signals pending for the process or thread.
98 Whether the signal is directed at the process in general or at a specific
99 thread depends on how it is generated.
100 For signals directed at a specific thread,
101 if the signal is not currently
103 by the thread then it is delivered to the thread.
104 For signals directed at the process,
105 if the signal is not currently
107 by all threads then it is delivered to one thread that does not have it blocked
108 (the selection of which is unspecified).
109 Signals may be delivered any time a thread enters the operating system
110 (e.g., during a system call, page fault or trap, or clock interrupt).
111 If multiple signals are ready to be delivered at the same time,
112 any signals that could be caused by traps are delivered first.
113 Additional signals may be processed at the same time, with each
114 appearing to interrupt the handlers for the previous signals
115 before their first instructions.
116 The set of pending signals is returned by the
120 is delivered, the current state of the thread is saved,
121 a new signal mask is calculated (as described below),
122 and the signal handler is invoked.
123 The call to the handler
124 is arranged so that if the signal handling routine returns
125 normally the thread will resume execution in the context
126 from before the signal's delivery.
127 If the thread wishes to resume in a different context, then it
128 must arrange to restore the previous context itself.
130 When a signal is delivered to a thread a new signal mask is
131 installed for the duration of the process' signal handler
134 system call is made).
135 This mask is formed by taking the union of the current signal mask set,
136 the signal to be delivered, and
137 the signal mask associated with the handler to be invoked.
142 assigns an action for a signal specified by
150 or a handler routine) and mask
151 to be used when delivering the specified signal.
154 is non-zero, the previous handling information for the signal
155 is returned to the user.
157 The above declaration of
158 .Vt "struct sigaction"
160 It is provided only to list the accessible members.
163 for the actual definition.
164 In particular, the storage occupied by sa_handler and sa_sigaction overlaps,
165 and an application can not use both simultaneously.
167 Once a signal handler is installed, it normally remains installed
170 system call is made, or an
173 A signal-specific default action may be reset by
178 The defaults are process termination, possibly with core dump;
179 no action; stopping the process; or continuing the process.
180 See the signal list below for each signal's default action.
185 the default action for the signal is to discard the signal,
186 and if a signal is pending,
187 the pending signal is discarded even if the signal is masked.
192 current and pending instances
193 of the signal are ignored and discarded.
195 Options may be specified by setting
197 The meaning of the various bits is as follows:
198 .Bl -tag -offset indent -width SA_RESETHANDXX
200 If this bit is set when installing a catching function
206 signal will be generated only when a child process exits,
207 not when a child process stops.
209 If this bit is set when calling
213 signal, the system will not create zombie processes when children of
214 the calling process exit.
215 If the calling process subsequently issues a
217 (or equivalent), it blocks until all of the calling process's child
218 processes terminate, and then returns a value of \-1 with
222 The same effect of avoiding zombie creation can also be achieved by setting
229 If this bit is set, the system will deliver the signal to the process
232 specified by each thread with
235 If this bit is set, further occurrences of the delivered signal are
236 not masked during the execution of the handler.
238 If this bit is set, the handler is reset back to
240 at the moment the signal is delivered.
244 If this bit is set, the handler function is assumed to be pointed to by the
247 .Vt "struct sigaction"
248 and should match the prototype shown above or as below in
250 This bit should not be set when assigning
256 If a signal is caught during the system calls listed below,
257 the call may be forced to terminate
260 the call may return with a data transfer shorter than requested,
261 or the call may be restarted.
262 Restart of pending calls is requested
267 The affected system calls include
276 on a communications channel or a slow device (such as a terminal,
277 but not a regular file)
282 However, calls that have already committed are not restarted,
283 but instead return a partial success (for example, a short read count).
287 the signal mask is inherited by the new thread and
288 the set of pending signals and the signal stack for the new thread are empty.
294 all signals, the signal mask, the signal stack,
295 and the restart/interrupt flags are inherited by the child.
299 system call reinstates the default
300 action for all signals which were caught and
301 resets all signals to be caught on the user stack.
302 Ignored signals remain ignored;
303 the signal mask remains the same;
304 signals that restart pending system calls continue to do so.
306 The following is a list of all signals
307 with names as in the include file
309 .Bl -column SIGVTALARMXX "create core imagexxx"
310 .It Sy "NAME Default Action Description"
311 .It Dv SIGHUP No " terminate process" " terminal line hangup"
312 .It Dv SIGINT No " terminate process" " interrupt program"
313 .It Dv SIGQUIT No " create core image" " quit program"
314 .It Dv SIGILL No " create core image" " illegal instruction"
315 .It Dv SIGTRAP No " create core image" " trace trap"
316 .It Dv SIGABRT No " create core image" Ta Xr abort 3
319 .It Dv SIGEMT No " create core image" " emulate instruction executed"
320 .It Dv SIGFPE No " create core image" " floating-point exception"
321 .It Dv SIGKILL No " terminate process" " kill program"
322 .It Dv SIGBUS No " create core image" " bus error"
323 .It Dv SIGSEGV No " create core image" " segmentation violation"
324 .It Dv SIGSYS No " create core image" " non-existent system call invoked"
325 .It Dv SIGPIPE No " terminate process" " write on a pipe with no reader"
326 .It Dv SIGALRM No " terminate process" " real-time timer expired"
327 .It Dv SIGTERM No " terminate process" " software termination signal"
328 .It Dv SIGURG No " discard signal" " urgent condition present on socket"
329 .It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)"
330 .It Dv SIGTSTP No " stop process" " stop signal generated from keyboard"
331 .It Dv SIGCONT No " discard signal" " continue after stop"
332 .It Dv SIGCHLD No " discard signal" " child status has changed"
333 .It Dv SIGTTIN No " stop process" " background read attempted from control terminal"
334 .It Dv SIGTTOU No " stop process" " background write attempted to control terminal"
335 .It Dv SIGIO No " discard signal" Tn " I/O"
336 is possible on a descriptor (see
338 .It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see"
340 .It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see"
342 .It Dv SIGVTALRM No " terminate process" " virtual time alarm (see"
344 .It Dv SIGPROF No " terminate process" " profiling timer alarm (see"
346 .It Dv SIGWINCH No " discard signal" " Window size change"
347 .It Dv SIGINFO No " discard signal" " status request from keyboard"
348 .It Dv SIGUSR1 No " terminate process" " User defined signal 1"
349 .It Dv SIGUSR2 No " terminate process" " User defined signal 2"
356 is not allowed to block
360 Any attempt to do so will be silently ignored.
362 The following functions are either reentrant or not interruptible
363 by signals and are async-signal safe.
364 Therefore applications may
365 invoke them, without restriction, from signal-catching functions
366 or from a child process after calling
368 in a multi-threaded process:
469 .\".Fn timer_getoverrun ,
473 .\".Fn timer_gettime ,
477 .\".Fn timer_settime .
479 All functions not in the above lists are considered to be unsafe
480 with respect to signals.
481 That is to say, the behaviour of such
482 functions is undefined when they are called from a signal handler
483 that interrupted an unsafe function.
484 In general though, signal handlers should do little more than set a
485 flag; most other actions are not safe.
487 Also, it is good practice to make a copy of the global variable
489 and restore it before returning from the signal handler.
490 This protects against the side effect of
492 being set by functions called from inside the signal handler.
496 There are three possible prototypes the handler may match:
497 .Bl -tag -offset indent -width short
501 .It Traditional BSD style:
503 .Fn handler int "int code" "struct sigcontext *scp" ;
504 .It Tn POSIX Dv SA_SIGINFO :
506 .Fn handler int "siginfo_t *info" "ucontext_t *uap" ;
509 The handler function should match the
515 It then should be pointed to by the
518 .Vt "struct sigaction" .
519 Note that you should not assign
527 flag is not set, the handler function should match
532 prototype and be pointed to by
536 .Vt "struct sigaction" .
539 always sends the three arguments of the latter and since the
541 prototype is a subset, both will work.
544 member declaration in
546 include files is that of
550 so a function pointer of a
552 function needs to be cast to
553 compile without warning.
556 style is not portable and since its capabilities
557 are a full subset of a
560 its use is deprecated.
564 argument is the signal number, one of the
579 handler contain a numeric code explaining the
580 cause of the signal, usually one of the
584 or codes specific to a signal, i.e.\& one of the
593 handler points to an instance of
594 .Vt "struct sigcontext" .
601 handler points to an instance of
607 will fail and no new signal handler will be installed if one
608 of the following occurs:
615 points to memory that is not a valid part of the process
621 is not a valid signal number.
623 An attempt is made to ignore or supply a handler for
646 system call is expected to conform to
652 flags are Berkeley extensions,
667 Those signals are available on most
674 flags are intended for backwards compatibility with other operating
682 flags are featuring options commonly found in other operating systems.
683 The flags are approved by
685 along with the option to avoid zombie creation by ignoring