1.\" $NetBSD: signal.7,v 1.20 2016/07/12 12:39:04 wiz Exp $ 2.\" 3.\" Copyright (c) 1999, 2016 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd July 9, 2016 28.Dt SIGNAL 7 29.Os 30.Sh NAME 31.Nm signal 32.Nd signal facilities 33.Sh DESCRIPTION 34A 35.Nm 36is a system-level notification delivered to a process. 37Signals may be generated as the result of process activity, by certain 38user inputs, by kernel facilities or subsystems, or sent 39programmatically by other processes or by users. 40There is a small fixed set of signals, each with a symbolic name and a 41number. 42For historical reasons many of the numbers are ``well-known values'', 43which are in practice the same on all implementations and 44realistically can never be changed. 45(Nonetheless, compiled code should always use only the symbolic 46names.) 47Many/most signals also have specific semantics, both in how they can 48be generated and in their effects. 49Some are special cases in ways that have quite far-reaching 50consequences. 51.Pp 52When a signal is 53.Em posted 54.Pq Dq sent 55to a process, in general any of several things can happen. 56If the process has elected to 57.Em ignore 58the signal, it is discarded and nothing happens. 59(Some signals may not be ignored, however.) 60If the process has elected to 61.Em block 62the signal temporarily, delivery is postponed until the process 63later unblocks that signal. 64Otherwise, the signal is 65.Em delivered , 66meaning that whatever the process is doing is interrupted in order to 67react to the signal. 68(Note that processes that are waiting in the kernel must unwind what 69they are doing for signals to be delivered. 70This can sometimes be expensive. 71See 72.Xr sigaction 2 73for further information.) 74.Pp 75If the process has elected to 76.Em catch 77the signal, which means that the process has installed a handler to 78react to the signal in some process-specific way, the kernel arranges 79for the process's handler logic to be invoked. 80This is always done in a way that allows the process to resume if 81desired. 82(Note, however, that some signals may not be caught.) 83Otherwise, the default action for the signal is taken. 84For most signals the default action is a core dump. 85See the table below. 86Note that the term 87.Em delivery 88is also used for the specific process of arranging for a signal 89handler to be invoked. 90.Pp 91In general, signals are delivered as soon as they are posted. 92(Some delays may occur due to scheduling.) 93However, in some cases a process that has been sleeping in the kernel 94may need to do slow things as part of unwinding its state; this can 95sometimes lead to human-perceptible delays. 96.Pp 97Also, some sleep states within the kernel are 98.Em uninterruptible 99meaning that signals posted will have no effect until the state 100clears. 101These states are supposed to be short-term only, but sometimes kernel 102bugs make this not the case and one can end up with unkillable 103processes. 104Such processes appear in state "D" in 105.Xr ps 1 . 106In general the only way to get rid of them is to reboot. 107(However, when the "wchan" reported is "tstile", it means the process 108is waiting for some other process to release resources; sometimes if 109one can find and kill that process the situation is recoverable.) 110.Ss Signal list 111The following signals are defined in 112.Nx : 113.Pp 114.Bl -column ".Sy SIGVTALRM" "Profiling timer expired blablabla" -compact 115.\".It Sy "Symbol" Ta Sy "Descriptive name" 116.It Dv SIGHUP Ta "Hangup" 117.It Dv SIGINT Ta "Interrupt" 118.It Dv SIGQUIT Ta "Quit" 119.It Dv SIGILL Ta "Illegal instruction" 120.It Dv SIGTRAP Ta "Trace/BPT trap" 121.It Dv SIGABRT Ta "Abort trap" 122.It Dv SIGEMT Ta "EMT trap" 123.It Dv SIGFPE Ta "Floating point exception" 124.It Dv SIGKILL Ta "Killed" 125.It Dv SIGBUS Ta "Bus error" 126.It Dv SIGSEGV Ta "Segmentation fault" 127.It Dv SIGSYS Ta "Bad system call" 128.It Dv SIGPIPE Ta "Broken pipe" 129.It Dv SIGALRM Ta "Alarm clock" 130.It Dv SIGTERM Ta "Terminated" 131.It Dv SIGURG Ta "Urgent I/O condition" 132.It Dv SIGSTOP Ta "Suspended (signal)" 133.It Dv SIGTSTP Ta "Suspended" 134.It Dv SIGCONT Ta "Continued" 135.It Dv SIGCHLD Ta "Child exited" 136.It Dv SIGTTIN Ta "Stopped (tty input)" 137.It Dv SIGTTOU Ta "Stopped (tty output)" 138.It Dv SIGIO Ta "I/O possible" 139.It Dv SIGXCPU Ta "CPU time limit exceeded" 140.It Dv SIGXFSZ Ta "File size limit exceeded" 141.It Dv SIGVTALRM Ta "Virtual timer expired" 142.It Dv SIGPROF Ta "Profiling timer expired" 143.It Dv SIGWINCH Ta "Window size changed" 144.It Dv SIGINFO Ta "Information request" 145.It Dv SIGUSR1 Ta "User defined signal 1" 146.It Dv SIGUSR2 Ta "User defined signal 2" 147.It Dv SIGPWR Ta "Power fail/restart" 148.El 149.Pp 150These are numbered 1 to 32. 151(There is no signal 0; 0 is a reserved value that can be used as a 152no-op with some signal operations.) 153.Pp 154Detailed descriptions of these signals follow. 155.Pp 156.Bl -tag -width "aaa" 157.\" ************ 158.It Dv SIGHUP (Hangup) 159This signal is generated by the tty driver 160.Xr tty 4 161to indicate a hangup condition on a process's controlling terminal: 162the user has disconnected. 163Accordingly, the default action is to terminate the process. 164This signal is also used by many daemons, 165such as 166.Xr inetd 8 , 167as a cue to reload configuration. 168The number for 169.Dv SIGHUP 170is 1, which is quite well known. 171.\" ************ 172.It Dv SIGINT (Interrupt) 173This signal is generated by the tty driver 174.Xr tty 4 175when the user presses the interrupt character, normally control-C. 176The default action is to terminate the process. 177The number for 178.Dv SIGINT 179is 2. 180.\" ************ 181.It Dv SIGQUIT Ta (Quit) 182This signal is generated by the tty driver 183.Xr tty 4 184when the user presses the quit character, normally control-backspace. 185The default action is to terminate the process and dump core. 186The number for 187.Dv SIGQUIT 188is 3. 189.\" ************ 190.It Dv SIGILL Ta (Illegal instruction) 191This signal is generated synchronously by the kernel when the process 192executes an invalid instruction. 193The default action is to terminate the process and dump core. 194Note: the results of executing an illegal instruction when 195.Dv SIGILL 196is blocked or ignored are formally unspecified. 197The number for 198.Dv SIGILL 199is 4. 200.\" ************ 201.It Dv SIGTRAP Ta (Trace/BPT trap) 202This signal is used when a process is being traced 203(see 204.Xr ptrace 2 ) 205to indicate that the process has stopped at a breakpoint or after 206single-stepping. 207It is normally intercepted by the debugger and not exposed to the 208debuggee. 209The default action is to terminate the process and dump core. 210The number for 211.Dv SIGTRAP 212is 5. 213.\" ************ 214.It Dv SIGABRT Ta (Abort trap) 215This signal is generated when the 216.Xr abort 3 217standard library function is called. 218The default action is to terminate the process and dump core. 219The number for 220.Dv SIGABRT 221is 6. 222This number was also formerly used for 223.Dv SIGIOT , 224which is no longer defined. 225.\" ************ 226.It Dv SIGEMT Ta (EMT trap) 227In theory this signal is generated when an instruction needs to be 228emulated. 229.\" XXX expand this -- I don't know, grep isn't helping much and 230.\" information seems pretty thin on the ground on the net. 231The default action is to terminate the process and dump core. 232The number for 233.Dv SIGEMT 234is 7. 235.\" ************ 236.It Dv SIGFPE Ta (Floating point exception) 237This signal is generated when an invalid floating point operation is 238detected by hardware or by a soft-float library. 239The default action is to terminate the process and dump core. 240The number for 241.Dv SIGFPE 242is 8. 243.\" ************ 244.It Dv SIGKILL Ta (Killed) 245This signal cannot be caught or ignored. 246The (unconditional) action is to terminate the process. 247It is most often sent by system administrators, but is also generated 248by the kernel in response to running completely out of memory and 249swap space. 250Note that because many processes need to perform cleanup before 251exiting, it is usually best (as a user or administrator) to not deploy 252.Dv SIGKILL 253until a process has failed to respond to other signals. 254The number for 255.Dv SIGKILL 256is 9, which is extremely well known. 257.\" ************ 258.It Dv SIGBUS Ta (Bus error) 259This signal is generated synchronously by the kernel when the process 260performs certain kinds of invalid memory accesses. 261The most common cause of 262.Dv SIGBUS 263is an unaligned memory access; however, on some architectures it may 264cover other memory conditions, such as attempts to access memory 265belonging to the kernel. 266The default action is to terminate the process and dump core. 267Note: the results of performing such invalid accesses when 268.Dv SIGBUS 269is blocked or ignored are formally unspecified. 270The number for 271.Dv SIGBUS 272is 10. 273.\" ************ 274.It Dv SIGSEGV Ta (Segmentation fault) 275This signal is generated synchronously by the kernel when the process 276attempts to access unmapped memory, or access memory in a manner that 277the protection settings for that memory region do not permit. 278On some architectures other assorted permission or protection errors 279also yield 280.Dv SIGSEGV . 281On 282.Nx , 283passing invalid pointers to system calls will yield failure with 284.Er EFAULT 285but not also 286.Dv SIGSEGV . 287The default action is to terminate the process and dump core. 288Note: the results of an invalid memory access when 289.Dv SIGSEGV 290is blocked or ignored are formally unspecified. 291The number for 292.Dv SIGSEGV 293is 11, which is very well known. 294.\" ************ 295.It Dv SIGSYS Ta (Bad system call) 296This signal is generated by the kernel, in addition to failing with 297.Er ENOSYS , 298when a system call is made using an invalid system call number. 299.\" (This facility was intended to facilitate emulation of system calls.) 300The default action is to terminate the process and dump core. 301The number for 302.Dv SIGSYS 303is 12. 304.\" ************ 305.It Dv SIGPIPE Ta (Broken pipe) 306This signal is generated by the kernel, in addition to failing with 307.Er EPIPE , 308when a 309.Xr write 2 310call or similar is made on a pipe or socket that has been closed and 311has no readers. 312The default action is to terminate the process. 313The number for 314.Dv SIGPIPE 315is 13. 316.\" ************ 317.It Dv SIGALRM Ta (Alarm clock) 318This signal is generated by the kernel when a real-time timer expires. 319See 320.Xr alarm 3 , 321.Xr setitimer 2 , 322and 323.Xr timer_settime 2 . 324The default action is to terminate the process. 325The number for 326.Dv SIGALRM 327is 14. 328.\" ************ 329.It Dv SIGTERM Ta (Terminated) 330This signal is the default signal sent by 331.Xr kill 1 332and represents a user or administrator request that a program shut 333down. 334It is sent to all processes as part of the 335.Xr shutdown 8 336procedure. 337The default action is to terminate the process. 338The number for 339.Dv SIGTERM 340is 15. 341.\" ************ 342.It Dv SIGURG Ta (Urgent I/O condition) 343This signal is generated when an ``urgent condition'' exists on a 344socket. 345In practice this means when 346.Xr tcp 4 347out-of-band data has arrived. 348The default action is to do nothing. 349The number for 350.Dv SIGURG 351is 16. 352.\" ************ 353.It Dv SIGSTOP Ta (Suspended (signal)) 354This signal cannot be caught or ignored. 355The (unconditional) action is to stop the process. 356Note that like with 357.Dv SIGKILL 358(and for similar reasons) it is best to not send this signal until a 359process has failed to respond to 360.Dv SIGTSTP . 361It can also be used by processes to stop themselves after catching 362.Dv SIGTSTP . 363A process that is explicitly stopped will not run again until told to 364with 365.Dv SIGCONT . 366The number for 367.Dv SIGSTOP 368is 17. 369.\" ************ 370.It Dv SIGTSTP Ta (Suspended) 371This signal is generated by the tty driver 372.Xr tty 4 373when the user presses the stop character, normally control-Z. 374The default action is to stop the process. 375The number for 376.Dv SIGTSTP 377is 18. 378.\" ************ 379.It Dv SIGCONT Ta (Continued) 380This signal is generated by the job-control feature of shells to 381manage processes. 382It causes the target process to start executing again after previously 383being stopped. 384This happens as a magic extra effect 385.Nm before 386the signal is actually delivered. 387The default action when the signal is delivered is to do nothing (else). 388The number for 389.Dv SIGCONT 390is 19. 391.\" ************ 392.It Dv SIGCHLD Ta (Child exited) 393This signal is generated by the kernel when one of a process's 394immediate children exits and can be waited for using one of the 395.Xr wait 2 396family of functions. 397The default action is to do nothing. 398As a special case hack, if 399.Dv SIGCHLD 400is ignored (not merely blocked) when a process is 401.Em created , 402it is detached from its parent immediately so it need not be waited 403for. 404This behavior is a System V historic wart, implemented in 405.Nx 406only for compatibility. 407It is not portable, not recommended, and should not be used by new 408code. 409.\" XXX should refer to something that can be used by new code... 410The number for 411.Dv SIGCHLD 412is 20. 413This signal was spelled 414.Dv SIGCLD 415in old System V versions and today many systems provide both 416spellings. 417.\" ************ 418.It Dv SIGTTIN Ta (Stopped (tty input)) 419This signal is generated by the tty driver 420.Xr tty 4 421when a process that is not in the foreground of its controlling 422terminal attempts to read from this terminal. 423The default action is to stop the process. 424The number for 425.Dv SIGTTIN 426is 21. 427.\" ************ 428.It Dv SIGTTOU Ta (Stopped (tty output)) 429This signal is generated by the tty driver 430.Xr tty 4 431when a process that is not in the foreground of its controlling 432terminal attempts to write to this terminal, if the terminal is 433configured accordingly, which is not the default. 434(See 435.Xr termios 4 . ) 436The default action is to stop the process. 437The number for 438.Dv SIGTTOU 439is 22. 440.\" ************ 441.It Dv SIGIO Ta (I/O possible) 442This signal is sent by the kernel when I/O becomes possible on a file 443handle opened for asynchronous access with 444.Dv O_ASYNC . 445See 446.Xr open 2 447and 448.Xr fcntl 2 . 449The default action is to do nothing. 450The number for 451.Dv SIGIO 452is 23. 453.\" ************ 454.It Dv SIGXCPU Ta (CPU time limit exceeded) 455This signal is sent by the kernel when the amount of CPU time consumed 456exceeds the configured limit. 457See 458.Xr setrlimit 2 459and the 460.Ic ulimit 461and 462.Ic rlimit 463builtins of 464.Xr sh 1 465and 466.Xr csh 1 467respectively. 468The default action is to terminate the process. 469The number for 470.Dv SIGXCPU 471is 24. 472.\" ************ 473.It Dv SIGXFSZ Ta (File size limit exceeded) 474This signal is sent by the kernel when a write causes the size of a 475file to exceed the configured limit. 476See 477.Xr setrlimit 2 478and the 479.Ic ulimit 480and 481.Ic rlimit 482builtins of 483.Xr sh 1 484and 485.Xr csh 1 486respectively. 487The default action is to terminate the process. 488The number for 489.Dv SIGXFSZ 490is 25. 491.\" ************ 492.It Dv SIGVTALRM Ta (Virtual timer expired) 493This signal is generated by the kernel when a virtual-time (process 494execution time) timer expires. 495See 496.Xr setitimer 2 497and 498.Xr timer_settime 2 . 499The default action is to terminate the process. 500The number for 501.Dv SIGVTALRM 502is 26. 503.\" ************ 504.It Dv SIGPROF Ta (Profiling timer expired) 505This signal is generated by the kernel when a profiling timer 506expires. 507See 508.Xr setitimer 2 509and 510.Xr timer_settime 2 . 511The default action is to terminate the process. 512The number for 513.Dv SIGPROF 514is 27. 515.\" ************ 516.It Dv SIGWINCH Ta (Window size changed) 517This signal is generated by the tty driver 518.Xr tty 4 519when the stored window size of the process's controlling terminal has 520changed. 521The default action is to do nothing. 522The number for 523.Dv SIGWINCH 524is 28. 525.\" ************ 526.It Dv SIGINFO Ta (Information request) 527This signal is generated by the tty driver 528.Xr tty 4 529when the user presses the status request character, normally 530control-T. 531The default action is to do nothing. 532The number for 533.Dv SIGINFO 534is 29. 535.\" ************ 536.It Dv SIGUSR1 Ta (User defined signal 1) 537This signal is not generated by the system and is made available for 538applications to use for their own purposes. 539Many daemons use it for restart or reload requests of various types. 540The default action is to terminate the process. 541The number for 542.Dv SIGUSR1 543is 30. 544.\" ************ 545.It Dv SIGUSR2 Ta (User defined signal 2) 546This signal is not generated by the system and is made available for 547applications to use for their own purposes. 548The default action is to terminate the process. 549The number for 550.Dv SIGUSR2 551is 31. 552.\" ************ 553.It Dv SIGPWR Ta (Power fail/restart) 554This signal is notionally sent by the kernel or by a privileged 555monitor process when an external power failure is detected, and again 556when power has been restored. 557Currently 558.Nx 559does not in fact send 560.Dv SIGPWR , 561although it is possible to prepare a custom configuration for 562.Xr powerd 8 563that does so. 564The default action is to do nothing. 565The number for 566.Dv SIGPWR 567is 32. 568.\" ************ 569.Ss Shell Interface 570Signals may be sent with the 571.Xr kill 1 572utility, either by number or the symbolic name without the ``SIG'' part. 573This utility is built into many shells to allow addressing job control 574jobs. 575.Ss Program Interface 576In C code signals may be sent using 577.Xr raise 3 , 578.Xr kill 2 , 579.Xr pthread_kill 3 , 580and some other related functions. 581.Pp 582Signals may be caught or ignored using 583.Xr sigaction 2 584or the simpler 585.Xr signal 3 , 586and blocked using 587.Xr sigprocmask 2 . 588.Sh STANDARDS 589The 590.Dv SIGTRAP , 591.Dv SIGEMT , 592.Dv SIGBUS , 593.Dv SIGSYS , 594.Dv SIGURG , 595.Dv SIGIO , 596.Dv SIGXCPU , 597.Dv SIGXFSZ , 598.Dv SIGVTALRM , 599.Dv SIGPROF , 600.Dv SIGWINCH , 601and 602.Dv SIGINFO 603signals are long-existing Berkeley extensions, available on most 604.Bx Ns \-derived 605systems. 606The 607.Dv SIGPWR 608signal comes from System V. 609.Pp 610The remaining signals conform to 611.St -p1003.1-90 . 612.Sh HISTORY 613.Dv SIGPWR 614was introduced in 615.Nx 1.4 . 616