Originální popis anglicky:
sigaction - examine and change a signal action
Návod, kniha: POSIX Programmer's Manual
#include <signal.h>
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
<signal.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
signal-catching function. |
| int |
sa_flags |
Special flags to affect behavior of signal. |
| void(*) (int, |
|
|
| siginfo_t *, void *) |
sa_sigaction |
Pointer to a signal-catching 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 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_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 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:
- SA_NOCLDSTOP
- 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.
- 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
function shall be entered as:
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 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 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 contents 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
sigaction() 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 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
occurrences 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 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
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 installed.
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 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.
None.
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 behavior of reentrant functions, as defined in the DESCRIPTION, 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. 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
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 (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 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.
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
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 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 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
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,
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.
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
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 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 cannot 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
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.
None.
Signal Concepts ,
bsd_signal() ,
kill() ,
_longjmp()
,
longjmp() ,
raise() ,
semget() ,
sem_init() ,
sem_open() ,
sigaddset() ,
sigaltstack() ,
sigdelset() ,
sigemptyset() ,
sigfillset() ,
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 original
Standard can be obtained online at http://www.opengroup.org/unix/online.html
.
