sigaction(2) sigaction(2)
NAME
sigaction - get/amend signal actions
SYNOPSIS
#include <signal.h>
int sigaction(int sig, const struct sigaction *act,
struct sigaction *oact);
DESCRIPTION
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>.
Only valid if generated with "c89":
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) sahandler SIGDFL, SIGIGN or pointer to a func-
tion.
sigsett samask Additional set of signals to be blocked
during execution of signal-catching
function.
int saflags Special flags to affect behavior of
signal.
void(*) (int, siginfot *, void *)
sasigaction Signal-catching function.
Only valid if generated with "cc":
void (*sahandler)();
sigsett samask;
int saflags;
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 sahandler field of the sigaction
structure identifies the action to be associated with the specified
signal. If the sahandler field specifies a signal-catching function,
the samask field identifies a set of signals that will be added to
the process' signal mask before the signal-catching function is
invoked. The SIGKILL and SIGSTOP signals will not be added to the sig-
nal mask using this mechanism; this restriction will be enforced by
the system without causing an error to be indicated.
Page 1 Reliant UNIX 5.44 Printed 11/98
sigaction(2) sigaction(2)
The saflags 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
saflags:
SANOCLDSTOP Do not generate SIGCHLD when children stop.
SAONSTACK 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. Other-
wise, the signal will be delivered on the current
stack.
SARESETHAND If set, the disposition of the signal will be reset to
SIGDFL and the SASIGINFO flag will be cleared on
entry to the signal handler (Note: SIGILL and SIGTRAP
cannot be automatically reset when delivered; the sys-
tem 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 SANODEFER flag were also set.
SARESTART This flag affects the behavior of interruptible func-
tions; that is, those specified to fail with errno set
to EINTR. If set, and a function specified as inter-
ruptible is interrupted by this signal, the function
will restart and will not fail with EINTR unless oth-
erwise specified. If the flag is not set, interrupti-
ble functions interrupted by this signal will fail
with errno set to EINTR.
SASIGINFO If cleared and the signal is caught, the signal-catch-
ing function will be entered as:
void func(int signo);
where signo is the only argument to the signal-catch-
ing function. In this case the sahandler member must
be used to describe the signal-catching function and
the application must not modify the sasigaction
member.
Only valid if generated in XPG4 mode (with "c89"):
If SASIGINFO is set and the signal is caught, the
signal-catching function will be entered as:
void func(int signo, siginfot *info, void *context);
Page 2 Reliant UNIX 5.44 Printed 11/98
sigaction(2) sigaction(2)
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
siginfot explaining the reason why the signal was
generated; the third argument can be cast to a pointer
to an object of type ucontextt to refer to the
receiving process' context that was interrupted when
the signal was delivered. In this case the
sasigaction member must be used to describe the
signal-catching function and the application must not
modify the sahandler member.
Only valid if generated with "cc":
If set and the signal is caught, pending signals of
type sig are reliably queued to the calling process
and two additional arguments are passed to the
signal-catching function. If the second argument is
not equal to NULL, it points to a siginfot structure
containing the reason why the signal was generated
[see siginfo(5)]; the third argument points to a
ucontextt structure containing the receiving process'
context when the signal was delivered [see
ucontext(5)].
Valid again below for both compilers:
The sisigno member contains the system-generated sig-
nal number.
The sierrno member may contain implementation-depen-
dent additional error information; if non-zero, it
contains an error number identifying the condition
that caused the signal to be generated.
The sicode member contains a code identifying the
cause of the signal. If the value of sicode is less
than or equal to 0, then the signal was generated by a
process and sipid and siuid respectively indicate
the process ID and the real user ID of the sender. The
values of sipid and siuid are otherwise meaningless.
SANOCLDWAIT If set, and sig equals SIGCHLD, 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 zom-
bie processes, it will block until all of its children
terminate, and wait(), wait3(), waitid() and waitpid()
will fail and set errno to ECHILD. Otherwise, terminat-
ing child processes will be transformed into zombie
processes, unless SIGCHLD is set to SIGIGN.
Page 3 Reliant UNIX 5.44 Printed 11/98
sigaction(2) sigaction(2)
SANODEFER 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 samask. Otherwise, sig will
always be added to the process' signal mask on entry
to the signal handler.
If sig is SIGCHLD and the SANOCLDSTOP flag is not set in saflags,
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 SANOCLDSTOP flag is
set in saflags, 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 samask for
the signal being delivered unless SANODEFER or SARESETHAND 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 SARESETHAND 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->sahandler 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 SIGDFL 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(). 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.
Page 4 Reliant UNIX 5.44 Printed 11/98
sigaction(2) sigaction(2)
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 process. If the action associated with a blocked signal
is anything other than to ignore the signal, and if that signal is
generated for the process, 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 genera-
tion or remains pending.
Each process has a signal mask that defines the set of signals
currently blocked from delivery to it. The signal mask for a process
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 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 con-
tinued, 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.
Signal Actions
There are three types of action that can be associated with a signal:
SIGDFL, SIGIGN or a pointer to a function. Initially, all signals
will be set to SIGDFL or SIGIGN prior to entry of the main() routine
(see the exec functions). The actions prescribed by these values are
as follows:
SIGDFL - signal-specific default action
- The default actions for the signals defined in this descrip-
tion are specified in <signal.h>.
Page 5 Reliant UNIX 5.44 Printed 11/98
sigaction(2) sigaction(2)
- 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 SANOCLDSTOP flag. While
a process is stopped, any additional signals that are sent to
the process will not be delivered until the process is contin-
ued, except SIGKILL which always terminates the receiving pro-
cess. 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 SIGDFL for a signal that is pend-
ing, and whose default action is to ignore the signal (for
example, SIGCHLD), will cause the pending signal to be dis-
carded, whether or not it is blocked.
SIGIGN - ignore signal
- Delivery of the signal will have no effect on the process. The
behavior of a process is undefined after it ignores a SIGFPE,
SIGILL or SIGSEGV signal that was not generated by kill() or
raise().
- The system will not allow the action for the signals SIGKILL
or SIGSTOP to be set to SIGIGN.
- Setting a signal action to SIGIGN for a signal that is pend-
ing will cause the pending signal to be discarded, whether or
not it is blocked.
- If a process sets the action for the SIGCHLD signal to
SIGIGN, the behavior is unspecified, except as specified
below.
If the action for the SIGCHLD signal is set to SIGIGN, child
processes of the calling processes will not be transformed
into zombie processes when they terminate. If the calling pro-
cess 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.
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.
Page 6 Reliant UNIX 5.44 Printed 11/98
sigaction(2) sigaction(2)
- If SASIGINFO 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 SASIGINFO is set, the signal-catching function will be
entered as:
void func(int signo, siginfot *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 siginfot associated with the sig-
nal being delivered, and ucontextptr points to a ucontextt.
- The behavior of a process is undefined after it returns nor-
mally 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 SIGCHLD
signal is generated to indicate that child process.
- When signal-catching functions are invoked asynchronously with
process execution, the behavior of some of the functions
defined is unspecified if they are called from a signal-catch-
ing function.
The following table defines a set of functions that are either
reentrant or not interruptible by signals. Therefore applica-
tions may invoke them, without restriction, from signal-catch-
ing functions:
access() getegid() rmdir() tcdrain()
alarm() geteuid() setgid() tcflow()
cfgetispeed() getgid() setpgid() tcflush()
cfgetospeed() getgroups() setsid() tcgetattr()
cfsetispeed() getpgrp() setuid() tcgetpgrp()
cfsetospeed() getpid() sigaction() tcsendbreak()
chdir() getppid() sigaddset() tcsetattr()
chmod() getuid() sigdelset() tcsetpgrp()
Page 7 Reliant UNIX 5.44 Printed 11/98
sigaction(2) sigaction(2)
chown() kill() sigemptyset() time()
close() link() sigfillset() times()
creat() lseek() sigismember() umask()
dup() mkdir() signal() uname()
dup2() mkfifo() sigpause() unlink()
execle() open() sigpending() utime()
execve() pathconf() sigprocmask() wait()
exit() pause() sigset() waitpid()
fcntl() pipe() sigsuspend() write()
fork() raise() sleep()
fpathconf() read() stat()
fstat() rename() sysconf()
All functions not in the above table are considered to be
unsafe with respect to signals. In the presence of signals,
all functions 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 by this
description 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-catch-
ing 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 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.
RETURN VALUE
Upon successful completion, sigaction() returns 0. Otherwise -1 is
returned, errno is set to indicate the error and no new signal-catch-
ing function will be installed.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
Page 8 Reliant UNIX 5.44 Printed 11/98
sigaction(2) sigaction(2)
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.
The sigaction() function may fail if:
EINVAL An attempt was made to set the action to SIGDFL for a sig-
nal that cannot be caught or ignored (or both).
APPLICATION USAGE
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
behavior of reentrant functions, as defined in the description, is as
specified by this description, 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 interac-
tions 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 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 description 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 glo-
bal variable errno; the signal-catching function may want to save and
restore its value. Naturally, the same principles apply to the reen-
trancy 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 func-
tions 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, it is not defined the
behavior when any unsafe function is called in a signal handler that
interrupts an unsafe function.
Page 9 Reliant UNIX 5.44 Printed 11/98
sigaction(2) sigaction(2)
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 sigatomict. Furthermore, if such
a call fails, the value of errno 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
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 SASIGINFO is set as a void * instead of a ucontextt *, but
without requiring type checking. New applications should explicitly
cast the third argument of the signal handling function to
ucontextt *.
The BSD optional four argument signal handling function is not sup-
ported 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 cer-
tain signals, scp is a pointer to the sigcontext structure, and addr
is additional address information. Much the same information is avail-
able in the objects pointed to by the second argument of the signal
handler specified when SASIGINFO is set.
SEE ALSO
kill(1), exit(2), introprm2(2), kill(2), pause(2), sigaltstack(2),
signal(2), sigprocmask(2), sigsend(2), sigsuspend(2), wait(2),
waitid(2), waitpid(2), wait3(3), raise(3C), setjmp(3C-ucb),
sigsetops(3C), siginfo(5), signal(5), ucontext(5).
Manual "C-Compiler", chapter "The cc/c89 command".
Page 10 Reliant UNIX 5.44 Printed 11/98