Document Dual ABI for std::ios_base::failure

Message ID 20180510111752.GA15121@redhat.com
State New
Headers show
Series
  • Document Dual ABI for std::ios_base::failure
Related show

Commit Message

Jonathan Wakely May 10, 2018, 11:17 a.m.
And a couple of other doc improvements, and regenerated the HTML
pages.

Please read the proposed change to using.xml and let me know if it's
clear.

	* 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.
commit ef4d4c52eb0073627270d7b13a5bc2a89f6cef0d
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Thu May 10 12:07:08 2018 +0100

    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.

Comments

Jonathan Wakely May 10, 2018, 7:12 p.m. | #1
On 10/05/18 12:17 +0100, Jonathan Wakely wrote:
>And a couple of other doc improvements, and regenerated the HTML
>pages.
>
>Please read the proposed change to using.xml and let me know if it's
>clear.
>
>	* 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.

Committed to trunk.

Patch

diff --git a/libstdc++-v3/doc/xml/faq.xml b/libstdc++-v3/doc/xml/faq.xml
index b0b1f98e641..edc07f16acb 100644
--- a/libstdc++-v3/doc/xml/faq.xml
+++ b/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
diff --git a/libstdc++-v3/doc/xml/manual/debug_mode.xml b/libstdc++-v3/doc/xml/manual/debug_mode.xml
index 5082bbfb724..570c17ba28a 100644
--- a/libstdc++-v3/doc/xml/manual/debug_mode.xml
+++ b/libstdc++-v3/doc/xml/manual/debug_mode.xml
@@ -285,7 +285,19 @@  containers have additional debug capability.
   </row>
 </thead>
 <tbody>
-    <row>
+  <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>
diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml
index 918703a5217..67f9cf5216b 100644
--- a/libstdc++-v3/doc/xml/manual/using.xml
+++ b/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