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