diff options
Diffstat (limited to 'man2/sigaction.2')
| -rw-r--r-- | man2/sigaction.2 | 1210 |
1 files changed, 0 insertions, 1210 deletions
diff --git a/man2/sigaction.2 b/man2/sigaction.2 deleted file mode 100644 index bbe4d5a..0000000 --- a/man2/sigaction.2 +++ /dev/null @@ -1,1210 +0,0 @@ -.\" 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 2024-02-25 "Linux man-pages 6.7" -.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> -.P -.BI "int sigaction(int " signum , -.BI " const struct sigaction *_Nullable restrict " act , -.BI " struct sigaction *_Nullable restrict " oldact ); -.fi -.P -.RS -4 -Feature Test Macro Requirements for glibc (see -.BR feature_test_macros (7)): -.RE -.P -.BR sigaction (): -.nf - _POSIX_C_SOURCE -.fi -.P -.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.) -.P -.I signum -specifies the signal and can be any valid signal except -.B SIGKILL -and -.BR SIGSTOP . -.P -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 . -.P -The -.I sigaction -structure is defined as something like: -.P -.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 -.P -On some architectures a union is involved: do not assign to both -.I sa_handler -and -.IR sa_sigaction . -.P -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). -.P -.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. -.P -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. -.P -.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. -.P -.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: -.P -.in +4n -.EX -void -handler(int sig, siginfo_t *info, void *ucontext) -{ - ... -} -.EE -.in -.P -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. -.P -The -.I siginfo_t -data type is a structure with the following fields: -.P -.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 -.P -.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: -.P -.in +4n -.EX -(SIGTRAP | PTRACE_EVENT_foo << 8). -.EE -.in -.P -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. -.P -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. -.P -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 -.P -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 -.P -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 -.P -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 -.P -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 -.P -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 -.P -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 -.P -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 -.P -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 . -.P -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 . -.P -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. -.P -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 . -.P -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. -.P -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. -.P -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). -.P -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. -.P -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. -.P -POSIX.1-1990 specified only -.BR SA_NOCLDSTOP . -POSIX.1-2001 added -.BR SA_NOCLDWAIT , -.BR SA_NODEFER , -.BR SA_ONSTACK , -.BR SA_RESETHAND , -.BR SA_RESTART , -and -.B SA_SIGINFO -as XSI extensions. -POSIX.1-2008 moved -.BR SA_NODEFER , -.BR SA_RESETHAND , -.BR SA_RESTART , -and -.B SA_SIGINFO -to the base specifications. -Use of these latter values in -.I sa_flags -may be less portable in applications intended for older -UNIX implementations. -.P -The -.B SA_RESETHAND -flag is compatible with the SVr4 flag of the same name. -.P -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. -.P -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. -.P -.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. -.P -It is not possible to block -.BR SIGKILL " or " SIGSTOP -(by specifying them in -.IR sa_mask ). -Attempts to do so are silently ignored. -.P -See -.BR sigsetops (3) -for details on manipulating signal sets. -.P -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. -.P -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. -.P -.\" 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) |