Debian Codegraph @

upstream/debian-trixie/man2/sigsuspend.2

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