NAME

signal, sigset, sighold, sigrelse, sigignore, sigpause - signal management

 SYNOPSIS

#include <signal.h>

void (*signal(int sig, void (*func)(int)))(int);
int sighold(int sig);
int sigignore(int sig);
int sigpause(int sig);
int sigrelse(int sig);
void (*sigset(int sig, void (*disp)(int)))(int);

 DESCRIPTION

Use of any of these functions is unspecified in a multi-threaded process.

The signal() function chooses one of three ways in which receipt of the signal number sig is to be subsequently handled. If the value of func is SIG_DFL, default handling for that signal will occur. If the value of func is SIG_IGN, the signal will be ignored. Otherwise, func must point to a function to be called when that signal occurs. Such a function is called a signal handler.

When a signal occurs, if func points to a function, first the equivalent of a:

signal(sig, SIG_DFL);

is executed or an implementation-dependent blocking of the signal is performed. (If the value of sig is SIGILL, whether the reset to SIG_DFL occurs is implementation-dependent.) Next the equivalent of:

(*func)(sig);

is executed. The func function may terminate by executing a return statement or by calling abort(), exit(), or longjmp(). If func executes a return statement and the value of sig was SIGFPE or any other implementation-dependent value corresponding to a computational exception, the behaviour is undefined. Otherwise, the program will resume execution at the point it was interrupted.

If the signal occurs other than as the result of calling abort(), kill() or raise(), the behaviour is undefined if the signal handler calls any function in the standard library other than one of the functions listed on the sigaction() page 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 indeterminate.

At program startup, the equivalent of:

signal(sig, SIG_IGN);

is executed for some signals, and the equivalent of:

signal(sig, SIG_DFL);

is executed for all other signals (see exec).

The sigset(), sighold(), sigignore(), sigpause() and sigrelse() functions provide simplified signal management.

The sigset() function is used to modify signal dispositions. The sig argument specifies the signal, which may be any signal except SIGKILL and SIGSTOP. The disp argument specifies the signal's disposition, which may be SIG_DFL, SIG_IGN or the address of a signal handler. If sigset() is used, and disp is the address of a signal handler, the system will add sig to the calling process' signal mask before executing the signal handler; when the signal handler returns, the system will restore the calling process' signal mask to its state prior the delivery of the signal. In addition, if sigset() is used, and disp is equal to SIG_HOLD, sig will be added to the calling process' signal mask and sig's disposition will remain unchanged. If sigset() is used, and disp is not equal to SIG_HOLD, sig will be removed from the calling process' signal mask.

The sighold() function adds sig to the calling process' signal mask.

The sigrelse() function removes sig from the calling process' signal mask.

The sigignore() function sets the disposition of sig to SIG_IGN.

The sigpause() function removes sig from the calling process' signal mask and suspends the calling process until a signal is received. The sigpause() function restores the process' signal mask to its original state before returning.

If the action for the SIGCHLD signal is set to SIG_IGN, 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 zombie processes, it will block until all of its children terminate, and wait(), wait3(), waitid() and waitpid() will fail and set errno to [ECHILD].

 RETURN VALUE

If the request can be honoured, signal() returns the value of func for the most recent call to signal() for the specified signal sig. Otherwise, SIG_ERR is returned and a positive value is stored in errno.

Upon successful completion, sigset() returns SIG_HOLD if the signal had been blocked and the signal's previous disposition if it had not been blocked. Otherwise, SIG_ERR is returned and errno is set to indicate the error.

The sigpause() function suspends execution of the thread until a signal is received, whereupon it returns -1 and sets errno to [EINTR].

For all other functions, upon successful completion, 0 is returned. Otherwise, -1 is returned and errno is set to indicate the error.

 ERRORS

The signal() 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 signal() 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 sigset(), sighold(), sigrelse(), sigignore() and sigpause() functions will fail if:

[EINVAL]

The sig argument is an illegal signal number.

The sigset(), and sigignore() functions will fail if:

[EINVAL]

An attempt is made to catch a signal that cannot be caught, or to ignore a signal that cannot be ignored.

 EXAMPLES

None.

 APPLICATION USAGE

The sigaction() function provides a more comprehensive and reliable mechanism for controlling signals; new applications should use sigaction() rather than signal().

The sighold() function, in conjunction with sigrelse() or sigpause(), may be used to establish critical regions of code that require the delivery of a signal to be temporarily deferred.

The sigsuspend() function should be used in preference to sigpause() for broader portability.

 FUTURE DIRECTIONS

None.

 SEE ALSO

exec, pause(), sigaction(), sigsuspend(), waitid(), <signal.h>.

DERIVATION

Derived from Issue 1 of the SVID.