sigaction

Specifies the action to take upon delivery of a signal.

Format

#include  <signal.h>

int sigaction  (int sig, const struct sigaction
               *action, struct sigaction
               *o_action);

Arguments

sig: The signal for which the action is to be taken.
action: A pointer to a sigaction structure that describes the action to take when you receive the signal specified by the sig argument.
o_action: A pointer to a sigaction structure. When the sigaction function returns from a call, the action previously attached to the specified signal is stored in this structure.

Description

When a process requests the sigaction function, the process can both examine and specify what action to perform when the specified signal is delivered. The arguments determine the behavior of the sigaction function as follows:

Specifying the sig argument identifies the affected signal. Use any one of the signal values defined in the <signal.h> header file, except SIGKILL.
If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags, then a SIGCHLD signal is 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 SIGCHLD signal is not generated in this way.
Specifying the action argument, if not null, points to a sigaction structure that defines what action to perform when the signal is received. If the action argument is null, signal handling remains unchanged, so you can use the call to inquire about the current handling of the signal.
Specifying the o_action argument, if not null, points to a sigaction structure that contains the action previously attached to the specified signal.

The sigaction structure consists of the following members:

  void        (*sa_handler)(int);
  sigset_t    sa_mask;
  int         sa_flags;

The sigaction structure members are defined as follows:

sa_handler This member can contain the following values:

SIG_DFL - Specifies the default action taken when the signal is delivered.
SIG_IGN - Specifies that the signal has no effect on the receiving process.
Function pointer - Requests to catch the signal. The signal causes the function call.

sa_mask This member can request that individual signals, in addition to those in the process signal mask, are blocked from delivery while the signal handler function specified by the sa_handler member is executing.

sa_flags This member can set the flags to enable further control over the actions taken when a signal is delivered.

The sa_flags member of the sigaction structure has the following values:

SA_ONSTACK Setting this bit causes the system to run the signal catching function on the signal stack specified by the sigstack function. If this bit is not set, the function runs on the stack of the process where the signal is delivered.

SA_RESETHAND Setting this bit resets the signal to SIG_DFL. Be aware that you cannot automatically reset SIGILL and SIGTRAP.

SA_NODEFER Setting this bit does not automatically block the signal as it is caught.

SA_NOCLDSTOP If this bit is set and the sig argument is equal to SIGCHLD and a child process of the calling process stops, then a SIGCHLD signal is sent to the calling process only if SA_NOCLDSTOP is not set for SIGCHLD.

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.

If the previous action for a specified signal had been established by signal, the values of the fields returned in the structure pointed to by the o_action argument of sigaction are unspecified, and in particular o_action->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 by means of the action argument of sigaction), the signal is handled 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.

See Section 4.2 for more information on signal handling.

Note: The sigvec and signal functions are provided for compatibility to old UNIX systems; their function is a subset of that available with the sigaction function.

See also sigstack, sigvec, signal, wait, read, and write, in this section.

Return Values

0 Indicates success.

-1 Indicates an error; A new signal handler is not installed. errno is set to one of the following values:

EFAULT - The action or o_action argument points to a location outside of the allocated address space of the process.
EINVAL - The sig argument is not a valid signal number. Or an attempt was made to ignore or supply a handler for the SIGKILL, SIGSTOP, and SIGCONT signals.

Previous Page | Next Page | Table of Contents | Index

sa_handler	This member can contain the following values: SIG_DFL - Specifies the default action taken when the signal is delivered. SIG_IGN - Specifies that the signal has no effect on the receiving process. Function pointer - Requests to catch the signal. The signal causes the function call.
sa_mask	This member can request that individual signals, in addition to those in the process signal mask, are blocked from delivery while the signal handler function specified by the sa_handler member is executing.
sa_flags	This member can set the flags to enable further control over the actions taken when a signal is delivered.

SA_ONSTACK	Setting this bit causes the system to run the signal catching function on the signal stack specified by the sigstack function. If this bit is not set, the function runs on the stack of the process where the signal is delivered.
SA_RESETHAND	Setting this bit resets the signal to SIG_DFL. Be aware that you cannot automatically reset SIGILL and SIGTRAP.
SA_NODEFER	Setting this bit does not automatically block the signal as it is caught.
SA_NOCLDSTOP	If this bit is set and the sig argument is equal to SIGCHLD and a child process of the calling process stops, then a SIGCHLD signal is sent to the calling process only if SA_NOCLDSTOP is not set for SIGCHLD.

0	Indicates success.
-1	Indicates an error; A new signal handler is not installed. errno is set to one of the following values: EFAULT - The action or o_action argument points to a location outside of the allocated address space of the process. EINVAL - The sig argument is not a valid signal number. Or an attempt was made to ignore or supply a handler for the SIGKILL, SIGSTOP, and SIGCONT signals.