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