C++ ABI version dynamic shared compatibility

C++ applications often depend on specific language support routines, say for throwing exceptions, or catching exceptions, and perhaps also depend on features in the C++ Standard Library. The C++ Standard Library has many include files, types defined in those include files, specific named functions, and other behavior. The text of these behaviors, as written in source include files, is called the Application Programing Interface, or API. Furthermore, C++ source that is compiled into object files is transformed by the compiler: it arranges objects with specific alignment and in a particular layout, mangling names according to a well-defined algorithm, has specific arrangements for the support of virtual functions, etc. These details are defined as the compiler Application Binary Interface, or ABI. From GCC version 3 onwards the GNU C++ compiler uses an industry-standard C++ ABI, the Itanium C++ ABI. The GNU C++ compiler, g++, has a compiler command line option to switch between various different C++ ABIs. This explicit version switch is the flag -fabi-version. In addition, some g++ command line options may change the ABI as a side-effect of use. Such flags include -fpack-struct and -fno-exceptions, but include others: see the complete list in the GCC manual under the heading Options for Code Generation Conventions. The configure options used when building a specific libstdc++ version may also impact the resulting library ABI. The available configure options, and their impact on the library ABI, are documented here. Putting all of these ideas together results in the C++ Standard Library ABI, which is the compilation of a given library API by a given compiler ABI. In a nutshell: library API + compiler ABI = library ABI The library ABI is mostly of interest for end-users who have unresolved symbols and are linking dynamically to the C++ Standard library, and who thus must be careful to compile their application with a compiler that is compatible with the available C++ Standard library binary. In this case, compatible is defined with the equation above: given an application compiled with a given compiler ABI and library API, it will work correctly with a Standard C++ Library created with the same constraints. To use a specific version of the C++ ABI, one must use a corresponding GNU C++ toolchain (i.e., g++ and libstdc++) that implements the C++ ABI in question.

The C++ interface has evolved throughout the history of the GNU C++ toolchain. With each release, various details have been changed so as to give distinct versions to the C++ interface.

Extending existing, stable ABIs. Versioning gives subsequent releases of library binaries the ability to add new symbols and add functionality, all the while retaining compatibility with the previous releases in the series. Thus, program binaries linked with the initial release of a library binary will still run correctly if the library binary is replaced by carefully-managed subsequent library binaries. This is called forward compatibility. The reverse (backwards compatibility) is not true. It is not possible to take program binaries linked with the latest version of a library binary in a release series (with additional symbols added), substitute in the initial release of the library binary, and remain link compatible. Allows multiple, incompatible ABIs to coexist at the same time.

How can this complexity be managed? What does C++ versioning mean? Because library and compiler changes often make binaries compiled with one version of the GNU tools incompatible with binaries compiled with other (either newer or older) versions of the same GNU tools, specific techniques are used to make managing this complexity easier. The following techniques are used: Release versioning on the libgcc_s.so binary. This is implemented via file names and the ELF DT_SONAME mechanism (at least on ELF systems). It is versioned as follows: GCC 3.x: libgcc_s.so.1 GCC 4.x: libgcc_s.so.1 For m68k-linux the versions differ as follows: GCC 3.4, GCC 4.x: libgcc_s.so.1 when configuring --with-sjlj-exceptions, or libgcc_s.so.2 For hppa-linux the versions differ as follows: GCC 3.4, GCC 4.[0-1]: either libgcc_s.so.1 when configuring --with-sjlj-exceptions, or libgcc_s.so.2 GCC 4.[2-7]: either libgcc_s.so.3 when configuring --with-sjlj-exceptions) or libgcc_s.so.4 Symbol versioning on the libgcc_s.so binary. It is versioned with the following labels and version definitions, where the version definition is the maximum for a particular release. Labels are cumulative. If a particular release is not listed, it has the same version labels as the preceding release. This corresponds to the mapfile: gcc/libgcc-std.ver GCC 3.0.0: GCC_3.0 GCC 3.3.0: GCC_3.3 GCC 3.3.1: GCC_3.3.1 GCC 3.3.2: GCC_3.3.2 GCC 3.3.4: GCC_3.3.4 GCC 3.4.0: GCC_3.4 GCC 3.4.2: GCC_3.4.2 GCC 3.4.4: GCC_3.4.4 GCC 4.0.0: GCC_4.0.0 GCC 4.1.0: GCC_4.1.0 GCC 4.2.0: GCC_4.2.0 GCC 4.3.0: GCC_4.3.0 GCC 4.4.0: GCC_4.4.0 GCC 4.5.0: GCC_4.5.0 GCC 4.6.0: GCC_4.6.0 GCC 4.7.0: GCC_4.7.0 GCC 4.8.0: GCC_4.8.0 GCC 7.1.0: GCC_7.0.0 GCC 9.1.0: GCC_9.0.0 GCC 11.1.0: GCC_11.0 GCC 12.1.0: GCC_12.0.0 GCC 13.1.0: GCC_13.0.0 Release versioning on the libstdc++.so binary, implemented in the same way as the libgcc_s.so binary above. Listed is the filename: DT_SONAME can be deduced from the filename by removing the last two period-delimited numbers. For example, filename libstdc++.so.5.0.4 corresponds to a DT_SONAME of libstdc++.so.5. Binaries with equivalent DT_SONAMEs are forward-compatibile: in the table below, releases incompatible with the previous one are explicitly noted. If a particular release is not listed, its libstdc++.so binary has the same filename and DT_SONAME as the preceding release. It is versioned as follows: GCC 3.0.0: libstdc++.so.3.0.0 GCC 3.0.1: libstdc++.so.3.0.1 GCC 3.0.2: libstdc++.so.3.0.2 GCC 3.0.3: libstdc++.so.3.0.2 (See Note 1) GCC 3.0.4: libstdc++.so.3.0.4 GCC 3.1.0: libstdc++.so.4.0.0 (Incompatible with previous) GCC 3.1.1: libstdc++.so.4.0.1 GCC 3.2.0: libstdc++.so.5.0.0 (Incompatible with previous) GCC 3.2.1: libstdc++.so.5.0.1 GCC 3.2.2: libstdc++.so.5.0.2 GCC 3.2.3: libstdc++.so.5.0.3 (See Note 2) GCC 3.3.0: libstdc++.so.5.0.4 GCC 3.3.1: libstdc++.so.5.0.5 GCC 3.4.0: libstdc++.so.6.0.0 (Incompatible with previous) GCC 3.4.1: libstdc++.so.6.0.1 GCC 3.4.2: libstdc++.so.6.0.2 GCC 3.4.3: libstdc++.so.6.0.3 GCC 4.0.0: libstdc++.so.6.0.4 GCC 4.0.1: libstdc++.so.6.0.5 GCC 4.0.2: libstdc++.so.6.0.6 GCC 4.0.3: libstdc++.so.6.0.7 GCC 4.1.0: libstdc++.so.6.0.7 GCC 4.1.1: libstdc++.so.6.0.8 GCC 4.2.0: libstdc++.so.6.0.9 GCC 4.2.1: libstdc++.so.6.0.9 (See Note 3) GCC 4.2.2: libstdc++.so.6.0.9 GCC 4.3.0: libstdc++.so.6.0.10 GCC 4.4.0: libstdc++.so.6.0.11 GCC 4.4.1: libstdc++.so.6.0.12 GCC 4.4.2: libstdc++.so.6.0.13 GCC 4.5.0: libstdc++.so.6.0.14 GCC 4.6.0: libstdc++.so.6.0.15 GCC 4.6.1: libstdc++.so.6.0.16 GCC 4.7.0: libstdc++.so.6.0.17 GCC 4.8.0: libstdc++.so.6.0.18 GCC 4.8.3: libstdc++.so.6.0.19 GCC 4.9.0: libstdc++.so.6.0.20 GCC 5.1.0: libstdc++.so.6.0.21 GCC 6.1.0: libstdc++.so.6.0.22 GCC 7.1.0: libstdc++.so.6.0.23 GCC 7.2.0: libstdc++.so.6.0.24 GCC 8.1.0: libstdc++.so.6.0.25 GCC 9.1.0: libstdc++.so.6.0.26 GCC 9.2.0: libstdc++.so.6.0.27 GCC 9.3.0: libstdc++.so.6.0.28 GCC 10.1.0: libstdc++.so.6.0.28 GCC 11.1.0: libstdc++.so.6.0.29 GCC 12.1.0: libstdc++.so.6.0.30 GCC 13.1.0: libstdc++.so.6.0.31 GCC 13.2.0: libstdc++.so.6.0.32 GCC 14.1.0: libstdc++.so.6.0.33 Note 1: Error should be libstdc++.so.3.0.3. Note 2: Not strictly required. Note 3: This release (but not previous or subsequent) has one known incompatibility, see 33678 in the GCC bug database. Symbol versioning on the libstdc++.so binary. mapfile: libstdc++-v3/config/abi/pre/gnu.ver It is versioned with the following labels and version definitions, where the version definition is the maximum for a particular release. Note, only symbols which are newly introduced will use the maximum version definition. Thus, for release series with the same label, but incremented version definitions, the later release has both versions. (An example of this would be the GCC 3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and GLIBCPP_3.2 for symbols that were introduced in the GCC 3.2.0 release.) If a particular release is not listed, it has the same version labels as the preceding release. GCC 3.0.0: (Error, not versioned) GCC 3.0.1: (Error, not versioned) GCC 3.0.2: (Error, not versioned) GCC 3.0.3: (Error, not versioned) GCC 3.0.4: (Error, not versioned) GCC 3.1.0: GLIBCPP_3.1, CXXABI_1 GCC 3.1.1: GLIBCPP_3.1, CXXABI_1 GCC 3.2.0: GLIBCPP_3.2, CXXABI_1.2 GCC 3.2.1: GLIBCPP_3.2.1, CXXABI_1.2 GCC 3.2.2: GLIBCPP_3.2.2, CXXABI_1.2 GCC 3.2.3: GLIBCPP_3.2.2, CXXABI_1.2 GCC 3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1 GCC 3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1 GCC 3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1 GCC 3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1 GCC 3.4.0: GLIBCXX_3.4, CXXABI_1.3 GCC 3.4.1: GLIBCXX_3.4.1, CXXABI_1.3 GCC 3.4.2: GLIBCXX_3.4.2 GCC 3.4.3: GLIBCXX_3.4.3 GCC 4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1 GCC 4.0.1: GLIBCXX_3.4.5 GCC 4.0.2: GLIBCXX_3.4.6 GCC 4.0.3: GLIBCXX_3.4.7 GCC 4.1.1: GLIBCXX_3.4.8 GCC 4.2.0: GLIBCXX_3.4.9 GCC 4.3.0: GLIBCXX_3.4.10, CXXABI_1.3.2 GCC 4.4.0: GLIBCXX_3.4.11, CXXABI_1.3.3 GCC 4.4.1: GLIBCXX_3.4.12, CXXABI_1.3.3 GCC 4.4.2: GLIBCXX_3.4.13, CXXABI_1.3.3 GCC 4.5.0: GLIBCXX_3.4.14, CXXABI_1.3.4 GCC 4.6.0: GLIBCXX_3.4.15, CXXABI_1.3.5 GCC 4.6.1: GLIBCXX_3.4.16, CXXABI_1.3.5 GCC 4.7.0: GLIBCXX_3.4.17, CXXABI_1.3.6 GCC 4.8.0: GLIBCXX_3.4.18, CXXABI_1.3.7 GCC 4.8.3: GLIBCXX_3.4.19, CXXABI_1.3.7 GCC 4.9.0: GLIBCXX_3.4.20, CXXABI_1.3.8 GCC 5.1.0: GLIBCXX_3.4.21, CXXABI_1.3.9 GCC 6.1.0: GLIBCXX_3.4.22, CXXABI_1.3.10 GCC 7.1.0: GLIBCXX_3.4.23, CXXABI_1.3.11 GCC 7.2.0: GLIBCXX_3.4.24, CXXABI_1.3.11 GCC 8.1.0: GLIBCXX_3.4.25, CXXABI_1.3.11 GCC 9.1.0: GLIBCXX_3.4.26, CXXABI_1.3.12 GCC 9.2.0: GLIBCXX_3.4.27, CXXABI_1.3.12 GCC 9.3.0: GLIBCXX_3.4.28, CXXABI_1.3.12 GCC 10.1.0: GLIBCXX_3.4.28, CXXABI_1.3.12 GCC 11.1.0: GLIBCXX_3.4.29, CXXABI_1.3.13 GCC 12.1.0: GLIBCXX_3.4.30, CXXABI_1.3.13 GCC 13.1.0: GLIBCXX_3.4.31, CXXABI_1.3.14 GCC 13.2.0: GLIBCXX_3.4.32, CXXABI_1.3.14 GCC 14.1.0: GLIBCXX_3.4.33, CXXABI_1.3.15 Incremental bumping of a compiler pre-defined macro, __GXX_ABI_VERSION. This macro is defined as the version of the compiler v3 ABI, with g++ 3.0 being version 100. This macro will be automatically defined whenever g++ is used (the curious can test this by invoking g++ with the '-v' flag.) This macro was defined in the file "lang-specs.h" in the gcc/cp directory. Later versions defined it in "c-common.c" in the gcc directory, and from G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the '-fabi-version' command line option. It is versioned as follows, where 'n' is given by '-fabi-version=n': GCC 3.0: 100 GCC 3.1: 100 (Error, should be 101) GCC 3.2: 102 GCC 3.3: 102 GCC 3.4, GCC 4.x: 102 (when n=1) GCC 3.4, GCC 4.x: 1000 + n (when n>1) GCC 3.4, GCC 4.x: 999999 (when n=0) Changes to the default compiler option for -fabi-version. It is versioned as follows: GCC 3.0: (Error, not versioned) GCC 3.1: (Error, not versioned) GCC 3.2: -fabi-version=1 GCC 3.3: -fabi-version=1 GCC 3.4, GCC 4.x: -fabi-version=2 (Incompatible with previous) GCC 5 and higher: -fabi-version=0 (See GCC manual for meaning) Incremental bumping of a library pre-defined macro. For releases before 3.4.0, the macro is __GLIBCPP__. For later releases, it's __GLIBCXX__. (The libstdc++ project generously changed from CPP to CXX throughout its source to allow the "C" pre-processor the CPP macro namespace.) These macros are defined as the date the library was released, in compressed ISO date format, as an integer constant. This macro is defined in the file c++config in the libstdc++-v3/include/bits directory. Up to GCC 4.1.0, it was changed every night by an automated script. Since GCC 4.1.0 it is set during configuration to the same value as gcc/DATESTAMP, so for an official release its value is the same as the date of the release, which is given in the GCC Release Timeline. This macro can be used in code to detect whether the C++ Standard Library implementation in use is libstdc++, but is not useful for detecting the libstdc++ version, nor whether particular features are supported. The macro value might be a date after a feature was added to the development trunk, but the release could be from an older branch without the feature. For example, in the 5.4.0 release the macro has the value 20160603 which is greater than the 20160427 value of the macro in the 6.1.0 release, but there are features supported in the 6.1.0 release that are not supported in the 5.4.0 release. You also can't test for the exact values listed below to try and identify a release, because a snapshot taken from the gcc-5-branch on 2016-04-27 would have the same value for the macro as the 6.1.0 release despite being a different version. Many GNU/Linux distributions build their GCC packages from snapshots, so the macro can have dates that don't correspond to official releases. It is versioned as follows: GCC 3.0.0: 20010615 GCC 3.0.1: 20010819 GCC 3.0.2: 20011023 GCC 3.0.3: 20011220 GCC 3.0.4: 20020220 GCC 3.1.0: 20020514 GCC 3.1.1: 20020725 GCC 3.2.0: 20020814 GCC 3.2.1: 20021119 GCC 3.2.2: 20030205 GCC 3.2.3: 20030422 GCC 3.3.0: 20030513 GCC 3.3.1: 20030804 GCC 3.3.2: 20031016 GCC 3.3.3: 20040214 GCC 3.4.0: 20040419 GCC 3.4.1: 20040701 GCC 3.4.2: 20040906 GCC 3.4.3: 20041105 GCC 3.4.4: 20050519 GCC 3.4.5: 20051201 GCC 3.4.6: 20060306 GCC 4.0.0: 20050421 GCC 4.0.1: 20050707 GCC 4.0.2: 20050921 GCC 4.0.3: 20060309 GCC 4.1.0 and later: the GCC release date, as shown in the GCC Release Timeline Since GCC 7, incremental bumping of a library pre-defined macro, _GLIBCXX_RELEASE. This macro is defined to the GCC major version that the libstdc++ headers belong to, as an integer constant. When compiling with GCC it has the same value as GCC's pre-defined macro __GNUC__. This macro can be used when libstdc++ is used with a non-GNU compiler where __GNUC__ is not defined, or has a different value that doesn't correspond to the libstdc++ version. This macro is defined in the file c++config in the libstdc++-v3/include/bits directory and is generated automatically by autoconf as part of the configure-time generation of config.h and subsequently <bits/c++config.h>. Historically, incremental bumping of a library pre-defined macro, _GLIBCPP_VERSION. This macro was defined as the released version of the library, as a string literal. This was only implemented in GCC 3.1.0 releases and higher, and was deprecated in 3.4.x (where it was called _GLIBCXX_VERSION), and is not defined in 4.0.0 and higher. This macro is defined in the same file as _GLIBCXX_RELEASE, described above. It is versioned as follows: GCC 3.0.0: "3.0.0" GCC 3.0.1: "3.0.0" (Error, should be "3.0.1") GCC 3.0.2: "3.0.0" (Error, should be "3.0.2") GCC 3.0.3: "3.0.0" (Error, should be "3.0.3") GCC 3.0.4: "3.0.0" (Error, should be "3.0.4") GCC 3.1.0: "3.1.0" GCC 3.1.1: "3.1.1" GCC 3.2.0: "3.2" GCC 3.2.1: "3.2.1" GCC 3.2.2: "3.2.2" GCC 3.2.3: "3.2.3" GCC 3.3.0: "3.3" GCC 3.3.1: "3.3.1" GCC 3.3.2: "3.3.2" GCC 3.3.3: "3.3.3" GCC 3.4: "version-unused" GCC 4 and later: not defined Matching each specific C++ compiler release to a specific set of C++ include files. This is only implemented in GCC 3.1.1 releases and higher. All C++ includes are installed in include/c++, then nested in a directory hierarchy corresponding to the C++ compiler's released version. This version corresponds to the variable "gcc_version" in "libstdc++-v3/acinclude.m4," and more details can be found in that file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before GCC 3.4.0). C++ includes are versioned as follows: GCC 3.0.0: include/g++-v3 GCC 3.0.1: include/g++-v3 GCC 3.0.2: include/g++-v3 GCC 3.0.3: include/g++-v3 GCC 3.0.4: include/g++-v3 GCC 3.1.0: include/g++-v3 GCC 3.1.1: include/c++/3.1.1 GCC 3.2.0: include/c++/3.2 GCC 3.2.1: include/c++/3.2.1 GCC 3.2.2: include/c++/3.2.2 GCC 3.2.3: include/c++/3.2.3 GCC 3.3.0: include/c++/3.3 GCC 3.3.1: include/c++/3.3.1 GCC 3.3.2: include/c++/3.3.2 GCC 3.3.3: include/c++/3.3.3 GCC 3.4.x: include/c++/3.4.x GCC 4.x.y: include/c++/4.x.y GCC 5.1.0: include/c++/5.1.0 GCC x.y.0: include/c++/x.y.0 (for releases after GCC 5.1.0) Taken together, these techniques can accurately specify interface and implementation changes in the GNU C++ tools themselves. Used properly, they allow both the GNU C++ tools implementation, and programs using them, an evolving yet controlled development that maintains backward compatibility.

Minimum environment that supports a versioned ABI: A supported dynamic linker, a GNU linker of sufficient vintage to understand demangled C++ name globbing (ld) or the Sun linker, a shared executable compiled with g++, and shared libraries (libgcc_s, libstdc++) compiled by a compiler (g++) with a compatible ABI. Phew. On top of all that, an additional constraint: libstdc++ did not attempt to version symbols (or age gracefully, really) until version 3.1.0. Most modern GNU/Linux and BSD versions, particularly ones using GCC 3.1 and later, will meet the requirements above, as does Solaris 2.5 and up.

It turns out that most of the configure options that change default behavior will impact the mangled names of exported symbols, and thus impact versioning and compatibility. For more information on configure options, including ABI impacts, see: here There is one flag that explicitly deals with symbol versioning: --enable-symvers. In particular, libstdc++-v3/acinclude.m4 has a macro called GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument passed in via --enable-symvers=foo). At that point, the macro attempts to make sure that all the requirement for symbol versioning are in place. For more information, please consult acinclude.m4.

When the GNU C++ library is being built with symbol versioning on, you should see the following at configure time for libstdc++ (showing either 'gnu' or another of the supported styles): checking versioning on shared library symbols... gnu If you don't see this line in the configure output, or if this line appears but the last word is 'no', then you are out of luck. If the compiler is pre-installed, a quick way to test is to compile the following (or any) simple C++ file and link it to the shared libstdc++ library: #include <iostream> int main() { std::cout << "hello" << std::endl; return 0; } %g++ hello.cc -o hello.out %ldd hello.out libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000) libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) %nm hello.out If you see symbols in the resulting output with "GLIBCXX_3" as part of the name, then the executable is versioned. Here's an example: U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4 On Solaris 2, you can use pvs -r instead: %g++ hello.cc -o hello.out %pvs -r hello.out libstdc++.so.6 (GLIBCXX_3.4, GLIBCXX_3.4.12); libgcc_s.so.1 (GCC_3.0); libc.so.1 (SUNWprivate_1.1, SYSVABI_1.3); ldd -v works too, but is very verbose.

The following will cause the library minor version number to increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5". Adding an exported global or static data member Adding an exported function, static or non-virtual member function Adding an exported symbol or symbols by additional instantiations Other allowed changes are possible.

The following non-exhaustive list will cause the library major version number to increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.4.0.0". Changes in the gcc/g++ compiler ABI Changing size of an exported symbol Changing alignment of an exported symbol Changing the layout of an exported symbol Changing mangling on an exported symbol Deleting an exported symbol Changing the inheritance properties of a type by adding or removing base classes Changing the size, alignment, or layout of types specified in the C++ standard. These may not necessarily be instantiated or otherwise exported in the library binary, and include all the required locale facets, as well as things like std::basic_streambuf, et al. Adding an explicit copy constructor or destructor to a class that would otherwise have implicit versions. This will change the way the compiler deals with this class in by-value return statements or parameters: instead of passing instances of this class in registers, the compiler will be forced to use memory. See the section on Function Calling Conventions and APIs of the C++ ABI documentation for further details.

Separation of interface and implementation This is accomplished by two techniques that separate the API from the ABI: forcing undefined references to link against a library binary for definitions. Include files have declarations, source files have defines For non-templatized types, such as much of class locale, the appropriate standard C++ include, say locale, can contain full declarations, while various source files (say locale.cc, locale_init.cc, localename.cc) contain definitions. Extern template on required types For parts of the standard that have an explicit list of required instantiations, the GNU extension syntax extern template can be used to control where template definitions reside. By marking required instantiations as extern template in include files, and providing explicit instantiations in the appropriate instantiation files, non-inlined template functions can be versioned. This technique is mostly used on parts of the standard that require char and wchar_t instantiations, and includes basic_string, the locale facets, and the types in iostreams. In addition, these techniques have the additional benefit that they reduce binary size, which can increase runtime performance. Namespaces linking symbol definitions to export mapfiles All symbols in the shared library binary are processed by a linker script at build time that either allows or disallows external linkage. Because of this, some symbols, regardless of normal C/C++ linkage, are not visible. Symbols that are internal have several appealing characteristics: by not exporting the symbols, there are no relocations when the shared library is started and thus this makes for faster runtime loading performance by the underlying dynamic loading mechanism. In addition, they have the possibility of changing without impacting ABI compatibility. The following namespaces are transformed by the mapfile: namespace std Defaults to exporting all symbols in label GLIBCXX that do not begin with an underscore, i.e., __test_func would not be exported by default. Select exceptional symbols are allowed to be visible. namespace __gnu_cxx Defaults to not exporting any symbols in label GLIBCXX, select items are allowed to be visible. namespace __gnu_internal Defaults to not exported, no items are allowed to be visible. namespace __cxxabiv1, aliased to namespace abi Defaults to not exporting any symbols in label CXXABI, select items are allowed to be visible. Freezing the API Disallowed changes, as above, are not made on a stable release branch. Enforcement tends to be less strict with GNU extensions that standard includes.

Testing for GNU C++ ABI changes is composed of two distinct areas: testing the C++ compiler (g++) for compiler changes, and testing the C++ library (libstdc++) for library changes. Testing the C++ compiler ABI can be done various ways. One. Intel ABI checker. Two. The second is yet unreleased, but has been announced on the gcc mailing list. It is yet unspecified if these tools will be freely available, and able to be included in a GNU project. Please contact Mark Mitchell (mark@codesourcery.com) for more details, and current status. Three. Involves using the vlad.consistency test framework. This has also been discussed on the gcc mailing lists. Testing the C++ library ABI can also be done various ways. One. (Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, one with a new compiler and an old library, and the other with an old compiler and a new library, and look for testsuite regressions) Details on how to set this kind of test up can be found here: http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html Two. Use the 'make check-abi' rule in the libstdc++ Makefile. This is a proactive check of the library ABI. Currently, exported symbol names that are either weak or defined are checked against a last known good baseline. Currently, this baseline is keyed off of 3.4.0 binaries, as this was the last time the .so number was incremented. In addition, all exported names are demangled, and the exported objects are checked to make sure they are the same size as the same object in the baseline. Notice that each baseline is relative to a default configured library and compiler: in particular, if options such as --enable-clocale, or --with-cpu, in case of multilibs, are used at configure time, the check may fail, either because of substantive differences or because of limitations of the current checking machinery. This dataset is insufficient, yet a start. Also needed is a comprehensive check for all user-visible types part of the standard library for sizeof() and alignof() changes. Verifying compatible layouts of objects is not even attempted. It should be possible to use sizeof, alignof, and offsetof to compute offsets for each structure and type in the standard library, saving to another datafile. Then, compute this in a similar way for new binaries, and look for differences. Another approach might be to use the -fdump-class-hierarchy flag to get information. However, currently this approach gives insufficient data for use in library testing, as class data members, their offsets, and other detailed data is not displayed with this flag. (See PR g++/7470 on how this was used to find bugs.) Perhaps there are other C++ ABI checkers. If so, please notify us. We'd like to know about them!

A "C" application, dynamically linked to two shared libraries, liba, libb. The dependent library liba is a C++ shared library compiled with GCC 3.3, and uses io, exceptions, locale, etc. The dependent library libb is a C++ shared library compiled with GCC 3.4, and also uses io, exceptions, locale, etc. As above, libone is constructed as follows: %$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc %$bld/H-x86-gcc-3.4.0/bin/g++ -shared -Wl,-soname -Wl,libone.so.1 -Wl,-O1 -Wl,-z,defs a.o -o libone.so.1.0.0 %ln -s libone.so.1.0.0 libone.so %$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc %ar cru libone.a a.o And, libtwo is constructed as follows: %$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc %$bld/H-x86-gcc-3.3.3/bin/g++ -shared -Wl,-soname -Wl,libtwo.so.1 -Wl,-O1 -Wl,-z,defs b.o -o libtwo.so.1.0.0 %ln -s libtwo.so.1.0.0 libtwo.so %$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc %ar cru libtwo.a b.o ...with the resulting libraries looking like %ldd libone.so.1.0.0 libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000) libm.so.6 => /lib/tls/libm.so.6 (0x400fa000) libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000) libc.so.6 => /lib/tls/libc.so.6 (0x40125000) /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) %ldd libtwo.so.1.0.0 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000) libm.so.6 => /lib/tls/libm.so.6 (0x400e1000) libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000) libc.so.6 => /lib/tls/libc.so.6 (0x4010c000) /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) Then, the "C" compiler is used to compile a source file that uses functions from each library. gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6 Which gives the expected: %ldd a.out libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000) libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000) /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) This resulting binary, when executed, will be able to safely use code from both liba, and the dependent libstdc++.so.6, and libb, with the dependent libstdc++.so.5.

Some features in the C++ language make versioning especially difficult. In particular, compiler generated constructs such as implicit instantiations for templates, typeinfo information, and virtual tables all may cause ABI leakage across shared library boundaries. Because of this, mixing C++ ABIs is not recommended at this time. For more background on this issue, see these bugzilla entries: 24660: versioning weak symbols in libstdc++ 19664: libstdc++ headers should have pop/push of the visibility around the declarations

UlrichDrepper ISO C++ J16/06-0046 BenjaminKosnik ISO C++ J16/06-0083 BenjaminKosnik SYRCoSE 2009 PavelShved DenisSilakov