libstdc++-v3/doc/html/manual/termination.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Termination</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><meta name="keywords" content="
   2       ISO C++
   3     ,
   4       library
   5     "><meta name="keywords" content="
   6       ISO C++
   7     ,
   8       runtime
   9     ,
  10       library
  11     "><link rel="home" href="../index.html" title="The GNU C++ Library"><link rel="up" href="support.html" title="Chapter 4.  Support"><link rel="prev" href="dynamic_memory.html" title="Dynamic Memory"><link rel="next" href="diagnostics.html" title="Chapter 5.  Diagnostics"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Termination</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="dynamic_memory.html">Prev</a> </td><th width="60%" align="center">Chapter 4.
  12   Support
  13
  14 </th><td width="20%" align="right"> <a accesskey="n" href="diagnostics.html">Next</a></td></tr></table><hr></div><div class="section" title="Termination"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="std.support.termination"></a>Termination</h2></div></div></div><div class="section" title="Termination Handlers"><div class="titlepage"><div><div><h3 class="title"><a name="support.termination.handlers"></a>Termination Handlers</h3></div></div></div><p>
  15       Not many changes here to <code class="filename">cstdlib</code>.  You should note that the
  16       <code class="function">abort()</code> function does not call the
  17       destructors of automatic nor static objects, so if you're
  18       depending on those to do cleanup, it isn't going to happen.
  19       (The functions registered with <code class="function">atexit()</code>
  20       don't get called either, so you can forget about that
  21       possibility, too.)
  22     </p><p>
  23       The good old <code class="function">exit()</code> function can be a bit
  24       funky, too, until you look closer.  Basically, three points to
  25       remember are:
  26     </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
  27         Static objects are destroyed in reverse order of their creation.
  28         </p></li><li class="listitem"><p>
  29         Functions registered with <code class="function">atexit()</code> are called in
  30         reverse order of registration, once per registration call.
  31         (This isn't actually new.)
  32         </p></li><li class="listitem"><p>
  33         The previous two actions are <span class="quote">“<span class="quote">interleaved,</span>”</span> that is,
  34         given this pseudocode:
  35         </p><pre class="programlisting">
  36   extern "C or C++" void  f1 (void);
  37   extern "C or C++" void  f2 (void);
  38
  39   static Thing obj1;
  40   atexit(f1);
  41   static Thing obj2;
  42   atexit(f2);
  43 </pre><p>
  44         then at a call of <code class="function">exit()</code>,
  45         <code class="varname">f2</code> will be called, then
  46         <code class="varname">obj2</code> will be destroyed, then
  47         <code class="varname">f1</code> will be called, and finally
  48         <code class="varname">obj1</code> will be destroyed. If
  49         <code class="varname">f1</code> or <code class="varname">f2</code> allow an
  50         exception to propagate out of them, Bad Things happen.
  51         </p></li></ol></div><p>
  52       Note also that <code class="function">atexit()</code> is only required to store 32
  53       functions, and the compiler/library might already be using some of
  54       those slots.  If you think you may run out, we recommend using
  55       the <code class="function">xatexit</code>/<code class="function">xexit</code> combination from <code class="literal">libiberty</code>, which has no such limit.
  56     </p></div><div class="section" title="Verbose Terminate Handler"><div class="titlepage"><div><div><h3 class="title"><a name="support.termination.verbose"></a>Verbose Terminate Handler</h3></div></div></div><p>
  57       If you are having difficulty with uncaught exceptions and want a
  58       little bit of help debugging the causes of the core dumps, you can
  59       make use of a GNU extension, the verbose terminate handler.
  60     </p><pre class="programlisting">
  61 #include &lt;exception&gt;
  62
  63 int main()
  64 {
  65   std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
  66   ...
  67
  68   throw <em class="replaceable"><code>anything</code></em>;
  69 }
  70 </pre><p>
  71      The <code class="function">__verbose_terminate_handler</code> function
  72      obtains the name of the current exception, attempts to demangle
  73      it, and prints it to stderr.  If the exception is derived from
  74      <code class="classname">exception</code> then the output from
  75      <code class="function">what()</code> will be included.
  76    </p><p>
  77      Any replacement termination function is required to kill the
  78      program without returning; this one calls abort.
  79    </p><p>
  80      For example:
  81    </p><pre class="programlisting">
  82 #include &lt;exception&gt;
  83 #include &lt;stdexcept&gt;
  84
  85 struct argument_error : public std::runtime_error
  86 {
  87   argument_error(const std::string&amp; s): std::runtime_error(s) { }
  88 };
  89
  90 int main(int argc)
  91 {
  92   std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
  93   if (argc &gt; 5)
  94     throw argument_error(<span class="quote">“<span class="quote">argc is greater than 5!</span>”</span>);
  95   else
  96     throw argc;
  97 }
  98 </pre><p>
  99      With the verbose terminate handler active, this gives:
 100    </p><pre class="screen">
 101    <code class="computeroutput">
 102    % ./a.out
 103    terminate called after throwing a `int'
 104    Aborted
 105    % ./a.out f f f f f f f f f f f
 106    terminate called after throwing an instance of `argument_error'
 107    what(): argc is greater than 5!
 108    Aborted
 109    </code>
 110    </pre><p>
 111      The 'Aborted' line comes from the call to
 112      <code class="function">abort()</code>, of course.
 113    </p><p>
 114      This is the default termination handler; nothing need be done to
 115      use it.  To go back to the previous <span class="quote">“<span class="quote">silent death</span>”</span>
 116      method, simply include <code class="filename">exception</code> and
 117      <code class="filename">cstdlib</code>, and call
 118    </p><pre class="programlisting">
 119      std::set_terminate(std::abort);
 120    </pre><p>
 121      After this, all calls to <code class="function">terminate</code> will use
 122      <code class="function">abort</code> as the terminate handler.
 123    </p><p>
 124      Note: the verbose terminate handler will attempt to write to
 125      stderr.  If your application closes stderr or redirects it to an
 126      inappropriate location,
 127      <code class="function">__verbose_terminate_handler</code> will behave in
 128      an unspecified manner.
 129    </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dynamic_memory.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="diagnostics.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Dynamic Memory </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5.
 130   Diagnostics
 131
 132 </td></tr></table></div></body></html>