| blob | b6644393b52a018b0677d488953160b8abb4d6a9 |
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 SIGVEC 3 2021-03-22 "Linux" "Linux Programmer's Manual"
26 .SH NAME
27 sigvec, sigblock, sigsetmask, siggetmask, sigmask \- BSD signal API
28 .SH SYNOPSIS
29 .nf
30 .B #include <signal.h>
31 .PP
32 .BI "int sigvec(int " sig ", const struct sigvec *" vec ", struct sigvec *" ovec );
33 .PP
34 .BI "int sigmask(int " signum );
35 .PP
36 .BI "int sigblock(int " mask );
37 .BI "int sigsetmask(int " mask );
38 .B int siggetmask(void);
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 All functions shown above:
47 .nf
48 Since glibc 2.19:
49 _DEFAULT_SOURCE
50 Glibc 2.19 and earlier:
51 _BSD_SOURCE
52 .fi
53 .SH DESCRIPTION
54 These functions are provided in glibc as a compatibility interface
55 for programs that make use of the historical BSD signal API.
56 This API is obsolete: new applications should use the POSIX signal API
57 .RB ( sigaction (2),
58 .BR sigprocmask (2),
59 etc.).
60 .PP
61 The
62 .BR sigvec ()
63 function sets and/or gets the disposition of the signal
64 .I sig
65 (like the POSIX
66 .BR sigaction (2)).
67 If
68 .I vec
69 is not NULL, it points to a
70 .I sigvec
71 structure that defines the new disposition for
72 .IR sig .
73 If
74 .I ovec
75 is not NULL, it points to a
76 .I sigvec
77 structure that is used to return the previous disposition of
78 .IR sig .
79 To obtain the current disposition of
80 .I sig
81 without changing it, specify NULL for
82 .IR vec ,
83 and a non-null pointer for
84 .IR ovec .
85 .PP
86 The dispositions for
87 .B SIGKILL
88 and
89 .B SIGSTOP
90 cannot be changed.
91 .PP
92 The
93 .I sigvec
94 structure has the following form:
95 .PP
96 .in +4n
97 .EX
98 struct sigvec {
99 void (*sv_handler)(int); /* Signal disposition */
100 int sv_mask; /* Signals to be blocked in handler */
101 int sv_flags; /* Flags */
102 };
103 .EE
104 .in
105 .PP
106 The
107 .I sv_handler
108 field specifies the disposition of the signal, and is either:
109 the address of a signal handler function;
110 .BR SIG_DFL ,
111 meaning the default disposition applies for the signal; or
112 .BR SIG_IGN ,
113 meaning that the signal is ignored.
114 .PP
115 If
116 .I sv_handler
117 specifies the address of a signal handler, then
118 .I sv_mask
119 specifies a mask of signals that are to be blocked while
120 the handler is executing.
121 In addition, the signal for which the handler is invoked is
122 also blocked.
123 Attempts to block
124 .B SIGKILL
125 or
126 .B SIGSTOP
127 are silently ignored.
128 .PP
129 If
130 .I sv_handler
131 specifies the address of a signal handler, then the
132 .I sv_flags
133 field specifies flags controlling what happens when the handler is called.
134 This field may contain zero or more of the following flags:
135 .TP
136 .B SV_INTERRUPT
137 If the signal handler interrupts a blocking system call,
138 then upon return from the handler the system call is not restarted:
139 instead it fails with the error
140 .BR EINTR .
141 If this flag is not specified, then system calls are restarted
142 by default.
143 .TP
144 .B SV_RESETHAND
145 Reset the disposition of the signal to the default
146 before calling the signal handler.
147 If this flag is not specified, then the handler remains established
148 until explicitly removed by a later call to
149 .BR sigvec ()
150 or until the process performs an
151 .BR execve (2).
152 .TP
153 .B SV_ONSTACK
154 Handle the signal on the alternate signal stack
155 (historically established under BSD using the obsolete
156 .BR sigstack ()
157 function; the POSIX replacement is
158 .BR sigaltstack (2)).
159 .PP
160 The
161 .BR sigmask ()
162 macro constructs and returns a "signal mask" for
163 .IR signum .
164 For example, we can initialize the
165 .I vec.sv_mask
166 field given to
167 .BR sigvec ()
168 using code such as the following:
169 .PP
170 .in +4n
171 .EX
172 vec.sv_mask = sigmask(SIGQUIT) | sigmask(SIGABRT);
173 /* Block SIGQUIT and SIGABRT during
174 handler execution */
175 .EE
176 .in
177 .PP
178 The
179 .BR sigblock ()
180 function adds the signals in
181 .I mask
182 to the process's signal mask
183 (like POSIX
184 .IR sigprocmask(SIG_BLOCK) ),
185 and returns the process's previous signal mask.
186 Attempts to block
187 .B SIGKILL
188 or
189 .B SIGSTOP
190 are silently ignored.
191 .PP
192 The
193 .BR sigsetmask ()
194 function sets the process's signal mask to the value given in
195 .I mask
196 (like POSIX
197 .IR sigprocmask(SIG_SETMASK) ),
198 and returns the process's previous signal mask.
199 .PP
200 The
201 .BR siggetmask ()
202 function returns the process's current signal mask.
203 This call is equivalent to
204 .IR sigblock(0) .
205 .SH RETURN VALUE
206 The
207 .BR sigvec ()
208 function returns 0 on success; on error, it returns \-1 and sets
209 .I errno
210 to indicate the error.
211 .PP
212 The
213 .BR sigblock ()
214 and
215 .BR sigsetmask ()
216 functions return the previous signal mask.
217 .PP
218 The
219 .BR sigmask ()
220 macro returns the signal mask for
221 .IR signum .
222 .SH ERRORS
223 See the ERRORS under
224 .BR sigaction (2)
225 and
226 .BR sigprocmask (2).
227 .SH VERSIONS
228 Starting with version 2.21, the GNU C library no longer exports the
229 .BR sigvec ()
230 function as part of the ABI.
231 (To ensure backward compatibility,
232 the glibc symbol versioning scheme continues to export the interface
233 to binaries linked against older versions of the library.)
234 .SH ATTRIBUTES
235 For an explanation of the terms used in this section, see
236 .BR attributes (7).
237 .ad l
238 .nh
239 .TS
240 allbox;
241 lbx lb lb
242 l l l.
243 Interface Attribute Value
244 T{
245 .BR sigvec (),
246 .BR sigmask (),
247 .BR sigblock (),
248 .BR sigsetmask (),
249 .BR siggetmask ()
250 T} Thread safety MT-Safe
251 .TE
252 .hy
253 .ad
254 .sp 1
255 .SH CONFORMING TO
256 All of these functions were in
257 4.3BSD, except
258 .BR siggetmask (),
259 whose origin is unclear.
260 These functions are obsolete: do not use them in new programs.
261 .SH NOTES
262 On 4.3BSD, the
263 .BR signal ()
264 function provided reliable semantics (as when calling
265 .BR sigvec ()
266 with
267 .I vec.sv_mask
268 equal to 0).
269 On System V,
270 .BR signal ()
271 provides unreliable semantics.
272 POSIX.1 leaves these aspects of
273 .BR signal ()
274 unspecified.
275 See
276 .BR signal (2)
277 for further details.
278 .PP
279 In order to wait for a signal,
280 BSD and System V both provided a function named
281 .BR sigpause (3),
282 but this function has a different argument on the two systems.
283 See
284 .BR sigpause (3)
285 for details.
286 .SH SEE ALSO
287 .BR kill (2),
288 .BR pause (2),
289 .BR sigaction (2),
290 .BR signal (2),
291 .BR sigprocmask (2),
292 .BR raise (3),
293 .BR sigpause (3),
294 .BR sigset (3),
295 .BR signal (7)