1.\" $NetBSD: sigaction.2,v 1.40 2004/06/13 19:17:06 lha 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 13, 2004 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 *act" "struct sigaction *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_NOCLDSTOP 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. 199.It Dv SA_ONSTACK 200If set, the system will deliver the signal to the process on a 201.Em "signal stack" , 202specified with 203.Xr sigaltstack 2 . 204.It Dv SA_RESETHAND 205If set, the default action will be reinstated when the signal 206is first posted. 207.It Dv SA_RESTART 208Normally, if a signal is caught during the system calls listed below, 209the call may be forced to terminate 210with the error 211.Er EINTR , 212the call may return with a data transfer shorter than requested, 213or the call may be restarted. 214Restarting of pending calls is requested 215by setting the 216.Dv SA_RESTART 217bit in 218.Ar sa_flags . 219The affected system calls include 220.Xr open 2 , 221.Xr read 2 , 222.Xr write 2 , 223.Xr sendto 2 , 224.Xr recvfrom 2 , 225.Xr sendmsg 2 226and 227.Xr recvmsg 2 228on a communications channel or a slow device (such as a terminal, 229but not a regular file) 230and during a 231.Xr wait 2 232or 233.Xr ioctl 2 . 234However, calls that have already committed are not restarted, 235but instead return a partial success (for example, a short read count). 236.Pp 237After a 238.Xr fork 2 239or 240.Xr vfork 2 241all signals, the signal mask, the signal stack, 242and the restart/interrupt flags are inherited by the child. 243.Pp 244The 245.Xr execve 2 246system call reinstates the default 247action for all signals which were caught and 248resets all signals to be caught on the user stack. 249Ignored signals remain ignored; 250the signal mask remains the same; 251signals that restart pending system calls continue to do so. 252.Pp 253See 254.Xr signal 7 255for comprehensive list of supported signals. 256.It Dv SA_SIGINFO 257If set, the signal handler function will receive additional information 258about the caught signal. 259An alternative handler that gets passed additional arguments will 260be called which is named 261.Fa sa_sigaction . 262The 263.Ar sig 264argument of this handler contains the signal number that was caught. 265The 266.Ar info 267argument contains additional signal specific information which 268is listed in 269.Xr siginfo 2 . 270The 271.Ar ctx 272argument 273is a pointer to the 274.Xr ucontext 2 275context where the signal handler will return to. 276.El 277.Pp 278Only functions that are async-signal-safe can safely be used in signal 279handlers, see 280.Xr signal 7 281for a complete list. 282.Sh NOTES 283The mask specified in 284.Fa act 285is not allowed to block 286.Dv SIGKILL 287or 288.Dv SIGSTOP . 289This is enforced silently by the system. 290.Sh RETURN VALUES 291A 0 value indicates that the call succeeded. 292A \-1 return value indicates an error occurred and 293.Va errno 294is set to indicate the reason. 295.Sh ERRORS 296.Fn sigaction 297will fail and no new signal handler will be installed if one 298of the following occurs: 299.Bl -tag -width Er 300.It Bq Er EFAULT 301Either 302.Fa act 303or 304.Fa oact 305points to memory that is not a valid part of the process 306address space. 307.It Bq Er EINVAL 308.Fa sig 309is not a valid signal number. 310.It Bq Er EINVAL 311An attempt is made to ignore or supply a handler for 312.Dv SIGKILL 313or 314.Dv SIGSTOP . 315.It Bq Er EINVAL 316The 317.Em sa_flags 318word contains bits other than 319.Dv SA_NOCLDSTOP , 320.Dv SA_NOCLDWAIT , 321.Dv SA_NODEFER , 322.Dv SA_ONSTACK , 323.Dv SA_RESETHAND , 324.Dv SA_RESTART , 325and 326.Dv SA_SIGINFO . 327.El 328.Sh SEE ALSO 329.Xr kill 1 , 330.Xr kill 2 , 331.Xr ptrace 2 , 332.Xr sigaltstack 2 , 333.Xr siginfo 2 , 334.Xr sigprocmask 2 , 335.Xr sigsuspend 2 , 336.Xr setjmp 3 , 337.Xr sigsetops 3 , 338.Xr tty 4 , 339.Xr signal 7 340.Sh STANDARDS 341The 342.Fn sigaction 343function conforms to 344.St -p1003.1-90 . 345The 346.Dv SA_ONSTACK 347and 348.Dv SA_RESTART 349flags are Berkeley extensions, available on most 350.Bx Ns \-derived 351systems. 352