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

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