Debian Codegraph @

upstream/debian-trixie/man3/sigvec.3

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