SIGACTION(P) POSIX Programmer's Manual SIGACTION(P)NAMEsigaction - examine and change a signal action
SYNOPSIS
#include <signal.h>
int sigaction(int sig, const struct sigaction *restrict act,
struct sigaction *restrict oact);
DESCRIPTION
The sigaction() function allows the calling process to examine and/or
specify the action to be associated with a specific signal. The argu‐
ment sig specifies the signal; acceptable values are defined in <sig‐
nal.h>.
The structure sigaction, used to describe an action to be taken, is
defined in the <signal.h> header to include at least the following mem‐
bers:
Member Type Member Name Description
void(*) (int) sa_handler Pointer to a signal-catching
function or one of the macros
SIG_IGN or SIG_DFL.
sigset_t sa_mask Additional set of signals to
be blocked during execution of
signal-catching function.
int sa_flags Special flags to affect behav‐
ior of signal.
void(*) (int,
siginfo_t *, sa_sigaction Pointer to a signal-catching
void *) function.
The storage occupied by sa_handler and sa_sigaction may overlap, and a
conforming application shall not use both simultaneously.
If the argument act is not a null pointer, it points to a structure
specifying the action to be associated with the specified signal. If
the argument oact is not a null pointer, the action previously associ‐
ated with the signal is stored in the location pointed to by the argu‐
ment oact. If the argument act is a null pointer, signal handling is
unchanged; thus, the call can be used to enquire about the current han‐
dling of a given signal. The SIGKILL and SIGSTOP signals shall not be
added to the signal mask using this mechanism; this restriction shall
be enforced by the system without causing an error to be indicated.
If the SA_SIGINFO flag (see below) is cleared in the sa_flags field of
the sigaction structure, the sa_handler field identifies the action to
be associated with the specified signal. If the SA_SIGINFO flag is
set in the sa_flags field, and the implementation supports the Realtime
Signals Extension option or the XSI Extension option, the sa_sigaction
field specifies a signal-catching function. If the SA_SIGINFO bit is
cleared and the sa_handler field specifies a signal-catching function,
or if the SA_SIGINFO bit is set, the sa_mask field identifies a set of
signals that shall be added to the signal mask of the thread before the
signal-catching function is invoked. If the sa_handler field specifies
a signal-catching function, the sa_mask field identifies a set of sig‐
nals that shall be added to the process' signal mask before the signal-
catching function is invoked.
The sa_flags field can be used to modify the behavior of the specified
signal.
The following flags, defined in the <signal.h> header, can be set in
sa_flags:
SA_NOCLDSTOP
Do not generate SIGCHLD when children stop or stopped chil‐
dren continue.
If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags, and
the implementation supports the SIGCHLD signal, then a SIGCHLD signal
shall be generated for the calling process whenever any of its child
processes stop and a SIGCHLD signal may be generated for the calling
process whenever any of its stopped child processes are continued. If
sig is SIGCHLD and the SA_NOCLDSTOP flag is set in sa_flags, then the
implementation shall not generate a SIGCHLD signal in this way.
SA_ONSTACK
If set and an alternate signal stack has been declared with
sigaltstack(), the signal shall be delivered to the calling
process on that stack. Otherwise, the signal shall be delivered
on the current stack.
SA_RESETHAND
If set, the disposition of the signal shall be reset to SIG_DFL
and the SA_SIGINFO flag shall be cleared on entry to the signal
handler.
Note:
SIGILL and SIGTRAP cannot be automatically reset when delivered;
the system silently enforces this restriction.
Otherwise, the disposition of the signal shall not be modified on entry
to the signal handler.
In addition, if this flag is set, sigaction() behaves as if the
SA_NODEFER flag were also set.
SA_RESTART
This flag affects the behavior of interruptible functions; that
is, those specified to fail with errno set to [EINTR]. If set,
and a function specified as interruptible is interrupted by this
signal, the function shall restart and shall not fail with
[EINTR] unless otherwise specified. If the flag is not set,
interruptible functions interrupted by this signal shall fail
with errno set to [EINTR].
SA_SIGINFO
If cleared and the signal is caught, the signal-catching func‐
tion shall be entered as:
void func(int signo);
where signo is the only argument to the signal-catching function. In
this case, the application shall use the sa_handler member to describe
the signal-catching function and the application shall not modify the
sa_sigaction member.
If SA_SIGINFO is set and the signal is caught, the signal-catching
function shall be entered as:
void func(int signo, siginfo_t *info, void *context);
where two additional arguments are passed to the signal-catching func‐
tion. The second argument shall point to an object of type siginfo_t
explaining the reason why the signal was generated; the third argument
can be cast to a pointer to an object of type ucontext_t to refer to
the receiving process' context that was interrupted when the signal was
delivered. In this case, the application shall use the sa_sigaction
member to describe the signal-catching function and the application
shall not modify the sa_handler member.
The si_signo member contains the system-generated signal number.
The si_errno member may contain implementation-defined additional error
information; if non-zero, it contains an error number identifying the
condition that caused the signal to be generated.
The si_code member contains a code identifying the cause of the signal.
If the value of si_code is less than or equal to 0, then the signal was
generated by a process and si_pid and si_uid, respectively, indicate
the process ID and the real user ID of the sender. The <signal.h>
header description contains information about the signal-specific con‐
tents of the elements of the siginfo_t type.
SA_NOCLDWAIT
If set, and sig equals SIGCHLD, child processes of the calling
processes shall not be transformed into zombie processes when
they terminate. If the calling process subsequently waits for
its children, and the process has no unwaited-for children that
were transformed into zombie processes, it shall block until all
of its children terminate, and wait(), waitid(), and waitpid()
shall fail and set errno to [ECHILD]. Otherwise, terminating
child processes shall be transformed into zombie processes,
unless SIGCHLD is set to SIG_IGN.
SA_NODEFER
If set and sig is caught, sig shall not be added to the process'
signal mask on entry to the signal handler unless it is included
in sa_mask. Otherwise, sig shall always be added to the process'
signal mask on entry to the signal handler.
When a signal is caught by a signal-catching function installed by
sigaction(), a new signal mask is calculated and installed for the
duration of the signal-catching function (or until a call to either
sigprocmask() or sigsuspend() is made). This mask is formed by taking
the union of the current signal mask and the value of the sa_mask for
the signal being delivered unless SA_NODEFER or SA_RESETHAND is set,
and then including the signal being delivered. If and when the user's
signal handler returns normally, the original signal mask is restored.
Once an action is installed for a specific signal, it shall remain
installed until another action is explicitly requested (by another call
to sigaction()), until the SA_RESETHAND flag causes resetting of the
handler, or until one of the exec functions is called.
If the previous action for sig had been established by signal(), the
values of the fields returned in the structure pointed to by oact are
unspecified, and in particular oact-> sa_handler is not necessarily the
same value passed to signal(). However, if a pointer to the same
structure or a copy thereof is passed to a subsequent call to sigac‐
tion() via the act argument, handling of the signal shall be as if the
original call to signal() were repeated.
If sigaction() fails, no new signal handler is installed.
It is unspecified whether an attempt to set the action for a signal
that cannot be caught or ignored to SIG_DFL is ignored or causes an
error to be returned with errno set to [EINVAL].
If SA_SIGINFO is not set in sa_flags, then the disposition of subse‐
quent occurrences of sig when it is already pending is implementation-
defined; the signal-catching function shall be invoked with a single
argument. If the implementation supports the Realtime Signals Exten‐
sion option, and if SA_SIGINFO is set in sa_flags, then subsequent
occurrences of sig generated by sigqueue() or as a result of any sig‐
nal-generating function that supports the specification of an applica‐
tion-defined value (when sig is already pending) shall be queued in
FIFO order until delivered or accepted; the signal-catching function
shall be invoked with three arguments. The application specified value
is passed to the signal-catching function as the si_value member of the
siginfo_t structure.
The result of the use of sigaction() and a sigwait() function concur‐
rently within a process on the same signal is unspecified.
RETURN VALUE
Upon successful completion, sigaction() shall return 0; otherwise, -1
shall be returned, errno shall be set to indicate the error, and no new
signal-catching function shall be installed.
ERRORS
The sigaction() function shall fail if:
EINVAL The sig argument is not a valid signal number or an attempt is
made to catch a signal that cannot be caught or ignore a signal
that cannot be ignored.
ENOTSUP
The SA_SIGINFO bit flag is set in the sa_flags field of the
sigaction structure, and the implementation does not support
either the Realtime Signals Extension option, or the XSI Exten‐
sion option.
The sigaction() function may fail if:
EINVAL An attempt was made to set the action to SIG_DFL for a signal
that cannot be caught or ignored (or both).
The following sections are informative.
EXAMPLES
None.
APPLICATION USAGE
The sigaction() function supersedes the signal() function, and should
be used in preference. In particular, sigaction() and signal() should
not be used in the same process to control the same signal. The behav‐
ior of reentrant functions, as defined in the DESCRIPTION, is as speci‐
fied by this volume of IEEE Std 1003.1-2001, regardless of invocation
from a signal-catching function. This is the only intended meaning of
the statement that reentrant functions may be used in signal-catching
functions without restrictions. Applications must still consider all
effects of such functions on such things as data structures, files, and
process state. In particular, application writers need to consider the
restrictions on interactions when interrupting sleep() and interactions
among multiple handles for a file description. The fact that any spe‐
cific function is listed as reentrant does not necessarily mean that
invocation of that function from a signal-catching function is recom‐
mended.
In order to prevent errors arising from interrupting non-reentrant
function calls, applications should protect calls to these functions
either by blocking the appropriate signals or through the use of some
programmatic semaphore (see semget() , sem_init() , sem_open() , and so
on). Note in particular that even the "safe" functions may modify
errno; the signal-catching function, if not executing as an independent
thread, may want to save and restore its value. Naturally, the same
principles apply to the reentrancy of application routines and asyn‐
chronous data access. Note that longjmp() and siglongjmp() are not in
the list of reentrant functions. This is because the code executing
after longjmp() and siglongjmp() can call any unsafe functions with the
same danger as calling those unsafe functions directly from the signal
handler. Applications that use longjmp() and siglongjmp() from within
signal handlers require rigorous protection in order to be portable.
Many of the other functions that are excluded from the list are tradi‐
tionally implemented using either malloc() or free() functions or the
standard I/O library, both of which traditionally use data structures
in a non-reentrant manner. Since any combination of different functions
using a common data structure can cause reentrancy problems, this vol‐
ume of IEEE Std 1003.1-2001 does not define the behavior when any
unsafe function is called in a signal handler that interrupts an unsafe
function.
If the signal occurs other than as the result of calling abort(),
kill(), or raise(), the behavior is undefined if the signal handler
calls any function in the standard library other than one of the func‐
tions listed in the table above or refers to any object with static
storage duration other than by assigning a value to a static storage
duration variable of type volatile sig_atomic_t. Furthermore, if such a
call fails, the value of errno is unspecified.
Usually, the signal is executed on the stack that was in effect before
the signal was delivered. An alternate stack may be specified to
receive a subset of the signals being caught.
When the signal handler returns, the receiving process resumes execu‐
tion at the point it was interrupted unless the signal handler makes
other arrangements. If longjmp() or _longjmp() is used to leave the
signal handler, then the signal mask must be explicitly restored by the
process.
This volume of IEEE Std 1003.1-2001 defines the third argument of a
signal handling function when SA_SIGINFO is set as a void * instead of
a ucontext_t *, but without requiring type checking. New applications
should explicitly cast the third argument of the signal handling func‐
tion to ucontext_t *.
The BSD optional four argument signal handling function is not sup‐
ported by this volume of IEEE Std 1003.1-2001. The BSD declaration
would be:
void handler(int sig, int code, struct sigcontext *scp,
char *addr);
where sig is the signal number, code is additional information on cer‐
tain signals, scp is a pointer to the sigcontext structure, and addr is
additional address information. Much the same information is available
in the objects pointed to by the second argument of the signal handler
specified when SA_SIGINFO is set.
RATIONALE
Although this volume of IEEE Std 1003.1-2001 requires that signals that
cannot be ignored shall not be added to the signal mask when a signal-
catching function is entered, there is no explicit requirement that
subsequent calls to sigaction() reflect this in the information
returned in the oact argument. In other words, if SIGKILL is included
in the sa_mask field of act, it is unspecified whether or not a subse‐
quent call to sigaction() returns with SIGKILL included in the sa_mask
field of oact.
The SA_NOCLDSTOP flag, when supplied in the act-> sa_flags parameter,
allows overloading SIGCHLD with the System V semantics that each SIGCLD
signal indicates a single terminated child. Most conforming applica‐
tions that catch SIGCHLD are expected to install signal-catching func‐
tions that repeatedly call the waitpid() function with the WNOHANG flag
set, acting on each child for which status is returned, until waitpid()
returns zero. If stopped children are not of interest, the use of the
SA_NOCLDSTOP flag can prevent the overhead from invoking the signal-
catching routine when they stop.
Some historical implementations also define other mechanisms for stop‐
ping processes, such as the ptrace() function. These implementations
usually do not generate a SIGCHLD signal when processes stop due to
this mechanism; however, that is beyond the scope of this volume of
IEEE Std 1003.1-2001.
This volume of IEEE Std 1003.1-2001 requires that calls to sigaction()
that supply a NULL act argument succeed, even in the case of signals
that cannot be caught or ignored (that is, SIGKILL or SIGSTOP). The
System V signal() and BSD sigvec() functions return [EINVAL] in these
cases and, in this respect, their behavior varies from sigaction().
This volume of IEEE Std 1003.1-2001 requires that sigaction() properly
save and restore a signal action set up by the ISO C standard signal()
function. However, there is no guarantee that the reverse is true, nor
could there be given the greater amount of information conveyed by the
sigaction structure. Because of this, applications should avoid using
both functions for the same signal in the same process. Since this can‐
not always be avoided in case of general-purpose library routines, they
should always be implemented with sigaction().
It was intended that the signal() function should be implementable as a
library routine using sigaction().
The POSIX Realtime Extension extends the sigaction() function as speci‐
fied by the POSIX.1-1990 standard to allow the application to request
on a per-signal basis via an additional signal action flag that the
extra parameters, including the application-defined signal value, if
any, be passed to the signal-catching function.
FUTURE DIRECTIONS
None.
SEE ALSO
Signal Concepts , bsd_signal() , kill() , _longjmp() , longjmp() ,
raise() , semget() , sem_init() , sem_open() , sigaddset() , sigalt‐
stack() , sigdelset() , sigemptyset() , sigfillset() , sigismember() ,
signal() , sigprocmask() , sigsuspend() , wait() , waitid() , waitpid()
, the Base Definitions volume of IEEE Std 1003.1-2001, <signal.h>,
<ucontext.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online
at http://www.opengroup.org/unix/online.html .
IEEE/The Open Group 2003 SIGACTION(P)
