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