1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!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 3 includes new implementations of <code class="classname">std::string</code> and 4 <code class="classname">std::list</code>. These changes were necessary to conform 5 to the 2011 C++ standard which forbids Copy-On-Write strings and requires 6 lists to keep track of their size. 7</p><p> In order to maintain backwards compatibility for existing code linked 8 to libstdc++ the library's soname has not changed and the old 9 implementations are still supported in parallel with the new ones. 10 This is achieved by defining the new implementations in an inline namespace 11 so they have different names for linkage purposes, e.g. the new version of 12 <code class="classname">std::list<int></code> is actually defined as 13 <code class="classname">std::__cxx11::list<int></code>. Because the symbols 14 for the new implementations have different names the definitions for both 15 versions can be present in the same library. 16</p><p> The <span class="symbol">_GLIBCXX_USE_CXX11_ABI</span> macro (see 17 <a class="xref" href="using_macros.html" title="Macros">Macros</a>) controls whether 18 the declarations in the library headers use the old or new ABI. 19 So the decision of which ABI to use can be made separately for each 20 source file being compiled. 21 Using the default configuration options for GCC the default value 22 of the macro is <code class="literal">1</code> which causes the new ABI to be active, 23 so to use the old ABI you must explicitly define the macro to 24 <code class="literal">0</code> before including any library headers. 25 (Be aware that some GNU/Linux distributions configure GCC 5 differently so 26 that the default value of the macro is <code class="literal">0</code> and users must 27 define it to <code class="literal">1</code> to enable the new ABI.) 28</p><p> Although the changes were made for C++11 conformance, the choice of ABI 29 to use is independent of the <code class="option">-std</code> option used to compile 30 your code, i.e. for a given GCC build the default value of the 31 <span class="symbol">_GLIBCXX_USE_CXX11_ABI</span> macro is the same for all dialects. 32 This ensures that the <code class="option">-std</code> does not change the ABI, so 33 that it is straightforward to link C++03 and C++11 code together. 34</p><p> Because <code class="classname">std::string</code> is used extensively 35 throughout the library a number of other types are also defined twice, 36 including the stringstream classes and several facets used by 37 <code class="classname">std::locale</code>. The standard facets which are always 38 installed in a locale may be present twice, with both ABIs, to ensure that 39 code like 40 <code class="code">std::use_facet<std::time_get<char>>(locale);</code> 41 will work correctly for both <code class="classname">std::time_get</code> and 42 <code class="classname">std::__cxx11::time_get</code> (even if a user-defined 43 facet that derives from one or other version of 44 <code class="classname">time_get</code> is installed in the locale). 45</p><p> Although the standard exception types defined in 46 <code class="filename"><stdexcept></code> use strings, most 47 are not defined twice, so that a <code class="classname">std::out_of_range</code> 48 exception thrown in one file can always be caught by a suitable handler in 49 another file, even if the two files are compiled with different ABIs. 50</p><p> One exception type does change when using the new ABI, namely 51 <code class="classname">std::ios_base::failure</code>. 52 This is necessary because the 2011 standard changed its base class from 53 <code class="classname">std::exception</code> to 54 <code class="classname">std::system_error</code>, which causes its layout to change. 55 Exceptions due to iostream errors are thrown by a function inside 56 <code class="filename">libstdc++.so</code>, so whether the thrown 57 exception uses the old <code class="classname">std::ios_base::failure</code> type 58 or the new one depends on the ABI that was active when 59 <code class="filename">libstdc++.so</code> was built, 60 <span class="emphasis"><em>not</em></span> the ABI active in the user code that is using 61 iostreams. 62 This means that for a given build of GCC the type thrown is fixed. 63 In current releases the library throws a special type that can be caught 64 by handlers for either the old or new type, 65 but for GCC 7.1, 7.2 and 7.3 the library throws the new 66 <code class="classname">std::ios_base::failure</code> type, 67 and for GCC 5.x and 6.x the library throws the old type. 68 Catch handlers of type <code class="classname">std::ios_base::failure</code> 69 will only catch the exceptions if using a newer release, 70 or if the handler is compiled with the same ABI as the type thrown by 71 the library. 72 Handlers for <code class="classname">std::exception</code> will always catch 73 iostreams exceptions, because the old and new type both inherit from 74 <code class="classname">std::exception</code>. 75</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 76 that involve types in the <code class="code">std::__cxx11</code> namespace or the tag 77 <code class="code">[abi:cxx11]</code> then it probably indicates that you are trying to 78 link together object files that were compiled with different values for the 79 <span class="symbol">_GLIBCXX_USE_CXX11_ABI</span> macro. This commonly happens when 80 linking to a third-party library that was compiled with an older version 81 of GCC. If the third-party library cannot be rebuilt with the new ABI then 82 you will need to recompile your code with the old ABI. 83</p><p> Not all uses of the new ABI will cause changes in symbol names, for 84 example a class with a <code class="classname">std::string</code> member variable 85 will have the same mangled name whether compiled with the old or new ABI. 86 In order to detect such problems the new types and functions are 87 annotated with the <span class="property">abi_tag</span> attribute, allowing the 88 compiler to warn about potential ABI incompatibilities in code using them. 89 Those warnings can be enabled with the <code class="option">-Wabi-tag</code> option. 90</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>