<!-- This HTML file has been created by texi2html 1.27
     from library.texinfo on 3 March 1994 -->

<TITLE>The GNU C Library - Signal Handling</TITLE>
<P>Go to the <A HREF="library_20.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_20.html">previous</A>, <A HREF="library_22.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html">next</A> section.<P>
<H1><A NAME="SEC330" HREF="library_toc.html#SEC330" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC330">Signal Handling</A></H1>
<A NAME="IDX1452"></A>
<P>
A <DFN>signal</DFN> is a software interrupt delivered to a process.  The
operating system uses signals to report exceptional situations to an
executing program.  Some signals report errors such as references to
invalid memory addresses; others report asynchronous events, such as
disconnection of a phone line.
<P>
The GNU C library defines a variety of signal types, each for a
particular kind of event.  Some kinds of events make it inadvisable or
impossible for the program to proceed as usual, and the corresponding
signals normally abort the program.  Other kinds of signals that report
harmless events are ignored by default.
<P>
If you anticipate an event that causes signals, you can define a handler
function and tell the operating system to run it when that particular
type of signal arrives.
<P>
Finally, one process can send a signal to another process; this allows a
parent process to abort a child, or two related processes to communicate
and synchronize.
<P>
<H2><A NAME="SEC331" HREF="library_toc.html#SEC331" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC331">Basic Concepts of Signals</A></H2>
<P>
This section explains basic concepts of how signals are generated, what
happens after a signal is delivered, and how programs can handle
signals.
<P>
<H3><A NAME="SEC332" HREF="library_toc.html#SEC332" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC332">Some Kinds of Signals</A></H3>
<P>
A signal reports the occurrence of an exceptional event.  These are some
of the events that can cause (or <DFN>generate</DFN>, or <DFN>raise</DFN>) a
signal:
<P>
<UL>
<LI>
A program error such as dividing by zero or issuing an address outside
the valid range.
<P>
<LI>
A user request to interrupt or terminate the program.  Most environments
are set up to let a user suspend the program by typing <KBD>C-z</KBD>, or
terminate it with <KBD>C-c</KBD>.  Whatever key sequence is used, the
operating system sends the proper signal to interrupt the process.
<P>
<LI>
The termination of a child process.
<P>
<LI>
Expiration of a timer or alarm.
<P>
<LI>
A call to <CODE>kill</CODE> or <CODE>raise</CODE> by the same process.
<P>
<LI>
A call to <CODE>kill</CODE> from another process.  Signals are a limited but
useful form of interprocess communication.
</UL>
<P>
Each of these kinds of events (excepting explicit calls to <CODE>kill</CODE>
and <CODE>raise</CODE>) generates its own particular kind of signal.  The
various kinds of signals are listed and described in detail in
section <A HREF="library_21.html#SEC335" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC335">Standard Signals</A>.
<P>
<A NAME="IDX1453"></A>
<H3><A NAME="SEC333" HREF="library_toc.html#SEC333" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC333">Concepts of Signal Generation</A></H3>
<P>
In general, the events that generate signals fall into three major
categories: errors, external events, and explicit requests.
<P>
An error means that a program has done something invalid and cannot
continue execution.  But not all kinds of errors generate signals--in
fact, most do not.  For example, opening a nonexistant file is an error,
but it does not raise a signal; instead, <CODE>open</CODE> returns <CODE>-1</CODE>.
In general, errors that are necessarily associated with certain library
functions are reported by returning a value that indicates an error.
The errors which raise signals are those which can happen anywhere in
the program, not just in library calls.  These include division by zero
and invalid memory addresses.
<P>
An external event generally has to do with I/O or other processes.
These include the arrival of input, the expiration of a timer, and the
termination of a child process.
<P>
An explicit request means the use of a library function such as
<CODE>kill</CODE> whose purpose is specifically to generate a signal.
<P>
Signals may be generated <DFN>synchronously</DFN> or <DFN>asynchronously</DFN>.  A
synchronous signal pertains to a specific action in the program, and is
delivered (unless blocked) during that action.  Errors generate signals
synchronously, and so do explicit requests by a process to generate a
signal for that same process.
<P>
Asynchronous signals are generated by events outside the control of the
process that receives them.  These signals arrive at unpredictable times
during execution.  External events generate signals asynchronously, and
so do explicit requests that apply to some other process.
<P>
A given type of signal is either typically synchrous or typically
asynchronous.  For example, signals for errors are typically synchronous
because errors generate signals synchronously.  But any type of signal
can be generated synchronously or asynchronously with an explicit
request.
<P>
<A NAME="IDX1454"></A>
<A NAME="IDX1455"></A>
<A NAME="IDX1456"></A>
<H3><A NAME="SEC334" HREF="library_toc.html#SEC334" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC334">How Signals Are Delivered</A></H3>
<P>
When a signal is generated, it becomes <DFN>pending</DFN>.  Normally it
remains pending for just a short period of time and then is
<DFN>delivered</DFN> to the process that was signaled.  However, if that kind
of signal is currently <DFN>blocked</DFN>, it may remain pending
indefinitely--until signals of that kind are <DFN>unblocked</DFN>.  Once
unblocked, it will be delivered immediately.  See section <A HREF="library_21.html#SEC368" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC368">Blocking Signals</A>.
<A NAME="IDX1457"></A>
<A NAME="IDX1458"></A>
<A NAME="IDX1459"></A>
<A NAME="IDX1460"></A>
<P>
When the signal is delivered, whether right away or after a long delay,
the <DFN>specified action</DFN> for that signal is taken.  For certain
signals, such as <CODE>SIGKILL</CODE> and <CODE>SIGSTOP</CODE>, the action is fixed,
but for most signals, the program has a choice: ignore the signal,
specify a <DFN>handler function</DFN>, or accept the <DFN>default action</DFN> for
that kind of signal.  The program specifies its choice using functions
such as <CODE>signal</CODE> or <CODE>sigaction</CODE> (see section <A HREF="library_21.html#SEC344" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC344">Specifying Signal Actions</A>).  We
sometimes say that a handler <DFN>catches</DFN> the signal.  While the
handler is running, that particular signal is normally blocked.
<P>
If the specified action for a kind of signal is to ignore it, then any
such signal which is generated is discarded immediately.  This happens
even if the signal is also blocked at the time.  A signal discarded in
this way will never be delivered, not even if the program subsequently
specifies a different action for that kind of signal and then unblocks
it.
<P>
If a signal arrives which the program has neither handled nor ignored,
its <DFN>default action</DFN> takes place.  Each kind of signal has its own
default action, documented below (see section <A HREF="library_21.html#SEC335" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC335">Standard Signals</A>).  For most kinds
of signals, the default action is to terminate the process.  For certain
kinds of signals that represent "harmless" events, the default action
is to do nothing.
<P>
When a signal terminates a process, its parent process can determine the
cause of termination by examining the termination status code reported
by the <CODE>wait</CODE> or <CODE>waitpid</CODE> functions.  (This is discussed in
more detail in section <A HREF="library_23.html#SEC407" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC407">Process Completion</A>.)  The information it can get
includes the fact that termination was due to a signal, and the kind of
signal involved.  If a program you run from a shell is terminated by a
signal, the shell typically prints some kind of error message.
<P>
The signals that normally represent program errors have a special
property: when one of these signals terminates the process, it also
writes a <DFN>core dump file</DFN> which records the state of the process at
the time of termination.  You can examine the core dump with a debugger
to investigate what caused the error.
<P>
If you raise a "program error" signal by explicit request, and this
terminates the process, it makes a core dump file just as if the signal
had been due directly to an error.
<P>
<A NAME="IDX1461"></A>
<A NAME="IDX1462"></A>
<H2><A NAME="SEC335" HREF="library_toc.html#SEC335" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC335">Standard Signals</A></H2>
<A NAME="IDX1463"></A>
<A NAME="IDX1464"></A>
<P>
This section lists the names for various standard kinds of signals and
describes what kind of event they mean.  Each signal name is a macro
which stands for a positive integer--the <DFN>signal number</DFN> for that
kind of signal.  Your programs should never make assumptions about the
numeric code for a particular kind of signal, but rather refer to them
always by the names defined here.  This is because the number for a
given kind of signal can vary from system to system, but the meanings of
the names are standardized and fairly uniform.
<P>
The signal names are defined in the header file <TT>`signal.h'</TT>.
<P>
<A NAME="IDX1465"></A>
<U>Macro:</U> int <B>NSIG</B><P>
The value of this symbolic constant is the total number of signals
defined.  Since the signal numbers are allocated consecutively,
<CODE>NSIG</CODE> is also one greater than the largest defined signal number.
<P>
<A NAME="IDX1466"></A>
<H3><A NAME="SEC336" HREF="library_toc.html#SEC336" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC336">Program Error Signals</A></H3>
<P>
The following signals are generated when a serious program error is
detected by the operating system or the computer itself.  In general,
all of these signals are indications that your program is seriously
broken in some way, and there's usually no way to continue the
computation which encountered the error.
<P>
Some programs handle program error signals in order to tidy up before
terminating; for example, programs that turn off echoing of terminal
input should handle program error signals in order to turn echoing back
on.  The handler should end by specifying the default action for the
signal that happened and then reraising it; this will cause the program
to terminate with that signal, as if it had not had a handler.
(See section <A HREF="library_21.html#SEC353" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC353">Handlers That Terminate the Process</A>.)
<P>
Termination is the sensible ultimate outcome from a program error in
most programs.  However, programming systems such as Lisp that can load
compiled user programs might need to keep executing even if a user
program incurs an error.  These programs have handlers which use
<CODE>longjmp</CODE> to return control to the command level.
<P>
The default action for all of these signals is to cause the process to
terminate.  If you block or ignore these signals or establish handlers
for them that return normally, your program will probably break horribly
when such signals happen, unless they are generated by <CODE>raise</CODE> or
<CODE>kill</CODE> instead of a real error.
<A NAME="IDX1467"></A>
<P>
When one of these program error signals terminates a process, it also
writes a <DFN>core dump file</DFN> which records the state of the process at
the time of termination.  The core dump file is named <TT>`core'</TT> and is
written in whichever directory is current in the process at the time.
(On the GNU system, you can specify the file name for core dumps with
the environment variable <CODE>COREFILE</CODE>.)  The purpose of core dump
files is so that you can examine them with a debugger to investigate
what caused the error.
<P>
<A NAME="IDX1468"></A>
<U>Macro:</U> int <B>SIGFPE</B><P>
The <CODE>SIGFPE</CODE> signal reports a fatal arithmetic error.  Although the
name is derived from "floating-point exception", this signal actually
covers all arithmetic errors, including division by zero and overflow.
If a program stores integer data in a location which is then used in a
floating-point operation, this often causes an "invalid operation"
exception, because the processor cannot recognize the data as a
floating-point number.
<A NAME="IDX1470"></A>
<A NAME="IDX1469"></A>
<P>
Actual floating-point exceptions are a complicated subject because there
are many types of exceptions with subtly different meanings, and the
<CODE>SIGFPE</CODE> signal doesn't distinguish between them.  The <CITE>IEEE
Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985)</CITE>
defines various floating-point exceptions and requires conforming
computer systems to report their occurrences.  However, this standard
does not specify how the exceptions are reported, or what kinds of
handling and control the operating system can offer to the programmer.
<P>
BSD systems provide the <CODE>SIGFPE</CODE> handler with an extra argument
that distinguishes various causes of the exception.  In order to access
this argument, you must define the handler to accept two arguments,
which means you must cast it to a one-argument function type in order to
establish the handler.  The GNU library does provide this extra