sigsuspend(2)

1sigsuspend(2)                 System Calls Manual                sigsuspend(2)
2
3
4

NAME

6       sigsuspend, rt_sigsuspend - wait for a signal
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <signal.h>
13
14       int sigsuspend(const sigset_t *mask);
15
16   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
17
18       sigsuspend():
19           _POSIX_C_SOURCE
20

DESCRIPTION

22       sigsuspend() temporarily replaces the signal mask of the calling thread
23       with the mask given by mask and then suspends the thread until delivery
24       of  a signal whose action is to invoke a signal handler or to terminate
25       a process.
26
27       If the signal terminates the process, then sigsuspend()  does  not  re‐
28       turn.   If  the  signal  is caught, then sigsuspend() returns after the
29       signal handler returns, and the signal mask is restored  to  the  state
30       before the call to sigsuspend().
31
32       It  is  not possible to block SIGKILL or SIGSTOP; specifying these sig‐
33       nals in mask, has no effect on the thread's signal mask.
34

RETURN VALUE

36       sigsuspend() always returns -1, with errno set to  indicate  the  error
37       (normally, EINTR).
38

ERRORS

40       EFAULT mask  points  to memory which is not a valid part of the process
41              address space.
42
43       EINTR  The call was interrupted by a signal; signal(7).
44

STANDARDS

46       POSIX.1-2008.
47

HISTORY

49       POSIX.1-2001.
50
51   C library/kernel differences
52       The original Linux system call was named sigsuspend().   However,  with
53       the  addition of real-time signals in Linux 2.2, the fixed-size, 32-bit
54       sigset_t type supported by that system call was no longer fit for  pur‐
55       pose.   Consequently,  a new system call, rt_sigsuspend(), was added to
56       support an enlarged sigset_t type.  The new system call takes a  second
57       argument,  size_t  sigsetsize, which specifies the size in bytes of the
58       signal set in mask.  This argument is currently required  to  have  the
59       value  sizeof(sigset_t)  (or the error EINVAL results).  The glibc sig‐
60       suspend() wrapper function hides these details from  us,  transparently
61       calling rt_sigsuspend() when the kernel provides it.
62

NOTES

64       Normally,  sigsuspend()  is  used in conjunction with sigprocmask(2) in
65       order to prevent delivery of a signal during the execution of a  criti‐
66       cal  code  section.   The caller first blocks the signals with sigproc‐
67       mask(2).  When the critical code has completed, the caller  then  waits
68       for  the  signals by calling sigsuspend() with the signal mask that was
69       returned by sigprocmask(2) (in the oldset argument).
70
71       See sigsetops(3) for details on manipulating signal sets.
72