1SIGACTION(3P)              POSIX Programmer's Manual             SIGACTION(3P)
2
3
4

PROLOG

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
11

NAME

13       sigaction — examine and change a signal action
14

SYNOPSIS

16       #include <signal.h>
17
18       int sigaction(int sig, const struct sigaction *restrict act,
19           struct sigaction *restrict oact);
20

DESCRIPTION

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
27       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
31      ┌────────────────┬───────────────┬───────────────────────────────────────┐
32Member Type   Member Name   Description               
33      ├────────────────┼───────────────┼───────────────────────────────────────┤
34void(*) (int)   sa_handler    │Pointer to a signal-catching function  │
35      │                │               │or one of the macros SIG_IGN or        │
36      │                │               │SIG_DFL.                               │
37sigset_t        sa_mask       │Additional set of signals to be        │
38      │                │               │blocked during execution of signal-    │
39      │                │               │catching function.                     │
40int             sa_flags      │Special flags to affect behavior of    │
41      │                │               │signal.                                │
42void(*) (int,   sa_sigaction  │Pointer to a signal-catching function. │
43siginfo_t *,  │               │                                       │
44void *)         │               │                                       │
45      └────────────────┴───────────────┴───────────────────────────────────────┘
46       The  storage occupied by sa_handler and sa_sigaction may overlap, and a
47       conforming application shall not use both simultaneously.
48
49       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
59       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
65       The sa_flags field can be used to modify the behavior of the  specified
66       signal.
67
68       The  following  flags,  defined in the <signal.h> header, can be set in
69       sa_flags:
70
71       SA_NOCLDSTOP  Do not generate SIGCHLD when  children  stop  or  stopped
72                     children continue.
73
74                     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
84       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
89       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
93                     Note:     SIGILL  and  SIGTRAP  cannot  be  automatically
94                               reset   when  delivered;  the  system  silently
95                               enforces this restriction.
96
97                     Otherwise, the disposition of the  signal  shall  not  be
98                     modified on entry to the signal handler.
99
100                     In  addition, if this flag is set, sigaction() may behave
101                     as if the SA_NODEFER flag were also set.
102
103       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
115       SA_SIGINFO    If cleared and the signal is caught, the  signal-catching
116                     function shall be entered as:
117
118                         void func(int signo);
119
120                     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
126                     If  SA_SIGINFO  is set and the signal is caught, the sig‐
127                     nal-catching function shall be entered as:
128
129                         void func(int signo, siginfo_t *info, void *context);
130
131                     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
142                     The  si_signo member contains the system-generated signal
143                     number.
144
145                     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
150                     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
154       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
165       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
171       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
180       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
185       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
193       If sigaction() fails, no new signal handler is installed.
194
195       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
199       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
211       The result of the use of sigaction() and a sigwait()  function  concur‐
212       rently within a process on the same signal is unspecified.
213

RETURN VALUE

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

ERRORS

220       The sigaction() function shall fail if:
221
222       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
226       ENOTSUP
227              The  SA_SIGINFO  bit  flag  is  set in the sa_flags field of the
228              sigaction structure.
229
230       The sigaction() function may fail if:
231
232       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
235       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
239       The following sections are informative.
240

EXAMPLES

242   Establishing a Signal Handler
243       The  following example demonstrates the use of sigaction() to establish
244       a handler for the SIGINT signal.
245
246           #include <signal.h>
247
248           static void handler(int signum)
249           {
250               /* Take appropriate actions for signal delivery */
251           }
252
253           int main()
254           {
255               struct sigaction sa;
256
257               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
264               /* Further code */
265           }
266

APPLICATION USAGE

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
284       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
310       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
314       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
319       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
325       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
328           void handler(int sig, int code, struct sigcontext *scp,
329               char *addr);
330
331       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
337       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
343       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

RATIONALE

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
356       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
366       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
372       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
378       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
387       It was intended that the signal() function should be implementable as a
388       library routine using sigaction().
389
390       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

FUTURE DIRECTIONS

397       None.
398

SEE ALSO

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
405       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
419       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 .
423
424
425
426IEEE/The Open Group                  2013                        SIGACTION(3P)
Impressum