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