1.\" $NetBSD: signal.7,v 1.25 2018/05/30 23:41:44 uwe 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 May 28, 2018 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" 3n "Profiling timer expired blablabla" -compact 115.\".It Sy "Symbol" Ta No Ta Sy "Descriptive name" 116.It Dv SIGHUP Ta 1 Ta "Hangup" 117.It Dv SIGINT Ta 2 Ta "Interrupt" 118.It Dv SIGQUIT Ta 3 Ta "Quit" 119.It Dv SIGILL Ta 4 Ta "Illegal instruction" 120.It Dv SIGTRAP Ta 5 Ta "Trace/BPT trap" 121.It Dv SIGABRT Ta 6 Ta "Abort trap" 122.It Dv SIGEMT Ta 7 Ta "EMT trap" 123.It Dv SIGFPE Ta 8 Ta "Floating point exception" 124.It Dv SIGKILL Ta 9 Ta "Killed" 125.It Dv SIGBUS Ta 10 Ta "Bus error" 126.It Dv SIGSEGV Ta 11 Ta "Segmentation fault" 127.It Dv SIGSYS Ta 12 Ta "Bad system call" 128.It Dv SIGPIPE Ta 13 Ta "Broken pipe" 129.It Dv SIGALRM Ta 14 Ta "Alarm clock" 130.It Dv SIGTERM Ta 15 Ta "Terminated" 131.It Dv SIGURG Ta 16 Ta "Urgent I/O condition" 132.It Dv SIGSTOP Ta 17 Ta "Suspended (signal)" 133.It Dv SIGTSTP Ta 18 Ta "Suspended" 134.It Dv SIGCONT Ta 19 Ta "Continued" 135.It Dv SIGCHLD Ta 20 Ta "Child exited, stopped or continued" 136.It Dv SIGTTIN Ta 21 Ta "Stopped (tty input)" 137.It Dv SIGTTOU Ta 22 Ta "Stopped (tty output)" 138.It Dv SIGIO Ta 23 Ta "I/O possible" 139.It Dv SIGXCPU Ta 24 Ta "CPU time limit exceeded" 140.It Dv SIGXFSZ Ta 25 Ta "File size limit exceeded" 141.It Dv SIGVTALRM Ta 26 Ta "Virtual timer expired" 142.It Dv SIGPROF Ta 27 Ta "Profiling timer expired" 143.It Dv SIGWINCH Ta 28 Ta "Window size changed" 144.It Dv SIGINFO Ta 29 Ta "Information request" 145.It Dv SIGUSR1 Ta 30 Ta "User defined signal 1" 146.It Dv SIGUSR2 Ta 31 Ta "User defined signal 2" 147.It Dv SIGPWR Ta 32 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.Bl -tag -width "aaa" 156.\" ************ 157.It Dv SIGHUP No (Hangup) 158This signal is generated by the 159.Xr tty 4 160driver 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 No (Interrupt) 173This signal is generated by the 174.Xr tty 4 175driver 176when the user presses the interrupt character, normally control-C. 177The default action is to terminate the process. 178The number for 179.Dv SIGINT 180is\~2. 181.\" ************ 182.It Dv SIGQUIT No (Quit) 183This signal is generated by the 184.Xr tty 4 185driver 186when the user presses the quit character, normally control-backspace. 187The default action is to terminate the process and dump core. 188The number for 189.Dv SIGQUIT 190is\~3. 191.\" ************ 192.It Dv SIGILL No (Illegal instruction) 193This signal is generated synchronously by the kernel when the process 194executes an invalid instruction. 195The default action is to terminate the process and dump core. 196Note: the results of executing an illegal instruction when 197.Dv SIGILL 198is blocked or ignored are formally unspecified. 199The number for 200.Dv SIGILL 201is\~4. 202.\" ************ 203.It Dv SIGTRAP No (Trace/BPT trap) 204This signal is used when a process is being traced 205(see 206.Xr ptrace 2 ) 207to indicate that the process has stopped at a breakpoint or after 208single-stepping. 209It is normally intercepted by the debugger and not exposed to the 210debuggee. 211The default action is to terminate the process and dump core. 212The number for 213.Dv SIGTRAP 214is\~5. 215.\" ************ 216.It Dv SIGABRT No (Abort trap) 217This signal is generated when the 218.Xr abort 3 219standard library function is called. 220The default action is to terminate the process and dump core. 221The number for 222.Dv SIGABRT 223is\~6. 224This number was also formerly used for 225.Dv SIGIOT , 226which is no longer defined, 227as it was specific to the PDP-11 instruction 228.Dv iot . 229.\" ************ 230.It Dv SIGEMT No (EMT trap) 231In theory this signal is generated when an instruction needs to be 232emulated. 233.\" XXX expand this -- I don't know, grep isn't helping much and 234.\" information seems pretty thin on the ground on the net. 235The default action is to terminate the process and dump core. 236The number for 237.Dv SIGEMT 238is\~7. 239.\" ************ 240.It Dv SIGFPE No (Floating point exception) 241This signal is generated when an invalid floating point operation is 242detected by hardware or by a soft-float library. 243The default action is to terminate the process and dump core. 244The number for 245.Dv SIGFPE 246is\~8. 247.\" ************ 248.It Dv SIGKILL No (Killed) 249This signal cannot be caught or ignored. 250The (unconditional) action is to terminate the process. 251It is most often sent by system administrators, but is also generated 252by the kernel in response to running completely out of memory and 253swap space. 254Note that because many processes need to perform cleanup before 255exiting, it is usually best (as a user or administrator) to not deploy 256.Dv SIGKILL 257until a process has failed to respond to other signals. 258The number for 259.Dv SIGKILL 260is\~9, which is extremely well known. 261.\" ************ 262.It Dv SIGBUS No (Bus error) 263This signal is generated synchronously by the kernel when the process 264performs certain kinds of invalid memory accesses. 265The most common cause of 266.Dv SIGBUS 267is an unaligned memory access; however, on some architectures it may 268cover other memory conditions, such as attempts to access memory 269belonging to the kernel. 270The default action is to terminate the process and dump core. 271Note: the results of performing such invalid accesses when 272.Dv SIGBUS 273is blocked or ignored are formally unspecified. 274The number for 275.Dv SIGBUS 276is\~10. 277.\" ************ 278.It Dv SIGSEGV No (Segmentation fault) 279This signal is generated synchronously by the kernel when the process 280attempts to access unmapped memory, or access memory in a manner that 281the protection settings for that memory region do not permit. 282On some architectures other assorted permission or protection errors 283also yield 284.Dv SIGSEGV . 285On 286.Nx , 287passing invalid pointers to system calls will yield failure with 288.Er EFAULT 289but not also 290.Dv SIGSEGV . 291The default action is to terminate the process and dump core. 292Note: the results of an invalid memory access when 293.Dv SIGSEGV 294is blocked or ignored are formally unspecified. 295The number for 296.Dv SIGSEGV 297is\~11, which is very well known. 298.\" ************ 299.It Dv SIGSYS No (Bad system call) 300This signal is generated by the kernel, in addition to failing with 301.Er ENOSYS , 302when a system call is made using an invalid system call number. 303.\" (This facility was intended to facilitate emulation of system calls.) 304The default action is to terminate the process and dump core. 305The number for 306.Dv SIGSYS 307is\~12. 308.\" ************ 309.It Dv SIGPIPE No (Broken pipe) 310This signal is generated by the kernel, in addition to failing with 311.Er EPIPE , 312when a 313.Xr write 2 314call or similar is made on a pipe or socket that has been closed and 315has no readers. 316The default action is to terminate the process. 317The number for 318.Dv SIGPIPE 319is\~13. 320.\" ************ 321.It Dv SIGALRM No (Alarm clock) 322This signal is generated by the kernel when a real-time timer expires. 323See 324.Xr alarm 3 , 325.Xr setitimer 2 , 326and 327.Xr timer_settime 2 . 328The default action is to terminate the process. 329The number for 330.Dv SIGALRM 331is\~14. 332.\" ************ 333.It Dv SIGTERM No (Terminated) 334This signal is the default signal sent by 335.Xr kill 1 336and represents a user or administrator request that a program shut 337down. 338It is sent to all processes as part of the 339.Xr shutdown 8 340procedure. 341The default action is to terminate the process. 342The number for 343.Dv SIGTERM 344is\~15. 345.\" ************ 346.It Dv SIGURG No (Urgent I/O condition) 347This signal is generated when an ``urgent condition'' exists on a 348socket. 349In practice this means when 350.Xr tcp 4 351out-of-band data has arrived. 352The default action is to do nothing. 353The number for 354.Dv SIGURG 355is\~16. 356.\" ************ 357.It Dv SIGSTOP No (Suspended (signal)) 358This signal cannot be caught or ignored. 359The (unconditional) action is to stop the process. 360Note that like with 361.Dv SIGKILL 362(and for similar reasons) it is best to not send this signal until a 363process has failed to respond to 364.Dv SIGTSTP . 365It can also be used by processes to stop themselves after catching 366.Dv SIGTSTP . 367A process that is explicitly stopped will not run again until told to 368with 369.Dv SIGCONT . 370The number for 371.Dv SIGSTOP 372is\~17. 373.\" ************ 374.It Dv SIGTSTP No (Suspended) 375This signal is generated by the 376.Xr tty 4 377driver 378when the user presses the stop character, normally control-Z. 379The default action is to stop the process. 380The number for 381.Dv SIGTSTP 382is\~18. 383.\" ************ 384.It Dv SIGCONT No (Continued) 385This signal is generated by the job-control feature of shells to 386manage processes. 387It causes the target process to start executing again after previously 388being stopped. 389This happens as a magic extra effect 390.Nm before 391the signal is actually delivered. 392The default action when the signal is delivered is to do nothing (else). 393The number for 394.Dv SIGCONT 395is\~19. 396.\" ************ 397.It Dv SIGCHLD No (Child exited, stopped or continued) 398This signal is generated by the kernel when one of a process's 399immediate children exits and can be waited for using one of the 400.Xr wait 2 401family of functions. 402The default action is to do nothing. 403As a special case hack, if 404.Dv SIGCHLD 405is ignored (not merely blocked) when a process is 406.Em created , 407it is detached from its parent immediately so it need not be waited 408for. 409This behavior is a System V historic wart, implemented in 410.Nx 411only for compatibility. 412It is not portable, not recommended, and should not be used by new 413code. 414.\" XXX should refer to something that can be used by new code... 415The number for 416.Dv SIGCHLD 417is\~20. 418This signal was spelled 419.Dv SIGCLD 420in old System V versions and today many systems provide both 421spellings. 422.\" ************ 423.It Dv SIGTTIN No (Stopped (tty input)) 424This signal is generated by the 425.Xr tty 4 426driver 427when a process that is not in the foreground of its controlling 428terminal attempts to read from this terminal. 429The default action is to stop the process. 430The number for 431.Dv SIGTTIN 432is\~21. 433.\" ************ 434.It Dv SIGTTOU No (Stopped (tty output)) 435This signal is generated by the 436.Xr tty 4 437driver 438when a process that is not in the foreground of its controlling 439terminal attempts to write to this terminal, if the terminal is 440configured accordingly, which is not the default. 441(See 442.Xr termios 4 . ) 443The default action is to stop the process. 444The number for 445.Dv SIGTTOU 446is\~22. 447.\" ************ 448.It Dv SIGIO No (I/O possible) 449This signal is sent by the kernel when I/O becomes possible on a file 450handle opened for asynchronous access with 451.Dv O_ASYNC . 452See 453.Xr open 2 454and 455.Xr fcntl 2 . 456The default action is to do nothing. 457The number for 458.Dv SIGIO 459is\~23. 460.\" ************ 461.It Dv SIGXCPU No (CPU time limit exceeded) 462This signal is sent by the kernel when the amount of CPU time consumed 463exceeds the configured limit. 464See 465.Xr setrlimit 2 466and the 467.Ic ulimit 468and 469.Ic rlimit 470builtins of 471.Xr sh 1 472and 473.Xr csh 1 474respectively. 475The default action is to terminate the process. 476The number for 477.Dv SIGXCPU 478is\~24. 479.\" ************ 480.It Dv SIGXFSZ No (File size limit exceeded) 481This signal is sent by the kernel when a write causes the size of a 482file to exceed the configured limit. 483See 484.Xr setrlimit 2 485and the 486.Ic ulimit 487and 488.Ic rlimit 489builtins of 490.Xr sh 1 491and 492.Xr csh 1 493respectively. 494The default action is to terminate the process. 495The number for 496.Dv SIGXFSZ 497is\~25. 498.\" ************ 499.It Dv SIGVTALRM No (Virtual timer expired) 500This signal is generated by the kernel when a virtual-time (process 501execution time) timer expires. 502See 503.Xr setitimer 2 504and 505.Xr timer_settime 2 . 506The default action is to terminate the process. 507The number for 508.Dv SIGVTALRM 509is\~26. 510.\" ************ 511.It Dv SIGPROF No (Profiling timer expired) 512This signal is generated by the kernel when a profiling timer 513expires. 514See 515.Xr setitimer 2 516and 517.Xr timer_settime 2 . 518The default action is to terminate the process. 519The number for 520.Dv SIGPROF 521is\~27. 522.\" ************ 523.It Dv SIGWINCH No (Window size changed) 524This signal is generated by the 525.Xr tty 4 526driver 527when the stored window size of the process's controlling terminal has 528changed. 529The default action is to do nothing. 530The number for 531.Dv SIGWINCH 532is\~28. 533.\" ************ 534.It Dv SIGINFO No (Information request) 535This signal is generated by the 536.Xr tty 4 537driver 538when the user presses the status request character, normally 539control-T. 540The default action is to do nothing. 541The number for 542.Dv SIGINFO 543is\~29. 544.\" ************ 545.It Dv SIGUSR1 No (User defined signal 1) 546This signal is not generated by the system and is made available for 547applications to use for their own purposes. 548Many daemons use it for restart or reload requests of various types. 549The default action is to terminate the process. 550The number for 551.Dv SIGUSR1 552is\~30. 553.\" ************ 554.It Dv SIGUSR2 No (User defined signal 2) 555This signal is not generated by the system and is made available for 556applications to use for their own purposes. 557The default action is to terminate the process. 558The number for 559.Dv SIGUSR2 560is\~31. 561.\" ************ 562.It Dv SIGPWR No (Power fail/restart) 563This signal is notionally sent by the kernel or by a privileged 564monitor process when an external power failure is detected, and again 565when power has been restored. 566Currently 567.Nx 568does not in fact send 569.Dv SIGPWR , 570although it is possible to prepare a custom configuration for 571.Xr powerd 8 572that does so. 573The default action is to do nothing. 574The number for 575.Dv SIGPWR 576is\~32. 577.\" ************ 578.El 579.Ss Shell Interface 580Signals may be sent with the 581.Xr kill 1 582utility, either by number or the symbolic name without the ``SIG'' part. 583This utility is built into many shells to allow addressing job control 584jobs. 585.Ss Program Interface 586In C code signals may be sent using 587.Xr raise 3 , 588.Xr kill 2 , 589.Xr pthread_kill 3 , 590and some other related functions. 591.Pp 592Signals may be caught or ignored using 593.Xr sigaction 2 594or the simpler 595.Xr signal 3 , 596and blocked using 597.Xr sigprocmask 2 . 598.Sh STANDARDS 599The 600.Dv SIGTRAP , 601.Dv SIGEMT , 602.Dv SIGBUS , 603.Dv SIGSYS , 604.Dv SIGURG , 605.Dv SIGIO , 606.Dv SIGXCPU , 607.Dv SIGXFSZ , 608.Dv SIGVTALRM , 609.Dv SIGPROF , 610.Dv SIGWINCH , 611and 612.Dv SIGINFO 613signals are long-existing Berkeley extensions, available on most 614.Bx Ns \-derived 615systems. 616The 617.Dv SIGPWR 618signal comes from System V. 619.Pp 620The remaining signals conform to 621.St -p1003.1-90 . 622.Sh HISTORY 623.Dv SIGPWR 624was introduced in 625.Nx 1.4 . 626