1.\" $OpenBSD: sigaction.2,v 1.70 2015/05/12 02:44:06 guenther 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: May 12 2015 $ 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.Em 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 199Options may be specified by setting 200.Fa sa_flags . 201The meaning of the various bits is as follows: 202.Bl -tag -offset indent -width SA_RESETHANDXX 203.It Dv SA_NOCLDSTOP 204If this bit is set when installing a catching function 205for the 206.Dv SIGCHLD 207signal, 208the 209.Dv SIGCHLD 210signal will be generated only when a child process exits, 211not when a child process stops. 212.It Dv SA_NOCLDWAIT 213If this bit is set when calling 214.Fn sigaction 215for the 216.Dv SIGCHLD 217signal, the system will not create zombie processes when children of 218the calling process exit, 219though existing zombies will remain. 220If the calling process subsequently issues a 221.Xr waitpid 2 222(or equivalent) and there are no previously existing zombie child 223processes that match the 224.Xr waitpid 2 225criteria, 226it blocks until all of the calling process's child 227processes that would match terminate, 228and then returns a value of \-1 with 229.Va errno 230set to 231.Er ECHILD . 232.It Dv SA_ONSTACK 233If this bit is set, the system will deliver the signal to the process 234on a 235.Em "signal stack" , 236specified with 237.Xr sigaltstack 2 . 238.It Dv SA_NODEFER 239If this bit is set, further occurrences of the delivered signal are 240not masked during the execution of the handler. 241.It Dv SA_RESETHAND 242If this bit is set, the handler is reset back to 243.Dv SIG_DFL 244at the moment the signal is delivered. 245.It Dv SA_SIGINFO 246If this bit is set, the 2nd argument of the handler is set to 247be a pointer to a 248.Em siginfo_t 249structure as described in 250.In sys/siginfo.h . 251It provides much more information about the causes and 252attributes of the signal that is being delivered. 253.It Dv SA_RESTART 254If a signal is caught during the system calls listed below, 255the call may be forced to terminate 256with the error 257.Er EINTR , 258the call may return with a data transfer shorter than requested, 259or the call may be restarted. 260Restarting of pending calls is requested 261by setting the 262.Dv SA_RESTART 263bit in 264.Fa sa_flags . 265The affected system calls include 266.Xr read 2 , 267.Xr write 2 , 268.Xr sendto 2 , 269.Xr recvfrom 2 , 270.Xr sendmsg 2 271and 272.Xr recvmsg 2 273on a communications channel or a slow device (such as a terminal, 274but not a regular file) 275and during a 276.Xr wait 2 277or 278.Xr ioctl 2 . 279However, calls that have already committed are not restarted, 280but instead return a partial success (for example, a short read count). 281.El 282.Pp 283After a 284.Xr fork 2 285or 286.Xr vfork 2 , 287all signals, the signal mask, the signal stack, 288and the restart/interrupt flags are inherited by the child. 289.Pp 290.Xr execve 2 291reinstates the default 292action for all signals which were caught and 293resets all signals to be caught on the user stack. 294Ignored signals remain ignored; 295the signal mask remains the same; 296signals that restart pending system calls continue to do so. 297.Pp 298The following is a list of all signals 299with names as in the include file 300.In signal.h : 301.Bl -column "SIGVTALARM" "create core image" "Description" 302.It Sy "Name" Ta Sy "Default Action" Ta Sy "Description" 303.It Dv SIGHUP Ta "terminate process" Ta "terminal line hangup" 304.It Dv SIGINT Ta "terminate process" Ta "interrupt program" 305.It Dv SIGQUIT Ta "create core image" Ta "quit program" 306.It Dv SIGILL Ta "create core image" Ta "illegal instruction" 307.It Dv SIGTRAP Ta "create core image" Ta "trace trap" 308.It Dv SIGABRT Ta "create core image" Ta "abort(3) call (formerly SIGIOT)" 309.It Dv SIGEMT Ta "create core image" Ta "emulate instruction executed" 310.It Dv SIGFPE Ta "create core image" Ta "floating-point exception" 311.It Dv SIGKILL Ta "terminate process" Ta "kill program (cannot be caught or ignored)" 312.It Dv SIGBUS Ta "create core image" Ta "bus error" 313.It Dv SIGSEGV Ta "create core image" Ta "segmentation violation" 314.It Dv SIGSYS Ta "create core image" Ta "system call given invalid argument" 315.It Dv SIGPIPE Ta "terminate process" Ta "write on a pipe with no reader" 316.It Dv SIGALRM Ta "terminate process" Ta "real-time timer expired" 317.It Dv SIGTERM Ta "terminate process" Ta "software termination signal" 318.It Dv SIGURG Ta "discard signal" Ta "urgent condition present on socket" 319.It Dv SIGSTOP Ta "stop process" Ta "stop (cannot be caught or ignored)" 320.It Dv SIGTSTP Ta "stop process" Ta "stop signal generated from keyboard" 321.It Dv SIGCONT Ta "discard signal" Ta "continue after stop" 322.It Dv SIGCHLD Ta "discard signal" Ta "child status has changed" 323.It Dv SIGTTIN Ta "stop process" Ta "background read attempted from control terminal" 324.It Dv SIGTTOU Ta "stop process" Ta "background write attempted to control terminal" 325.It Dv SIGIO Ta "discard signal" Ta "I/O is possible on a descriptor (see" 326.Xr fcntl 2 ) 327.It Dv SIGXCPU Ta "terminate process" Ta "CPU time limit exceeded (see" 328.Xr setrlimit 2 ) 329.It Dv SIGXFSZ Ta "terminate process" Ta "file size limit exceeded (see" 330.Xr setrlimit 2 ) 331.It Dv SIGVTALRM Ta "terminate process" Ta "virtual time alarm (see" 332.Xr setitimer 2 ) 333.It Dv SIGPROF Ta "terminate process" Ta "profiling timer alarm (see" 334.Xr setitimer 2 ) 335.It Dv SIGWINCH Ta "discard signal" Ta "window size change" 336.It Dv SIGINFO Ta "discard signal" Ta "status request from keyboard" 337.It Dv SIGUSR1 Ta "terminate process" Ta "user defined signal 1" 338.It Dv SIGUSR2 Ta "terminate process" Ta "user defined signal 2" 339.It Dv SIGTHR Ta "discard signal" Ta "thread AST" 340.El 341.Sh RETURN VALUES 342.Rv -std 343.Sh EXAMPLES 344The handler routine can be declared: 345.Bd -literal -offset indent 346void 347handler(int sig) 348.Pp 349.Ed 350If the 351.Dv SA_SIGINFO 352option is enabled, the canonical way to declare it is: 353.Bd -literal -offset indent 354void 355handler(int sig, siginfo_t *sip, void *ctx) 356.Ed 357.Pp 358Here 359.Fa sig 360is the signal number, into which the hardware faults and traps are mapped. 361If the 362.Dv SA_SIGINFO 363option is set, 364.Fa sip 365is a pointer to a 366.Dv siginfo_t 367as described in 368.In sys/siginfo.h . 369If 370.Dv SA_SIGINFO 371is not set, this pointer will be 372.Dv NULL 373instead. 374The function specified in 375.Fa sa_sigaction 376will be called instead of the function specified by 377.Fa sa_handler 378(note that in some implementations these are in fact the same). 379.Fa ctx 380may be cast to a pointer to 381.Fa ucontext_t 382which can be used to restore the thread's context from before the signal. 383On 384.Ox , 385.Fa ucontext_t 386is an alias for the 387.Fa sigcontext 388structure defined in 389.In signal.h . 390The contents of this structure are machine-dependent. 391.Sh ERRORS 392.Fn sigaction 393will fail and no new signal handler will be installed if one 394of the following occurs: 395.Bl -tag -width Er 396.It Bq Er EFAULT 397Either 398.Fa act 399or 400.Fa oact 401points to memory that is not a valid part of the process 402address space. 403.It Bq Er EINVAL 404.Fa sig 405is not a valid signal number. 406.It Bq Er EINVAL 407An attempt is made to ignore or supply a handler for 408.Dv SIGKILL 409or 410.Dv SIGSTOP . 411.El 412.Sh SEE ALSO 413.Xr kill 1 , 414.Xr kill 2 , 415.Xr ptrace 2 , 416.Xr sigaltstack 2 , 417.Xr sigprocmask 2 , 418.Xr sigsuspend 2 , 419.Xr wait 2 , 420.Xr setjmp 3 , 421.Xr sigblock 3 , 422.Xr sigpause 3 , 423.Xr sigsetops 3 , 424.Xr sigvec 3 , 425.Xr tty 4 426.Sh STANDARDS 427The 428.Fn sigaction 429function conforms to 430.St -p1003.1-2008 . 431.Pp 432The 433.Dv SA_ONSTACK 434flag and the 435.Dv SIGPROF , 436.Dv SIGSYS , 437.Dv SIGTRAP , 438.Dv SIGVTALRM , 439.Dv SIGXCPU , 440and 441.Dv SIGXFSZ 442signals conform to the X/Open System Interfaces option of that standard. 443The standard marks 444.Dv SIGPROF 445as obsolescent. 446The signals 447.Dv SIGEMT , 448.Dv SIGINFO , 449.Dv SIGIO , 450and 451.Dv SIGWINCH 452are Berkeley extensions. 453These signals are available on most 454.Bx Ns -derived 455systems. 456The 457.Dv SIGTHR 458signal is specific to 459.Ox 460and is part of the 461implementation of thread cancellation; 462.Fa sigaction 463and other signal interfaces may reject attempts to use or alter the 464handling of 465.Dv SIGTHR . 466.Pp 467The following functions are either reentrant or not interruptible 468by signals and are async-signal-safe. 469Therefore applications may 470invoke them, without restriction, from signal-catching functions: 471.Pp 472Standard Interfaces: 473.Pp 474.Fn _exit , 475.Fn _Exit , 476.Fn abort , 477.Fn accept , 478.Fn access , 479.Fn alarm , 480.Fn bind , 481.Fn cfgetispeed , 482.Fn cfgetospeed , 483.Fn cfsetispeed , 484.Fn cfsetospeed , 485.Fn chdir , 486.Fn chmod , 487.Fn chown , 488.Fn clock_gettime , 489.Fn close , 490.Fn connect , 491.Fn creat , 492.Fn dup , 493.Fn dup2 , 494.Fn execl , 495.Fn execle , 496.Fn execv , 497.Fn execve , 498.Fn faccessat , 499.Fn fchdir , 500.Fn fchmod , 501.Fn fchmodat , 502.Fn fchown , 503.Fn fchownat , 504.Fn fcntl , 505.Fn fdatasync , 506.Fn fork , 507.Fn fpathconf , 508.Fn fstat , 509.Fn fstatat , 510.Fn fsync , 511.Fn ftruncate , 512.Fn futimens , 513.Fn futimes , 514.Fn getegid , 515.Fn geteuid , 516.Fn getgid , 517.Fn getgroups , 518.Fn getpeername , 519.Fn getpgrp , 520.Fn getpid , 521.Fn getppid , 522.Fn getsockname , 523.Fn getsockopt , 524.Fn getuid , 525.Fn kill , 526.Fn link , 527.Fn linkat , 528.Fn listen , 529.Fn lseek , 530.Fn lstat , 531.Fn mkdir , 532.Fn mkdirat , 533.Fn mkfifo , 534.Fn mkfifoat , 535.Fn mknod , 536.Fn mknodat , 537.Fn open , 538.Fn openat , 539.Fn pathconf , 540.Fn pause , 541.Fn pipe , 542.Fn poll , 543.Fn pselect , 544.Fn pthread_sigmask , 545.Fn raise , 546.Fn read , 547.Fn readlink , 548.Fn readlinkat , 549.Fn recv , 550.Fn recvfrom , 551.Fn recvmsg , 552.Fn rename , 553.Fn renameat , 554.Fn rmdir , 555.Fn select , 556.Fn send , 557.Fn sendmsg , 558.Fn sendto , 559.Fn setgid , 560.Fn setpgid , 561.Fn setsid , 562.Fn setsockopt , 563.Fn setuid , 564.Fn shutdown , 565.Fn sigaction , 566.Fn sigaddset , 567.Fn sigdelset , 568.Fn sigemptyset , 569.Fn sigfillset , 570.Fn sigismember , 571.Fn signal , 572.Fn sigpause , 573.Fn sigpending , 574.Fn sigprocmask , 575.Fn sigsuspend , 576.Fn sleep , 577.Fn sockatmark , 578.Fn socket , 579.Fn socketpair , 580.Fn stat , 581.Fn strcat , 582.Fn strcpy , 583.Fn strncat , 584.Fn strncpy , 585.Fn symlink , 586.Fn symlinkat , 587.Fn sysconf , 588.Fn tcdrain , 589.Fn tcflow , 590.Fn tcflush , 591.Fn tcgetattr , 592.Fn tcgetpgrp , 593.Fn tcsendbreak , 594.Fn tcsetattr , 595.Fn tcsetpgrp , 596.Fn time , 597.Fn times , 598.Fn umask , 599.Fn uname , 600.Fn unlink , 601.Fn unlinkat , 602.Fn utime , 603.Fn utimensat , 604.Fn utimes , 605.Fn wait , 606.Fn waitpid , 607.Fn write , 608and perhaps some others. 609.\" unimplemented functions that should be async-sig-safe, if we had them 610.\" POSIX Issue 7 additions 611.\" .Pp 612.\" .Fn fexecve . 613.\" 614.\" Realtime Interfaces: 615.\" .Pp 616.\" .Fn aio_error , 617.\" .Fn aio_return , 618.\" .Fn aio_suspend , 619.\" .Fn sem_post , 620.\" .Fn sigqueue , 621.\" .Fn timer_getoverrun , 622.\" .Fn timer_gettime , 623.\" .Fn timer_settime . 624.Pp 625Extension Interfaces: 626.Pp 627.Fn accept4 , 628.Fn chflags , 629.Fn chflagsat , 630.Fn dup3 , 631.Fn fchflags , 632.Fn getentropy , 633.Fn getresgid , 634.Fn getresuid , 635.Fn pipe2 , 636.Fn ppoll , 637.Fn sendsyslog , 638.Fn setresgid , 639.Fn setresuid , 640.Fn strlcat , 641.Fn strlcpy , 642.Fn wait3 , 643.Fn wait4 . 644.Pp 645In addition, access and updates to 646.Va errno 647are guaranteed to be safe. 648Most functions not in the above lists are considered to be unsafe 649with respect to signals. 650That is to say, the behaviour of such functions when called from 651a signal handler is undefined. 652In general though, signal handlers should do little more than set a 653flag, ideally of type volatile sig_atomic_t; most other actions are not safe. 654.Pp 655Additionally, it is advised that signal handlers guard against 656modification of the external symbol 657.Va errno 658by the above functions, saving it at entry and restoring 659it on return, thus: 660.Bd -literal -offset indent 661void 662handler(int sig) 663{ 664 int save_errno = errno; 665 666 ... 667 errno = save_errno; 668} 669.Ed 670.Pp 671The functions below are async-signal-safe in 672.Ox 673except when used with floating-point arguments or directives, 674but are probably unsafe on other systems: 675.Pp 676.Bl -tag -offset indent -compact -width foofoofoofoo 677.It Fn dprintf 678Safe. 679.It Fn vdprintf 680Safe. 681.It Fn snprintf 682Safe. 683.It Fn vsnprintf 684Safe. 685.It Fn syslog_r 686Safe if the 687.Va syslog_data 688struct is initialized as a local variable. 689.El 690