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.3 2004/03/11 12:28:51 hmp 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 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 errno set to 200.Er ECHILD . 201.It Dv SA_ONSTACK 202If this bit is set, the system will deliver the signal to the process 203on a 204.Em "signal stack" , 205specified with 206.Xr sigaltstack 2 . 207.It Dv SA_NODEFER 208If this bit is set, further occurrences of the delivered signal are 209not masked during the execution of the handler. 210.It Dv SA_RESETHAND 211If this bit is set, the handler is reset back to 212.Dv SIG_DFL 213at the moment the signal is delivered. 214.It Dv SA_SIGINFO 215If this bit is set, the handler function is assumed to be pointed to by the 216.Dv sa_sigaction 217member of struct sigaction and should match the prototype shown above or as 218below in 219.Sx EXAMPLES . 220This bit should not be set when assigning 221.Dv SIG_DFL 222or 223.Dv SIG_IGN . 224.El 225.Pp 226If a signal is caught during the system calls listed below, 227the call may be forced to terminate 228with the error 229.Er EINTR , 230the call may return with a data transfer shorter than requested, 231or the call may be restarted. 232Restart of pending calls is requested 233by setting the 234.Dv SA_RESTART 235bit in 236.Ar sa_flags . 237The affected system calls include 238.Xr open 2 , 239.Xr read 2 , 240.Xr write 2 , 241.Xr sendto 2 , 242.Xr recvfrom 2 , 243.Xr sendmsg 2 244and 245.Xr recvmsg 2 246on a communications channel or a slow device (such as a terminal, 247but not a regular file) 248and during a 249.Xr wait 2 250or 251.Xr ioctl 2 . 252However, calls that have already committed are not restarted, 253but instead return a partial success (for example, a short read count). 254.Pp 255After a 256.Xr fork 2 257or 258.Xr vfork 2 259all signals, the signal mask, the signal stack, 260and the restart/interrupt flags are inherited by the child. 261.Pp 262.Xr Execve 2 263reinstates the default 264action for all signals which were caught and 265resets all signals to be caught on the user stack. 266Ignored signals remain ignored; 267the signal mask remains the same; 268signals that restart pending system calls continue to do so. 269.Pp 270The following is a list of all signals 271with names as in the include file 272.Aq Pa signal.h : 273.Bl -column SIGVTALARMXX "create core imagexxx" 274.It Sy "NAME Default Action Description" 275.It Dv SIGHUP No " terminate process" " terminal line hangup" 276.It Dv SIGINT No " terminate process" " interrupt program" 277.It Dv SIGQUIT No " create core image" " quit program" 278.It Dv SIGILL No " create core image" " illegal instruction" 279.It Dv SIGTRAP No " create core image" " trace trap" 280.It Dv SIGABRT No " create core image" Ta Xr abort 3 281call (formerly 282.Dv SIGIOT ) 283.It Dv SIGEMT No " create core image" " emulate instruction executed" 284.It Dv SIGFPE No " create core image" " floating-point exception" 285.It Dv SIGKILL No " terminate process" " kill program" 286.It Dv SIGBUS No " create core image" " bus error" 287.It Dv SIGSEGV No " create core image" " segmentation violation" 288.It Dv SIGSYS No " create core image" " non-existent system call invoked" 289.It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" 290.It Dv SIGALRM No " terminate process" " real-time timer expired" 291.It Dv SIGTERM No " terminate process" " software termination signal" 292.It Dv SIGURG No " discard signal" " urgent condition present on socket" 293.It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" 294.It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" 295.It Dv SIGCONT No " discard signal" " continue after stop" 296.It Dv SIGCHLD No " discard signal" " child status has changed" 297.It Dv SIGTTIN No " stop process" " background read attempted from control terminal" 298.It Dv SIGTTOU No " stop process" " background write attempted to control terminal" 299.It Dv SIGIO No " discard signal" Tn " I/O" 300is possible on a descriptor (see 301.Xr fcntl 2 ) 302.It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" 303.Xr setrlimit 2 ) 304.It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" 305.Xr setrlimit 2 ) 306.It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" 307.Xr setitimer 2 ) 308.It Dv SIGPROF No " terminate process" " profiling timer alarm (see" 309.Xr setitimer 2 ) 310.It Dv SIGWINCH No " discard signal" " Window size change" 311.It Dv SIGINFO No " discard signal" " status request from keyboard" 312.It Dv SIGUSR1 No " terminate process" " User defined signal 1" 313.It Dv SIGUSR2 No " terminate process" " User defined signal 2" 314.El 315.Sh NOTE 316The 317.Fa sa_mask 318field specified in 319.Fa act 320is not allowed to block 321.Dv SIGKILL 322or 323.Dv SIGSTOP . 324Any attempt to do so will be silently ignored. 325.Pp 326The following functions are either reentrant or not interruptible 327by signals and are async-signal safe. 328Therefore applications may 329invoke them, without restriction, from signal-catching functions: 330.Pp 331Base Interfaces: 332.Pp 333.Fn _exit , 334.Fn access , 335.Fn alarm , 336.Fn cfgetispeed , 337.Fn cfgetospeed , 338.Fn cfsetispeed , 339.Fn cfsetospeed , 340.Fn chdir , 341.Fn chmod , 342.Fn chown , 343.Fn close , 344.Fn creat , 345.Fn dup , 346.Fn dup2 , 347.Fn execle , 348.Fn execve , 349.Fn fcntl , 350.Fn fork , 351.Fn fpathconf , 352.Fn fstat , 353.Fn fsync , 354.Fn getegid , 355.Fn geteuid , 356.Fn getgid , 357.Fn getgroups , 358.Fn getpgrp , 359.Fn getpid , 360.Fn getppid , 361.Fn getuid , 362.Fn kill , 363.Fn link , 364.Fn lseek , 365.Fn mkdir , 366.Fn mkfifo , 367.Fn open , 368.Fn pathconf , 369.Fn pause , 370.Fn pipe , 371.Fn raise , 372.Fn read , 373.Fn rename , 374.Fn rmdir , 375.Fn setgid , 376.Fn setpgid , 377.Fn setsid , 378.Fn setuid , 379.Fn sigaction , 380.Fn sigaddset , 381.Fn sigdelset , 382.Fn sigemptyset , 383.Fn sigfillset , 384.Fn sigismember , 385.Fn signal , 386.Fn sigpending , 387.Fn sigprocmask , 388.Fn sigsuspend , 389.Fn sleep , 390.Fn stat , 391.Fn sysconf , 392.Fn tcdrain , 393.Fn tcflow , 394.Fn tcflush , 395.Fn tcgetattr , 396.Fn tcgetpgrp , 397.Fn tcsendbreak , 398.Fn tcsetattr , 399.Fn tcsetpgrp , 400.Fn time , 401.Fn times , 402.Fn umask , 403.Fn uname , 404.Fn unlink , 405.Fn utime , 406.Fn wait , 407.Fn waitpid , 408.Fn write . 409.Pp 410Realtime Interfaces: 411.Pp 412.Fn aio_error , 413.Fn clock_gettime , 414.Fn sigpause , 415.Fn timer_getoverrun , 416.Fn aio_return , 417.Fn fdatasync , 418.Fn sigqueue , 419.Fn timer_gettime , 420.Fn aio_suspend , 421.Fn sem_post , 422.Fn sigset , 423.Fn timer_settime . 424.Pp 425All functions not in the above lists are considered to be unsafe 426with respect to signals. That is to say, the behaviour of such 427functions when called from a signal handler is undefined. 428.Sh RETURN VALUES 429.Rv -std sigaction 430.Sh EXAMPLES 431There are three possible prototypes the handler may match: 432.Bl -tag -offset indent -width short 433.It ANSI C: 434.Ft void 435.Fn handler int ; 436.It Traditional BSD style: 437.Ft void 438.Fn handler int "int code" "struct sigcontext *scp" ; 439.It POSIX SA_SIGINFO: 440.Ft void 441.Fn handler int "siginfo_t *info" "ucontext_t *uap" ; 442.El 443.Pp 444The handler function should match the SA_SIGINFO prototype if the 445SA_SIGINFO bit is set in flags. 446It then should be pointed to by the 447.Dv sa_sigaction 448member of 449.Dv struct sigaction . 450Note that you should not assign SIG_DFL or SIG_IGN this way. 451.Pp 452If the SA_SIGINFO flag is not set, the handler function should match 453either the ANSI C or traditional 454.Bx 455prototype and be pointed to by 456the 457.Dv sa_handler 458member of 459.Dv struct sigaction . 460In practice, 461.Dx 462always sends the three arguments of the latter and since the ANSI C 463prototype is a subset, both will work. 464The 465.Dv sa_handler 466member declaration in 467.Dx 468include files is that of ANSI C (as required by POSIX), 469so a function pointer of a 470.Bx Ns -style 471function needs to be casted to 472compile without warning. 473The traditional 474.Bx 475style is not portable and since its capabilities 476are a full subset of a SA_SIGINFO handler, 477its use is deprecated. 478.Pp 479The 480.Fa sig 481argument is the signal number, one of the 482.Dv SIG... 483values from <signal.h>. 484.Pp 485The 486.Fa code 487argument of the 488.Bx Ns -style 489handler and the 490.Dv si_code 491member of the 492.Dv info 493argument to a SA_SIGINFO handler contain a numeric code explaining the 494cause of the signal, usually one of the 495.Dv SI_... 496values from 497<sys/signal.h> or codes specific to a signal, i.e. one of the 498.Dv FPE_... 499values for SIGFPE. 500.Pp 501The 502.Fa scp 503argument to a 504.Bx Ns -style 505handler points to an instance of struct 506sigcontext. 507.Pp 508The 509.Fa uap 510argument to a POSIX SA_SIGINFO handler points to an instance of 511ucontext_t. 512.Sh ERRORS 513.Fn Sigaction 514will fail and no new signal handler will be installed if one 515of the following occurs: 516.Bl -tag -width Er 517.It Bq Er EFAULT 518Either 519.Fa act 520or 521.Fa oact 522points to memory that is not a valid part of the process 523address space. 524.It Bq Er EINVAL 525.Fa Sig 526is not a valid signal number. 527.It Bq Er EINVAL 528An attempt is made to ignore or supply a handler for 529.Dv SIGKILL 530or 531.Dv SIGSTOP . 532.El 533.Sh STANDARDS 534The 535.Fn sigaction 536function call is expected to conform to 537.St -p1003.1-90 . 538The 539.Dv SA_ONSTACK 540and 541.Dv SA_RESTART 542flags are Berkeley extensions, 543as 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 . 557Those signals are available on most 558.Bx Ns \-derived 559systems. 560The 561.Dv SA_NODEFER 562and 563.Dv SA_RESETHAND 564flags are intended for backwards compatibility with other operating 565systems. The 566.Dv SA_NOCLDSTOP , 567and 568.Dv SA_NOCLDWAIT 569.\" and 570.\" SA_SIGINFO 571flags are featuring options commonly found in other operating systems. 572.Sh SEE ALSO 573.Xr kill 1 , 574.Xr kill 2 , 575.Xr ptrace 2 , 576.Xr sigaltstack 2 , 577.Xr sigblock 2 , 578.Xr sigpause 2 , 579.Xr sigpending 2 , 580.Xr sigprocmask 2 , 581.Xr sigsetmask 2 , 582.Xr sigsuspend 2 , 583.Xr sigvec 2 , 584.Xr wait 2 , 585.Xr fpsetmask 3 , 586.Xr setjmp 3 , 587.Xr siginterrupt 3 , 588.Xr sigsetops 3 , 589.Xr ucontext 3 , 590.Xr tty 4 591