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 2020-12-21 "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 *" act ,
56 .BI " struct sigaction *" 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.)
264 .SS The siginfo_t argument to a SA_SIGINFO handler
269 the signal handler address is passed via the
272 This handler takes three arguments, as follows:
277 handler(int sig, siginfo_t *info, void *ucontext)
284 These three arguments are as follows
287 The number of the signal that caused invocation of the handler.
292 which is a structure containing further information about the signal,
296 This is a pointer to a
298 structure, cast to \fIvoid\ *\fP.
299 The structure pointed to by this field contains
300 signal context information that was saved
301 on the user-space stack by the kernel; for details, see
303 Further information about the
305 structure can be found in
309 Commonly, the handler function doesn't make any use of the third argument.
313 data type is a structure with the following fields:
318 int si_signo; /* Signal number */
319 int si_errno; /* An errno value */
320 int si_code; /* Signal code */
321 int si_trapno; /* Trap number that caused
322 hardware\-generated signal
323 (unused on most architectures) */
325 .\" The siginfo_t 'si_trapno' field seems to be used
326 .\" only on SPARC and Alpha; this page could use
327 .\" a little more detail on its purpose there.
328 pid_t si_pid; /* Sending process ID */
329 uid_t si_uid; /* Real user ID of sending process */
330 int si_status; /* Exit value or signal */
331 clock_t si_utime; /* User time consumed */
332 clock_t si_stime; /* System time consumed */
333 union sigval si_value; /* Signal value */
334 int si_int; /* POSIX.1b signal */
335 void *si_ptr; /* POSIX.1b signal */
336 int si_overrun; /* Timer overrun count;
338 int si_timerid; /* Timer ID; POSIX.1b timers */
339 .\" In the kernel: si_tid
340 void *si_addr; /* Memory location which caused fault */
341 long si_band; /* Band event (was \fIint\fP in
342 glibc 2.3.2 and earlier) */
343 int si_fd; /* File descriptor */
344 short si_addr_lsb; /* Least significant bit of address
345 (since Linux 2.6.32) */
346 void *si_lower; /* Lower bound when address violation
347 occurred (since Linux 3.19) */
348 void *si_upper; /* Upper bound when address violation
349 occurred (since Linux 3.19) */
350 int si_pkey; /* Protection key on PTE that caused
351 fault (since Linux 4.6) */
352 void *si_call_addr; /* Address of system call instruction
354 int si_syscall; /* Number of attempted system call
356 unsigned int si_arch; /* Architecture of attempted system call
362 .IR si_signo ", " si_errno " and " si_code
363 are defined for all signals.
365 is generally unused on Linux.)
366 The rest of the struct may be a union, so that one should
367 read only the fields that are meaningful for the given signal:
374 .IR si_pid " and " si_uid .
375 In addition, signals sent with
378 .IR si_int " and " si_ptr
379 with the values specified by the sender of the signal;
384 Signals sent by POSIX.1b timers (since Linux 2.6) fill in
390 field is an internal ID used by the kernel to identify
391 the timer; it is not the same as the timer ID returned by
392 .BR timer_create (2).
395 field is the timer overrun count;
396 this is the same information as is obtained by a call to
397 .BR timer_getoverrun (2).
398 These fields are nonstandard Linux extensions.
400 Signals sent for message queue notification (see the description of
405 .IR si_int / si_ptr ,
411 with the process ID of the message sender; and
413 with the real user ID of the message sender.
417 .IR si_pid ", " si_uid ", " si_status ", " si_utime ", and " si_stime ,
418 providing information about the child.
421 field is the process ID of the child;
423 is the child's real user ID.
426 field contains the exit status of the child (if
430 or the signal number that caused the process to change state.
435 contain the user and system CPU time used by the child process;
436 these fields do not include the times used by waited-for children (unlike
440 In kernels up to 2.6, and since 2.6.27, these fields report
442 .IR sysconf(_SC_CLK_TCK) .
443 In 2.6 kernels before 2.6.27,
444 a bug meant that these fields reported time in units
445 of the (configurable) system jiffy (see
448 .\" When si_utime and si_stime where originally implemented, the
449 .\" measurement unit was HZ, which was the same as clock ticks
450 .\" (sysconf(_SC_CLK_TCK)). In 2.6, HZ became configurable, and
451 .\" was *still* used as the unit to return the info these fields,
452 .\" with the result that the field values depended on the
453 .\" configured HZ. Of course, the should have been measured in
454 .\" USER_HZ instead, so that sysconf(_SC_CLK_TCK) could be used to
455 .\" convert to seconds. I have a queued patch to fix this:
456 .\" http://thread.gmane.org/gmane.linux.kernel/698061/ .
457 .\" This patch made it into 2.6.27.
458 .\" But note that these fields still don't return the times of
459 .\" waited-for children (as is done by getrusage() and times()
460 .\" and wait4()). Solaris 8 does include child times.
470 with the address of the fault.
471 On some architectures,
472 these signals also fill in the
484 This field indicates the least significant bit of the reported address
485 and therefore the extent of the corruption.
486 For example, if a full page was corrupted,
489 .IR log2(sysconf(_SC_PAGESIZE)) .
492 is delivered in response to a
494 event (PTRACE_EVENT_foo),
496 is not populated, but
500 are populated with the respective process ID and user ID responsible for
504 the tracee will be shown as delivering the event.
508 are Linux-specific extensions.
527 (the two names are synonyms on Linux)
529 .IR si_band " and " si_fd .
532 event is a bit mask containing the same values as are filled in the
538 field indicates the file descriptor for which the I/O event occurred;
539 for further details, see the description of
545 generated (since Linux 3.5)
546 .\" commit a0727e8ce513fe6890416da960181ceb10fbfae6
547 when a seccomp filter returns
548 .BR SECCOMP_RET_TRAP ,
554 and other fields as described in
563 argument that is passed to a
565 signal handler is a value (not a bit mask)
566 indicating why this signal was sent.
573 and have the ptrace event in the high byte:
577 (SIGTRAP | PTRACE_EVENT_foo << 8).
583 event, the values that can appear in
585 are described in the remainder of this section.
587 the definitions of most of these symbols are obtained from
589 by defining feature test macros (before including
591 header file) as follows:
594 with the value 500 or greater;
598 .BR _XOPEN_SOURCE_EXTENDED ;
602 with the value 200809L or greater.
606 constants, the symbol definitions are provided only in the first two cases.
607 Before glibc 2.20, no feature test macros were required to obtain these symbols.
609 For a regular signal, the following list shows the values which can be
612 for any signal, along with the reason that the signal was generated.
627 .BR SI_MESGQ " (since Linux 2.6.6)"
628 POSIX message queue state changed; see
637 (only in kernels up to Linux 2.2; from Linux 2.4 onward
643 .BR SI_TKILL " (since Linux 2.4.19)"
647 .\" SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented
648 .\" It appears to have been an idea that was tried during 2.5.6
649 .\" through to 2.5.24 and then was backed out.
652 The following values can be placed in
666 Illegal addressing mode.
681 Internal stack error.
684 The following values can be placed in
692 Integer divide by zero.
698 Floating-point divide by zero.
701 Floating-point overflow.
704 Floating-point underflow.
707 Floating-point inexact result.
710 Floating-point invalid operation.
713 Subscript out of range.
716 The following values can be placed in
724 Address not mapped to object.
727 Invalid permissions for mapped object.
729 .BR SEGV_BNDERR " (since Linux 3.19)"
730 .\" commit ee1b58d36aa1b5a79eaba11f5c3633c88231da83
731 Failed address bound checks.
733 .BR SEGV_PKUERR " (since Linux 4.6)"
734 .\" commit cd0ea35ff5511cde299a61c21a95889b4a71464e
735 Access was denied by memory protection keys.
738 The protection key which applied to this access is available via
742 The following values can be placed in
750 Invalid address alignment.
753 Nonexistent physical address.
756 Object-specific hardware error.
758 .BR BUS_MCEERR_AR " (since Linux 2.6.32)"
759 Hardware memory error consumed on a machine check; action required.
761 .BR BUS_MCEERR_AO " (since Linux 2.6.32)"
762 Hardware memory error detected in process but not consumed; action optional.
765 The following values can be placed in
778 .BR TRAP_BRANCH " (since Linux 2.4, IA64 only)"
779 Process taken branch trap.
781 .BR TRAP_HWBKPT " (since Linux 2.4, IA64 only)"
782 Hardware breakpoint/watchpoint.
785 The following values can be placed in
799 Child terminated abnormally.
802 Traced child has trapped.
807 .BR CLD_CONTINUED " (since Linux 2.6.9)"
808 Stopped child has continued.
811 The following values can be placed in
819 Data input available.
822 Output buffers available.
825 Input message available.
831 High priority input available.
837 The following value can be placed in
844 .BR SYS_SECCOMP " (since Linux 3.5)"
851 returns 0 on success; on error, \-1 is returned, and
853 is set to indicate the error.
857 .IR act " or " oldact
858 points to memory which is not a valid part of the process address space.
861 An invalid signal was specified.
862 This will also be generated if an attempt
863 is made to change the action for
864 .BR SIGKILL " or " SIGSTOP ,
865 which cannot be caught or ignored.
867 POSIX.1-2001, POSIX.1-2008, SVr4.
868 .\" SVr4 does not document the EINTR condition.
872 inherits a copy of its parent's signal dispositions.
875 the dispositions of handled signals are reset to the default;
876 the dispositions of ignored signals are left unchanged.
878 According to POSIX, the behavior of a process is undefined after it
884 signal that was not generated by
888 Integer division by zero has undefined result.
889 On some architectures it will generate a
892 (Also dividing the most negative integer by \-1 may generate
894 Ignoring this signal might lead to an endless loop.
896 POSIX.1-1990 disallowed setting the action for
900 POSIX.1-2001 and later allow this possibility, so that ignoring
902 can be used to prevent the creation of zombies (see
904 Nevertheless, the historical BSD and System\ V behaviors for ignoring
906 differ, so that the only completely portable method of ensuring that
907 terminated children do not become zombies is to catch the
913 POSIX.1-1990 specified only
924 Use of these latter values in
926 may be less portable in applications intended for older
927 UNIX implementations.
931 flag is compatible with the SVr4 flag of the same name.
935 flag is compatible with the SVr4 flag of the same name under kernels
937 On older kernels the Linux implementation
938 allowed the receipt of any signal, not just the one we are installing
939 (effectively overriding any
944 can be called with a NULL second argument to query the current signal
946 It can also be used to check whether a given signal is valid for
947 the current machine by calling it with NULL second and third arguments.
949 It is not possible to block
950 .BR SIGKILL " or " SIGSTOP
951 (by specifying them in
953 Attempts to do so are silently ignored.
957 for details on manipulating signal sets.
960 .BR signal\-safety (7)
961 for a list of the async-signal-safe functions that can be
962 safely called inside from inside a signal handler.
964 .SS C library/kernel differences
965 The glibc wrapper function for
969 on attempts to change the disposition of the two real-time signals
970 used internally by the NPTL threading implementation.
975 On architectures where the signal trampoline resides in the C library,
976 the glibc wrapper function for
978 places the address of the trampoline code in the
988 The original Linux system call was named
990 However, with the addition of real-time signals in Linux 2.2,
991 the fixed-size, 32-bit
993 type supported by that system call was no longer fit for purpose.
994 Consequently, a new system call,
996 was added to support an enlarged
999 The new system call takes a fourth argument,
1000 .IR "size_t sigsetsize" ,
1001 which specifies the size in bytes of the signal sets in
1004 .IR oldact.sa_mask .
1005 This argument is currently required to have the value
1006 .IR sizeof(sigset_t)
1012 wrapper function hides these details from us, transparently calling
1014 when the kernel provides it.
1017 Before the introduction of
1019 it was also possible to get some additional information about the signal.
1020 This was done by providing an
1022 signal handler with a second argument of type
1023 .IR "struct sigcontext" ,
1024 which is the same structure as the one that is passed in the
1028 structure that is passed (via a pointer) in the third argument of the
1031 See the relevant Linux kernel sources for details.
1032 This use is obsolete now.
1034 When delivering a signal with a
1037 the kernel does not always provide meaningful values
1038 for all of the fields of the
1040 that are relevant for that signal.
1042 In kernels up to and including 2.6.13, specifying
1046 prevents not only the delivered signal from being masked during
1047 execution of the handler, but also the signals specified in
1049 This bug was fixed in kernel 2.6.14.
1050 .\" commit 69be8f189653cd81aae5a74e26615b12871bb72e
1058 .BR pidfd_send_signal (2),
1059 .BR restart_syscall (2),
1061 .BR sigaltstack (2),
1065 .BR sigprocmask (2),
1071 .BR siginterrupt (3),