mirror of https://github.com/mkerrisk/man-pages
930 lines
22 KiB
Groff
930 lines
22 KiB
Groff
'\" t
|
|
.\" 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 2015-08-08 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
sigaction, rt_sigaction \- examine and change a signal action
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <signal.h>
|
|
.sp
|
|
.BI "int sigaction(int " signum ", const struct sigaction *" act ,
|
|
.BI " struct sigaction *" oldact );
|
|
.fi
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.ad l
|
|
.BR sigaction ():
|
|
_POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
|
|
|
|
.IR siginfo_t :
|
|
_POSIX_C_SOURCE >= 199309L
|
|
.ad b
|
|
.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:
|
|
.sp
|
|
.in +4n
|
|
.nf
|
|
struct sigaction {
|
|
void (*sa_handler)(int);
|
|
void (*sa_sigaction)(int, siginfo_t *, void *);
|
|
sigset_t sa_mask;
|
|
int sa_flags;
|
|
void (*sa_restorer)(void);
|
|
};
|
|
.fi
|
|
.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 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 may be
|
|
.B SIG_DFL
|
|
for the default action,
|
|
.B SIG_IGN
|
|
to ignore this signal, or 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 the signal number as its first argument, a
|
|
pointer to a
|
|
.I siginfo_t
|
|
as its second argument and a pointer to a
|
|
.I ucontext_t
|
|
(cast to \fIvoid\ *\fP) as its third argument.
|
|
(Commonly, the handler function doesn't make any use of the third argument.
|
|
See
|
|
.BR getcontext (3)
|
|
for further information about
|
|
.IR ucontext_t .)
|
|
.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:
|
|
.RS 4
|
|
.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 .
|
|
|
|
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 prevent the signal from being received from within its own signal
|
|
handler.
|
|
This flag is meaningful only when establishing a signal handler.
|
|
.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.
|
|
.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.)
|
|
.RE
|
|
.PP
|
|
The
|
|
.I siginfo_t
|
|
argument to
|
|
.I sa_sigaction
|
|
is a struct with the following fields:
|
|
.sp
|
|
.in +4n
|
|
.nf
|
|
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 */
|
|
sigval_t 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_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) */
|
|
}
|
|
.fi
|
|
.in
|
|
|
|
.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.
|
|
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 *
|
|
.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).
|
|
.PP
|
|
.I si_code
|
|
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:
|
|
|
|
.nf
|
|
(SIGTRAP | PTRACE_EVENT_foo << 8).
|
|
.fi
|
|
|
|
For a regular signal, the following list shows the values which can be
|
|
placed in
|
|
.I si_code
|
|
for any signal, along with 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.
|
|
.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)"
|
|
Process taken branch trap.
|
|
.TP
|
|
.BR TRAP_HWBKPT " (since Linux 2.4)"
|
|
Hardware breakpoint/watchpoint.
|
|
.RE
|
|
.PP
|
|
The following values can be placed in
|
|
.I si_code
|
|
for a
|
|
.B SIGCHLD
|
|
signal:
|
|
.RS 4
|
|
.TP
|
|
.B CLD_EXITED
|
|
Child has exited.
|
|
.TP
|
|
.B CLD_KILLED
|
|
Child was killed.
|
|
.TP
|
|
.B CLD_DUMPED
|
|
Child terminated abnormally.
|
|
.TP
|
|
.B CLD_TRAPPED
|
|
Traced child has trapped.
|
|
.TP
|
|
.B CLD_STOPPED
|
|
Child has stopped.
|
|
.TP
|
|
.BR CLD_CONTINUED " (since Linux 2.6.9)"
|
|
Stopped child has continued.
|
|
.RE
|
|
.PP
|
|
The following values can be placed in
|
|
.I si_code
|
|
for a
|
|
.BR SIGIO / SIGPOLL
|
|
signal:
|
|
.RS 4
|
|
.TP
|
|
.B POLL_IN
|
|
Data input available.
|
|
.TP
|
|
.B POLL_OUT
|
|
Output buffers available.
|
|
.TP
|
|
.B POLL_MSG
|
|
Input message available.
|
|
.TP
|
|
.B POLL_ERR
|
|
I/O error.
|
|
.TP
|
|
.B POLL_PRI
|
|
High priority input available.
|
|
.TP
|
|
.B POLL_HUP
|
|
Device disconnected.
|
|
.RE
|
|
.PP
|
|
The following value can be placed in
|
|
.I si_code
|
|
for a
|
|
.BR SIGSYS
|
|
signal:
|
|
.RS 4
|
|
.TP
|
|
.BR SYS_SECCOMP " (since Linux 3.5)"
|
|
Triggered by a
|
|
.BR seccomp (2)
|
|
filter rule.
|
|
.RE
|
|
.SH RETURN VALUE
|
|
.BR sigaction ()
|
|
returns 0 on success; on error, \-1 is returned, and
|
|
.I errno
|
|
is set to indicate the error.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EFAULT
|
|
.IR act " or " oldact
|
|
points to memory which is not a valid part of the process address space.
|
|
.TP
|
|
.B EINVAL
|
|
An invalid signal was specified.
|
|
This will also be generated if an attempt
|
|
is made to change the action for
|
|
.BR SIGKILL " or " SIGSTOP ", "
|
|
which cannot be caught or ignored.
|
|
.SH CONFORMING TO
|
|
POSIX.1-2001, POSIX.1-2008, SVr4.
|
|
.\" SVr4 does not document the EINTR condition.
|
|
.SH NOTES
|
|
A child created via
|
|
.BR fork (2)
|
|
inherits a copy of its parent's signal dispositions.
|
|
During an
|
|
.BR execve (2),
|
|
the dispositions of handled signals are reset to the default;
|
|
the dispositions of ignored signals are left unchanged.
|
|
|
|
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 newer.
|
|
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 (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.
|
|
|
|
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,
|
|
namely by using a
|
|
.I sa_handler
|
|
with second argument of type
|
|
.IR "struct sigcontext".
|
|
See the relevant Linux kernel sources for details.
|
|
This use is obsolete now.
|
|
.SH BUGS
|
|
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.
|
|
.SH EXAMPLE
|
|
See
|
|
.BR mprotect (2).
|
|
.SH SEE ALSO
|
|
.BR kill (1),
|
|
.BR kill (2),
|
|
.BR killpg (2),
|
|
.BR pause (2),
|
|
.BR restart_syscall (2),
|
|
.BR seccomp (2)
|
|
.BR sigaltstack (2),
|
|
.BR signal (2),
|
|
.BR signalfd (2),
|
|
.BR sigpending (2),
|
|
.BR sigreturn (2),
|
|
.BR sigprocmask (2),
|
|
.BR sigsuspend (2),
|
|
.BR wait (2),
|
|
.BR raise (3),
|
|
.BR siginterrupt (3),
|
|
.BR sigqueue (3),
|
|
.BR sigsetops (3),
|
|
.BR sigvec (3),
|
|
.BR core (5),
|
|
.BR signal (7)
|