Retro68/gcc/libstdc++-v3/doc/xml/manual/diagnostics.xml
2017-04-10 13:32:00 +02:00

161 lines
6.0 KiB
XML

<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="std.diagnostics" xreflabel="Diagnostics">
<?dbhtml filename="diagnostics.html"?>
<info><title>
Diagnostics
<indexterm><primary>Diagnostics</primary></indexterm>
</title>
<keywordset>
<keyword>ISO C++</keyword>
<keyword>library</keyword>
</keywordset>
</info>
<section xml:id="std.diagnostics.exceptions" xreflabel="Exceptions"><info><title>Exceptions</title></info>
<?dbhtml filename="exceptions.html"?>
<section xml:id="std.diagnostics.exceptions.api"><info><title>API Reference</title></info>
<para>
All exception objects are defined in one of the standard header
files: <filename>exception</filename>,
<filename>stdexcept</filename>, <filename>new</filename>, and
<filename>typeinfo</filename>.
</para>
<para>
The base exception object is <classname>exception</classname>,
located in <filename>exception</filename>. This object has no
<classname>string</classname> member.
</para>
<para>
Derived from this are several classes that may have a
<classname>string</classname> member: a full hierarchy can be
found in the source documentation.
</para>
<para>
Full API details.
</para>
<!-- Doxygen XML: api/group__exceptions.xml -->
</section>
<section xml:id="std.diagnostics.exceptions.data" xreflabel="Adding Data to Exceptions"><info><title>Adding Data to <classname>exception</classname></title></info>
<para>
The standard exception classes carry with them a single string as
data (usually describing what went wrong or where the 'throw' took
place). It's good to remember that you can add your own data to
these exceptions when extending the hierarchy:
</para>
<programlisting>
struct My_Exception : public std::runtime_error
{
public:
My_Exception (const string&amp; whatarg)
: std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
int errno_at_time_of_throw() const { return e; }
DBID id_of_thing_that_threw() const { return id; }
protected:
int e;
DBID id; // some user-defined type
};
</programlisting>
</section>
</section>
<section xml:id="std.diagnostics.errno" xreflabel="errno"><info><title>Use of errno by the library</title></info>
<?dbhtml filename="errno.html"?>
<para>
The C and POSIX standards guarantee that <varname>errno</varname>
is never set to zero by any library function.
The C++ standard has less to say about when <varname>errno</varname>
is or isn't set, but libstdc++ follows the same rule and never sets
it to zero.
</para>
<para>
On the other hand, there are few guarantees about when the C++ library
sets <varname>errno</varname> on error, beyond what is specified for
functions that come from the C library.
For example, when <function>std::stoi</function> throws an exception of
type <classname>std::out_of_range</classname>, <varname>errno</varname>
may or may not have been set to <constant>ERANGE</constant>.
</para>
<para>
Parts of the C++ library may be implemented in terms of C library
functions, which may result in <varname>errno</varname> being set
with no explicit call to a C function. For example, on a target where
<function>operator new</function> uses <function>malloc</function>
a failed memory allocation with <function>operator new</function> might
set <varname>errno</varname> to <constant>ENOMEM</constant>.
Which C++ library functions can set <varname>errno</varname> in this way
is unspecified because it may vary between platforms and between releases.
</para>
</section>
<section xml:id="std.diagnostics.concept_checking" xreflabel="Concept Checking"><info><title>Concept Checking</title></info>
<?dbhtml filename="concept_checking.html"?>
<para>
In 1999, SGI added <quote>concept checkers</quote> to their
implementation of the STL: code which checked the template
parameters of instantiated pieces of the STL, in order to insure
that the parameters being used met the requirements of the
standard. For example, the Standard requires that types passed as
template parameters to <classname>vector</classname> be
"Assignable" (which means what you think it means). The
checking was done during compilation, and none of the code was
executed at runtime.
</para>
<para>
Unfortunately, the size of the compiler files grew significantly
as a result. The checking code itself was cumbersome. And bugs
were found in it on more than one occasion.
</para>
<para>
The primary author of the checking code, Jeremy Siek, had already
started work on a replacement implementation. The new code was
formally reviewed and accepted into
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the
Boost libraries</link>, and we are pleased to incorporate it into the
GNU C++ library.
</para>
<para>
The new version imposes a much smaller space overhead on the generated
object file. The checks are also cleaner and easier to read and
understand.
</para>
<para>
They are off by default for all versions of GCC.
They can be enabled at configure time with
<link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
You can enable them on a per-translation-unit basis with
<literal>-D_GLIBCXX_CONCEPT_CHECKS</literal>.
</para>
<para>
Please note that the checks are based on the requirements in the original
C++ standard, many of which were relaxed in the C++11 standard and so valid
C++11 code may be incorrectly rejected by the concept checks. Additionally,
some correct C++03 code might be rejected by the concept checks,
for example template argument types may need to be complete when used in
a template definition, rather than at the point of instantiation.
There are no plans to address these shortcomings.
</para>
</section>
</chapter>