C Programming/C Reference/signal.h

signal.h is a header file defined in the C Standard Library to specify how a program handles signals while it executes. A signal can report some exceptional behavior within the program (such as division by zero), or a signal can report some asynchronous event outside the program (such as someone striking an interactive attention key on a keyboard).

A signal can be generated by calling raise (to send a signal to the current process) or kill (to send a signal to any process). Each implementation defines what signals it generates (if any) and under what circumstances it generates them. An implementation can define signals other than the ones listed here. The standard header <signal.h> can define additional macros with names beginning with SIG to specify the values of additional signals. All such values are integer constant expressions >= 0.

A signal handler can be specified for all but two signals (SIGKILL and SIGSTOP cannot be caught, blocked or ignored). A signal handler is a function that the target environment calls when the corresponding signal occurs. The target environment suspends execution of the program until the signal handler returns or calls longjmp. For maximum portability, an asynchronous signal handler should only:

• make calls (that succeed) to the function signal
• assign values to objects of type volatile sig_atomic_t
• return control to its caller

If the signal reports an error within the program (and the signal is not asynchronous), the signal handler can terminate by calling abort, exit, or longjmp.

Member functions

• int raise(int sig). This raises a signal artificially. It causes signal sig to be generated. The sig argument is compatible with the SIG macros.If the call is successful, zero is returned. Otherwise a nonzero value is returned.

Example:

#include <signal.h>
#include <stdio.h>
#include <stdlib.h>

static void catch_function(int signal) {
    puts("Interactive attention signal caught.");
}

int main(void) {
    if (signal(SIGINT, catch_function) == SIG_ERR) {
        fputs("An error occurred while setting a signal handler.\n", stderr);
        return EXIT_FAILURE;
    }
    puts("Raising the interactive attention signal.");
    if (raise(SIGINT) != 0) {
        fputs("Error raising the signal.\n", stderr);
        return EXIT_FAILURE;
    }
    puts("Exiting.");
    return 0;
}

• psignal(int sig, const char *s), outputs to stderr a string representation of a signal number. It is in 4.3BSD, Solaris and Linux, but is not specified by POSIX or SUS.

On the same systems, string.h contains the non-standard strsignal(int sig) which operates analogously to strerror.

• void (* signal(int sig, void (*func)(int)) )(int), sets the action taken when the program receives the signal sig. 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 points to a signal handler function to be called when the signal occurs.

The function func may terminate by executing a return statement or by calling the abort, exit or longjmp functions. If func executes a return statement, and the value of sig was SIGFPE or any other implementation-defined value corresponding to a computational exception, the behavior is undefined. Otherwise, the program will resume execution at the point it was interrupted. If the function returns and the return request can be honored, the signal function returns the value of func for the most recent call to signal for the specified signal sig. Otherwise a value of SIG_ERR is returned and a positive value is stored in errno.

If the signal occurs other than as the result of calling the abort or raise function, the behavior is undefined if the signal handler calls any function in the standard library other than the signal function itself (with a first argument of the signal number corresponding to the signal that cause the invocation of the handler) or refers to any object with status storage duration other than by assigning to a static storage duration variable of type volatile sig_atomic_t. Furthermore, if such a call to the signal function results in a SIG_ERR return, the value of errno is indeterminate.^[1]

Member types

typedef i-type sig_atomic_t

Member macros

• SIG_DFL - Used to set default signal handling.
• SIG_IGN - Used to handle a signal by ignoring it.
• SIG_ERR - A number used for errors.

Member constants

References

External links

• Dinkumware's manual on signal.h
• XGC's manual for signal.h