| blob | 981bd7c4de407e481be67a481c8ece4b0a07cd61 |
1 .\" Copyright (c) 2005 by Michael Kerrisk <mtk.manpages@gmail.com>
2 .\"
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
7 .\"
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
12 .\"
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
19 .\" professionally.
20 .\"
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" %%%LICENSE_END
24 .\"
25 .TH SIGSET 3 2021-03-22 "Linux" "Linux Programmer's Manual"
26 .SH NAME
27 sigset, sighold, sigrelse, sigignore \- System V signal API
28 .SH SYNOPSIS
29 .nf
30 .B #include <signal.h>
31 .PP
32 .B typedef void (*sighandler_t)(int);
33 .PP
34 .BI "sighandler_t sigset(int " sig ", sighandler_t " disp );
35 .PP
36 .BI "int sighold(int " sig );
37 .BI "int sigrelse(int " sig );
38 .BI "int sigignore(int " sig );
39 .fi
40 .PP
41 .RS -4
42 Feature Test Macro Requirements for glibc (see
43 .BR feature_test_macros (7)):
44 .RE
45 .PP
46 .BR sigset (),
47 .BR sighold (),
48 .BR sigrelse (),
49 .BR sigignore ():
50 .nf
51 _XOPEN_SOURCE >= 500
52 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
53 .fi
54 .SH DESCRIPTION
55 These functions are provided in glibc as a compatibility interface
56 for programs that make use of the historical System V signal API.
57 This API is obsolete: new applications should use the POSIX signal API
58 .RB ( sigaction (2),
59 .BR sigprocmask (2),
60 etc.)
61 .PP
62 The
63 .BR sigset ()
64 function modifies the disposition of the signal
65 .IR sig .
66 The
67 .I disp
68 argument can be the address of a signal handler function,
69 or one of the following constants:
70 .TP
71 .B SIG_DFL
72 Reset the disposition of
73 .I sig
74 to the default.
75 .TP
76 .B SIG_IGN
77 Ignore
78 .IR sig .
79 .TP
80 .B SIG_HOLD
81 Add
82 .I sig
83 to the process's signal mask, but leave the disposition of
84 .I sig
85 unchanged.
86 .PP
87 If
88 .I disp
89 specifies the address of a signal handler, then
90 .I sig
91 is added to the process's signal mask during execution of the handler.
92 .PP
93 If
94 .I disp
95 was specified as a value other than
96 .BR SIG_HOLD ,
97 then
98 .I sig
99 is removed from the process's signal mask.
100 .PP
101 The dispositions for
102 .B SIGKILL
103 and
104 .B SIGSTOP
105 cannot be changed.
106 .PP
107 The
108 .BR sighold ()
109 function adds
110 .I sig
111 to the calling process's signal mask.
112 .PP
113 The
114 .BR sigrelse ()
115 function removes
116 .I sig
117 from the calling process's signal mask.
118 .PP
119 The
120 .BR sigignore ()
121 function sets the disposition of
122 .I sig
123 to
124 .BR SIG_IGN .
125 .SH RETURN VALUE
126 On success,
127 .BR sigset ()
128 returns
129 .B SIG_HOLD
130 if
131 .I sig
132 was blocked before the call,
133 or the signal's previous disposition
134 if it was not blocked before the call.
135 On error,
136 .BR sigset ()
137 returns \-1, with
138 .I errno
139 set to indicate the error.
140 (But see BUGS below.)
141 .PP
142 The
143 .BR sighold (),
144 .BR sigrelse (),
145 and
146 .BR sigignore ()
147 functions return 0 on success; on error, these functions return \-1 and set
148 .I errno
149 to indicate the error.
150 .SH ERRORS
151 For
152 .BR sigset ()
153 see the ERRORS under
154 .BR sigaction (2)
155 and
156 .BR sigprocmask (2).
157 .PP
158 For
159 .BR sighold ()
160 and
161 .BR sigrelse ()
162 see the ERRORS under
163 .BR sigprocmask (2).
164 .PP
165 For
166 .BR sigignore (),
167 see the errors under
168 .BR sigaction (2).
169 .SH ATTRIBUTES
170 For an explanation of the terms used in this section, see
171 .BR attributes (7).
172 .ad l
173 .nh
174 .TS
175 allbox;
176 lbx lb lb
177 l l l.
178 Interface Attribute Value
179 T{
180 .BR sigset (),
181 .BR sighold (),
182 .BR sigrelse (),
183 .BR sigignore ()
184 T} Thread safety MT-Safe
185 .TE
186 .hy
187 .ad
188 .sp 1
189 .SH CONFORMING TO
190 SVr4, POSIX.1-2001, POSIX.1-2008.
191 These functions are obsolete: do not use them in new programs.
192 POSIX.1-2008 marks
193 .BR sighold (),
194 .BR sigignore (),
195 .BR sigpause (3),
196 .BR sigrelse (),
197 and
198 .BR sigset ()
199 as obsolete, recommending the use of
200 .BR sigaction (2),
201 .BR sigprocmask (2),
202 .BR pthread_sigmask (3),
203 and
204 .BR sigsuspend (2)
205 instead.
206 .SH NOTES
207 These functions appeared in glibc version 2.1.
208 .PP
209 The
210 .I sighandler_t
211 type is a GNU extension; it is used on this page only to make the
212 .BR sigset ()
213 prototype more easily readable.
214 .PP
215 The
216 .BR sigset ()
217 function provides reliable signal handling semantics (as when calling
218 .BR sigaction (2)
219 with
220 .I sa_mask
221 equal to 0).
222 .PP
223 On System V, the
224 .BR signal ()
225 function provides unreliable semantics (as when calling
226 .BR sigaction (2)
227 with
228 .I sa_mask
229 equal to
230 .IR "SA_RESETHAND | SA_NODEFER" ).
231 On BSD,
232 .BR signal ()
233 provides reliable semantics.
234 POSIX.1-2001 leaves these aspects of
235 .BR signal ()
236 unspecified.
237 See
238 .BR signal (2)
239 for further details.
240 .PP
241 In order to wait for a signal,
242 BSD and System V both provided a function named
243 .BR sigpause (3),
244 but this function has a different argument on the two systems.
245 See
246 .BR sigpause (3)
247 for details.
248 .SH BUGS
249 In versions of glibc before 2.2,
250 .BR sigset ()
251 did not unblock
252 .I sig
253 if
254 .I disp
255 was specified as a value other than
256 .BR SIG_HOLD .
257 .PP
258 In versions of glibc before 2.5,
259 .BR sigset ()
260 does not correctly return the previous disposition of the signal
261 in two cases.
262 First, if
263 .I disp
264 is specified as
265 .BR SIG_HOLD ,
266 then a successful
267 .BR sigset ()
268 always returns
269 .BR SIG_HOLD .
270 Instead, it should return the previous disposition of the signal
271 (unless the signal was blocked, in which case
272 .B SIG_HOLD
273 should be returned).
274 Second, if the signal is currently blocked, then
275 the return value of a successful
276 .BR sigset ()
277 should be
278 .BR SIG_HOLD .
279 Instead, the previous disposition of the signal is returned.
280 These problems have been fixed since glibc 2.5.
281 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1951
282 .SH SEE ALSO
283 .BR kill (2),
284 .BR pause (2),
285 .BR sigaction (2),
286 .BR signal (2),
287 .BR sigprocmask (2),
288 .BR raise (3),
289 .BR sigpause (3),
290 .BR sigvec (3),
291 .BR signal (7)