mirror of https://github.com/mkerrisk/man-pages
501 lines
12 KiB
Groff
501 lines
12 KiB
Groff
'\" t
|
|
.\" Copyright (c) 1994,1995 Mike Battersby <mib@deakin.edu.au>
|
|
.\" and Copyright 2004, 2005 Michael Kerrisk <mtk-manpages@gmx.net>
|
|
.\" based on work by faith@cs.unc.edu
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" 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@gmx.net>
|
|
.\" Added mention of SIGCONT under SA_NOCLDSTOP
|
|
.\" Added SA_NOCLDWAIT
|
|
.\" Modified 2004-11-17 by Michael Kerrisk <mtk-manpages@gmx.net>
|
|
.\" 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.
|
|
.\"
|
|
.TH SIGACTION 2 2005-09-15 "Linux 2.6.14" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
sigaction \- examine and change a signal action
|
|
.SH SYNOPSIS
|
|
.B #include <signal.h>
|
|
.sp
|
|
.BI "int sigaction(int " signum ", const struct sigaction *" act ,
|
|
.BI "struct sigaction *" oldact );
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR sigaction ()
|
|
system call is used to change the action taken by a process on
|
|
receipt of a specific signal.
|
|
.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
|
|
.RS
|
|
.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
|
|
.RE
|
|
.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
|
|
element is obsolete and should not be used.
|
|
POSIX does not specify a
|
|
.I sa_restorer
|
|
element.
|
|
.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 void *) as its third argument.
|
|
.PP
|
|
.I sa_mask
|
|
gives a mask of signals which should be blocked 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 behaviour of the signal handling
|
|
process. It is formed by the bitwise OR of zero or more of the following:
|
|
.RS
|
|
.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)).
|
|
.TP
|
|
.B SA_NOCLDWAIT
|
|
(Linux 2.6 and later)
|
|
.\" 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).
|
|
.TP
|
|
.B SA_RESETHAND
|
|
Restore the signal action to the default state once the signal handler
|
|
has been called.
|
|
.B SA_ONESHOT
|
|
is an obsolete, non-standard synonym for this flag.
|
|
.TP
|
|
.BR 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.
|
|
.TP
|
|
.B SA_RESTART
|
|
Provide behaviour compatible with BSD signal semantics by making certain
|
|
system calls restartable across signals.
|
|
.TP
|
|
.B SA_NODEFER
|
|
Do not prevent the signal from being received from within its own signal
|
|
handler.
|
|
.B SA_NOMASK
|
|
is an obsolete, non-standard synonym for this flag.
|
|
.TP
|
|
.B SA_SIGINFO
|
|
The signal handler takes 3 arguments, not one. In this case,
|
|
.I sa_sigaction
|
|
should be set instead of
|
|
.IR sa_handler .
|
|
(The
|
|
.I sa_sigaction
|
|
field was added in Linux 2.1.86.)
|
|
.RE
|
|
.PP
|
|
The
|
|
.I siginfo_t
|
|
parameter to
|
|
.I sa_sigaction
|
|
is a struct with the following elements
|
|
.sp
|
|
.RS
|
|
.nf
|
|
.ta 4 13 24
|
|
siginfo_t {
|
|
int si_signo; /* Signal number */
|
|
int si_errno; /* An errno value */
|
|
int si_code; /* Signal code */
|
|
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 */
|
|
void * si_addr; /* Memory location which caused fault */
|
|
int si_band; /* Band event */
|
|
int si_fd; /* File descriptor */
|
|
}
|
|
.fi
|
|
.RE
|
|
|
|
.IR si_signo ", " si_errno " and " si_code
|
|
are defined for all signals.
|
|
.RI ( si_signo
|
|
is unused on Linux.)
|
|
The rest of the struct may be a union, so that one should only
|
|
read the fields that are meaningful for the given signal.
|
|
POSIX.1b signals and
|
|
.B SIGCHLD
|
|
fill in
|
|
.IR si_pid " and " si_uid .
|
|
.BR
|
|
.B SIGCHLD
|
|
also fills in
|
|
.IR si_status ", " si_utime " and " si_stime .
|
|
.IR si_int " and " si_ptr
|
|
are specified by the sender of the POSIX.1b signal.
|
|
.\" See
|
|
.\" .BR sigqueue (2)
|
|
.\" for more details.
|
|
.BR SIGILL ,
|
|
.BR SIGFPE ,
|
|
.BR SIGSEGV ,
|
|
and
|
|
.B SIGBUS
|
|
fill in
|
|
.I si_addr
|
|
with the address of the fault.
|
|
.B SIGPOLL
|
|
fills in
|
|
.IR si_band " and " si_fd .
|
|
|
|
.I si_code
|
|
indicates why this signal was sent. It is a value, not a bitmask. The
|
|
values which are possible for any signal are listed in this table:
|
|
.TS
|
|
tab(:) allbox;
|
|
c s
|
|
l l.
|
|
\fIsi_code\fR
|
|
Value:Signal origin
|
|
SI_USER:kill(), sigsend(), or raise()
|
|
SI_KERNEL:The kernel
|
|
SI_QUEUE:sigqueue()
|
|
SI_TIMER:POSIX timer expired
|
|
SI_MESGQ:POSIX message queue state changed (since Linux 2.6.6)
|
|
SI_ASYNCIO:AIO completed
|
|
SI_SIGIO:queued SIGIO
|
|
SI_TKILL:tkill() or tgkill() (since Linux 2.4.19)
|
|
.\" 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.
|
|
.TE
|
|
|
|
.TS
|
|
tab(:) allbox;
|
|
c s
|
|
l l.
|
|
SIGILL
|
|
ILL_ILLOPC:illegal opcode
|
|
ILL_ILLOPN:illegal operand
|
|
ILL_ILLADR:illegal addressing mode
|
|
ILL_ILLTRP:illegal trap
|
|
ILL_PRVOPC:privileged opcode
|
|
ILL_PRVREG:privileged register
|
|
ILL_COPROC:coprocessor error
|
|
ILL_BADSTK:internal stack error
|
|
.TE
|
|
|
|
.TS
|
|
tab(:) allbox;
|
|
c s
|
|
l l.
|
|
SIGFPE
|
|
FPE_INTDIV:integer divide by zero
|
|
FPE_INTOVF:integer overflow
|
|
FPE_FLTDIV:floating point divide by zero
|
|
FPE_FLTOVF:floating point overflow
|
|
FPE_FLTUND:floating point underflow
|
|
FPE_FLTRES:floating point inexact result
|
|
FPE_FLTINV:floating point invalid operation
|
|
FPE_FLTSUB:subscript out of range
|
|
.TE
|
|
|
|
.TS
|
|
tab(:) allbox;
|
|
c s
|
|
l l.
|
|
SIGSEGV
|
|
SEGV_MAPERR:address not mapped to object
|
|
SEGV_ACCERR:invalid permissions for mapped object
|
|
.TE
|
|
|
|
.TS
|
|
tab(:) allbox;
|
|
c s
|
|
l l.
|
|
SIGBUS
|
|
BUS_ADRALN:invalid address alignment
|
|
BUS_ADRERR:non-existent physical address
|
|
BUS_OBJERR:object specific hardware error
|
|
.TE
|
|
|
|
.TS
|
|
tab(:) allbox;
|
|
c s
|
|
l l.
|
|
SIGTRAP
|
|
TRAP_BRKPT:process breakpoint
|
|
TRAP_TRACE:process trace trap
|
|
.TE
|
|
|
|
.TS
|
|
tab(:) allbox;
|
|
c s
|
|
l l.
|
|
SIGCHLD
|
|
CLD_EXITED:child has exited
|
|
CLD_KILLED:child was killed
|
|
CLD_DUMPED:child terminated abnormally
|
|
CLD_TRAPPED:traced child has trapped
|
|
CLD_STOPPED:child has stopped
|
|
CLD_CONTINUED:stopped child has continued (since Linux 2.6.9)
|
|
.TE
|
|
|
|
.TS
|
|
tab(:) allbox;
|
|
c s
|
|
l l.
|
|
SIGPOLL
|
|
POLL_IN:data input available
|
|
POLL_OUT:output buffers available
|
|
POLL_MSG:input message available
|
|
POLL_ERR:i/o error
|
|
POLL_PRI:high priority input available
|
|
POLL_HUP:device disconnected
|
|
.TE
|
|
|
|
.SH "RETURN VALUE"
|
|
.BR sigaction ()
|
|
returns 0 on success and \-1 on 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 NOTES
|
|
.PP
|
|
According to POSIX, the behaviour of a process is undefined after it
|
|
ignores a
|
|
.BR SIGFPE ,
|
|
.BR SIGILL ,
|
|
or
|
|
.BR SIGSEGV
|
|
signal that was not generated by
|
|
.BR kill ()
|
|
or
|
|
.BR raise ().
|
|
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 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 allows 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 behaviours 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 only specified
|
|
.BR SA_NOCLDSTOP .
|
|
POSIX.1-2001 added
|
|
.BR SA_NOCLDWAIT ,
|
|
.BR SA_RESETHAND ,
|
|
.BR SA_NODEFER ,
|
|
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
|
|
Support for
|
|
.B SA_SIGINFO
|
|
was added in Linux 2.2.
|
|
.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
|
|
.\"The
|
|
.\".BR SA_RESETHAND " and " SA_NODEFER
|
|
.\"names for SVr4 compatibility are present only in library versions 3.0.9
|
|
.\"and greater.
|
|
.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.
|
|
.SH BUGS
|
|
In kernels up to and including 2.6.13, specifying
|
|
.B SA_NODEFER
|
|
in
|
|
.I sa_flags
|
|
preventing not only the delivered signal from being masked during
|
|
execution of the handler, but also the signals specified in
|
|
.IR sa_mask .
|
|
This bug is was fixed in kernel 2.6.14.
|
|
.SH "CONFORMING TO"
|
|
POSIX, SVr4. SVr4 does not document the EINTR condition.
|
|
.SH UNDOCUMENTED
|
|
Before the introduction of
|
|
.B 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 kernel sources for details.
|
|
This use is obsolete now.
|
|
.SH "SEE ALSO"
|
|
.BR kill (1),
|
|
.BR kill (2),
|
|
.BR pause (2),
|
|
.BR sigaltstack (2),
|
|
.BR signal (2),
|
|
.BR sigpending (2),
|
|
.BR sigprocmask (2),
|
|
.BR sigqueue (2),
|
|
.BR sigsuspend (2),
|
|
.BR wait (2),
|
|
.BR killpg (3),
|
|
.BR raise (3),
|
|
.BR siginterrupt (3),
|
|
.BR sigsetops (3),
|
|
.BR sigvec (3),
|
|
.BR core (5),
|
|
.BR signal (7)
|