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& 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> 161