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