NetBSD/share/man/man7/signal.7

.\"	$NetBSD: signal.7,v 1.26 2021/05/30 07:17:01 dholland 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.
As a special case hack, if
.Dv SIGCHLD
is ignored (not merely blocked) when a process is
.Em created ,
it is detached from its parent immediately so it need not be waited
for.
This behavior is a System V historic wart, implemented in
.Nx
only for compatibility.
It is not portable, not recommended, and should not be used by new
code.
.\" XXX should refer to something that can be used by new code...
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 .