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