1.\" $OpenBSD: sigaction.2,v 1.42 2005/09/06 22:13:19 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 April 3, 1994 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.Pp 42.Bd -literal 43struct sigaction { 44 union { /* signal handler */ 45 void (*__sa_handler)(int); 46 void (*__sa_sigaction)(int, siginfo_t *, void *); 47 } __sigaction_u; 48 sigset_t sa_mask; /* signal mask to apply */ 49 int sa_flags; /* see signal options below */ 50}; 51.Ed 52.Pp 53.Fd #define sa_handler __sigaction_u.__sa_handler 54.Fd #define sa_sigaction __sigaction_u.__sa_sigaction 55.Ft int 56.Fn sigaction "int sig" "const struct sigaction *act" "struct sigaction *oact" 57.Sh DESCRIPTION 58The system defines a set of signals that may be delivered to a process. 59Signal delivery resembles the occurrence of a hardware interrupt: 60the signal is normally blocked from further occurrence, the current process 61context is saved, and a new one is built. 62A process may specify a 63.Em handler 64to which a signal is delivered, or specify that a signal is to be 65.Em ignored . 66A process may also specify that a default action is to be taken 67by the system when a signal occurs. 68A signal may also be 69.Em blocked , 70in which case its delivery is postponed until it is 71.Em unblocked . 72The action to be taken on delivery is determined at the time 73of delivery. 74Normally, signal handlers execute on the current stack 75of the process. 76This may be changed, on a per-handler basis, 77so that signals are taken on a special 78.Em "signal stack" . 79.Pp 80Signal routines normally execute with the signal that caused their 81invocation 82.Em blocked , 83but other signals may yet occur. 84A global 85.Em "signal mask" 86defines the set of signals currently blocked from delivery 87to a process. 88The signal mask for a process is initialized from that of its 89parent (normally empty). 90It may be changed with a 91.Xr sigprocmask 2 92call, or when a signal is delivered to the process. 93.Pp 94When a signal 95condition arises for a process, the signal is added to a set of 96signals pending for the process. 97If the signal is not currently 98.Em blocked 99by the process then it is delivered to the process. 100Signals may be delivered any time a process enters the operating system 101(e.g., during a system call, page fault or trap, or clock interrupt). 102If multiple signals are ready to be delivered at the same time, 103any signals that could be caused by traps are delivered first. 104Additional signals may be processed at the same time, with each 105appearing to interrupt the handlers for the previous signals 106before their first instructions. 107The set of pending signals is returned by the 108.Xr sigpending 2 109function. 110When a caught signal 111is delivered, the current state of the process is saved, 112a new signal mask is calculated (as described below), 113and the signal handler is invoked. 114The call to the handler is arranged so that if the signal handling routine 115returns normally the process will resume execution in the context from 116before the signal's delivery. 117If the process wishes to resume in a different context, then it 118must arrange to restore the previous context itself. 119.Pp 120When a signal is delivered to a process a new signal mask is 121installed for the duration of the process' signal handler 122(or until a 123.Xr sigprocmask 2 124call is made). 125This mask is formed by taking the union of the current signal mask set, 126the signal to be delivered, and the signal mask 127.Em sa_mask 128associated with the handler to be invoked. 129.Pp 130.Fn sigaction 131assigns an action for a signal specified by 132.Fa sig . 133If 134.Fa act 135is non-zero, it 136specifies an action 137.Pf ( Dv SIG_DFL , 138.Dv SIG_IGN , 139or a handler routine) and mask 140to be used when delivering the specified signal. 141If 142.Fa oact 143is non-zero, the previous handling information for the signal 144is returned to the user. 145.Pp 146Once a signal handler is installed, it normally remains installed 147until another 148.Fn sigaction 149call is made, or an 150.Xr execve 2 151is performed. 152The value of 153.Fa sa_handler 154(or, if the 155.Dv SA_SIGINFO 156flag is set, the value of 157.Fa sa_sigaction 158instead) indicates what action should be performed when a 159signal arrives. 160A signal-specific default action may be reset by 161setting 162.Fa sa_handler 163to 164.Dv SIG_DFL . 165Alternately, if the 166.Dv SA_RESETHAND 167flag is set the default action will be reinstated when the signal 168is first posted. 169The defaults are process termination, possibly with core dump; 170no action; stopping the process; or continuing the process. 171See the signal list below for each signal's default action. 172If 173.Fa sa_handler 174is 175.Dv SIG_DFL , 176the default action for the signal is to discard the signal, 177and if a signal is pending, 178the pending signal is discarded even if the signal is masked. 179If 180.Fa sa_handler 181is set to 182.Dv SIG_IGN , 183current and pending instances 184of the signal are ignored and discarded. 185If 186.Fa sig 187is 188.Dv SIGCHLD 189and 190.Fa sa_handler 191is set to 192.Dv SIG_IGN , 193the 194.Dv SA_NOCLDWAIT 195flag (described below) is implied. 196.Pp 197Options may be specified by setting 198.Em sa_flags . 199The meaning of the various bits is as follows: 200.Bl -tag -offset indent -width SA_RESETHANDXX 201.It Dv SA_NOCLDSTOP 202If this bit is set when installing a catching function 203for the 204.Dv SIGCHLD 205signal, 206the 207.Dv SIGCHLD 208signal will be generated only when a child process exits, 209not when a child process stops. 210.It Dv SA_NOCLDWAIT 211If this bit is set when calling 212.Fn sigaction 213for the 214.Dv SIGCHLD 215signal, the system will not create zombie processes when children of 216the calling process exit. 217If the calling process subsequently issues a 218.Xr wait 2 219(or equivalent), it blocks until all of the calling process's child 220processes terminate, and then returns a value of \-1 with 221.Va errno 222set to 223.Er ECHILD . 224.It Dv SA_ONSTACK 225If this bit is set, the system will deliver the signal to the process 226on a 227.Em "signal stack" , 228specified with 229.Xr sigaltstack 2 . 230.It Dv SA_NODEFER 231If this bit is set, further occurrences of the delivered signal are 232not masked during the execution of the handler. 233.It Dv SA_RESETHAND 234If this bit is set, the handler is reset back to 235.Dv SIG_DFL 236at the moment the signal is delivered. 237.It Dv SA_SIGINFO 238If this bit is set, the 2nd argument of the handler is set to 239be a pointer to a 240.Em siginfo_t 241structure as described in 242.Aq Pa sys/siginfo.h . 243The 244.Em siginfo_t 245structure is a part of 246.St -p1003.1b . 247It provides much more information about the causes and 248attributes of the signal that is being delivered. 249.It Dv SA_RESTART 250If a signal is caught during the system calls listed below, 251the call may be forced to terminate 252with the error 253.Er EINTR , 254the call may return with a data transfer shorter than requested, 255or the call may be restarted. 256Restarting of pending calls is requested 257by setting the 258.Dv SA_RESTART 259bit in 260.Ar sa_flags . 261The affected system calls include 262.Xr read 2 , 263.Xr write 2 , 264.Xr sendto 2 , 265.Xr recvfrom 2 , 266.Xr sendmsg 2 267and 268.Xr recvmsg 2 269on a communications channel or a slow device (such as a terminal, 270but not a regular file) 271and during a 272.Xr wait 2 273or 274.Xr ioctl 2 . 275However, calls that have already committed are not restarted, 276but instead return a partial success (for example, a short read count). 277.El 278.Pp 279After a 280.Xr fork 2 281or 282.Xr vfork 2 , 283all signals, the signal mask, the signal stack, 284and the restart/interrupt flags are inherited by the child. 285.Pp 286.Xr execve 2 287reinstates the default 288action for all signals which were caught and 289resets all signals to be caught on the user stack. 290Ignored signals remain ignored; 291the signal mask remains the same; 292signals that restart pending system calls continue to do so. 293.Pp 294The following is a list of all signals 295with names as in the include file 296.Aq Pa signal.h : 297.Bl -column SIGVTALARMXX "create core imagexxx" 298.It Sy " NAME " " Default Action " " Description" 299.It Dv SIGHUP No " terminate process" " terminal line hangup" 300.It Dv SIGINT No " terminate process" " interrupt program" 301.It Dv SIGQUIT No " create core image" " quit program" 302.It Dv SIGILL No " create core image" " illegal instruction" 303.It Dv SIGTRAP No " create core image" " trace trap" 304.It Dv SIGABRT No " create core image" Xr abort 3 305call (formerly 306.Dv SIGIOT ) 307.It Dv SIGEMT No " create core image" " emulate instruction executed" 308.It Dv SIGFPE No " create core image" " floating-point exception" 309.It Dv SIGKILL No " terminate process" " kill program (cannot be caught or ignored)" 310.It Dv SIGBUS No " create core image" " bus error" 311.It Dv SIGSEGV No " create core image" " segmentation violation" 312.It Dv SIGSYS No " create core image" " system call given invalid argument" 313.It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" 314.It Dv SIGALRM No " terminate process" " real-time timer expired" 315.It Dv SIGTERM No " terminate process" " software termination signal" 316.It Dv SIGURG No " discard signal" " urgent condition present on socket" 317.It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" 318.It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" 319.It Dv SIGCONT No " discard signal" " continue after stop" 320.It Dv SIGCHLD No " discard signal" " child status has changed" 321.It Dv SIGTTIN No " stop process" " background read attempted from control terminal" 322.It Dv SIGTTOU No " stop process" " background write attempted to control terminal" 323.It Dv SIGIO No " discard signal" Tn " I/O" 324is possible on a descriptor (see 325.Xr fcntl 2 ) 326.It Dv SIGXCPU No " terminate process" " CPU time limit exceeded (see" 327.Xr setrlimit 2 ) 328.It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" 329.Xr setrlimit 2 ) 330.It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" 331.Xr setitimer 2 ) 332.It Dv SIGPROF No " terminate process" " profiling timer alarm (see" 333.Xr setitimer 2 ) 334.It Dv SIGWINCH No " discard signal" " window size change" 335.It Dv SIGINFO No " discard signal" " status request from keyboard" 336.It Dv SIGUSR1 No " terminate process" " user defined signal 1" 337.It Dv SIGUSR2 No " terminate process" " user defined signal 2" 338.El 339.Sh NOTE 340The 341.Fa sa_mask 342field specified in 343.Fa act 344is not allowed to block 345.Dv SIGKILL 346or 347.Dv SIGSTOP . 348Any attempt to do so will be silently ignored. 349.Pp 350The following functions are either reentrant or not interruptible 351by signals and are async-signal safe. 352Therefore applications may invoke them, without restriction, from 353signal-catching functions: 354.Bd -ragged -offset indent 355.Xr _exit 2 , 356.Xr access 2 , 357.Xr alarm 3 , 358.Xr cfgetispeed 3 , 359.Xr cfgetospeed 3 , 360.Xr cfsetispeed 3 , 361.Xr cfsetospeed 3 , 362.Xr chdir 2 , 363.Xr chmod 2 , 364.Xr chown 2 , 365.Xr close 2 , 366.Xr creat 3 , 367.Xr dup 2 , 368.Xr dup2 2 , 369.Xr execle 3 , 370.Xr execve 2 , 371.Xr fcntl 2 , 372.Xr fork 2 , 373.Xr fpathconf 2 , 374.Xr fstat 2 , 375.Xr fsync 2 , 376.Xr getegid 2 , 377.Xr geteuid 2 , 378.Xr getgid 2 , 379.Xr getgroups 2 , 380.Xr getpgrp 2 , 381.Xr getpid 2 , 382.Xr getppid 2 , 383.Xr getuid 2 , 384.Xr kill 2 , 385.Xr link 2 , 386.Xr lseek 2 , 387.Xr mkdir 2 , 388.Xr mkfifo 2 , 389.Xr open 2 , 390.Xr pathconf 2 , 391.Xr pause 3 , 392.Xr pipe 2 , 393.Xr raise 3 , 394.Xr read 2 , 395.Xr rename 2 , 396.Xr rmdir 2 , 397.Xr setgid 2 , 398.Xr setpgid 2 , 399.Xr setsid 2 , 400.Xr setuid 2 , 401.Xr sigaction 2 , 402.Xr sigaddset 3 , 403.Xr sigdelset 3 , 404.Xr sigemptyset 3 , 405.Xr sigfillset 3 , 406.Xr sigismember 3 , 407.Xr signal 3 , 408.Xr sigpause 3 , 409.Xr sigpending 2 , 410.Xr sigprocmask 2 , 411.Xr sigsuspend 2 , 412.Xr sleep 3 , 413.Xr stat 2 , 414.Xr sysconf 3 , 415.Xr tcdrain 3 , 416.Xr tcflow 3 , 417.Xr tcflush 3 , 418.Xr tcgetattr 3 , 419.Xr tcgetpgrp 3 , 420.Xr tcsendbreak 3 , 421.Xr tcsetattr 3 , 422.Xr tcsetpgrp 3 , 423.Xr time 3 , 424.Xr times 3 , 425.Xr umask 2 , 426.Xr uname 3 , 427.Xr unlink 2 , 428.Xr utime 3 , 429.Xr wait 2 , 430.Xr waitpid 2 , 431.Xr write 2 . 432.\" .Fn aio_error , 433.\" .Fn clock_gettime , 434.\" .Fn timer_getoverrun , 435.\" .Fn aio_return , 436.\" .Fn fdatasync , 437.\" .Fn sigqueue , 438.\" .Fn timer_gettime , 439.\" .Fn aio_suspend , 440.\" .Fn sem_post , 441.\" .Fn timer_settime . 442.Ed 443.Pp 444Please see 445.Xr signal 3 446for a more detailed list. 447.Pp 448All functions not in the above list are considered to be unsafe 449with respect to signals. 450That is to say, the behaviour of such functions when called from 451a signal handler is undefined. 452In general though, signal handlers should do little more than set a 453flag; most other actions are not safe. 454.Pp 455Additionally, it is advised that signal handlers guard against 456modification of the external symbol 457.Va errno 458by the above functions, saving it at entry and restoring 459it on return, thus: 460.Bd -literal -offset indent 461void 462handler(sig) 463{ 464 int save_errno = errno; 465 466 ... 467 errno = save_errno; 468} 469.Ed 470.Sh RETURN VALUES 471A 0 value indicates that the call succeeded. 472A \-1 return value indicates an error occurred and 473.Va errno 474is set to indicate the reason. 475.Sh EXAMPLES 476The handler routine can be declared: 477.Bd -literal -offset indent 478void 479handler(sig) 480 int sig; 481.Pp 482.Ed 483If the 484.Dv SA_SIGINFO 485option is enabled, the canonical way to declare it is: 486.Bd -literal -offset indent 487void 488handler(sig, sip, scp) 489 int sig; 490 siginfo_t *sip; 491 struct sigcontext *scp; 492.Ed 493.Pp 494Here 495.Fa sig 496is the signal number, into which the hardware faults and traps are mapped. 497If the 498.Dv SA_SIGINFO 499option is set, 500.Fa sip 501is a pointer to a 502.Dv siginfo_t 503as described in 504.Aq Pa sys/siginfo.h . 505If 506.Dv SA_SIGINFO 507is not set, this pointer will be 508.Dv NULL 509instead. 510The function specified in 511.Fa sa_sigaction 512will be called instead of the function specified by 513.Fa sa_handler 514(Note that in some implementations these are in fact the same). 515.Fa scp 516is a pointer to the 517.Fa sigcontext 518structure (defined in 519.Aq Pa signal.h ) , 520used to restore the context from before the signal. 521.Sh ERRORS 522.Fn sigaction 523will fail and no new signal handler will be installed if one 524of the following occurs: 525.Bl -tag -width Er 526.It Bq Er EFAULT 527Either 528.Fa act 529or 530.Fa oact 531points to memory that is not a valid part of the process 532address space. 533.It Bq Er EINVAL 534.Fa sig 535is not a valid signal number. 536.It Bq Er EINVAL 537An attempt is made to ignore or supply a handler for 538.Dv SIGKILL 539or 540.Dv SIGSTOP . 541.El 542.Sh SEE ALSO 543.Xr kill 1 , 544.Xr kill 2 , 545.Xr ptrace 2 , 546.Xr sigaltstack 2 , 547.Xr sigprocmask 2 , 548.Xr sigsuspend 2 , 549.Xr wait 2 , 550.Xr setjmp 3 , 551.Xr sigblock 3 , 552.Xr sigpause 3 , 553.Xr sigsetops 3 , 554.Xr sigvec 3 , 555.Xr tty 4 556.Sh STANDARDS 557The 558.Fn sigaction 559function conforms to 560.St -p1003.1-90 . 561The 562.Dv SA_ONSTACK 563and 564.Dv SA_RESTART 565flags are Berkeley extensions, as are the signals 566.Dv SIGTRAP , 567.Dv SIGEMT , 568.Dv SIGBUS , 569.Dv SIGSYS , 570.Dv SIGURG , 571.Dv SIGIO , 572.Dv SIGXCPU , 573.Dv SIGXFSZ , 574.Dv SIGVTALRM , 575.Dv SIGPROF , 576.Dv SIGWINCH , 577and 578.Dv SIGINFO . 579These signals are available on most 580.Tn BSD Ns \-derived 581systems. 582The 583.Dv SA_NODEFER 584and 585.Dv SA_RESETHAND 586flags are intended for backwards compatibility with other operating 587systems. 588The 589.Dv SA_NOCLDSTOP , 590.Dv SA_NOCLDWAIT , 591and 592.Dv SA_SIGINFO 593flags are options commonly found in other operating systems. 594The following functions are either reentrant or not interruptible 595by signals and are async-signal safe. 596Therefore applications may 597invoke them, without restriction, from signal-catching functions: 598.Pp 599Base Interfaces: 600.Pp 601.Fn _exit , 602.Fn access , 603.Fn alarm , 604.Fn cfgetispeed , 605.Fn cfgetospeed , 606.Fn cfsetispeed , 607.Fn cfsetospeed , 608.Fn chdir , 609.Fn chmod , 610.Fn chown , 611.Fn close , 612.Fn creat , 613.Fn dup , 614.Fn dup2 , 615.Fn execle , 616.Fn execve , 617.Fn fcntl , 618.Fn fork , 619.Fn fpathconf , 620.Fn fstat , 621.Fn fsync , 622.Fn getegid , 623.Fn geteuid , 624.Fn getgid , 625.Fn getgroups , 626.Fn getpgrp , 627.Fn getpid , 628.Fn getppid , 629.Fn getuid , 630.Fn kill , 631.Fn link , 632.Fn lseek , 633.Fn mkdir , 634.Fn mkfifo , 635.Fn open , 636.Fn pathconf , 637.Fn pause , 638.Fn pipe , 639.Fn raise , 640.Fn read , 641.Fn rename , 642.Fn rmdir , 643.Fn setgid , 644.Fn setpgid , 645.Fn setsid , 646.Fn setuid , 647.Fn sigaction , 648.Fn sigaddset , 649.Fn sigdelset , 650.Fn sigemptyset , 651.Fn sigfillset , 652.Fn sigismember , 653.Fn signal , 654.Fn sigpending , 655.Fn sigprocmask , 656.Fn sigsuspend , 657.Fn sleep , 658.Fn stat , 659.Fn sysconf , 660.Fn tcdrain , 661.Fn tcflow , 662.Fn tcflush , 663.Fn tcgetattr , 664.Fn tcgetpgrp , 665.Fn tcsendbreak , 666.Fn tcsetattr , 667.Fn tcsetpgrp , 668.Fn time , 669.Fn times , 670.Fn umask , 671.Fn uname , 672.Fn unlink , 673.Fn utime , 674.Fn wait , 675.Fn waitpid , 676.Fn write . 677.Pp 678.\" Realtime Interfaces: 679.\" .Pp 680.\" .Fn aio_error , 681.\" .Fn aio_return , 682.\" .Fn aio_suspend , 683.\" .Fn clock_gettime , 684.\" .Fn fdatasync , 685.\" .Fn sem_post , 686.\" .Fn sigpause , 687.\" .Fn sigqueue , 688.\" .Fn sigset , 689.\" .Fn timer_getoverrun , 690.\" .Fn timer_gettime , 691.\" .Fn timer_settime . 692.\" .Pp 693ANSI C Interfaces: 694.Pp 695.Fn strcat , 696.Fn strcpy , 697.Fn strncat , 698.Fn strncpy , 699and perhaps some others. 700.Pp 701Extension Interfaces: 702.Pp 703.Fn strlcat , 704.Fn strlcpy . 705.Pp 706Most functions not in the above lists are considered to be unsafe 707with respect to signals. 708That is to say, the behaviour of such functions when called from 709a signal handler is undefined. 710.Pp 711Additionally, inside the signal handler it is also considered safer to 712make a copy of the global variable 713.Va errno 714and restore it before returning from the signal handler. 715.Pp 716A few other functions are signal race safe in 717.Ox 718but probably not on other systems: 719.Pp 720.Bl -tag -offset indent -compact -width foofoofoofoo 721.It Fn snprintf 722Safe. 723.It Fn vsnprintf 724Safe. 725.It Fn syslog_r 726Safe if the 727.Va syslog_data 728struct is initialized as a local variable. 729.El 730