1.\" $OpenBSD: sigaction.2,v 1.58 2014/07/19 08:55:22 matthew 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: July 19 2014 $ 34.Dt SIGACTION 2 35.Os 36.Sh NAME 37.Nm sigaction 38.Nd software signal facilities 39.Sh SYNOPSIS 40.Fd #include <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.Em 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 . 251The 252.Em siginfo_t 253structure is a part of 254.St -p1003.1b . 255It provides much more information about the causes and 256attributes of the signal that is being delivered. 257.It Dv SA_RESTART 258If a signal is caught during the system calls listed below, 259the call may be forced to terminate 260with the error 261.Er EINTR , 262the call may return with a data transfer shorter than requested, 263or the call may be restarted. 264Restarting of pending calls is requested 265by setting the 266.Dv SA_RESTART 267bit in 268.Ar sa_flags . 269The affected system calls include 270.Xr read 2 , 271.Xr write 2 , 272.Xr sendto 2 , 273.Xr recvfrom 2 , 274.Xr sendmsg 2 275and 276.Xr recvmsg 2 277on a communications channel or a slow device (such as a terminal, 278but not a regular file) 279and during a 280.Xr wait 2 281or 282.Xr ioctl 2 . 283However, calls that have already committed are not restarted, 284but instead return a partial success (for example, a short read count). 285.El 286.Pp 287After a 288.Xr fork 2 289or 290.Xr vfork 2 , 291all signals, the signal mask, the signal stack, 292and the restart/interrupt flags are inherited by the child. 293.Pp 294.Xr execve 2 295reinstates the default 296action for all signals which were caught and 297resets all signals to be caught on the user stack. 298Ignored signals remain ignored; 299the signal mask remains the same; 300signals that restart pending system calls continue to do so. 301.Pp 302The following is a list of all signals 303with names as in the include file 304.In signal.h : 305.Bl -column "SIGVTALARM" "create core image" "Description" 306.It Sy "Name" Ta Sy "Default Action" Ta Sy "Description" 307.It Dv SIGHUP Ta "terminate process" Ta "terminal line hangup" 308.It Dv SIGINT Ta "terminate process" Ta "interrupt program" 309.It Dv SIGQUIT Ta "create core image" Ta "quit program" 310.It Dv SIGILL Ta "create core image" Ta "illegal instruction" 311.It Dv SIGTRAP Ta "create core image" Ta "trace trap" 312.It Dv SIGABRT Ta "create core image" Ta "abort(3) call (formerly SIGIOT)" 313.It Dv SIGEMT Ta "create core image" Ta "emulate instruction executed" 314.It Dv SIGFPE Ta "create core image" Ta "floating-point exception" 315.It Dv SIGKILL Ta "terminate process" Ta "kill program (cannot be caught or ignored)" 316.It Dv SIGBUS Ta "create core image" Ta "bus error" 317.It Dv SIGSEGV Ta "create core image" Ta "segmentation violation" 318.It Dv SIGSYS Ta "create core image" Ta "system call given invalid argument" 319.It Dv SIGPIPE Ta "terminate process" Ta "write on a pipe with no reader" 320.It Dv SIGALRM Ta "terminate process" Ta "real-time timer expired" 321.It Dv SIGTERM Ta "terminate process" Ta "software termination signal" 322.It Dv SIGURG Ta "discard signal" Ta "urgent condition present on socket" 323.It Dv SIGSTOP Ta "stop process" Ta "stop (cannot be caught or ignored)" 324.It Dv SIGTSTP Ta "stop process" Ta "stop signal generated from keyboard" 325.It Dv SIGCONT Ta "discard signal" Ta "continue after stop" 326.It Dv SIGCHLD Ta "discard signal" Ta "child status has changed" 327.It Dv SIGTTIN Ta "stop process" Ta "background read attempted from control terminal" 328.It Dv SIGTTOU Ta "stop process" Ta "background write attempted to control terminal" 329.It Dv SIGIO Ta "discard signal" Ta "I/O is possible on a descriptor (see" 330.Xr fcntl 2 ) 331.It Dv SIGXCPU Ta "terminate process" Ta "CPU time limit exceeded (see" 332.Xr setrlimit 2 ) 333.It Dv SIGXFSZ Ta "terminate process" Ta "file size limit exceeded (see" 334.Xr setrlimit 2 ) 335.It Dv SIGVTALRM Ta "terminate process" Ta "virtual time alarm (see" 336.Xr setitimer 2 ) 337.It Dv SIGPROF Ta "terminate process" Ta "profiling timer alarm (see" 338.Xr setitimer 2 ) 339.It Dv SIGWINCH Ta "discard signal" Ta "window size change" 340.It Dv SIGINFO Ta "discard signal" Ta "status request from keyboard" 341.It Dv SIGUSR1 Ta "terminate process" Ta "user defined signal 1" 342.It Dv SIGUSR2 Ta "terminate process" Ta "user defined signal 2" 343.It Dv SIGTHR Ta "discard signal" Ta "thread AST" 344.El 345.Sh RETURN VALUES 346A 0 value indicates that the call succeeded. 347A \-1 return value indicates an error occurred and 348.Va errno 349is set to indicate the reason. 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, struct sigcontext *scp) 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 scp 387is a pointer to the 388.Fa sigcontext 389structure (defined in 390.In signal.h ) , 391used to restore the context from before the signal. 392.Sh ERRORS 393.Fn sigaction 394will fail and no new signal handler will be installed if one 395of the following occurs: 396.Bl -tag -width Er 397.It Bq Er EFAULT 398Either 399.Fa act 400or 401.Fa oact 402points to memory that is not a valid part of the process 403address space. 404.It Bq Er EINVAL 405.Fa sig 406is not a valid signal number. 407.It Bq Er EINVAL 408An attempt is made to ignore or supply a handler for 409.Dv SIGKILL 410or 411.Dv SIGSTOP . 412.El 413.Sh SEE ALSO 414.Xr kill 1 , 415.Xr kill 2 , 416.Xr ptrace 2 , 417.Xr sigaltstack 2 , 418.Xr sigprocmask 2 , 419.Xr sigsuspend 2 , 420.Xr wait 2 , 421.Xr setjmp 3 , 422.Xr sigblock 3 , 423.Xr sigpause 3 , 424.Xr sigsetops 3 , 425.Xr sigvec 3 , 426.Xr tty 4 427.Sh STANDARDS 428The 429.Fn sigaction 430function conforms to 431.St -p1003.1-90 . 432The 433.Dv SA_ONSTACK 434and 435.Dv SA_RESTART 436flags are Berkeley extensions, as are the signals 437.Dv SIGTRAP , 438.Dv SIGEMT , 439.Dv SIGBUS , 440.Dv SIGSYS , 441.Dv SIGURG , 442.Dv SIGIO , 443.Dv SIGXCPU , 444.Dv SIGXFSZ , 445.Dv SIGVTALRM , 446.Dv SIGPROF , 447.Dv SIGWINCH , 448and 449.Dv SIGINFO . 450These signals are available on most 451.Bx Ns -derived 452systems. 453The 454.Dv SA_NODEFER 455and 456.Dv SA_RESETHAND 457flags are intended for backwards compatibility with other operating 458systems. 459The 460.Dv SA_NOCLDSTOP , 461.Dv SA_NOCLDWAIT , 462and 463.Dv SA_SIGINFO 464flags are options commonly found in other operating systems. 465The following functions are either reentrant or not interruptible 466by signals and are async-signal safe. 467Therefore applications may 468invoke them, without restriction, from signal-catching functions: 469.Pp 470Base Interfaces: 471.Pp 472.Fn _exit , 473.Fn abort , 474.Fn accept , 475.Fn access , 476.Fn alarm , 477.Fn bind , 478.Fn cfgetispeed , 479.Fn cfgetospeed , 480.Fn cfsetispeed , 481.Fn cfsetospeed , 482.Fn chdir , 483.Fn chmod , 484.Fn chown , 485.Fn clock_gettime , 486.Fn close , 487.Fn connect , 488.Fn creat , 489.Fn dup , 490.Fn dup2 , 491.Fn execl , 492.Fn execle , 493.Fn execv , 494.Fn execve , 495.Fn faccessat , 496.Fn fchdir , 497.Fn fchmod , 498.Fn fchmodat , 499.Fn fchown , 500.Fn fchownat , 501.Fn fcntl , 502.Fn fdatasync , 503.Fn fork , 504.Fn fpathconf , 505.Fn fstat , 506.Fn fstatat , 507.Fn fsync , 508.Fn ftruncate , 509.Fn futimens , 510.Fn futimes , 511.Fn getegid , 512.Fn geteuid , 513.Fn getgid , 514.Fn getgroups , 515.Fn getpeername , 516.Fn getpgrp , 517.Fn getpid , 518.Fn getppid , 519.Fn getsockname , 520.Fn getsockopt , 521.Fn getuid , 522.Fn kill , 523.Fn link , 524.Fn linkat , 525.Fn listen , 526.Fn lseek , 527.Fn lstate , 528.Fn mkdir , 529.Fn mkdirat , 530.Fn mkfifo , 531.Fn mkfifoat , 532.Fn mknod , 533.Fn mknodat , 534.Fn open , 535.Fn openat , 536.Fn pathconf , 537.Fn pause , 538.Fn pipe , 539.Fn poll , 540.Fn pselect , 541.Fn read , 542.Fn readlink , 543.Fn readlinkat , 544.Fn recv , 545.Fn recvfrom , 546.Fn recvmsg , 547.Fn rename , 548.Fn renameat , 549.Fn rmdir , 550.Fn select , 551.Fn send , 552.Fn sendmsg , 553.Fn sendto , 554.Fn setgid , 555.Fn setpgid , 556.Fn setsid , 557.Fn setsockopt , 558.Fn setuid , 559.Fn shutdown , 560.Fn sigaction , 561.Fn sigaddset , 562.Fn sigdelset , 563.Fn sigemptyset , 564.Fn sigfillset , 565.Fn sigismember , 566.Fn signal , 567.Fn sigpause , 568.Fn sigpending , 569.Fn sigprocmask , 570.Fn sigsuspend , 571.Fn sleep , 572.Fn socket , 573.Fn socketpair , 574.Fn stat , 575.Fn symlink , 576.Fn symlinkat , 577.Fn sysconf , 578.Fn tcdrain , 579.Fn tcflow , 580.Fn tcflush , 581.Fn tcgetattr , 582.Fn tcgetpgrp , 583.Fn tcsendbreak , 584.Fn tcsetattr , 585.Fn tcsetpgrp , 586.Fn time , 587.Fn times , 588.Fn umask , 589.Fn uname , 590.Fn unlink , 591.Fn unlinkat , 592.Fn utime , 593.Fn utimensat . 594.Fn utimes , 595.Fn wait , 596.Fn waitpid , 597.Fn write . 598.Pp 599.\" unimplemented functions that should be async-sig-safe, if we had them 600.\" POSIX Issue 6 additions 601.\" .Fn sockatmark . 602.\" 603.\" POSIX Issue 7 additions 604.\" .Pp 605.\" .Fn fexecve . 606.\" 607.\" Realtime Interfaces: 608.\" .Pp 609.\" .Fn aio_error , 610.\" .Fn aio_return , 611.\" .Fn aio_suspend , 612.\" .Fn sem_post , 613.\" .Fn sigqueue , 614.\" .Fn timer_getoverrun , 615.\" .Fn timer_gettime , 616.\" .Fn timer_settime . 617ANSI C Interfaces: 618.Pp 619.Fn _Exit , 620.Fn raise , 621.Fn strcat , 622.Fn strcpy , 623.Fn strncat , 624.Fn strncpy , 625and perhaps some others. 626.Pp 627Extension Interfaces: 628.Pp 629.Fn chflags , 630.Fn fchflags , 631.Fn getentropy , 632.Fn getresgid , 633.Fn getresuid , 634.Fn ppoll , 635.Fn setresgid , 636.Fn setresuid , 637.Fn strlcat , 638.Fn strlcpy , 639.Fn wait3 , 640.Fn wait4 . 641.Pp 642In addition, access and updates to 643.Va errno 644are guaranteed to be safe. 645Most functions not in the above lists are considered to be unsafe 646with respect to signals. 647That is to say, the behaviour of such functions when called from 648a signal handler is undefined. 649In general though, signal handlers should do little more than set a 650flag, ideally of type volatile sig_atomic_t; most other actions are not safe. 651.Pp 652Additionally, it is advised that signal handlers guard against 653modification of the external symbol 654.Va errno 655by the above functions, saving it at entry and restoring 656it on return, thus: 657.Bd -literal -offset indent 658void 659handler(int sig) 660{ 661 int save_errno = errno; 662 663 ... 664 errno = save_errno; 665} 666.Ed 667.Pp 668The functions below are async-signal-safe in 669.Ox 670except when used with floating-point arguments or directives, 671but are probably unsafe on other systems: 672.Pp 673.Bl -tag -offset indent -compact -width foofoofoofoo 674.It Fn dprintf 675Safe. 676.It Fn vdprintf 677Safe. 678.It Fn snprintf 679Safe. 680.It Fn vsnprintf 681Safe. 682.It Fn syslog_r 683Safe if the 684.Va syslog_data 685struct is initialized as a local variable. 686.El 687