sigaction(2)sigaction(2)NAMEsigaction - examine and change signal action
SYNOPSISDESCRIPTION
The function allows the calling process to examine and/or specify the
action to be associated with a specific signal. The argument sig spec‐
ifies the signal; acceptable values are defined in
The structure sigaction, used to describe an action to be taken, is
defined in the header to include at least the following members:
Member Type Member Name Description
void(*)(int) sa_handler SIG_DFL, SIG_IGN or
pointer to a func‐
tion.
sigset_t sa_mask Additional set of
signals to be
blocked during exe‐
cution of signal-
catching function.
int sa_flags Special flags to
affect behavior of
signal.
void(*)(int, siginfo_t*,void *) sa_sigaction signal-catching
function.
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 handling of a
given signal. The sa_handler field of the structure identifies the
action to be associated with the specified signal. If the sa_handler
field specifies a signal-catching function, the sa_mask field identi‐
fies a set of signals that will be added to the thread's signal mask
before the signal-catching function is invoked. The and signals will
not be added to the signal mask using this mechanism; this restriction
will be enforced by the system without causing an error to be indi‐
cated.
The sa_flags field can be used to modify the behavior of the specified
signal. The following flags, defined in the header can be set in
sa_flags:
Do not generate when children stop.
If set and an alternate signal stack has been declared with
or the signal will be delivered to the
calling process on that stack. Other‐
wise, the signal will be delivered on the
current stack.
If set, the disposition of the signal will be reset to
and the flag will be cleared on entry to
the signal handler (Note: and cannot be
automatically reset when delivered; the
system silently enforces this restric‐
tion). Otherwise, the disposition of the
signal will not be modified on entry to
the signal handler. In addition, if this
flag is set, behaves as if the flag were
also set.
This flag affects the behavior of interruptible functions; that
is, those specified to fail with set to
If set, and a function specified as
interruptible is interrupted by this sig‐
nal, the function will restart and will
not fail with unless otherwise specified.
If the flag is not set, interruptible
functions interrupted by this signal will
fail with set to
If cleared and the signal is caught, the signal-catching
function will be entered as:
where is the only argument to the signal
catching function. In this case the
sa_handler member must be used to
describe the signal catching function and
the application must not modify the
sa_sigaction member.
If is set and the signal is caught, the
signal-catching function will be entered
as:
where two additional arguments are passed
to the signal catching function. If the
second argument is not a null pointer, it
will 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 ucon‐
text_t to refer to the context of the
receiving process or thread that was
interrupted when the signal was deliv‐
ered. In this case the sa_sigaction mem‐
ber must be used to describe the signal
catching function and the application
must not modify the sa_handler member.
The si_signo member of info contains the
system-generated signal number.
The si_errno member may contain implemen‐
tation-dependent additional error infor‐
mation; 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 iden‐
tifying 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 respec‐
tively indicate the process ID and the
real user ID of the sender. The values
of si_pid and si_uid are otherwise mean‐
ingless.
If is set in sa_flags, subsequent occur‐
rences of sig generated by or as a result
of any signal-generating function that
supports the specification of an applica‐
tion-defined value - when sig is already
pending - will be queued in FIFO order
until delivered, and the application
specified value will be passed to the
signal-catching function as the si_value
member of info (See If is not set in
sa_flags, then the disposition of subse‐
quent occurrences of sig when it is
already pending is implementation-
defined.
If set, and sig equals child processes of the calling
process will not be transformed into zom‐
bie processes when they terminate. If
the calling process subsequently waits
for its children, and the process has no
unwaited for children that were trans‐
formed into zombie processes, it will
block until all of its children termi‐
nate, and and will fail and set errno to
Otherwise, terminating child processes
will be transformed into zombie pro‐
cesses, unless is set to
If set and sig is caught, sig will not be added to
the process' signal mask on entry to the
signal handler unless it is included in
sa_mask. Otherwise, sig will always be
added to the process' signal mask on
entry to the signal handler.
If sig is and the flag is not set in sa_flags, and the implementation
supports the signal, then a signal will be generated for the calling
process whenever any of its child processes stop. If sig is and the
flag is set in sa_flags, then the implementation will not generate a
signal in this way.
When a signal is caught by a signal-catching function installed by a
new signal mask is calculated and installed for the duration of the
signal-catching function (or until a call to either or 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 or 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 remains installed
until another action is explicitly requested (by another call to until
the 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 the values of
the fields returned in the structure pointed to by oact are unspeci‐
fied, and in particular oact->sa_handler is not necessarily the same
value passed to However, if a pointer to the same structure or a copy
thereof is passed to a subsequent call to via the act argument, han‐
dling of the signal will be as if the original call to were repeated.
If 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 is ignored or causes an error to be
returned with set to
A signal is said to be for (or sent to) a process when the event that
causes the signal first occurs. Examples of such events include detec‐
tion of hardware faults, timer expiration and terminal activity, as
well as the invocation of and In some circumstances, the same event
generates signals for multiple processes.
Each process has an action to be taken in response to each signal
defined by the system (see Signal Actions). A signal is said to be
delivered to a process when the appropriate action for the process and
signal is taken.
During the time between the generation of a signal and its delivery,
the signal is said to be Ordinarily, this interval cannot be detected
by an application.
However, a signal can be from delivery to a thread. If the action
associated with a blocked signal is anything other than to ignore the
signal, and if that signal is generated for the thread, the signal will
remain pending until either it is unblocked or the action associated
with it is set to ignore the signal.
If the action associated with a blocked signal is to ignore the signal
and if that signal is generated for the process, it is unspecified
whether the signal is discarded immediately upon generation or remains
pending.
Each thread has a signal mask that defines the set of signals currently
blocked from delivery to it. The signal mask for a thread is initial‐
ized from that of its parent. The and functions control the manipula‐
tion of the signal mask.
The determination of which action is taken in response to a signal is
made at the time the signal is delivered, allowing for any changes
since the time of generation. This determination is independent of the
means by which the signal was originally generated. If a subsequent
occurrence of a pending signal is generated, it is implementation-
dependent as to whether the signal is delivered more than once. The
order in which multiple, simultaneously pending signals are delivered
to a process is unspecified.
When any stop signal is generated for a process, any pending signals
for that process will be discarded. Conversely, when is generated for
a process, all pending stop signals for that process will be discarded.
When is generated for a process that is stopped, the process will be
continued, even if the signal is blocked or ignored. If is blocked and
not ignored, it will remain pending until it is either unblocked or a
stop signal is generated for the process.
Some signal-generating functions, such as high-resolution timer expira‐
tion, asynchronous I/O completion, interprocess message arrival, and
the function, support the specification of an application-defined
value, either explicitly as a parameter to the function or in a struc‐
ture parameter (see signal(5)).
Realtime Signals Extension
When a signal is generated by or any signal-generating function that
supports the specification of an application-defined value, and if the
flag is set for that signal, the signal will be queued to the process
along with the application-specified signal value.
Multiple occurrences of signals so generated are queued in FIFO order.
When multiple unblocked signals, all in the range to are pending, the
implementation delivers the pending unblocked signal with the lowest
signal number within that range.
The selection order between realtime and nonrealtime signals, or
between multiple pending nonrealtime signals, is unspecified.
Signals generated by or other events that cause signals to occur, such
as detection of hardware faults, timer expiration, or terminal activ‐
ity, and for which the implementation does not support queueing, will
have no effect on signals already queued for the same signal number.
If, when a pending signal is delivered, there are additional signals to
be queued to that signal number, the signal will remain pending. Oth‐
erwise, the pending indication will be reset.
An implementation will document any condition not specified by this
document under which the implementation generates signals.
Signal Actions
There are three types of action that can be associated with a signal:
or a pointer to a function. Initially, all signals will be set to or
prior to entry of the routine (see the functions). The actions pre‐
scribed by these values are as follows:
- signal-specific default action
· The default actions for the signals defined in this document
are specified under signal(5).
· If the default action is to stop the process, the execution
of that process is temporarily suspended. When a process
stops, a signal will be generated for its parent process,
unless the parent process has set the flag. While a process
is stopped, any additional signals that are sent to the
process will not be delivered until the process is continued,
except which always terminates the receiving process. A
process that is a member of an orphaned process group will
not be allowed to stop in response to the or signals. In
cases where delivery of one of these signals would stop such
a process, the signal will be discarded.
· Setting a signal action to for a signal that is pending, and
whose default action is to ignore the signal (for example,
will cause the pending signal to be discarded, whether or not
it is blocked. Any queued values pending will be discarded,
and the system resources used to queue them will be released
and made available to queue other signals.
- ignore signal
· Delivery of the signal will have no effect on the process.
The behavior of a process is undefined after it ignores a or
signal that was not generated by
· The system will not allow the action for the signals or to be
set to
· Setting a signal action to for a signal that is pending will
cause the pending signal to be discarded, whether or not it
is blocked. Any queued values pending will be discarded, and
the system resources used to queue them will be released and
made available to queue other signals.
· If a process sets the action for the signal to the behavior
is unspecified, except as specified below.
If the action for the signal is set to child processes of the
calling processes will not be transformed into zombie pro‐
cesses when they terminate. If the calling process subse‐
quently waits for its children, and the process has no
unwaited for children that were transformed into zombie pro‐
cesses, it will block until all of its children terminate,
and and will fail and set to
Pointer to a function - catch signal
· On delivery of the signal, the receiving process is to exe‐
cute the signal-catching function at the specified address.
After returning from the signal-catching function, the
receiving process will resume execution at the point at which
it was interrupted.
· If is cleared, the signal-catching function will be entered
as:
where is the specified signal-catching function and signo is
the signal number of the signal being delivered.
· If is set, the signal-catching function will be entered as:
where is the specified signal-catching function, is the sig‐
nal number of the signal being delivered, siginfo points to
an object of type siginfo_t associated with the signal being
delivered, and points to a ucontext_t.
· The behavior of a process is undefined after it returns nor‐
mally from a signal- catching function for a or signal that
was not generated by or
· The system will not allow a process to catch the signals and
· If a process establishes a signal-catching function for the
signal while it has a terminated child process for which it
has not waited, a signal is delivered to the parent process
immediately.
· When signal-catching functions are invoked asynchronously
with process execution, the behavior of some of the functions
defined by this document is unspecified if they are called
from a signal-catching function.
Refer to the "Async Signal Safe" section of thread_safety(5)
which defines a set of functions that are either reentrant or
not interruptible by signals. Therefore applications may
invoke them, without restriction, from signal-catching func‐
tions.
All functions not mentioned under the "Async Signal Safe"
section of thread_safety(5) are considered to be unsafe with
respect to signals. In the presence of signals, all func‐
tions defined by this document will behave as defined when
called from or interrupted by a signal-catching function,
with a single exception: when a signal interrupts an unsafe
function and the signal-catching function calls an unsafe
function, the behavior is undefined.
Signal Effects on Other Functions
Signals affect the behavior of certain functions (defined under the
section of thread_safety(5)) if delivered to a process while it is exe‐
cuting such a function. If the action of the signal is to terminate
the process, the process will be terminated and the function will not
return.
If the action of the signal is to stop the process, the process will
stop until continued or terminated. Generation of a signal for the
process causes the process to be continued, and the original function
will continue at the point the process was stopped.
If the action of the signal is to invoke a signal-catching function,
the signal-catching function will be invoked; in this case the original
function is said to be by the signal. If the signal-catching function
executes a return statement, the behavior of the interrupted function
will be as described individually for that function. Signals that are
ignored will not affect the behavior of any function; signals that are
blocked will not affect the behavior of any function until they are
unblocked and then delivered.
APPLICATION USAGE
The function supersedes the interface, and should be used in prefer‐
ence. In particular, and should not be used in the same process to
control the same signal.
The behavior of reentrant functions, as defined in the description, is
as specified by this document, 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 with‐
out 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 and interactions among multiple handles
for a file descriptor.
The fact that any specific function is listed as reentrant does not
necessarily mean that invocation of that function from a signal-catch‐
ing function is recommended.
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.
This document does not address the more general problem of synchroniz‐
ing access to shared data structures. Note in particular that even the
"safe" functions may modify the global variable the signal-catching
function 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 and are not in the list of reentrant functions. This is
because the code executing after and can call any unsafe functions with
the same danger as calling those unsafe functions directly from the
signal handler. Applications that use and 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 or functions or the standard I/O
library, both of which traditionally use data structures in a non-reen‐
trant manner.
Because any combination of different functions using a common data
structure can cause reentrancy problems, this document 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 or the behav‐
ior is undefined if the signal handler calls any function in the stan‐
dard 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 variable of type
volatile sig_atomic_t. Furthermore, if such a call fails, the value of
is indeterminate.
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 will resume exe‐
cution at the point it was interrupted unless the signal handler makes
other arrangements. If or is used to leave the signal handler, then
the signal mask must be explicitly restored by the process.
POSIX.4-1993 defines the third argument of a signal handling function
when is set as a void * instead of a ucontext_t *, but without requir‐
ing type checking. New applications should explicitly cast the third
argument of the signal handling function to uncontext_t *.
The BSD optional four argument signal handling function is not sup‐
ported by this specification. The BSD declaration would be
where sig is the signal number, code is additional information on cer‐
tain signals, scp is a pointer to the 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 speci‐
fied when is set.
Threads Considerations
The signal disposition, catch/ignore/default, established by is shared
by all threads in the process.
If the signal disposition for sig is set to or is set to and the
default action for sig is to ignore the signal, any instances of sig
pending on the process or any of the threads will be discarded. The
signals are discarded regardless of whether the signal is blocked by
any of the threads.
For more information regarding signals and threads, see signal(5).
RETURN VALUE
Upon successful completion, returns 0. Otherwise −1 is returned, is
set to indicate the error and no new signal-catching function will be
installed.
ERRORS
The function will fail if:
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.
act or oact points to an invalid address. The reli‐
able detection of this error is implementation
dependent.
The function may fail if:
An attempt was made to set the action to
for a signal that cannot be caught or
ignored (or both).
WARNINGS
The function is marked as an extension in the list of safe functions
because it is not included in the corresponding list in the ISO POSIX-1
standard, but it is expected to be added in a future revision of that
standard.
AUTHOR
was derived from the IEEE POSIX 1003.1-1988 Standard.
SEE ALSOkill(2), sigaltstack(2), signal(2), sigpending(2), sigprocmask(2),
sigqueue(2), sigspace(2), sigsuspend(2), ttrace(2), wait(2), waitid(2),
setjmp(3C), sigsetops(3C), thread_safety(5).
STANDARDS CONFORMANCEsigaction(2)
