xref: /netbsd-src/external/gpl3/gcc/dist/libstdc++-v3/doc/xml/manual/diagnostics.xml (revision b1e838363e3c6fc78a55519254d99869742dd33c)
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>
171