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

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