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