NAME

sigaction − examine and change signal action

SYNOPSIS

#include <signal.h>

int sigaction (

int sig,
const struct sigaction *act,
struct sigaction *oact

);

DESCRIPTION

sigaction() allows the calling process to examine and specify the action to be taken on delivery of a specific signal.  The argument sig specifies the signal; acceptable values are defined in <signal.h>.  More details on the semantics of specific signals can be found in the signal(5) manual entry.

The sigaction structure and type sigset_t are defined in <signal.h>. 

act and oact are pointers to sigaction structures that include the following elements:

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

Unless it is a null pointer, the argument act points to a structure specifying the action to be taken when delivering 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 oact.  If the argument act is a null pointer, signal handling is unchanged; thus sigaction() can be used to inquire about the current handling of a given signal. 

The sa_handler member of the sigaction structure is assigned one of three values: SIG_DFL, SIG_IGN, or a function address. The actions prescribed by these values are as follows:

SIG_DFL Execute default action for signal. 
Upon receipt of the signal sig, the default action (specified on signal(5)) is performed. The default action for most signals is to terminate the process.

A pending signal is discarded (whether or not it is blocked) if sigaction() is set to SIG_DFL for a pending signal whose default action is to ignore the signal (as in the case of SIGCHLD). 

SIG_IGN Ignore the signal. 
Setting a signal action to SIG_IGN causes a pending signal to be discarded, whether or not it is blocked. 

The SIGKILL and SIGSTOP signals cannot be ignored. 

function address Catch the signal. 
Upon receipt of the signal sig, the receiving process executes the signal-catching function pointed to by sa_handler. The signal-catching function is entered as a C-language function call. Details on the arguments passed to this function can be found in the signal(5) manual entry.

The signals SIGKILL and SIGSTOP cannot be caught. 

When a signal is caught by a signal-catching function installed by sigaction, a new mask is calculated and installed for the duration of the signal-catching function, or until a call is made to sigprocmask() or sigsuspend() (see sigprocmask(2) and sigsuspend(2)). This mask is formed by taking the union of the current signal mask, the signal to be delivered, and unless the SA_RESETHAND flag is set (see below), the signal mask specified in the sa_mask field of the sigaction structure associated with the signal being delivered.  If and when the signal-catching function 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, or until one of the exec(2) functions is called.

If the previous action for sig was established by signal(2), the values of the fields returned in the structure pointed to by oact are unspecified; 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 is reinstated as if the original call to signal() were repeated. 

The set of signals specified by the sa_mask field of the sigaction structure pointed to by the act argument cannot block the SIGKILL or SIGSTOP signal.  This is enforced by the system without causing an error to be indicated. 

The sa_flags field in the sigaction structure can be used to modify the behavior of the specified signal.  The following flag bits, defined in the <signal.h> header, can be set in sa_flags:

SA_NOCLDSTOP Do not generate SIGCHLD when untraced children stop (see ptrace(2)).

SA_ONSTACK Use the space reserved by sigspace() for signal processing. 

SA_RESETHAND Use the semantics of signal().  The signal mask specified by the sa_mask field is not used when setting up the effective signal mask for the signal handler.  If the signal is not one of those marked "not reset when caught" (see signal(5)), the default action for the signal is reinstated when the signal is caught, prior to entering the signal-catching function. The "not reset when caught" distinction is insignificant when sigaction() is called and SA_RESETHAND is not set. 

RETURN VALUE

Upon successful completion, sigaction() returns 0; otherwise it returns −1 and sets errno to indicate the error. 

ERRORS

sigaction() fails and no new signal-catching function is installed if any of the following conditions is encountered:

[EINVAL] The value of the sig argument is not a valid signal number, or an attempt is made to supply an action other than SIG_DFL for the SIGKILL or SIGSTOP signal. 

[EFAULT] act or oact points to an invalid address.  The reliable detection of this error is implementation dependent. 

AUTHOR

sigaction() was derived from the IEEE POSIX 1003.1-1988 Standard. 

SEE ALSO

ptrace(2), sigprocmask(2), sigpending(2), sigspace(2), sigsuspend(2), sigsetops(3C), signal(5). 

STANDARDS CONFORMANCE

sigaction(): AES, XPG3, XPG4, FIPS 151-2, POSIX.1

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992