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

   1 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
   2          xml:id="std.diagnostics" xreflabel="Diagnostics">
   3 <?dbhtml filename="diagnostics.html"?>
   4
   5 <info><title>
   6   Diagnostics
   7   <indexterm><primary>Diagnostics</primary></indexterm>
   8 </title>
   9   <keywordset>
  10     <keyword>ISO C++</keyword>
  11     <keyword>library</keyword>
  12   </keywordset>
  13 </info>
  14
  15
  16
  17 <section xml:id="std.diagnostics.exceptions" xreflabel="Exceptions"><info><title>Exceptions</title></info>
  18   <?dbhtml filename="exceptions.html"?>
  19
  20
  21   <section xml:id="std.diagnostics.exceptions.api"><info><title>API Reference</title></info>
  22
  23     <para>
  24       All exception objects are defined in one of the standard header
  25       files: <filename>exception</filename>,
  26       <filename>stdexcept</filename>, <filename>new</filename>, and
  27       <filename>typeinfo</filename>.
  28     </para>
  29
  30     <para>
  31       The base exception object is <classname>exception</classname>,
  32       located in <filename>exception</filename>. This object has no
  33       <classname>string</classname> member.
  34     </para>
  35
  36     <para>
  37       Derived from this are several classes that may have a
  38       <classname>string</classname> member: a full hierarchy can be
  39       found in the source documentation.
  40     </para>
  41
  42     <para>
  43       Full API details.
  44     </para>
  45
  46     <!-- Doxygen XML: api/group__exceptions.xml -->
  47
  48   </section>
  49   <section xml:id="std.diagnostics.exceptions.data" xreflabel="Adding Data to Exceptions"><info><title>Adding Data to <classname>exception</classname></title></info>
  50
  51     <para>
  52       The standard exception classes carry with them a single string as
  53       data (usually describing what went wrong or where the 'throw' took
  54     place).  It's good to remember that you can add your own data to
  55     these exceptions when extending the hierarchy:
  56    </para>
  57    <programlisting>
  58    struct My_Exception : public std::runtime_error
  59    {
  60      public:
  61        My_Exception (const string&amp; whatarg)
  62            : std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
  63        int  errno_at_time_of_throw() const { return e; }
  64        DBID id_of_thing_that_threw() const { return id; }
  65      protected:
  66        int    e;
  67        DBID   id;     // some user-defined type
  68    };
  69    </programlisting>
  70
  71   </section>
  72 </section>
  73
  74 <section xml:id="std.diagnostics.errno" xreflabel="errno"><info><title>Use of errno by the library</title></info>
  75   <?dbhtml filename="errno.html"?>
  76
  77   <para>
  78     The C and POSIX standards guarantee that <varname>errno</varname>
  79     is never set to zero by any library function.
  80     The C++ standard has less to say about when <varname>errno</varname>
  81     is or isn't set, but libstdc++ follows the same rule and never sets
  82     it to zero.
  83   </para>
  84
  85   <para>
  86     On the other hand, there are few guarantees about when the C++ library
  87     sets <varname>errno</varname> on error, beyond what is specified for
  88     functions that come from the C library.
  89     For example, when <function>std::stoi</function> throws an exception of
  90     type <classname>std::out_of_range</classname>, <varname>errno</varname>
  91     may or may not have been set to <constant>ERANGE</constant>.
  92   </para>
  93
  94   <para>
  95     Parts of the C++ library may be implemented in terms of C library
  96     functions, which may result in <varname>errno</varname> being set
  97     with no explicit call to a C function. For example, on a target where
  98     <function>operator new</function> uses <function>malloc</function>
  99     a failed memory allocation with <function>operator new</function> might
 100     set <varname>errno</varname> to <constant>ENOMEM</constant>.
 101     Which C++ library functions can set <varname>errno</varname> in this way
 102     is unspecified because it may vary between platforms and between releases.
 103   </para>
 104
 105 </section>
 106
 107 <section xml:id="std.diagnostics.concept_checking" xreflabel="Concept Checking"><info><title>Concept Checking</title></info>
 108   <?dbhtml filename="concept_checking.html"?>
 109
 110   <para>
 111     In 1999, SGI added <quote>concept checkers</quote> to their
 112     implementation of the STL: code which checked the template
 113     parameters of instantiated pieces of the STL, in order to insure
 114     that the parameters being used met the requirements of the
 115     standard.  For example, the Standard requires that types passed as
 116     template parameters to <classname>vector</classname> be
 117     "Assignable" (which means what you think it means).  The
 118     checking was done during compilation, and none of the code was
 119     executed at runtime.
 120    </para>
 121    <para>
 122      Unfortunately, the size of the compiler files grew significantly
 123      as a result.  The checking code itself was cumbersome.  And bugs
 124      were found in it on more than one occasion.
 125    </para>
 126    <para>
 127      The primary author of the checking code, Jeremy Siek, had already
 128      started work on a replacement implementation.  The new code was
 129      formally reviewed and accepted into
 130    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the
 131    Boost libraries</link>, and we are pleased to incorporate it into the
 132    GNU C++ library.
 133  </para>
 134  <para>
 135    The new version imposes a much smaller space overhead on the generated
 136    object file.  The checks are also cleaner and easier to read and
 137    understand.
 138  </para>
 139
 140  <para>
 141    They are off by default for all versions of GCC.
 142    They can be enabled at configure time with
 143    <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
 144    You can enable them on a per-translation-unit basis with
 145      <literal>-D_GLIBCXX_CONCEPT_CHECKS</literal>.
 146  </para>
 147
 148  <para>
 149    Please note that the checks are based on the requirements in the original
 150    C++ standard, many of which were relaxed in the C++11 standard and so valid
 151    C++11 code may be incorrectly rejected by the concept checks.  Additionally,
 152    some correct C++03 code might be rejected by the concept checks,
 153    for example template argument types may need to be complete when used in
 154    a template definition, rather than at the point of instantiation.
 155    There are no plans to address these shortcomings.
 156  </para>
 157
 158 </section>
 159
 160 </chapter>