SIGACTION(3V)

NAME
sigaction - examine and change signal action

SYNOPSIS

#include <signal.h>

int sigaction(sig, act, oact)
int sig;
struct sigaction *act, *oact;

DESCRIPTION

sigaction() allows the calling process to examine and specify (or both) the action to be associated with a specific signal. 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> as follows:

    struct sigaction {
    	void (*sa_handler)();	/*
    					 * SIG_DFL, SIG_IGN,
    					 * or pointer to a function
    					 */
    	sigset_t sa_mask;	/*
    					 * Additional signals to be
    					 * blocked during execution of
    					 * signal-catching function
    					 */
    	int sa_flags;		/*
    					 * Special flags to affect
    					 * behavior of signal
    					 */
    };

If act is not NULL, it points to a structure specifying the action to be associated with the specified signal. If oact is not NULL, the action previously associated with the signal is stored in the location pointed to by the oact. If act is NULL, signal handling is unchanged by this function. 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, the sa_mask field identifies a set of signals that shall be added to the process's signal mask before the signal-catching function mask is invoked. 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.

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

    #define	SA_ONSTACK	0x0001	/*
    							 * take signal on
    							 * signal stack
    							 */
    #define	SA_INTERRUPT	0x0002	/*
    							 * do not restart
    							 * system on signal
    							 * return
    							 */
    #define	SA_RESETHAND	0x0004	/*
    							 * reset handler to
    							 * SIG_DFL when
    							 * signal taken
    							 */
    #define	SA_NOCLDSTOP	0x0008	/* don't send
    							 * SIGCHLD on child
    							 * stop
    							 */

If sig is SIGCHILD and the SA_NOCLDSTOP flag is not set in sa_flags, and the implementation supports the SIGCHILD signal, a SIGCHILD signal shall be generated for the calling process whenever any of its child processes stop. If sig is SIGCHILD and the SA_NOCLDSTOP flag is set in sa_flags, the implementation shall not generate a SIGCHILD signal in this way.

If the SA_ONSTACK bit is set in the flags for that signal, the system will deliver the signal to the process on the signal stack specified with sigstack(2), rather than delivering the signal on the current stack.

If a caught signal occurs during certain system calls, the call is restarted by default. The call can be forced to terminate prematurely with an EINTR error return by setting the SA_INTERRUPT bit in the flags for that signal. SA_INTERRUPT is not available in 4.2BSD, hence it should not be used if backward compatibility is needed. The affected system calls are read(2V) or write(2V) on a slow device (such as a terminal or pipe or other socket, but not a file) and during a wait(2V).

Once a signal handler is installed, it remains installed until another sigvec() call is made, or an execve(2V) is performed, unless the SA_RESETHAND bit is set in the flags for that signal. In that case, the value of the handler for the caught signal is set to SIG_DFL before entering the signal-catching function, unless the signal is SIGILL or SIGTRAP. Also, if this bit is set, the bit for that signal in the signal mask will not be set; unless the signal mask associated with that signal blocks that signal, further occurrences of that signal will not be blocked. The SA_RESETHAND flag is not available in 4.2BSD, hence it should not be used if backward compatibility is needed.

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()). 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, 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() ), or until one of the exec functions is called.

If the previous action for sig had been established by signal() defined in the C standard, the values of the fields returned in the structure pointed to by the oact are unspecified, and in particular oact->sv_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() using act, handling of the signal shall be as if the original call to signal() were repeated.

If sigaction() fails, no new signal handler is installed.

RETURN VALUES

sigaction() returns:

0   on success.

-1  on failure and sets errno to indicate the error.

ERRORS

EINVAL
    sig is an invalid or unsupported signal number.

    An attempt was made to catch a signal that cannot be ignored. See <signal.h>.

SEE ALSO
kill(2V), sigpause(2V), sigprocmask(2V), signal(3V), sigsetops(3V)