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

NAME

12       sigaction - examine and change a signal action
13

SYNOPSIS

15       #include <signal.h>
16
17       int sigaction(int sig, const struct sigaction *restrict act,
18              struct sigaction *restrict oact);
19
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           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
44       The storage occupied by sa_handler and sa_sigaction may overlap, and  a
45       conforming application shall not use both simultaneously.
46
47       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
57       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
71       The  sa_flags field can be used to modify the behavior of the specified
72       signal.
73
74       The following flags, defined in the <signal.h> header, can  be  set  in
75       sa_flags:
76
77       SA_NOCLDSTOP
78              Do  not generate SIGCHLD when children stop  or stopped children
79              continue.
80
81       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
89       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
95       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
100       Note:
101              SIGILL and SIGTRAP cannot be automatically reset when delivered;
102              the system silently enforces this restriction.
103
104       Otherwise, the disposition of the signal shall not be modified on entry
105       to the signal handler.
106
107       In  addition,  if  this  flag  is  set,  sigaction()  behaves as if the
108       SA_NODEFER flag were also set.
109
110       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
119       SA_SIGINFO
120              If cleared and the signal is caught, the  signal-catching  func‐
121              tion shall be entered as:
122
123
124              void func(int signo);
125
126       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
131       If SA_SIGINFO is set and the  signal  is  caught,  the  signal-catching
132       function shall be entered as:
133
134
135              void func(int signo, siginfo_t *info, void *context);
136
137       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
146       The si_signo member contains the system-generated signal number.
147
148       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
152       The si_code member contains a code identifying the cause of the signal.
153
154       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
160       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
171       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
177
178       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
187       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
192       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
200       If sigaction() fails, no new signal handler is installed.
201
202       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
206       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
219       The result of the use of sigaction() and a sigwait()  function  concur‐
220       rently within a process on the same signal is unspecified.
221

RETURN VALUE

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

ERRORS

228       The sigaction() function shall fail if:
229
230       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
234       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
240
241       The sigaction() function may fail if:
242
243       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
246
247       The following sections are informative.
248

EXAMPLES

250       None.
251

APPLICATION USAGE

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
269       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
292       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
300       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
304       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
310       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
316       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
320
321              void handler(int sig, int code, struct sigcontext *scp,
322                  char *addr);
323
324       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

RATIONALE

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
340       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
350       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
356       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
362       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
371       It was intended that the signal() function should be implementable as a
372       library routine using sigaction().
373
374       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

FUTURE DIRECTIONS

381       None.
382

SEE ALSO

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 .
400
401
402
403IEEE/The Open Group                  2003                        SIGACTION(3P)
Impressum