Debian Codegraph @

upstream/debian-unstable/man2/sigsuspend.2

raw
1 .\" Copyright 2005, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH sigsuspend 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 sigsuspend, rt_sigsuspend \- wait for a signal
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <signal.h>
15 .P
16 .BI "int sigsuspend(const sigset_t *" mask );
17 .fi
18 .P
19 .RS -4
20 Feature Test Macro Requirements for glibc (see
21 .BR feature_test_macros (7)):
22 .RE
23 .P
24 .BR sigsuspend ():
25 .nf
26 _POSIX_C_SOURCE
27 .fi
28 .SH DESCRIPTION
29 .BR sigsuspend ()
30 temporarily replaces the signal mask of the calling thread with the
31 mask given by
32 .I mask
33 and then suspends the thread until delivery of a signal whose
34 action is to invoke a signal handler or to terminate a process.
35 .P
36 If the signal terminates the process, then
37 .BR sigsuspend ()
38 does not return.
39 If the signal is caught, then
40 .BR sigsuspend ()
41 returns after the signal handler returns,
42 and the signal mask is restored to the state before the call to
43 .BR sigsuspend ().
44 .P
45 It is not possible to block
46 .B SIGKILL
47 or
48 .BR SIGSTOP ;
49 specifying these signals in
50 .IR mask ,
51 has no effect on the thread's signal mask.
52 .SH RETURN VALUE
53 .BR sigsuspend ()
54 always returns \-1, with
55 .I errno
56 set to indicate the error (normally,
57 .BR EINTR ).
58 .SH ERRORS
59 .TP
60 .B EFAULT
61 .I mask
62 points to memory which is not a valid part of the process address space.
63 .TP
64 .B EINTR
65 The call was interrupted by a signal;
66 .BR signal (7).
67 .SH STANDARDS
68 POSIX.1-2024.
69 .SH HISTORY
70 POSIX.1-2001.
71 .SS C library/kernel differences
72 The original Linux system call was named
73 .BR sigsuspend ().
74 However, with the addition of real-time signals in Linux 2.2,
75 the fixed-size, 32-bit
76 .I sigset_t
77 type supported by that system call was no longer fit for purpose.
78 Consequently, a new system call,
79 .BR rt_sigsuspend (),
80 was added to support an enlarged
81 .I sigset_t
82 type.
83 The new system call takes a second argument,
84 .IR "size_t sigsetsize" ,
85 which specifies the size in bytes of the signal set in
86 .IR mask .
87 This argument is currently required to have the value
88 .I sizeof(sigset_t)
89 (or the error
90 .B EINVAL
91 results).
92 The glibc
93 .BR sigsuspend ()
94 wrapper function hides these details from us, transparently calling
95 .BR rt_sigsuspend ()
96 when the kernel provides it.
97 .\"
98 .SH NOTES
99 Normally,
100 .BR sigsuspend ()
101 is used in conjunction with
102 .BR sigprocmask (2)
103 in order to prevent delivery of a signal during the execution of a
104 critical code section.
105 The caller first blocks the signals with
106 .BR sigprocmask (2).
107 When the critical code has completed, the caller then waits for the
108 signals by calling
109 .BR sigsuspend ()
110 with the signal mask that was returned by
111 .BR sigprocmask (2)
112 (in the
113 .I oldset
114 argument).
115 .P
116 See
117 .BR sigsetops (3)
118 for details on manipulating signal sets.
119 .SH SEE ALSO
120 .BR kill (2),
121 .BR pause (2),
122 .BR sigaction (2),
123 .BR signal (2),
124 .BR sigprocmask (2),
125 .BR sigwaitinfo (2),
126 .BR sigsetops (3),
127 .BR sigwait (3),
128 .BR signal (7)