Skip to content

R
riscv-gcc-1
Commit 0f8a1c15 by Jonathan Wakely
Options

Document Dual ABI for std::ios_base::failure 

	* doc/xml/faq.xml: Link to C++17 status. Add note to outdated answer.
	* doc/xml/manual/debug_mode.xml: Add array and forward_list to list
	of C++11 containers with Debug Mode support.
	* doc/xml/manual/using.xml: Document Dual ABI for ios_base::failure.
	* doc/html/*: Regenerate.

From-SVN: r260129
parent a6e1cfdd
Showing with 98 additions and 18 deletions
libstdc++-v3/ChangeLog
2018-05-10 Jonathan Wakely <jwakely@redhat.com>
* doc/xml/faq.xml: Link to C++17 status. Add note to outdated answer.
* doc/xml/manual/debug_mode.xml: Add array and forward_list to list
of C++11 containers with Debug Mode support.
* doc/xml/manual/using.xml: Document Dual ABI for ios_base::failure.
* doc/html/*: Regenerate.
2018-05-10 Jason Merrill <jason@redhat.com>
* include/bits/regex_compiler.h (_S_cache_size): Change from
......
libstdc++-v3/doc/html/faq.html
......@@ -538,14 +538,15 @@
except for some corner cases. Support for localization
in <code class="classname">locale</code> may be incomplete on some non-GNU
platforms. Also dependent on the underlying platform is support
for <span class="type">wchar_t</span> and <span class="type">long
long</span> specializations, and details of thread support.
for <span class="type">wchar_t</span> and <span class="type">long long</span> specializations,
and details of thread support.
</p><p>
Long answer: See the implementation status pages for
<a class="link" href="manual/status.html#status.iso.1998" title="C++ 1998/2003">C++98</a>,
<a class="link" href="manual/status.html#status.iso.tr1" title="C++ TR1">TR1</a>, and
<a class="link" href="manual/status.html#status.iso.2011" title="C++ 2011">C++11</a>.
<a class="link" href="manual/status.html#status.iso.2014" title="C++ 2014">C++14</a>.
<a class="link" href="manual/status.html#status.iso.tr1" title="C++ TR1">TR1</a>,
<a class="link" href="manual/status.html#status.iso.2011" title="C++ 2011">C++11</a>,
<a class="link" href="manual/status.html#status.iso.2014" title="C++ 2014">C++14</a>, and
<a class="link" href="manual/status.html#status.iso.2017" title="C++ 2017">C++17</a>.
</p></td></tr><tr class="question"><td align="left" valign="top"><a id="faq.standard_bugs"></a><a id="q-standard_bugs"></a><p><strong>5.2.</strong></p></td><td align="left" valign="top"><p>
Bugs in the ISO C++ language or library specification
</p></td></tr><tr class="answer"><td align="left" valign="top"><a id="a-standard_bugs"></a></td><td align="left" valign="top"><p>
......@@ -642,7 +643,7 @@
without other drawbacks, send us a patch.
</p></td></tr><tr class="question"><td align="left" valign="top"><a id="faq.ambiguous_overloads"></a><a id="q-ambiguous_overloads"></a><p><strong>6.3.</strong></p></td><td align="left" valign="top"><p>
Ambiguous overloads after including an old-style header
</p></td></tr><tr class="answer"><td align="left" valign="top"><a id="a-ambiguous_overloads"></a></td><td align="left" valign="top"><p>
</p></td></tr><tr class="answer"><td align="left" valign="top"><a id="a-ambiguous_overloads"></a></td><td align="left" valign="top"><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This answer is old and probably no longer be relevant.</p></div><p>
Another problem is the <code class="literal">rel_ops</code> namespace and the template
comparison operator functions contained therein. If they become
visible in the same namespace as other comparison functions
......
libstdc++-v3/doc/html/manual/debug_mode_using.html
......@@ -20,4 +20,4 @@
containers:
</p><div class="table"><a id="table.debug_mode_containers"></a><p class="title"><strong>Table 17.1. Debugging Containers</strong></p><div class="table-contents"><table class="table" summary="Debugging Containers" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Container</th><th align="left">Header</th><th align="left">Debug container</th><th align="left">Debug header</th></tr></thead><tbody><tr><td align="left"><code class="classname">std::bitset</code></td><td align="left"><code class="filename">bitset</code></td><td align="left"><code class="classname">__gnu_debug::bitset</code></td><td align="left"><code class="filename">&lt;debug/bitset&gt;</code></td></tr><tr><td align="left"><code class="classname">std::deque</code></td><td align="left"><code class="filename">deque</code></td><td align="left"><code class="classname">__gnu_debug::deque</code></td><td align="left"><code class="filename">&lt;debug/deque&gt;</code></td></tr><tr><td align="left"><code class="classname">std::list</code></td><td align="left"><code class="filename">list</code></td><td align="left"><code class="classname">__gnu_debug::list</code></td><td align="left"><code class="filename">&lt;debug/list&gt;</code></td></tr><tr><td align="left"><code class="classname">std::map</code></td><td align="left"><code class="filename">map</code></td><td align="left"><code class="classname">__gnu_debug::map</code></td><td align="left"><code class="filename">&lt;debug/map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::multimap</code></td><td align="left"><code class="filename">map</code></td><td align="left"><code class="classname">__gnu_debug::multimap</code></td><td align="left"><code class="filename">&lt;debug/map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::multiset</code></td><td align="left"><code class="filename">set</code></td><td align="left"><code class="classname">__gnu_debug::multiset</code></td><td align="left"><code class="filename">&lt;debug/set&gt;</code></td></tr><tr><td align="left"><code class="classname">std::set</code></td><td align="left"><code class="filename">set</code></td><td align="left"><code class="classname">__gnu_debug::set</code></td><td align="left"><code class="filename">&lt;debug/set&gt;</code></td></tr><tr><td align="left"><code class="classname">std::string</code></td><td align="left"><code class="filename">string</code></td><td align="left"><code class="classname">__gnu_debug::string</code></td><td align="left"><code class="filename">&lt;debug/string&gt;</code></td></tr><tr><td align="left"><code class="classname">std::wstring</code></td><td align="left"><code class="filename">string</code></td><td align="left"><code class="classname">__gnu_debug::wstring</code></td><td align="left"><code class="filename">&lt;debug/string&gt;</code></td></tr><tr><td align="left"><code class="classname">std::basic_string</code></td><td align="left"><code class="filename">string</code></td><td align="left"><code class="classname">__gnu_debug::basic_string</code></td><td align="left"><code class="filename">&lt;debug/string&gt;</code></td></tr><tr><td align="left"><code class="classname">std::vector</code></td><td align="left"><code class="filename">vector</code></td><td align="left"><code class="classname">__gnu_debug::vector</code></td><td align="left"><code class="filename">&lt;debug/vector&gt;</code></td></tr></tbody></table></div></div><br class="table-break" /><p>In addition, when compiling in C++11 mode, these additional
containers have additional debug capability.
</p><div class="table"><a id="table.debug_mode_containers_cxx11"></a><p class="title"><strong>Table 17.2. Debugging Containers C++11</strong></p><div class="table-contents"><table class="table" summary="Debugging Containers C++11" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Container</th><th align="left">Header</th><th align="left">Debug container</th><th align="left">Debug header</th></tr></thead><tbody><tr><td align="left"><code class="classname">std::unordered_map</code></td><td align="left"><code class="filename">unordered_map</code></td><td align="left"><code class="classname">__gnu_debug::unordered_map</code></td><td align="left"><code class="filename">&lt;debug/unordered_map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_multimap</code></td><td align="left"><code class="filename">unordered_map</code></td><td align="left"><code class="classname">__gnu_debug::unordered_multimap</code></td><td align="left"><code class="filename">&lt;debug/unordered_map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_set</code></td><td align="left"><code class="filename">unordered_set</code></td><td align="left"><code class="classname">__gnu_debug::unordered_set</code></td><td align="left"><code class="filename">&lt;debug/unordered_set&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_multiset</code></td><td align="left"><code class="filename">unordered_set</code></td><td align="left"><code class="classname">__gnu_debug::unordered_multiset</code></td><td align="left"><code class="filename">&lt;debug/unordered_set&gt;</code></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="debug_mode_semantics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="debug_mode_design.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Semantics </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Design</td></tr></table></div></body></html>
\ No newline at end of file
</p><div class="table"><a id="table.debug_mode_containers_cxx11"></a><p class="title"><strong>Table 17.2. Debugging Containers C++11</strong></p><div class="table-contents"><table class="table" summary="Debugging Containers C++11" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Container</th><th align="left">Header</th><th align="left">Debug container</th><th align="left">Debug header</th></tr></thead><tbody><tr><td align="left"><code class="classname">std::array</code></td><td align="left"><code class="filename">array</code></td><td align="left"><code class="classname">__gnu_debug::array</code></td><td align="left"><code class="filename">&lt;debug/array&gt;</code></td></tr><tr><td align="left"><code class="classname">std::forward_list</code></td><td align="left"><code class="filename">forward_list</code></td><td align="left"><code class="classname">__gnu_debug::forward_list</code></td><td align="left"><code class="filename">&lt;debug/forward_list&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_map</code></td><td align="left"><code class="filename">unordered_map</code></td><td align="left"><code class="classname">__gnu_debug::unordered_map</code></td><td align="left"><code class="filename">&lt;debug/unordered_map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_multimap</code></td><td align="left"><code class="filename">unordered_map</code></td><td align="left"><code class="classname">__gnu_debug::unordered_multimap</code></td><td align="left"><code class="filename">&lt;debug/unordered_map&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_set</code></td><td align="left"><code class="filename">unordered_set</code></td><td align="left"><code class="classname">__gnu_debug::unordered_set</code></td><td align="left"><code class="filename">&lt;debug/unordered_set&gt;</code></td></tr><tr><td align="left"><code class="classname">std::unordered_multiset</code></td><td align="left"><code class="filename">unordered_set</code></td><td align="left"><code class="classname">__gnu_debug::unordered_multiset</code></td><td align="left"><code class="filename">&lt;debug/unordered_set&gt;</code></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="debug_mode_semantics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="debug_mode_design.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Semantics </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Design</td></tr></table></div></body></html>
\ No newline at end of file
libstdc++-v3/doc/html/manual/using.html
......@@ -25,5 +25,7 @@
<code class="filename">&lt;atomic&gt;</code>.
</td></tr><tr><td align="left"><code class="literal">-lstdc++fs</code></td><td align="left">Linking to <code class="filename">libstdc++fs</code>
is required for use of the Filesystem library extensions in
<code class="filename">&lt;experimental/filesystem&gt;</code>.
<code class="filename">&lt;experimental/filesystem&gt;</code>
and the C++17 Filesystem library in
<code class="filename">&lt;filesystem&gt;</code>.
</td></tr><tr><td align="left"><code class="literal">-fopenmp</code></td><td align="left">For <a class="link" href="parallel_mode.html" title="Chapter 18. Parallel Mode">parallel</a> mode.</td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="make.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="intro.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_headers.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Make </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Headers</td></tr></table></div></body></html>
\ No newline at end of file
libstdc++-v3/doc/html/manual/using_dual_abi.html
......@@ -14,7 +14,7 @@
for the new implementations have different names the definitions for both
versions can be present in the same library.
</p><p> The <span class="symbol">_GLIBCXX_USE_CXX11_ABI</span> macro (see
<a class="xref" href="using_macros.html" title="Macros">Macros</a>) controls whether
<a class="xref" href="using_macros.html" title="Macros">Macros</a>) controls whether
the declarations in the library headers use the old or new ABI.
So the decision of which ABI to use can be made separately for each
source file being compiled.
......@@ -43,10 +43,35 @@
facet that derives from one or other version of
<code class="classname">time_get</code> is installed in the locale).
</p><p> Although the standard exception types defined in
<code class="filename">&lt;stdexcept&gt;</code> use strings, they
<code class="filename">&lt;stdexcept&gt;</code> use strings, most
are not defined twice, so that a <code class="classname">std::out_of_range</code>
exception thrown in one file can always be caught by a suitable handler in
another file, even if the two files are compiled with different ABIs.
</p><p> One exception type does change when using the new ABI, namely
<code class="classname">std::ios_base::failure</code>.
This is necessary because the 2011 standard changed its base class from
<code class="classname">std::exception</code> to
<code class="classname">std::system_error</code>, which causes its layout to change.
Exceptions due to iostream errors are thrown by a function inside
<code class="filename">libstdc++.so</code>, so whether the thrown
exception uses the old <code class="classname">std::ios_base::failure</code> type
or the new one depends on the ABI that was active when
<code class="filename">libstdc++.so</code> was built,
<span class="emphasis"><em>not</em></span> the ABI active in the user code that is using
iostreams.
This means that for a given build of GCC the type thrown is fixed.
In current releases the library throws a special type that can be caught
by handlers for either the old or new type,
but for GCC 7.1, 7.2 and 7.3 the library throws the new
<code class="classname">std::ios_base::failure</code> type,
and for GCC 5.x and 6.x the library throws the old type.
Catch handlers of type <code class="classname">std::ios_base::failure</code>
will only catch the exceptions if using a newer release,
or if the handler is compiled with the same ABI as the type thrown by
the library.
Handlers for <code class="classname">std::exception</code> will always catch
iostreams exceptions, because the old and new type both inherit from
<code class="classname">std::exception</code>.
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.abi.trouble"></a>Troubleshooting</h3></div></div></div><p> If you get linker errors about undefined references to symbols
that involve types in the <code class="code">std::__cxx11</code> namespace or the tag
<code class="code">[abi:cxx11]</code> then it probably indicates that you are trying to
......
libstdc++-v3/doc/xml/faq.xml
......@@ -742,15 +742,16 @@
except for some corner cases. Support for localization
in <classname>locale</classname> may be incomplete on some non-GNU
platforms. Also dependent on the underlying platform is support
for <type>wchar_t</type> and <type>long
long</type> specializations, and details of thread support.
for <type>wchar_t</type> and <type>long long</type> specializations,
and details of thread support.
</para>
<para>
Long answer: See the implementation status pages for
<link linkend="status.iso.1998">C++98</link>,
<link linkend="status.iso.tr1">TR1</link>, and
<link linkend="status.iso.2011">C++11</link>.
<link linkend="status.iso.2014">C++14</link>.
<link linkend="status.iso.tr1">TR1</link>,
<link linkend="status.iso.2011">C++11</link>,
<link linkend="status.iso.2014">C++14</link>, and
<link linkend="status.iso.2017">C++17</link>.
</para>
</answer>
</qandaentry>
......@@ -891,6 +892,9 @@
</para>
</question>
<answer xml:id="a-ambiguous_overloads">
<note>
<para>This answer is old and probably no longer be relevant.</para>
</note>
<para>
Another problem is the <literal>rel_ops</literal> namespace and the template
comparison operator functions contained therein. If they become
......
libstdc++-v3/doc/xml/manual/debug_mode.xml
......@@ -286,6 +286,18 @@ containers have additional debug capability.
</thead>
<tbody>
<row>
<entry><classname>std::array</classname></entry>
<entry><filename class="headerfile">array</filename></entry>
<entry><classname>__gnu_debug::array</classname></entry>
<entry><filename class="headerfile">&lt;debug/array&gt;</filename></entry>
</row>
<row>
<entry><classname>std::forward_list</classname></entry>
<entry><filename class="headerfile">forward_list</filename></entry>
<entry><classname>__gnu_debug::forward_list</classname></entry>
<entry><filename class="headerfile">&lt;debug/forward_list&gt;</filename></entry>
</row>
<row>
<entry><classname>std::unordered_map</classname></entry>
<entry><filename class="headerfile">unordered_map</filename></entry>
<entry><classname>__gnu_debug::unordered_map</classname></entry>
......
libstdc++-v3/doc/xml/manual/using.xml
......@@ -1036,7 +1036,7 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
</para>
<para> The <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro (see
<xref linkend="manual.intro.using.macros"/>) controls whether
<xref linkend="manual.intro.using.macros"/>) controls whether
the declarations in the library headers use the old or new ABI.
So the decision of which ABI to use can be made separately for each
source file being compiled.
......@@ -1071,12 +1071,39 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
</para>
<para> Although the standard exception types defined in
<filename class="headerfile">&lt;stdexcept&gt;</filename> use strings, they
<filename class="headerfile">&lt;stdexcept&gt;</filename> use strings, most
are not defined twice, so that a <classname>std::out_of_range</classname>
exception thrown in one file can always be caught by a suitable handler in
another file, even if the two files are compiled with different ABIs.
</para>
<para> One exception type does change when using the new ABI, namely
<classname>std::ios_base::failure</classname>.
This is necessary because the 2011 standard changed its base class from
<classname>std::exception</classname> to
<classname>std::system_error</classname>, which causes its layout to change.
Exceptions due to iostream errors are thrown by a function inside
<filename class="libraryfile">libstdc++.so</filename>, so whether the thrown
exception uses the old <classname>std::ios_base::failure</classname> type
or the new one depends on the ABI that was active when
<filename class="libraryfile">libstdc++.so</filename> was built,
<emphasis>not</emphasis> the ABI active in the user code that is using
iostreams.
This means that for a given build of GCC the type thrown is fixed.
In current releases the library throws a special type that can be caught
by handlers for either the old or new type,
but for GCC 7.1, 7.2 and 7.3 the library throws the new
<classname>std::ios_base::failure</classname> type,
and for GCC 5.x and 6.x the library throws the old type.
Catch handlers of type <classname>std::ios_base::failure</classname>
will only catch the exceptions if using a newer release,
or if the handler is compiled with the same ABI as the type thrown by
the library.
Handlers for <classname>std::exception</classname> will always catch
iostreams exceptions, because the old and new type both inherit from
<classname>std::exception</classname>.
</para>
<section xml:id="manual.intro.using.abi.trouble" xreflabel="Dual ABI Troubleshooting"><info><title>Troubleshooting</title></info>
<para> If you get linker errors about undefined references to symbols
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment