1.\" $NetBSD: sigaction.2,v 1.45 2014/01/04 15:54:27 wiz 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. 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.\" @(#)sigaction.2 8.2 (Berkeley) 4/3/94 31.\" 32.Dd June 3, 2006 33.Dt SIGACTION 2 34.Os 35.Sh NAME 36.Nm sigaction 37.Nd software signal facilities 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In signal.h 42.Ft int 43.Fn sigaction "int sig" "const struct sigaction * restrict act" "struct sigaction * restrict oact" 44.Sh DESCRIPTION 45The system defines a set of signals that may be delivered to a process. 46Signal delivery resembles the occurrence of a hardware interrupt: 47the signal is blocked from further occurrence, the current process 48context is saved, and a new one is built. 49A process may specify a 50.Em handler 51to which a signal is delivered, or specify that a signal is to be 52.Em ignored . 53A process may also specify that a default action is to be taken 54by the system when a signal occurs. 55A signal may also be 56.Em blocked , 57in which case its delivery is postponed until it is 58.Em unblocked . 59The action to be taken on delivery is determined at the time of delivery. 60Normally, signal handlers execute on the current stack of the process. 61This may be changed, on a per-handler basis, so that signals are 62taken on a special 63.Em "signal stack" . 64.Pp 65Signal routines execute with the signal that caused their 66invocation 67.Em blocked , 68but other signals may yet occur. 69A global 70.Em "signal mask" 71defines the set of signals currently blocked from delivery 72to a process. 73The signal mask for a process is initialized from that of its parent 74(normally empty). 75It may be changed with a 76.Xr sigprocmask 2 77call, or when a signal is delivered to the process. 78Signal masks are represented using the 79.Em sigset_t 80type; the 81.Xr sigsetops 3 82interface is used to modify such data. 83.Pp 84When a signal 85condition arises for a process, the signal is added to a set of 86signals pending for the process. 87If the signal is not currently 88.Em blocked 89by the process then it is delivered to the process. 90Signals may be delivered any time a process enters the operating system 91(e.g., during a system call, page fault or trap, or clock interrupt). 92If multiple signals are ready to be delivered at the same time, 93any signals that could be caused by traps are delivered first. 94Additional signals may be processed at the same time, with each 95appearing to interrupt the handlers for the previous signals 96before their first instructions. 97The set of pending signals is returned by the 98.Xr sigpending 2 99function. 100When a caught signal 101is delivered, the current state of the process is saved, 102a new signal mask is calculated (as described below), 103and the signal handler is invoked. 104The call to the handler is arranged so that if the signal handling 105routine returns normally the process will resume execution in the 106context from 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 110.Em "struct sigaction" 111includes the following members: 112.Bd -literal -offset indent 113void (*sa_sigaction)(int sig, siginfo_t *info, void *ctx); 114void (*sa_handler)(int sig); 115sigset_t sa_mask; 116int sa_flags; 117.Ed 118.Pp 119When a signal is delivered to a process a new signal mask is 120installed for the duration of the process' signal handler 121(or until a 122.Xr sigprocmask 2 123call is made). 124This mask is formed by taking the union of the current signal mask, 125the signal to be delivered, and 126the signal mask associated with the handler to be invoked, 127.Em sa_mask . 128.Pp 129.Fn sigaction 130assigns an action for a specific signal. 131If 132.Fa act 133is non-zero, it 134specifies an action 135.Pf ( Dv SIG_DFL , 136.Dv SIG_IGN , 137or a handler routine) and mask 138to be used when delivering the specified signal. 139If 140.Fa oact 141is non-zero, the previous handling information for the signal 142is returned to the user. 143.Pp 144Once a signal handler is installed, it remains installed 145until another 146.Fn sigaction 147call is made, or an 148.Xr execve 2 149is performed. 150A signal-specific default action may be reset by 151setting 152.Fa sa_handler 153to 154.Dv SIG_DFL . 155The defaults are process termination, possibly with core dump; 156no action; stopping the process; or continuing the process. 157See the signal list below for each signal's default action. 158If 159.Fa sa_handler 160is set to 161.Dv SIG_DFL , 162the default action for the signal is to discard the signal, 163and if a signal is pending, 164the pending signal is discarded even if the signal is masked. 165If 166.Fa sa_handler 167is set to 168.Dv SIG_IGN , 169current and pending instances 170of the signal are ignored and discarded. 171.Pp 172Options may be specified by setting 173.Em sa_flags . 174.Bl -tag -width SA_NOKERNINFO 175.It Dv SA_NODEFER 176If set, then the signal that caused the handler to be executed is not added 177to the list of block signals. 178Please note that 179.Fa sa_mask 180takes precedence over 181.Dv SA_NODEFER , 182so that if the specified signal is blocked in 183.Fa sa_mask , 184then 185.Dv SA_NODEFER 186will have no effect. 187.It Dv SA_NOCLDSTOP 188If set when installing a catching function 189for the 190.Dv SIGCHLD 191signal, 192the 193.Dv SIGCHLD 194signal will be generated only when a child process exits, 195not when a child process stops. 196.It Dv SA_NOCLDWAIT 197If set, the system will not create a zombie when the child exits, 198but the child process will be automatically waited for. 199The same effect can be achieved by setting the signal handler for 200.Dv SIGCHLD 201to 202.Dv SIG_IGN . 203.It Dv SA_ONSTACK 204If set, the system will deliver the signal to the process on a 205.Em "signal stack" , 206specified with 207.Xr sigaltstack 2 . 208.It Dv SA_RESETHAND 209If set, the default action will be reinstated when the signal 210is first posted. 211.It Dv SA_RESTART 212Normally, if a signal is caught during the system calls listed below, 213the call may be forced to terminate 214with the error 215.Er EINTR , 216the call may return with a data transfer shorter than requested, 217or the call may be restarted. 218Restarting of pending calls is requested 219by setting the 220.Dv SA_RESTART 221bit in 222.Ar sa_flags . 223The affected system calls include 224.Xr open 2 , 225.Xr read 2 , 226.Xr write 2 , 227.Xr sendto 2 , 228.Xr recvfrom 2 , 229.Xr sendmsg 2 230and 231.Xr recvmsg 2 232on a communications channel or a slow device (such as a terminal, 233but not a regular file) 234and during a 235.Xr wait 2 236or 237.Xr ioctl 2 . 238However, calls that have already committed are not restarted, 239but instead return a partial success (for example, a short read count). 240.Pp 241After a 242.Xr fork 2 243or 244.Xr vfork 2 245all signals, the signal mask, the signal stack, 246and the restart/interrupt flags are inherited by the child. 247.Pp 248The 249.Xr execve 2 250system call reinstates the default 251action for all signals which were caught and 252resets all signals to be caught on the user stack. 253Ignored signals remain ignored; 254the signal mask remains the same; 255signals that restart pending system calls continue to do so. 256.Pp 257See 258.Xr signal 7 259for comprehensive list of supported signals. 260.It Dv SA_SIGINFO 261If set, the signal handler function will receive additional information 262about the caught signal. 263An alternative handler that gets passed additional arguments will 264be called which is named 265.Fa sa_sigaction . 266The 267.Ar sig 268argument of this handler contains the signal number that was caught. 269The 270.Ar info 271argument contains additional signal specific information which 272is listed in 273.Xr siginfo 2 . 274The 275.Ar ctx 276argument 277is a pointer to the 278.Xr ucontext 2 279context where the signal handler will return to. 280.It Dv SA_NOKERNINFO 281This flag is relevant only to 282.Dv SIGINFO , 283and turns off printing kernel messages on the tty. 284It is similar to the 285.Dv NOKERNINFO 286flag in 287.Xr termios 4 . 288.El 289.Pp 290Only functions that are async-signal-safe can safely be used in signal 291handlers; see 292.Xr signal 7 293for a complete list. 294.Sh NOTES 295The mask specified in 296.Fa act 297is not allowed to block 298.Dv SIGKILL 299or 300.Dv SIGSTOP . 301This is enforced silently by the system. 302.Sh RETURN VALUES 303A 0 value indicates that the call succeeded. 304A \-1 return value indicates an error occurred and 305.Va errno 306is set to indicate the reason. 307.Sh ERRORS 308.Fn sigaction 309will fail and no new signal handler will be installed if one 310of the following occurs: 311.Bl -tag -width Er 312.It Bq Er EFAULT 313Either 314.Fa act 315or 316.Fa oact 317points to memory that is not a valid part of the process 318address space. 319.It Bq Er EINVAL 320.Fa sig 321is not a valid signal number; 322or an attempt is made to ignore or supply a handler for 323.Dv SIGKILL 324or 325.Dv SIGSTOP ; 326or the 327.Em sa_flags 328word contains bits other than 329.Dv SA_NOCLDSTOP , 330.Dv SA_NOCLDWAIT , 331.Dv SA_NODEFER , 332.Dv SA_ONSTACK , 333.Dv SA_RESETHAND , 334.Dv SA_RESTART , 335and 336.Dv SA_SIGINFO . 337.El 338.Sh SEE ALSO 339.Xr kill 1 , 340.Xr kill 2 , 341.Xr ptrace 2 , 342.Xr sigaltstack 2 , 343.Xr siginfo 2 , 344.Xr sigprocmask 2 , 345.Xr sigsuspend 2 , 346.Xr setjmp 3 , 347.Xr sigsetops 3 , 348.Xr tty 4 , 349.Xr signal 7 350.Sh STANDARDS 351The 352.Fn sigaction 353function conforms to 354.St -p1003.1-90 . 355The 356.Dv SA_ONSTACK 357and 358.Dv SA_RESTART 359flags are Berkeley extensions, available on most 360.Bx Ns \-derived 361systems. 362