| blob | 57ad6418c3d192d740eaf4cb02b8cb1ae9aeba2b |
1 .\" Copyright (c) 1994,1995 Mike Battersby <mib@deakin.edu.au>
2 .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" based on work by faith@cs.unc.edu
4 .\"
5 .\" %%%LICENSE_START(VERBATIM)
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
9 .\"
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
14 .\"
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date. The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein. The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
21 .\" professionally.
22 .\"
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" %%%LICENSE_END
26 .\"
27 .\" Modified, aeb, 960424
28 .\" Modified Fri Jan 31 17:31:20 1997 by Eric S. Raymond <esr@thyrsus.com>
29 .\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff.
30 .\" Modified Sat May 8 17:40:19 1999 by Matthew Wilcox
31 .\" add POSIX.1b signals
32 .\" Modified Sat Dec 29 01:44:52 2001 by Evan Jones <ejones@uwaterloo.ca>
33 .\" SA_ONSTACK
34 .\" Modified 2004-11-11 by Michael Kerrisk <mtk.manpages@gmail.com>
35 .\" Added mention of SIGCONT under SA_NOCLDSTOP
36 .\" Added SA_NOCLDWAIT
37 .\" Modified 2004-11-17 by Michael Kerrisk <mtk.manpages@gmail.com>
38 .\" Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags.
39 .\" Formatting fixes
40 .\" 2004-12-09, mtk, added SI_TKILL + other minor changes
41 .\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend()
42 .\" out of this page into separate pages.
43 .\" 2010-06-11 Andi Kleen, add hwpoison signal extensions
44 .\" 2010-06-11 mtk, improvements to discussion of various siginfo_t fields.
45 .\" 2015-01-17, Kees Cook <keescook@chromium.org>
46 .\" Added notes on ptrace SIGTRAP and SYS_SECCOMP.
47 .\"
48 .TH SIGACTION 2 2021-03-22 "Linux" "Linux Programmer's Manual"
49 .SH NAME
50 sigaction, rt_sigaction \- examine and change a signal action
51 .SH SYNOPSIS
52 .nf
53 .B #include <signal.h>
54 .PP
55 .BI "int sigaction(int " signum ", const struct sigaction *restrict " act ,
56 .BI " struct sigaction *restrict " oldact );
57 .fi
58 .PP
59 .RS -4
60 Feature Test Macro Requirements for glibc (see
61 .BR feature_test_macros (7)):
62 .RE
63 .PP
64 .BR sigaction ():
65 .nf
66 _POSIX_C_SOURCE
67 .fi
68 .PP
69 .IR siginfo_t :
70 .nf
71 _POSIX_C_SOURCE >= 199309L
72 .fi
73 .SH DESCRIPTION
74 The
75 .BR sigaction ()
76 system call is used to change the action taken by a process on
77 receipt of a specific signal.
78 (See
79 .BR signal (7)
80 for an overview of signals.)
81 .PP
82 .I signum
83 specifies the signal and can be any valid signal except
84 .B SIGKILL
85 and
86 .BR SIGSTOP .
87 .PP
88 If
89 .I act
90 is non-NULL, the new action for signal
91 .I signum
92 is installed from
93 .IR act .
94 If
95 .I oldact
96 is non-NULL, the previous action is saved in
97 .IR oldact .
98 .PP
99 The
100 .I sigaction
101 structure is defined as something like:
102 .PP
103 .in +4n
104 .EX
105 struct sigaction {
106 void (*sa_handler)(int);
107 void (*sa_sigaction)(int, siginfo_t *, void *);
108 sigset_t sa_mask;
109 int sa_flags;
110 void (*sa_restorer)(void);
111 };
112 .EE
113 .in
114 .PP
115 On some architectures a union is involved: do not assign to both
116 .I sa_handler
117 and
118 .IR sa_sigaction .
119 .PP
120 The
121 .I sa_restorer
122 field is not intended for application use.
123 (POSIX does not specify a
124 .I sa_restorer
125 field.)
126 Some further details of the purpose of this field can be found in
127 .BR sigreturn (2).
128 .PP
129 .I sa_handler
130 specifies the action to be associated with
131 .I signum
132 and is be one of the following:
133 .IP * 2
134 .B SIG_DFL
135 for the default action.
136 .IP *
137 .B SIG_IGN
138 to ignore this signal.
139 .IP *
140 A pointer to a signal handling function.
141 This function receives the signal number as its only argument.
142 .PP
143 If
144 .B SA_SIGINFO
145 is specified in
146 .IR sa_flags ,
147 then
148 .I sa_sigaction
149 (instead of
150 .IR sa_handler )
151 specifies the signal-handling function for
152 .IR signum .
153 This function receives three arguments, as described below.
154 .PP
155 .I sa_mask
156 specifies a mask of signals which should be blocked
157 (i.e., added to the signal mask of the thread in which
158 the signal handler is invoked)
159 during execution of the signal handler.
160 In addition, the signal which triggered the handler
161 will be blocked, unless the
162 .B SA_NODEFER
163 flag is used.
164 .PP
165 .I sa_flags
166 specifies a set of flags which modify the behavior of the signal.
167 It is formed by the bitwise OR of zero or more of the following:
168 .TP
169 .B SA_NOCLDSTOP
170 If
171 .I signum
172 is
173 .BR SIGCHLD ,
174 do not receive notification when child processes stop (i.e., when they
175 receive one of
176 .BR SIGSTOP ", " SIGTSTP ", " SIGTTIN ,
177 or
178 .BR SIGTTOU )
179 or resume (i.e., they receive
180 .BR SIGCONT )
181 (see
182 .BR wait (2)).
183 This flag is meaningful only when establishing a handler for
184 .BR SIGCHLD .
185 .TP
186 .BR SA_NOCLDWAIT " (since Linux 2.6)"
187 .\" To be precise: Linux 2.5.60 -- MTK
188 If
189 .I signum
190 is
191 .BR SIGCHLD ,
192 do not transform children into zombies when they terminate.
193 See also
194 .BR waitpid (2).
195 This flag is meaningful only when establishing a handler for
196 .BR SIGCHLD ,
197 or when setting that signal's disposition to
198 .BR SIG_DFL .
199 .IP
200 If the
201 .B SA_NOCLDWAIT
202 flag is set when establishing a handler for
203 .BR SIGCHLD ,
204 POSIX.1 leaves it unspecified whether a
205 .B SIGCHLD
206 signal is generated when a child process terminates.
207 On Linux, a
208 .B SIGCHLD
209 signal is generated in this case;
210 on some other implementations, it is not.
211 .TP
212 .B SA_NODEFER
213 Do not add the signal to the thread's signal mask while the
214 handler is executing, unless the signal is specified in
215 .IR act.sa_mask .
216 Consequently, a further instance of the signal may be delivered
217 to the thread while it is executing the handler.
218 This flag is meaningful only when establishing a signal handler.
219 .IP
220 .B SA_NOMASK
221 is an obsolete, nonstandard synonym for this flag.
222 .TP
223 .B SA_ONSTACK
224 Call the signal handler on an alternate signal stack provided by
225 .BR sigaltstack (2).
226 If an alternate stack is not available, the default stack will be used.
227 This flag is meaningful only when establishing a signal handler.
228 .TP
229 .BR SA_RESETHAND
230 Restore the signal action to the default upon entry to the signal handler.
231 This flag is meaningful only when establishing a signal handler.
232 .IP
233 .B SA_ONESHOT
234 is an obsolete, nonstandard synonym for this flag.
235 .TP
236 .B SA_RESTART
237 Provide behavior compatible with BSD signal semantics by making certain
238 system calls restartable across signals.
239 This flag is meaningful only when establishing a signal handler.
240 See
241 .BR signal (7)
242 for a discussion of system call restarting.
243 .TP
244 .BR SA_RESTORER
245 .IR "Not intended for application use" .
246 This flag is used by C libraries to indicate that the
247 .IR sa_restorer
248 field contains the address of a "signal trampoline".
249 See
250 .BR sigreturn (2)
251 for more details.
252 .TP
253 .BR SA_SIGINFO " (since Linux 2.2)"
254 The signal handler takes three arguments, not one.
255 In this case,
256 .I sa_sigaction
257 should be set instead of
258 .IR sa_handler .
259 This flag is meaningful only when establishing a signal handler.
260 .\" (The
261 .\" .I sa_sigaction
262 .\" field was added in Linux 2.1.86.)
263 .\"
264 .SS The siginfo_t argument to a SA_SIGINFO handler
265 When the
266 .B SA_SIGINFO
267 flag is specified in
268 .IR act.sa_flags ,
269 the signal handler address is passed via the
270 .IR act.sa_sigaction
271 field.
272 This handler takes three arguments, as follows:
273 .PP
274 .in +4n
275 .EX
276 void
277 handler(int sig, siginfo_t *info, void *ucontext)
278 {
279 ...
280 }
281 .EE
282 .in
283 .PP
284 These three arguments are as follows
285 .TP
286 .I sig
287 The number of the signal that caused invocation of the handler.
288 .TP
289 .I info
290 A pointer to a
291 .IR siginfo_t ,
292 which is a structure containing further information about the signal,
293 as described below.
294 .TP
295 .I ucontext
296 This is a pointer to a
297 .I ucontext_t
298 structure, cast to \fIvoid\ *\fP.
299 The structure pointed to by this field contains
300 signal context information that was saved
301 on the user-space stack by the kernel; for details, see
302 .BR sigreturn (2).
303 Further information about the
304 .IR ucontext_t
305 structure can be found in
306 .BR getcontext (3)
307 and
308 .BR signal (7).
309 Commonly, the handler function doesn't make any use of the third argument.
310 .PP
311 The
312 .I siginfo_t
313 data type is a structure with the following fields:
314 .PP
315 .in +4n
316 .EX
317 siginfo_t {
318 int si_signo; /* Signal number */
319 int si_errno; /* An errno value */
320 int si_code; /* Signal code */
321 int si_trapno; /* Trap number that caused
322 hardware\-generated signal
323 (unused on most architectures) */
324 .\" FIXME
325 .\" The siginfo_t 'si_trapno' field seems to be used
326 .\" only on SPARC and Alpha; this page could use
327 .\" a little more detail on its purpose there.
328 pid_t si_pid; /* Sending process ID */
329 uid_t si_uid; /* Real user ID of sending process */
330 int si_status; /* Exit value or signal */
331 clock_t si_utime; /* User time consumed */
332 clock_t si_stime; /* System time consumed */
333 union sigval si_value; /* Signal value */
334 int si_int; /* POSIX.1b signal */
335 void *si_ptr; /* POSIX.1b signal */
336 int si_overrun; /* Timer overrun count;
337 POSIX.1b timers */
338 int si_timerid; /* Timer ID; POSIX.1b timers */
339 .\" In the kernel: si_tid
340 void *si_addr; /* Memory location which caused fault */
341 long si_band; /* Band event (was \fIint\fP in
342 glibc 2.3.2 and earlier) */
343 int si_fd; /* File descriptor */
344 short si_addr_lsb; /* Least significant bit of address
345 (since Linux 2.6.32) */
346 void *si_lower; /* Lower bound when address violation
347 occurred (since Linux 3.19) */
348 void *si_upper; /* Upper bound when address violation
349 occurred (since Linux 3.19) */
350 int si_pkey; /* Protection key on PTE that caused
351 fault (since Linux 4.6) */
352 void *si_call_addr; /* Address of system call instruction
353 (since Linux 3.5) */
354 int si_syscall; /* Number of attempted system call
355 (since Linux 3.5) */
356 unsigned int si_arch; /* Architecture of attempted system call
357 (since Linux 3.5) */
358 }
359 .EE
360 .in
361 .PP
362 .IR si_signo ", " si_errno " and " si_code
363 are defined for all signals.
364 .RI ( si_errno
365 is generally unused on Linux.)
366 The rest of the struct may be a union, so that one should
367 read only the fields that are meaningful for the given signal:
368 .IP * 2
369 Signals sent with
370 .BR kill (2)
371 and
372 .BR sigqueue (3)
373 fill in
374 .IR si_pid " and " si_uid .
375 In addition, signals sent with
376 .BR sigqueue (3)
377 fill in
378 .IR si_int " and " si_ptr
379 with the values specified by the sender of the signal;
380 see
381 .BR sigqueue (3)
382 for more details.
383 .IP *
384 Signals sent by POSIX.1b timers (since Linux 2.6) fill in
385 .I si_overrun
386 and
387 .IR si_timerid .
388 The
389 .I si_timerid
390 field is an internal ID used by the kernel to identify
391 the timer; it is not the same as the timer ID returned by
392 .BR timer_create (2).
393 The
394 .I si_overrun
395 field is the timer overrun count;
396 this is the same information as is obtained by a call to
397 .BR timer_getoverrun (2).
398 These fields are nonstandard Linux extensions.
399 .IP *
400 Signals sent for message queue notification (see the description of
401 .B SIGEV_SIGNAL
402 in
403 .BR mq_notify (3))
404 fill in
405 .IR si_int / si_ptr ,
406 with the
407 .I sigev_value
408 supplied to
409 .BR mq_notify (3);
410 .IR si_pid ,
411 with the process ID of the message sender; and
412 .IR si_uid ,
413 with the real user ID of the message sender.
414 .IP *
415 .B SIGCHLD
416 fills in
417 .IR si_pid ", " si_uid ", " si_status ", " si_utime ", and " si_stime ,
418 providing information about the child.
419 The
420 .I si_pid
421 field is the process ID of the child;
422 .I si_uid
423 is the child's real user ID.
424 The
425 .I si_status
426 field contains the exit status of the child (if
427 .I si_code
428 is
429 .BR CLD_EXITED ),
430 or the signal number that caused the process to change state.
431 The
432 .I si_utime
433 and
434 .I si_stime
435 contain the user and system CPU time used by the child process;
436 these fields do not include the times used by waited-for children (unlike
437 .BR getrusage (2)
438 and
439 .BR times (2)).
440 In kernels up to 2.6, and since 2.6.27, these fields report
441 CPU time in units of
442 .IR sysconf(_SC_CLK_TCK) .
443 In 2.6 kernels before 2.6.27,
444 a bug meant that these fields reported time in units
445 of the (configurable) system jiffy (see
446 .BR time (7)).
447 .\" FIXME .
448 .\" When si_utime and si_stime where originally implemented, the
449 .\" measurement unit was HZ, which was the same as clock ticks
450 .\" (sysconf(_SC_CLK_TCK)). In 2.6, HZ became configurable, and
451 .\" was *still* used as the unit to return the info these fields,
452 .\" with the result that the field values depended on the
453 .\" configured HZ. Of course, the should have been measured in
454 .\" USER_HZ instead, so that sysconf(_SC_CLK_TCK) could be used to
455 .\" convert to seconds. I have a queued patch to fix this:
456 .\" http://thread.gmane.org/gmane.linux.kernel/698061/ .
457 .\" This patch made it into 2.6.27.
458 .\" But note that these fields still don't return the times of
459 .\" waited-for children (as is done by getrusage() and times()
460 .\" and wait4()). Solaris 8 does include child times.
461 .IP *
462 .BR SIGILL ,
463 .BR SIGFPE ,
464 .BR SIGSEGV ,
465 .BR SIGBUS ,
466 and
467 .BR SIGTRAP
468 fill in
469 .I si_addr
470 with the address of the fault.
471 On some architectures,
472 these signals also fill in the
473 .I si_trapno
474 field.
475 .IP
476 Some suberrors of
477 .BR SIGBUS ,
478 in particular
479 .B BUS_MCEERR_AO
480 and
481 .BR BUS_MCEERR_AR ,
482 also fill in
483 .IR si_addr_lsb .
484 This field indicates the least significant bit of the reported address
485 and therefore the extent of the corruption.
486 For example, if a full page was corrupted,
487 .I si_addr_lsb
488 contains
489 .IR log2(sysconf(_SC_PAGESIZE)) .
490 When
491 .BR SIGTRAP
492 is delivered in response to a
493 .BR ptrace (2)
494 event (PTRACE_EVENT_foo),
495 .I si_addr
496 is not populated, but
497 .I si_pid
498 and
499 .I si_uid
500 are populated with the respective process ID and user ID responsible for
501 delivering the trap.
502 In the case of
503 .BR seccomp (2),
504 the tracee will be shown as delivering the event.
505 .B BUS_MCEERR_*
506 and
507 .I si_addr_lsb
508 are Linux-specific extensions.
509 .IP
510 The
511 .BR SEGV_BNDERR
512 suberror of
513 .B SIGSEGV
514 populates
515 .IR si_lower
516 and
517 .IR si_upper .
518 .IP
519 The
520 .BR SEGV_PKUERR
521 suberror of
522 .B SIGSEGV
523 populates
524 .IR si_pkey .
525 .IP *
526 .BR SIGIO / SIGPOLL
527 (the two names are synonyms on Linux)
528 fills in
529 .IR si_band " and " si_fd .
530 The
531 .I si_band
532 event is a bit mask containing the same values as are filled in the
533 .I revents
534 field by
535 .BR poll (2).
536 The
537 .I si_fd
538 field indicates the file descriptor for which the I/O event occurred;
539 for further details, see the description of
540 .BR F_SETSIG
541 in
542 .BR fcntl (2).
543 .IP *
544 .BR SIGSYS ,
545 generated (since Linux 3.5)
546 .\" commit a0727e8ce513fe6890416da960181ceb10fbfae6
547 when a seccomp filter returns
548 .BR SECCOMP_RET_TRAP ,
549 fills in
550 .IR si_call_addr ,
551 .IR si_syscall ,
552 .IR si_arch ,
553 .IR si_errno ,
554 and other fields as described in
555 .BR seccomp (2).
556 .\"
557 .SS
558 The si_code field
559 The
560 .I si_code
561 field inside the
562 .I siginfo_t
563 argument that is passed to a
564 .B SA_SIGINFO
565 signal handler is a value (not a bit mask)
566 indicating why this signal was sent.
567 For a
568 .BR ptrace (2)
569 event,
570 .I si_code
571 will contain
572 .BR SIGTRAP
573 and have the ptrace event in the high byte:
574 .PP
575 .in +4n
576 .EX
577 (SIGTRAP | PTRACE_EVENT_foo << 8).
578 .EE
579 .in
580 .PP
581 For a
582 .RB non- ptrace (2)
583 event, the values that can appear in
584 .I si_code
585 are described in the remainder of this section.
586 Since glibc 2.20,
587 the definitions of most of these symbols are obtained from
588 .I <signal.h>
589 by defining feature test macros (before including
590 .I any
591 header file) as follows:
592 .IP * 3
593 .B _XOPEN_SOURCE
594 with the value 500 or greater;
595 .IP *
596 .B _XOPEN_SOURCE
597 and
598 .BR _XOPEN_SOURCE_EXTENDED ;
599 or
600 .IP *
601 .B _POSIX_C_SOURCE
602 with the value 200809L or greater.
603 .PP
604 For the
605 .B TRAP_*
606 constants, the symbol definitions are provided only in the first two cases.
607 Before glibc 2.20, no feature test macros were required to obtain these symbols.
608 .PP
609 For a regular signal, the following list shows the values which can be
610 placed in
611 .I si_code
612 for any signal, along with the reason that the signal was generated.
613 .RS 4
614 .TP
615 .B SI_USER
616 .BR kill (2).
617 .TP
618 .B SI_KERNEL
619 Sent by the kernel.
620 .TP
621 .B SI_QUEUE
622 .BR sigqueue (3).
623 .TP
624 .B SI_TIMER
625 POSIX timer expired.
626 .TP
627 .BR SI_MESGQ " (since Linux 2.6.6)"
628 POSIX message queue state changed; see
629 .BR mq_notify (3).
630 .TP
631 .B SI_ASYNCIO
632 AIO completed.
633 .TP
634 .B SI_SIGIO
635 Queued
636 .B SIGIO
637 (only in kernels up to Linux 2.2; from Linux 2.4 onward
638 .BR SIGIO / SIGPOLL
639 fills in
640 .I si_code
641 as described below).
642 .TP
643 .BR SI_TKILL " (since Linux 2.4.19)"
644 .BR tkill (2)
645 or
646 .BR tgkill (2).
647 .\" SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented
648 .\" It appears to have been an idea that was tried during 2.5.6
649 .\" through to 2.5.24 and then was backed out.
650 .RE
651 .PP
652 The following values can be placed in
653 .I si_code
654 for a
655 .B SIGILL
656 signal:
657 .RS 4
658 .TP
659 .B ILL_ILLOPC
660 Illegal opcode.
661 .TP
662 .B ILL_ILLOPN
663 Illegal operand.
664 .TP
665 .B ILL_ILLADR
666 Illegal addressing mode.
667 .TP
668 .B ILL_ILLTRP
669 Illegal trap.
670 .TP
671 .B ILL_PRVOPC
672 Privileged opcode.
673 .TP
674 .B ILL_PRVREG
675 Privileged register.
676 .TP
677 .B ILL_COPROC
678 Coprocessor error.
679 .TP
680 .B ILL_BADSTK
681 Internal stack error.
682 .RE
683 .PP
684 The following values can be placed in
685 .I si_code
686 for a
687 .B SIGFPE
688 signal:
689 .RS 4
690 .TP
691 .B FPE_INTDIV
692 Integer divide by zero.
693 .TP
694 .B FPE_INTOVF
695 Integer overflow.
696 .TP
697 .B FPE_FLTDIV
698 Floating-point divide by zero.
699 .TP
700 .B FPE_FLTOVF
701 Floating-point overflow.
702 .TP
703 .B FPE_FLTUND
704 Floating-point underflow.
705 .TP
706 .B FPE_FLTRES
707 Floating-point inexact result.
708 .TP
709 .B FPE_FLTINV
710 Floating-point invalid operation.
711 .TP
712 .B FPE_FLTSUB
713 Subscript out of range.
714 .RE
715 .PP
716 The following values can be placed in
717 .I si_code
718 for a
719 .B SIGSEGV
720 signal:
721 .RS 4
722 .TP
723 .B SEGV_MAPERR
724 Address not mapped to object.
725 .TP
726 .B SEGV_ACCERR
727 Invalid permissions for mapped object.
728 .TP
729 .BR SEGV_BNDERR " (since Linux 3.19)"
730 .\" commit ee1b58d36aa1b5a79eaba11f5c3633c88231da83
731 Failed address bound checks.
732 .TP
733 .BR SEGV_PKUERR " (since Linux 4.6)"
734 .\" commit cd0ea35ff5511cde299a61c21a95889b4a71464e
735 Access was denied by memory protection keys.
736 See
737 .BR pkeys (7).
738 The protection key which applied to this access is available via
739 .IR si_pkey .
740 .RE
741 .PP
742 The following values can be placed in
743 .I si_code
744 for a
745 .B SIGBUS
746 signal:
747 .RS 4
748 .TP
749 .B BUS_ADRALN
750 Invalid address alignment.
751 .TP
752 .B BUS_ADRERR
753 Nonexistent physical address.
754 .TP
755 .B BUS_OBJERR
756 Object-specific hardware error.
757 .TP
758 .BR BUS_MCEERR_AR " (since Linux 2.6.32)"
759 Hardware memory error consumed on a machine check; action required.
760 .TP
761 .BR BUS_MCEERR_AO " (since Linux 2.6.32)"
762 Hardware memory error detected in process but not consumed; action optional.
763 .RE
764 .PP
765 The following values can be placed in
766 .I si_code
767 for a
768 .B SIGTRAP
769 signal:
770 .RS 4
771 .TP
772 .B TRAP_BRKPT
773 Process breakpoint.
774 .TP
775 .B TRAP_TRACE
776 Process trace trap.
777 .TP
778 .BR TRAP_BRANCH " (since Linux 2.4, IA64 only)"
779 Process taken branch trap.
780 .TP
781 .BR TRAP_HWBKPT " (since Linux 2.4, IA64 only)"
782 Hardware breakpoint/watchpoint.
783 .RE
784 .PP
785 The following values can be placed in
786 .I si_code
787 for a
788 .B SIGCHLD
789 signal:
790 .RS 4
791 .TP
792 .B CLD_EXITED
793 Child has exited.
794 .TP
795 .B CLD_KILLED
796 Child was killed.
797 .TP
798 .B CLD_DUMPED
799 Child terminated abnormally.
800 .TP
801 .B CLD_TRAPPED
802 Traced child has trapped.
803 .TP
804 .B CLD_STOPPED
805 Child has stopped.
806 .TP
807 .BR CLD_CONTINUED " (since Linux 2.6.9)"
808 Stopped child has continued.
809 .RE
810 .PP
811 The following values can be placed in
812 .I si_code
813 for a
814 .BR SIGIO / SIGPOLL
815 signal:
816 .RS 4
817 .TP
818 .B POLL_IN
819 Data input available.
820 .TP
821 .B POLL_OUT
822 Output buffers available.
823 .TP
824 .B POLL_MSG
825 Input message available.
826 .TP
827 .B POLL_ERR
828 I/O error.
829 .TP
830 .B POLL_PRI
831 High priority input available.
832 .TP
833 .B POLL_HUP
834 Device disconnected.
835 .RE
836 .PP
837 The following value can be placed in
838 .I si_code
839 for a
840 .BR SIGSYS
841 signal:
842 .RS 4
843 .TP
844 .BR SYS_SECCOMP " (since Linux 3.5)"
845 Triggered by a
846 .BR seccomp (2)
847 filter rule.
848 .RE
849 .SH RETURN VALUE
850 .BR sigaction ()
851 returns 0 on success; on error, \-1 is returned, and
852 .I errno
853 is set to indicate the error.
854 .SH ERRORS
855 .TP
856 .B EFAULT
857 .IR act " or " oldact
858 points to memory which is not a valid part of the process address space.
859 .TP
860 .B EINVAL
861 An invalid signal was specified.
862 This will also be generated if an attempt
863 is made to change the action for
864 .BR SIGKILL " or " SIGSTOP ,
865 which cannot be caught or ignored.
866 .SH CONFORMING TO
867 POSIX.1-2001, POSIX.1-2008, SVr4.
868 .\" SVr4 does not document the EINTR condition.
869 .SH NOTES
870 A child created via
871 .BR fork (2)
872 inherits a copy of its parent's signal dispositions.
873 During an
874 .BR execve (2),
875 the dispositions of handled signals are reset to the default;
876 the dispositions of ignored signals are left unchanged.
877 .PP
878 According to POSIX, the behavior of a process is undefined after it
879 ignores a
880 .BR SIGFPE ,
881 .BR SIGILL ,
882 or
883 .B SIGSEGV
884 signal that was not generated by
885 .BR kill (2)
886 or
887 .BR raise (3).
888 Integer division by zero has undefined result.
889 On some architectures it will generate a
890 .B SIGFPE
891 signal.
892 (Also dividing the most negative integer by \-1 may generate
893 .BR SIGFPE .)
894 Ignoring this signal might lead to an endless loop.
895 .PP
896 POSIX.1-1990 disallowed setting the action for
897 .B SIGCHLD
898 to
899 .BR SIG_IGN .
900 POSIX.1-2001 and later allow this possibility, so that ignoring
901 .B SIGCHLD
902 can be used to prevent the creation of zombies (see
903 .BR wait (2)).
904 Nevertheless, the historical BSD and System\ V behaviors for ignoring
905 .B SIGCHLD
906 differ, so that the only completely portable method of ensuring that
907 terminated children do not become zombies is to catch the
908 .B SIGCHLD
909 signal and perform a
910 .BR wait (2)
911 or similar.
912 .PP
913 POSIX.1-1990 specified only
914 .BR SA_NOCLDSTOP .
915 POSIX.1-2001 added
916 .BR SA_NOCLDSTOP ,
917 .BR SA_NOCLDWAIT ,
918 .BR SA_NODEFER ,
919 .BR SA_ONSTACK ,
920 .BR SA_RESETHAND ,
921 .BR SA_RESTART ,
922 and
923 .BR SA_SIGINFO .
924 Use of these latter values in
925 .I sa_flags
926 may be less portable in applications intended for older
927 UNIX implementations.
928 .PP
929 The
930 .B SA_RESETHAND
931 flag is compatible with the SVr4 flag of the same name.
932 .PP
933 The
934 .B SA_NODEFER
935 flag is compatible with the SVr4 flag of the same name under kernels
936 1.3.9 and later.
937 On older kernels the Linux implementation
938 allowed the receipt of any signal, not just the one we are installing
939 (effectively overriding any
940 .I sa_mask
941 settings).
942 .PP
943 .BR sigaction ()
944 can be called with a NULL second argument to query the current signal
945 handler.
946 It can also be used to check whether a given signal is valid for
947 the current machine by calling it with NULL second and third arguments.
948 .PP
949 It is not possible to block
950 .BR SIGKILL " or " SIGSTOP
951 (by specifying them in
952 .IR sa_mask ).
953 Attempts to do so are silently ignored.
954 .PP
955 See
956 .BR sigsetops (3)
957 for details on manipulating signal sets.
958 .PP
959 See
960 .BR signal\-safety (7)
961 for a list of the async-signal-safe functions that can be
962 safely called inside from inside a signal handler.
963 .\"
964 .SS C library/kernel differences
965 The glibc wrapper function for
966 .BR sigaction ()
967 gives an error
968 .RB ( EINVAL )
969 on attempts to change the disposition of the two real-time signals
970 used internally by the NPTL threading implementation.
971 See
972 .BR nptl (7)
973 for details.
974 .PP
975 On architectures where the signal trampoline resides in the C library,
976 the glibc wrapper function for
977 .BR sigaction ()
978 places the address of the trampoline code in the
979 .I act.sa_restorer
980 field and sets the
981 .B SA_RESTORER
982 flag in the
983 .IR act.sa_flags
984 field.
985 See
986 .BR sigreturn (2).
987 .PP
988 The original Linux system call was named
989 .BR sigaction ().
990 However, with the addition of real-time signals in Linux 2.2,
991 the fixed-size, 32-bit
992 .IR sigset_t
993 type supported by that system call was no longer fit for purpose.
994 Consequently, a new system call,
995 .BR rt_sigaction (),
996 was added to support an enlarged
997 .IR sigset_t
998 type.
999 The new system call takes a fourth argument,
1000 .IR "size_t sigsetsize" ,
1001 which specifies the size in bytes of the signal sets in
1002 .IR act.sa_mask
1003 and
1004 .IR oldact.sa_mask .
1005 This argument is currently required to have the value
1006 .IR sizeof(sigset_t)
1007 (or the error
1008 .B EINVAL
1009 results).
1010 The glibc
1011 .BR sigaction ()
1012 wrapper function hides these details from us, transparently calling
1013 .BR rt_sigaction ()
1014 when the kernel provides it.
1015 .\"
1016 .SS Undocumented
1017 Before the introduction of
1018 .BR SA_SIGINFO ,
1019 it was also possible to get some additional information about the signal.
1020 This was done by providing an
1021 .I sa_handler
1022 signal handler with a second argument of type
1023 .IR "struct sigcontext" ,
1024 which is the same structure as the one that is passed in the
1025 .I uc_mcontext
1026 field of the
1027 .I ucontext
1028 structure that is passed (via a pointer) in the third argument of the
1029 .I sa_sigaction
1030 handler.
1031 See the relevant Linux kernel sources for details.
1032 This use is obsolete now.
1033 .SH BUGS
1034 When delivering a signal with a
1035 .B SA_SIGINFO
1036 handler,
1037 the kernel does not always provide meaningful values
1038 for all of the fields of the
1039 .I siginfo_t
1040 that are relevant for that signal.
1041 .PP
1042 In kernels up to and including 2.6.13, specifying
1043 .B SA_NODEFER
1044 in
1045 .I sa_flags
1046 prevents not only the delivered signal from being masked during
1047 execution of the handler, but also the signals specified in
1048 .IR sa_mask .
1049 This bug was fixed in kernel 2.6.14.
1050 .\" commit 69be8f189653cd81aae5a74e26615b12871bb72e
1051 .SH EXAMPLES
1052 See
1053 .BR mprotect (2).
1054 .SH SEE ALSO
1055 .BR kill (1),
1056 .BR kill (2),
1057 .BR pause (2),
1058 .BR pidfd_send_signal (2),
1059 .BR restart_syscall (2),
1060 .BR seccomp (2),
1061 .BR sigaltstack (2),
1062 .BR signal (2),
1063 .BR signalfd (2),
1064 .BR sigpending (2),
1065 .BR sigprocmask (2),
1066 .BR sigreturn (2),
1067 .BR sigsuspend (2),
1068 .BR wait (2),
1069 .BR killpg (3),
1070 .BR raise (3),
1071 .BR siginterrupt (3),
1072 .BR sigqueue (3),
1073 .BR sigsetops (3),
1074 .BR sigvec (3),
1075 .BR core (5),
1076 .BR signal (7)