libstdc++ Dual ABI: Diagnose C++ Library Mismatches That Changing -std Will Not Fix
A C++ library that links with one application but reports unresolved std::__cxx11 symbols with another needs an object-level ABI check. Changing the language dialect alone is not a reliable repair. With GCC’s libstdc++ dual ABI, the library declarations selected by _GLIBCXX_USE_CXX11_ABI can differ between translation units even when both are compiled as C++17.
This procedure is pinned to the GCC 14.2 libstdc++ manual. An executed x86-64 host fixture held C++17 constant and varied the dual-ABI macro across a std::string interface. It establishes one reproducible link boundary, not compatibility for every standard-library type or binary-only SDK.
Separate the three version questions
Record the language dialect, compiler ABI settings and libstdc++ declaration ABI separately. The dialect controls accepted language features. Compiler ABI options can change how the compiler represents or names C++ entities. The dual-ABI macro selects particular old or new standard-library interfaces provided by libstdc++.
The GCC 14.2 dual-ABI documentation says the new implementation was introduced in GCC 5.1 and that the choice is independent of the -std option. The library can provide both forms under the same shared-library SONAME. A matching libstdc++.so.6 filename therefore does not establish which declarations an object used.
Do not assume every distribution configured the same macro default. Capture the actual compile command for each boundary object, including generated code, imported archives and precompiled headers. If a vendor supplies only a binary, request its build contract rather than guessing from a product release number.
Inventory declarations before linking
Ask the actual compiler to preprocess a tiny file that includes a relevant C++ library header, then inspect _GLIBCXX_USE_CXX11_ABI. For an owned local probe, a command shaped like g++ -std=c++17 -dM -E -x c++ probe.cpp can expose the macro after probe.cpp includes <string>. A bare macro dump without the relevant headers may not establish the library’s configured choice.
Repeat with the exact include paths and definitions used by each component. A command run outside the build system is useful only if its environment matches the object being diagnosed. Save the compiler identity, selected headers, macro result and artifact hash in a small boundary inventory.
When overriding the macro deliberately, define it before the standard-library headers are included. Recompile every affected translation unit and invalidate precompiled artifacts that captured another declaration environment. A late definition in a source file cannot retroactively change declarations already processed.
Use symbol names as clues
Inspect undefined and defined symbols separately. nm -C helps humans recognize std::__cxx11 and ABI-tagged names; retain the raw names as machine-comparable evidence. For archives, identify the member that supplies or requests the symbol instead of attributing every mismatch to the final executable.
A consumer requesting a new-ABI std::string signature cannot be satisfied by an implementation whose corresponding function has the old-ABI signature. First compare the requested and provided names. Only after that should you investigate library order, missing archive members or search-path selection.
Absence of an obvious __cxx11 name is not proof of compatible layout. The GCC manual specifically warns that some types containing std::string can keep the same mangled name across the two ABIs. A successful link can therefore leave an unsafe object-layout boundary. Its suggested -Wabi-tag diagnostics can add evidence, but they do not replace an explicit interface audit.
Read the controlled four-case matrix
The fixture compiled a function taking std::string by value and a caller passing a three-character string. Every compilation used GCC 14.2.0 with -std=c++17. Only _GLIBCXX_USE_CXX11_ABI changed between zero and one.
| Library ABI | Caller ABI | Observed result |
|---|---|---|
| 0 | 0 | Linked and returned the expected length. |
| 1 | 1 | Linked and returned the expected length. |
| 0 | 1 | Link failed with an unresolved interface. |
| 1 | 0 | Link failed with an unresolved interface. |
These were owned host executables using BFD Binutils 2.44. No mismatched-layout object was executed. No target image, exception exchange, custom allocator or vendor binary was qualified. The matrix is evidence that a fixed language mode can still contain a dual-ABI mismatch, rather than evidence that every mismatch must fail safely at link time.
Choose a repair with an explicit boundary
If sources are available, select one supported ABI contract for components that exchange affected C++ types and rebuild the complete boundary. Include constructors, destructors, inline methods and templates instantiated on both sides. Keep the selected macro in exported build requirements where consumers can actually inherit it.
If a binary-only dependency cannot be rebuilt, a deliberately narrow C interface may isolate its C++ implementation. Keep creation, destruction and allocation ownership on the same side, and pass documented byte buffers or opaque handles. Merely adding extern “C” to a function that still exposes std::string does not make its data representation independent of the C++ ABI.
Do not rename a library, fabricate a symbol alias or suppress the unresolved reference to force a link. Those changes do not translate object representations. The GCC ABI policy is useful for separating compiler, runtime and configuration compatibility instead of treating them as one version number.
Close the qualification loop
Retest an actual public interface with matched builds, then exercise ownership transfer, empty and nonempty values, error paths and lifetime boundaries in a disposable target environment. Add an intentional mismatched compile case to the build checks when the interface has a clear symbol-level distinction. Keep layout-sensitive cases as separately reviewed contracts.
The release result should state which objects share an ABI, how that choice is reproduced and which foreign boundary remains isolated. Preserve the four-case evidence and the raw symbol inventory. This turns a confusing std::__cxx11 linker message into a specific build-contract decision without claiming that one successful executable proves all C++ interoperability.
