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
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.
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.
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
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
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>
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.
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.
48 .TH SIGACTION 2 2021-03-22 "Linux" "Linux Programmer's Manual"
50 sigaction, rt_sigaction \- examine and change a signal action
53 .B #include <signal.h>
55 .BI "int sigaction(int " signum ", const struct sigaction *restrict " act ,
56 .BI " struct sigaction *restrict " oldact );
60 Feature Test Macro Requirements for glibc (see
61 .BR feature_test_macros (7)):
71 _POSIX_C_SOURCE >= 199309L
76 system call is used to change the action taken by a process on
77 receipt of a specific signal.
80 for an overview of signals.)
83 specifies the signal and can be any valid signal except
90 is non-NULL, the new action for signal
96 is non-NULL, the previous action is saved in
101 structure is defined as something like:
106 void (*sa_handler)(int);
107 void (*sa_sigaction)(int, siginfo_t *, void *);
110 void (*sa_restorer)(void);
115 On some architectures a union is involved: do not assign to both
122 field is not intended for application use.
123 (POSIX does not specify a
126 Some further details of the purpose of this field can be found in
130 specifies the action to be associated with
132 and is be one of the following:
135 for the default action.
138 to ignore this signal.
140 A pointer to a signal handling function.
141 This function receives the signal number as its only argument.
151 specifies the signal-handling function for
153 This function receives three arguments, as described below.
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
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:
174 do not receive notification when child processes stop (i.e., when they
176 .BR SIGSTOP ", " SIGTSTP ", " SIGTTIN ,
179 or resume (i.e., they receive
183 This flag is meaningful only when establishing a handler for
186 .BR SA_NOCLDWAIT " (since Linux 2.6)"
187 .\" To be precise: Linux 2.5.60 -- MTK
192 do not transform children into zombies when they terminate.
195 This flag is meaningful only when establishing a handler for
197 or when setting that signal's disposition to
202 flag is set when establishing a handler for
204 POSIX.1 leaves it unspecified whether a
206 signal is generated when a child process terminates.
209 signal is generated in this case;
210 on some other implementations, it is not.
213 Do not add the signal to the thread's signal mask while the
214 handler is executing, unless the signal is specified in
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.
221 is an obsolete, nonstandard synonym for this flag.
224 Call the signal handler on an alternate signal stack provided by
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.
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.
234 is an obsolete, nonstandard synonym for this flag.
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.
242 for a discussion of system call restarting.
245 .IR "Not intended for application use" .
246 This flag is used by C libraries to indicate that the
248 field contains the address of a "signal trampoline".
253 .BR SA_SIGINFO " (since Linux 2.2)"
254 The signal handler takes three arguments, not one.
257 should be set instead of
259 This flag is meaningful only when establishing a signal handler.
262 .\" field was added in Linux 2.1.86.)
266 Used to dynamically probe for flag bit support.
268 If an attempt to register a handler succeeds with this flag set in
270 alongside other flags that are potentially unsupported by the kernel,
271 and an immediately subsequent
273 call specifying the same signal number and with a non-NULL
279 .IR oldact->sa_flags ,
282 may be used as a bitmask
283 describing which of the potentially unsupported flags are,
285 See the section "Dynamically probing for flag bit support"
286 below for more details.
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
295 an architecture-specific subset of the tag bits will be preserved in
298 Programs that need to be compatible with Linux versions older than 5.11
301 to probe for support.
302 .SS The siginfo_t argument to a SA_SIGINFO handler
307 the signal handler address is passed via the
310 This handler takes three arguments, as follows:
315 handler(int sig, siginfo_t *info, void *ucontext)
322 These three arguments are as follows
325 The number of the signal that caused invocation of the handler.
330 which is a structure containing further information about the signal,
334 This is a pointer to a
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
341 Further information about the
343 structure can be found in
347 Commonly, the handler function doesn't make any use of the third argument.
351 data type is a structure with the following fields:
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) */
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;
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
392 int si_syscall; /* Number of attempted system call
394 unsigned int si_arch; /* Architecture of attempted system call
400 .IR si_signo ", " si_errno " and " si_code
401 are defined for all signals.
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:
412 .IR si_pid " and " si_uid .
413 In addition, signals sent with
416 .IR si_int " and " si_ptr
417 with the values specified by the sender of the signal;
422 Signals sent by POSIX.1b timers (since Linux 2.6) fill in
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).
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.
438 Signals sent for message queue notification (see the description of
443 .IR si_int / si_ptr ,
449 with the process ID of the message sender; and
451 with the real user ID of the message sender.
455 .IR si_pid ", " si_uid ", " si_status ", " si_utime ", and " si_stime ,
456 providing information about the child.
459 field is the process ID of the child;
461 is the child's real user ID.
464 field contains the exit status of the child (if
468 or the signal number that caused the process to change state.
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
478 In kernels up to 2.6, and since 2.6.27, these fields report
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
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.
508 with the address of the fault.
509 On some architectures,
510 these signals also fill in the
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,
527 .IR log2(sysconf(_SC_PAGESIZE)) .
530 is delivered in response to a
532 event (PTRACE_EVENT_foo),
534 is not populated, but
538 are populated with the respective process ID and user ID responsible for
542 the tracee will be shown as delivering the event.
546 are Linux-specific extensions.
565 (the two names are synonyms on Linux)
567 .IR si_band " and " si_fd .
570 event is a bit mask containing the same values as are filled in the
576 field indicates the file descriptor for which the I/O event occurred;
577 for further details, see the description of
583 generated (since Linux 3.5)
584 .\" commit a0727e8ce513fe6890416da960181ceb10fbfae6
585 when a seccomp filter returns
586 .BR SECCOMP_RET_TRAP ,
592 and other fields as described in
601 argument that is passed to a
603 signal handler is a value (not a bit mask)
604 indicating why this signal was sent.
611 and have the ptrace event in the high byte:
615 (SIGTRAP | PTRACE_EVENT_foo << 8).
621 event, the values that can appear in
623 are described in the remainder of this section.
625 the definitions of most of these symbols are obtained from
627 by defining feature test macros (before including
629 header file) as follows:
632 with the value 500 or greater;
636 .BR _XOPEN_SOURCE_EXTENDED ;
640 with the value 200809L or greater.
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.
647 For a regular signal, the following list shows the values which can be
650 for any signal, along with the reason that the signal was generated.
665 .BR SI_MESGQ " (since Linux 2.6.6)"
666 POSIX message queue state changed; see
675 (only in kernels up to Linux 2.2; from Linux 2.4 onward
681 .BR SI_TKILL " (since Linux 2.4.19)"
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.
690 The following values can be placed in
704 Illegal addressing mode.
719 Internal stack error.
722 The following values can be placed in
730 Integer divide by zero.
736 Floating-point divide by zero.
739 Floating-point overflow.
742 Floating-point underflow.
745 Floating-point inexact result.
748 Floating-point invalid operation.
751 Subscript out of range.
754 The following values can be placed in
762 Address not mapped to object.
765 Invalid permissions for mapped object.
767 .BR SEGV_BNDERR " (since Linux 3.19)"
768 .\" commit ee1b58d36aa1b5a79eaba11f5c3633c88231da83
769 Failed address bound checks.
771 .BR SEGV_PKUERR " (since Linux 4.6)"
772 .\" commit cd0ea35ff5511cde299a61c21a95889b4a71464e
773 Access was denied by memory protection keys.
776 The protection key which applied to this access is available via
780 The following values can be placed in
788 Invalid address alignment.
791 Nonexistent physical address.
794 Object-specific hardware error.
796 .BR BUS_MCEERR_AR " (since Linux 2.6.32)"
797 Hardware memory error consumed on a machine check; action required.
799 .BR BUS_MCEERR_AO " (since Linux 2.6.32)"
800 Hardware memory error detected in process but not consumed; action optional.
803 The following values can be placed in
816 .BR TRAP_BRANCH " (since Linux 2.4, IA64 only)"
817 Process taken branch trap.
819 .BR TRAP_HWBKPT " (since Linux 2.4, IA64 only)"
820 Hardware breakpoint/watchpoint.
823 The following values can be placed in
837 Child terminated abnormally.
840 Traced child has trapped.
845 .BR CLD_CONTINUED " (since Linux 2.6.9)"
846 Stopped child has continued.
849 The following values can be placed in
857 Data input available.
860 Output buffers available.
863 Input message available.
869 High priority input available.
875 The following value can be placed in
882 .BR SYS_SECCOMP " (since Linux 3.5)"
887 .SS Dynamically probing for flag bit support
890 call on Linux accepts unknown bits set in
893 The behavior of the kernel starting with Linux 5.11 is that a second
895 will clear unknown bits from
896 .IR oldact\->sa_flags .
897 However, historically, a second
899 call would typically leave those bits set in
900 .IR oldact\->sa_flags .
902 This means that support for new flags cannot be detected
903 simply by testing for a flag in
905 and a program must test that
907 has been cleared before relying on the contents of
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
917 in the signal handler itself.
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
932 and, if defined by the architecture,
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.
940 See EXAMPLES below for a demonstration of the use of
944 returns 0 on success; on error, \-1 is returned, and
946 is set to indicate the error.
950 .IR act " or " oldact
951 points to memory which is not a valid part of the process address space.
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.
960 POSIX.1-2001, POSIX.1-2008, SVr4.
961 .\" SVr4 does not document the EINTR condition.
965 inherits a copy of its parent's signal dispositions.
968 the dispositions of handled signals are reset to the default;
969 the dispositions of ignored signals are left unchanged.
971 According to POSIX, the behavior of a process is undefined after it
977 signal that was not generated by
981 Integer division by zero has undefined result.
982 On some architectures it will generate a
985 (Also dividing the most negative integer by \-1 may generate
987 Ignoring this signal might lead to an endless loop.
989 POSIX.1-1990 disallowed setting the action for
993 POSIX.1-2001 and later allow this possibility, so that ignoring
995 can be used to prevent the creation of zombies (see
997 Nevertheless, the historical BSD and System\ V behaviors for ignoring
999 differ, so that the only completely portable method of ensuring that
1000 terminated children do not become zombies is to catch the
1002 signal and perform a
1006 POSIX.1-1990 specified only
1017 Use of these latter values in
1019 may be less portable in applications intended for older
1020 UNIX implementations.
1024 flag is compatible with the SVr4 flag of the same name.
1028 flag is compatible with the SVr4 flag of the same name under kernels
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
1037 can be called with a NULL second argument to query the current signal
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.
1042 It is not possible to block
1043 .BR SIGKILL " or " SIGSTOP
1044 (by specifying them in
1046 Attempts to do so are silently ignored.
1050 for details on manipulating signal sets.
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.
1057 .SS C library/kernel differences
1058 The glibc wrapper function for
1062 on attempts to change the disposition of the two real-time signals
1063 used internally by the NPTL threading implementation.
1068 On architectures where the signal trampoline resides in the C library,
1069 the glibc wrapper function for
1071 places the address of the trampoline code in the
1081 The original Linux system call was named
1083 However, with the addition of real-time signals in Linux 2.2,
1084 the fixed-size, 32-bit
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
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
1097 .IR oldact.sa_mask .
1098 This argument is currently required to have the value
1099 .IR sizeof(sigset_t)
1105 wrapper function hides these details from us, transparently calling
1107 when the kernel provides it.
1110 Before the introduction of
1112 it was also possible to get some additional information about the signal.
1113 This was done by providing an
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
1121 structure that is passed (via a pointer) in the third argument of the
1124 See the relevant Linux kernel sources for details.
1125 This use is obsolete now.
1127 When delivering a signal with a
1130 the kernel does not always provide meaningful values
1131 for all of the fields of the
1133 that are relevant for that signal.
1135 In kernels up to and including 2.6.13, specifying
1139 prevents not only the delivered signal from being masked during
1140 execution of the handler, but also the signals specified in
1142 This bug was fixed in kernel 2.6.14.
1143 .\" commit 69be8f189653cd81aae5a74e26615b12871bb72e
1147 .SS Probing for flag support
1148 The following example program exits with status
1151 .B SA_EXPOSE_TAGBITS
1152 is determined to be supported, and
1163 handler(int signo, siginfo_t *info, void *context)
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);
1172 _exit(EXIT_SUCCESS);
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");
1194 .BR pidfd_send_signal (2),
1195 .BR restart_syscall (2),
1197 .BR sigaltstack (2),
1201 .BR sigprocmask (2),
1207 .BR siginterrupt (3),