xref: /freebsd/lib/libc/compat-43/sigvec.2 (revision 6e5dcc6113da649a79e5bc2c3ea9329bcd1d85d5)
1.\" Copyright (c) 1980, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)sigvec.2	8.2 (Berkeley) 4/19/94
29.\"
30.Dd April 2, 2022
31.Dt SIGVEC 2
32.Os
33.Sh NAME
34.Nm sigvec
35.Nd software signal facilities
36.Sh LIBRARY
37.Lb libc
38.Sh SYNOPSIS
39.In signal.h
40.Bd -literal
41struct sigvec {
42        void     (*sv_handler)();
43	int      sv_mask;
44	int      sv_flags;
45};
46.Ed
47.Ft int
48.Fn sigvec "int sig" "struct sigvec *vec" "struct sigvec *ovec"
49.Sh DESCRIPTION
50.Bf -symbolic
51This interface is made obsolete by
52.Xr sigaction 2 .
53.Ef
54.Pp
55The system defines a set of signals that may be delivered to a process.
56Signal delivery resembles the occurrence of a hardware interrupt:
57the signal is blocked from further occurrence, the current process
58context is saved, and a new one is built.
59A process may specify a
60.Em handler
61to which a signal is delivered, or specify that a signal is to be
62.Em blocked
63or
64.Em ignored .
65A process may also specify that a default action is to be taken
66by the system when a signal occurs.
67Normally, signal handlers execute on the current stack
68of the process.
69This may be changed, on a per-handler basis,
70so that signals are taken on a special
71.Em "signal stack" .
72.Pp
73All signals have the same
74.Em priority .
75Signal routines execute with the signal that caused their
76invocation
77.Em blocked ,
78but other signals may yet occur.
79A global
80.Em "signal mask"
81defines the set of signals currently blocked from delivery
82to a process.
83The signal mask for a process is initialized
84from that of its parent (normally 0).
85It
86may be changed with a
87.Xr sigblock 2
88or
89.Xr sigsetmask 2
90call, or when a signal is delivered to the process.
91.Pp
92When a signal
93condition arises for a process, the signal is added to a set of
94signals pending for the process.
95If the signal is not currently
96.Em blocked
97by the process then it is delivered to the process.
98When a signal
99is delivered, the current state of the process is saved,
100a new signal mask is calculated (as described below),
101and the signal handler is invoked.
102The call to the handler
103is arranged so that if the signal handling routine returns
104normally the process will resume execution in the context
105from before the signal's delivery.
106If the process wishes to resume in a different context, then it
107must arrange to restore the previous context itself.
108.Pp
109When a signal is delivered to a process a new signal mask is
110installed for the duration of the process' signal handler
111(or until a
112.Xr sigblock 2
113or
114.Xr sigsetmask 2
115call is made).
116This mask is formed by taking the current signal mask,
117adding the signal to be delivered, and
118.Em or Ns 'ing
119in the signal mask associated with the handler to be invoked.
120.Pp
121The
122.Fn sigvec
123function
124assigns a handler for a specific signal.
125If
126.Fa vec
127is non-zero, it
128specifies a handler routine and mask
129to be used when delivering the specified signal.
130Further, if the
131.Dv SV_ONSTACK
132bit is set in
133.Fa sv_flags ,
134the system will deliver the signal to the process on a
135.Em "signal stack" ,
136specified with
137.Xr sigaltstack 2 .
138If
139.Fa ovec
140is non-zero, the previous handling information for the signal
141is returned to the user.
142.Pp
143The following is a list of all signals
144with names as in the include file
145.In signal.h :
146.Bl -column SIGVTALARMXX "create core imagexxx"
147.It Sy "NAME	Default Action	Description"
148.It Dv SIGHUP No "	terminate process" "	terminal line hangup"
149.It Dv SIGINT No "	terminate process" "	interrupt program"
150.It Dv SIGQUIT No "	create core image" "	quit program"
151.It Dv SIGILL No "	create core image" "	illegal instruction"
152.It Dv SIGTRAP No "	create core image" "	trace trap"
153.It Dv SIGABRT No "	create core image" Ta Xr abort 3
154call (formerly
155.Dv SIGIOT )
156.It Dv SIGEMT No "	create core image" "	emulate instruction executed"
157.It Dv SIGFPE No "	create core image" "	floating-point exception"
158.It Dv SIGKILL No "	terminate process" "	kill program"
159.It Dv SIGBUS No "	create core image" "	bus error"
160.It Dv SIGSEGV No "	create core image" "	segmentation violation"
161.It Dv SIGSYS No "	create core image" "	non-existent system call invoked"
162.It Dv SIGPIPE No "	terminate process" "	write on a pipe with no reader"
163.It Dv SIGALRM No "	terminate process" "	real-time timer expired"
164.It Dv SIGTERM No "	terminate process" "	software termination signal"
165.It Dv SIGURG No "	discard signal" "	urgent condition present on socket"
166.It Dv SIGSTOP No "	stop process" "	stop (cannot be caught or ignored)"
167.It Dv SIGTSTP No "	stop process" "	stop signal generated from keyboard"
168.It Dv SIGCONT No "	discard signal" "	continue after stop"
169.It Dv SIGCHLD No "	discard signal" "	child status has changed"
170.It Dv SIGTTIN No "	stop process" "	background read attempted from control terminal"
171.It Dv SIGTTOU No "	stop process" "	background write attempted to control terminal"
172.It Dv SIGIO No "	discard signal" Tn "	I/O"
173is possible on a descriptor (see
174.Xr fcntl 2 )
175.It Dv SIGXCPU No "	terminate process" "	cpu time limit exceeded (see"
176.Xr setrlimit 2 )
177.It Dv SIGXFSZ No "	terminate process" "	file size limit exceeded (see"
178.Xr setrlimit 2 )
179.It Dv SIGVTALRM No "	terminate process" "	virtual time alarm (see"
180.Xr setitimer 2 )
181.It Dv SIGPROF No "	terminate process" "	profiling timer alarm (see"
182.Xr setitimer 2 )
183.It Dv SIGWINCH No "	discard signal" "	Window size change"
184.It Dv SIGINFO No "	discard signal" "	status request from keyboard"
185.It Dv SIGUSR1 No "	terminate process" "	User defined signal 1"
186.It Dv SIGUSR2 No "	terminate process" "	User defined signal 2"
187.El
188.Pp
189Once a signal handler is installed, it remains installed
190until another
191.Fn sigvec
192call is made, or an
193.Xr execve 2
194is performed.
195A signal-specific default action may be reset by
196setting
197.Fa sv_handler
198to
199.Dv SIG_DFL .
200The defaults are process termination, possibly with core dump;
201no action; stopping the process; or continuing the process.
202See the above signal list for each signal's default action.
203If
204.Fa sv_handler
205is
206.Dv SIG_IGN
207current and pending instances
208of the signal are ignored and discarded.
209.Pp
210If a signal is caught during the system calls listed below,
211the call is normally restarted.
212The call can be forced to terminate prematurely with an
213.Er EINTR
214error return by setting the
215.Dv SV_INTERRUPT
216bit in
217.Fa sv_flags .
218The affected system calls include
219.Xr read 2 ,
220.Xr write 2 ,
221.Xr sendto 2 ,
222.Xr recvfrom 2 ,
223.Xr sendmsg 2
224and
225.Xr recvmsg 2
226on a communications channel or a slow device (such as a terminal,
227but not a regular file)
228and during a
229.Xr wait 2
230or
231.Xr ioctl 2 .
232However, calls that have already committed are not restarted,
233but instead return a partial success (for example, a short read count).
234.Pp
235After a
236.Xr fork 2
237or
238.Xr vfork 2
239all signals, the signal mask, the signal stack,
240and the restart/interrupt flags are inherited by the child.
241.Pp
242The
243.Xr execve 2
244system call reinstates the default
245action for all signals which were caught and
246resets all signals to be caught on the user stack.
247Ignored signals remain ignored;
248the signal mask remains the same;
249signals that interrupt system calls continue to do so.
250.Sh NOTES
251The mask specified in
252.Fa vec
253is not allowed to block
254.Dv SIGKILL
255or
256.Dv SIGSTOP .
257This is done silently by the system.
258.Pp
259The
260.Dv SV_INTERRUPT
261flag is not available in
262.Bx 4.2 ,
263hence it should not be used if backward compatibility is needed.
264.Sh RETURN VALUES
265.Rv -std sigvec
266.Sh EXAMPLES
267On the
268.Tn VAX\-11
269The handler routine can be declared:
270.Bd -literal -offset indent
271void handler(sig, code, scp)
272int sig, code;
273struct sigcontext *scp;
274.Ed
275.Pp
276Here
277.Fa sig
278is the signal number, into which the hardware faults and traps are
279mapped as defined below.
280The
281.Fa code
282argument
283is either a constant
284as given below or, for compatibility mode faults, the code provided by
285the hardware (Compatibility mode faults are distinguished from the
286other
287.Dv SIGILL
288traps by having
289.Dv PSL_CM
290set in the psl).
291The
292.Fa scp
293argument
294is a pointer to the
295.Fa sigcontext
296structure (defined in
297.In signal.h ) ,
298used to restore the context from before the signal.
299.Sh ERRORS
300The
301.Fn sigvec
302function
303will fail and no new signal handler will be installed if one
304of the following occurs:
305.Bl -tag -width Er
306.It Bq Er EFAULT
307Either
308.Fa vec
309or
310.Fa ovec
311points to memory that is not a valid part of the process
312address space.
313.It Bq Er EINVAL
314The
315.Fa sig
316argument
317is not a valid signal number.
318.It Bq Er EINVAL
319An attempt is made to ignore or supply a handler for
320.Dv SIGKILL
321or
322.Dv SIGSTOP .
323.El
324.Sh SEE ALSO
325.Xr kill 1 ,
326.Xr kill 2 ,
327.Xr ptrace 2 ,
328.Xr sigaction 2 ,
329.Xr sigaltstack 2 ,
330.Xr sigblock 2 ,
331.Xr sigpause 2 ,
332.Xr sigprocmask 2 ,
333.Xr sigsetmask 2 ,
334.Xr sigsuspend 2 ,
335.Xr setjmp 3 ,
336.Xr siginterrupt 3 ,
337.Xr signal 3 ,
338.Xr sigsetops 3 ,
339.Xr tty 4
340.Sh HISTORY
341A
342.Fn sigvec
343system call first appeared in
344.Bx 4.2 .
345It was reimplemented as a wrapper around
346.Xr sigaction 2
347in
348.Bx 4.3 Reno .
349.Sh BUGS
350This manual page is still confusing.
351