diff options
Diffstat (limited to '')
| -rw-r--r-- | man2/sigaction.2 | 1203 |
1 files changed, 1203 insertions, 0 deletions
diff --git a/man2/sigaction.2 b/man2/sigaction.2 new file mode 100644 index 0000000..8edde42 --- /dev/null +++ b/man2/sigaction.2 @@ -0,0 +1,1203 @@ +.\" 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 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 2023-05-03 "Linux man-pages 6.05.01" +.SH NAME +sigaction, rt_sigaction \- examine and change a signal action +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.PP +.BI "int sigaction(int " signum , +.BI " const struct sigaction *_Nullable restrict " act , +.BI " struct sigaction *_Nullable 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 can be one of the following: +.IP \[bu] 3 +.B SIG_DFL +for the default action. +.IP \[bu] +.B SIG_IGN +to ignore this signal. +.IP \[bu] +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 +.B 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 +.B SA_RESTORER +.IR "Not intended for application use" . +This flag is used by C libraries to indicate that the +.I 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.) +.\" +.TP +.BR SA_UNSUPPORTED " (since Linux 5.11)" +Used to dynamically probe for flag bit support. +.IP +If an attempt to register a handler succeeds with this flag set in +.I act\->sa_flags +alongside other flags that are potentially unsupported by the kernel, +and an immediately subsequent +.BR sigaction () +call specifying the same signal number and with a non-NULL +.I oldact +argument yields +.B SA_UNSUPPORTED +.I clear +in +.IR oldact\->sa_flags , +then +.I oldact\->sa_flags +may be used as a bitmask +describing which of the potentially unsupported flags are, +in fact, supported. +See the section "Dynamically probing for flag bit support" +below for more details. +.TP +.BR SA_EXPOSE_TAGBITS " (since Linux 5.11)" +Normally, when delivering a signal, +an architecture-specific set of tag bits are cleared from the +.I si_addr +field of +.IR siginfo_t . +If this flag is set, +an architecture-specific subset of the tag bits will be preserved in +.IR si_addr . +.IP +Programs that need to be compatible with Linux versions older than 5.11 +must use +.B SA_UNSUPPORTED +to probe for support. +.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 +.I 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 +.I 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 \[bu] 3 +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 \[bu] +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 \[bu] +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 \[bu] +.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)). +Up to Linux 2.6, and since Linux 2.6.27, these fields report +CPU time in units of +.IR sysconf(_SC_CLK_TCK) . +In Linux 2.6 kernels before Linux 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 Linux 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 Linux 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 \[bu] +.BR SIGILL , +.BR SIGFPE , +.BR SIGSEGV , +.BR SIGBUS , +and +.B 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 +.B 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 +.B SEGV_BNDERR +suberror of +.B SIGSEGV +populates +.I si_lower +and +.IR si_upper . +.IP +The +.B SEGV_PKUERR +suberror of +.B SIGSEGV +populates +.IR si_pkey . +.IP \[bu] +.BR SIGIO / SIGPOLL +(the two names are synonyms on Linux) +fills in +.I si_band +and +.IR 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 +.B F_SETSIG +in +.BR fcntl (2). +.IP \[bu] +.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 +.B 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 \[bu] 3 +.B _XOPEN_SOURCE +with the value 500 or greater; +.IP \[bu] +.B _XOPEN_SOURCE +and +.BR _XOPEN_SOURCE_EXTENDED ; +or +.IP \[bu] +.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 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 Linux 2.6.9 sources, but isn't implemented +.\" It appears to have been an idea that was tried during 2.5.6 +.\" through to Linux 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 +.B SIGSYS +signal: +.RS 4 +.TP +.BR SYS_SECCOMP " (since Linux 3.5)" +Triggered by a +.BR seccomp (2) +filter rule. +.RE +.SS Dynamically probing for flag bit support +The +.BR sigaction () +call on Linux accepts unknown bits set in +.I act\->sa_flags +without error. +The behavior of the kernel starting with Linux 5.11 is that a second +.BR sigaction () +will clear unknown bits from +.IR oldact\->sa_flags . +However, historically, a second +.BR sigaction () +call would typically leave those bits set in +.IR oldact\->sa_flags . +.PP +This means that support for new flags cannot be detected +simply by testing for a flag in +.IR sa_flags , +and a program must test that +.B SA_UNSUPPORTED +has been cleared before relying on the contents of +.IR sa_flags . +.PP +Since the behavior of the signal handler cannot be guaranteed +unless the check passes, +it is wise to either block the affected signal +while registering the handler and performing the check in this case, +or where this is not possible, +for example if the signal is synchronous, to issue the second +.BR sigaction () +in the signal handler itself. +.PP +In kernels that do not support a specific flag, +the kernel's behavior is as if the flag was not set, +even if the flag was set in +.IR act\->sa_flags . +.PP +The flags +.BR SA_NOCLDSTOP , +.BR SA_NOCLDWAIT , +.BR SA_SIGINFO , +.BR SA_ONSTACK , +.BR SA_RESTART , +.BR SA_NODEFER , +.BR SA_RESETHAND , +and, if defined by the architecture, +.B SA_RESTORER +may not be reliably probed for using this mechanism, +because they were introduced before Linux 5.11. +However, in general, programs may assume that these flags are supported, +since they have all been supported since Linux 2.6, +which was released in the year 2003. +.PP +See EXAMPLES below for a demonstration of the use of +.BR SA_UNSUPPORTED . +.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 VERSIONS +.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 +.I 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 +.I 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 +.I 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 +.I act.sa_mask +and +.IR oldact.sa_mask . +This argument is currently required to have the value +.I 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. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.\" SVr4 does not document the EINTR condition. +.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). +.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 +.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 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 +Up to and including Linux 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 Linux 2.6.14. +.\" commit 69be8f189653cd81aae5a74e26615b12871bb72e +.SH EXAMPLES +See +.BR mprotect (2). +.SS Probing for flag support +The following example program exits with status +.B EXIT_SUCCESS +if +.B SA_EXPOSE_TAGBITS +is determined to be supported, and +.B EXIT_FAILURE +otherwise. +.PP +.\" SRC BEGIN (sigaction.c) +.EX +#include <signal.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +void +handler(int signo, siginfo_t *info, void *context) +{ + struct sigaction oldact; +\& + if (sigaction(SIGSEGV, NULL, &oldact) == \-1 + || (oldact.sa_flags & SA_UNSUPPORTED) + || !(oldact.sa_flags & SA_EXPOSE_TAGBITS)) + { + _exit(EXIT_FAILURE); + } + _exit(EXIT_SUCCESS); +} +\& +int +main(void) +{ + struct sigaction act = { 0 }; +\& + act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS; + act.sa_sigaction = &handler; + if (sigaction(SIGSEGV, &act, NULL) == \-1) { + perror("sigaction"); + exit(EXIT_FAILURE); + } +\& + raise(SIGSEGV); +} +.EE +.\" SRC END +.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) |