libstdc++-v3/doc/xml/manual/support.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
   4 [ ]>
   5
   6 <chapter id="std.support" xreflabel="Support">
   7 <?dbhtml filename="support.html"?>
   8
   9 <chapterinfo>
  10   <keywordset>
  11     <keyword>
  12       ISO C++
  13     </keyword>
  14     <keyword>
  15       library
  16     </keyword>
  17   </keywordset>
  18 </chapterinfo>
  19
  20 <title>
  21   Support
  22   <indexterm><primary>Support</primary></indexterm>
  23 </title>
  24
  25   <para>
  26     This part deals with the functions called and objects created
  27     automatically during the course of a program's existence.
  28   </para>
  29
  30   <para>
  31     While we can't reproduce the contents of the Standard here (you
  32     need to get your own copy from your nation's member body; see our
  33     homepage for help), we can mention a couple of changes in what
  34     kind of support a C++ program gets from the Standard Library.
  35   </para>
  36
  37 <sect1 id="std.support.types" xreflabel="Types">
  38   <?dbhtml filename="fundamental_types.html"?>
  39   <title>Types</title>
  40   <sect2 id="std.support.types.fundamental" xreflabel="Fundamental Types">
  41     <title>Fundamental Types</title>
  42     <para>
  43       C++ has the following builtin types:
  44     </para>
  45     <itemizedlist>
  46       <listitem><para>
  47         char
  48       </para></listitem>
  49       <listitem><para>
  50         signed char
  51       </para></listitem>
  52       <listitem><para>
  53         unsigned char
  54       </para></listitem>
  55       <listitem><para>
  56         signed short
  57       </para></listitem>
  58       <listitem><para>
  59         signed int
  60       </para></listitem>
  61       <listitem><para>
  62         signed long
  63       </para></listitem>
  64       <listitem><para>
  65         unsigned short
  66       </para></listitem>
  67       <listitem><para>
  68         unsigned int
  69       </para></listitem>
  70       <listitem><para>
  71         unsigned long
  72       </para></listitem>
  73       <listitem><para>
  74         bool
  75       </para></listitem>
  76       <listitem><para>
  77         wchar_t
  78       </para></listitem>
  79       <listitem><para>
  80         float
  81       </para></listitem>
  82       <listitem><para>
  83         double
  84       </para></listitem>
  85       <listitem><para>
  86         long double
  87       </para></listitem>
  88     </itemizedlist>
  89
  90     <para>
  91       These fundamental types are always available, without having to
  92       include a header file. These types are exactly the same in
  93       either C++ or in C.
  94     </para>
  95
  96     <para>
  97       Specializing parts of the library on these types is prohibited:
  98       instead, use a POD.
  99     </para>
 100
 101   </sect2>
 102   <sect2 id="std.support.types.numeric_limits" xreflabel="Numeric Properties">
 103     <title>Numeric Properties</title>
 104
 105
 106     <para>
 107     The header <filename class="headerfile">limits</filename> defines
 108     traits classes to give access to various implementation
 109     defined-aspects of the fundamental types. The traits classes --
 110     fourteen in total -- are all specializations of the template class
 111     <classname>numeric_limits</classname>, documented <ulink
 112     url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00593.html">here</ulink>
 113     and defined as follows:
 114     </para>
 115
 116    <programlisting>
 117    template&lt;typename T&gt;
 118      struct class
 119      {
 120        static const bool is_specialized;
 121        static T max() throw();
 122        static T min() throw();
 123
 124        static const int digits;
 125        static const int digits10;
 126        static const bool is_signed;
 127        static const bool is_integer;
 128        static const bool is_exact;
 129        static const int radix;
 130        static T epsilon() throw();
 131        static T round_error() throw();
 132
 133        static const int min_exponent;
 134        static const int min_exponent10;
 135        static const int max_exponent;
 136        static const int max_exponent10;
 137
 138        static const bool has_infinity;
 139        static const bool has_quiet_NaN;
 140        static const bool has_signaling_NaN;
 141        static const float_denorm_style has_denorm;
 142        static const bool has_denorm_loss;
 143        static T infinity() throw();
 144        static T quiet_NaN() throw();
 145        static T denorm_min() throw();
 146
 147        static const bool is_iec559;
 148        static const bool is_bounded;
 149        static const bool is_modulo;
 150
 151        static const bool traps;
 152        static const bool tinyness_before;
 153        static const float_round_style round_style;
 154      };
 155    </programlisting>
 156   </sect2>
 157
 158   <sect2 id="std.support.types.null" xreflabel="NULL">
 159     <title>NULL</title>
 160     <para>
 161      The only change that might affect people is the type of
 162      <constant>NULL</constant>: while it is required to be a macro,
 163      the definition of that macro is <emphasis>not</emphasis> allowed
 164      to be <constant>(void*)0</constant>, which is often used in C.
 165     </para>
 166
 167     <para>
 168      For <command>g++</command>, <constant>NULL</constant> is
 169      <programlisting>#define</programlisting>'d to be
 170      <constant>__null</constant>, a magic keyword extension of
 171      <command>g++</command>.
 172     </para>
 173
 174     <para>
 175      The biggest problem of #defining <constant>NULL</constant> to be
 176      something like <quote>0L</quote> is that the compiler will view
 177      that as a long integer before it views it as a pointer, so
 178      overloading won't do what you expect. (This is why
 179      <command>g++</command> has a magic extension, so that
 180      <constant>NULL</constant> is always a pointer.)
 181     </para>
 182
 183     <para>In his book <ulink
 184     url="http://www.awprofessional.com/titles/0-201-92488-9/"><emphasis>Effective
 185     C++</emphasis></ulink>, Scott Meyers points out that the best way
 186     to solve this problem is to not overload on pointer-vs-integer
 187     types to begin with.  He also offers a way to make your own magic
 188     <constant>NULL</constant> that will match pointers before it
 189     matches integers.
 190     </para>
 191     <para>See
 192       <ulink url="http://www.awprofessional.com/titles/0-201-31015-5/">the
 193       Effective C++ CD example</ulink>
 194     </para>
 195   </sect2>
 196
 197 </sect1>
 198
 199 <sect1 id="std.support.memory" xreflabel="Dynamic Memory">
 200   <?dbhtml filename="dynamic_memory.html"?>
 201   <title>Dynamic Memory</title>
 202   <para>
 203     There are six flavors each of <function>new</function> and
 204     <function>delete</function>, so make certain that you're using the right
 205     ones. Here are quickie descriptions of <function>new</function>:
 206   </para>
 207   <itemizedlist>
 208       <listitem><para>
 209         single object form, throwing a
 210         <classname>bad_alloc</classname> on errors; this is what most
 211         people are used to using
 212       </para></listitem>
 213       <listitem><para>
 214         Single object &quot;nothrow&quot; form, returning NULL on errors
 215       </para></listitem>
 216       <listitem><para>
 217         Array <function>new</function>, throwing
 218         <classname>bad_alloc</classname> on errors
 219       </para></listitem>
 220       <listitem><para>
 221         Array nothrow <function>new</function>, returning
 222         <constant>NULL</constant> on errors
 223       </para></listitem>
 224       <listitem><para>
 225         Placement <function>new</function>, which does nothing (like
 226         it's supposed to)
 227       </para></listitem>
 228       <listitem><para>
 229         Placement array <function>new</function>, which also does
 230         nothing
 231       </para></listitem>
 232    </itemizedlist>
 233    <para>
 234      They are distinguished by the parameters that you pass to them, like
 235      any other overloaded function.  The six flavors of <function>delete</function>
 236      are distinguished the same way, but none of them are allowed to throw
 237      an exception under any circumstances anyhow.  (They match up for
 238      completeness' sake.)
 239    </para>
 240    <para>
 241      Remember that it is perfectly okay to call <function>delete</function> on a
 242      NULL pointer!  Nothing happens, by definition.  That is not the
 243      same thing as deleting a pointer twice.
 244    </para>
 245    <para>
 246      By default, if one of the <quote>throwing <function>new</function>s</quote> can't
 247      allocate the memory requested, it tosses an instance of a
 248      <classname>bad_alloc</classname> exception (or, technically, some class derived
 249      from it).  You can change this by writing your own function (called a
 250      new-handler) and then registering it with <function>set_new_handler()</function>:
 251    </para>
 252    <programlisting>
 253    typedef void (*PFV)(void);
 254
 255    static char*  safety;
 256    static PFV    old_handler;
 257
 258    void my_new_handler ()
 259    {
 260        delete[] safety;
 261        popup_window ("Dude, you are running low on heap memory.  You
 262                       should, like, close some windows, or something.
 263                       The next time you run out, we're gonna burn!");
 264        set_new_handler (old_handler);
 265        return;
 266    }
 267
 268    int main ()
 269    {
 270        safety = new char[500000];
 271        old_handler = set_new_handler (&amp;my_new_handler);
 272        ...
 273    }
 274    </programlisting>
 275    <para>
 276      <classname>bad_alloc</classname> is derived from the base <classname>exception</classname>
 277      class defined in Sect1 19.
 278    </para>
 279 </sect1>
 280
 281 <sect1 id="std.support.termination" xreflabel="Termination">
 282   <?dbhtml filename="termination.html"?>
 283   <title>Termination</title>
 284   <sect2 id="support.termination.handlers" xreflabel="Termination Handlers">
 285     <title>Termination Handlers</title>
 286     <para>
 287       Not many changes here to <filename
 288       class="headerfile">cstdlib</filename>.  You should note that the
 289       <function>abort()</function> function does not call the
 290       destructors of automatic nor static objects, so if you're
 291       depending on those to do cleanup, it isn't going to happen.
 292       (The functions registered with <function>atexit()</function>
 293       don't get called either, so you can forget about that
 294       possibility, too.)
 295     </para>
 296     <para>
 297       The good old <function>exit()</function> function can be a bit
 298       funky, too, until you look closer.  Basically, three points to
 299       remember are:
 300     </para>
 301     <orderedlist>
 302       <listitem>
 303         <para>
 304         Static objects are destroyed in reverse order of their creation.
 305         </para>
 306       </listitem>
 307       <listitem>
 308         <para>
 309         Functions registered with <function>atexit()</function> are called in
 310         reverse order of registration, once per registration call.
 311         (This isn't actually new.)
 312         </para>
 313       </listitem>
 314       <listitem>
 315         <para>
 316         The previous two actions are <quote>interleaved,</quote> that is,
 317         given this pseudocode:
 318         </para>
 319 <programlisting>
 320   extern "C or C++" void  f1 (void);
 321   extern "C or C++" void  f2 (void);
 322
 323   static Thing obj1;
 324   atexit(f1);
 325   static Thing obj2;
 326   atexit(f2);
 327 </programlisting>
 328         <para>
 329         then at a call of <function>exit()</function>,
 330         <varname>f2</varname> will be called, then
 331         <varname>obj2</varname> will be destroyed, then
 332         <varname>f1</varname> will be called, and finally
 333         <varname>obj1</varname> will be destroyed. If
 334         <varname>f1</varname> or <varname>f2</varname> allow an
 335         exception to propagate out of them, Bad Things happen.
 336         </para>
 337       </listitem>
 338     </orderedlist>
 339     <para>
 340       Note also that <function>atexit()</function> is only required to store 32
 341       functions, and the compiler/library might already be using some of
 342       those slots.  If you think you may run out, we recommend using
 343       the <function>xatexit</function>/<function>xexit</function> combination from <literal>libiberty</literal>, which has no such limit.
 344     </para>
 345   </sect2>
 346
 347   <sect2 id="support.termination.verbose" xreflabel="Verbose Terminate Handler">
 348   <?dbhtml filename="verbose_termination.html"?>
 349     <title>Verbose Terminate Handler</title>
 350     <para>
 351       If you are having difficulty with uncaught exceptions and want a
 352       little bit of help debugging the causes of the core dumps, you can
 353       make use of a GNU extension, the verbose terminate handler.
 354     </para>
 355
 356 <programlisting>
 357 #include &lt;exception&gt;
 358
 359 int main()
 360 {
 361   std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
 362   ...
 363
 364   throw <replaceable>anything</replaceable>;
 365 }
 366 </programlisting>
 367
 368    <para>
 369      The <function>__verbose_terminate_handler</function> function
 370      obtains the name of the current exception, attempts to demangle
 371      it, and prints it to stderr.  If the exception is derived from
 372      <classname>exception</classname> then the output from
 373      <function>what()</function> will be included.
 374    </para>
 375
 376    <para>
 377      Any replacement termination function is required to kill the
 378      program without returning; this one calls abort.
 379    </para>
 380
 381    <para>
 382      For example:
 383    </para>
 384
 385 <programlisting>
 386 #include &lt;exception&gt;
 387 #include &lt;stdexcept&gt;
 388
 389 struct argument_error : public std::runtime_error
 390 {
 391   argument_error(const std::string&amp; s): std::runtime_error(s) { }
 392 };
 393
 394 int main(int argc)
 395 {
 396   std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
 397   if (argc &gt; 5)
 398     throw argument_error(<quote>argc is greater than 5!</quote>);
 399   else
 400     throw argc;
 401 }
 402 </programlisting>
 403
 404    <para>
 405      With the verbose terminate handler active, this gives:
 406    </para>
 407
 408    <screen>
 409    <computeroutput>
 410    % ./a.out
 411    terminate called after throwing a `int'
 412    Aborted
 413    % ./a.out f f f f f f f f f f f
 414    terminate called after throwing an instance of `argument_error'
 415    what(): argc is greater than 5!
 416    Aborted
 417    </computeroutput>
 418    </screen>
 419
 420    <para>
 421      The 'Aborted' line comes from the call to
 422      <function>abort()</function>, of course.
 423    </para>
 424
 425    <para>
 426      This is the default termination handler; nothing need be done to
 427      use it.  To go back to the previous <quote>silent death</quote>
 428      method, simply include <filename>exception</filename> and
 429      <filename>cstdlib</filename>, and call
 430    </para>
 431
 432    <programlisting>
 433      std::set_terminate(std::abort);
 434    </programlisting>
 435
 436    <para>
 437      After this, all calls to <function>terminate</function> will use
 438      <function>abort</function> as the terminate handler.
 439    </para>
 440
 441    <para>
 442      Note: the verbose terminate handler will attempt to write to
 443      stderr.  If your application closes stderr or redirects it to an
 444      inappropriate location,
 445      <function>__verbose_terminate_handler</function> will behave in
 446      an unspecified manner.
 447    </para>
 448
 449   </sect2>
 450 </sect1>
 451
 452 </chapter>