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;
  
    sigaction(SIGINT, &act, &oldact);
  
    [...]

Block and unblock a signal:

sigset_t set, oldset;
  
// initialize set (first empty set, then add SIGINT)
sigemptyset(&set);
sigaddset(&set, SIGINT);
  
// block SIGINT and get previous signal mask
sigprocmask(SIG_BLOCK, &set, &oldset);
  
// SIGINT is blocked
[...]
  
// unblock SIGINT
sigprocmask(SIG_UNBLOCK, &set, NULL);

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
sigprocmask(SIG_SETMASK, &set, &oldset);
  
// all signals are blocked except for SIGINT
[...]

Data Structure Documentation

struct sigaction

Data Fields
void(*	sa_handler )(int)

sigset_t	sa_mask

int	sa_flags

Field Documentation

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.

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.

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

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

pid	pid of the receiving process
sig	signal to be sent

Return values

0	on success
-1	on error, `errno` is set

int sigemptyset ( sigset_t * set )

The sigemptyset() function empties a given signal set.

We do not expect error handling when setting signal masks.

Parameters

set	pointer to the signal set

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

set	pointer to the signal set

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

set	pointer to the signal set
signum	signal to be added

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

set	pointer to the signal set
signum	signal to be removed

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

set	pointer to the signal set
signum	signal to be tested

Return values

1	signal is a member
0	signal is not a member

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`

We do not expect error handling when manipulating signal masks.

Parameters

how	determines how the signal mask is changed
set	pointer to the signal set
oset	copy of previous signal set

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.

We do not expect error handling when installing signal handlers.

Parameters

sig	signal to change action for
act	action to take
oact	copy of previous action

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

mask	temporary signal mask

Linux libc-doc

Files

Data Structures

Functions

Detailed Description

Data Structure Documentation

Data Fields

Field Documentation

Function Documentation