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
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 */
53 .Fa "const struct sigaction * restrict act"
54 .Fa "struct sigaction * restrict oact"
57 The system defines a set of signals that may be delivered to a process.
58 Signal delivery resembles the occurrence of a hardware interrupt:
59 the signal is normally blocked from further occurrence, the current thread
60 context is saved, and a new one is built.
61 A process may specify a
63 to which a signal is delivered, or specify that a signal is to be
65 A process may also specify that a default action is to be taken
66 by the system when a signal occurs.
70 in which case it will not be delivered to that thread until it is
72 The action to be taken on delivery is determined at the time
74 Normally, signal handlers execute on the current stack
76 This may be changed, on a per-handler basis,
77 so that signals are taken on a special
80 Signal routines normally execute with the signal that caused their
83 but other signals may yet occur.
86 defines the set of signals currently blocked from delivery
88 The signal mask for a thread is initialized
89 from that of its parent (normally empty).
90 It may be changed with a
94 call, or when a signal is delivered to the thread.
97 condition arises for a process or thread, the signal is added to a set of
98 signals pending for the process or thread.
99 Whether the signal is directed at the process in general or at a specific
100 thread depends on how it is generated.
101 For signals directed at a specific thread,
102 if the signal is not currently
104 by the thread then it is delivered to the thread.
105 For signals directed at the process,
106 if the signal is not currently
108 by all threads then it is delivered to one thread that does not have it blocked
109 (the selection of which is unspecified).
110 Signals may be delivered any time a thread enters the operating system
111 (e.g., during a system call, page fault or trap, or clock interrupt).
112 If multiple signals are ready to be delivered at the same time,
113 any signals that could be caused by traps are delivered first.
114 Additional signals may be processed at the same time, with each
115 appearing to interrupt the handlers for the previous signals
116 before their first instructions.
117 The set of pending signals is returned by the
121 is delivered, the current state of the thread is saved,
122 a new signal mask is calculated (as described below),
123 and the signal handler is invoked.
124 The call to the handler
125 is arranged so that if the signal handling routine returns
126 normally the thread will resume execution in the context
127 from before the signal's delivery.
128 If the thread wishes to resume in a different context, then it
129 must arrange to restore the previous context itself.
131 When a signal is delivered to a thread a new signal mask is
132 installed for the duration of the process' signal handler
135 system call is made).
136 This mask is formed by taking the union of the current signal mask set,
137 the signal to be delivered, and
138 the signal mask associated with the handler to be invoked.
143 assigns an action for a signal specified by
147 is non-NULL, it specifies an action
150 or a handler routine) and mask to be used when delivering the specified signal.
153 is non-NULL, the previous handling information for the signal
154 is returned to the user.
156 The above declaration of
157 .Vt "struct sigaction"
159 It is provided only to list the accessible members.
162 for the actual definition.
163 In particular, the storage occupied by
167 overlaps, and it is nonsensical for an application to attempt to use both
170 Once a signal handler is installed, it normally remains installed
173 system call is made, or an
176 A signal-specific default action may be reset by
181 The defaults are process termination, possibly with core dump;
182 no action; stopping the process; or continuing the process.
183 See the signal list below for each signal's default action.
188 the default action for the signal is to discard the signal,
189 and if a signal is pending,
190 the pending signal is discarded even if the signal is masked.
195 current and pending instances
196 of the signal are ignored and discarded.
198 Options may be specified by setting
200 The meaning of the various bits is as follows:
201 .Bl -tag -offset indent -width SA_RESETHANDXX
203 If this bit is set when installing a catching function
209 signal will be generated only when a child process exits,
210 not when a child process stops.
212 If this bit is set when calling
216 signal, the system will not create zombie processes when children of
217 the calling process exit.
218 If the calling process subsequently issues a
220 (or equivalent), it blocks until all of the calling process's child
221 processes terminate, and then returns a value of \-1 with
225 The same effect of avoiding zombie creation can also be achieved by setting
232 If this bit is set, the system will deliver the signal to the process
235 specified by each thread with
238 If this bit is set, further occurrences of the delivered signal are
239 not masked during the execution of the handler.
241 If this bit is set, the handler is reset back to
243 at the moment the signal is delivered.
247 If this bit is set, the handler function is assumed to be pointed to by the
250 .Vt "struct sigaction"
251 and should match the prototype shown above or as below in
253 This bit should not be set when assigning
259 If a signal is caught during the system calls listed below,
260 the call may be forced to terminate
263 the call may return with a data transfer shorter than requested,
264 or the call may be restarted.
265 Restart of pending calls is requested
270 The affected system calls include
279 on a communications channel or a slow device (such as a terminal,
280 but not a regular file)
285 However, calls that have already committed are not restarted,
286 but instead return a partial success (for example, a short read count).
290 the signal mask is inherited by the new thread and
291 the set of pending signals and the signal stack for the new thread are empty.
297 all signals, the signal mask, the signal stack,
298 and the restart/interrupt flags are inherited by the child.
302 system call reinstates the default
303 action for all signals which were caught and
304 resets all signals to be caught on the user stack.
305 Ignored signals remain ignored;
306 the signal mask remains the same;
307 signals that restart pending system calls continue to do so.
309 The following is a list of all signals
310 with names as in the include file
312 .Bl -column SIGVTALARMXX "create core imagexxx"
313 .It Sy NAME Ta Sy Default Action Ta Sy Description
314 .It Dv SIGHUP Ta terminate process Ta terminal line hangup
315 .It Dv SIGINT Ta terminate process Ta interrupt program
316 .It Dv SIGQUIT Ta create core image Ta quit program
317 .It Dv SIGILL Ta create core image Ta illegal instruction
318 .It Dv SIGTRAP Ta create core image Ta trace trap
319 .It Dv SIGABRT Ta create core image Ta Xr abort 3 call (formerly Dv SIGIOT )
320 .It Dv SIGEMT Ta create core image Ta emulate instruction executed
321 .It Dv SIGFPE Ta create core image Ta floating-point exception
322 .It Dv SIGKILL Ta terminate process Ta kill program
323 .It Dv SIGBUS Ta create core image Ta bus error
324 .It Dv SIGSEGV Ta create core image Ta segmentation violation
325 .It Dv SIGSYS Ta create core image Ta non-existent system call invoked
326 .It Dv SIGPIPE Ta terminate process Ta write on a pipe with no reader
327 .It Dv SIGALRM Ta terminate process Ta real-time timer expired
328 .It Dv SIGTERM Ta terminate process Ta software termination signal
329 .It Dv SIGURG Ta discard signal Ta urgent condition present on socket
330 .It Dv SIGSTOP Ta stop process Ta stop (cannot be caught or ignored)
331 .It Dv SIGTSTP Ta stop process Ta stop signal generated from keyboard
332 .It Dv SIGCONT Ta discard signal Ta continue after stop
333 .It Dv SIGCHLD Ta discard signal Ta child status has changed
334 .It Dv SIGTTIN Ta stop process Ta background read attempted from control terminal
335 .It Dv SIGTTOU Ta stop process Ta background write attempted to control terminal
336 .It Dv SIGIO Ta discard signal Ta I/O is possible on a descriptor (see Xr fcntl 2 )
337 .It Dv SIGXCPU Ta terminate process Ta cpu time limit exceeded (see Xr setrlimit 2 )
338 .It Dv SIGXFSZ Ta terminate process Ta file size limit exceeded (see Xr setrlimit 2 )
339 .It Dv SIGVTALRM Ta terminate process Ta virtual time alarm (see Xr setitimer 2 )
340 .It Dv SIGPROF Ta terminate process Ta profiling timer alarm (see Xr setitimer 2 )
341 .It Dv SIGWINCH Ta discard signal Ta window size change
342 .It Dv SIGINFO Ta discard signal Ta status request from keyboard
343 .It Dv SIGUSR1 Ta terminate process Ta user defined signal 1
344 .It Dv SIGUSR2 Ta terminate process Ta user defined signal 2
351 is not allowed to block
355 Any attempt to do so will be silently ignored.
357 The following functions are either reentrant or not interruptible
358 by signals and are async-signal safe.
359 Therefore applications may
360 invoke them, without restriction, from signal-catching functions
361 or from a child process after calling
363 in a multi-threaded process:
430 .Fn pthread_sigmask ,
487 X/Open Systems Interfaces:
497 .Fn timer_getoverrun ,
506 Base Interfaces not specified as async-signal safe by
513 Base Interfaces not specified as async-signal safe by
568 Extension Interfaces:
588 In addition, reading or writing
590 is async-signal safe.
592 All functions not in the above lists are considered to be unsafe
593 with respect to signals.
594 That is to say, the behaviour of such
595 functions is undefined when they are called from a signal handler
596 that interrupted an unsafe function.
597 In general though, signal handlers should do little more than set a
598 flag; most other actions are not safe.
600 Also, it is good practice to make a copy of the global variable
602 and restore it before returning from the signal handler.
603 This protects against the side effect of
605 being set by functions called from inside the signal handler.
609 There are three possible prototypes the handler may match:
610 .Bl -tag -offset indent -width short
614 .It Traditional BSD style:
616 .Fn handler int "int code" "struct sigcontext *scp" ;
617 .It Tn POSIX Dv SA_SIGINFO :
619 .Fn handler int "siginfo_t *info" "ucontext_t *uap" ;
622 The handler function should match the
628 It then should be pointed to by the
631 .Vt "struct sigaction" .
632 Note that you should not assign
640 flag is not set, the handler function should match
645 prototype and be pointed to by
649 .Vt "struct sigaction" .
652 always sends the three arguments of the latter and since the
654 prototype is a subset, both will work.
657 member declaration in
659 include files is that of
663 so a function pointer of a
665 function needs to be casted to
666 compile without warning.
669 style is not portable and since its capabilities
670 are a full subset of a
673 its use is deprecated.
677 argument is the signal number, one of the
692 handler contain a numeric code explaining the
693 cause of the signal, usually one of the
697 or codes specific to a signal, i.e., one of the
706 handler points to an instance of
707 .Vt "struct sigcontext" .
714 handler points to an instance of
720 will fail and no new signal handler will be installed if one
721 of the following occurs:
727 is not a valid signal number.
729 An attempt is made to ignore or supply a handler for
755 system call is expected to conform to
761 flags are Berkeley extensions,
776 Those signals are available on most
783 flags are intended for backwards compatibility with other operating
791 flags are featuring options commonly found in other operating systems.
792 The flags are approved by
794 along with the option to avoid zombie creation by ignoring