1.\" $NetBSD: sigaction.2,v 1.53 2024/12/18 15:31:20 christos 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 December 18, 2024 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 or continues. 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 . 208If an alternate stack is not available, the default stack will be used. 209.It Dv SA_RESETHAND 210If set, the default action will be reinstated when the signal 211is first posted. 212.It Dv SA_RESTART 213Normally, if a signal is caught during the system calls listed below, 214the call may be forced to terminate 215with the error 216.Er EINTR , 217the call may return with a data transfer shorter than requested, 218or the call may be restarted. 219Restarting of pending calls is requested 220by setting the 221.Dv SA_RESTART 222bit in 223.Ar sa_flags . 224The affected system calls include 225.Xr open 2 , 226.Xr read 2 , 227.Xr write 2 , 228.Xr sendto 2 , 229.Xr recvfrom 2 , 230.Xr sendmsg 2 231and 232.Xr recvmsg 2 233on a communications channel or a slow device (such as a terminal, 234but not a regular file) 235and during a 236.Xr wait 2 237or 238.Xr ioctl 2 . 239However, calls that have already committed are not restarted, 240but instead return a partial success (for example, a short read count). 241.Pp 242After a 243.Xr fork 2 244or 245.Xr vfork 2 246all signals, the signal mask, the signal stack, 247and the restart/interrupt flags are inherited by the child. 248.Pp 249The 250.Xr execve 2 251system call reinstates the default 252action for all signals which were caught and 253resets all signals to be caught on the user stack. 254Ignored signals remain ignored; 255the signal mask remains the same; 256signals that restart pending system calls continue to do so. 257.Pp 258See 259.Xr signal 7 260for comprehensive list of supported signals. 261.It Dv SA_SIGINFO 262If set, the signal handler function will receive additional information 263about the caught signal. 264An alternative handler that gets passed additional arguments will 265be called which is named 266.Fa sa_sigaction . 267The 268.Ar sig 269argument of this handler contains the signal number that was caught. 270The 271.Ar info 272argument contains additional signal specific information which 273is listed in 274.Xr siginfo 2 . 275The 276.Ar ctx 277argument 278is a pointer to the 279.Xr ucontext 2 280context where the signal handler will return to. 281.It Dv SA_NOKERNINFO 282This flag is relevant only to 283.Dv SIGINFO , 284and turns off printing kernel messages on the tty. 285It is similar to the 286.Dv NOKERNINFO 287flag in 288.Xr termios 4 . 289.El 290.Pp 291If the signal handler is called due to signal delivery resulting from reasons 292other than direct calls to 293.Xr kill 2 294or 295.Xr _lwp_kill 2 296or indirect calls to 297.Xr _lwp_kill 2 298via 299.Xr abort 3 300or 301.Xr raise 3 302any activity (such as calling functions or assigning variables in the global 303or static scopes) other than setting a variable of the type 304.Vt volatile sig_atomic_t 305is undefined. 306.Ss Signal-safe functions 307Only functions that are guaranteed to be async-signal-safe can safely 308be used in signal handlers. 309These are functions that are either reentrant or non-interruptible. 310(These functions are also the only functions that may be used in a 311child process after doing 312.Xr fork 2 313in a threaded program.) 314.Pp 315The following functions are async-signal-safe. 316Any function not listed 317below is unsafe to use in signal handlers. 318.Pp 319.Xr _Exit 2 , 320.Xr _exit 2 , 321.Xr abort 3 , 322.Xr accept 2 , 323.Xr access 2 , 324.\" .Xr aio_error 325.\" .Xr aio_return 326.\" .Xr aio_suspend 327.Xr alarm 3 , 328.Xr bind 2 , 329.Xr cfgetispeed 3 , 330.Xr cfgetospeed 3 , 331.Xr cfsetispeed 3 , 332.Xr cfsetospeed 3 , 333.Xr chdir 2 , 334.Xr chmod 2 , 335.Xr chown 2 , 336.Xr clock_gettime 2 , 337.Xr close 2 , 338.Xr connect 2 , 339.Xr creat 3 , 340.Xr dup 2 , 341.Xr dup2 2 , 342.Xr execle 3 , 343.Xr execve 2 , 344.Xr fchmod 2 , 345.Xr fchown 2 , 346.Xr fcntl 2 , 347.Xr fdatasync 2 , 348.Xr fork 2 , 349.Xr fpathconf 2 , 350.Xr fstat 2 , 351.Xr fsync 2 , 352.Xr ftruncate 2 , 353.Xr getegid 2 , 354.Xr geteuid 2 , 355.Xr getgid 2 , 356.Xr getgroups 2 , 357.Xr getpeername 2 , 358.Xr getpgrp 2 , 359.Xr getpid 2 , 360.Xr getppid 2 , 361.Xr getsockname 2 , 362.Xr getsockopt 2 , 363.Xr getuid 2 , 364.Xr kill 2 , 365.Xr link 2 , 366.Xr listen 2 , 367.Xr lseek 2 , 368.Xr lstat 2 , 369.Xr mkdir 2 , 370.Xr mkfifo 2 , 371.Xr open 2 , 372.Xr pathconf 2 , 373.Xr pause 3 , 374.Xr pipe 2 , 375.Xr poll 2 , 376.\" .Xr posix_trace_event 2 377.\" .Xr pselect 2 378.Xr pthread_mutex_unlock 3 , 379.Xr raise 3 , 380.Xr read 2 , 381.Xr readlink 2 , 382.Xr recv 2 , 383.Xr recvfrom 2 , 384.Xr recvmsg 2 , 385.Xr rename 2 , 386.Xr rmdir 2 , 387.Xr select 2 , 388.Xr sem_post 3 , 389.Xr send 2 , 390.Xr sendmsg 2 , 391.Xr sendto 2 , 392.Xr setgid 2 , 393.Xr setpgid 2 , 394.Xr setsid 2 , 395.Xr setsockopt 2 , 396.Xr setuid 2 , 397.Xr shutdown 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