<html lang="en">
<head>
<title>Basic Signal Handling - The GNU C Library</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="The GNU C Library">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Signal-Actions.html#Signal-Actions" title="Signal Actions">
<link rel="next" href="Advanced-Signal-Handling.html#Advanced-Signal-Handling" title="Advanced Signal Handling">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU C library.

This is Edition 0.12, last updated 2007-10-27,
of `The GNU C Library Reference Manual', for version
2.8 (Sourcery G++ Lite 2011.03-41).

Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software Needs Free Documentation''
and ``GNU Lesser General Public License'', the Front-Cover texts being
``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual.  Buying copies from the FSF
supports it in developing GNU and promoting software freedom.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Basic-Signal-Handling"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Advanced-Signal-Handling.html#Advanced-Signal-Handling">Advanced Signal Handling</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Signal-Actions.html#Signal-Actions">Signal Actions</a>
<hr>
</div>

<h4 class="subsection">24.3.1 Basic Signal Handling</h4>

<p><a name="index-g_t_0040code_007bsignal_007d-function-2907"></a>
The <code>signal</code> function provides a simple interface for establishing
an action for a particular signal.  The function and associated macros
are declared in the header file <samp><span class="file">signal.h</span></samp>. 
<a name="index-signal_002eh-2908"></a>
<!-- signal.h -->
<!-- GNU -->

<div class="defun">
&mdash; Data Type: <b>sighandler_t</b><var><a name="index-sighandler_005ft-2909"></a></var><br>
<blockquote><p>This is the type of signal handler functions.  Signal handlers take one
integer argument specifying the signal number, and have return type
<code>void</code>.  So, you should define handler functions like this:

     <pre class="smallexample">          void <var>handler</var> (int <code>signum</code>) { ... }
</pre>
        <p>The name <code>sighandler_t</code> for this data type is a GNU extension. 
</p></blockquote></div>

<!-- signal.h -->
<!-- ISO -->
<div class="defun">
&mdash; Function: sighandler_t <b>signal</b> (<var>int signum, sighandler_t action</var>)<var><a name="index-signal-2910"></a></var><br>
<blockquote><p>The <code>signal</code> function establishes <var>action</var> as the action for
the signal <var>signum</var>.

        <p>The first argument, <var>signum</var>, identifies the signal whose behavior
you want to control, and should be a signal number.  The proper way to
specify a signal number is with one of the symbolic signal names
(see <a href="Standard-Signals.html#Standard-Signals">Standard Signals</a>)&mdash;don't use an explicit number, because
the numerical code for a given kind of signal may vary from operating
system to operating system.

        <p>The second argument, <var>action</var>, specifies the action to use for the
signal <var>signum</var>.  This can be one of the following:

          <dl>
<dt><code>SIG_DFL</code><dd><a name="index-SIG_005fDFL-2911"></a><a name="index-default-action-for-a-signal-2912"></a><code>SIG_DFL</code> specifies the default action for the particular signal. 
The default actions for various kinds of signals are stated in
<a href="Standard-Signals.html#Standard-Signals">Standard Signals</a>.

          <br><dt><code>SIG_IGN</code><dd><a name="index-SIG_005fIGN-2913"></a><a name="index-ignore-action-for-a-signal-2914"></a><code>SIG_IGN</code> specifies that the signal should be ignored.

          <p>Your program generally should not ignore signals that represent serious
events or that are normally used to request termination.  You cannot
ignore the <code>SIGKILL</code> or <code>SIGSTOP</code> signals at all.  You can
ignore program error signals like <code>SIGSEGV</code>, but ignoring the error
won't enable the program to continue executing meaningfully.  Ignoring
user requests such as <code>SIGINT</code>, <code>SIGQUIT</code>, and <code>SIGTSTP</code>
is unfriendly.

          <p>When you do not wish signals to be delivered during a certain part of
the program, the thing to do is to block them, not ignore them. 
See <a href="Blocking-Signals.html#Blocking-Signals">Blocking Signals</a>.

          <br><dt><var>handler</var><dd>Supply the address of a handler function in your program, to specify
running this handler as the way to deliver the signal.

          <p>For more information about defining signal handler functions,
see <a href="Defining-Handlers.html#Defining-Handlers">Defining Handlers</a>. 
</dl>

        <p>If you set the action for a signal to <code>SIG_IGN</code>, or if you set it
to <code>SIG_DFL</code> and the default action is to ignore that signal, then
any pending signals of that type are discarded (even if they are
blocked).  Discarding the pending signals means that they will never be
delivered, not even if you subsequently specify another action and
unblock this kind of signal.

        <p>The <code>signal</code> function returns the action that was previously in
effect for the specified <var>signum</var>.  You can save this value and
restore it later by calling <code>signal</code> again.

        <p>If <code>signal</code> can't honor the request, it returns <code>SIG_ERR</code>
instead.  The following <code>errno</code> error conditions are defined for
this function:

          <dl>
<dt><code>EINVAL</code><dd>You specified an invalid <var>signum</var>; or you tried to ignore or provide
a handler for <code>SIGKILL</code> or <code>SIGSTOP</code>. 
</dl>
        </p></blockquote></div>

   <p><strong>Compatibility Note:</strong> A problem encountered when working with the
<code>signal</code> function is that it has different semantics on BSD and
SVID systems.  The difference is that on SVID systems the signal handler
is deinstalled after signal delivery.  On BSD systems the
handler must be explicitly deinstalled.  In the GNU C Library we use the
BSD version by default.  To use the SVID version you can either use the
function <code>sysv_signal</code> (see below) or use the <code>_XOPEN_SOURCE</code>
feature select macro (see <a href="Feature-Test-Macros.html#Feature-Test-Macros">Feature Test Macros</a>).  In general, use of these
functions should be avoided because of compatibility problems.  It
is better to use <code>sigaction</code> if it is available since the results
are much more reliable.

   <p>Here is a simple example of setting up a handler to delete temporary
files when certain fatal signals happen:

<pre class="smallexample">     #include &lt;signal.h&gt;
     
     void
     termination_handler (int signum)
     {
       struct temp_file *p;
     
       for (p = temp_file_list; p; p = p-&gt;next)
         unlink (p-&gt;name);
     }
     
     int
     main (void)
     {
       ...
       if (signal (SIGINT, termination_handler) == SIG_IGN)
         signal (SIGINT, SIG_IGN);
       if (signal (SIGHUP, termination_handler) == SIG_IGN)
         signal (SIGHUP, SIG_IGN);
       if (signal (SIGTERM, termination_handler) == SIG_IGN)
         signal (SIGTERM, SIG_IGN);
       ...
     }
</pre>
   <p class="noindent">Note that if a given signal was previously set to be ignored, this code
avoids altering that setting.  This is because non-job-control shells
often ignore certain signals when starting children, and it is important
for the children to respect this.

   <p>We do not handle <code>SIGQUIT</code> or the program error signals in this
example because these are designed to provide information for debugging
(a core dump), and the temporary files may give useful information.

<!-- signal.h -->
<!-- GNU -->
<div class="defun">
&mdash; Function: sighandler_t <b>sysv_signal</b> (<var>int signum, sighandler_t action</var>)<var><a name="index-sysv_005fsignal-2915"></a></var><br>
<blockquote><p>The <code>sysv_signal</code> implements the behavior of the standard
<code>signal</code> function as found on SVID systems.  The difference to BSD
systems is that the handler is deinstalled after a delivery of a signal.

        <p><strong>Compatibility Note:</strong> As said above for <code>signal</code>, this
function should be avoided when possible.  <code>sigaction</code> is the
preferred method. 
</p></blockquote></div>

<!-- signal.h -->
<!-- SVID -->
<div class="defun">
&mdash; Function: sighandler_t <b>ssignal</b> (<var>int signum, sighandler_t action</var>)<var><a name="index-ssignal-2916"></a></var><br>
<blockquote><p>The <code>ssignal</code> function does the same thing as <code>signal</code>; it is
provided only for compatibility with SVID. 
</p></blockquote></div>

<!-- signal.h -->
<!-- ISO -->
<div class="defun">
&mdash; Macro: sighandler_t <b>SIG_ERR</b><var><a name="index-SIG_005fERR-2917"></a></var><br>
<blockquote><p>The value of this macro is used as the return value from <code>signal</code>
to indicate an error. 
</p></blockquote></div>

   </body></html>