mirror of https://github.com/mkerrisk/man-pages
1213 lines
29 KiB
Groff
1213 lines
29 KiB
Groff
.\" 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-08-27 "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.)
|
|
.\"
|
|
.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
|
|
.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
|
|
.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 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).
|
|
.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
|
|
.EX
|
|
#include <signal.h>
|
|
#include <stdlib.h>
|
|
#include <stdio.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
|
|
.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)
|