Debian Codegraph @

upstream/debian-trixie/man2/sigaction.2

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