sigaction(2) sigaction(2)
NAME [Toc] [Back]
sigaction - examine and change signal action
SYNOPSIS [Toc] [Back]
#include <signal.h>
int sigaction (
int sig,
const struct sigaction *act,
struct sigaction *oact
);
DESCRIPTION [Toc] [Back]
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 header <signal.h> to include at least the following
members:
Member Type Member Name Description
void(*)(int) sa_handler SIG_DFL, SIG_IGN or
pointer to a
function.
sigset_t sa_mask Additional set of
signals to be
blocked during
execution 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
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 sa_handler field of the sigaction
structure identifies the action to be associated with the specified
signal. If the sa_handler field specifies a signal-catching function,
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
sigaction(2) sigaction(2)
the sa_mask field identifies a set of signals that will be added to
the thread's signal mask before the signal-catching function is
invoked. The SIGKILL and SIGSTOP 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 indicated.
The sa_flags field can be used to modify the behavior of the specified
signal. The following flags, defined in the header <signal.h>, can be
set in sa_flags:
SA_NOCLDSTOP Do not generate SIGCHLD when children
stop.
SA_ONSTACK If set and an alternate signal stack has
been declared with sigaltstack() or
sigstack(), the signal will be delivered
to the calling process on that stack.
Otherwise, the signal will be delivered on
the current stack.
SA_RESETHAND If set, the disposition of the signal will
be reset to SIG_DFL and the SA_SIGINFO
flag will be cleared on entry to the
signal handler (Note: SIGILL, SIGTRAP, and
SIGPWR cannot be automatically reset when
delivered; the system silently enforces
this restriction). Otherwise, the
disposition of the signal will 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 behaviour 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 will restart and will
not fail with [EINTR] unless otherwise
specified. If the flag is not set,
interruptible functions interrupted by
this signal will fail with errno set to
[EINTR].
SA_SIGINFO If cleared and the signal is caught, the
signal-catching function will be entered
as:
void func(int signo); where signo is the
only argument to the signal catching
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
sigaction(2) sigaction(2)
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 SA_SIGINFO is set and the signal is
caught, the signal-catching function will
be entered as:
void func(int signo, siginfo_t *info, void
*context); 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 ucontext_t to refer to the
context of the receiving process or thread
that was interrupted when the signal was
delivered. In this case the sa_sigaction
member 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
implementation-dependent 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 values of si_pid and
si_uid are otherwise meaningless.
If SA_SIGINFO is set in sa_flags,
subsequent occurrences of sig generated by
sigqueue() or as a result of any signalgenerating
function that supports the
specification of an application-defined
value - when sig is already pending - will
be queued in FIFO order until delivered,
and the application specified value will
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
sigaction(2) sigaction(2)
be passed to the signal-catching function
as the si_value member of info (See
Realtime Signals Extension). 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.
SA_NOCLDWAIT If set, and sig equals SIGCHLD, child
processes of the calling process will 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 will block until all of its
children terminate, and wait(), wait3(),
waitid(), and waitpid() will fail and set
errno to [ECHILD]. Otherwise, terminating
child processes will be transformed into
zombie processes, unless SIGCHLD is set to
SIG_IGN.
SA_NODEFER 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 SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags,
and the implementation supports the SIGCHLD signal, then a SIGCHLD
signal will be generated for the calling process whenever any of its
child processes stop. If sig is SIGCHLD and the SA_NOCLDSTOP flag is
set in sa_flags, then the implementation will not generate a SIGCHLD
signal in this way.
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 remains
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.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
sigaction(2) sigaction(2)
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 will 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].
A signal is said to be generated for (or sent to) a process when the
event that causes the signal first occurs. Examples of such events
include detection of hardware faults, timer expiration and terminal
activity, as well as the invocation of kill() and sigqueue(). 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 pending. Ordinarily, this interval cannot be
detected by an application. However, a signal can be blocked 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 initialized from that of its parent. The sigaction(),
sigprocmask(), and sigsuspend() functions control the manipulation 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
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
sigaction(2) sigaction(2)
signals are delivered to a process is unspecified.
When any stop signal ( SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU) is
generated for a process, any pending SIGCONT signals for that process
will be discarded. Conversely, when SIGCONT is generated for a
process, all pending stop signals for that process will be discarded.
When SIGCONT is generated for a process that is stopped, the process
will be continued, even if the SIGCONT signal is blocked or ignored.
If SIGCONT 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
expiration, asynchronous I/O completion, interprocess message arrival,
and the sigqueue() function, support the specification of an
application-defined value, either explicitly as a parameter to the
function or in a sigevent structure parameter (see signal(5)).
Realtime Signals Extension [Toc] [Back]
When a signal is generated by sigqueue() or any signal-generating
function that supports the specification of an application-defined
value, and if the SA_SIGINFO 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
SIGRTMIN to SIGRTMAX, 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 kill() or other events that cause signals to
occur, such as detection of hardware faults, alarm() timer expiration,
or terminal activity, 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.
Otherwise, 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 [Toc] [Back]
There are three types of action that can be associated with a signal:
SIG_DFL, SIG_IGN or a pointer to a function. Initially, all signals
will be set to SIG_DFL or SIG_IGN prior to entry of the main() routine
(see the exec functions). The actions prescribed by these values are
as follows:
SIG_DFL - signal-specific default action
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
sigaction(2) sigaction(2)
+ 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
SIGCHLD signal will be generated for its parent process,
unless the parent process has set the SA_NOCLDSTOP 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 SIGKILL 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
SIGTSTP, SIGTTIN, or SIGTTOU 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 SIG_DFL for a signal that is
pending, and whose default action is to ignore the signal (for
example, SIGCHLD), 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.
SIG_IGN - ignore signal
+ Delivery of the signal will have no effect on the process. The
behaviour of a process is undefined after it ignores a SIGFPE,
SIGILL, or SIGSEGV signal that was not generated by kill(),
sigqueue()or raise().
+ The system will not allow the action for the signals SIGKILL
or SIGSTOP to be set to SIG_IGN.
+ Setting a signal action to SIG_IGN 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 SIGCHLD signal to
SIG_IGN, the behaviour is unspecified, except as specified
below.
If the action for the SIGCHLD signal is set to SIG_IGN, child
processes of the calling processes will 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 will block until all of its children terminate,
and wait(), wait3(), waitid(), and waitpid() will fail and set
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
sigaction(2) sigaction(2)
errno to [ECHILD].
Pointer to a function - catch signal
+ On delivery of the signal, the receiving process is to execute
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 SA_SIGINFO is cleared, the signal-catching function will be
entered as:
void func(int signo);
where func is the specified signal-catching function and signo
is the signal number of the signal being delivered.
+ If SA_SIGINFO is set, the signal-catching function will be
entered as:
void func(int signo, siginfo_t *siginfo, void *ucontextptr);
where func is the specified signal-catching function, signo is
the signal number of the signal being delivered, siginfo
points to an object of type siginfo_t associated with the
signal being delivered, and ucontextptr points to a
ucontext_t.
+ The behaviour of a process is undefined after it returns
normally from a signal- catching function for a SIGBUS,
SIGFPE, SIGILL, or SIGSEGV signal that was not generated by
kill() or raise().
+ The system will not allow a process to catch the signals
SIGKILL and SIGSTOP.
+ If a process establishes a signal-catching function for the
SIGCHLD signal while it has a terminated child process for
which it has not waited, it is unspecified whether a SIGCHILD
signal is generated to indicate that child process.
+ When signal-catching functions are invoked asynchronously with
process execution, the behaviour 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
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
sigaction(2) sigaction(2)
functions.
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 functions
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
behaviour is undefined.
Signal Effects on Other Functions [Toc] [Back]
Signals affect the behaviour of certain functions (defined under the
"Async Signal Safe" section of thread_safety(5)) if delivered to a
process while it is executing 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 SIGCONT 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 interrupted
by the signal. If the signal-catching function executes a return
statement, the behaviour of the interrupted function will be as
described individually for that function. Signals that are ignored
will not affect the behaviour of any function; signals that are
blocked will not affect the behaviour of any function until they are
unblocked and then delivered.
RETURN VALUE [Toc] [Back]
Upon successful completion, sigaction() returns 0. Otherwise -1 is
returned, errno is set to indicate the error and no new signalcatching
function will be installed.
ERRORS [Toc] [Back]
The sigaction() function will 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.
[EFAULT] act or oact points to an invalid
address. The reliable detection of this
error is implementation dependent.
The sigaction() function may fail if:
[EINVAL] An attempt was made to set the action to
SIG_DFL for a signal that cannot be
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003
sigaction(2) sigaction(2)
caught or ignored (or both).
APPLICATION USAGE [Toc] [Back]
The sigaction() function supersedes the signal() interface, 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
behaviour of reentrant functions, as defined in the description, is as
specified by this document, regardless of invocation from a signalcatching
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 descriptor. The fact
that any specific function is listed as reentrant does not necessarily
mean that invocation of that function from a signal-catching 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 synchronizing access to shared data structures.
Note in particular that even the "safe" functions may modify the
global variable errno; the signal-catching function 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
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 traditionally
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. Because any combination of different functions
using a common data structure can cause reentrancy problems, this
document does not define the behaviour 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(), sigqueue(), or raise(), the behaviour 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 variable of type volatile sig_atomic_t.
Furthermore, if such a call fails, the value of errno is
indeterminate.
Hewlett-Packard Company - 10 - HP-UX 11i Version 2: August 2003
sigaction(2) sigaction(2)
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
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.
POSIX.4-1993 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 function to uncontext_t
*.
The BSD optional four argument signal handling function is not
supported by this specification. 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
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.
Threads Considerations [Toc] [Back]
The signal disposition, catch/ignore/default, established by
sigaction() is shared by all threads in the process.
If the signal disposition for sig is set to SIG_IGN or is set to
SIG_DFL 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).
FUTURE DIRECTIONS [Toc] [Back]
The fpathconf() 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 [Toc] [Back]
sigaction() was derived from the IEEE POSIX 1003.1-1988 Standard.
SEE ALSO [Toc] [Back]
kill(2), ptrace(2), sigaltstack(2), signal(2), sigpending(2),
Hewlett-Packard Company - 11 - HP-UX 11i Version 2: August 2003
sigaction(2) sigaction(2)
sigprocmask(2), sigqueue(2), sigspace(2), sigsuspend(2), wait(2),
waitid(2), setjmp(3C), sigsetops(3C), thread_safety(5).
STANDARDS CONFORMANCE [Toc] [Back]
sigaction(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1
Hewlett-Packard Company - 12 - HP-UX 11i Version 2: August 2003 [ Back ] |
