Debian Codegraph @

upstream/debian-unstable/man3/sigvec.3

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