sigaction (2) - Linux Manuals
sigaction: examine and change a signal action
Command to display sigaction manual in Linux: $ man 2 sigaction
NAME
sigaction, rt_sigaction - examine and change a signal action
SYNOPSIS
#include <signal.h>
int sigaction(int signum, const struct sigaction *act,
struct sigaction *oldact);
Feature Test Macro Requirements for glibc (see
feature_test_macros(7)):
sigaction():
_POSIX_C_SOURCE
siginfo_t:
_POSIX_C_SOURCE >= 199309L
DESCRIPTION
The
sigaction()
system call is used to change the action taken by a process on
receipt of a specific signal.
(See
signal(7)
for an overview of signals.)
signum
specifies the signal and can be any valid signal except
SIGKILL
and
SIGSTOP.
If
act
is non-NULL, the new action for signal
signum
is installed from
act.
If
oldact
is non-NULL, the previous action is saved in
oldact.
The
sigaction
structure is defined as something like:
struct sigaction {
void (*sa_handler)(int);
void (*sa_sigaction)(int, siginfo_t *, void *);
sigset_t sa_mask;
int sa_flags;
void (*sa_restorer)(void);
};
On some architectures a union is involved: do not assign to both
sa_handler
and
sa_sigaction.
The
sa_restorer
field is not intended for application use.
(POSIX does not specify a
sa_restorer
field.)
Some further details of the purpose of this field can be found in
sigreturn(2).
sa_handler
specifies the action to be associated with
signum
and is be one of the following:
- *
-
SIG_DFL
for the default action.
- *
-
SIG_IGN
to ignore this signal.
- *
-
A pointer to a signal handling function.
This function receives the signal number as its only argument.
If
SA_SIGINFO
is specified in
sa_flags,
then
sa_sigaction
(instead of
sa_handler)
specifies the signal-handling function for
signum.
This function receives three arguments, as described below.
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
SA_NODEFER
flag is used.
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:
- SA_NOCLDSTOP
-
If
signum
is
SIGCHLD,
do not receive notification when child processes stop (i.e., when they
receive one of
SIGSTOP, SIGTSTP, SIGTTIN,
or
SIGTTOU)
or resume (i.e., they receive
SIGCONT)
(see
wait(2)).
This flag is meaningful only when establishing a handler for
SIGCHLD.
- SA_NOCLDWAIT (since Linux 2.6)
-
If
signum
is
SIGCHLD,
do not transform children into zombies when they terminate.
See also
waitpid(2).
This flag is meaningful only when establishing a handler for
SIGCHLD,
or when setting that signal's disposition to
SIG_DFL.
-
If the
SA_NOCLDWAIT
flag is set when establishing a handler for
SIGCHLD,
POSIX.1 leaves it unspecified whether a
SIGCHLD
signal is generated when a child process terminates.
On Linux, a
SIGCHLD
signal is generated in this case;
on some other implementations, it is not.
- SA_NODEFER
-
Do not add the signal to the thread's signal mask while the
handler is executing, unless the signal is specified in
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.
-
SA_NOMASK
is an obsolete, nonstandard synonym for this flag.
- SA_ONSTACK
-
Call the signal handler on an alternate signal stack provided by
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.
- 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.
-
SA_ONESHOT
is an obsolete, nonstandard synonym for this flag.
- 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
signal(7)
for a discussion of system call restarting.
- SA_RESTORER
-
Not intended for application use.
This flag is used by C libraries to indicate that the
sa_restorer
field contains the address of a "signal trampoline".
See
sigreturn(2)
for more details.
- SA_SIGINFO (since Linux 2.2)
-
The signal handler takes three arguments, not one.
In this case,
sa_sigaction
should be set instead of
sa_handler.
This flag is meaningful only when establishing a signal handler.
The siginfo_t argument to a SA_SIGINFO handler
When the
SA_SIGINFO
flag is specified in
act.sa_flags,
the signal handler address is passed via the
act.sa_sigaction
field.
This handler takes three arguments, as follows:
void
handler(int sig, siginfo_t *info, void *ucontext)
{
...
}
These three arguments are as follows
- sig
-
The number of the signal that caused invocation of the handler.
- info
-
A pointer to a
siginfo_t,
which is a structure containing further information about the signal,
as described below.
- ucontext
-
This is a pointer to a
ucontext_t
structure, cast to void *.
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
sigreturn(2).
Further information about the
ucontext_t
structure can be found in
getcontext(3)
and
signal(7).
Commonly, the handler function doesn't make any use of the third argument.
The
siginfo_t
data type is a structure with the following fields:
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) */
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;