Discover gchatelet/gcc_cpp_mangling_documentation Open Source project

This document gathers my findings about gcc c++ name mangling.

It is to be considered as supplementaty materials to the Itanium C++ ABI's mangling section, especially it explores what accounts as a symbol to be substituted in the case of regular functions, templates and abbreviations.

Mangling basics

Global variable declaration

As in C name mangling, it is just the name of the variable.

eg. int bar; is mangled as bar.

eg. void(*baz)(int); is mangled as baz.

Const or nested variable declaration

eg. int* const bar; is mangled as _ZL3bar

_Z preambule starts the mangled name.
L indicates the variable is const
- Only applies to types with indirections (pointer / reference) since const <value_type> is mangled as <value_type>
3bar variable name, length encoded.

eg. void(* const baz)(int) = nullptr; is mangled as _ZL3baz

_Z preambule starts the mangled name.
L indicates the variable is const
3baz variable name, length encoded.

eg. namespace a { int bar; } is mangled as _ZN1a3barE

_Z preambule starts the mangled name.
N1a3barE encoded symbol. It is enclosed in N..E because the symbol is within a scope
- 1a namespace name, length encoded.
- 3bar variable name, length encoded.

Note: the std namespace is special. It is abbreviated St and remove the need for N..E enclosing.

eg. namespace std { int bar; } is mangled as _ZSt3bar

Function declaration

 _Z <declaration> (<parameter>+ | v )

<parameter> is defined as ([PR]K?)*(<basic_type>|<function>|<user_type>) with:

P for pointer
R for reference
K for const
<basic_type> for one of C++ basic types
<function> are encoded between F..E, return type of the function is encoded before parameters
<user_type> are encoded between N..E when nested (TODO add definition) and describe the whole hierarchy of types.

eg. void foo() is mangled as _Z3foov

_Z preambule is always here.
3foo function name, length encoded.
v no parameter is encoded as a single void parameter.

Note: the return type is not encoded here (although there are cases where it is encoded: function pointers and funtion template instances)

Function template instance declaration

 _Z <declaration> I<template_parameter>+E <template_return_type> (<parameter>+ | v )

eg.

template <typename A> void foo(A);
template <> void foo(int) {}

is mangled _Z3fooIiEvT_:

_Z preambule is always here, it starts the mangled name, for OSX it would be __Z.
3foo function name, length encoded.
IiE template parameter int is enclosed in I..E
v the return type void.
T_ reference to the first template parameter. Second would be T0_, third T1_, fourth T2_, etc ...

Declaration and user defined type encoding

Declaration and user defined types are encoded with their scope

namespace a {
    struct S {
        void foo();
        void const_foo() const;
    };
}

foo is mangled _ZN1a1S3fooEv:
- N1a1S3fooE: a::S::foo, foo is nested since it's within S and a so it is enclosed in N..E
  - 1a
  - 1S
  - 3foo
- v: because there is no parameters (encoded as a single void parameter).
const_foo is mangled _ZNK1a1S9const_fooEv:
- NK1a1S9const_fooE: a::S::foo, foo is nested since it's within S and a so it is enclosed in N..E
  - K because type S is const in the context of foo
  - 1a
  - 1S
  - 9const_foo

Substitutions

To save space a compression scheme is used where symbols that appears multiple times are then substituted by an item from the sequence : S_, S0_, S1_, S2_, etc ...

The main added value of this document is to identify what is to be counted as a substitution.

eg.

void foo(void*, void*)

foo would be encoded as _Z3fooPvS_. To be decomposed as

_Z
3foo
Pv stands for "pointer to void". Since it's not a basic type it's accounted as a symbol.
S_ refers to the first symbol encoded, here Pv.

Note: foo is a declaration, not a type and so it doesn't account as a substituable symbol.

Abbreviations

Some symbols are recognized as special and are never substituted

St = ::std::
Sa = ::std::allocator
Sb = ::std::basic_string
Ss = ::std::basic_string<char, ::std::char_traits<char>, ::std::allocator<char> >
Si = ::std::basic_istream<char, ::std::char_traits<char> >
So = ::std::basic_ostream<char, ::std::char_traits<char> >
Sd = ::std::basic_iostream<char, ::std::char_traits<char> >

More on substitutions in function parameters

Function parameters are either basic types, user defined types or indirections to basic or user defined types.

Basic types are encoded using a single letter. See Itanium C++ ABI's types mangling. Basic types are never substituable.
- eg. void foo(int) is encoded _Z3fooi
No parameter is seen by the compiler as a single void parameter.
- eg. void foo() is seen as void foo(void) and encoded _Z3foov
Parameters are encoded one after the other.
- eg. void foo(char, int, short) is encoded _Z3foocis. None of char, int or short are substituable.

Indirections (pointer/reference) and type qualifiers are prepended to the type. Each indirection / type qualifier accounts for a new symbol.
- eg. void foo(int) is encoded _Z3fooi.
  - No substitution.
- eg. void foo(const int) is encoded _Z3fooi.
  - No substitution.
- eg. void foo(const int*) is encoded _Z3fooPKi
  - Ki becomes S_
  - PKi becomes S0_
- eg. void foo(const int&) is encoded _Z3fooRKi
  - Ki becomes S_
  - RKi becomes S0_
- eg. void foo(const int* const*) is encoded _Z3fooPKPKi
  - Ki becomes S_
  - PKi becomes S0_
  - KPKi becomes S1_
  - PKPKi becomes S2_
- eg. void foo(int*&) is encoded _Z3fooRPi
  - Pi becomes S_
  - RPi becomes S0_

Note: const int alone is encoded as int, more generally constness of the type is not part of the signature (but constness of indirect types are).

Functions are encoded between F..E and prepended with P for function pointer (R for function reference), return type of the function is encoded.
- eg. void foo(void(*)(int)) is encoded _Z3fooPFviE
  - FviE becomes S_
  - PFviE becomes S0_
  - eg. void foo(void*(*)(void*),void*(*)(const void*),const void*(*)(void*)); is encoded _Z3fooPFPvS_EPFS_PKvEPFS3_S_E with the following substitutions

    _Z3fooPFPvS_EPFS_PKvEPFS3_S_E
S_          ^^                    : Pv          void*
S0_        ^^^^^^                 : FPvS_E      void*()(void*)
S1_       ^^^^^^^                 : PFPvS_E     void*(*)(void*)
S2_                   ^^          : Kv          const void
S3_                  ^^^          : PKv         const void*
S4_               ^^^^^^^         : FS_PKvE     void*()(const void*)
S5_              ^^^^^^^^         : PFS_PKvE    void*(*)(const void*)
S6_                       ^^^^^^^ : FS3_S_E     const void*()(void*)
S7_                      ^^^^^^^^ : PFS3_S_E    const void*(*)(void*)

More on substitutions in scopes

namespace

namespace a {
	struct A{};
	void foo(A) {}
}

foo would be encoded as _ZN1a3fooENS_1AE

a::foo is encoded as N1a3fooE
- It is enclosed by N..E (symbol is nested and not in std)
- a is encoded 1a
- foo is encoded 3foo
a::A is encoded NS_1AE
- enclosed in N..E (symbol is nested and not in std)
- a is encoded S_
- A is encoded 1A

Note: if namespace is std then it is abbreviated and nested symbol are no more enclosed in N..E

namespace std {
	struct A{};
	void foo(A) {}
}

foo is encoded as _ZSt3fooSt1A

std::foo is encoded as St3foo
std::A is encoded as St1A

Note: std is not substituted since it is an abbreviation.

struct / classes

struct A {
    struct B{};
    void foo(B);
};

void A::foo(A::B) is encoded _ZN1A3fooENS_1BE

N1A3fooE: declaration
- 1A: A is now as S_
- 3foo: name (not substituable)
NS_1BE: single parameter of type B
- S_: A
- 1B: name, B is now S0_

More on substitutions in templates

Template instances account for one substitution.

template<typename T>
struct A {
    void foo(A);
};

template<> void A<int>::foo(A<int>) {}

template<> void A<int>::foo(A<int>) is encoded as _ZN1AIiE3fooES0_

N1AIiE3fooE: declaration
- 1AIiE: is the template instantiation
  - 1A: is now S_
  - IiE: one int template parameter
  - It accounts for a substitution, it is now S0_
- 3foo: name (not substituable)
S0_: refers to A<int>

Templated function parameters are substituted with T[0-9]*_ on first use and then substituted again normally.

struct A {
    template<typename T>
    void foo(T, T);
};

template<> void A::foo<int>(int, int) {}

template<> void A::foo<int>(int, int) is encoded as _ZN1A3fooIiEEvT_S1_

N1A3fooIiEE: declaration
- 1A: is now S_
- 3foo: name (not substituable)
- IiE: one int template parameter, is now T_
- N1A3fooIiEE the full instantiated template is now S0_
v: template instance return type
T_S1_ function parameters
- T_: refers to the first template parameter, is now S1_
- S1_

Templated function parameters are substituted only if the declaration is templated.

template<typename T>
struct A {
    void foo(T, T);
};

template<> void A<int>::foo(int, int) {}

template<> void A<int>::foo(int, int) is encoded as _ZN1AIiE3fooEii

N1AIiE3fooE: declaration
- 1A: is now S_
- IiE: one int template parameter (basic types are not substituable)
- 1AIiE3: is now S0_
- 3foo: name (not substituable)
ii: first and second parameter refers to the first template parameter but is not substituted.

struct B {};

template<typename T>
struct A {
    void foo(T, T);
};

template <> void A<B>::foo(B, B) {}

template <> void A<B>::foo(B, B) is encoded as _ZN1AI1BE3fooES0_S0_

N1AI1BE3fooE: declaration
- 1A: is now S_
- I1BE: one B template parameter is now S0_
- 1AI1BE: is now S1_
- 3foo: name (not substituable)
S0_S0_: S0_ refers to B.

Function template parameters are substituted.

template<typename A, typename B> A foo(B, A, B);
template<> int foo(char, int, char) {}
template<> int foo(int, int, int) {}

template<> int foo(char, int, char) is encoded as _Z3fooIicET_T0_S0_S1_

3fooIicE: is now S_
T_: The return type of the function. int is now S0_
T0_: char is now S1_

template<> int foo(int, int, int) is encoded as _Z3fooIiiET_T0_S0_S1_

3fooIiiE: is now S_
T_: The return type of the function. int is now S0_
T0_: int is now S1_

gchatelet/gcc_cpp_mangling_documentation

gchatelet

Reviews

Repository Details