[Go to CFHT Home Page] Man Pages
Back to Software Index  BORDER=0Manpage Top Level
    sigsuspend(2) manual page Table of Contents

Name

sigsuspend - install a signal mask and suspend caller until signal

Synopsis

#include <signal.h>

int sigsuspend(const sigset_t *set);

MT-Level

Async-Signal-Safe

Description

sigsuspend() replaces the caller’s signal mask with the set of signals pointed to by the argument set and then suspends the caller until delivery of a signal whose action is either to execute a signal catching function or to terminate the process.

If the action is to terminate the process, sigsuspend() does not return. If the action is to execute a signal catching function, sigsuspend() returns after the signal catching function returns. On return, the signal mask is restored to the set that existed before the call to sigsuspend(). For the precise semantics of signal mask restoration in a multithreaded process, see NOTES.

It is not possible to block those signals that cannot be ignored (see signal(5) ); this restriction is silently imposed by the system.

Return Values

Since sigsuspend() suspends process execution indefinitely, there is no successful completion return value. On failure, it returns -1 and sets errno to indicate the error.

Errors

sigsuspend() fails if either of the following is true:

EFAULT
set points to an illegal address.
EINTR
A signal is caught by the calling process and control is returned from the signal catching function.

See Also

sigaction(2) , sigprocmask(2) , signal(3C) , sigsetops(3C) , signal(5)

Notes

In a multi-threaded program, the preferred interface which performs a similar function, sigwait(2) , should be used instead of sigsuspend(). However, if sigsuspend() is used in a multi-threaded program, its semantics of signal mask restoration are slightly different from those for a single-threaded process; these are captured in one sentence:

On return from the signal catching function, the signal mask is restored to the set that existed before the call to sigsuspend().

This has two implications:

    .
  1. If a thread specifies two signals in the mask to sigsuspend(), both signals could interrupt its call to sigsuspend() simultaneously. In the traditional program which does not use threads, the call to sigsuspend() with two signals in the mask, always returns with only one signal delivered. The other signal stays pending if masked earlier, unlike the MT case.
    2. .
  2. While a thread is executing the signal handler which interrupted its call to sigsuspend(), its signal mask is the one passed to sigsuspend(). It does not get restored to the previous mask until it returns from all the signal handlers which interrupted sigsuspend(2) .

Table of Contents