1SIGACTION(2)               Linux Programmer's Manual              SIGACTION(2)
2
3
4

NAME

6       sigaction, rt_sigaction - examine and change a signal action
7

SYNOPSIS

9       #include <signal.h>
10
11       int sigaction(int signum, const struct sigaction *act,
12                     struct sigaction *oldact);
13
14   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
15
16       sigaction(): _POSIX_C_SOURCE
17
18       siginfo_t: _POSIX_C_SOURCE >= 199309L
19

DESCRIPTION

21       The  sigaction()  system  call  is used to change the action taken by a
22       process on receipt of a specific signal.  (See signal(7) for  an  over‐
23       view of signals.)
24
25       signum  specifies the signal and can be any valid signal except SIGKILL
26       and SIGSTOP.
27
28       If act is non-NULL, the new action for signal signum is installed  from
29       act.  If oldact is non-NULL, the previous action is saved in oldact.
30
31       The sigaction structure is defined as something like:
32
33           struct sigaction {
34               void     (*sa_handler)(int);
35               void     (*sa_sigaction)(int, siginfo_t *, void *);
36               sigset_t   sa_mask;
37               int        sa_flags;
38               void     (*sa_restorer)(void);
39           };
40
41       On  some  architectures  a  union  is  involved:  do not assign to both
42       sa_handler and sa_sigaction.
43
44       The sa_restorer field is not intended for application use.  (POSIX does
45       not  specify a sa_restorer field.)  Some further details of the purpose
46       of this field can be found in sigreturn(2).
47
48       sa_handler specifies the action to be associated with signum and may be
49       SIG_DFL  for  the  default  action, SIG_IGN to ignore this signal, or a
50       pointer to a signal handling function.  This function receives the sig‐
51       nal number as its only argument.
52
53       If  SA_SIGINFO  is specified in sa_flags, then sa_sigaction (instead of
54       sa_handler) specifies the signal-handling function  for  signum.   This
55       function receives three arguments, as described below.
56
57       sa_mask  specifies  a  mask  of  signals which should be blocked (i.e.,
58       added to the signal mask of the thread in which the signal  handler  is
59       invoked) during execution of the signal handler.  In addition, the sig‐
60       nal which triggered the handler will be blocked, unless the  SA_NODEFER
61       flag is used.
62
63       sa_flags specifies a set of flags which modify the behavior of the sig‐
64       nal.  It is formed by the bitwise OR of zero or more of the following:
65
66       SA_NOCLDSTOP
67              If signum is SIGCHLD, do not  receive  notification  when  child
68              processes stop (i.e., when they receive one of SIGSTOP, SIGTSTP,
69              SIGTTIN, or SIGTTOU) or resume (i.e., they receive SIGCONT) (see
70              wait(2)).  This flag is meaningful only when establishing a han‐
71              dler for SIGCHLD.
72
73       SA_NOCLDWAIT (since Linux 2.6)
74              If signum is SIGCHLD, do not  transform  children  into  zombies
75              when  they  terminate.  See also waitpid(2).  This flag is mean‐
76              ingful only when establishing a handler  for  SIGCHLD,  or  when
77              setting that signal's disposition to SIG_DFL.
78
79              If  the SA_NOCLDWAIT flag is set when establishing a handler for
80              SIGCHLD, POSIX.1 leaves it unspecified whether a SIGCHLD  signal
81              is  generated  when  a  child  process  terminates.  On Linux, a
82              SIGCHLD signal is generated in this case; on some  other  imple‐
83              mentations, it is not.
84
85       SA_NODEFER
86              Do  not  prevent  the signal from being received from within its
87              own signal handler.  This flag is meaningful  only  when  estab‐
88              lishing a signal handler.  SA_NOMASK is an obsolete, nonstandard
89              synonym for this flag.
90
91       SA_ONSTACK
92              Call the signal handler on an alternate signal stack provided by
93              sigaltstack(2).   If  an  alternate  stack is not available, the
94              default stack will be used.  This flag is meaningful  only  when
95              establishing a signal handler.
96
97       SA_RESETHAND
98              Restore  the signal action to the default upon entry to the sig‐
99              nal handler.  This flag is meaningful only when  establishing  a
100              signal  handler.  SA_ONESHOT is an obsolete, nonstandard synonym
101              for this flag.
102
103       SA_RESTART
104              Provide behavior compatible with BSD signal semantics by  making
105              certain  system  calls restartable across signals.  This flag is
106              meaningful only when establishing a signal  handler.   See  sig‐
107              nal(7) for a discussion of system call restarting.
108
109       SA_RESTORER
110              Not  intended  for  application  use.   This  flag  is used by C
111              libraries to indicate that the sa_restorer  field  contains  the
112              address  of  a  "signal  trampoline".  See sigreturn(2) for more
113              details.
114
115       SA_SIGINFO (since Linux 2.2)
116              The signal handler takes three  arguments,  not  one.   In  this
117              case,  sa_sigaction  should  be set instead of sa_handler.  This
118              flag is meaningful only when establishing a signal handler.
119
120   The siginfo_t argument to a SA_SIGINFO handler
121       When the SA_SIGINFO flag is specified in act.sa_flags, the signal  han‐
122       dler  address  is  passed via the act.sa_sigaction field.  This handler
123       takes three arguments, as follows:
124
125           void
126           handler(int sig, siginfo_t *info, void *ucontext)
127           {
128               ...
129           }
130
131       These three arguments are as follows
132
133       sig    The number of the signal that caused invocation of the handler.
134
135       info   A pointer to a siginfo_t, which is a structure  containing  fur‐
136              ther information about the signal, as described below.
137
138       ucontext
139              This  is  a  pointer  to a ucontext_t structure, cast to void *.
140              The structure pointed to by this field contains  signal  context
141              information  that  was saved on the user-space stack by the ker‐
142              nel; for details, see sigreturn(2).  Further  information  about
143              the  ucontext_t  structure  can be found in getcontext(3).  Com‐
144              monly, the handler function doesn't make any use  of  the  third
145              argument.
146
147       The siginfo_t data type is a structure with the following fields:
148
149           siginfo_t {
150               int      si_signo;     /* Signal number */
151               int      si_errno;     /* An errno value */
152               int      si_code;      /* Signal code */
153               int      si_trapno;    /* Trap number that caused
154                                         hardware-generated signal
155                                         (unused on most architectures) */
156               pid_t    si_pid;       /* Sending process ID */
157               uid_t    si_uid;       /* Real user ID of sending process */
158               int      si_status;    /* Exit value or signal */
159               clock_t  si_utime;     /* User time consumed */
160               clock_t  si_stime;     /* System time consumed */
161               sigval_t si_value;     /* Signal value */
162               int      si_int;       /* POSIX.1b signal */
163               void    *si_ptr;       /* POSIX.1b signal */
164               int      si_overrun;   /* Timer overrun count;
165                                         POSIX.1b timers */
166               int      si_timerid;   /* Timer ID; POSIX.1b timers */
167               void    *si_addr;      /* Memory location which caused fault */
168               long     si_band;      /* Band event (was int in
169                                         glibc 2.3.2 and earlier) */
170               int      si_fd;        /* File descriptor */
171               short    si_addr_lsb;  /* Least significant bit of address
172                                         (since Linux 2.6.32) */
173               void    *si_lower;     /* Lower bound when address violation
174                                         occurred (since Linux 3.19) */
175               void    *si_upper;     /* Upper bound when address violation
176                                         occurred (since Linux 3.19) */
177               int      si_pkey;      /* Protection key on PTE that caused
178                                         fault (since Linux 4.6) */
179               void    *si_call_addr; /* Address of system call instruction
180                                         (since Linux 3.5) */
181               int      si_syscall;   /* Number of attempted system call
182                                         (since Linux 3.5) */
183               unsigned int si_arch;  /* Architecture of attempted system call
184                                         (since Linux 3.5) */
185           }
186
187       si_signo,  si_errno and si_code are defined for all signals.  (si_errno
188       is generally unused on Linux.)  The rest of the struct may be a  union,
189       so  that  one  should  read only the fields that are meaningful for the
190       given signal:
191
192       * Signals sent with kill(2) and sigqueue(3) fill in si_pid and  si_uid.
193         In  addition, signals sent with sigqueue(3) fill in si_int and si_ptr
194         with  the  values  specified  by  the  sender  of  the  signal;   see
195         sigqueue(3) for more details.
196
197       * Signals  sent by POSIX.1b timers (since Linux 2.6) fill in si_overrun
198         and si_timerid.  The si_timerid field is an internal ID used  by  the
199         kernel  to  identify  the  timer;  it is not the same as the timer ID
200         returned by timer_create(2).  The si_overrun field is the timer over‐
201         run  count;  this is the same information as is obtained by a call to
202         timer_getoverrun(2).  These fields are nonstandard Linux extensions.
203
204       * Signals sent for message queue notification (see the  description  of
205         SIGEV_SIGNAL   in  mq_notify(3))  fill  in  si_int/si_ptr,  with  the
206         sigev_value supplied to mq_notify(3); si_pid, with the process ID  of
207         the  message sender; and si_uid, with the real user ID of the message
208         sender.
209
210       * SIGCHLD fills in si_pid, si_uid, si_status, si_utime,  and  si_stime,
211         providing  information  about  the  child.   The  si_pid field is the
212         process ID of the child; si_uid is the child's  real  user  ID.   The
213         si_status  field contains the exit status of the child (if si_code is
214         CLD_EXITED), or the signal number that caused the process  to  change
215         state.   The  si_utime  and  si_stime contain the user and system CPU
216         time used by the child process; these fields do not include the times
217         used  by  waited-for children (unlike getrusage(2) and times(2)).  In
218         kernels up to 2.6, and since 2.6.27, these fields report CPU time  in
219         units  of  sysconf(_SC_CLK_TCK).  In 2.6 kernels before 2.6.27, a bug
220         meant that these fields reported time in units of the  (configurable)
221         system jiffy (see time(7)).
222
223       * SIGILL, SIGFPE, SIGSEGV, SIGBUS, and SIGTRAP fill in si_addr with the
224         address of the fault.  On some architectures, these signals also fill
225         in the si_trapno field.
226
227         Some   suberrors   of   SIGBUS,   in   particular  BUS_MCEERR_AO  and
228         BUS_MCEERR_AR, also fill in si_addr_lsb.  This  field  indicates  the
229         least  significant  bit  of  the  reported  address and therefore the
230         extent of the corruption.  For example, if a full page was corrupted,
231         si_addr_lsb  contains  log2(sysconf(_SC_PAGESIZE)).   When SIGTRAP is
232         delivered  in  response  to  a  ptrace(2)  event  (PTRACE_EVENT_foo),
233         si_addr  is  not  populated, but si_pid and si_uid are populated with
234         the respective process ID and user ID responsible for delivering  the
235         trap.   In the case of seccomp(2), the tracee will be shown as deliv‐
236         ering the event.  BUS_MCEERR_*  and  si_addr_lsb  are  Linux-specific
237         extensions.
238
239         The SEGV_BNDERR suberror of SIGSEGV populates si_lower and si_upper.
240
241         The SEGV_PKUERR suberror of SIGSEGV populates si_pkey.
242
243       * SIGIO/SIGPOLL  (the two names are synonyms on Linux) fills in si_band
244         and si_fd.  The si_band event is a bit mask containing the same  val‐
245         ues  as  are filled in the revents field by poll(2).  The si_fd field
246         indicates the file descriptor for which the I/O event  occurred;  for
247         further details, see the description of F_SETSIG in fcntl(2).
248
249       * SIGSYS,  generated  (since  Linux  3.5) when a seccomp filter returns
250         SECCOMP_RET_TRAP,  fills  in   si_call_addr,   si_syscall,   si_arch,
251         si_errno, and other fields as described in seccomp(2).
252
253   The si_code field
254       The  si_code  field  inside  the siginfo_t argument that is passed to a
255       SA_SIGINFO signal handler is a value (not a bit  mask)  indicating  why
256       this signal was sent.  For a ptrace(2) event, si_code will contain SIG‐
257       TRAP and have the ptrace event in the high byte:
258
259           (SIGTRAP | PTRACE_EVENT_foo << 8).
260
261       For a non-ptrace(2) event, the values that can appear  in  si_code  are
262       described in the remainder of this section.  Since glibc 2.20, the def‐
263       initions of most of these  symbols  are  obtained  from  <signal.h>  by
264       defining feature test macros (before including any header file) as fol‐
265       lows:
266
267       *  _XOPEN_SOURCE with the value 500 or greater;
268
269       *  _XOPEN_SOURCE and _XOPEN_SOURCE_EXTENDED; or
270
271       *  _POSIX_C_SOURCE with the value 200809L or greater.
272
273       For the TRAP_* constants, the symbol definitions are provided  only  in
274       the  first  two  cases.  Before glibc 2.20, no feature test macros were
275       required to obtain these symbols.
276
277       For a regular signal, the following list shows the values which can  be
278       placed in si_code for any signal, along with the reason that the signal
279       was generated.
280
281           SI_USER
282                  kill(2).
283
284           SI_KERNEL
285                  Sent by the kernel.
286
287           SI_QUEUE
288                  sigqueue(3).
289
290           SI_TIMER
291                  POSIX timer expired.
292
293           SI_MESGQ (since Linux 2.6.6)
294                  POSIX message queue state changed; see mq_notify(3).
295
296           SI_ASYNCIO
297                  AIO completed.
298
299           SI_SIGIO
300                  Queued SIGIO (only in kernels up to Linux  2.2;  from  Linux
301                  2.4  onward  SIGIO/SIGPOLL  fills  in  si_code  as described
302                  below).
303
304           SI_TKILL (since Linux 2.4.19)
305                  tkill(2) or tgkill(2).
306
307       The following values can be placed in si_code for a SIGILL signal:
308
309           ILL_ILLOPC
310                  Illegal opcode.
311
312           ILL_ILLOPN
313                  Illegal operand.
314
315           ILL_ILLADR
316                  Illegal addressing mode.
317
318           ILL_ILLTRP
319                  Illegal trap.
320
321           ILL_PRVOPC
322                  Privileged opcode.
323
324           ILL_PRVREG
325                  Privileged register.
326
327           ILL_COPROC
328                  Coprocessor error.
329
330           ILL_BADSTK
331                  Internal stack error.
332
333       The following values can be placed in si_code for a SIGFPE signal:
334
335           FPE_INTDIV
336                  Integer divide by zero.
337
338           FPE_INTOVF
339                  Integer overflow.
340
341           FPE_FLTDIV
342                  Floating-point divide by zero.
343
344           FPE_FLTOVF
345                  Floating-point overflow.
346
347           FPE_FLTUND
348                  Floating-point underflow.
349
350           FPE_FLTRES
351                  Floating-point inexact result.
352
353           FPE_FLTINV
354                  Floating-point invalid operation.
355
356           FPE_FLTSUB
357                  Subscript out of range.
358
359       The following values can be placed in si_code for a SIGSEGV signal:
360
361           SEGV_MAPERR
362                  Address not mapped to object.
363
364           SEGV_ACCERR
365                  Invalid permissions for mapped object.
366
367           SEGV_BNDERR (since Linux 3.19)
368                  Failed address bound checks.
369
370           SEGV_PKUERR (since Linux 4.6)
371                  Access was denied by memory protection keys.  See  pkeys(7).
372                  The protection key which applied to this access is available
373                  via si_pkey.
374
375       The following values can be placed in si_code for a SIGBUS signal:
376
377           BUS_ADRALN
378                  Invalid address alignment.
379
380           BUS_ADRERR
381                  Nonexistent physical address.
382
383           BUS_OBJERR
384                  Object-specific hardware error.
385
386           BUS_MCEERR_AR (since Linux 2.6.32)
387                  Hardware memory error consumed on a  machine  check;  action
388                  required.
389
390           BUS_MCEERR_AO (since Linux 2.6.32)
391                  Hardware  memory error detected in process but not consumed;
392                  action optional.
393
394       The following values can be placed in si_code for a SIGTRAP signal:
395
396           TRAP_BRKPT
397                  Process breakpoint.
398
399           TRAP_TRACE
400                  Process trace trap.
401
402           TRAP_BRANCH (since Linux 2.4, IA64 only))
403                  Process taken branch trap.
404
405           TRAP_HWBKPT (since Linux 2.4, IA64 only))
406                  Hardware breakpoint/watchpoint.
407
408       The following values can be placed in si_code for a SIGCHLD signal:
409
410           CLD_EXITED
411                  Child has exited.
412
413           CLD_KILLED
414                  Child was killed.
415
416           CLD_DUMPED
417                  Child terminated abnormally.
418
419           CLD_TRAPPED
420                  Traced child has trapped.
421
422           CLD_STOPPED
423                  Child has stopped.
424
425           CLD_CONTINUED (since Linux 2.6.9)
426                  Stopped child has continued.
427
428       The following values can be placed in si_code for a SIGIO/SIGPOLL  sig‐
429       nal:
430
431           POLL_IN
432                  Data input available.
433
434           POLL_OUT
435                  Output buffers available.
436
437           POLL_MSG
438                  Input message available.
439
440           POLL_ERR
441                  I/O error.
442
443           POLL_PRI
444                  High priority input available.
445
446           POLL_HUP
447                  Device disconnected.
448
449       The following value can be placed in si_code for a SIGSYS signal:
450
451           SYS_SECCOMP (since Linux 3.5)
452                  Triggered by a seccomp(2) filter rule.
453

RETURN VALUE

455       sigaction()  returns  0 on success; on error, -1 is returned, and errno
456       is set to indicate the error.
457

ERRORS

459       EFAULT act or oldact points to memory which is not a valid part of  the
460              process address space.
461
462       EINVAL An invalid signal was specified.  This will also be generated if
463              an attempt is made to change the action for SIGKILL or  SIGSTOP,
464              which cannot be caught or ignored.
465

CONFORMING TO

467       POSIX.1-2001, POSIX.1-2008, SVr4.
468

NOTES

470       A child created via fork(2) inherits a copy of its parent's signal dis‐
471       positions.  During an execve(2), the dispositions  of  handled  signals
472       are  reset to the default; the dispositions of ignored signals are left
473       unchanged.
474
475       According to POSIX, the behavior of a process  is  undefined  after  it
476       ignores  a  SIGFPE, SIGILL, or SIGSEGV signal that was not generated by
477       kill(2) or raise(3).  Integer division by zero  has  undefined  result.
478       On some architectures it will generate a SIGFPE signal.  (Also dividing
479       the most negative integer by -1 may generate  SIGFPE.)   Ignoring  this
480       signal might lead to an endless loop.
481
482       POSIX.1-1990  disallowed  setting  the  action  for SIGCHLD to SIG_IGN.
483       POSIX.1-2001 and later allow this possibility, so that ignoring SIGCHLD
484       can  be  used to prevent the creation of zombies (see wait(2)).  Never‐
485       theless, the historical BSD and System V behaviors for ignoring SIGCHLD
486       differ,  so  that  the only completely portable method of ensuring that
487       terminated children do not become zombies is to catch the SIGCHLD  sig‐
488       nal and perform a wait(2) or similar.
489
490       POSIX.1-1990 specified only SA_NOCLDSTOP.  POSIX.1-2001 added SA_NOCLD‐
491       STOP, SA_NOCLDWAIT, SA_NODEFER, SA_ONSTACK,  SA_RESETHAND,  SA_RESTART,
492       and  SA_SIGINFO.   Use  of  these latter values in sa_flags may be less
493       portable in applications intended for older UNIX implementations.
494
495       The SA_RESETHAND flag is compatible with the  SVr4  flag  of  the  same
496       name.
497
498       The  SA_NODEFER  flag is compatible with the SVr4 flag of the same name
499       under kernels 1.3.9 and newer.  On older kernels the Linux  implementa‐
500       tion  allowed  the  receipt  of  any  signal,  not  just the one we are
501       installing (effectively overriding any sa_mask settings).
502
503       sigaction() can be called with a NULL second argument to query the cur‐
504       rent signal handler.  It can also be used to check whether a given sig‐
505       nal is valid for the current machine by calling it with NULL second and
506       third arguments.
507
508       It  is  not possible to block SIGKILL or SIGSTOP (by specifying them in
509       sa_mask).  Attempts to do so are silently ignored.
510
511       See sigsetops(3) for details on manipulating signal sets.
512
513       See signal-safety(7) for a list of the async-signal-safe functions that
514       can be safely called inside from inside a signal handler.
515
516   C library/kernel differences
517       The  glibc  wrapper function for sigaction() gives an error (EINVAL) on
518       attempts to change the disposition of the two  real-time  signals  used
519       internally  by  the  NPTL  threading  implementation.   See nptl(7) for
520       details.
521
522       On architectures where the signal trampoline resides in the C  library,
523       the  glibc  wrapper  function for sigaction() places the address of the
524       trampoline code in the act.sa_restorer field and sets  the  SA_RESTORER
525       flag in the act.sa_flags field.  See sigreturn(2).
526
527       The  original  Linux  system call was named sigaction().  However, with
528       the addition of real-time signals in Linux 2.2, the fixed-size,  32-bit
529       sigset_t  type supported by that system call was no longer fit for pur‐
530       pose.  Consequently, a new system call, rt_sigaction(),  was  added  to
531       support  an enlarged sigset_t type.  The new system call takes a fourth
532       argument, size_t sigsetsize, which specifies the size in bytes  of  the
533       signal  sets  in act.sa_mask and oldact.sa_mask.  This argument is cur‐
534       rently required to have the value sizeof(sigset_t) (or the error EINVAL
535       results).   The  glibc sigaction() wrapper function hides these details
536       from us, transparently calling rt_sigaction() when the kernel  provides
537       it.
538
539   Undocumented
540       Before the introduction of SA_SIGINFO, it was also possible to get some
541       additional information about the signal.  This was done by providing an
542       sa_handler signal handler with a second argument of type struct sigcon‐
543       text, which is the same structure as the one  that  is  passed  in  the
544       uc_mcontext  field  of  the  ucontext  structure  that is passed (via a
545       pointer) in the third argument of the sa_sigaction  handler.   See  the
546       relevant Linux kernel sources for details.  This use is obsolete now.
547

BUGS

549       When delivering a signal with a SA_SIGINFO handler, the kernel does not
550       always provide meaningful values for all of the fields of the siginfo_t
551       that are relevant for that signal.
552
553       In  kernels  up  to  and  including  2.6.13,  specifying  SA_NODEFER in
554       sa_flags prevents not only the delivered signal from being masked  dur‐
555       ing  execution  of  the  handler,  but  also  the  signals specified in
556       sa_mask.  This bug was fixed in kernel 2.6.14.
557

EXAMPLES

559       See mprotect(2).
560

SEE ALSO

562       kill(1), kill(2), pause(2),  pidfd_send_signal(2),  restart_syscall(2),
563       seccomp(2), sigaltstack(2), signal(2), signalfd(2), sigpending(2), sig‐
564       procmask(2), sigreturn(2), sigsuspend(2), wait(2), killpg(3), raise(3),
565       siginterrupt(3),  sigqueue(3),  sigsetops(3),  sigvec(3), core(5), sig‐
566       nal(7)
567

COLOPHON

569       This page is part of release 5.07 of the Linux  man-pages  project.   A
570       description  of  the project, information about reporting bugs, and the
571       latest    version    of    this    page,    can     be     found     at
572       https://www.kernel.org/doc/man-pages/.
573
574
575
576Linux                             2020-04-11                      SIGACTION(2)
Impressum