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
12 sigaction - examine and change a signal action
13
15 #include <signal.h>
16 int sigaction(int sig, const struct sigaction *restrict act,
18 struct sigaction *restrict oact);
19
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 Member Type Member Name Description
32 void(*) (int) sa_handler Pointer to a signal-catching
33 function or one of the macros
34 SIG_IGN or SIG_DFL.
35 sigset_t sa_mask Additional set of signals to
36 be blocked during execution of
37 signal-catching function.
38 int sa_flags Special flags to affect behav‐
39 ior of signal.
40 void(*) (int,
41 siginfo_t *, sa_sigaction Pointer to a signal-catching
42 void *) function.
43 The storage occupied by sa_handler and sa_sigaction may overlap, and a
45 conforming application shall not use both simultaneously.
46 If the argument act is not a null pointer, it points to a structure
48 specifying the action to be associated with the specified signal. If
49 the argument oact is not a null pointer, the action previously associ‐
50 ated with the signal is stored in the location pointed to by the argu‐
51 ment oact. If the argument act is a null pointer, signal handling is
52 unchanged; thus, the call can be used to enquire about the current han‐
53 dling of a given signal. The SIGKILL and SIGSTOP signals shall not be
54 added to the signal mask using this mechanism; this restriction shall
55 be enforced by the system without causing an error to be indicated.
56 If the SA_SIGINFO flag (see below) is cleared in the sa_flags field of
58 the sigaction structure, the sa_handler field identifies the action to
59 be associated with the specified signal. If the SA_SIGINFO flag is set
60 in the sa_flags field, and the implementation supports the Realtime
61 Signals Extension option or the XSI Extension option, the sa_sigaction
62 field specifies a signal-catching function. If the SA_SIGINFO bit is
63 cleared and the sa_handler field specifies a signal-catching function,
64 or if the SA_SIGINFO bit is set, the sa_mask field identifies a set of
65 signals that shall be added to the signal mask of the thread before the
66 signal-catching function is invoked. If the sa_handler field specifies
67 a signal-catching function, the sa_mask field identifies a set of sig‐
68 nals that shall be added to the process' signal mask before the signal-
69 catching function is invoked.
70 The sa_flags field can be used to modify the behavior of the specified
72 signal.
73 The following flags, defined in the <signal.h> header, can be set in
75 sa_flags:
76 SA_NOCLDSTOP
78 Do not generate SIGCHLD when children stop or stopped children
79 continue.
80 If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags, and
82 the implementation supports the SIGCHLD signal, then a SIGCHLD signal
83 shall be generated for the calling process whenever any of its child
84 processes stop and a SIGCHLD signal may be generated for the calling
85 process whenever any of its stopped child processes are continued. If
86 sig is SIGCHLD and the SA_NOCLDSTOP flag is set in sa_flags, then the
87 implementation shall not generate a SIGCHLD signal in this way.
88 SA_ONSTACK
90 If set and an alternate signal stack has been declared with
91 sigaltstack(), the signal shall be delivered to the calling
92 process on that stack. Otherwise, the signal shall be delivered
93 on the current stack.
94 SA_RESETHAND
96 If set, the disposition of the signal shall be reset to SIG_DFL
97 and the SA_SIGINFO flag shall be cleared on entry to the signal
98 handler.
99 Note:
101 SIGILL and SIGTRAP cannot be automatically reset when delivered;
102 the system silently enforces this restriction.
103 Otherwise, the disposition of the signal shall not be modified on entry
105 to the signal handler.
106 In addition, if this flag is set, sigaction() behaves as if the
108 SA_NODEFER flag were also set.
109 SA_RESTART
111 This flag affects the behavior of interruptible functions; that
112 is, those specified to fail with errno set to [EINTR]. If set,
113 and a function specified as interruptible is interrupted by this
114 signal, the function shall restart and shall not fail with
115 [EINTR] unless otherwise specified. If the flag is not set,
116 interruptible functions interrupted by this signal shall fail
117 with errno set to [EINTR].
118 SA_SIGINFO
120 If cleared and the signal is caught, the signal-catching func‐
121 tion shall be entered as:
122 void func(int signo);
125 where signo is the only argument to the signal-catching function. In
127 this case, the application shall use the sa_handler member to describe
128 the signal-catching function and the application shall not modify the
129 sa_sigaction member.
130 If SA_SIGINFO is set and the signal is caught, the signal-catching
132 function shall be entered as:
133 void func(int signo, siginfo_t *info, void *context);
136 where two additional arguments are passed to the signal-catching func‐
138 tion. The second argument shall point to an object of type siginfo_t
139 explaining the reason why the signal was generated; the third argument
140 can be cast to a pointer to an object of type ucontext_t to refer to
141 the receiving process' context that was interrupted when the signal was
142 delivered. In this case, the application shall use the sa_sigaction
143 member to describe the signal-catching function and the application
144 shall not modify the sa_handler member.
145 The si_signo member contains the system-generated signal number.
147 The si_errno member may contain implementation-defined additional error
149 information; if non-zero, it contains an error number identifying the
150 condition that caused the signal to be generated.
151 The si_code member contains a code identifying the cause of the signal.
153 If the value of si_code is less than or equal to 0, then the signal was
155 generated by a process and si_pid and si_uid, respectively, indicate
156 the process ID and the real user ID of the sender. The <signal.h>
157 header description contains information about the signal-specific con‐
158 tents of the elements of the siginfo_t type.
159 SA_NOCLDWAIT
161 If set, and sig equals SIGCHLD, child processes of the calling
162 processes shall not be transformed into zombie processes when
163 they terminate. If the calling process subsequently waits for
164 its children, and the process has no unwaited-for children that
165 were transformed into zombie processes, it shall block until all
166 of its children terminate, and wait(), waitid(), and waitpid()
167 shall fail and set errno to [ECHILD]. Otherwise, terminating
168 child processes shall be transformed into zombie processes,
169 unless SIGCHLD is set to SIG_IGN.
170 SA_NODEFER
172 If set and sig is caught, sig shall not be added to the process'
173 signal mask on entry to the signal handler unless it is included
174 in sa_mask. Otherwise, sig shall always be added to the process'
175 signal mask on entry to the signal handler.
176 When a signal is caught by a signal-catching function installed by
179 sigaction(), a new signal mask is calculated and installed for the
180 duration of the signal-catching function (or until a call to either
181 sigprocmask() or sigsuspend() is made). This mask is formed by taking
182 the union of the current signal mask and the value of the sa_mask for
183 the signal being delivered unless SA_NODEFER or SA_RESETHAND is set,
184 and then including the signal being delivered. If and when the user's
185 signal handler returns normally, the original signal mask is restored.
186 Once an action is installed for a specific signal, it shall remain
188 installed until another action is explicitly requested (by another call
189 to sigaction()), until the SA_RESETHAND flag causes resetting of the
190 handler, or until one of the exec functions is called.
191 If the previous action for sig had been established by signal(), the
193 values of the fields returned in the structure pointed to by oact are
194 unspecified, and in particular oact-> sa_handler is not necessarily the
195 same value passed to signal(). However, if a pointer to the same
196 structure or a copy thereof is passed to a subsequent call to sigac‐
197 tion() via the act argument, handling of the signal shall be as if the
198 original call to signal() were repeated.
199 If sigaction() fails, no new signal handler is installed.
201 It is unspecified whether an attempt to set the action for a signal
203 that cannot be caught or ignored to SIG_DFL is ignored or causes an
204 error to be returned with errno set to [EINVAL].
205 If SA_SIGINFO is not set in sa_flags, then the disposition of subse‐
207 quent occurrences of sig when it is already pending is implementation-
208 defined; the signal-catching function shall be invoked with a single
209 argument. If the implementation supports the Realtime Signals Exten‐
210 sion option, and if SA_SIGINFO is set in sa_flags, then subsequent
211 occurrences of sig generated by sigqueue() or as a result of any sig‐
212 nal-generating function that supports the specification of an applica‐
213 tion-defined value (when sig is already pending) shall be queued in
214 FIFO order until delivered or accepted; the signal-catching function
215 shall be invoked with three arguments. The application specified value
216 is passed to the signal-catching function as the si_value member of the
217 siginfo_t structure.
218 The result of the use of sigaction() and a sigwait() function concur‐
220 rently within a process on the same signal is unspecified.
221
223 Upon successful completion, sigaction() shall return 0; otherwise, -1
224 shall be returned, errno shall be set to indicate the error, and no new
225 signal-catching function shall be installed.
226
228 The sigaction() function shall fail if:
229 EINVAL The sig argument is not a valid signal number or an attempt is
231 made to catch a signal that cannot be caught or ignore a signal
232 that cannot be ignored.
233 ENOTSUP
235 The SA_SIGINFO bit flag is set in the sa_flags field of the
236 sigaction structure, and the implementation does not support
237 either the Realtime Signals Extension option, or the XSI Exten‐
238 sion option.
239 The sigaction() function may fail if:
242 EINVAL An attempt was made to set the action to SIG_DFL for a signal
244 that cannot be caught or ignored (or both).
245 The following sections are informative.
248
250 None.
251
253 The sigaction() function supersedes the signal() function, and should
254 be used in preference. In particular, sigaction() and signal() should
255 not be used in the same process to control the same signal. The behav‐
256 ior of reentrant functions, as defined in the DESCRIPTION, is as speci‐
257 fied by this volume of IEEE Std 1003.1-2001, regardless of invocation
258 from a signal-catching function. This is the only intended meaning of
259 the statement that reentrant functions may be used in signal-catching
260 functions without restrictions. Applications must still consider all
261 effects of such functions on such things as data structures, files, and
262 process state. In particular, application writers need to consider the
263 restrictions on interactions when interrupting sleep() and interactions
264 among multiple handles for a file description. The fact that any spe‐
265 cific function is listed as reentrant does not necessarily mean that
266 invocation of that function from a signal-catching function is recom‐
267 mended.
268 In order to prevent errors arising from interrupting non-reentrant
270 function calls, applications should protect calls to these functions
271 either by blocking the appropriate signals or through the use of some
272 programmatic semaphore (see semget(), sem_init(), sem_open(), and so
273 on). Note in particular that even the "safe" functions may modify
274 errno; the signal-catching function, if not executing as an independent
275 thread, may want to save and restore its value. Naturally, the same
276 principles apply to the reentrancy of application routines and asyn‐
277 chronous data access. Note that longjmp() and siglongjmp() are not in
278 the list of reentrant functions. This is because the code executing
279 after longjmp() and siglongjmp() can call any unsafe functions with the
280 same danger as calling those unsafe functions directly from the signal
281 handler. Applications that use longjmp() and siglongjmp() from within
282 signal handlers require rigorous protection in order to be portable.
283 Many of the other functions that are excluded from the list are tradi‐
284 tionally implemented using either malloc() or free() functions or the
285 standard I/O library, both of which traditionally use data structures
286 in a non-reentrant manner. Since any combination of different functions
287 using a common data structure can cause reentrancy problems, this vol‐
288 ume of IEEE Std 1003.1-2001 does not define the behavior when any
289 unsafe function is called in a signal handler that interrupts an unsafe
290 function.
291 If the signal occurs other than as the result of calling abort(),
293 kill(), or raise(), the behavior is undefined if the signal handler
294 calls any function in the standard library other than one of the func‐
295 tions listed in the table above or refers to any object with static
296 storage duration other than by assigning a value to a static storage
297 duration variable of type volatile sig_atomic_t. Furthermore, if such a
298 call fails, the value of errno is unspecified.
299 Usually, the signal is executed on the stack that was in effect before
301 the signal was delivered. An alternate stack may be specified to
302 receive a subset of the signals being caught.
303 When the signal handler returns, the receiving process resumes execu‐
305 tion at the point it was interrupted unless the signal handler makes
306 other arrangements. If longjmp() or _longjmp() is used to leave the
307 signal handler, then the signal mask must be explicitly restored by the
308 process.
309 This volume of IEEE Std 1003.1-2001 defines the third argument of a
311 signal handling function when SA_SIGINFO is set as a void * instead of
312 a ucontext_t *, but without requiring type checking. New applications
313 should explicitly cast the third argument of the signal handling func‐
314 tion to ucontext_t *.
315 The BSD optional four argument signal handling function is not sup‐
317 ported by this volume of IEEE Std 1003.1-2001. The BSD declaration
318 would be:
319 void handler(int sig, int code, struct sigcontext *scp,
322 char *addr);
323 where sig is the signal number, code is additional information on cer‐
325 tain signals, scp is a pointer to the sigcontext structure, and addr is
326 additional address information. Much the same information is available
327 in the objects pointed to by the second argument of the signal handler
328 specified when SA_SIGINFO is set.
329
331 Although this volume of IEEE Std 1003.1-2001 requires that signals that
332 cannot be ignored shall not be added to the signal mask when a signal-
333 catching function is entered, there is no explicit requirement that
334 subsequent calls to sigaction() reflect this in the information
335 returned in the oact argument. In other words, if SIGKILL is included
336 in the sa_mask field of act, it is unspecified whether or not a subse‐
337 quent call to sigaction() returns with SIGKILL included in the sa_mask
338 field of oact.
339 The SA_NOCLDSTOP flag, when supplied in the act-> sa_flags parameter,
341 allows overloading SIGCHLD with the System V semantics that each SIGCLD
342 signal indicates a single terminated child. Most conforming applica‐
343 tions that catch SIGCHLD are expected to install signal-catching func‐
344 tions that repeatedly call the waitpid() function with the WNOHANG flag
345 set, acting on each child for which status is returned, until waitpid()
346 returns zero. If stopped children are not of interest, the use of the
347 SA_NOCLDSTOP flag can prevent the overhead from invoking the signal-
348 catching routine when they stop.
349 Some historical implementations also define other mechanisms for stop‐
351 ping processes, such as the ptrace() function. These implementations
352 usually do not generate a SIGCHLD signal when processes stop due to
353 this mechanism; however, that is beyond the scope of this volume of
354 IEEE Std 1003.1-2001.
355 This volume of IEEE Std 1003.1-2001 requires that calls to sigaction()
357 that supply a NULL act argument succeed, even in the case of signals
358 that cannot be caught or ignored (that is, SIGKILL or SIGSTOP). The
359 System V signal() and BSD sigvec() functions return [EINVAL] in these
360 cases and, in this respect, their behavior varies from sigaction().
361 This volume of IEEE Std 1003.1-2001 requires that sigaction() properly
363 save and restore a signal action set up by the ISO C standard signal()
364 function. However, there is no guarantee that the reverse is true, nor
365 could there be given the greater amount of information conveyed by the
366 sigaction structure. Because of this, applications should avoid using
367 both functions for the same signal in the same process. Since this can‐
368 not always be avoided in case of general-purpose library routines, they
369 should always be implemented with sigaction().
370 It was intended that the signal() function should be implementable as a
372 library routine using sigaction().
373 The POSIX Realtime Extension extends the sigaction() function as speci‐
375 fied by the POSIX.1-1990 standard to allow the application to request
376 on a per-signal basis via an additional signal action flag that the
377 extra parameters, including the application-defined signal value, if
378 any, be passed to the signal-catching function.
379
381 None.
382
384 Signal Concepts, bsd_signal(), kill(), _longjmp(), longjmp(), raise(),
385 semget(), sem_init() , sem_open(), sigaddset(), sigaltstack(),
386 sigdelset(), sigemptyset(), sigfillset(), sigismember(), signal(), sig‐
387 procmask(), sigsuspend(), wait(), waitid(), waitpid(), the Base Defini‐
388 tions volume of IEEE Std 1003.1-2001, <signal.h>, <ucontext.h>
389
391 Portions of this text are reprinted and reproduced in electronic form
392 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
393 -- Portable Operating System Interface (POSIX), The Open Group Base
394 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
395 Electrical and Electronics Engineers, Inc and The Open Group. In the
396 event of any discrepancy between this version and the original IEEE and
397 The Open Group Standard, the original IEEE and The Open Group Standard
398 is the referee document. The original Standard can be obtained online
399 at http://www.opengroup.org/unix/online.html .
400IEEE/The Open Group 2003 SIGACTION(3P)