| blob | a1b0119139f7433fe70530b1a33fe0993b5a97ac |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution.
4 .TH SIGVEC 3UCB "Oct 30, 2007"
5 .SH NAME
6 sigvec \- software signal facilities
7 .SH SYNOPSIS
8 .LP
9 .nf
10 \fB/usr/ucb/cc\fR [ \fIflag\fR \&.\|.\|. ] \fIfile\fR\&.\|.\|.
11 #include <signal.h>
13 \fBint\fR \fBsigvec\fR(\fIsig\fR, \fInvec\fR, \fIovec\fR)
14 \fBint\fR \fIsig\fR;
15 \fBstruct sigvec *\fR\fInvec\fR, \fB*\fR\fIovec\fR;
16 .fi
18 .SH DESCRIPTION
19 .sp
20 .LP
21 The system defines a set of signals that may be delivered to a process. Signal
22 delivery resembles the occurrence of a hardware interrupt: the signal is
23 blocked from further occurrence, the current process context is saved, and a
24 new one is built. A process may specify a \fIhandler\fR to which a signal is
25 delivered, or specify that a signal is to be \fIblocked\fR or \fIignored\fR. A
26 process may also specify that a default action is to be taken by the system
27 when a signal occurs. Normally, signal handlers execute on the current stack of
28 the process. This may be changed, on a per-handler basis, so that signals are
29 taken on a special \fIsignal stack\fR.
30 .sp
31 .LP
32 All signals have the same \fIpriority\fR. Signal routines execute with the
33 signal that caused their invocation to be \fIblocked\fR, but other signals may
34 yet occur. A global \fIsignal mask\fR defines the set of signals currently
35 blocked from delivery to a process. The signal mask for a process is
36 initialized from that of its parent (normally 0). It may be changed with a
37 \fBsigblock()\fR or \fBsigsetmask()\fR call, or when a signal is delivered to
38 the process.
39 .sp
40 .LP
41 A process may also specify a set of \fIflags\fR for a signal that affect the
42 delivery of that signal.
43 .sp
44 .LP
45 When a signal condition arises for a process, the signal is added to a set of
46 signals pending for the process. If the signal is not currently \fIblocked\fR
47 by the process then it is delivered to the process. When a signal is
48 delivered, the current state of the process is saved, a new signal mask is
49 calculated (as described below), and the signal handler is invoked. The call to
50 the handler is arranged so that if the signal handling routine returns normally
51 the process will resume execution in the context from before the signal's
52 delivery. If the process wishes to resume in a different context, then it must
53 arrange to restore the previous context itself.
54 .sp
55 .LP
56 When a signal is delivered to a process a new signal mask is installed for the
57 duration of the process' signal handler (or until a \fBsigblock()\fR or
58 \fBsigsetmask()\fR call is made). This mask is formed by taking the current
59 signal mask, adding the signal to be delivered, and \fBOR\fRing in the signal
60 mask associated with the handler to be invoked.
61 .sp
62 .LP
63 The action to be taken when the signal is delivered is specified by a
64 \fBsigvec()\fR structure, which includes the following members:
65 .sp
66 .in +2
67 .nf
68 void (*sv_handler)(\|); /* signal handler */
69 int sv_mask; /* signal mask to apply */
70 int sv_flags; /* see signal options */
71 #define SV_ONSTACK /* take signal on signal stack */
72 #define SV_INTERRUPT /* do not restart system on signal
73 return */
74 #define SV_RESETHAND /* reset handler to SIG_DFL when
75 signal taken*/
76 .fi
77 .in -2
79 .sp
80 .LP
81 If the \fBSV_ONSTACK\fR bit is set in the flags for that signal, the system
82 will deliver the signal to the process on the signal stack specified with
83 \fBsigstack\fR(3UCB) rather than delivering the signal on the current stack.
84 .sp
85 .LP
86 If \fInvec\fR is not a \fINULL\fR pointer, \fBsigvec()\fR assigns the handler
87 specified by \fBsv_handler()\fR, the mask specified by \fBsv_mask()\fR, and the
88 flags specified by \fBsv_flags()\fR to the specified signal. If \fInvec\fR is
89 a \fINULL\fR pointer, \fBsigvec()\fR does not change the handler, mask, or
90 flags for the specified signal.
91 .sp
92 .LP
93 The mask specified in \fInvec\fR is not allowed to block \fBSIGKILL\fR,
94 \fBSIGSTOP\fR, or \fBSIGCONT\fR. The system enforces this restriction silently.
95 .sp
96 .LP
97 If \fIovec\fR is not a \fINULL\fR pointer, the handler, mask, and flags in
98 effect for the signal before the call to \fBsigvec()\fR are returned to the
99 user. A call to \fBsigvec()\fR with \fInvec\fR a \fINULL\fR pointer and
100 \fIovec\fR not a \fINULL\fR pointer can be used to determine the handling
101 information currently in effect for a signal without changing that information.
102 .sp
103 .LP
104 The following is a list of all signals with names as in the include file
105 \fB<signal.h>\fR:
106 .sp
107 .ne 2
108 .na
109 \fB\fBSIGHUP\fR\fR
110 .ad
111 .RS 13n
112 hangup
113 .RE
115 .sp
116 .ne 2
117 .na
118 \fB\fBSIGINT\fR\fR
119 .ad
120 .RS 13n
121 interrupt
122 .RE
124 .sp
125 .ne 2
126 .na
127 \fB\fBSIGQUIT\fR*\fR
128 .ad
129 .RS 13n
130 quit
131 .RE
133 .sp
134 .ne 2
135 .na
136 \fB\fBSIGILL\fR*\fR
137 .ad
138 .RS 13n
139 illegal instruction
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fB\fBSIGTRAP\fR*\fR
146 .ad
147 .RS 13n
148 trace trap
149 .RE
151 .sp
152 .ne 2
153 .na
154 \fB\fBSIGABRT\fR*\fR
155 .ad
156 .RS 13n
157 abort (generated by \fBabort\fR(3C) routine)
158 .RE
160 .sp
161 .ne 2
162 .na
163 \fB\fBSIGEMT\fR*\fR
164 .ad
165 .RS 13n
166 emulator trap
167 .RE
169 .sp
170 .ne 2
171 .na
172 \fB\fBSIGFPE\fR*\fR
173 .ad
174 .RS 13n
175 arithmetic exception
176 .RE
178 .sp
179 .ne 2
180 .na
181 \fB\fBSIGKILL\fR\fR
182 .ad
183 .RS 13n
184 kill (cannot be caught, blocked, or ignored)
185 .RE
187 .sp
188 .ne 2
189 .na
190 \fB\fBSIGBUS\fR*\fR
191 .ad
192 .RS 13n
193 bus error
194 .RE
196 .sp
197 .ne 2
198 .na
199 \fB\fBSIGSEGV\fR*\fR
200 .ad
201 .RS 13n
202 segmentation violation
203 .RE
205 .sp
206 .ne 2
207 .na
208 \fB\fBSIGSYS\fR*\fR
209 .ad
210 .RS 13n
211 bad argument to function
212 .RE
214 .sp
215 .ne 2
216 .na
217 \fB\fBSIGPIPE\fR\fR
218 .ad
219 .RS 13n
220 write on a pipe or other socket with no one to read it
221 .RE
223 .sp
224 .ne 2
225 .na
226 \fB\fBSIGALRM\fR\fR
227 .ad
228 .RS 13n
229 alarm clock
230 .RE
232 .sp
233 .ne 2
234 .na
235 \fB\fBSIGTERM\fR\fR
236 .ad
237 .RS 13n
238 software termination signal
239 .RE
241 .sp
242 .ne 2
243 .na
244 \fB\fBSIGURG\fR*\fR
245 .ad
246 .RS 13n
247 urgent condition present on socket
248 .RE
250 .sp
251 .ne 2
252 .na
253 \fB\fBSIGSTOP\fR**\fR
254 .ad
255 .RS 13n
256 stop (cannot be caught, blocked, or ignored)
257 .RE
259 .sp
260 .ne 2
261 .na
262 \fB\fBSIGTSTP\fR**\fR
263 .ad
264 .RS 13n
265 stop signal generated from keyboard
266 .RE
268 .sp
269 .ne 2
270 .na
271 \fB\fBSIGCONT\fR*\fR
272 .ad
273 .RS 13n
274 continue after stop (cannot be blocked)
275 .RE
277 .sp
278 .ne 2
279 .na
280 \fB\fBSIGCHLD\fR*\fR
281 .ad
282 .RS 13n
283 child status has changed
284 .RE
286 .sp
287 .ne 2
288 .na
289 \fB\fBSIGTTIN\fR**\fR
290 .ad
291 .RS 13n
292 background read attempted from control terminal
293 .RE
295 .sp
296 .ne 2
297 .na
298 \fB\fBSIGTTOU\fR**\fR
299 .ad
300 .RS 13n
301 background write attempted to control terminal
302 .RE
304 .sp
305 .ne 2
306 .na
307 \fB\fBSIGIO\fR*\fR
308 .ad
309 .RS 13n
310 I/O is possible on a descriptor (see \fBfcntl\fR(2))
311 .RE
313 .sp
314 .ne 2
315 .na
316 \fB\fBSIGXCPU\fR\fR
317 .ad
318 .RS 13n
319 cpu time limit exceeded (see \fBgetrlimit\fR(2))
320 .RE
322 .sp
323 .ne 2
324 .na
325 \fB\fBSIGXFSZ\fR\fR
326 .ad
327 .RS 13n
328 file size limit exceeded (see \fBgetrlimit\fR(2))
329 .RE
331 .sp
332 .ne 2
333 .na
334 \fB\fBSIGVTALRM\fR\fR
335 .ad
336 .RS 13n
337 virtual time alarm; see \fBsetitimer()\fR on \fBgetitimer\fR(2)
338 .RE
340 .sp
341 .ne 2
342 .na
343 \fB\fBSIGPROF\fR\fR
344 .ad
345 .RS 13n
346 profiling timer alarm; see \fBsetitimer()\fR on \fBgetitimer\fR(2)
347 .RE
349 .sp
350 .ne 2
351 .na
352 \fB\fBSIGWINCH\fR*\fR
353 .ad
354 .RS 13n
355 window changed (see \fBtermio\fR(7I))
356 .RE
358 .sp
359 .ne 2
360 .na
361 \fB\fBSIGLOST\fR\fR
362 .ad
363 .RS 13n
364 resource lost (see \fBlockd\fR(1M))
365 .RE
367 .sp
368 .ne 2
369 .na
370 \fB\fBSIGUSR1\fR\fR
371 .ad
372 .RS 13n
373 user-defined signal 1
374 .RE
376 .sp
377 .ne 2
378 .na
379 \fB\fBSIGUSR2\fR\fR
380 .ad
381 .RS 13n
382 user-defined signal 2
383 .RE
385 .sp
386 .LP
387 The starred signals in the list above cause a core image if not caught or
388 ignored.
389 .sp
390 .LP
391 Once a signal handler is installed, it remains installed until another
392 \fBsigvec()\fR call is made, or an \fBexecve\fR(2) is performed, unless the
393 \fBSV_RESETHAND\fR bit is set in the flags for that signal. In that case, the
394 value of the handler for the caught signal will be set to \fBSIG_DFL\fR before
395 entering the signal-catching function, unless the signal is \fBSIGILL\fR,
396 \fBSIGPWR\fR, or \fBSIGTRAP\fR. Also, if this bit is set, the bit for that
397 signal in the signal mask will not be set; unless the signal mask associated
398 with that signal blocks that signal, further occurrences of that signal will
399 not be blocked. The \fBSV_RESETHAND\fR flag is not available in 4.2BSD, hence
400 it should not be used if backward compatibility is needed.
401 .sp
402 .LP
403 The default action for a signal may be reinstated by setting the signal's
404 handler to \fBSIG_DFL\fR; this default is termination except for signals marked
405 with * or **. Signals marked with * are discarded if the action is
406 \fBSIG_DFL\fR; signals marked with ** cause the process to stop. If the process
407 is terminated, a "core image" will be made in the current working directory of
408 the receiving process if the signal is one for which an asterisk appears in the
409 above list (see \fBcore\fR(4)).
410 .sp
411 .LP
412 If the handler for that signal is \fBSIG_IGN\fR, the signal is subsequently
413 ignored, and pending instances of the signal are discarded.
414 .sp
415 .LP
416 If a caught signal occurs during certain functions, the call is normally
417 restarted. The call can be forced to terminate prematurely with an \fBEINTR\fR
418 error return by setting the \fBSV_INTERRUPT\fR bit in the flags for that
419 signal. The \fBSV_INTERRUPT\fR flag is not available in 4.2BSD, hence it should
420 not be used if backward compatibility is needed. The affected functions are
421 \fBread\fR(2) or \fBwrite\fR(2) on a slow device (such as a terminal or pipe or
422 other socket, but not a file) and during a \fBwait\fR(3C).
423 .sp
424 .LP
425 After a \fBfork\fR(2) or \fBvfork\fR(2) the child inherits all signals, the
426 signal mask, the signal stack, and the restart/interrupt and
427 reset-signal-handler flags.
428 .sp
429 .LP
430 The \fBexecve\fR(2) call resets all caught signals to default action and resets
431 all signals to be caught on the user stack. Ignored signals remain ignored; the
432 signal mask remains the same; signals that interrupt functions continue to do
433 so.
434 .sp
435 .LP
436 The accuracy of \fIaddr\fR is machine dependent. For example, certain machines
437 may supply an address that is on the same page as the address that caused the
438 fault. If an appropriate \fIaddr\fR cannot be computed it will be set to
439 \fBSIG_NOADDR\fR.
440 .SH RETURN VALUES
441 .sp
442 .LP
443 A \fB0\fR value indicates that the call succeeded. A \fB\(mi1\fR return value
444 indicates that an error occurred and \fBerrno\fR is set to indicate the reason.
445 .SH ERRORS
446 .sp
447 .LP
448 \fBsigvec()\fR will fail and no new signal handler will be installed if one of
449 the following occurs:
450 .sp
451 .ne 2
452 .na
453 \fB\fBEFAULT\fR\fR
454 .ad
455 .RS 10n
456 Either \fInvec\fR or \fIovec\fR is not a \fINULL\fR pointer and points to
457 memory that is not a valid part of the process address space.
458 .RE
460 .sp
461 .ne 2
462 .na
463 \fB\fBEINVAL\fR\fR
464 .ad
465 .RS 10n
466 \fIsig\fR is not a valid signal number or is \fBSIGKILL\fR or \fBSIGSTOP\fR.
467 .RE
469 .SH SEE ALSO
470 .sp
471 .LP
472 \fBIntro\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2),
473 \fBgetitimer\fR(2), \fBgetrlimit\fR(2), \fBioctl\fR(2), \fBkill\fR(2),
474 \fBread\fR(2), \fBumask\fR(2), \fBvfork\fR(2), \fBwrite\fR(2),
475 \fBptrace\fR(3C), \fBsetjmp\fR(3C) \fBsigblock\fR(3UCB), \fBsignal\fR(3C),
476 \fBsignal\fR(3UCB), \fBsigstack\fR(3UCB), \fBwait\fR(3C), \fBwait\fR(3UCB),
477 \fBcore\fR(4), \fBstreamio\fR(7I), \fBtermio\fR(7I)
478 .SH NOTES
479 .sp
480 .LP
481 Use of these interfaces should be restricted to only applications written on
482 BSD platforms. Use of these interfaces with any of the system libraries or in
483 multi-thread applications is unsupported.
484 .sp
485 .LP
486 \fBSIGPOLL\fR is a synonym for \fBSIGIO\fR. A \fBSIGIO\fR will be issued when a
487 file descriptor corresponding to a \fBSTREAMS\fR (see \fBIntro\fR(2)) file has
488 a "selectable" event pending. Unless that descriptor has been put into
489 asynchronous mode (see \fBfcntl\fR(2)), a process may specifically request that
490 this signal be sent using the \fBI_SETSIG\fR \fBioctl\fR(2) call (see
491 \fBstreamio\fR(7I)). Otherwise, the process will never receive \fBSIGPOLLs0\fR.
492 .sp
493 .LP
494 The handler routine can be declared:
495 .sp
496 .in +2
497 .nf
498 void handler(int sig, int code, struct sigcontext *scp,
499 char *addr);
500 .fi
501 .in -2
503 .sp
504 .LP
505 Here \fIsig\fR is the signal number; \fIcode\fR is a parameter of certain
506 signals that provides additional detail; \fIscp\fR is a pointer to the
507 \fBsigcontext\fR structure (defined in \fBsignal.h\fR), used to restore the
508 context from before the signal; and \fIaddr\fR is additional address
509 information.
510 .sp
511 .LP
512 The signals \fBSIGKILL\fR, \fBSIGSTOP\fR, and \fBSIGCONT\fR cannot be ignored.