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