Platform:Itanium C++ ABI
| Developer | Itanium C++ ABI group (CodeSourcery, HP, Intel, Red Hat, others; 1999-2001), now maintained at itanium-cxx-abi.github.io |
|---|---|
| Platforms | Linux, Android, FreeBSD/NetBSD/OpenBSD, macOS/iOS, MinGW-w64 and Cygwin, WebAssembly, Fuchsia, bare-metal ARM/AArch64/RISC-V/MIPS |
| Magic | 47 4E 55 43 43 2B 2B 00 ("GNUCC++\0" exception class), 43 4C 4E 47 43 2B 2B 00 ("CLNGC++\0") |
| Website | https://itanium-cxx-abi.github.io/cxx-abi/abi.html |
| On this wiki | Facts · Code · Notes · Topics |
The C++ binary conventions of GCC and Clang everywhere except MSVC-compatible Windows: Linux, Android, the BSDs, macOS/iOS, MinGW, WebAssembly and most embedded targets. Mangled names start with _Z, every polymorphic class has a vtable whose slot -1 points to its type_info object (__class_type_info, __si_class_type_info or __vmi_class_type_info) and slot -2 holds the offset to the top of the object, and C++ exceptions go through __cxa_throw and the two-phase _Unwind_* unwinder, tagged with the exception class "GNUCC++\0" (libstdc++) or "CLNGC++\0" (libc++abi).
Overview
The ABI was written for Intel Itanium in 1999-2001 but became the C++ ABI of GCC (3.0 and later) and Clang on every other architecture, so it is what a reverser meets in Linux and Android binaries, macOS/iOS apps, MinGW-built Windows programs, WebAssembly modules and most console and embedded code built with Clang or GCC. Only MSVC and clang-cl on Windows use a different ABI (Platform:Microsoft Visual C++ ABI).
The compiler side is GCC's C++ front end (gcc/cp/) and Clang (clang/lib/CodeGen/ItaniumCXXABI.cpp, clang/lib/AST/ItaniumMangle.cpp); the runtime side (__cxa_* functions, the type_info classes, __dynamic_cast, the personality routine) is libsupc++ inside libstdc++ (GCC), libc++abi (LLVM, used with libc++ on macOS, Android NDK, FreeBSD and Fuchsia) or libcxxrt. The unwinder below it (_Unwind_RaiseException, _Unwind_Resume) is libgcc_s / libgcc_eh or LLVM libunwind.
- Names: Platform:Itanium C++ ABI/Name mangling:
_Z+ encoding, e.g._ZNKSt9exception4whatEv=std::exception::what() const; special names_ZTV(vtable),_ZTI(typeinfo),_ZTS(typeinfo name),_ZTT(VTT),_ZTh/_ZTv(thunks),_ZGV(guard variable). - Classes: Platform:Itanium C++ ABI/RTTI and vtables: vtable = [virtual-base offsets] [offset-to-top] [&type_info] then the function pointers; objects point to the first function pointer (the address point). type_info objects carry the mangled type name without
_Z. - Exceptions: Platform:Itanium C++ ABI/Exception handling:
__cxa_allocate_exception+__cxa_throw→_Unwind_RaiseException, a search phase and a cleanup phase driven by the personality routine (__gxx_personality_v0) reading the LSDA in.gcc_except_table.
Target variants (all from CreateItaniumCXXABI in clang ItaniumCXXABI.cpp): 32-bit ARM and Apple iOS/watchOS use the ARM C++ ABI (constructors return this, array cookies, 32-bit guard words tested on bit 0, member-function pointers with the virtual bit in adj; exceptions through ARM EHABI .ARM.exidx/.ARM.extab instead of .eh_frame); AArch64 keeps the generic ABI but uses ARM-style member-function pointers and guard variables; MIPS uses ARM-style member-function pointers only; WebAssembly, Fuchsia (relative vtables) and AIX (XL) have their own small differences. On Windows, MinGW-w64 x86-64 unwinds through SEH (__gxx_personality_seh0), 32-bit MinGW through DWARF-2 tables (__gxx_personality_v0) or setjmp/longjmp (__gxx_personality_sj0).
Identification
A binary was compiled as C++ under this ABI when it has:
_Z-prefixed symbols in its symbol table, exports or imports (_ZNSt6vectorIiSaIiEE9push_backERKi), and C++ type-name strings without the_Z(St9exception,N4acng5acbufE) where MSVC would have.?AV...@@;- imports of
__cxa_allocate_exception,__cxa_throw,__cxa_begin_catch,__cxa_end_catch,__cxa_rethrow,__cxa_pure_virtual,__cxa_guard_acquire/__cxa_guard_release,__cxa_atexit,__dynamic_castand a personality routine (__gxx_personality_v0, or__gxx_personality_seh0on MinGW x64); - data imports or relocations against
_ZTVN10__cxxabiv117__class_type_infoE,_ZTVN10__cxxabiv120__si_class_type_infoEor_ZTVN10__cxxabiv121__vmi_class_type_infoE(the vtables every RTTI object points to); - a statically linked runtime: the strings
N10__cxxabiv117__class_type_infoE,N10__cxxabiv120__si_class_type_infoE,N10__cxxabiv121__vmi_class_type_infoEandSt9type_info.
Which runtime: libstdc++ code contains the exception class 0x474E5543432B2B00 ("GNUCC++\0"), libc++abi 0x434C4E47432B2B00 ("CLNGC++\0"), see Platform:Itanium C++ ABI/Exception handling#Exception class. The standard library's inline namespaces name it too: std::__1:: (libc++), std::__ndk1:: (Android NDK libc++), std::__cxx11:: and std::_V2:: (libstdc++ since GCC 5).
Conventions
- this is the first (hidden) argument of member functions: RDI on x86-64 System V, RCX on Win64 (MinGW), R0 on ARM, X0 on AArch64; on 32-bit x86 Linux it is on the stack (no
__thiscall, unlike MSVC). - Constructors and destructors exist in several variants: C1 complete-object, C2 base-object, C3 allocating constructor; D0 deleting, D1 complete-object, D2 base-object destructor. Compilers often make C1/C2 and D1/D2 aliases of one body. A class with a virtual destructor has two vtable slots for it: D1 first, then D0.
- Key function: a class's vtable and type_info are emitted in the object file that defines its first non-inline, non-pure virtual function; classes without one get COMDAT (weak,
.gnu.linkonce/group) copies in every user. - Pointers inside RTTI and vtables are absolute addresses. In ELF shared objects and PIEs the file holds 0 there (RELA: x86-64, AArch64, RISC-V) or the addend (REL: ARM, i386, MIPS) and the dynamic relocations fill them in, so a static tool must apply
.rela.dyn/.rel.dyn. - Static locals are protected by a guard variable
_ZGV<name>: 64-bit, initialised when its first byte is non-zero (generic ABI); a 32-bit (ARM) or 64-bit (AArch64) word tested on bit 0 under the ARM rules.
Recovery recipes
- Name the classes of a stripped binary: every word that points to a type-name string is the second field of a type_info object; the word before it points to one of the
__cxxabiv1vtables (+2 pointers) and gives the kind; every place that stores the type_info's address right after a 0 or negative offset-to-top is a vtable, whose functions follow. Code:Itanium C++ ABI/itanium_rtti_scan (Python) does this for ELF (applying REL/RELA relocations) and MinGW PE files. - Rebuild the hierarchy: a
__si_class_type_infohas one public non-virtual base at offset 0 (third field); a__vmi_class_type_infolists every direct base with its offset (or, for a virtual base, the vtable offset of its virtual-base offset) and public/virtual flags. - Read virtual calls:
mov rax, [rdi]/call [rax + 8*k](x86-64) calls slot k counted from the address point; the type ofrdifollows from which constructor stored which vtable address (lea rax, [vtable+16]; mov [rdi], rax). - Demangle:
c++filt,llvm-cxxfilt, or Code:Itanium C++ ABI/itanium_demangle (Python) when no toolchain is installed.
Topics
- Name mangling — How GCC and Clang mangle C++ names: _Z + an encoding built from length-prefixed source names, N...E nested names, I...E template arguments, one-letter builtin…
- RTTI and vtables — Layout of Itanium-ABI vtables (virtual-base offsets, offset-to-top, type_info pointer, then function pointers at the address point), VTTs and construction…
- Exception handling — How C++ exceptions work under the Itanium ABI: __cxa_allocate_exception puts a __cxa_exception header in front of the thrown object, __cxa_throw fills it and…
- LSDA — Layout of the language-specific data area (LSDA) in .gcc_except_table that the Itanium personality routines (__gxx_personality_v0, Rust's rust_eh_personality)…
Code & repositories
- {{Repo|url=https://github.com/llvm/llvm-project%7Ccommit=4bd435d59f89ded8e537e5c6e0b560ad89518c3f%7Clicense=Apache-2.0 WITH LLVM-exception (declared by the contributor; GitHub's detector did not recognize LICENSE.TXT)|description=LLVM. libcxxabi/ is the LLVM Itanium C++ runtime: src/private_typeinfo.h (__class_type_info, __si_class_type_info, __vmi_class_type_info, __base_class_type_info, __pbase_type_info layouts and flag masks), src/cxa_exception.h/.cpp (__cxa_exception header, CLNGC++ exception classes), src/cxa_personality.cpp (LSDA parser), src/cxa_guard_impl.h (guard variables), src/demangle/ItaniumDemangle.h (the __cxa_demangle / llvm-cxxfilt demangler) with 29,753 test vectors in test/DemangleTestCases.inc; libunwind/include/unwind*.h (_Unwind_Exception, reason codes); clang/lib/CodeGen/ItaniumCXXABI.cpp (vtables, RTTI emission, member pointers, guard variables, per-target ABI variants) and clang/lib/AST/ItaniumMangle.cpp (mangler).|tested_on=Read at this commit (sparse checkout of libcxxabi/src, libcxxabi/test, libunwind/include and the two clang files). The type_info, vtable and exception-class layouts were compared byte for byte with a MinGW-w64 GCC x86-64 libstdc++-6.dll and pyelftools' ARM libc++abi test library; the test vectors were run against the wiki's Python demangler (29,378 of 29,753 reproduced exactly, 0 wrong, the rest refused). Not built.|checked=checked 2026-10-17; last activity 2026-10-17; Note: the latest release ships binaries; the wiki links only the source, never the binaries}}
- {{Repo|url=https://github.com/gcc-mirror/gcc%7Ccommit=9e5dc38543418730291b90de2d03263a60ce5b8f%7Clicense=GPL-3.0-or-later WITH GCC-exception-3.1 (the libstdc++-v3 files cited here; GitHub's detector reports GPL-2.0 from the top-level COPYING, which covers other parts of GCC)|description=GCC (read-only mirror). libstdc++-v3/libsupc++/ is GCC's Itanium C++ runtime: cxxabi.h (type_info class hierarchy, __base_class_type_info with long long __offset_flags on LLP64), unwind-cxx.h (__cxa_exception, __cxa_refcounted_exception, __cxa_dependent_exception, the GNUCC++ exception classes, ARM EHABI variants), eh_throw.cc, eh_personality.cc (__gxx_personality_v0/_seh0/_sj0), tinfo.h; gcc/cp/rtti.cc emits the type_info objects and gcc/cp/mangle.cc mangles names.|tested_on=Read at this commit: libstdc++-v3/libsupc++/unwind-cxx.h, cxxabi.h and eh_throw.cc (gcc/cp/rtti.cc and mangle.cc are named, not reviewed); the exception classes and the 8-byte offset_flags were confirmed in a MinGW-w64 GCC x86-64 libstdc++-6.dll. Not built.|checked=checked 2026-10-17; last activity 2026-10-17}}
- itanium demangle (Python) — Dependency-free Itanium C++ ABI demangler (GCC/Clang/MinGW/Android/macOS _Z names and bare type-info names such as St9exception) with LLVM-identical output; refuses expressions instead of guessing…
- itanium rtti scan (Python) — Lists the C++ classes of a stripped GCC/Clang (Itanium ABI) ELF or MinGW PE file from its RTTI: type_info objects with their kind (class/si/vmi/pointer), base classes with offsets and virtual/public…
- https://github.com/rust-lang/rust @
02fb0a16311c3411fa373627706da085cd8fbd3c· license: Apache-2.0
The Rust compiler and standard library: symbol mangling in compiler/rustc_symbol_mangling, panic machinery in library/core/src/panicking.rs and library/panic_unwind, a compact LSDA parser in library/std/src/sys/personality/dwarf/eh.rs.
Tested on: source read, not run: Read at master 02fb0a16311c (2026-10-17), sparse checkout · checked 2026-10-18; last activity 2026-10-18
Pitfalls
- D0, D1 and D2 (and C1, C2) demangle to the same text (
Foo::~Foo()); keep the mangled name when the variant matters. - Win64 is LLP64: libstdc++ declares
__base_class_type_info::__offset_flagsaslong longthere and GCC and Clang (MinGW targets) emit 8-byte offset_flags; libc++abi still declareslong(a FIXME in clang's ItaniumCXXABI.cpp). - Abstract classes: in a GCC x86-64 build of libstdc++ the two destructor slots of every abstract-class vtable were 0 (11 of 214 vtables) and pure virtual slots pointed to
__cxa_pure_virtual; a scanner that requires slot 0 to be code misses them. - Type-name strings are not always preceded by a NUL: in an Android ARM libc++ shared object the linker packed
NSt6__ndk112system_errorEright after binary data, so find them through the pointers of type_info objects, not by splitting string sections at NULs. - Fundamental types (
i,Pv,DF16_...) have their type_info only in the runtime library; their 1-3 character names are useless as signatures. - GCC and Clang also insert stack protector canaries (
fs:0x28,__stack_chk_fail), stack probes and magic-number divisions that are not author code: see Technique:Recognizing compiler-generated code.
Evidence & references
- The ABI specification: https://itanium-cxx-abi.github.io/cxx-abi/abi.html (sections 2.3 member pointers, 2.5 vtables, 2.9 RTTI, 3.3.2 guard variables, 5.1 mangling) and the exception-handling ABI https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html.
- llvm-project at commit 4bd435d59f89ded8e537e5c6e0b560ad89518c3f:
libcxxabi/src/private_typeinfo.h,libcxxabi/src/cxa_exception.h,libcxxabi/src/cxa_exception.cpp,libcxxabi/src/demangle/ItaniumDemangle.h,libcxxabi/test/DemangleTestCases.inc,libunwind/include/unwind.h,libunwind/include/unwind_itanium.h,clang/lib/CodeGen/ItaniumCXXABI.cpp. - gcc-mirror/gcc at commit 9e5dc38543418730291b90de2d03263a60ce5b8f:
libstdc++-v3/libsupc++/unwind-cxx.h,libstdc++-v3/libsupc++/cxxabi.h. - Checked on files: a MinGW-w64 GCC x86-64 (SEH) build of libstdc++-6.dll (6,852 exports), and three public-domain ELF test files of pyelftools at commit 5a04389392e25d8128e1acb59828a0a85be791b1 (
test/testfiles_for_unittests/arm_exidx_test.soand.so.elf: Android ARM libc++/libc++abi;test/testfiles_for_readelf/angr-eh_frame.so.elf: MIPS64 little-endian, GCC).