1SIGACTION(3P) POSIX Programmer's Manual SIGACTION(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 sigaction — examine and change a signal action
14
16 #include <signal.h>
17 int sigaction(int sig, const struct sigaction *restrict act,
19 struct sigaction *restrict oact);
20
22 The sigaction() function allows the calling process to examine and/or
23 specify the action to be associated with a specific signal. The argu‐
24 ment sig specifies the signal; acceptable values are defined in <sig‐
25 nal.h>.
26 The structure sigaction, used to describe an action to be taken, is
28 defined in the <signal.h> header to include at least the following mem‐
29 bers:
30 ┌────────────────┬───────────────┬───────────────────────────────────────┐
32 │ Member Type │ Member Name │ Description │
33 ├────────────────┼───────────────┼───────────────────────────────────────┤
34 │void(*) (int) │ sa_handler │Pointer to a signal-catching function │
35 │ │ │or one of the macros SIG_IGN or │
36 │ │ │SIG_DFL. │
37 │sigset_t │ sa_mask │Additional set of signals to be │
38 │ │ │blocked during execution of signal- │
39 │ │ │catching function. │
40 │int │ sa_flags │Special flags to affect behavior of │
41 │ │ │signal. │
42 │void(*) (int, │ sa_sigaction │Pointer to a signal-catching function. │
43 │ siginfo_t *, │ │ │
44 │void *) │ │ │
45 └────────────────┴───────────────┴───────────────────────────────────────┘
46 The storage occupied by sa_handler and sa_sigaction may overlap, and a
47 conforming application shall not use both simultaneously.
48 If the argument act is not a null pointer, it points to a structure
50 specifying the action to be associated with the specified signal. If
51 the argument oact is not a null pointer, the action previously associ‐
52 ated with the signal is stored in the location pointed to by the argu‐
53 ment oact. If the argument act is a null pointer, signal handling is
54 unchanged; thus, the call can be used to enquire about the current han‐
55 dling of a given signal. The SIGKILL and SIGSTOP signals shall not be
56 added to the signal mask using this mechanism; this restriction shall
57 be enforced by the system without causing an error to be indicated.
58 If the SA_SIGINFO flag (see below) is cleared in the sa_flags field of
60 the sigaction structure, the sa_handler field identifies the action to
61 be associated with the specified signal. If the SA_SIGINFO flag is set
62 in the sa_flags field, the sa_sigaction field specifies a signal-catch‐
63 ing function.
64 The sa_flags field can be used to modify the behavior of the specified
66 signal.
67 The following flags, defined in the <signal.h> header, can be set in
69 sa_flags:
70 SA_NOCLDSTOP Do not generate SIGCHLD when children stop or stopped
72 children continue.
73 If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in
75 sa_flags, and the implementation supports the SIGCHLD
76 signal, then a SIGCHLD signal shall be generated for the
77 calling process whenever any of its child processes stop
78 and a SIGCHLD signal may be generated for the calling
79 process whenever any of its stopped child processes are
80 continued. If sig is SIGCHLD and the SA_NOCLDSTOP flag
81 is set in sa_flags, then the implementation shall not
82 generate a SIGCHLD signal in this way.
83 SA_ONSTACK If set and an alternate signal stack has been declared
85 with sigaltstack(), the signal shall be delivered to the
86 calling process on that stack. Otherwise, the signal
87 shall be delivered on the current stack.
88 SA_RESETHAND If set, the disposition of the signal shall be reset to
90 SIG_DFL and the SA_SIGINFO flag shall be cleared on entry
91 to the signal handler.
92 Note: SIGILL and SIGTRAP cannot be automatically
94 reset when delivered; the system silently
95 enforces this restriction.
96 Otherwise, the disposition of the signal shall not be
98 modified on entry to the signal handler.
99 In addition, if this flag is set, sigaction() may behave
101 as if the SA_NODEFER flag were also set.
102 SA_RESTART This flag affects the behavior of interruptible func‐
104 tions; that is, those specified to fail with errno set to
105 [EINTR]. If set, and a function specified as interrupt‐
106 ible is interrupted by this signal, the function shall
107 restart and shall not fail with [EINTR] unless otherwise
108 specified. If an interruptible function which uses a
109 timeout is restarted, the duration of the timeout follow‐
110 ing the restart is set to an unspecified value that does
111 not exceed the original timeout value. If the flag is not
112 set, interruptible functions interrupted by this signal
113 shall fail with errno set to [EINTR].
114 SA_SIGINFO If cleared and the signal is caught, the signal-catching
116 function shall be entered as:
117 void func(int signo);
119 where signo is the only argument to the signal-catching
121 function. In this case, the application shall use the
122 sa_handler member to describe the signal-catching func‐
123 tion and the application shall not modify the sa_sigac‐
124 tion member.
125 If SA_SIGINFO is set and the signal is caught, the sig‐
127 nal-catching function shall be entered as:
128 void func(int signo, siginfo_t *info, void *context);
130 where two additional arguments are passed to the signal-
132 catching function. The second argument shall point to an
133 object of type siginfo_t explaining the reason why the
134 signal was generated; the third argument can be cast to a
135 pointer to an object of type ucontext_t to refer to the
136 receiving thread's context that was interrupted when the
137 signal was delivered. In this case, the application shall
138 use the sa_sigaction member to describe the signal-catch‐
139 ing function and the application shall not modify the
140 sa_handler member.
141 The si_signo member contains the system-generated signal
143 number.
144 The si_errno member may contain implementation-defined
146 additional error information; if non-zero, it contains an
147 error number identifying the condition that caused the
148 signal to be generated.
149 The si_code member contains a code identifying the cause
151 of the signal, as described in Section 2.4.3, Signal
152 Actions.
153 SA_NOCLDWAIT If set, and sig equals SIGCHLD, child processes of the
155 calling processes shall not be transformed into zombie
156 processes when they terminate. If the calling process
157 subsequently waits for its children, and the process has
158 no unwaited-for children that were transformed into zom‐
159 bie processes, it shall block until all of its children
160 terminate, and wait(), waitid(), and waitpid() shall fail
161 and set errno to [ECHILD]. Otherwise, terminating child
162 processes shall be transformed into zombie processes,
163 unless SIGCHLD is set to SIG_IGN.
164 SA_NODEFER If set and sig is caught, sig shall not be added to the
166 thread's signal mask on entry to the signal handler
167 unless it is included in sa_mask. Otherwise, sig shall
168 always be added to the thread's signal mask on entry to
169 the signal handler.
170 When a signal is caught by a signal-catching function installed by
172 sigaction(), a new signal mask is calculated and installed for the
173 duration of the signal-catching function (or until a call to either
174 sigprocmask() or sigsuspend() is made). This mask is formed by taking
175 the union of the current signal mask and the value of the sa_mask for
176 the signal being delivered, and unless SA_NODEFER or SA_RESETHAND is
177 set, then including the signal being delivered. If and when the user's
178 signal handler returns normally, the original signal mask is restored.
179 Once an action is installed for a specific signal, it shall remain
181 installed until another action is explicitly requested (by another call
182 to sigaction()), until the SA_RESETHAND flag causes resetting of the
183 handler, or until one of the exec functions is called.
184 If the previous action for sig had been established by signal(), the
186 values of the fields returned in the structure pointed to by oact are
187 unspecified, and in particular oact->sa_handler is not necessarily the
188 same value passed to signal(). However, if a pointer to the same
189 structure or a copy thereof is passed to a subsequent call to sigac‐
190 tion() via the act argument, handling of the signal shall be as if the
191 original call to signal() were repeated.
192 If sigaction() fails, no new signal handler is installed.
194 It is unspecified whether an attempt to set the action for a signal
196 that cannot be caught or ignored to SIG_DFL is ignored or causes an
197 error to be returned with errno set to [EINVAL].
198 If SA_SIGINFO is not set in sa_flags, then the disposition of subse‐
200 quent occurrences of sig when it is already pending is implementation-
201 defined; the signal-catching function shall be invoked with a single
202 argument. If SA_SIGINFO is set in sa_flags, then subsequent occur‐
203 rences of sig generated by sigqueue() or as a result of any signal-gen‐
204 erating function that supports the specification of an application-
205 defined value (when sig is already pending) shall be queued in FIFO
206 order until delivered or accepted; the signal-catching function shall
207 be invoked with three arguments. The application specified value is
208 passed to the signal-catching function as the si_value member of the
209 siginfo_t structure.
210 The result of the use of sigaction() and a sigwait() function concur‐
212 rently within a process on the same signal is unspecified.
213
215 Upon successful completion, sigaction() shall return 0; otherwise, −1
216 shall be returned, errno shall be set to indicate the error, and no new
217 signal-catching function shall be installed.
218
220 The sigaction() function shall fail if:
221 EINVAL The sig argument is not a valid signal number or an attempt is
223 made to catch a signal that cannot be caught or ignore a signal
224 that cannot be ignored.
225 ENOTSUP
227 The SA_SIGINFO bit flag is set in the sa_flags field of the
228 sigaction structure.
229 The sigaction() function may fail if:
231 EINVAL An attempt was made to set the action to SIG_DFL for a signal
233 that cannot be caught or ignored (or both).
234 In addition, the sigaction() function may fail if the SA_SIGINFO flag
236 is set in the sa_flags field of the sigaction structure for a signal
237 not in the range SIGRTMIN to SIGRTMAX.
238 The following sections are informative.
240
242 Establishing a Signal Handler
243 The following example demonstrates the use of sigaction() to establish
244 a handler for the SIGINT signal.
245 #include <signal.h>
247 static void handler(int signum)
249 {
250 /* Take appropriate actions for signal delivery */
251 }
252 int main()
254 {
255 struct sigaction sa;
256 sa.sa_handler = handler;
258 sigemptyset(&sa.sa_mask);
259 sa.sa_flags = SA_RESTART; /* Restart functions if
260 interrupted by handler */
261 if (sigaction(SIGINT, &sa, NULL) == −1)
262 /* Handle error */;
263 /* Further code */
265 }
266
268 The sigaction() function supersedes the signal() function, and should
269 be used in preference. In particular, sigaction() and signal() should
270 not be used in the same process to control the same signal. The behav‐
271 ior of async-signal-safe functions, as defined in their respective
272 DESCRIPTION sections, is as specified by this volume of POSIX.1‐2008,
273 regardless of invocation from a signal-catching function. This is the
274 only intended meaning of the statement that async-signal-safe functions
275 may be used in signal-catching functions without restrictions. Applica‐
276 tions must still consider all effects of such functions on such things
277 as data structures, files, and process state. In particular, applica‐
278 tion developers need to consider the restrictions on interactions when
279 interrupting sleep() and interactions among multiple handles for a file
280 description. The fact that any specific function is listed as async-
281 signal-safe does not necessarily mean that invocation of that function
282 from a signal-catching function is recommended.
283 In order to prevent errors arising from interrupting non-async-signal-
285 safe function calls, applications should protect calls to these func‐
286 tions either by blocking the appropriate signals or through the use of
287 some programmatic semaphore (see semget(), sem_init(), sem_open(), and
288 so on). Note in particular that even the ``safe'' functions may modify
289 errno; the signal-catching function, if not executing as an independent
290 thread, should save and restore its value in order to avoid the possi‐
291 bility that delivery of a signal in between an error return from a
292 function that sets errno and the subsequent examination of errno could
293 result in the signal-catching function changing the value of errno.
294 Naturally, the same principles apply to the async-signal-safety of
295 application routines and asynchronous data access. Note that longjmp()
296 and siglongjmp() are not in the list of async-signal-safe functions.
297 This is because the code executing after longjmp() and siglongjmp() can
298 call any unsafe functions with the same danger as calling those unsafe
299 functions directly from the signal handler. Applications that use
300 longjmp() and siglongjmp() from within signal handlers require rigorous
301 protection in order to be portable. Many of the other functions that
302 are excluded from the list are traditionally implemented using either
303 malloc() or free() functions or the standard I/O library, both of which
304 traditionally use data structures in a non-async-signal-safe manner.
305 Since any combination of different functions using a common data struc‐
306 ture can cause async-signal-safety problems, this volume of
307 POSIX.1‐2008 does not define the behavior when any unsafe function is
308 called in a signal handler that interrupts an unsafe function.
309 Usually, the signal is executed on the stack that was in effect before
311 the signal was delivered. An alternate stack may be specified to
312 receive a subset of the signals being caught.
313 When the signal handler returns, the receiving thread resumes execution
315 at the point it was interrupted unless the signal handler makes other
316 arrangements. If longjmp() or _longjmp() is used to leave the signal
317 handler, then the signal mask must be explicitly restored.
318 This volume of POSIX.1‐2008 defines the third argument of a signal han‐
320 dling function when SA_SIGINFO is set as a void * instead of a ucon‐
321 text_t *, but without requiring type checking. New applications should
322 explicitly cast the third argument of the signal handling function to
323 ucontext_t *.
324 The BSD optional four argument signal handling function is not sup‐
326 ported by this volume of POSIX.1‐2008. The BSD declaration would be:
327 void handler(int sig, int code, struct sigcontext *scp,
329 char *addr);
330 where sig is the signal number, code is additional information on cer‐
332 tain signals, scp is a pointer to the sigcontext structure, and addr is
333 additional address information. Much the same information is available
334 in the objects pointed to by the second argument of the signal handler
335 specified when SA_SIGINFO is set.
336 Since the sigaction() function is allowed but not required to set
338 SA_NODEFER when the application sets the SA_RESETHAND flag, applica‐
339 tions which depend on the SA_RESETHAND functionality for the newly
340 installed signal handler must always explicitly set SA_NODEFER when
341 they set SA_RESETHAND in order to be portable.
342 See also the rationale for Realtime Signal Generation and Delivery in
344 the Rationale (Informative) volume of POSIX.1‐2008, Section B.2.4.2,
345 Signal Generation and Delivery.
346
348 Although this volume of POSIX.1‐2008 requires that signals that cannot
349 be ignored shall not be added to the signal mask when a signal-catching
350 function is entered, there is no explicit requirement that subsequent
351 calls to sigaction() reflect this in the information returned in the
352 oact argument. In other words, if SIGKILL is included in the sa_mask
353 field of act, it is unspecified whether or not a subsequent call to
354 sigaction() returns with SIGKILL included in the sa_mask field of oact.
355 The SA_NOCLDSTOP flag, when supplied in the act->sa_flags parameter,
357 allows overloading SIGCHLD with the System V semantics that each SIGCLD
358 signal indicates a single terminated child. Most conforming applica‐
359 tions that catch SIGCHLD are expected to install signal-catching func‐
360 tions that repeatedly call the waitpid() function with the WNOHANG flag
361 set, acting on each child for which status is returned, until waitpid()
362 returns zero. If stopped children are not of interest, the use of the
363 SA_NOCLDSTOP flag can prevent the overhead from invoking the signal-
364 catching routine when they stop.
365 Some historical implementations also define other mechanisms for stop‐
367 ping processes, such as the ptrace() function. These implementations
368 usually do not generate a SIGCHLD signal when processes stop due to
369 this mechanism; however, that is beyond the scope of this volume of
370 POSIX.1‐2008.
371 This volume of POSIX.1‐2008 requires that calls to sigaction() that
373 supply a NULL act argument succeed, even in the case of signals that
374 cannot be caught or ignored (that is, SIGKILL or SIGSTOP). The System
375 V signal() and BSD sigvec() functions return [EINVAL] in these cases
376 and, in this respect, their behavior varies from sigaction().
377 This volume of POSIX.1‐2008 requires that sigaction() properly save and
379 restore a signal action set up by the ISO C standard signal() function.
380 However, there is no guarantee that the reverse is true, nor could
381 there be given the greater amount of information conveyed by the sigac‐
382 tion structure. Because of this, applications should avoid using both
383 functions for the same signal in the same process. Since this cannot
384 always be avoided in case of general-purpose library routines, they
385 should always be implemented with sigaction().
386 It was intended that the signal() function should be implementable as a
388 library routine using sigaction().
389 The POSIX Realtime Extension extends the sigaction() function as speci‐
391 fied by the POSIX.1‐1990 standard to allow the application to request
392 on a per-signal basis via an additional signal action flag that the
393 extra parameters, including the application-defined signal value, if
394 any, be passed to the signal-catching function.
395
397 None.
398
400 Section 2.4, Signal Concepts, exec, kill(), _longjmp(), longjmp(),
401 pthread_sigmask(), raise(), semget(), sem_init(), sem_open(),
402 sigaddset(), sigaltstack(), sigdelset(), sigemptyset(), sigfillset(),
403 sigismember(), signal(), sigsuspend(), wait(), waitid()
404 The Base Definitions volume of POSIX.1‐2008, <signal.h>
406
408 Portions of this text are reprinted and reproduced in electronic form
409 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
410 -- Portable Operating System Interface (POSIX), The Open Group Base
411 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
412 cal and Electronics Engineers, Inc and The Open Group. (This is
413 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
414 event of any discrepancy between this version and the original IEEE and
415 The Open Group Standard, the original IEEE and The Open Group Standard
416 is the referee document. The original Standard can be obtained online
417 at http://www.unix.org/online.html .
418 Any typographical or formatting errors that appear in this page are
420 most likely to have been introduced during the conversion of the source
421 files to man page format. To report such errors, see https://www.ker‐
422 nel.org/doc/man-pages/reporting_bugs.html .
423IEEE/The Open Group 2013 SIGACTION(3P)