GCC5 and the C++11 ABI

gnu logoThe GNU C++ team works hard to avoid breaking ABI compatibility between releases, including between different -std= modes. But some new complexity requirements in the C++11 standard require ABI changes to several standard library classes to satisfy, most notably to std::basic_string and std::list. And since std::basic_string is used widely, much of the standard library is affected.

Many users routinely rebuild all their code when they change compilers; such users will be unaffected by this change. Code built with an earlier compiler will also continue to work with the new libstdc++, which provides both old and new ABIs.

Users that depend on third-party libraries or plugin interfaces that still use the old ABI can build their code with -D_GLIBCXX_USE_CXX11_ABI=0 and everything should work fine. In most cases, it will be obvious when this flag is needed because of errors from the linker complaining about unresolved symbols involving “__cxx11”.

Providers of such libraries or interfaces need to consider whether they want to provide ABI coexistence, like libstdc++ does, or require their users to rebuild.  If they want to provide coexistence, they need to understand how to handle the change.

The last time G++ went through an ABI change, back in the 3.x period, we changed the soname of libstdc++, which was widely regarded as a mistake. Changing the soname caused a lot of pain but is not sufficient to deal with changes in symbol ABIs: if you load multiple shared objects that depend on different versions of the library, you can still get clashes between different versions of the same symbol.

So the plan for this ABI change has been to leave the soname (and the existing binary interface) alone, and express the new ABI using different mangled names.

C++11 introduced inline namespaces, which are useful for changing the mangled name of a type or declaration without affecting its users. But inline namespaces only deal with ABI changes that are visible in the mangled name; for other ABI changes, such as changes to return type or non-static data members, we need to do something else.

So we’ve introduced the notion of ABI “tags”, to correspond to particular changes in the ABI of a type, function, or variable that would not otherwise be reflected in the mangled name. ABI tags become part of the mangled name, and thereby avoid the problem of two conflicting definitions of the same symbol. Tags are expressed via attribute abi_tag, which can be applied to an inline namespace, or directly to a declaration. So to allow the new ABI to coexist with the old ABI, a library such as libstdc++ needs to ensure that all the declarations with modified ABI are tagged appropriately.

inline namespace abi2 __attribute ((abi_tag)) {
  class MyType { ... };
  MyType fn();

Since C++ allows classes to be declared as incomplete before they are defined, we can’t just automatically propagate tags from, e.g., base to derived class. The derived class needs to be explicitly tagged as well. To help with this, the compiler provides the -Wabi-tag flag, which warns about any declarations which involve a tagged type but don’t have that tag themselves.

// warning: Derived does not have the abi2 tag
struct Derived: MyType { ... };

It is recommended to use inline namespaces for tags when possible, but that obviously won’t work for non-namespace-scope declarations such as member functions.  If there is an ABI change to a member function that is not reflected in the mangled name, then you can apply a tag to it directly.  For instance, the return type of complex::real changed in C++11:

#if __cplusplus >= 201103L
      __attribute ((abi_tag ("cxx11")))
      constexpr _Tp real() const { return _M_real; }
      _Tp& real() { return _M_real; }

The libabigail (https://sourceware.org/libabigail/) tools are also useful for testing whether there are any ABI changes in existing symbols between versions of your library.

Again, only providers of libraries and the like need to think about these complexities, and then only if they want to provide backward compatibility.  Users just need to make sure that they are building with the ABI used by the libraries that they depend on.

Join the Red Hat Developer Program (it’s free) and get access to related cheat sheets, books, and product downloads.


Take advantage of your Red Hat Developers membership and download RHEL today at no cost.


  1. That article is one of the very few sources of information about the new ABI in GCC5. Thank you.

    But you didn’t cover the case when I want to ship a binary application built with GCC5 and the new ABI. Those binaries probably won’t run on older distributions like RHEL6 because libstdc++ has an old version.

    Is there any way to use the new features of libstdc++ in that case or will I be stuck with the old ABI until I drop support for distributions which don’t ship libstdc++ with the new ABI? Is static linking possible?

    1. For RHEL there is the Red Hat Developer Toolset which allows newer compilers to build programs using compilers newer than the system compiler, which works by statically linking the parts of libstdc++ that are not present in the system library. If you want to use upstream GCC 5 before DTS 4 is available, you can indeed statically link all of libstdc++. Or you can use the old ABI in your application.

  2. I understand the need for applying abi tags to declarations, but not to namespaces. Indeed some simple experiments seem to indicate that doing so has no effect. Any chance you could explain what effect applying an abi tag to a namspace actually has? Also, you can use ‘__attribute((abi_tag))’ for a namespace, but you must apply an abi tag for a declaration eg ‘__attribute((abi_tag(“cxx11”) ))’. Why is that? What happens when I don’t supply an abi tag? Thanks 🙂

    1. The idea is that people will use ABI tags on inline namespaces to indicate that everything within them has that ABI tag. There is no need to reflect this ABI tag in the mangled name because the name of the inline namespace is already part of the mangled name. But the ABI tag does affect -Wabi-tag for classes within the namespace, as with the MyType example above.

      Using just ‘__attribute((abi_tag))’ on a namespace uses the namespace name as the name of the tag; you can explicitly specify the tag name if you want it to be different. For example, in libstdc++ the namespace is “__cxx11” and the tag is “cxx11” so we need to provide an explicit tag name.

      1. Ok, got it. Anything declared inside the namespace is considered to be part of the specified ABI, just as if it was declared with the abi tag explicitly, except that it need not and will not be tagged as such in its mangled name. Correct?

        But, actually libstdc++ does use the naked abi_tag once (in 5.2.0/i686-pc-linux-gnu/bits/c++config.h). Is that an error?

Leave a Reply