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"><exception></filename>, 26 <filename class="headerfile"><stdexcept></filename>, 27 <filename class="headerfile"><new></filename>, and 28 <filename class="headerfile"><typeinfo></filename>. 29 The C++ 2011 revision of the standard added more exception types 30 in the headers 31 <filename class="headerfile"><functional></filename>, 32 <filename class="headerfile"><future></filename>, 33 <filename class="headerfile"><regex></filename>, and 34 <filename class="headerfile"><system_error></filename>. 35 The C++ 2017 revision of the standard added more exception types 36 in the headers 37 <filename class="headerfile"><any></filename>, 38 <filename class="headerfile"><filesystem></filename>, 39 <filename class="headerfile"><optional></filename>, and 40 <filename class="headerfile"><variant></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"><exception></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& 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