SIGACTION(P) POSIX Programmer's Manual SIGACTION(P)
sigaction - examine and change a signal action
int sigaction(int sig, const struct sigaction *restrict act,
struct sigaction *restrict oact);
The sigaction() function allows the calling process to examine and/or specify the action
to be associated with a specific signal. The argument sig specifies the signal; acceptable
values are defined in <signal.h>.
The structure sigaction, used to describe an action to be taken, is defined in the <sig-
nal.h> header to include at least the following members:
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
int sa_flags Special flags to affect behav-
ior of signal.
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 applica-
tion 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 associated with the signal is stored in the location pointed to by
the argument oact. If the argument act is a null pointer, signal handling is unchanged;
thus, the call can be used to enquire about the current handling 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_sigac-
tion 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 speci-
fies a signal-catching function, the sa_mask field identifies a set of signals 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:
Do not generate SIGCHLD when children stop or stopped children 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.
If set and an alternate signal stack has been declared with sigaltstack(), the sig-
nal shall be delivered to the calling process on that stack. Otherwise, the signal
shall be delivered on the current stack.
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.
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 han-
In addition, if this flag is set, sigaction() behaves as if the SA_NODEFER flag were also
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 interrupt-
ible 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].
If cleared and the signal is caught, the signal-catching function shall be entered
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
void func(int signo, siginfo_t *info, void *context);
where two additional arguments are passed to the signal-catching function. 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 deliv-
ered. In this case, the application shall use the sa_sigaction member to describe the sig-
nal-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
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 contents of the elements of the siginfo_t type.
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 chil-
dren 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.
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 sig-
nal 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 tak-
ing 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 sig-
nal 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 sigaction() via the
act argument, handling of the signal shall be as if the original call to signal() were
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 [EIN-
If SA_SIGINFO is not set in sa_flags, then the disposition of subsequent 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 Extension option, and if SA_SIGINFO is set in sa_flags, then subsequent occur-
rences of sig generated by sigqueue() or as a result of any signal-generating function
that supports the specification of an application-defined value (when sig is already pend-
ing) shall be queued in FIFO order until delivered or accepted; the signal-catching func-
tion 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 concurrently within a
process on the same signal is unspecified.
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
The sigaction() function shall fail if:
EINVAL The sig argument is not a valid signal number or an attempt is made to catch a sig-
nal that cannot be caught or ignore a signal that cannot be ignored.
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 Extension 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.
The sigaction() function supersedes the signal() function, and should be used in prefer-
ence. In particular, sigaction() and signal() should not be used in the same process to
control the same signal. The behavior of reentrant functions, as defined in the DESCRIP-
TION, is as specified 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. Appli-
cations must still consider all effects of such functions on such things as data struc-
tures, 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 specific function is listed as reentrant
does not necessarily mean that invocation of that function from a signal-catching function
In order to prevent errors arising from interrupting non-reentrant function calls, appli-
cations 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 sig-
nal-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 asynchronous data access. Note that longjmp() and siglongjmp() are not in the
list of reentrant functions. This is because the code executing after longjmp() and sig-
longjmp() can call any unsafe functions with the same danger as calling those unsafe func-
tions 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 traditionally implemented using
either malloc() or free() functions or the standard I/O library, both of which tradition-
ally use data structures in a non-reentrant manner. Since any combination of different
functions using a common data structure can cause reentrancy problems, this volume 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 functions 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 vari-
able of type volatile sig_atomic_t. Furthermore, if such a call fails, the value of errno
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
When the signal handler returns, the receiving process resumes execution 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 func-
tion 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 function to ucontext_t *.
The BSD optional four argument signal handling function is not supported by this volume of
IEEE Std 1003.1-2001. The BSD declaration would be:
void handler(int sig, int code, struct sigcontext *scp,
where sig is the signal number, code is additional information on certain 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.
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 informa-
tion 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 subsequent 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 applications that catch SIGCHLD are expected to install signal-
catching functions 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 stopping 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 vol-
ume 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 guaran-
tee 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 cannot always be avoided in
case of general-purpose library routines, they should always be implemented with sigac-
It was intended that the signal() function should be implementable as a library routine
The POSIX Realtime Extension extends the sigaction() function as specified 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.
Signal Concepts , bsd_signal() , kill() , _longjmp() , longjmp() , raise() , semget() ,
sem_init() , sem_open() , sigaddset() , sigaltstack() , sigdelset() , sigemptyset() , sig-
fillset() , sigismember() , signal() , sigprocmask() , sigsuspend() , wait() , waitid() ,
waitpid() , the Base Definitions volume of IEEE Std 1003.1-2001, <signal.h>, <ucontext.h>
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 orig-
inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .
IEEE/The Open Group 2003 SIGACTION(P)