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.10 2008/05/10 20:39:51 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. 68A process may specify a 69.Em handler 70to which a signal is delivered, or specify that a signal is to be 71.Em ignored . 72A process may also specify that a default action is to be taken 73by the system when a signal occurs. 74A signal may also be 75.Em blocked , 76in which case its delivery is postponed until it is 77.Em unblocked . 78The action to be taken on delivery is determined at the time 79of delivery. 80Normally, signal handlers execute on the current stack 81of the process. 82This may be changed, on a per-handler basis, 83so that signals are taken on a special 84.Em "signal stack" . 85.Pp 86Signal routines normally execute with the signal that caused their 87invocation 88.Em blocked , 89but other signals may yet occur. 90A global 91.Em "signal mask" 92defines the set of signals currently blocked from delivery 93to a process. 94The signal mask for a process is initialized 95from that of its parent (normally empty). 96It may be changed with a 97.Xr sigprocmask 2 98call, or when a signal is delivered to the process. 99.Pp 100When a signal 101condition arises for a process, the signal is added to a set of 102signals pending for the process. 103If the signal is not currently 104.Em blocked 105by the process then it is delivered to the process. 106Signals may be delivered any time a process enters the operating system 107(e.g., during a system call, page fault or trap, or clock interrupt). 108If multiple signals are ready to be delivered at the same time, 109any signals that could be caused by traps are delivered first. 110Additional signals may be processed at the same time, with each 111appearing to interrupt the handlers for the previous signals 112before their first instructions. 113The set of pending signals is returned by the 114.Xr sigpending 2 115function. 116When a caught signal 117is delivered, the current state of the process is saved, 118a new signal mask is calculated (as described below), 119and the signal handler is invoked. 120The call to the handler 121is arranged so that if the signal handling routine returns 122normally the process will resume execution in the context 123from before the signal's delivery. 124If the process wishes to resume in a different context, then it 125must arrange to restore the previous context itself. 126.Pp 127When a signal is delivered to a process a new signal mask is 128installed for the duration of the process' signal handler 129(or until a 130.Xr sigprocmask 2 131call is made). 132This mask is formed by taking the union of the current signal mask set, 133the signal to be delivered, and 134the signal mask associated with the handler to be invoked. 135.Pp 136.Fn Sigaction 137assigns an action for a signal specified by 138.Fa sig . 139If 140.Fa act 141is non-zero, it 142specifies an action 143.Pf ( Dv SIG_DFL , 144.Dv SIG_IGN , 145or a handler routine) and mask 146to be used when delivering the specified signal. 147If 148.Fa oact 149is non-zero, the previous handling information for the signal 150is returned to the user. 151.Pp 152Once a signal handler is installed, it normally remains installed 153until another 154.Fn sigaction 155call is made, or an 156.Xr execve 2 157is performed. 158A signal-specific default action may be reset by 159setting 160.Fa sa_handler 161to 162.Dv SIG_DFL . 163The defaults are process termination, possibly with core dump; 164no action; stopping the process; or continuing the process. 165See the signal list below for each signal's default action. 166If 167.Fa sa_handler 168is 169.Dv SIG_DFL , 170the default action for the signal is to discard the signal, 171and if a signal is pending, 172the pending signal is discarded even if the signal is masked. 173If 174.Fa sa_handler 175is set to 176.Dv SIG_IGN 177current and pending instances 178of the signal are ignored and discarded. 179.Pp 180Options may be specified by setting 181.Em sa_flags . 182The meaning of the various bits is as follows: 183.Bl -tag -offset indent -width SA_RESETHANDXX 184.It Dv SA_NOCLDSTOP 185If this bit is set when installing a catching function 186for the 187.Dv SIGCHLD 188signal, 189the 190.Dv SIGCHLD 191signal will be generated only when a child process exits, 192not when a child process stops. 193.It Dv SA_NOCLDWAIT 194If this bit is set when calling 195.Fn sigaction 196for the 197.Dv SIGCHLD 198signal, the system will not create zombie processes when children of 199the calling process exit. 200If the calling process subsequently issues a 201.Xr wait 2 202(or equivalent), it blocks until all of the calling process's child 203processes terminate, and then returns a value of -1 with 204.Va errno 205set to 206.Er ECHILD . 207.It Dv SA_ONSTACK 208If this bit is set, the system will deliver the signal to the process 209on a 210.Em "signal stack" , 211specified with 212.Xr sigaltstack 2 . 213.It Dv SA_NODEFER 214If this bit is set, further occurrences of the delivered signal are 215not masked during the execution of the handler. 216.It Dv SA_RESETHAND 217If this bit is set, the handler is reset back to 218.Dv SIG_DFL 219at the moment the signal is delivered. 220.It Dv SA_SIGINFO 221If this bit is set, the handler function is assumed to be pointed to by the 222.Dv sa_sigaction 223member of struct sigaction and should match the prototype shown above or as 224below in 225.Sx EXAMPLES . 226This bit should not be set when assigning 227.Dv SIG_DFL 228or 229.Dv SIG_IGN . 230.El 231.Pp 232If a signal is caught during the system calls listed below, 233the call may be forced to terminate 234with the error 235.Er EINTR , 236the call may return with a data transfer shorter than requested, 237or the call may be restarted. 238Restart of pending calls is requested 239by setting the 240.Dv SA_RESTART 241bit in 242.Ar sa_flags . 243The affected system calls include 244.Xr open 2 , 245.Xr read 2 , 246.Xr write 2 , 247.Xr sendto 2 , 248.Xr recvfrom 2 , 249.Xr sendmsg 2 250and 251.Xr recvmsg 2 252on a communications channel or a slow device (such as a terminal, 253but not a regular file) 254and during a 255.Xr wait 2 256or 257.Xr ioctl 2 . 258However, calls that have already committed are not restarted, 259but instead return a partial success (for example, a short read count). 260.Pp 261After a 262.Xr fork 2 263or 264.Xr vfork 2 265all signals, the signal mask, the signal stack, 266and the restart/interrupt flags are inherited by the child. 267.Pp 268.Xr Execve 2 269reinstates the default 270action for all signals which were caught and 271resets all signals to be caught on the user stack. 272Ignored signals remain ignored; 273the signal mask remains the same; 274signals that restart pending system calls continue to do so. 275.Pp 276The following is a list of all signals 277with names as in the include file 278.In signal.h : 279.Bl -column SIGVTALARMXX "create core imagexxx" 280.It Sy "NAME Default Action Description" 281.It Dv SIGHUP No " terminate process" " terminal line hangup" 282.It Dv SIGINT No " terminate process" " interrupt program" 283.It Dv SIGQUIT No " create core image" " quit program" 284.It Dv SIGILL No " create core image" " illegal instruction" 285.It Dv SIGTRAP No " create core image" " trace trap" 286.It Dv SIGABRT No " create core image" Ta Xr abort 3 287call (formerly 288.Dv SIGIOT ) 289.It Dv SIGEMT No " create core image" " emulate instruction executed" 290.It Dv SIGFPE No " create core image" " floating-point exception" 291.It Dv SIGKILL No " terminate process" " kill program" 292.It Dv SIGBUS No " create core image" " bus error" 293.It Dv SIGSEGV No " create core image" " segmentation violation" 294.It Dv SIGSYS No " create core image" " non-existent system call invoked" 295.It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" 296.It Dv SIGALRM No " terminate process" " real-time timer expired" 297.It Dv SIGTERM No " terminate process" " software termination signal" 298.It Dv SIGURG No " discard signal" " urgent condition present on socket" 299.It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" 300.It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" 301.It Dv SIGCONT No " discard signal" " continue after stop" 302.It Dv SIGCHLD No " discard signal" " child status has changed" 303.It Dv SIGTTIN No " stop process" " background read attempted from control terminal" 304.It Dv SIGTTOU No " stop process" " background write attempted to control terminal" 305.It Dv SIGIO No " discard signal" Tn " I/O" 306is possible on a descriptor (see 307.Xr fcntl 2 ) 308.It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" 309.Xr setrlimit 2 ) 310.It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" 311.Xr setrlimit 2 ) 312.It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" 313.Xr setitimer 2 ) 314.It Dv SIGPROF No " terminate process" " profiling timer alarm (see" 315.Xr setitimer 2 ) 316.It Dv SIGWINCH No " discard signal" " Window size change" 317.It Dv SIGINFO No " discard signal" " status request from keyboard" 318.It Dv SIGUSR1 No " terminate process" " User defined signal 1" 319.It Dv SIGUSR2 No " terminate process" " User defined signal 2" 320.El 321.Sh NOTE 322The 323.Fa sa_mask 324field specified in 325.Fa act 326is not allowed to block 327.Dv SIGKILL 328or 329.Dv SIGSTOP . 330Any attempt to do so will be silently ignored. 331.Pp 332The following functions are either reentrant or not interruptible 333by signals and are async-signal safe. 334Therefore applications may 335invoke them, without restriction, from signal-catching functions: 336.Pp 337Base Interfaces: 338.Pp 339.Fn _exit , 340.Fn access , 341.Fn alarm , 342.Fn cfgetispeed , 343.Fn cfgetospeed , 344.Fn cfsetispeed , 345.Fn cfsetospeed , 346.Fn chdir , 347.Fn chmod , 348.Fn chown , 349.Fn close , 350.Fn creat , 351.Fn dup , 352.Fn dup2 , 353.Fn execle , 354.Fn execve , 355.Fn fcntl , 356.Fn fork , 357.Fn fpathconf , 358.Fn fstat , 359.Fn fsync , 360.Fn getegid , 361.Fn geteuid , 362.Fn getgid , 363.Fn getgroups , 364.Fn getpgrp , 365.Fn getpid , 366.Fn getppid , 367.Fn getuid , 368.Fn kill , 369.Fn link , 370.Fn lseek , 371.Fn mkdir , 372.Fn mkfifo , 373.Fn open , 374.Fn pathconf , 375.Fn pause , 376.Fn pipe , 377.Fn raise , 378.Fn read , 379.Fn rename , 380.Fn rmdir , 381.Fn setgid , 382.Fn setpgid , 383.Fn setsid , 384.Fn setuid , 385.Fn sigaction , 386.Fn sigaddset , 387.Fn sigdelset , 388.Fn sigemptyset , 389.Fn sigfillset , 390.Fn sigismember , 391.Fn signal , 392.Fn sigpending , 393.Fn sigprocmask , 394.Fn sigsuspend , 395.Fn sleep , 396.Fn stat , 397.Fn sysconf , 398.Fn tcdrain , 399.Fn tcflow , 400.Fn tcflush , 401.Fn tcgetattr , 402.Fn tcgetpgrp , 403.Fn tcsendbreak , 404.Fn tcsetattr , 405.Fn tcsetpgrp , 406.Fn time , 407.Fn times , 408.Fn umask , 409.Fn uname , 410.Fn unlink , 411.Fn utime , 412.Fn wait , 413.Fn waitpid , 414.Fn write . 415.Pp 416Realtime Interfaces: 417.Pp 418.Fn aio_error , 419.Fn clock_gettime , 420.Fn sigpause , 421.\".Fn timer_getoverrun , 422.Fn aio_return , 423.Fn fdatasync , 424.Fn sigqueue , 425.\".Fn timer_gettime , 426.Fn aio_suspend , 427.Fn sem_post , 428.Fn sigset . 429.\".Fn timer_settime . 430.Pp 431All functions not in the above lists are considered to be unsafe 432with respect to signals. 433That is to say, the behaviour of such 434functions when called from a signal handler is undefined. 435.Sh RETURN VALUES 436.Rv -std sigaction 437.Sh EXAMPLES 438There are three possible prototypes the handler may match: 439.Bl -tag -offset indent -width short 440.It ANSI C: 441.Ft void 442.Fn handler int ; 443.It Traditional BSD style: 444.Ft void 445.Fn handler int "int code" "struct sigcontext *scp" ; 446.It POSIX SA_SIGINFO: 447.Ft void 448.Fn handler int "siginfo_t *info" "ucontext_t *uap" ; 449.El 450.Pp 451The handler function should match the 452.Dv SA_SIGINFO 453prototype if the 454.Dv SA_SIGINFO 455bit is set in flags. 456It then should be pointed to by the 457.Dv sa_sigaction 458member of 459.Dv struct sigaction . 460Note that you should not assign 461.Dv SIG_DFL 462or 463.Dv SIG_IGN 464this way. 465.Pp 466If the 467.Dv SA_SIGINFO 468flag is not set, the handler function should match 469either the ANSI C or traditional 470.Bx 471prototype and be pointed to by 472the 473.Dv sa_handler 474member of 475.Dv struct sigaction . 476In practice, 477.Dx 478always sends the three arguments of the latter and since the ANSI C 479prototype is a subset, both will work. 480The 481.Dv sa_handler 482member declaration in 483.Dx 484include files is that of ANSI C (as required by POSIX), 485so a function pointer of a 486.Bx Ns -style 487function needs to be casted to 488compile without warning. 489The traditional 490.Bx 491style is not portable and since its capabilities are a full subset of a 492.Dv SA_SIGINFO 493handler, its use is deprecated. 494.Pp 495The 496.Fa sig 497argument is the signal number, one of the 498.Dv SIG... 499.In signal.h . 500.Pp 501The 502.Fa code 503argument of the 504.Bx Ns -style 505handler and the 506.Dv si_code 507member of the 508.Dv info 509argument to a 510.Dv SA_SIGINFO 511handler contain a numeric code explaining the 512cause of the signal, usually one of the 513.Dv SI_... 514values from 515.In sys/signal.h 516or codes specific to a signal, i.e.\& one of the 517.Dv FPE_... 518values for 519.Dv SIGFPE . 520.Pp 521The 522.Fa scp 523argument to a 524.Bx Ns -style 525handler points to an instance of struct 526sigcontext. 527.Pp 528The 529.Fa uap 530argument to a POSIX 531.Dv SA_SIGINFO 532handler points to an instance of ucontext_t. 533.Sh ERRORS 534.Fn Sigaction 535will fail and no new signal handler will be installed if one 536of the following occurs: 537.Bl -tag -width Er 538.It Bq Er EFAULT 539Either 540.Fa act 541or 542.Fa oact 543points to memory that is not a valid part of the process 544address space. 545.It Bq Er EINVAL 546.Fa Sig 547is not a valid signal number. 548.It Bq Er EINVAL 549An attempt is made to ignore or supply a handler for 550.Dv SIGKILL 551or 552.Dv SIGSTOP . 553.El 554.Sh SEE ALSO 555.Xr kill 1 , 556.Xr kill 2 , 557.Xr ptrace 2 , 558.Xr sigaltstack 2 , 559.Xr sigblock 2 , 560.Xr sigpause 2 , 561.Xr sigpending 2 , 562.Xr sigprocmask 2 , 563.Xr sigsetmask 2 , 564.Xr sigsuspend 2 , 565.Xr sigvec 2 , 566.Xr wait 2 , 567.Xr fpsetmask 3 , 568.Xr setjmp 3 , 569.Xr siginterrupt 3 , 570.Xr sigsetops 3 , 571.Xr ucontext 3 , 572.Xr tty 4 573.Sh STANDARDS 574The 575.Fn sigaction 576function call is expected to conform to 577.St -p1003.1-90 . 578The 579.Dv SA_ONSTACK 580and 581.Dv SA_RESTART 582flags are Berkeley extensions, 583as are the signals, 584.Dv SIGTRAP , 585.Dv SIGEMT , 586.Dv SIGBUS , 587.Dv SIGSYS , 588.Dv SIGURG , 589.Dv SIGIO , 590.Dv SIGXCPU , 591.Dv SIGXFSZ , 592.Dv SIGVTALRM , 593.Dv SIGPROF , 594.Dv SIGWINCH , 595and 596.Dv SIGINFO . 597Those signals are available on most 598.Bx Ns \-derived 599systems. 600The 601.Dv SA_NODEFER 602and 603.Dv SA_RESETHAND 604flags are intended for backwards compatibility with other operating 605systems. 606The 607.Dv SA_NOCLDSTOP , 608and 609.Dv SA_NOCLDWAIT 610.\" and 611.\" SA_SIGINFO 612flags are featuring options commonly found in other operating systems. 613