diff options
Diffstat (limited to 'static/netbsd/man7/signal.7')
| -rw-r--r-- | static/netbsd/man7/signal.7 | 633 |
1 files changed, 633 insertions, 0 deletions
diff --git a/static/netbsd/man7/signal.7 b/static/netbsd/man7/signal.7 new file mode 100644 index 00000000..37515d50 --- /dev/null +++ b/static/netbsd/man7/signal.7 @@ -0,0 +1,633 @@ +.\" $NetBSD: signal.7,v 1.28 2023/07/17 14:20:19 riastradh Exp $ +.\" +.\" Copyright (c) 1999, 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd August 24, 2018 +.Dt SIGNAL 7 +.Os +.Sh NAME +.Nm signal +.Nd signal facilities +.Sh DESCRIPTION +A +.Nm +is a system-level notification delivered to a process. +Signals may be generated as the result of process activity, by certain +user inputs, by kernel facilities or subsystems, or sent +programmatically by other processes or by users. +There is a small fixed set of signals, each with a symbolic name and a +number. +For historical reasons many of the numbers are ``well-known values'', +which are in practice the same on all implementations and +realistically can never be changed. +(Nonetheless, compiled code should always use only the symbolic +names.) +Many/most signals also have specific semantics, both in how they can +be generated and in their effects. +Some are special cases in ways that have quite far-reaching +consequences. +.Pp +When a signal is +.Em posted +.Pq Dq sent +to a process, in general any of several things can happen. +If the process has elected to +.Em ignore +the signal, it is discarded and nothing happens. +(Some signals may not be ignored, however.) +If the process has elected to +.Em block +the signal temporarily, delivery is postponed until the process +later unblocks that signal. +Otherwise, the signal is +.Em delivered , +meaning that whatever the process is doing is interrupted in order to +react to the signal. +(Note that processes that are waiting in the kernel must unwind what +they are doing for signals to be delivered. +This can sometimes be expensive. +See +.Xr sigaction 2 +for further information.) +.Pp +If the process has elected to +.Em catch +the signal, which means that the process has installed a handler to +react to the signal in some process-specific way, the kernel arranges +for the process's handler logic to be invoked. +This is always done in a way that allows the process to resume if +desired. +(Note, however, that some signals may not be caught.) +Otherwise, the default action for the signal is taken. +For most signals the default action is to terminate the process and +generate a core dump. +See the table below. +Note that the term +.Em delivery +is also used for the specific process of arranging for a signal +handler to be invoked. +.Pp +In general, signals are delivered as soon as they are posted. +(Some delays may occur due to scheduling.) +However, in some cases a process that has been sleeping in the kernel +may need to do slow things as part of unwinding its state; this can +sometimes lead to human-perceptible delays. +.Pp +Also, some sleep states within the kernel are +.Em uninterruptible +meaning that signals posted will have no effect until the state +clears. +These states are supposed to be short-term only, but sometimes kernel +bugs make this not the case and one can end up with unkillable +processes. +Such processes appear in state "D" in +.Xr ps 1 . +In general the only way to get rid of them is to reboot. +(However, when the "wchan" reported is "tstile", it means the process +is waiting for some other process to release resources; sometimes if +one can find and kill that process the situation is recoverable.) +.Ss Signal list +The following signals are defined in +.Nx : +.Pp +.Bl -column ".Sy SIGVTALRM" 3n "Profiling timer expired blablabla" -compact +.\".It Sy "Symbol" Ta No Ta Sy "Descriptive name" +.It Dv SIGHUP Ta 1 Ta "Hangup" +.It Dv SIGINT Ta 2 Ta "Interrupt" +.It Dv SIGQUIT Ta 3 Ta "Quit" +.It Dv SIGILL Ta 4 Ta "Illegal instruction" +.It Dv SIGTRAP Ta 5 Ta "Trace/BPT trap" +.It Dv SIGABRT Ta 6 Ta "Abort trap" +.It Dv SIGEMT Ta 7 Ta "EMT trap" +.It Dv SIGFPE Ta 8 Ta "Floating point exception" +.It Dv SIGKILL Ta 9 Ta "Killed" +.It Dv SIGBUS Ta 10 Ta "Bus error" +.It Dv SIGSEGV Ta 11 Ta "Segmentation fault" +.It Dv SIGSYS Ta 12 Ta "Bad system call" +.It Dv SIGPIPE Ta 13 Ta "Broken pipe" +.It Dv SIGALRM Ta 14 Ta "Alarm clock" +.It Dv SIGTERM Ta 15 Ta "Terminated" +.It Dv SIGURG Ta 16 Ta "Urgent I/O condition" +.It Dv SIGSTOP Ta 17 Ta "Suspended (signal)" +.It Dv SIGTSTP Ta 18 Ta "Suspended" +.It Dv SIGCONT Ta 19 Ta "Continued" +.It Dv SIGCHLD Ta 20 Ta "Child exited, stopped or continued" +.It Dv SIGTTIN Ta 21 Ta "Stopped (tty input)" +.It Dv SIGTTOU Ta 22 Ta "Stopped (tty output)" +.It Dv SIGIO Ta 23 Ta "I/O possible" +.It Dv SIGXCPU Ta 24 Ta "CPU time limit exceeded" +.It Dv SIGXFSZ Ta 25 Ta "File size limit exceeded" +.It Dv SIGVTALRM Ta 26 Ta "Virtual timer expired" +.It Dv SIGPROF Ta 27 Ta "Profiling timer expired" +.It Dv SIGWINCH Ta 28 Ta "Window size changed" +.It Dv SIGINFO Ta 29 Ta "Information request" +.It Dv SIGUSR1 Ta 30 Ta "User defined signal 1" +.It Dv SIGUSR2 Ta 31 Ta "User defined signal 2" +.It Dv SIGPWR Ta 32 Ta "Power fail/restart" +.El +.Pp +These are numbered 1 to 32. +(There is no signal 0; 0 is a reserved value that can be used as a +no-op with some signal operations.) +.Pp +Detailed descriptions of these signals follow. +.Bl -tag -width "aaa" +.\" ************ +.It Dv SIGHUP No (Hangup) +This signal is generated by the +.Xr tty 4 +driver +to indicate a hangup condition on a process's controlling terminal: +the user has disconnected. +Accordingly, the default action is to terminate the process. +This signal is also used by many daemons, +such as +.Xr inetd 8 , +as a cue to reload configuration. +The number for +.Dv SIGHUP +is\~1, which is quite well known. +.\" ************ +.It Dv SIGINT No (Interrupt) +This signal is generated by the +.Xr tty 4 +driver +when the user presses the interrupt character, normally control-C. +The default action is to terminate the process. +The number for +.Dv SIGINT +is\~2. +.\" ************ +.It Dv SIGQUIT No (Quit) +This signal is generated by the +.Xr tty 4 +driver +when the user presses the quit character, normally control-backspace. +The default action is to terminate the process and dump core. +The number for +.Dv SIGQUIT +is\~3. +.\" ************ +.It Dv SIGILL No (Illegal instruction) +This signal is generated synchronously by the kernel when the process +executes an invalid instruction. +The default action is to terminate the process and dump core. +Note: the results of executing an illegal instruction when +.Dv SIGILL +is blocked or ignored are formally unspecified. +The number for +.Dv SIGILL +is\~4. +.\" ************ +.It Dv SIGTRAP No (Trace/BPT trap) +This signal is used when a process is being traced +(see +.Xr ptrace 2 ) +to indicate that the process has stopped at a breakpoint or after +single-stepping. +It is normally intercepted by the debugger and not exposed to the +debuggee. +The default action is to terminate the process and dump core. +The number for +.Dv SIGTRAP +is\~5. +.\" ************ +.It Dv SIGABRT No (Abort trap) +This signal is generated when the +.Xr abort 3 +standard library function is called. +The default action is to terminate the process and dump core. +The number for +.Dv SIGABRT +is\~6. +This number was also formerly used for +.Dv SIGIOT , +which is no longer defined, +as it was specific to the PDP-11 instruction +.Dv iot . +.\" ************ +.It Dv SIGEMT No (EMT trap) +In theory this signal is generated when an instruction needs to be +emulated. +.\" XXX expand this -- I don't know, grep isn't helping much and +.\" information seems pretty thin on the ground on the net. +The default action is to terminate the process and dump core. +The number for +.Dv SIGEMT +is\~7. +.\" ************ +.It Dv SIGFPE No (Floating point exception) +This signal is generated when an invalid floating point operation is +detected by hardware or by a soft-float library. +The default action is to terminate the process and dump core. +The number for +.Dv SIGFPE +is\~8. +.\" ************ +.It Dv SIGKILL No (Killed) +This signal cannot be caught or ignored. +The (unconditional) action is to terminate the process. +It is most often sent by system administrators, but is also generated +by the kernel in response to running completely out of memory and +swap space. +Note that because many processes need to perform cleanup before +exiting, it is usually best (as a user or administrator) to not deploy +.Dv SIGKILL +until a process has failed to respond to other signals. +The number for +.Dv SIGKILL +is\~9, which is extremely well known. +.\" ************ +.It Dv SIGBUS No (Bus error) +This signal is generated synchronously by the kernel when the process +performs certain kinds of invalid memory accesses. +The most common cause of +.Dv SIGBUS +is an unaligned memory access; however, on some architectures it may +cover other memory conditions, such as attempts to access memory +belonging to the kernel. +The default action is to terminate the process and dump core. +Note: the results of performing such invalid accesses when +.Dv SIGBUS +is blocked or ignored are formally unspecified. +The number for +.Dv SIGBUS +is\~10. +.\" ************ +.It Dv SIGSEGV No (Segmentation fault) +This signal is generated synchronously by the kernel when the process +attempts to access unmapped memory, or access memory in a manner that +the protection settings for that memory region do not permit. +On some architectures other assorted permission or protection errors +also yield +.Dv SIGSEGV . +On +.Nx , +passing invalid pointers to system calls will yield failure with +.Er EFAULT +but not also +.Dv SIGSEGV . +The default action is to terminate the process and dump core. +Note: the results of an invalid memory access when +.Dv SIGSEGV +is blocked or ignored are formally unspecified. +The number for +.Dv SIGSEGV +is\~11, which is very well known. +.\" ************ +.It Dv SIGSYS No (Bad system call) +This signal is generated by the kernel, in addition to failing with +.Er ENOSYS , +when a system call is made using an invalid system call number. +.\" (This facility was intended to facilitate emulation of system calls.) +The default action is to terminate the process and dump core. +The number for +.Dv SIGSYS +is\~12. +.\" ************ +.It Dv SIGPIPE No (Broken pipe) +This signal is generated by the kernel, in addition to failing with +.Er EPIPE , +when a +.Xr write 2 +call or similar is made on a pipe or socket that has been closed and +has no readers. +The default action is to terminate the process. +The number for +.Dv SIGPIPE +is\~13. +.\" ************ +.It Dv SIGALRM No (Alarm clock) +This signal is generated by the kernel when a real-time timer expires. +See +.Xr alarm 3 , +.Xr setitimer 2 , +and +.Xr timer_settime 2 . +The default action is to terminate the process. +The number for +.Dv SIGALRM +is\~14. +.\" ************ +.It Dv SIGTERM No (Terminated) +This signal is the default signal sent by +.Xr kill 1 +and represents a user or administrator request that a program shut +down. +It is sent to all processes as part of the +.Xr shutdown 8 +procedure. +The default action is to terminate the process. +The number for +.Dv SIGTERM +is\~15. +.\" ************ +.It Dv SIGURG No (Urgent I/O condition) +This signal is generated when an ``urgent condition'' exists on a +socket. +In practice this means when +.Xr tcp 4 +out-of-band data has arrived. +The default action is to do nothing. +The number for +.Dv SIGURG +is\~16. +.\" ************ +.It Dv SIGSTOP No (Suspended (signal)) +This signal cannot be caught or ignored. +The (unconditional) action is to stop the process. +Note that like with +.Dv SIGKILL +(and for similar reasons) it is best to not send this signal until a +process has failed to respond to +.Dv SIGTSTP . +It can also be used by processes to stop themselves after catching +.Dv SIGTSTP . +A process that is explicitly stopped will not run again until told to +with +.Dv SIGCONT . +The number for +.Dv SIGSTOP +is\~17. +.\" ************ +.It Dv SIGTSTP No (Suspended) +This signal is generated by the +.Xr tty 4 +driver +when the user presses the stop character, normally control-Z. +The default action is to stop the process. +The number for +.Dv SIGTSTP +is\~18. +.\" ************ +.It Dv SIGCONT No (Continued) +This signal is generated by the job-control feature of shells to +manage processes. +It causes the target process to start executing again after previously +being stopped. +This happens as a magic extra effect +.Nm before +the signal is actually delivered. +The default action when the signal is delivered is to do nothing (else). +The number for +.Dv SIGCONT +is\~19. +.\" ************ +.It Dv SIGCHLD No (Child exited, stopped or continued) +This signal is generated by the kernel when one of a process's +immediate children exits and can be waited for using one of the +.Xr wait 2 +family of functions. +The default action is to do nothing. +.Pp +As a special case, if a child exits when its parent process has +.Dv SIGCHLD +ignored +.Pq not merely blocked +by having its signal handler set to +.Dv SIG_IGN , +or if the signal action has the +.Dv SA_NOCLDWAIT +flag set +.Pq Xr sigaction 2 , +then the child is detached so that +.Xr wait 2 +in the parent will wait for +.Em all +children to exit and then fail with +.Er ECHILD +without returning any information about any specific child processes. +.Pp +The number for +.Dv SIGCHLD +is\~20. +This signal was spelled +.Dv SIGCLD +in old System V versions and today many systems provide both +spellings. +.\" ************ +.It Dv SIGTTIN No (Stopped (tty input)) +This signal is generated by the +.Xr tty 4 +driver +when a process that is not in the foreground of its controlling +terminal attempts to read from this terminal. +The default action is to stop the process. +The number for +.Dv SIGTTIN +is\~21. +.\" ************ +.It Dv SIGTTOU No (Stopped (tty output)) +This signal is generated by the +.Xr tty 4 +driver +when a process that is not in the foreground of its controlling +terminal attempts to write to this terminal, if the terminal is +configured accordingly, which is not the default. +(See +.Xr termios 4 . ) +The default action is to stop the process. +The number for +.Dv SIGTTOU +is\~22. +.\" ************ +.It Dv SIGIO No (I/O possible) +This signal is sent by the kernel when I/O becomes possible on a file +handle opened for asynchronous access with +.Dv O_ASYNC . +See +.Xr open 2 +and +.Xr fcntl 2 . +The default action is to do nothing. +The number for +.Dv SIGIO +is\~23. +.\" ************ +.It Dv SIGXCPU No (CPU time limit exceeded) +This signal is sent by the kernel when the amount of CPU time consumed +exceeds the configured limit. +See +.Xr setrlimit 2 +and the +.Ic ulimit +and +.Ic rlimit +builtins of +.Xr sh 1 +and +.Xr csh 1 +respectively. +The default action is to terminate the process. +The number for +.Dv SIGXCPU +is\~24. +.\" ************ +.It Dv SIGXFSZ No (File size limit exceeded) +This signal is sent by the kernel when a write causes the size of a +file to exceed the configured limit. +See +.Xr setrlimit 2 +and the +.Ic ulimit +and +.Ic rlimit +builtins of +.Xr sh 1 +and +.Xr csh 1 +respectively. +The default action is to terminate the process. +The number for +.Dv SIGXFSZ +is\~25. +.\" ************ +.It Dv SIGVTALRM No (Virtual timer expired) +This signal is generated by the kernel when a virtual-time (process +execution time) timer expires. +See +.Xr setitimer 2 +and +.Xr timer_settime 2 . +The default action is to terminate the process. +The number for +.Dv SIGVTALRM +is\~26. +.\" ************ +.It Dv SIGPROF No (Profiling timer expired) +This signal is generated by the kernel when a profiling timer +expires. +See +.Xr setitimer 2 +and +.Xr timer_settime 2 . +The default action is to terminate the process. +The number for +.Dv SIGPROF +is\~27. +.\" ************ +.It Dv SIGWINCH No (Window size changed) +This signal is generated by the +.Xr tty 4 +driver +when the stored window size of the process's controlling terminal has +changed. +The default action is to do nothing. +The number for +.Dv SIGWINCH +is\~28. +.\" ************ +.It Dv SIGINFO No (Information request) +This signal is generated by the +.Xr tty 4 +driver +when the user presses the status request character, normally +control-T. +The default action is to do nothing. +The number for +.Dv SIGINFO +is\~29. +.\" ************ +.It Dv SIGUSR1 No (User defined signal 1) +This signal is not generated by the system and is made available for +applications to use for their own purposes. +Many daemons use it for restart or reload requests of various types. +The default action is to terminate the process. +The number for +.Dv SIGUSR1 +is\~30. +.\" ************ +.It Dv SIGUSR2 No (User defined signal 2) +This signal is not generated by the system and is made available for +applications to use for their own purposes. +The default action is to terminate the process. +The number for +.Dv SIGUSR2 +is\~31. +.\" ************ +.It Dv SIGPWR No (Power fail/restart) +This signal is notionally sent by the kernel or by a privileged +monitor process when an external power failure is detected, and again +when power has been restored. +Currently +.Nx +does not in fact send +.Dv SIGPWR , +although it is possible to prepare a custom configuration for +.Xr powerd 8 +that does so. +The default action is to do nothing. +The number for +.Dv SIGPWR +is\~32. +.\" ************ +.El +.Ss Shell Interface +Signals may be sent with the +.Xr kill 1 +utility, either by number or the symbolic name without the ``SIG'' part. +This utility is built into many shells to allow addressing job control +jobs. +.Ss Program Interface +In C code signals may be sent using +.Xr raise 3 , +.Xr kill 2 , +.Xr pthread_kill 3 , +and some other related functions. +.Pp +Signals may be caught or ignored using +.Xr sigaction 2 +or the simpler +.Xr signal 3 , +and blocked using +.Xr sigprocmask 2 . +.Sh STANDARDS +The +.Dv SIGTRAP , +.Dv SIGEMT , +.Dv SIGBUS , +.Dv SIGSYS , +.Dv SIGURG , +.Dv SIGIO , +.Dv SIGXCPU , +.Dv SIGXFSZ , +.Dv SIGVTALRM , +.Dv SIGPROF , +.Dv SIGWINCH , +and +.Dv SIGINFO +signals are long-existing Berkeley extensions, available on most +.Bx Ns \-derived +systems. +The +.Dv SIGPWR +signal comes from System V. +.Pp +The remaining signals conform to +.St -p1003.1-90 . +.Sh HISTORY +.Dv SIGPWR +was introduced in +.Nx 1.4 . |