Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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)