1.\" $NetBSD: sigaction.2,v 1.49 2016/07/25 22:00:36 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 July 9, 2016 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 290If the signal handler is called due to signal delively resulting from reasons 291other than direct calls to 292.Xr kill 2 293or 294.Xr _lwp_kill 2 295or indirect calls to 296.Xr _lwp_kill 2 297via 298.Xr abort 3 299or 300.Xr raise 3 301any activity (such as calling functions or assigning variables in the global 302or static scopes) other than setting a variable of the type 303.Vt volatile sig_atomic_t 304is undefined. 305.Ss Signal-safe functions 306Only functions that are guaranteed to be async-signal-safe can safely 307be used in signal handlers. 308These are functions that are either reentrant or non-interruptible. 309(These functions are also the only functions that may be used in a 310child process after doing 311.Xr fork 2 312in a threaded program.) 313.Pp 314The following functions are async-signal-safe. 315Any function not listed 316below is unsafe to use in signal handlers. 317.Pp 318.Xr _Exit 2 , 319.Xr _exit 2 , 320.Xr abort 3 , 321.Xr accept 2 , 322.Xr access 2 , 323.\" .Xr aio_error 324.\" .Xr aio_return 325.\" .Xr aio_suspend 326.Xr alarm 3 , 327.Xr bind 2 , 328.Xr cfgetispeed 3 , 329.Xr cfgetospeed 3 , 330.Xr cfsetispeed 3 , 331.Xr cfsetospeed 3 , 332.Xr chdir 2 , 333.Xr chmod 2 , 334.Xr chown 2 , 335.Xr clock_gettime 2 , 336.Xr close 2 , 337.Xr connect 2 , 338.Xr creat 3 , 339.Xr dup 2 , 340.Xr dup2 2 , 341.Xr execle 3 , 342.Xr execve 2 , 343.Xr fchmod 2 , 344.Xr fchown 2 , 345.Xr fcntl 2 , 346.Xr fdatasync 2 , 347.Xr fork 2 , 348.Xr fpathconf 2 , 349.Xr fstat 2 , 350.Xr fsync 2 , 351.Xr ftruncate 2 , 352.Xr getegid 2 , 353.Xr geteuid 2 , 354.Xr getgid 2 , 355.Xr getgroups 2 , 356.Xr getpeername 2 , 357.Xr getpgrp 2 , 358.Xr getpid 2 , 359.Xr getppid 2 , 360.Xr getsockname 2 , 361.Xr getsockopt 2 , 362.Xr getuid 2 , 363.Xr kill 2 , 364.Xr link 2 , 365.Xr listen 2 , 366.Xr lseek 2 , 367.Xr lstat 2 , 368.Xr mkdir 2 , 369.Xr mkfifo 2 , 370.Xr open 2 , 371.Xr pathconf 2 , 372.Xr pause 3 , 373.Xr pipe 2 , 374.Xr poll 2 , 375.\" .Xr posix_trace_event 2 376.\" .Xr pselect 2 377.Xr pthread_mutex_unlock 3 , 378.Xr raise 3 , 379.Xr read 2 , 380.Xr readlink 2 , 381.Xr recv 2 , 382.Xr recvfrom 2 , 383.Xr recvmsg 2 , 384.Xr rename 2 , 385.Xr rmdir 2 , 386.Xr select 2 , 387.Xr sem_post 3 , 388.Xr send 2 , 389.Xr sendmsg 2 , 390.Xr sendto 2 , 391.Xr setgid 2 , 392.Xr setpgid 2 , 393.Xr setsid 2 , 394.Xr setsockopt 2 , 395.Xr setuid 2 , 396.Xr shutdown 2 , 397.Xr sigaction 2 , 398.Xr sigaddset 3 , 399.Xr sigdelset 3 , 400.Xr sigemptyset 3 , 401.Xr sigfillset 3 , 402.Xr sigismember 3 , 403.Xr sleep 3 , 404.Xr signal 3 , 405.Xr sigpause 3 , 406.Xr sigpending 2 , 407.Xr sigprocmask 2 , 408.\" .Xr sigqueue 409.Xr sigset 3 , 410.Xr sigsuspend 2 , 411.Xr sockatmark 3 , 412.Xr socket 2 , 413.Xr socketpair 2 , 414.Xr stat 2 , 415.Xr symlink 2 , 416.Xr sysconf 3 , 417.Xr tcdrain 3 , 418.Xr tcflow 3 , 419.Xr tcflush 3 , 420.Xr tcgetattr 3 , 421.Xr tcgetpgrp 3 , 422.Xr tcsendbreak 3 , 423.Xr tcsetattr 3 , 424.Xr tcsetpgrp 3 , 425.Xr time 3 , 426.Xr timer_getoverrun 2 , 427.Xr timer_gettime 2 , 428.Xr timer_settime 2 , 429.Xr times 3 , 430.Xr umask 2 , 431.Xr uname 3 , 432.Xr unlink 2 , 433.Xr utime 3 , 434.Xr wait 2 , 435.Xr waitpid 2 , 436.Xr write 2 . 437.Sh NOTES 438The mask specified in 439.Fa act 440is not allowed to block 441.Dv SIGKILL 442or 443.Dv SIGSTOP . 444This is enforced silently by the system. 445.Sh RETURN VALUES 446A 0 value indicates that the call succeeded. 447A \-1 return value indicates an error occurred and 448.Va errno 449is set to indicate the reason. 450.Sh ERRORS 451.Fn sigaction 452will fail and no new signal handler will be installed if one 453of the following occurs: 454.Bl -tag -width Er 455.It Bq Er EFAULT 456Either 457.Fa act 458or 459.Fa oact 460points to memory that is not a valid part of the process 461address space. 462.It Bq Er EINVAL 463.Fa sig 464is not a valid signal number; 465or an attempt is made to ignore or supply a handler for 466.Dv SIGKILL 467or 468.Dv SIGSTOP ; 469or the 470.Em sa_flags 471word contains bits other than 472.Dv SA_NOCLDSTOP , 473.Dv SA_NOCLDWAIT , 474.Dv SA_NODEFER , 475.Dv SA_ONSTACK , 476.Dv SA_RESETHAND , 477.Dv SA_RESTART , 478and 479.Dv SA_SIGINFO . 480.El 481.Sh SEE ALSO 482.Xr kill 1 , 483.Xr kill 2 , 484.Xr ptrace 2 , 485.Xr sigaltstack 2 , 486.Xr sigprocmask 2 , 487.Xr sigstack 2 , 488.Xr sigsuspend 2 , 489.Xr fpgetmask 3 , 490.Xr fpsetmask 3 , 491.Xr setjmp 3 , 492.Xr sigblock 3 , 493.Xr siginterrupt 3 , 494.Xr signal 3 , 495.Xr sigpause 3 , 496.Xr sigsetmask 3 , 497.Xr sigsetops 3 , 498.Xr tty 4 499.Sh STANDARDS 500The 501.Fn sigaction 502function conforms to 503.St -p1003.1-90 . 504The 505.Dv SA_ONSTACK 506and 507.Dv SA_RESTART 508flags are Berkeley extensions, available on most 509.Bx Ns \-derived 510systems. 511