| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Dual ABI</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_macros.html" title="Macros" /><link rel="next" href="using_namespaces.html" title="Namespaces" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Dual ABI</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_macros.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_namespaces.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.abi"></a>Dual ABI</h2></div></div></div><p> In the GCC 5.1 release libstdc++ introduced a new library ABI that |
| includes new implementations of <code class="classname">std::string</code> and |
| <code class="classname">std::list</code>. These changes were necessary to conform |
| to the 2011 C++ standard which forbids Copy-On-Write strings and requires |
| lists to keep track of their size. |
| </p><p> In order to maintain backwards compatibility for existing code linked |
| to libstdc++ the library's soname has not changed and the old |
| implementations are still supported in parallel with the new ones. |
| This is achieved by defining the new implementations in an inline namespace |
| so they have different names for linkage purposes, e.g. the new version of |
| <code class="classname">std::list<int></code> is actually defined as |
| <code class="classname">std::__cxx11::list<int></code>. Because the symbols |
| 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 |
| 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. |
| Using the default configuration options for GCC the default value |
| of the macro is <code class="literal">1</code> which causes the new ABI to be active, |
| so to use the old ABI you must explicitly define the macro to |
| <code class="literal">0</code> before including any library headers. |
| (Be aware that some GNU/Linux distributions configure GCC 5 differently so |
| that the default value of the macro is <code class="literal">0</code> and users must |
| define it to <code class="literal">1</code> to enable the new ABI.) |
| </p><p> Although the changes were made for C++11 conformance, the choice of ABI |
| to use is independent of the <code class="option">-std</code> option used to compile |
| your code, i.e. for a given GCC build the default value of the |
| <span class="symbol">_GLIBCXX_USE_CXX11_ABI</span> macro is the same for all dialects. |
| This ensures that the <code class="option">-std</code> does not change the ABI, so |
| that it is straightforward to link C++03 and C++11 code together. |
| </p><p> Because <code class="classname">std::string</code> is used extensively |
| throughout the library a number of other types are also defined twice, |
| including the stringstream classes and several facets used by |
| <code class="classname">std::locale</code>. The standard facets which are always |
| installed in a locale may be present twice, with both ABIs, to ensure that |
| code like |
| <code class="code">std::use_facet<std::time_get<char>>(locale);</code> |
| will work correctly for both <code class="classname">std::time_get</code> and |
| <code class="classname">std::__cxx11::time_get</code> (even if a user-defined |
| 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"><stdexcept></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 |
| link together object files that were compiled with different values for the |
| <span class="symbol">_GLIBCXX_USE_CXX11_ABI</span> macro. This commonly happens when |
| linking to a third-party library that was compiled with an older version |
| of GCC. If the third-party library cannot be rebuilt with the new ABI then |
| you will need to recompile your code with the old ABI. |
| </p><p> Not all uses of the new ABI will cause changes in symbol names, for |
| example a class with a <code class="classname">std::string</code> member variable |
| will have the same mangled name whether compiled with the old or new ABI. |
| In order to detect such problems the new types and functions are |
| annotated with the <span class="property">abi_tag</span> attribute, allowing the |
| compiler to warn about potential ABI incompatibilities in code using them. |
| Those warnings can be enabled with the <code class="option">-Wabi-tag</code> option. |
| </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_macros.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_namespaces.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Macros </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Namespaces</td></tr></table></div></body></html> |
