1.\" $OpenBSD: sigaction.2,v 1.77 2022/10/13 21:37:05 jmc Exp $ 2.\" $NetBSD: sigaction.2,v 1.7 1995/10/12 15:41:16 jtc Exp $ 3.\" 4.\" Copyright (c) 1980, 1990, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)sigaction.2 8.2 (Berkeley) 4/3/94 32.\" 33.Dd $Mdocdate: October 13 2022 $ 34.Dt SIGACTION 2 35.Os 36.Sh NAME 37.Nm sigaction 38.Nd software signal facilities 39.Sh SYNOPSIS 40.In signal.h 41.Bd -literal 42struct sigaction { 43 union { /* signal handler */ 44 void (*__sa_handler)(int); 45 void (*__sa_sigaction)(int, siginfo_t *, void *); 46 } __sigaction_u; 47 sigset_t sa_mask; /* signal mask to apply */ 48 int sa_flags; /* see signal options below */ 49}; 50.Ed 51.Pp 52.Fd #define sa_handler __sigaction_u.__sa_handler 53.Fd #define sa_sigaction __sigaction_u.__sa_sigaction 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 normally 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 72of delivery. 73Normally, signal handlers execute on the current stack 74of the process. 75This may be changed, on a per-handler basis, 76so that signals are taken on a special 77.Em "signal stack" . 78.Pp 79Signal routines normally execute with the signal that caused their 80invocation 81.Em blocked , 82but other signals may yet occur. 83A global 84.Em "signal mask" 85defines the set of signals currently blocked from delivery 86to a process. 87The signal mask for a process is initialized from that of its 88parent (normally empty). 89It may be changed with a 90.Xr sigprocmask 2 91call, or when a signal is delivered to the process. 92.Pp 93When a signal 94condition arises for a process, the signal is added to a set of 95signals pending for the process. 96If the signal is not currently 97.Em blocked 98by the process then it is delivered to the process. 99Signals may be delivered any time a process enters the operating system 100(e.g., during a system call, page fault or trap, or clock interrupt). 101If multiple signals are ready to be delivered at the same time, 102any signals that could be caused by traps are delivered first. 103Additional signals may be processed at the same time, with each 104appearing to interrupt the handlers for the previous signals 105before their first instructions. 106The set of pending signals is returned by the 107.Xr sigpending 2 108function. 109When a caught signal 110is delivered, the current state of the process is saved, 111a new signal mask is calculated (as described below), 112and the signal handler is invoked. 113The call to the handler is arranged so that if the signal handling routine 114returns normally the process will resume execution in the context from 115before the signal's delivery. 116If the process wishes to resume in a different context, then it 117must arrange to restore the previous context itself. 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 set, 125the signal to be delivered, and the signal mask 126.Fa sa_mask 127associated with the handler to be invoked, but always excluding 128.Dv SIGKILL 129and 130.Dv SIGSTOP . 131.Pp 132.Fn sigaction 133assigns an action for a signal specified by 134.Fa sig . 135If 136.Fa act 137is non-zero, it 138specifies an action 139.Pf ( Dv SIG_DFL , 140.Dv SIG_IGN , 141or a handler routine) and mask 142to be used when delivering the specified signal. 143If 144.Fa oact 145is non-zero, the previous handling information for the signal 146is returned to the user. 147.Pp 148Once a signal handler is installed, it normally remains installed 149until another 150.Fn sigaction 151call is made, or an 152.Xr execve 2 153is performed. 154The value of 155.Fa sa_handler 156(or, if the 157.Dv SA_SIGINFO 158flag is set, the value of 159.Fa sa_sigaction 160instead) indicates what action should be performed when a 161signal arrives. 162A signal-specific default action may be reset by 163setting 164.Fa sa_handler 165to 166.Dv SIG_DFL . 167Alternately, if the 168.Dv SA_RESETHAND 169flag is set the default action will be reinstated when the signal 170is first posted. 171The defaults are process termination, possibly with core dump; 172no action; stopping the process; or continuing the process. 173See the signal list below for each signal's default action. 174If 175.Fa sa_handler 176is 177.Dv SIG_DFL , 178the default action for the signal is to discard the signal, 179and if a signal is pending, 180the pending signal is discarded even if the signal is masked. 181If 182.Fa sa_handler 183is set to 184.Dv SIG_IGN , 185current and pending instances 186of the signal are ignored and discarded. 187If 188.Fa sig 189is 190.Dv SIGCHLD 191and 192.Fa sa_handler 193is set to 194.Dv SIG_IGN , 195the 196.Dv SA_NOCLDWAIT 197flag (described below) is implied. 198.Pp 199The signal mask 200.Fa sa_mask 201is typically manipulated using the 202.Xr sigaddset 3 203family of functions. 204.Pp 205Options may be specified by setting 206.Fa sa_flags . 207The meaning of the various bits is as follows: 208.Bl -tag -offset indent -width SA_RESETHANDXX 209.It Dv SA_NOCLDSTOP 210If this bit is set when installing a catching function 211for the 212.Dv SIGCHLD 213signal, 214the 215.Dv SIGCHLD 216signal will be generated only when a child process exits, 217not when a child process stops. 218.It Dv SA_NOCLDWAIT 219If this bit is set when calling 220.Fn sigaction 221for the 222.Dv SIGCHLD 223signal, the system will not create zombie processes when children of 224the calling process exit, 225though existing zombies will remain. 226If the calling process subsequently issues a 227.Xr waitpid 2 228(or equivalent) and there are no previously existing zombie child 229processes that match the 230.Xr waitpid 2 231criteria, 232it blocks until all of the calling process's child 233processes that would match terminate, 234and then returns a value of \-1 with 235.Va errno 236set to 237.Er ECHILD . 238.It Dv SA_ONSTACK 239If this bit is set, the system will deliver the signal to the process 240on a 241.Em "signal stack" , 242specified with 243.Xr sigaltstack 2 . 244.It Dv SA_NODEFER 245If this bit is set, further occurrences of the delivered signal are 246not masked during the execution of the handler. 247.It Dv SA_RESETHAND 248If this bit is set, the handler is reset back to 249.Dv SIG_DFL 250at the moment the signal is delivered. 251.It Dv SA_SIGINFO 252If this bit is set, the 2nd argument of the handler is set to 253be a pointer to a 254.Em siginfo_t 255structure as described in 256.In sys/siginfo.h . 257It provides much more information about the causes and 258attributes of the signal that is being delivered. 259.It Dv SA_RESTART 260If a signal is caught during the system calls listed below, 261the call may be forced to terminate 262with the error 263.Er EINTR , 264the call may return with a data transfer shorter than requested, 265or the call may be restarted. 266Restarting of pending calls is requested 267by setting the 268.Dv SA_RESTART 269bit in 270.Fa sa_flags . 271The affected system calls include 272.Xr read 2 , 273.Xr write 2 , 274.Xr sendto 2 , 275.Xr recvfrom 2 , 276.Xr sendmsg 2 277and 278.Xr recvmsg 2 279on a communications channel or a slow device (such as a terminal, 280but not a regular file) 281and during a 282.Xr wait 2 283or 284.Xr ioctl 2 . 285However, calls that have already committed are not restarted, 286but instead return a partial success (for example, a short read count). 287.El 288.Pp 289After a 290.Xr fork 2 291or 292.Xr vfork 2 , 293all signals, the signal mask, the signal stack, 294and the restart/interrupt flags are inherited by the child. 295.Pp 296.Xr execve 2 297reinstates the default 298action for 299.Dv SIGCHLD 300and all signals which were caught; all other signals remain ignored. 301All signals are reset to be caught on the user stack and 302the signal mask remains the same; 303signals that restart pending system calls continue to do so. 304.Pp 305The following is a list of all signals 306with names as in the include file 307.In signal.h : 308.Bl -column "SIGVTALARM" "create core image" "Description" 309.It Sy "Name" Ta Sy "Default Action" Ta Sy "Description" 310.It Dv SIGHUP Ta "terminate process" Ta "terminal line hangup" 311.It Dv SIGINT Ta "terminate process" Ta "interrupt program" 312.It Dv SIGQUIT Ta "create core image" Ta "quit program" 313.It Dv SIGILL Ta "create core image" Ta "illegal instruction" 314.It Dv SIGTRAP Ta "create core image" Ta "trace trap" 315.It Dv SIGABRT Ta "create core image" Ta "abort(3) call (formerly SIGIOT)" 316.It Dv SIGEMT Ta "create core image" Ta "emulate instruction executed" 317.It Dv SIGFPE Ta "create core image" Ta "floating-point exception" 318.It Dv SIGKILL Ta "terminate process" Ta "kill program (cannot be caught or ignored)" 319.It Dv SIGBUS Ta "create core image" Ta "bus error" 320.It Dv SIGSEGV Ta "create core image" Ta "segmentation violation" 321.It Dv SIGSYS Ta "create core image" Ta "system call given invalid argument" 322.It Dv SIGPIPE Ta "terminate process" Ta "write on a pipe with no reader" 323.It Dv SIGALRM Ta "terminate process" Ta "real-time timer expired" 324.It Dv SIGTERM Ta "terminate process" Ta "software termination signal" 325.It Dv SIGURG Ta "discard signal" Ta "urgent condition present on socket" 326.It Dv SIGSTOP Ta "stop process" Ta "stop (cannot be caught or ignored)" 327.It Dv SIGTSTP Ta "stop process" Ta "stop signal generated from keyboard" 328.It Dv SIGCONT Ta "discard signal" Ta "continue after stop" 329.It Dv SIGCHLD Ta "discard signal" Ta "child status has changed" 330.It Dv SIGTTIN Ta "stop process" Ta "background read attempted from controlling terminal" 331.It Dv SIGTTOU Ta "stop process" Ta "background write attempted to controlling terminal" 332.It Dv SIGIO Ta "discard signal" Ta "I/O is possible on a descriptor (see" 333.Xr fcntl 2 ) 334.It Dv SIGXCPU Ta "terminate process" Ta "CPU time limit exceeded (see" 335.Xr setrlimit 2 ) 336.It Dv SIGXFSZ Ta "terminate process" Ta "file size limit exceeded (see" 337.Xr setrlimit 2 ) 338.It Dv SIGVTALRM Ta "terminate process" Ta "virtual time alarm (see" 339.Xr setitimer 2 ) 340.It Dv SIGPROF Ta "terminate process" Ta "profiling timer alarm (see" 341.Xr setitimer 2 ) 342.It Dv SIGWINCH Ta "discard signal" Ta "window size change" 343.It Dv SIGINFO Ta "discard signal" Ta "status request from keyboard" 344.It Dv SIGUSR1 Ta "terminate process" Ta "user defined signal 1" 345.It Dv SIGUSR2 Ta "terminate process" Ta "user defined signal 2" 346.It Dv SIGTHR Ta "discard signal" Ta "thread AST" 347.El 348.Sh RETURN VALUES 349.Rv -std 350.Sh EXAMPLES 351The handler routine can be declared: 352.Bd -literal -offset indent 353void 354handler(int sig) 355.Pp 356.Ed 357If the 358.Dv SA_SIGINFO 359option is enabled, the canonical way to declare it is: 360.Bd -literal -offset indent 361void 362handler(int sig, siginfo_t *sip, void *ctx) 363.Ed 364.Pp 365Here 366.Fa sig 367is the signal number, into which the hardware faults and traps are mapped. 368If the 369.Dv SA_SIGINFO 370option is set, 371.Fa sip 372is a pointer to a 373.Dv siginfo_t 374as described in 375.In sys/siginfo.h . 376If 377.Dv SA_SIGINFO 378is not set, this pointer will be 379.Dv NULL 380instead. 381The function specified in 382.Fa sa_sigaction 383will be called instead of the function specified by 384.Fa sa_handler 385(note that in some implementations these are in fact the same). 386.Fa ctx 387may be cast to a pointer to 388.Fa ucontext_t 389which can be used to restore the thread's context from before the signal. 390On 391.Ox , 392.Fa ucontext_t 393is an alias for the 394.Fa sigcontext 395structure defined in 396.In signal.h . 397The contents of this structure are machine-dependent. 398.Sh ERRORS 399.Fn sigaction 400will fail and no new signal handler will be installed if one 401of the following occurs: 402.Bl -tag -width Er 403.It Bq Er EFAULT 404Either 405.Fa act 406or 407.Fa oact 408points to memory that is not a valid part of the process 409address space. 410.It Bq Er EINVAL 411.Fa sig 412is not a valid signal number. 413.It Bq Er EINVAL 414An attempt is made to ignore or supply a handler for 415.Dv SIGKILL 416or 417.Dv SIGSTOP . 418.El 419.Sh SEE ALSO 420.Xr kill 1 , 421.Xr kill 2 , 422.Xr ptrace 2 , 423.Xr sigaltstack 2 , 424.Xr sigprocmask 2 , 425.Xr sigsuspend 2 , 426.Xr wait 2 , 427.Xr setjmp 3 , 428.Xr sigaddset 3 , 429.Xr sigblock 3 , 430.Xr sigpause 3 , 431.Xr sigvec 3 , 432.Xr tty 4 433.Sh STANDARDS 434The 435.Fn sigaction 436function conforms to 437.St -p1003.1-2008 . 438.Pp 439The 440.Dv SA_ONSTACK 441flag and the 442.Dv SIGPROF , 443.Dv SIGSYS , 444.Dv SIGTRAP , 445.Dv SIGVTALRM , 446.Dv SIGXCPU , 447and 448.Dv SIGXFSZ 449signals conform to the X/Open System Interfaces option of that standard. 450The standard marks 451.Dv SIGPROF 452as obsolescent. 453The signals 454.Dv SIGEMT , 455.Dv SIGINFO , 456.Dv SIGIO , 457and 458.Dv SIGWINCH 459are Berkeley extensions. 460These signals are available on most 461.Bx Ns -derived 462systems. 463The 464.Dv SIGTHR 465signal is specific to 466.Ox 467and is part of the 468implementation of thread cancellation; 469.Fa sigaction 470and other signal interfaces may reject attempts to use or alter the 471handling of 472.Dv SIGTHR . 473.Pp 474The following functions are either reentrant or not interruptible 475by signals and are async-signal-safe. 476Therefore applications may 477invoke them, without restriction, from signal-catching functions: 478.Pp 479Standard Interfaces: 480.Pp 481.Fn _exit , 482.Fn _Exit , 483.Fn abort , 484.Fn accept , 485.Fn access , 486.Fn alarm , 487.Fn bind , 488.Fn cfgetispeed , 489.Fn cfgetospeed , 490.Fn cfsetispeed , 491.Fn cfsetospeed , 492.Fn chdir , 493.Fn chmod , 494.Fn chown , 495.Fn clock_gettime , 496.Fn close , 497.Fn connect , 498.Fn creat , 499.Fn dup , 500.Fn dup2 , 501.Fn execl , 502.Fn execle , 503.Fn execv , 504.Fn execve , 505.Fn faccessat , 506.Fn fchdir , 507.Fn fchmod , 508.Fn fchmodat , 509.Fn fchown , 510.Fn fchownat , 511.Fn fcntl , 512.Fn fdatasync , 513.Fn fork , 514.Fn fpathconf , 515.Fn fstat , 516.Fn fstatat , 517.Fn fsync , 518.Fn ftruncate , 519.Fn futimens , 520.Fn futimes , 521.Fn getegid , 522.Fn geteuid , 523.Fn getgid , 524.Fn getgroups , 525.Fn getpeername , 526.Fn getpgrp , 527.Fn getpid , 528.Fn getppid , 529.Fn getsockname , 530.Fn getsockopt , 531.Fn getuid , 532.Fn kill , 533.Fn link , 534.Fn linkat , 535.Fn listen , 536.Fn lseek , 537.Fn lstat , 538.Fn mkdir , 539.Fn mkdirat , 540.Fn mkfifo , 541.Fn mkfifoat , 542.Fn mknod , 543.Fn mknodat , 544.Fn open , 545.Fn openat , 546.Fn pathconf , 547.Fn pause , 548.Fn pipe , 549.Fn poll , 550.Fn pselect , 551.Fn pthread_sigmask , 552.Fn raise , 553.Fn read , 554.Fn readlink , 555.Fn readlinkat , 556.Fn recv , 557.Fn recvfrom , 558.Fn recvmsg , 559.Fn rename , 560.Fn renameat , 561.Fn rmdir , 562.Fn select , 563.Fn send , 564.Fn sendmsg , 565.Fn sendto , 566.Fn setgid , 567.Fn setpgid , 568.Fn setsid , 569.Fn setsockopt , 570.Fn setuid , 571.Fn shutdown , 572.Fn sigaction , 573.Fn sigaddset , 574.Fn sigdelset , 575.Fn sigemptyset , 576.Fn sigfillset , 577.Fn sigismember , 578.Fn signal , 579.Fn sigpause , 580.Fn sigpending , 581.Fn sigprocmask , 582.Fn sigsuspend , 583.Fn sleep , 584.Fn sockatmark , 585.Fn socket , 586.Fn socketpair , 587.Fn stat , 588.Fn strcat , 589.Fn strcpy , 590.Fn strncat , 591.Fn strncpy , 592.Fn symlink , 593.Fn symlinkat , 594.Fn sysconf , 595.Fn tcdrain , 596.Fn tcflow , 597.Fn tcflush , 598.Fn tcgetattr , 599.Fn tcgetpgrp , 600.Fn tcsendbreak , 601.Fn tcsetattr , 602.Fn tcsetpgrp , 603.Fn time , 604.Fn times , 605.Fn umask , 606.Fn uname , 607.Fn unlink , 608.Fn unlinkat , 609.Fn utime , 610.Fn utimensat , 611.Fn utimes , 612.Fn wait , 613.Fn waitpid , 614.Fn write , 615and perhaps some others. 616.\" unimplemented functions that should be async-sig-safe, if we had them 617.\" POSIX Issue 7 additions 618.\" .Pp 619.\" .Fn fexecve . 620.\" 621.\" Realtime Interfaces: 622.\" .Pp 623.\" .Fn aio_error , 624.\" .Fn aio_return , 625.\" .Fn aio_suspend , 626.\" .Fn sem_post , 627.\" .Fn sigqueue , 628.\" .Fn timer_getoverrun , 629.\" .Fn timer_gettime , 630.\" .Fn timer_settime . 631.Pp 632Extension Interfaces: 633.Pp 634.Fn accept4 , 635.Fn chflags , 636.Fn chflagsat , 637.Fn dup3 , 638.Fn fchflags , 639.Fn getentropy , 640.Fn getresgid , 641.Fn getresuid , 642.Fn pipe2 , 643.Fn ppoll , 644.Fn sendsyslog , 645.Fn setresgid , 646.Fn setresuid , 647.Fn strlcat , 648.Fn strlcpy , 649.Fn wait3 , 650.Fn wait4 . 651.Pp 652In addition, access and updates to 653.Va errno 654are guaranteed to be safe. 655Most functions not in the above lists are considered to be unsafe 656with respect to signals. 657That is to say, the behaviour of such functions when called from 658a signal handler is undefined. 659In general though, signal handlers should do little more than set a 660flag, ideally of type volatile sig_atomic_t; most other actions are not safe. 661.Pp 662Additionally, it is advised that signal handlers guard against 663modification of the external symbol 664.Va errno 665by the above functions, saving it at entry and restoring 666it on return, thus: 667.Bd -literal -offset indent 668void 669handler(int sig) 670{ 671 int save_errno = errno; 672 673 ... 674 errno = save_errno; 675} 676.Ed 677.Pp 678The functions below are async-signal-safe in 679.Ox 680except when used with floating-point arguments or directives, 681but are probably unsafe on other systems: 682.Pp 683.Bl -tag -offset indent -compact -width foofoofoofoo 684.It Fn dprintf 685Safe. 686.It Fn vdprintf 687Safe. 688.It Fn snprintf 689Safe. 690.It Fn vsnprintf 691Safe. 692.It Fn syslog_r 693Safe if the 694.Va syslog_data 695struct is initialized as a local variable. 696.El 697