| blob | b3551d147c3b878024597bdfe7521b504d456b62 |
1 .\" $NetBSD: sigvec.3,v 1.24 2005/12/03 21:01:53 christos Exp $
2 .\"
3 .\" Copyright (c) 1980, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" from: @(#)sigvec.2 8.2 (Berkeley) 4/19/94
31 .\"
32 .Dd December 3, 2005
33 .Dt SIGVEC 3
34 .Os
35 .Sh NAME
36 .Nm sigvec
37 .Nd software signal facilities
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In signal.h
42 .Bd -literal
43 struct sigvec {
44 void (*sv_handler)();
45 int sv_mask;
46 int sv_flags;
47 };
48 .Ed
49 .Ft int
50 .Fn sigvec "int sig" "struct sigvec *vec" "struct sigvec *ovec"
51 .Sh DESCRIPTION
52 .Bf -symbolic
53 This interface is made obsolete by
54 .Xr sigaction 2 .
55 The structure, flags, and function declaration have been removed from
56 the header files but the function is kept in the c library for binary
57 compatibility.
58 .Ef
59 .Pp
60 The system defines a set of signals that may be delivered to a process.
61 Signal delivery resembles the occurrence of a hardware interrupt:
62 the signal is blocked from further occurrence, the current process
63 context is saved, and a new one is built.
64 A process may specify a
65 .Em handler
66 to which a signal is delivered, or specify that a signal is to be
67 .Em ignored .
68 A process may also specify that a default action is to be taken
69 by the system when a signal occurs.
70 A signal may also be
71 .Em blocked ,
72 in which case its delivery is postponed until it is
73 .Em unblocked .
74 The action to be taken on delivery is determined at the time
75 of delivery.
76 Normally, signal handlers execute on the current stack
77 of the process.
78 This may be changed, on a per-handler basis, so that signals are
79 taken on a special
80 .Em "signal stack" .
81 .Pp
82 Signal routines execute with the signal that caused their
83 invocation
84 .Em blocked ,
85 but other signals may yet occur.
86 A global
87 .Em "signal mask"
88 defines the set of signals currently blocked from delivery
89 to a process.
90 The signal mask for a process is initialized from that of its parent
91 (normally 0).
92 It may be changed with a
93 .Xr sigblock 3
94 or
95 .Xr sigsetmask 3
96 call, or when a signal is delivered to the process.
97 .Pp
98 When a signal
99 condition arises for a process, the signal is added to a set of
100 signals pending for the process.
101 If the signal is not currently
102 .Em blocked
103 by the process then it is delivered to the process.
104 When a caught signal
105 is delivered, the current state of the process is saved,
106 a new signal mask is calculated (as described below),
107 and the signal handler is invoked.
108 The call to the handler is arranged so that if the signal handling
109 routine returns normally the process will resume execution in the
110 context from before the signal's delivery.
111 If the process wishes to resume in a different context, then it
112 must arrange to restore the previous context itself.
113 .Pp
114 When a signal is delivered to a process a new signal mask is
115 installed for the duration of the process' signal handler
116 (or until a
117 .Xr sigblock 3
118 or
119 .Xr sigsetmask 3
120 call is made).
121 This mask is formed by taking the union of the current signal mask,
122 the signal to be delivered, and
123 the signal mask associated with the handler to be invoked.
124 .Pp
125 .Fn sigvec
126 assigns a handler for a specific signal.
127 If
128 .Fa vec
129 is non-zero, it
130 specifies an action
131 .Pf ( Dv SIG_DFL ,
132 .Dv SIG_IGN ,
133 or a handler routine) and mask
134 to be used when delivering the specified signal.
135 Further, if the
136 .Dv SV_ONSTACK
137 bit is set in
138 .Fa sv_flags ,
139 the system will deliver the signal to the process on a
140 .Em "signal stack" ,
141 specified with
142 .Xr sigaltstack 2 .
143 If
144 .Fa ovec
145 is non-zero, the previous handling information for the signal
146 is returned to the user.
147 .Pp
148 Once a signal handler is installed, it remains installed
149 until another
150 .Fn sigvec
151 call is made, or an
152 .Xr execve 2
153 is performed.
154 A signal-specific default action may be reset by
155 setting
156 .Fa sv_handler
157 to
158 .Dv SIG_DFL .
159 The defaults are process termination, possibly with core dump;
160 no action; stopping the process; or continuing the process.
161 See the signal list below for each signal's default action.
162 If
163 .Fa sv_handler
164 is set to
165 .Dv SIG_DFL ,
166 the default action for the signal is to discard the signal,
167 and if a signal is pending,
168 the pending signal is discarded even if the signal is masked.
169 If
170 .Fa sv_handler
171 is set to
172 .Dv SIG_IGN ,
173 current and pending instances
174 of the signal are ignored and discarded.
175 .Pp
176 Options may be specified by setting
177 .Em sv_flags .
178 If the
179 .Dv SV_ONSTACK
180 bit is set in
181 .Fa sv_flags ,
182 the system will deliver the signal to the process on a
183 .Em "signal stack" ,
184 specified with
185 .Xr sigstack 2 .
186 .Pp
187 If a signal is caught during the system calls listed below,
188 the call may be restarted,
189 the call may return with a data transfer shorter than requested,
190 or the call may be forced to terminate
191 with the error
192 .Dv EINTR .
193 Interrupting of pending calls is requested
194 by setting the
195 .Dv SV_INTERRUPT
196 bit in
197 .Ar sv_flags .
198 The affected system calls include
199 .Xr open 2 ,
200 .Xr read 2 ,
201 .Xr write 2 ,
202 .Xr sendto 2 ,
203 .Xr recvfrom 2 ,
204 .Xr sendmsg 2
205 and
206 .Xr recvmsg 2
207 on a communications channel or a slow device (such as a terminal,
208 but not a regular file)
209 and during a
210 .Xr wait 2
211 or
212 .Xr ioctl 2 .
213 However, calls that have already committed are not restarted,
214 but instead return a partial success (for example, a short read count).
215 .Pp
216 After a
217 .Xr fork 2
218 or
219 .Xr vfork 2
220 all signals, the signal mask, the signal stack,
221 and the interrupt/restart flags are inherited by the child.
222 .Pp
223 The
224 .Xr execve 2
225 system call reinstates the default action for all signals which
226 were caught and resets all signals to be caught on the user stack.
227 Ignored signals remain ignored;
228 the signal mask remains the same;
229 signals that interrupt pending system calls continue to do so.
230 .Pp
231 See
232 .Xr signal 7
233 for comprehensive list of supported signals.
234 .Sh NOTES
235 The mask specified in
236 .Fa vec
237 is not allowed to block
238 .Dv SIGKILL
239 or
240 .Dv SIGSTOP .
241 This is enforced silently by the system.
242 .Pp
243 The
244 .Dv SV_INTERRUPT
245 flag is not available in
246 .Bx 4.2 ,
247 hence it should not be used if backward compatibility is needed.
248 .Sh RETURN VALUES
249 A 0 value indicated that the call succeeded.
250 A \-1 return value indicates an error occurred and
251 .Va errno
252 is set to indicated the reason.
253 .Sh EXAMPLES
254 The handler routine can be declared:
255 .Bd -literal -offset indent
256 void
257 handler(sig, code, scp)
258 int sig, code;
259 struct sigcontext *scp;
260 .Ed
261 .Pp
262 Here
263 .Fa sig
264 is the signal number, into which the hardware faults and traps are
265 mapped as defined below.
266 .Fa code
267 is a parameter that is either a constant
268 or the code provided by the hardware.
269 .Fa scp
270 is a pointer to the
271 .Fa sigcontext
272 structure (defined in
273 .Aq Pa signal.h ) ,
274 used to restore the context from before the signal.
275 .Sh ERRORS
276 .Fn sigvec
277 will fail and no new signal handler will be installed if one
278 of the following occurs:
279 .Bl -tag -width Er
280 .It Bq Er EFAULT
281 Either
282 .Fa vec
283 or
284 .Fa ovec
285 points to memory that is not a valid part of the process
286 address space.
287 .It Bq Er EINVAL
288 .Fa sig
289 is not a valid signal number.
290 .It Bq Er EINVAL
291 An attempt is made to ignore or supply a handler for
292 .Dv SIGKILL
293 or
294 .Dv SIGSTOP .
295 .El
296 .Sh SEE ALSO
297 .Xr kill 1 ,
298 .Xr kill 2 ,
299 .Xr ptrace 2 ,
300 .Xr sigaction 2 ,
301 .Xr sigaltstack 2 ,
302 .Xr sigprocmask 2 ,
303 .Xr sigstack 2 ,
304 .Xr sigsuspend 2 ,
305 .Xr setjmp 3 ,
306 .Xr sigblock 3 ,
307 .Xr siginterrupt 3 ,
308 .Xr signal 3 ,
309 .Xr sigpause 3 ,
310 .Xr sigsetmask 3 ,
311 .Xr sigsetops 3 ,
312 .Xr tty 4 ,
313 .Xr signal 7