1.\" $NetBSD: sigvec.3,v 1.23 2003/08/07 16:42:40 agc 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 November 1, 1997 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 43struct 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 53This interface is made obsolete by 54.Xr sigaction 2 . 55.Ef 56.Pp 57The system defines a set of signals that may be delivered to a process. 58Signal delivery resembles the occurrence of a hardware interrupt: 59the signal is blocked from further occurrence, the current process 60context is saved, and a new one is built. 61A process may specify a 62.Em handler 63to which a signal is delivered, or specify that a signal is to be 64.Em ignored . 65A process may also specify that a default action is to be taken 66by the system when a signal occurs. 67A signal may also be 68.Em blocked , 69in which case its delivery is postponed until it is 70.Em unblocked . 71The action to be taken on delivery is determined at the time 72of delivery. 73Normally, signal handlers execute on the current stack 74of the process. 75This may be changed, on a per-handler basis, so that signals are 76taken on a special 77.Em "signal stack" . 78.Pp 79Signal routines execute with the signal that caused their 80invocation 81.Em blocked , 82but other signals may yet occur. 83A global 84.Em "signal mask" 85defines the set of signals currently blocked from delivery 86to a process. 87The signal mask for a process is initialized from that of its parent 88(normally 0). 89It may be changed with a 90.Xr sigblock 3 91or 92.Xr sigsetmask 3 93call, or when a signal is delivered to the process. 94.Pp 95When a signal 96condition arises for a process, the signal is added to a set of 97signals pending for the process. 98If the signal is not currently 99.Em blocked 100by the process then it is delivered to the process. 101When a caught signal 102is delivered, the current state of the process is saved, 103a new signal mask is calculated (as described below), 104and the signal handler is invoked. 105The call to the handler is arranged so that if the signal handling 106routine returns normally the process will resume execution in the 107context from before the signal's delivery. 108If the process wishes to resume in a different context, then it 109must arrange to restore the previous context itself. 110.Pp 111When a signal is delivered to a process a new signal mask is 112installed for the duration of the process' signal handler 113(or until a 114.Xr sigblock 3 115or 116.Xr sigsetmask 3 117call is made). 118This mask is formed by taking the union of the current signal mask, 119the signal to be delivered, and 120the signal mask associated with the handler to be invoked. 121.Pp 122.Fn sigvec 123assigns a handler for a specific signal. 124If 125.Fa vec 126is non-zero, it 127specifies an action 128.Pf ( Dv SIG_DFL , 129.Dv SIG_IGN , 130or a handler routine) and mask 131to be used when delivering the specified signal. 132Further, if the 133.Dv SV_ONSTACK 134bit is set in 135.Fa sv_flags , 136the system will deliver the signal to the process on a 137.Em "signal stack" , 138specified with 139.Xr sigaltstack 2 . 140If 141.Fa ovec 142is non-zero, the previous handling information for the signal 143is returned to the user. 144.Pp 145Once a signal handler is installed, it remains installed 146until another 147.Fn sigvec 148call is made, or an 149.Xr execve 2 150is performed. 151A signal-specific default action may be reset by 152setting 153.Fa sv_handler 154to 155.Dv SIG_DFL . 156The defaults are process termination, possibly with core dump; 157no action; stopping the process; or continuing the process. 158See the signal list below for each signal's default action. 159If 160.Fa sv_handler 161is set to 162.Dv SIG_DFL , 163the default action for the signal is to discard the signal, 164and if a signal is pending, 165the pending signal is discarded even if the signal is masked. 166If 167.Fa sv_handler 168is set to 169.Dv SIG_IGN , 170current and pending instances 171of the signal are ignored and discarded. 172.Pp 173Options may be specified by setting 174.Em sv_flags . 175If the 176.Dv SV_ONSTACK 177bit is set in 178.Fa sv_flags , 179the system will deliver the signal to the process on a 180.Em "signal stack" , 181specified with 182.Xr sigstack 2 . 183.Pp 184If a signal is caught during the system calls listed below, 185the call may be restarted, 186the call may return with a data transfer shorter than requested, 187or the call may be forced to terminate 188with the error 189.Dv EINTR . 190Interrupting of pending calls is requested 191by setting the 192.Dv SV_INTERRUPT 193bit in 194.Ar sv_flags . 195The affected system calls include 196.Xr open 2 , 197.Xr read 2 , 198.Xr write 2 , 199.Xr sendto 2 , 200.Xr recvfrom 2 , 201.Xr sendmsg 2 202and 203.Xr recvmsg 2 204on a communications channel or a slow device (such as a terminal, 205but not a regular file) 206and during a 207.Xr wait 2 208or 209.Xr ioctl 2 . 210However, calls that have already committed are not restarted, 211but instead return a partial success (for example, a short read count). 212.Pp 213After a 214.Xr fork 2 215or 216.Xr vfork 2 217all signals, the signal mask, the signal stack, 218and the interrupt/restart flags are inherited by the child. 219.Pp 220The 221.Xr execve 2 222system call reinstates the default action for all signals which 223were caught and resets all signals to be caught on the user stack. 224Ignored signals remain ignored; 225the signal mask remains the same; 226signals that interrupt pending system calls continue to do so. 227.Pp 228See 229.Xr signal 7 230for comprehensive list of supported signals. 231.Sh NOTES 232The mask specified in 233.Fa vec 234is not allowed to block 235.Dv SIGKILL 236or 237.Dv SIGSTOP . 238This is enforced silently by the system. 239.Pp 240The 241.Dv SV_INTERRUPT 242flag is not available in 243.Bx 4.2 , 244hence it should not be used if backward compatibility is needed. 245.Sh RETURN VALUES 246A 0 value indicated that the call succeeded. 247A \-1 return value indicates an error occurred and 248.Va errno 249is set to indicated the reason. 250.Sh EXAMPLES 251The handler routine can be declared: 252.Bd -literal -offset indent 253void 254handler(sig, code, scp) 255 int sig, code; 256 struct sigcontext *scp; 257.Ed 258.Pp 259Here 260.Fa sig 261is the signal number, into which the hardware faults and traps are 262mapped as defined below. 263.Fa code 264is a parameter that is either a constant 265or the code provided by the hardware. 266.Fa scp 267is a pointer to the 268.Fa sigcontext 269structure (defined in 270.Aq Pa signal.h ) , 271used to restore the context from before the signal. 272.Sh ERRORS 273.Fn sigvec 274will fail and no new signal handler will be installed if one 275of the following occurs: 276.Bl -tag -width Er 277.It Bq Er EFAULT 278Either 279.Fa vec 280or 281.Fa ovec 282points to memory that is not a valid part of the process 283address space. 284.It Bq Er EINVAL 285.Fa sig 286is not a valid signal number. 287.It Bq Er EINVAL 288An attempt is made to ignore or supply a handler for 289.Dv SIGKILL 290or 291.Dv SIGSTOP . 292.El 293.Sh SEE ALSO 294.Xr kill 1 , 295.Xr kill 2 , 296.Xr ptrace 2 , 297.Xr sigaction 2 , 298.Xr sigaltstack 2 , 299.Xr sigprocmask 2 , 300.Xr sigstack 2 , 301.Xr sigsuspend 2 , 302.Xr setjmp 3 , 303.Xr sigblock 3 , 304.Xr siginterrupt 3 , 305.Xr signal 3 , 306.Xr sigpause 3 , 307.Xr sigsetmask 3 , 308.Xr sigsetops 3 , 309.Xr tty 4 , 310.Xr signal 7 311