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