1.\" $NetBSD: sigaction.2,v 1.27 2002/02/08 01:28:22 ross Exp $ 2.\" 3.\" Copyright (c) 1980, 1990, 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.\" @(#)sigaction.2 8.2 (Berkeley) 4/3/94 35.\" 36.Dd November 1, 1997 37.Dt SIGACTION 2 38.Os 39.Sh NAME 40.Nm sigaction 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 sigaction { 48 void (*sa_handler)(int); 49 sigset_t sa_mask; 50 int sa_flags; 51 void (*sa_sigaction)(int, siginfo_t *, void *); 52}; 53.Ed 54.Ft int 55.Fn sigaction "int sig" "const struct sigaction *act" "struct sigaction *oact" 56.Sh DESCRIPTION 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 of delivery. 72Normally, signal handlers execute on the current stack of the process. 73This may be changed, on a per-handler basis, so that signals are 74taken on a special 75.Em "signal stack" . 76.Pp 77Signal routines execute with the signal that caused their 78invocation 79.Em blocked , 80but other signals may yet occur. 81A global 82.Em "signal mask" 83defines the set of signals currently blocked from delivery 84to a process. 85The signal mask for a process is initialized from that of its parent 86(normally empty). 87It may be changed with a 88.Xr sigprocmask 2 89call, or when a signal is delivered to the process. 90.Pp 91When a signal 92condition arises for a process, the signal is added to a set of 93signals pending for the process. 94If the signal is not currently 95.Em blocked 96by the process then it is delivered to the process. 97Signals may be delivered any time a process enters the operating system 98(e.g., during a system call, page fault or trap, or clock interrupt). 99If multiple signals are ready to be delivered at the same time, 100any signals that could be caused by traps are delivered first. 101Additional signals may be processed at the same time, with each 102appearing to interrupt the handlers for the previous signals 103before their first instructions. 104The set of pending signals is returned by the 105.Xr sigpending 2 106function. 107When a caught signal 108is delivered, the current state of the process is saved, 109a new signal mask is calculated (as described below), 110and the signal handler is invoked. 111The call to the handler is arranged so that if the signal handling 112routine returns normally the process will resume execution in the 113context from before the signal's delivery. 114If the process wishes to resume in a different context, then it 115must arrange to restore the previous context itself. 116.Pp 117When a signal is delivered to a process a new signal mask is 118installed for the duration of the process' signal handler 119(or until a 120.Xr sigprocmask 2 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.Em sa_mask . 126.Pp 127.Fn sigaction 128assigns an action for a specific signal. 129If 130.Fa act 131is non-zero, it 132specifies an action 133.Pf ( Dv SIG_DFL , 134.Dv SIG_IGN , 135or a handler routine) and mask 136to be used when delivering the specified signal. 137If 138.Fa oact 139is non-zero, the previous handling information for the signal 140is returned to the user. 141.Pp 142Once a signal handler is installed, it remains installed 143until another 144.Fn sigaction 145call is made, or an 146.Xr execve 2 147is performed. 148A signal-specific default action may be reset by 149setting 150.Fa sa_handler 151to 152.Dv SIG_DFL . 153Alternately, if the 154.Dv SA_RESETHAND 155bit is set the default action will be reinstated when the signal 156is first posted. 157The defaults are process termination, possibly with core dump; 158no action; stopping the process; or continuing the process. 159See the signal list below for each signal's default action. 160If 161.Fa sa_handler 162is set to 163.Dv SIG_DFL , 164the default action for the signal is to discard the signal, 165and if a signal is pending, 166the pending signal is discarded even if the signal is masked. 167If 168.Fa sa_handler 169is set to 170.Dv SIG_IGN , 171current and pending instances 172of the signal are ignored and discarded. 173.Pp 174Options may be specified by setting 175.Em sa_flags . 176If the 177.Dv SA_NOCLDSTOP 178bit is set when installing a catching function 179for the 180.Dv SIGCHLD 181signal, 182the 183.Dv SIGCHLD 184signal will be generated only when a child process exits, 185not when a child process stops. 186Further, if the 187.Dv SA_ONSTACK 188bit is set in 189.Em sa_flags , 190the system will deliver the signal to the process on a 191.Em "signal stack" , 192specified with 193.Xr sigaltstack 2 . 194Finally, if the 195.Dv SA_NOCLDWAIT 196bit is set in 197.Em sa_flags , 198the system will not create a zombie when the child exits, but the child 199process will be automatically waited for. 200.Pp 201If a signal is caught during the system calls listed below, 202the call may be forced to terminate 203with the error 204.Er EINTR , 205the call may return with a data transfer shorter than requested, 206or the call may be restarted. 207Restarting of pending calls is requested 208by setting the 209.Dv SA_RESTART 210bit in 211.Ar sa_flags . 212The affected system calls include 213.Xr open 2 , 214.Xr read 2 , 215.Xr write 2 , 216.Xr sendto 2 , 217.Xr recvfrom 2 , 218.Xr sendmsg 2 219and 220.Xr recvmsg 2 221on a communications channel or a slow device (such as a terminal, 222but not a regular file) 223and during a 224.Xr wait 2 225or 226.Xr ioctl 2 . 227However, calls that have already committed are not restarted, 228but instead return a partial success (for example, a short read count). 229.Pp 230After a 231.Xr fork 2 232or 233.Xr vfork 2 234all signals, the signal mask, the signal stack, 235and the restart/interrupt flags are inherited by the child. 236.Pp 237The 238.Xr execve 2 239system call reinstates the default 240action for all signals which were caught and 241resets all signals to be caught on the user stack. 242Ignored signals remain ignored; 243the signal mask remains the same; 244signals that restart pending system calls continue to do so. 245.Pp 246See 247.Xr signal 7 248for comprehensive list of supported signals. 249.Sh NOTES 250The mask specified in 251.Fa act 252is not allowed to block 253.Dv SIGKILL 254or 255.Dv SIGSTOP . 256This is enforced silently by the system. 257.Sh RETURN VALUES 258A 0 value indicates that the call succeeded. 259A \-1 return value indicates an error occurred and 260.Va errno 261is set to indicate the reason. 262.Sh EXAMPLES 263The handler routine can be declared: 264.Bd -literal -offset indent 265void 266handler(sig, code, scp) 267 int sig, code; 268 struct sigcontext *scp; 269.Ed 270.Pp 271Here 272.Fa sig 273is the signal number, into which the hardware faults and traps are 274mapped. 275.Fa code 276is a parameter that is either a constant 277or the code provided by the hardware. 278.Fa scp 279is a pointer to the 280.Fa sigcontext 281structure (defined in 282.Aq Pa signal.h ) , 283used to restore the context from before the signal. 284.Pp 285For POSIX compliance, the 286.Fa sa_handler 287is declared to be (void (*)(int)) and the above handler will need to be 288casted to that type. 289Future versions of 290.Nx 291will replace the 292.Fa sigcontext 293interface with the 294.Fa siginfo 295interface. 296.Sh ERRORS 297.Fn sigaction 298will fail and no new signal handler will be installed if one 299of the following occurs: 300.Bl -tag -width Er 301.It Bq Er EFAULT 302Either 303.Fa act 304or 305.Fa oact 306points to memory that is not a valid part of the process 307address space. 308.It Bq Er EINVAL 309.Fa sig 310is not a valid signal number. 311.It Bq Er EINVAL 312An attempt is made to ignore or supply a handler for 313.Dv SIGKILL 314or 315.Dv SIGSTOP . 316.El 317.Sh SEE ALSO 318.Xr kill 1 , 319.Xr kill 2 , 320.Xr ptrace 2 , 321.Xr sigaltstack 2 , 322.Xr sigprocmask 2 , 323.Xr sigsuspend 2 , 324.Xr setjmp 3 , 325.Xr sigsetops 3 , 326.Xr tty 4 , 327.Xr signal 7 328.Sh STANDARDS 329The 330.Fn sigaction 331function conforms to 332.St -p1003.1-90 . 333The 334.Dv SA_ONSTACK 335and 336.Dv SA_RESTART 337flags are Berkeley extensions, available on most 338.Bx Ns \-derived 339systems. 340