| .\" Copyright (c) 1994,1995 Mike Battersby <mib@deakin.edu.au> |
| .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" based on work by faith@cs.unc.edu |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified, aeb, 960424 |
| .\" Modified Fri Jan 31 17:31:20 1997 by Eric S. Raymond <esr@thyrsus.com> |
| .\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff. |
| .\" Modified Sat May 8 17:40:19 1999 by Matthew Wilcox |
| .\" add POSIX.1b signals |
| .\" Modified Sat Dec 29 01:44:52 2001 by Evan Jones <ejones@uwaterloo.ca> |
| .\" SA_ONSTACK |
| .\" Modified 2004-11-11 by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" Added mention of SIGCONT under SA_NOCLDSTOP |
| .\" Added SA_NOCLDWAIT |
| .\" Modified 2004-11-17 by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags. |
| .\" Formatting fixes |
| .\" 2004-12-09, mtk, added SI_TKILL + other minor changes |
| .\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend() |
| .\" out of this page into separate pages. |
| .\" 2010-06-11 Andi Kleen, add hwpoison signal extensions |
| .\" 2010-06-11 mtk, improvements to discussion of various siginfo_t fields. |
| .\" 2015-01-17, Kees Cook <keescook@chromium.org> |
| .\" Added notes on ptrace SIGTRAP and SYS_SECCOMP. |
| .\" |
| .TH SIGACTION 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| sigaction, rt_sigaction \- examine and change a signal action |
| .SH SYNOPSIS |
| .nf |
| .B #include <signal.h> |
| .PP |
| .BI "int sigaction(int " signum ", const struct sigaction *restrict " act , |
| .BI " struct sigaction *restrict " oldact ); |
| .fi |
| .PP |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .PP |
| .BR sigaction (): |
| .nf |
| _POSIX_C_SOURCE |
| .fi |
| .PP |
| .IR siginfo_t : |
| .nf |
| _POSIX_C_SOURCE >= 199309L |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR sigaction () |
| system call is used to change the action taken by a process on |
| receipt of a specific signal. |
| (See |
| .BR signal (7) |
| for an overview of signals.) |
| .PP |
| .I signum |
| specifies the signal and can be any valid signal except |
| .B SIGKILL |
| and |
| .BR SIGSTOP . |
| .PP |
| If |
| .I act |
| is non-NULL, the new action for signal |
| .I signum |
| is installed from |
| .IR act . |
| If |
| .I oldact |
| is non-NULL, the previous action is saved in |
| .IR oldact . |
| .PP |
| The |
| .I sigaction |
| structure is defined as something like: |
| .PP |
| .in +4n |
| .EX |
| struct sigaction { |
| void (*sa_handler)(int); |
| void (*sa_sigaction)(int, siginfo_t *, void *); |
| sigset_t sa_mask; |
| int sa_flags; |
| void (*sa_restorer)(void); |
| }; |
| .EE |
| .in |
| .PP |
| On some architectures a union is involved: do not assign to both |
| .I sa_handler |
| and |
| .IR sa_sigaction . |
| .PP |
| The |
| .I sa_restorer |
| field is not intended for application use. |
| (POSIX does not specify a |
| .I sa_restorer |
| field.) |
| Some further details of the purpose of this field can be found in |
| .BR sigreturn (2). |
| .PP |
| .I sa_handler |
| specifies the action to be associated with |
| .I signum |
| and is be one of the following: |
| .IP * 2 |
| .B SIG_DFL |
| for the default action. |
| .IP * |
| .B SIG_IGN |
| to ignore this signal. |
| .IP * |
| A pointer to a signal handling function. |
| This function receives the signal number as its only argument. |
| .PP |
| If |
| .B SA_SIGINFO |
| is specified in |
| .IR sa_flags , |
| then |
| .I sa_sigaction |
| (instead of |
| .IR sa_handler ) |
| specifies the signal-handling function for |
| .IR signum . |
| This function receives three arguments, as described below. |
| .PP |
| .I sa_mask |
| specifies a mask of signals which should be blocked |
| (i.e., added to the signal mask of the thread in which |
| the signal handler is invoked) |
| during execution of the signal handler. |
| In addition, the signal which triggered the handler |
| will be blocked, unless the |
| .B SA_NODEFER |
| flag is used. |
| .PP |
| .I sa_flags |
| specifies a set of flags which modify the behavior of the signal. |
| It is formed by the bitwise OR of zero or more of the following: |
| .TP |
| .B SA_NOCLDSTOP |
| If |
| .I signum |
| is |
| .BR SIGCHLD , |
| do not receive notification when child processes stop (i.e., when they |
| receive one of |
| .BR SIGSTOP ", " SIGTSTP ", " SIGTTIN , |
| or |
| .BR SIGTTOU ) |
| or resume (i.e., they receive |
| .BR SIGCONT ) |
| (see |
| .BR wait (2)). |
| This flag is meaningful only when establishing a handler for |
| .BR SIGCHLD . |
| .TP |
| .BR SA_NOCLDWAIT " (since Linux 2.6)" |
| .\" To be precise: Linux 2.5.60 -- MTK |
| If |
| .I signum |
| is |
| .BR SIGCHLD , |
| do not transform children into zombies when they terminate. |
| See also |
| .BR waitpid (2). |
| This flag is meaningful only when establishing a handler for |
| .BR SIGCHLD , |
| or when setting that signal's disposition to |
| .BR SIG_DFL . |
| .IP |
| If the |
| .B SA_NOCLDWAIT |
| flag is set when establishing a handler for |
| .BR SIGCHLD , |
| POSIX.1 leaves it unspecified whether a |
| .B SIGCHLD |
| signal is generated when a child process terminates. |
| On Linux, a |
| .B SIGCHLD |
| signal is generated in this case; |
| on some other implementations, it is not. |
| .TP |
| .B SA_NODEFER |
| Do not add the signal to the thread's signal mask while the |
| handler is executing, unless the signal is specified in |
| .IR act.sa_mask . |
| Consequently, a further instance of the signal may be delivered |
| to the thread while it is executing the handler. |
| This flag is meaningful only when establishing a signal handler. |
| .IP |
| .B SA_NOMASK |
| is an obsolete, nonstandard synonym for this flag. |
| .TP |
| .B SA_ONSTACK |
| Call the signal handler on an alternate signal stack provided by |
| .BR sigaltstack (2). |
| If an alternate stack is not available, the default stack will be used. |
| This flag is meaningful only when establishing a signal handler. |
| .TP |
| .BR SA_RESETHAND |
| Restore the signal action to the default upon entry to the signal handler. |
| This flag is meaningful only when establishing a signal handler. |
| .IP |
| .B SA_ONESHOT |
| is an obsolete, nonstandard synonym for this flag. |
| .TP |
| .B SA_RESTART |
| Provide behavior compatible with BSD signal semantics by making certain |
| system calls restartable across signals. |
| This flag is meaningful only when establishing a signal handler. |
| See |
| .BR signal (7) |
| for a discussion of system call restarting. |
| .TP |
| .BR SA_RESTORER |
| .IR "Not intended for application use" . |
| This flag is used by C libraries to indicate that the |
| .IR sa_restorer |
| field contains the address of a "signal trampoline". |
| See |
| .BR sigreturn (2) |
| for more details. |
| .TP |
| .BR SA_SIGINFO " (since Linux 2.2)" |
| The signal handler takes three arguments, not one. |
| In this case, |
| .I sa_sigaction |
| should be set instead of |
| .IR sa_handler . |
| This flag is meaningful only when establishing a signal handler. |
| .\" (The |
| .\" .I sa_sigaction |
| .\" field was added in Linux 2.1.86.) |
| .\" |
| .SS The siginfo_t argument to a SA_SIGINFO handler |
| When the |
| .B SA_SIGINFO |
| flag is specified in |
| .IR act.sa_flags , |
| the signal handler address is passed via the |
| .IR act.sa_sigaction |
| field. |
| This handler takes three arguments, as follows: |
| .PP |
| .in +4n |
| .EX |
| void |
| handler(int sig, siginfo_t *info, void *ucontext) |
| { |
| ... |
| } |
| .EE |
| .in |
| .PP |
| These three arguments are as follows |
| .TP |
| .I sig |
| The number of the signal that caused invocation of the handler. |
| .TP |
| .I info |
| A pointer to a |
| .IR siginfo_t , |
| which is a structure containing further information about the signal, |
| as described below. |
| .TP |
| .I ucontext |
| This is a pointer to a |
| .I ucontext_t |
| structure, cast to \fIvoid\ *\fP. |
| The structure pointed to by this field contains |
| signal context information that was saved |
| on the user-space stack by the kernel; for details, see |
| .BR sigreturn (2). |
| Further information about the |
| .IR ucontext_t |
| structure can be found in |
| .BR getcontext (3) |
| and |
| .BR signal (7). |
| Commonly, the handler function doesn't make any use of the third argument. |
| .PP |
| The |
| .I siginfo_t |
| data type is a structure with the following fields: |
| .PP |
| .in +4n |
| .EX |
| siginfo_t { |
| int si_signo; /* Signal number */ |
| int si_errno; /* An errno value */ |
| int si_code; /* Signal code */ |
| int si_trapno; /* Trap number that caused |
| hardware\-generated signal |
| (unused on most architectures) */ |
| .\" FIXME |
| .\" The siginfo_t 'si_trapno' field seems to be used |
| .\" only on SPARC and Alpha; this page could use |
| .\" a little more detail on its purpose there. |
| pid_t si_pid; /* Sending process ID */ |
| uid_t si_uid; /* Real user ID of sending process */ |
| int si_status; /* Exit value or signal */ |
| clock_t si_utime; /* User time consumed */ |
| clock_t si_stime; /* System time consumed */ |
| union sigval si_value; /* Signal value */ |
| int si_int; /* POSIX.1b signal */ |
| void *si_ptr; /* POSIX.1b signal */ |
| int si_overrun; /* Timer overrun count; |
| POSIX.1b timers */ |
| int si_timerid; /* Timer ID; POSIX.1b timers */ |
| .\" In the kernel: si_tid |
| void *si_addr; /* Memory location which caused fault */ |
| long si_band; /* Band event (was \fIint\fP in |
| glibc 2.3.2 and earlier) */ |
| int si_fd; /* File descriptor */ |
| short si_addr_lsb; /* Least significant bit of address |
| (since Linux 2.6.32) */ |
| void *si_lower; /* Lower bound when address violation |
| occurred (since Linux 3.19) */ |
| void *si_upper; /* Upper bound when address violation |
| occurred (since Linux 3.19) */ |
| int si_pkey; /* Protection key on PTE that caused |
| fault (since Linux 4.6) */ |
| void *si_call_addr; /* Address of system call instruction |
| (since Linux 3.5) */ |
| int si_syscall; /* Number of attempted system call |
| (since Linux 3.5) */ |
| unsigned int si_arch; /* Architecture of attempted system call |
| (since Linux 3.5) */ |
| } |
| .EE |
| .in |
| .PP |
| .IR si_signo ", " si_errno " and " si_code |
| are defined for all signals. |
| .RI ( si_errno |
| is generally unused on Linux.) |
| The rest of the struct may be a union, so that one should |
| read only the fields that are meaningful for the given signal: |
| .IP * 2 |
| Signals sent with |
| .BR kill (2) |
| and |
| .BR sigqueue (3) |
| fill in |
| .IR si_pid " and " si_uid . |
| In addition, signals sent with |
| .BR sigqueue (3) |
| fill in |
| .IR si_int " and " si_ptr |
| with the values specified by the sender of the signal; |
| see |
| .BR sigqueue (3) |
| for more details. |
| .IP * |
| Signals sent by POSIX.1b timers (since Linux 2.6) fill in |
| .I si_overrun |
| and |
| .IR si_timerid . |
| The |
| .I si_timerid |
| field is an internal ID used by the kernel to identify |
| the timer; it is not the same as the timer ID returned by |
| .BR timer_create (2). |
| The |
| .I si_overrun |
| field is the timer overrun count; |
| this is the same information as is obtained by a call to |
| .BR timer_getoverrun (2). |
| These fields are nonstandard Linux extensions. |
| .IP * |
| Signals sent for message queue notification (see the description of |
| .B SIGEV_SIGNAL |
| in |
| .BR mq_notify (3)) |
| fill in |
| .IR si_int / si_ptr , |
| with the |
| .I sigev_value |
| supplied to |
| .BR mq_notify (3); |
| .IR si_pid , |
| with the process ID of the message sender; and |
| .IR si_uid , |
| with the real user ID of the message sender. |
| .IP * |
| .B SIGCHLD |
| fills in |
| .IR si_pid ", " si_uid ", " si_status ", " si_utime ", and " si_stime , |
| providing information about the child. |
| The |
| .I si_pid |
| field is the process ID of the child; |
| .I si_uid |
| is the child's real user ID. |
| The |
| .I si_status |
| field contains the exit status of the child (if |
| .I si_code |
| is |
| .BR CLD_EXITED ), |
| or the signal number that caused the process to change state. |
| The |
| .I si_utime |
| and |
| .I si_stime |
| contain the user and system CPU time used by the child process; |
| these fields do not include the times used by waited-for children (unlike |
| .BR getrusage (2) |
| and |
| .BR times (2)). |
| In kernels up to 2.6, and since 2.6.27, these fields report |
| CPU time in units of |
| .IR sysconf(_SC_CLK_TCK) . |
| In 2.6 kernels before 2.6.27, |
| a bug meant that these fields reported time in units |
| of the (configurable) system jiffy (see |
| .BR time (7)). |
| .\" FIXME . |
| .\" When si_utime and si_stime where originally implemented, the |
| .\" measurement unit was HZ, which was the same as clock ticks |
| .\" (sysconf(_SC_CLK_TCK)). In 2.6, HZ became configurable, and |
| .\" was *still* used as the unit to return the info these fields, |
| .\" with the result that the field values depended on the |
| .\" configured HZ. Of course, the should have been measured in |
| .\" USER_HZ instead, so that sysconf(_SC_CLK_TCK) could be used to |
| .\" convert to seconds. I have a queued patch to fix this: |
| .\" http://thread.gmane.org/gmane.linux.kernel/698061/ . |
| .\" This patch made it into 2.6.27. |
| .\" But note that these fields still don't return the times of |
| .\" waited-for children (as is done by getrusage() and times() |
| .\" and wait4()). Solaris 8 does include child times. |
| .IP * |
| .BR SIGILL , |
| .BR SIGFPE , |
| .BR SIGSEGV , |
| .BR SIGBUS , |
| and |
| .BR SIGTRAP |
| fill in |
| .I si_addr |
| with the address of the fault. |
| On some architectures, |
| these signals also fill in the |
| .I si_trapno |
| field. |
| .IP |
| Some suberrors of |
| .BR SIGBUS , |
| in particular |
| .B BUS_MCEERR_AO |
| and |
| .BR BUS_MCEERR_AR , |
| also fill in |
| .IR si_addr_lsb . |
| This field indicates the least significant bit of the reported address |
| and therefore the extent of the corruption. |
| For example, if a full page was corrupted, |
| .I si_addr_lsb |
| contains |
| .IR log2(sysconf(_SC_PAGESIZE)) . |
| When |
| .BR SIGTRAP |
| is delivered in response to a |
| .BR ptrace (2) |
| event (PTRACE_EVENT_foo), |
| .I si_addr |
| is not populated, but |
| .I si_pid |
| and |
| .I si_uid |
| are populated with the respective process ID and user ID responsible for |
| delivering the trap. |
| In the case of |
| .BR seccomp (2), |
| the tracee will be shown as delivering the event. |
| .B BUS_MCEERR_* |
| and |
| .I si_addr_lsb |
| are Linux-specific extensions. |
| .IP |
| The |
| .BR SEGV_BNDERR |
| suberror of |
| .B SIGSEGV |
| populates |
| .IR si_lower |
| and |
| .IR si_upper . |
| .IP |
| The |
| .BR SEGV_PKUERR |
| suberror of |
| .B SIGSEGV |
| populates |
| .IR si_pkey . |
| .IP * |
| .BR SIGIO / SIGPOLL |
| (the two names are synonyms on Linux) |
| fills in |
| .IR si_band " and " si_fd . |
| The |
| .I si_band |
| event is a bit mask containing the same values as are filled in the |
| .I revents |
| field by |
| .BR poll (2). |
| The |
| .I si_fd |
| field indicates the file descriptor for which the I/O event occurred; |
| for further details, see the description of |
| .BR F_SETSIG |
| in |
| .BR fcntl (2). |
| .IP * |
| .BR SIGSYS , |
| generated (since Linux 3.5) |
| .\" commit a0727e8ce513fe6890416da960181ceb10fbfae6 |
| when a seccomp filter returns |
| .BR SECCOMP_RET_TRAP , |
| fills in |
| .IR si_call_addr , |
| .IR si_syscall , |
| .IR si_arch , |
| .IR si_errno , |
| and other fields as described in |
| .BR seccomp (2). |
| .\" |
| .SS |
| The si_code field |
| The |
| .I si_code |
| field inside the |
| .I siginfo_t |
| argument that is passed to a |
| .B SA_SIGINFO |
| signal handler is a value (not a bit mask) |
| indicating why this signal was sent. |
| For a |
| .BR ptrace (2) |
| event, |
| .I si_code |
| will contain |
| .BR SIGTRAP |
| and have the ptrace event in the high byte: |
| .PP |
| .in +4n |
| .EX |
| (SIGTRAP | PTRACE_EVENT_foo << 8). |
| .EE |
| .in |
| .PP |
| For a |
| .RB non- ptrace (2) |
| event, the values that can appear in |
| .I si_code |
| are described in the remainder of this section. |
| Since glibc 2.20, |
| the definitions of most of these symbols are obtained from |
| .I <signal.h> |
| by defining feature test macros (before including |
| .I any |
| header file) as follows: |
| .IP * 3 |
| .B _XOPEN_SOURCE |
| with the value 500 or greater; |
| .IP * |
| .B _XOPEN_SOURCE |
| and |
| .BR _XOPEN_SOURCE_EXTENDED ; |
| or |
| .IP * |
| .B _POSIX_C_SOURCE |
| with the value 200809L or greater. |
| .PP |
| For the |
| .B TRAP_* |
| constants, the symbol definitions are provided only in the first two cases. |
| Before glibc 2.20, no feature test macros were required to obtain these symbols. |
| .PP |
| For a regular signal, the following list shows the values which can be |
| placed in |
| .I si_code |
| for any signal, along with the reason that the signal was generated. |
| .RS 4 |
| .TP |
| .B SI_USER |
| .BR kill (2). |
| .TP |
| .B SI_KERNEL |
| Sent by the kernel. |
| .TP |
| .B SI_QUEUE |
| .BR sigqueue (3). |
| .TP |
| .B SI_TIMER |
| POSIX timer expired. |
| .TP |
| .BR SI_MESGQ " (since Linux 2.6.6)" |
| POSIX message queue state changed; see |
| .BR mq_notify (3). |
| .TP |
| .B SI_ASYNCIO |
| AIO completed. |
| .TP |
| .B SI_SIGIO |
| Queued |
| .B SIGIO |
| (only in kernels up to Linux 2.2; from Linux 2.4 onward |
| .BR SIGIO / SIGPOLL |
| fills in |
| .I si_code |
| as described below). |
| .TP |
| .BR SI_TKILL " (since Linux 2.4.19)" |
| .BR tkill (2) |
| or |
| .BR tgkill (2). |
| .\" SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented |
| .\" It appears to have been an idea that was tried during 2.5.6 |
| .\" through to 2.5.24 and then was backed out. |
| .RE |
| .PP |
| The following values can be placed in |
| .I si_code |
| for a |
| .B SIGILL |
| signal: |
| .RS 4 |
| .TP |
| .B ILL_ILLOPC |
| Illegal opcode. |
| .TP |
| .B ILL_ILLOPN |
| Illegal operand. |
| .TP |
| .B ILL_ILLADR |
| Illegal addressing mode. |
| .TP |
| .B ILL_ILLTRP |
| Illegal trap. |
| .TP |
| .B ILL_PRVOPC |
| Privileged opcode. |
| .TP |
| .B ILL_PRVREG |
| Privileged register. |
| .TP |
| .B ILL_COPROC |
| Coprocessor error. |
| .TP |
| .B ILL_BADSTK |
| Internal stack error. |
| .RE |
| .PP |
| The following values can be placed in |
| .I si_code |
| for a |
| .B SIGFPE |
| signal: |
| .RS 4 |
| .TP |
| .B FPE_INTDIV |
| Integer divide by zero. |
| .TP |
| .B FPE_INTOVF |
| Integer overflow. |
| .TP |
| .B FPE_FLTDIV |
| Floating-point divide by zero. |
| .TP |
| .B FPE_FLTOVF |
| Floating-point overflow. |
| .TP |
| .B FPE_FLTUND |
| Floating-point underflow. |
| .TP |
| .B FPE_FLTRES |
| Floating-point inexact result. |
| .TP |
| .B FPE_FLTINV |
| Floating-point invalid operation. |
| .TP |
| .B FPE_FLTSUB |
| Subscript out of range. |
| .RE |
| .PP |
| The following values can be placed in |
| .I si_code |
| for a |
| .B SIGSEGV |
| signal: |
| .RS 4 |
| .TP |
| .B SEGV_MAPERR |
| Address not mapped to object. |
| .TP |
| .B SEGV_ACCERR |
| Invalid permissions for mapped object. |
| .TP |
| .BR SEGV_BNDERR " (since Linux 3.19)" |
| .\" commit ee1b58d36aa1b5a79eaba11f5c3633c88231da83 |
| Failed address bound checks. |
| .TP |
| .BR SEGV_PKUERR " (since Linux 4.6)" |
| .\" commit cd0ea35ff5511cde299a61c21a95889b4a71464e |
| Access was denied by memory protection keys. |
| See |
| .BR pkeys (7). |
| The protection key which applied to this access is available via |
| .IR si_pkey . |
| .RE |
| .PP |
| The following values can be placed in |
| .I si_code |
| for a |
| .B SIGBUS |
| signal: |
| .RS 4 |
| .TP |
| .B BUS_ADRALN |
| Invalid address alignment. |
| .TP |
| .B BUS_ADRERR |
| Nonexistent physical address. |
| .TP |
| .B BUS_OBJERR |
| Object-specific hardware error. |
| .TP |
| .BR BUS_MCEERR_AR " (since Linux 2.6.32)" |
| Hardware memory error consumed on a machine check; action required. |
| .TP |
| .BR BUS_MCEERR_AO " (since Linux 2.6.32)" |
| Hardware memory error detected in process but not consumed; action optional. |
| .RE |
| .PP |
| The following values can be placed in |
| .I si_code |
| for a |
| .B SIGTRAP |
| signal: |
| .RS 4 |
| .TP |
| .B TRAP_BRKPT |
| Process breakpoint. |
| .TP |
| .B TRAP_TRACE |
| Process trace trap. |
| .TP |
| .BR TRAP_BRANCH " (since Linux 2.4, IA64 only)" |
| Process taken branch trap. |
| .TP |
| .BR TRAP_HWBKPT " (since Linux 2.4, IA64 only)" |
| Hardware breakpoint/watchpoint. |
| .RE |
| .PP |
| The following values can be placed in |
| .I si_code |
| for a |
| .B SIGCHLD |
| signal: |
| .RS 4 |
| .TP |
| .B CLD_EXITED |
| Child has exited. |
| .TP |
| .B CLD_KILLED |
| Child was killed. |
| .TP |
| .B CLD_DUMPED |
| Child terminated abnormally. |
| .TP |
| .B CLD_TRAPPED |
| Traced child has trapped. |
| .TP |
| .B CLD_STOPPED |
| Child has stopped. |
| .TP |
| .BR CLD_CONTINUED " (since Linux 2.6.9)" |
| Stopped child has continued. |
| .RE |
| .PP |
| The following values can be placed in |
| .I si_code |
| for a |
| .BR SIGIO / SIGPOLL |
| signal: |
| .RS 4 |
| .TP |
| .B POLL_IN |
| Data input available. |
| .TP |
| .B POLL_OUT |
| Output buffers available. |
| .TP |
| .B POLL_MSG |
| Input message available. |
| .TP |
| .B POLL_ERR |
| I/O error. |
| .TP |
| .B POLL_PRI |
| High priority input available. |
| .TP |
| .B POLL_HUP |
| Device disconnected. |
| .RE |
| .PP |
| The following value can be placed in |
| .I si_code |
| for a |
| .BR SIGSYS |
| signal: |
| .RS 4 |
| .TP |
| .BR SYS_SECCOMP " (since Linux 3.5)" |
| Triggered by a |
| .BR seccomp (2) |
| filter rule. |
| .RE |
| .SH RETURN VALUE |
| .BR sigaction () |
| returns 0 on success; on error, \-1 is returned, and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| .IR act " or " oldact |
| points to memory which is not a valid part of the process address space. |
| .TP |
| .B EINVAL |
| An invalid signal was specified. |
| This will also be generated if an attempt |
| is made to change the action for |
| .BR SIGKILL " or " SIGSTOP , |
| which cannot be caught or ignored. |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, SVr4. |
| .\" SVr4 does not document the EINTR condition. |
| .SH NOTES |
| A child created via |
| .BR fork (2) |
| inherits a copy of its parent's signal dispositions. |
| During an |
| .BR execve (2), |
| the dispositions of handled signals are reset to the default; |
| the dispositions of ignored signals are left unchanged. |
| .PP |
| According to POSIX, the behavior of a process is undefined after it |
| ignores a |
| .BR SIGFPE , |
| .BR SIGILL , |
| or |
| .B SIGSEGV |
| signal that was not generated by |
| .BR kill (2) |
| or |
| .BR raise (3). |
| Integer division by zero has undefined result. |
| On some architectures it will generate a |
| .B SIGFPE |
| signal. |
| (Also dividing the most negative integer by \-1 may generate |
| .BR SIGFPE .) |
| Ignoring this signal might lead to an endless loop. |
| .PP |
| POSIX.1-1990 disallowed setting the action for |
| .B SIGCHLD |
| to |
| .BR SIG_IGN . |
| POSIX.1-2001 and later allow this possibility, so that ignoring |
| .B SIGCHLD |
| can be used to prevent the creation of zombies (see |
| .BR wait (2)). |
| Nevertheless, the historical BSD and System\ V behaviors for ignoring |
| .B SIGCHLD |
| differ, so that the only completely portable method of ensuring that |
| terminated children do not become zombies is to catch the |
| .B SIGCHLD |
| signal and perform a |
| .BR wait (2) |
| or similar. |
| .PP |
| POSIX.1-1990 specified only |
| .BR SA_NOCLDSTOP . |
| POSIX.1-2001 added |
| .BR SA_NOCLDSTOP , |
| .BR SA_NOCLDWAIT , |
| .BR SA_NODEFER , |
| .BR SA_ONSTACK , |
| .BR SA_RESETHAND , |
| .BR SA_RESTART , |
| and |
| .BR SA_SIGINFO . |
| Use of these latter values in |
| .I sa_flags |
| may be less portable in applications intended for older |
| UNIX implementations. |
| .PP |
| The |
| .B SA_RESETHAND |
| flag is compatible with the SVr4 flag of the same name. |
| .PP |
| The |
| .B SA_NODEFER |
| flag is compatible with the SVr4 flag of the same name under kernels |
| 1.3.9 and later. |
| On older kernels the Linux implementation |
| allowed the receipt of any signal, not just the one we are installing |
| (effectively overriding any |
| .I sa_mask |
| settings). |
| .PP |
| .BR sigaction () |
| can be called with a NULL second argument to query the current signal |
| handler. |
| It can also be used to check whether a given signal is valid for |
| the current machine by calling it with NULL second and third arguments. |
| .PP |
| It is not possible to block |
| .BR SIGKILL " or " SIGSTOP |
| (by specifying them in |
| .IR sa_mask ). |
| Attempts to do so are silently ignored. |
| .PP |
| See |
| .BR sigsetops (3) |
| for details on manipulating signal sets. |
| .PP |
| See |
| .BR signal\-safety (7) |
| for a list of the async-signal-safe functions that can be |
| safely called inside from inside a signal handler. |
| .\" |
| .SS C library/kernel differences |
| The glibc wrapper function for |
| .BR sigaction () |
| gives an error |
| .RB ( EINVAL ) |
| on attempts to change the disposition of the two real-time signals |
| used internally by the NPTL threading implementation. |
| See |
| .BR nptl (7) |
| for details. |
| .PP |
| On architectures where the signal trampoline resides in the C library, |
| the glibc wrapper function for |
| .BR sigaction () |
| places the address of the trampoline code in the |
| .I act.sa_restorer |
| field and sets the |
| .B SA_RESTORER |
| flag in the |
| .IR act.sa_flags |
| field. |
| See |
| .BR sigreturn (2). |
| .PP |
| The original Linux system call was named |
| .BR sigaction (). |
| However, with the addition of real-time signals in Linux 2.2, |
| the fixed-size, 32-bit |
| .IR sigset_t |
| type supported by that system call was no longer fit for purpose. |
| Consequently, a new system call, |
| .BR rt_sigaction (), |
| was added to support an enlarged |
| .IR sigset_t |
| type. |
| The new system call takes a fourth argument, |
| .IR "size_t sigsetsize" , |
| which specifies the size in bytes of the signal sets in |
| .IR act.sa_mask |
| and |
| .IR oldact.sa_mask . |
| This argument is currently required to have the value |
| .IR sizeof(sigset_t) |
| (or the error |
| .B EINVAL |
| results). |
| The glibc |
| .BR sigaction () |
| wrapper function hides these details from us, transparently calling |
| .BR rt_sigaction () |
| when the kernel provides it. |
| .\" |
| .SS Undocumented |
| Before the introduction of |
| .BR SA_SIGINFO , |
| it was also possible to get some additional information about the signal. |
| This was done by providing an |
| .I sa_handler |
| signal handler with a second argument of type |
| .IR "struct sigcontext" , |
| which is the same structure as the one that is passed in the |
| .I uc_mcontext |
| field of the |
| .I ucontext |
| structure that is passed (via a pointer) in the third argument of the |
| .I sa_sigaction |
| handler. |
| See the relevant Linux kernel sources for details. |
| This use is obsolete now. |
| .SH BUGS |
| When delivering a signal with a |
| .B SA_SIGINFO |
| handler, |
| the kernel does not always provide meaningful values |
| for all of the fields of the |
| .I siginfo_t |
| that are relevant for that signal. |
| .PP |
| In kernels up to and including 2.6.13, specifying |
| .B SA_NODEFER |
| in |
| .I sa_flags |
| prevents not only the delivered signal from being masked during |
| execution of the handler, but also the signals specified in |
| .IR sa_mask . |
| This bug was fixed in kernel 2.6.14. |
| .\" commit 69be8f189653cd81aae5a74e26615b12871bb72e |
| .SH EXAMPLES |
| See |
| .BR mprotect (2). |
| .SH SEE ALSO |
| .BR kill (1), |
| .BR kill (2), |
| .BR pause (2), |
| .BR pidfd_send_signal (2), |
| .BR restart_syscall (2), |
| .BR seccomp (2), |
| .BR sigaltstack (2), |
| .BR signal (2), |
| .BR signalfd (2), |
| .BR sigpending (2), |
| .BR sigprocmask (2), |
| .BR sigreturn (2), |
| .BR sigsuspend (2), |
| .BR wait (2), |
| .BR killpg (3), |
| .BR raise (3), |
| .BR siginterrupt (3), |
| .BR sigqueue (3), |
| .BR sigsetops (3), |
| .BR sigvec (3), |
| .BR core (5), |
| .BR signal (7) |