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