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