Debian Codegraph @

upstream/debian-unstable/man2/sigaction.2

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