1.\" Copyright (c) 1980, 1991 The Regents of the University of California. 2.\" 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.\" $OpenBSD: sigvec.3,v 1.37 2022/10/13 21:37:05 jmc Exp $ 29.\" 30.Dd $Mdocdate: October 13 2022 $ 31.Dt SIGVEC 3 32.Os 33.Sh NAME 34.Nm sigvec 35.Nd software signal facilities 36.Sh SYNOPSIS 37.In signal.h 38.Bd -literal 39struct sigvec { 40 void (*sv_handler)(); 41 int sv_mask; 42 int sv_flags; 43}; 44.Ed 45.Ft int 46.Fn sigvec "int sig" "struct sigvec *vec" "struct sigvec *ovec" 47.Sh DESCRIPTION 48.Bf -symbolic 49This interface is made obsolete by 50.Xr sigaction 2 . 51.Ef 52.Pp 53The system defines a set of signals that may be delivered to a process. 54Signal delivery resembles the occurrence of a hardware interrupt: 55the signal is blocked from further occurrence, the current process 56context is saved, and a new one is built. 57A process may specify a 58.Em handler 59to which a signal is delivered, or specify that a signal is to be 60.Em blocked 61or 62.Em ignored . 63A process may also specify that a default action is to be taken 64by the system when a signal occurs. 65A signal may also be 66.Em blocked , 67in which case its delivery is postponed until it is 68.Em unblocked . 69The action to be taken on delivery is determined at the time 70of delivery. 71Normally, signal handlers execute on the current stack 72of the process. 73This may be changed, on a per-handler basis, 74so that signals are taken on a special 75.Em "signal stack" . 76.Pp 77All signals have the same 78.Em priority . 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 88from that of its parent (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 106is arranged so that if the signal handling routine returns 107normally the process will resume execution in the context 108from before the signal's delivery. 109If the process wishes to resume in a different context, then it 110must arrange to restore the previous context itself. 111.Pp 112When a signal is delivered to a process, a new signal mask is 113installed for the duration of the process' signal handler 114(or until a 115.Xr sigblock 3 116or 117.Xr sigsetmask 3 118call is made). 119This mask is formed by taking the union of the current signal mask, 120the signal to be delivered, and 121the signal mask associated with the handler to be invoked. 122.Pp 123.Fn sigvec 124assigns a handler for a specific signal. 125If 126.Fa vec 127is non-zero, it 128specifies an action 129.Pf ( Dv SIG_DFL , 130.Dv SIG_IGN , 131or a handler routine) and mask 132to be used when delivering the specified signal. 133If 134.Fa ovec 135is non-zero, the previous handling information for the signal 136is returned to the user. 137.Pp 138Once a signal handler is installed, it remains installed 139until another 140.Fn sigvec 141call is made, or an 142.Xr execve 2 143is performed. 144A signal-specific default action may be reset by 145setting 146.Fa sv_handler 147to 148.Dv SIG_DFL . 149The defaults are process termination, possibly with core dump; 150no action; stopping the process; or continuing the process. 151See the signal list below for each signal's default action. 152If 153.Fa sv_handler 154is set to 155.Dv SIG_IGN , 156the default action for the signal is to discard the signal, 157and if a signal is pending, 158the pending signal is discarded even if the signal is masked. 159If 160.Fa sv_handler 161is set to 162.Dv SIG_IGN , 163current and pending instances 164of the signal are ignored and discarded. 165.Pp 166Options may be specified by setting 167.Em sv_flags . 168If the 169.Dv SV_ONSTACK 170bit is set in 171.Fa sv_flags , 172the system will deliver the signal to the process on a 173.Em "signal stack" , 174specified with 175.Xr sigaltstack 2 . 176.Pp 177If a signal is caught during the system calls listed below, 178the call may be restarted, 179the call may return with a data transfer shorter than requested, 180or the call may be forced to terminate 181with the error 182.Er EINTR . 183Interrupting of pending calls is requested 184by setting the 185.Dv SV_INTERRUPT 186bit in 187.Ar sv_flags . 188The affected system calls include 189.Xr open 2 , 190.Xr read 2 , 191.Xr write 2 , 192.Xr sendto 2 , 193.Xr recvfrom 2 , 194.Xr sendmsg 2 195and 196.Xr recvmsg 2 197on a communications channel or a slow device (such as a terminal, 198but not a regular file) 199and during a 200.Xr wait 2 201or 202.Xr ioctl 2 . 203However, calls that have already committed are not restarted, 204but instead return a partial success (for example, a short read count). 205.Pp 206After a 207.Xr fork 2 208or 209.Xr vfork 2 210all signals, the signal mask, the signal stack, 211and the interrupt/restart flags are inherited by the child. 212.Pp 213.Xr execve 2 214reinstates the default 215action for all signals which were caught and 216resets all signals to be caught on the user stack. 217Ignored signals remain ignored; 218the signal mask remains the same; 219signals that interrupt pending system calls continue to do so. 220.Pp 221The following is a list of all signals 222with names as in the include file 223.In signal.h : 224.Bl -column "SIGVTALRM" "create core image" "terminal line hangup" 225.It Sy "Name" Ta Sy "Default Action" Ta Sy "Description" 226.It Dv SIGHUP Ta "terminate process" Ta "terminal line hangup" 227.It Dv SIGINT Ta "terminate process" Ta "interrupt program" 228.It Dv SIGQUIT Ta "create core image" Ta "quit program" 229.It Dv SIGILL Ta "create core image" Ta "illegal instruction" 230.It Dv SIGTRAP Ta "create core image" Ta "trace trap" 231.It Dv SIGABRT Ta "create core image" Ta "abort(3) call (formerly SIGIOT)" 232.It Dv SIGEMT Ta "create core image" Ta "emulate instruction executed" 233.It Dv SIGFPE Ta "create core image" Ta "floating-point exception" 234.It Dv SIGKILL Ta "terminate process" Ta "kill program (cannot be caught or ignored)" 235.It Dv SIGBUS Ta "create core image" Ta "bus error" 236.It Dv SIGSEGV Ta "create core image" Ta "segmentation violation" 237.It Dv SIGSYS Ta "create core image" Ta "system call given invalid argument" 238.It Dv SIGPIPE Ta "terminate process" Ta "write on a pipe with no reader" 239.It Dv SIGALRM Ta "terminate process" Ta "real-time timer expired" 240.It Dv SIGTERM Ta "terminate process" Ta "software termination signal" 241.It Dv SIGURG Ta "discard signal" Ta "urgent condition present on socket" 242.It Dv SIGSTOP Ta "stop process" Ta "stop (cannot be caught or ignored)" 243.It Dv SIGTSTP Ta "stop process" Ta "stop signal generated from keyboard" 244.It Dv SIGCONT Ta "discard signal" Ta "continue after stop" 245.It Dv SIGCHLD Ta "discard signal" Ta "child status has changed" 246.It Dv SIGTTIN Ta "stop process" Ta "background read attempted from controlling terminal" 247.It Dv SIGTTOU Ta "stop process" Ta "background write attempted to controlling terminal" 248.It Dv SIGIO Ta "discard signal" Ta "I/O is possible on a descriptor (see" 249.Xr fcntl 2 ) 250.It Dv SIGXCPU Ta "terminate process" Ta "CPU time limit exceeded (see" 251.Xr setrlimit 2 ) 252.It Dv SIGXFSZ Ta "terminate process" Ta "file size limit exceeded (see" 253.Xr setrlimit 2 ) 254.It Dv SIGVTALRM Ta "terminate process" Ta "virtual time alarm (see" 255.Xr setitimer 2 ) 256.It Dv SIGPROF Ta "terminate process" Ta "profiling timer alarm (see" 257.Xr setitimer 2 ) 258.It Dv SIGWINCH Ta "discard signal" Ta "window size change" 259.It Dv SIGINFO Ta "discard signal" Ta "status request from keyboard" 260.It Dv SIGUSR1 Ta "terminate process" Ta "user-defined signal 1" 261.It Dv SIGUSR2 Ta "terminate process" Ta "user-defined signal 2" 262.El 263.Sh NOTES 264The mask specified in 265.Fa vec 266is not allowed to block 267.Dv SIGKILL 268or 269.Dv SIGSTOP . 270This is enforced silently by the system. 271.Pp 272The 273.Dv SV_INTERRUPT 274flag is not available in 275.Bx 4.2 , 276hence it should not be used if backward compatibility is needed. 277.Sh RETURN VALUES 278A 0 value indicated that the call succeeded. 279A \-1 return value indicates an error occurred and 280.Va errno 281is set to indicated the reason. 282.Sh EXAMPLES 283For an example of signal handler declarations, see 284.Xr sigaction 2 . 285.Sh ERRORS 286.Fn sigvec 287will fail and no new signal handler will be installed if one 288of the following occurs: 289.Bl -tag -width Er 290.It Bq Er EFAULT 291Either 292.Fa vec 293or 294.Fa ovec 295points to memory that is not a valid part of the process 296address space. 297.It Bq Er EINVAL 298.Fa sig 299is not a valid signal number. 300.It Bq Er EINVAL 301An attempt is made to ignore or supply a handler for 302.Dv SIGKILL 303or 304.Dv SIGSTOP . 305.El 306.Sh SEE ALSO 307.Xr kill 1 , 308.Xr kill 2 , 309.Xr ptrace 2 , 310.Xr sigaction 2 , 311.Xr sigaltstack 2 , 312.Xr sigprocmask 2 , 313.Xr sigsuspend 2 , 314.Xr setjmp 3 , 315.Xr sigaddset 3 , 316.Xr sigblock 3 , 317.Xr siginterrupt 3 , 318.Xr sigpause 3 , 319.Xr sigsetmask 3 , 320.Xr tty 4 321.Sh HISTORY 322A 323.Fn sigvec 324system call first appeared in 325.Bx 4.2 . 326It was reimplemented as a wrapper around 327.Xr sigaction 2 328in 329.Bx 4.3 Reno . 330The old system call was kept for compatibility until 331.Ox 4.9 . 332