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