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