Friedrich-Alexander-Universität Erlangen-Nürnberg  /   Technische Fakultät  /   Department Informatik

 

Files

file  signal.h
 

Data Structures

struct  sigaction
 

Functions

int kill (pid_t pid, int sig)
 Send signal to a process. More...
 
int sigemptyset (sigset_t *set)
 Empty signal set. More...
 
int sigfillset (sigset_t *set)
 Fill signal set. More...
 
int sigaddset (sigset_t *set, int signum)
 Add signal to set. More...
 
int sigdelset (sigset_t *set, int signum)
 Remove signal from set. More...
 
int sigismember (const sigset_t *set, int signum)
 Test signal's membership. More...
 
int sigprocmask (int how, const sigset_t *set, sigset_t *oset)
 Change signal mask of a process. More...
 
int sigaction (int sig, const struct sigaction *act, struct sigaction *oact)
 Set action for a signal. More...
 
int sigsuspend (const sigset_t *mask)
 Wait for a signal. More...
 

Detailed Description

This set of functions and system calls control the signal handling of processes in Linux. A signal asynchronously interrupts the execution of a process and has great similarities with interrupts as known from the microcontroller programming. This includes the arising problems of asymmetric program interruption, for example, lost wake-up and synchronization problems.

A complete list of all signals and further information can be found at man 7 signal. The action values mean, that the default action is either to terminate the process (Term), to terminate the process and generate a core dump (Core) or to ignore a signal (Ign). An excerpt of the available signals is shown here:

Signal Default Action Description
SIGINT Term interrupt from keyboard (Ctrl-C)
SIGQUIT Core quit from keyboard
SIGKILL Term kill signal (non blockable)
SIGSEGV Core invalid memory reference
SIGALRM Term timer signal
SIGTERM Term termination signal
SIGUSR1 Term user-defined signal 1
SIGUSR2 Term user-defined signal 2
SIGCLD/SIGCHLD Ign child stopped/terminated

The following examples show some typical use cases for the presented functions.

Install a new action for SIGINT

static void sigint_handler(int signum) { ... }
int main(int argc, char *argv[]) {
struct sigaction act, oldact;
// signal mask during handling of a signal
// (handled signal itself is automatically blocked)
sigemptyset(&act.sa_mask);
// set signal handler (also possible: SIG_DFL (default action)
// and SIG_IGN (ignoring))
act.sa_handler = sigint_handler;
// set flags
act.sa_flags = SA_RESTART;
if (sigaction(SIGINT, &act, &oldact) == -1) {
perror("sigaction");
exit(EXIT_FAILURE);
}
[...]

Block and unblock a signal:

sigset_t set, oldset;
// initialize set (first empty set, then add SIGINT)
sigaddset(&set, SIGINT);
// block SIGINT and get previous signal mask
if (sigprocmask(SIG_BLOCK, &set, &oldset) == -1) {
perror("sigprocmask");
exit(EXIT_FAILURE);
}
// SIGINT is blocked
[...]
// unblock SIGINT
if (sigprocmask(SIG_UNBLOCK, &set, NULL) == -1) {
perror("sigprocmask");
exit(EXIT_FAILURE);
}

Only allow one signal

sigset_t set, oldset;
// initialize set (first add all signals, then remove SIGINT)
sigfillset(&set);
sigdelset(&set, SIGINT);
// install new signal mask and get previously installed signal mask
if (sigprocmask(SIG_SETMASK, &set, &oldset) == -1) {
perror("sigprocmask");
exit(EXIT_FAILURE);
}
// all signals are blocked except for SIGINT
[...]

Data Structure Documentation

◆ sigaction

struct sigaction

Data Fields

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

Field Documentation

◆ sa_handler

void(* sa_handler) (int)

Pointer to the function, which will be installed for the associated signal. The installed function must have one parameter, where the incoming signal is encoded, and no return value. Instead of a pointer to a handler function the two special values SIG_IGN (ignore occurences of this signal) or SIG_DFL (restore the default action for this signal) can be used.

◆ sa_mask

sigset_t sa_mask

Specifies a signal mask with signals, which are blocked during the handling of the associated signal. The signal itself will be implicitly added to the signal mask (except SA_NODEFER is used in sa_flags). Usually, an empty signal mask can be used.

◆ sa_flags

int sa_flags

Specifies further options for the signal handling process. It is formed by a bitwise OR of zero or more options. Usually, it is set to SA_RESTART.

Function Documentation

◆ kill()

int kill ( pid_t  pid,
int  sig 
)

The kill() system call can be used to send the signal specified in sig to the process specified in pid. The kill() function can also be used to send the signal to multiple processes, see man 2 kill for more details.

Parameters
pidpid of the receiving process
sigsignal to be sent
Return values
0on success
-1on error, errno is set

◆ sigemptyset()

int sigemptyset ( sigset_t *  set)

The sigemptyset() function empties a given signal set.

We do not expect error handling when setting signal masks.

Parameters
setpointer to the signal set

◆ sigfillset()

int sigfillset ( sigset_t *  set)

The sigfillset() function fills a signal set, that is, all signals are included.

We do not expect error handling when setting signal masks.

Parameters
setpointer to the signal set

◆ sigaddset()

int sigaddset ( sigset_t *  set,
int  signum 
)

The sigaddset() function adds the signal signum to the signal set in set.

We do not expect error handling when setting signal masks.

Parameters
setpointer to the signal set
signumsignal to be added

◆ sigdelset()

int sigdelset ( sigset_t *  set,
int  signum 
)

The sigdelset() function removes the signal signum from the signal set set.

We do not expect error handling when setting signal masks.

Parameters
setpointer to the signal set
signumsignal to be removed

◆ sigismember()

int sigismember ( const sigset_t *  set,
int  signum 
)

The sigismember() function determines whether the signal signum is a member of the signal set set.

Parameters
setpointer to the signal set
signumsignal to be tested
Return values
1signal is a member
0signal is not a member

◆ sigprocmask()

int sigprocmask ( int  how,
const sigset_t *  set,
sigset_t *  oset 
)

The sigprocmask() function is used to manipulate or get the currently installed signal mask. The signal mask is the set of signals that are currently blocked.

The new installed signal mask is specified in the struct pointed to by act (act can be NULL if no new signal mask should be installed). If oact is not NULL the previously installed signal mask is saved.

Instead of setting a new signal mask, the current set can be manipulated by adding or removing the signals specified in act depending on the value of how. The possible values for how are:

Value Description
SIG_BLOCK add signals in set to the set of currently blocked signals
SIG_UNBLOCK remove signals in set from the set of currently blocked signals
SIG_SETMASK set the set of currently block signals to the signals in set
Parameters
howdetermines how the signal mask is changed
setpointer to the signal set
osetcopy of previous signal set
Return values
0on success
-1on error, errno is set

◆ sigaction()

int sigaction ( int  sig,
const struct sigaction act,
struct sigaction oact 
)

The sigaction() function is used to change the action taken by a process, when receiving a specific signal. For each signal a default action is specified, which can be overwritten by sigaction() (except for SIGKILL and SIGSTOP).

The new installed action for the signal sig is specified in the struct pointed to by act (act can be NULL if no new action should be installed). If oact is not NULL the previous action is saved. For further information about the content of act and oact see the documentation of struct sigaction.

Parameters
sigsignal to change action for
actaction to take
oactcopy of previous action
Return values
0on success
-1on error, errno is set

◆ sigsuspend()

int sigsuspend ( const sigset_t *  mask)

The sigsuspend() function temporarily replaces the signal mask of the process with mask and then suspends the execution of the process until it receives a signal in an atomic way.

If the signal terminates the process, this function does not return. If the signal is caught, this function returns after the execution of the signal handler and the old signal mask is restored.

The return value of sigsuspend() is always -1 and can be ignored.

Parameters
masktemporary signal mask