1.\" Copyright (c) 1980, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From: @(#)sigaction.2 8.2 (Berkeley) 4/3/94 33.\" $FreeBSD: src/lib/libc/sys/sigaction.2,v 1.22.2.10 2002/12/29 16:35:34 schweikh Exp $ 34.\" $DragonFly: src/lib/libc/sys/sigaction.2,v 1.8 2007/06/30 19:03:52 swildner Exp $ 35.\" 36.Dd April 3, 1994 37.Dt SIGACTION 2 38.Os 39.Sh NAME 40.Nm sigaction 41.Nd software signal facilities 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In signal.h 46.Bd -literal 47struct sigaction { 48 /* 49 * Signal handler function if flag SA_SIGINFO is not used and for 50 * SIG_DFL and SIG_IGN. 51 */ 52 void (*sa_handler)(int); 53 54 /* Signal handler function if flag SA_SIGINFO is used */ 55 void (*sa_sigaction)(int, siginfo_t *, void *); 56 57 sigset_t sa_mask; /* signal mask to apply */ 58 int sa_flags; /* see signal options below */ 59}; 60.Ed 61.Ft int 62.Fn sigaction "int sig" "const struct sigaction *act" "struct sigaction *oact" 63.Sh DESCRIPTION 64The system defines a set of signals that may be delivered to a process. 65Signal delivery resembles the occurrence of a hardware interrupt: 66the signal is normally blocked from further occurrence, the current process 67context is saved, and a new one is built. A process may specify a 68.Em handler 69to which a signal is delivered, or specify that a signal is to be 70.Em ignored . 71A process may also specify that a default action is to be taken 72by the system when a signal occurs. 73A signal may also be 74.Em blocked , 75in which case its delivery is postponed until it is 76.Em unblocked . 77The action to be taken on delivery is determined at the time 78of delivery. 79Normally, signal handlers execute on the current stack 80of the process. This 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. The signal mask for a process is initialized 92from that of its parent (normally empty). It 93may be changed with a 94.Xr sigprocmask 2 95call, or when a signal is delivered to the process. 96.Pp 97When a signal 98condition arises for a process, the signal is added to a set of 99signals pending for the process. 100If the signal is not currently 101.Em blocked 102by the process then it is delivered to the process. 103Signals may be delivered any time a process enters the operating system 104(e.g., during a system call, page fault or trap, or clock interrupt). 105If multiple signals are ready to be delivered at the same time, 106any signals that could be caused by traps are delivered first. 107Additional signals may be processed at the same time, with each 108appearing to interrupt the handlers for the previous signals 109before their first instructions. 110The set of pending signals is returned by the 111.Xr sigpending 2 112function. 113When a caught signal 114is delivered, the current state of the process is saved, 115a new signal mask is calculated (as described below), 116and the signal handler is invoked. The call to the handler 117is arranged so that if the signal handling routine returns 118normally the process will resume execution in the context 119from before the signal's delivery. 120If the process wishes to resume in a different context, then it 121must arrange to restore the previous context itself. 122.Pp 123When a signal is delivered to a process a new signal mask is 124installed for the duration of the process' signal handler 125(or until a 126.Xr sigprocmask 2 127call is made). 128This mask is formed by taking the union of the current signal mask set, 129the signal to be delivered, and 130the signal mask associated with the handler to be invoked. 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. 154A signal-specific default action may be reset by 155setting 156.Fa sa_handler 157to 158.Dv SIG_DFL . 159The defaults are process termination, possibly with core dump; 160no action; stopping the process; or continuing the process. 161See the signal list below for each signal's default action. 162If 163.Fa sa_handler 164is 165.Dv SIG_DFL , 166the default action for the signal is to discard the signal, 167and if a signal is pending, 168the pending signal is discarded even if the signal is masked. 169If 170.Fa sa_handler 171is set to 172.Dv SIG_IGN 173current and pending instances 174of the signal are ignored and discarded. 175.Pp 176Options may be specified by setting 177.Em sa_flags . 178The meaning of the various bits is as follows: 179.Bl -tag -offset indent -width SA_RESETHANDXX 180.It Dv SA_NOCLDSTOP 181If this bit is set when installing a catching function 182for the 183.Dv SIGCHLD 184signal, 185the 186.Dv SIGCHLD 187signal will be generated only when a child process exits, 188not when a child process stops. 189.It Dv SA_NOCLDWAIT 190If this bit is set when calling 191.Fn sigaction 192for the 193.Dv SIGCHLD 194signal, the system will not create zombie processes when children of 195the calling process exit. If the calling process subsequently issues 196a 197.Xr wait 2 198(or equivalent), it blocks until all of the calling process's child 199processes terminate, and then returns a value of -1 with 200.Va errno 201set to 202.Er ECHILD . 203.It Dv SA_ONSTACK 204If this bit is set, the system will deliver the signal to the process 205on a 206.Em "signal stack" , 207specified with 208.Xr sigaltstack 2 . 209.It Dv SA_NODEFER 210If this bit is set, further occurrences of the delivered signal are 211not masked during the execution of the handler. 212.It Dv SA_RESETHAND 213If this bit is set, the handler is reset back to 214.Dv SIG_DFL 215at the moment the signal is delivered. 216.It Dv SA_SIGINFO 217If this bit is set, the handler function is assumed to be pointed to by the 218.Dv sa_sigaction 219member of struct sigaction and should match the prototype shown above or as 220below in 221.Sx EXAMPLES . 222This bit should not be set when assigning 223.Dv SIG_DFL 224or 225.Dv SIG_IGN . 226.El 227.Pp 228If a signal is caught during the system calls listed below, 229the call may be forced to terminate 230with the error 231.Er EINTR , 232the call may return with a data transfer shorter than requested, 233or the call may be restarted. 234Restart of pending calls is requested 235by setting the 236.Dv SA_RESTART 237bit in 238.Ar sa_flags . 239The affected system calls include 240.Xr open 2 , 241.Xr read 2 , 242.Xr write 2 , 243.Xr sendto 2 , 244.Xr recvfrom 2 , 245.Xr sendmsg 2 246and 247.Xr recvmsg 2 248on a communications channel or a slow device (such as a terminal, 249but not a regular file) 250and during a 251.Xr wait 2 252or 253.Xr ioctl 2 . 254However, calls that have already committed are not restarted, 255but instead return a partial success (for example, a short read count). 256.Pp 257After a 258.Xr fork 2 259or 260.Xr vfork 2 261all signals, the signal mask, the signal stack, 262and the restart/interrupt flags are inherited by the child. 263.Pp 264.Xr Execve 2 265reinstates the default 266action for all signals which were caught and 267resets all signals to be caught on the user stack. 268Ignored signals remain ignored; 269the signal mask remains the same; 270signals that restart pending system calls continue to do so. 271.Pp 272The following is a list of all signals 273with names as in the include file 274.In signal.h : 275.Bl -column SIGVTALARMXX "create core imagexxx" 276.It Sy "NAME Default Action Description" 277.It Dv SIGHUP No " terminate process" " terminal line hangup" 278.It Dv SIGINT No " terminate process" " interrupt program" 279.It Dv SIGQUIT No " create core image" " quit program" 280.It Dv SIGILL No " create core image" " illegal instruction" 281.It Dv SIGTRAP No " create core image" " trace trap" 282.It Dv SIGABRT No " create core image" Ta Xr abort 3 283call (formerly 284.Dv SIGIOT ) 285.It Dv SIGEMT No " create core image" " emulate instruction executed" 286.It Dv SIGFPE No " create core image" " floating-point exception" 287.It Dv SIGKILL No " terminate process" " kill program" 288.It Dv SIGBUS No " create core image" " bus error" 289.It Dv SIGSEGV No " create core image" " segmentation violation" 290.It Dv SIGSYS No " create core image" " non-existent system call invoked" 291.It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" 292.It Dv SIGALRM No " terminate process" " real-time timer expired" 293.It Dv SIGTERM No " terminate process" " software termination signal" 294.It Dv SIGURG No " discard signal" " urgent condition present on socket" 295.It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" 296.It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" 297.It Dv SIGCONT No " discard signal" " continue after stop" 298.It Dv SIGCHLD No " discard signal" " child status has changed" 299.It Dv SIGTTIN No " stop process" " background read attempted from control terminal" 300.It Dv SIGTTOU No " stop process" " background write attempted to control terminal" 301.It Dv SIGIO No " discard signal" Tn " I/O" 302is possible on a descriptor (see 303.Xr fcntl 2 ) 304.It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" 305.Xr setrlimit 2 ) 306.It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" 307.Xr setrlimit 2 ) 308.It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" 309.Xr setitimer 2 ) 310.It Dv SIGPROF No " terminate process" " profiling timer alarm (see" 311.Xr setitimer 2 ) 312.It Dv SIGWINCH No " discard signal" " Window size change" 313.It Dv SIGINFO No " discard signal" " status request from keyboard" 314.It Dv SIGUSR1 No " terminate process" " User defined signal 1" 315.It Dv SIGUSR2 No " terminate process" " User defined signal 2" 316.El 317.Sh NOTE 318The 319.Fa sa_mask 320field specified in 321.Fa act 322is not allowed to block 323.Dv SIGKILL 324or 325.Dv SIGSTOP . 326Any attempt to do so will be silently ignored. 327.Pp 328The following functions are either reentrant or not interruptible 329by signals and are async-signal safe. 330Therefore applications may 331invoke them, without restriction, from signal-catching functions: 332.Pp 333Base Interfaces: 334.Pp 335.Fn _exit , 336.Fn access , 337.Fn alarm , 338.Fn cfgetispeed , 339.Fn cfgetospeed , 340.Fn cfsetispeed , 341.Fn cfsetospeed , 342.Fn chdir , 343.Fn chmod , 344.Fn chown , 345.Fn close , 346.Fn creat , 347.Fn dup , 348.Fn dup2 , 349.Fn execle , 350.Fn execve , 351.Fn fcntl , 352.Fn fork , 353.Fn fpathconf , 354.Fn fstat , 355.Fn fsync , 356.Fn getegid , 357.Fn geteuid , 358.Fn getgid , 359.Fn getgroups , 360.Fn getpgrp , 361.Fn getpid , 362.Fn getppid , 363.Fn getuid , 364.Fn kill , 365.Fn link , 366.Fn lseek , 367.Fn mkdir , 368.Fn mkfifo , 369.Fn open , 370.Fn pathconf , 371.Fn pause , 372.Fn pipe , 373.Fn raise , 374.Fn read , 375.Fn rename , 376.Fn rmdir , 377.Fn setgid , 378.Fn setpgid , 379.Fn setsid , 380.Fn setuid , 381.Fn sigaction , 382.Fn sigaddset , 383.Fn sigdelset , 384.Fn sigemptyset , 385.Fn sigfillset , 386.Fn sigismember , 387.Fn signal , 388.Fn sigpending , 389.Fn sigprocmask , 390.Fn sigsuspend , 391.Fn sleep , 392.Fn stat , 393.Fn sysconf , 394.Fn tcdrain , 395.Fn tcflow , 396.Fn tcflush , 397.Fn tcgetattr , 398.Fn tcgetpgrp , 399.Fn tcsendbreak , 400.Fn tcsetattr , 401.Fn tcsetpgrp , 402.Fn time , 403.Fn times , 404.Fn umask , 405.Fn uname , 406.Fn unlink , 407.Fn utime , 408.Fn wait , 409.Fn waitpid , 410.Fn write . 411.Pp 412Realtime Interfaces: 413.Pp 414.Fn aio_error , 415.Fn clock_gettime , 416.Fn sigpause , 417.Fn timer_getoverrun , 418.Fn aio_return , 419.Fn fdatasync , 420.Fn sigqueue , 421.Fn timer_gettime , 422.Fn aio_suspend , 423.Fn sem_post , 424.Fn sigset , 425.Fn timer_settime . 426.Pp 427All functions not in the above lists are considered to be unsafe 428with respect to signals. That is to say, the behaviour of such 429functions when called from a signal handler is undefined. 430.Sh RETURN VALUES 431.Rv -std sigaction 432.Sh EXAMPLES 433There are three possible prototypes the handler may match: 434.Bl -tag -offset indent -width short 435.It ANSI C: 436.Ft void 437.Fn handler int ; 438.It Traditional BSD style: 439.Ft void 440.Fn handler int "int code" "struct sigcontext *scp" ; 441.It POSIX SA_SIGINFO: 442.Ft void 443.Fn handler int "siginfo_t *info" "ucontext_t *uap" ; 444.El 445.Pp 446The handler function should match the SA_SIGINFO prototype if the 447SA_SIGINFO bit is set in flags. 448It then should be pointed to by the 449.Dv sa_sigaction 450member of 451.Dv struct sigaction . 452Note that you should not assign SIG_DFL or SIG_IGN this way. 453.Pp 454If the SA_SIGINFO flag is not set, the handler function should match 455either the ANSI C or traditional 456.Bx 457prototype and be pointed to by 458the 459.Dv sa_handler 460member of 461.Dv struct sigaction . 462In practice, 463.Dx 464always sends the three arguments of the latter and since the ANSI C 465prototype is a subset, both will work. 466The 467.Dv sa_handler 468member declaration in 469.Dx 470include files is that of ANSI C (as required by POSIX), 471so a function pointer of a 472.Bx Ns -style 473function needs to be casted to 474compile without warning. 475The traditional 476.Bx 477style is not portable and since its capabilities 478are a full subset of a SA_SIGINFO handler, 479its use is deprecated. 480.Pp 481The 482.Fa sig 483argument is the signal number, one of the 484.Dv SIG... 485.In signal.h . 486.Pp 487The 488.Fa code 489argument of the 490.Bx Ns -style 491handler and the 492.Dv si_code 493member of the 494.Dv info 495argument to a SA_SIGINFO handler contain a numeric code explaining the 496cause of the signal, usually one of the 497.Dv SI_... 498values from 499.In sys/signal.h 500or codes specific to a signal, i.e. one of the 501.Dv FPE_... 502values for SIGFPE. 503.Pp 504The 505.Fa scp 506argument to a 507.Bx Ns -style 508handler points to an instance of struct 509sigcontext. 510.Pp 511The 512.Fa uap 513argument to a POSIX SA_SIGINFO handler points to an instance of 514ucontext_t. 515.Sh ERRORS 516.Fn Sigaction 517will fail and no new signal handler will be installed if one 518of the following occurs: 519.Bl -tag -width Er 520.It Bq Er EFAULT 521Either 522.Fa act 523or 524.Fa oact 525points to memory that is not a valid part of the process 526address space. 527.It Bq Er EINVAL 528.Fa Sig 529is not a valid signal number. 530.It Bq Er EINVAL 531An attempt is made to ignore or supply a handler for 532.Dv SIGKILL 533or 534.Dv SIGSTOP . 535.El 536.Sh SEE ALSO 537.Xr kill 1 , 538.Xr kill 2 , 539.Xr ptrace 2 , 540.Xr sigaltstack 2 , 541.Xr sigblock 2 , 542.Xr sigpause 2 , 543.Xr sigpending 2 , 544.Xr sigprocmask 2 , 545.Xr sigsetmask 2 , 546.Xr sigsuspend 2 , 547.Xr sigvec 2 , 548.Xr wait 2 , 549.Xr fpsetmask 3 , 550.Xr setjmp 3 , 551.Xr siginterrupt 3 , 552.Xr sigsetops 3 , 553.Xr ucontext 3 , 554.Xr tty 4 555.Sh STANDARDS 556The 557.Fn sigaction 558function call is expected to conform to 559.St -p1003.1-90 . 560The 561.Dv SA_ONSTACK 562and 563.Dv SA_RESTART 564flags are Berkeley extensions, 565as 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 . 579Those signals are available on most 580.Bx Ns \-derived 581systems. 582The 583.Dv SA_NODEFER 584and 585.Dv SA_RESETHAND 586flags are intended for backwards compatibility with other operating 587systems. The 588.Dv SA_NOCLDSTOP , 589and 590.Dv SA_NOCLDWAIT 591.\" and 592.\" SA_SIGINFO 593flags are featuring options commonly found in other operating systems. 594