Visual C++ name mangling

Visual C++ name mangling is a mangling (decoration) scheme used in Microsoft's Visual C++ series of compilers. It provides a way of encoding the name and additional information about a function, structure, class or another datatype in order to pass more semantic information from the Microsoft Visual C++ compiler to its linker. Visual Studio and the Windows SDK (which includes the command line compilers) come with the program, which may be invoked to obtain the C-style function prototype encoded in a mangled name. The information below has been mostly reverse-engineered; there is no official documentation for the actual algorithm used.

Overview
Any object code produced by the compiler is usually linked with other pieces of object code by the linker. The linker relies on unique object names for identification but C++ (and many modern programming languages) allows different entities to be named with the same identifier as long as they occupy a different namespace. Names need to be mangled by the compiler to make them distinct before reaching the linker. The linker also needs information on each program entity. For example, to correctly link a function it needs its name, the number of arguments and their types. C++ decoration can become complex (storing information about classes, templates, namespaces, operator overloading, etc.).

The C++ language does not define a standard decoration scheme, so each C++ compiler uses its own.

Basic Structure
All mangled C++ names start with  (question mark). Because all mangled C names start with alphanumeric characters,  (at-sign) and   (underscore), C++ names can be distinguished from C names.

The structure of mangled names looks like this:
 * Prefix
 * Optional: Prefix
 * Qualified name
 * Type information (see below)

Function
Type information in function names generally looks like this:
 * Access level and function type
 * Conditional: CV-class modifier of function, if non-static member function
 * Function property

Data
Type information in data names looks like this:
 * Access level and storage class
 * Data type
 * CV-class modifier

Elements
Mangled name contains a lot of elements which will be discussed.

Name
Qualified name consists of the following fragments:
 * Basic name: one of: name fragment or special name
 * Qualification #1: one of: name fragment, name with template arguments, numbered namespace or back reference
 * Qualification #2
 * Terminator
 * Terminator

Qualification is written in reversed order. For example  becomes.

Name Fragment
A fragment of a name is simply represented as the name with trailing.

Special Name
Special names are represented as a code with a preceding. Most of special names are constructor, destructor, operator and internal symbol. Below is a table for known codes.

Below are the RTTI-related codes (all starting with ). Some codes have trailing parameters. String constants (all starting with ):

The name corresponds to the value stored in a read-only COMDAT section, in order to avoid duplicate storage of the same string. These sections are generated only if the /GF switch is given to the Microsoft compiler.

The entire name consists of: For example, the complete name  represents the 21-character double-byte string "invalid null pointer\0". All characters have 0 for their high order byte.
 * or .  Indicates single- or double-byte characters, respectively.
 * Length of the string in bytes (encoded number). Includes null terminating character, if any.
 * A 32-bit value (encoded number). Meaning unknown, presumably a hash of the string.
 * The bytes of the string (up to the first 32 characters only). For double-byte strings, the bytes are in big-endian order.  They can be interpreted as Unicode text using the UTF-16BE encoding.  Each byte is encoded as:
 * Possibly another encoded number, meaning unknown.
 * Terminating  character.

It is possible, but very unlikely, for two different strings to be given the same symbol name. The strings would have to have the same first 32 characters, the same length, and the same hash value. The MSVC compiler generates COMDAT sections which tell the linker to "pick any" section with the same symbol name, ignoring the contents. Therefore, the linker will not catch the discrepancy.

Name with Template Arguments
Name fragments starting with  have template arguments. This kind of name looks like this:
 * Prefix
 * Name terminated by
 * Template argument list

For example, we assume the following prototype.

The name of this function can be obtained by the following process:

So the mangled name for this function is.

Nested Name
A name fragment starting with  denotes a nested name. This is a name inside a local scope which must be exported. Its structure looks like the following:
 * Optional sequence number for multiple occurrences of same name in the same local scope. This can only happen if the scope is a function, with the name being declared in multiple blocks.  It consists of:
 * encoded number.
 * Prefix
 * C++ Mangled name (so starting with  again), which names the local scope.
 * C++ Mangled name (so starting with  again), which names the local scope.

For example,  means variable   inside. The UnDecorateSymbolName function returns  for this input.

And  means constant   inside , where the compiler chose the number 2 to associate with it. The UnDecorateSymbolName function returns for this input.

Numbered Namespace
In qualification, a numbered namespace is represented as a preceding  and an unsigned number. The UnDecorateSymbolName function returns something like ' ' for this kind of input.

Exceptionally, if a numbered namespace starts with, it becomes an anonymous namespace (' ').

Back Reference
Decimal digits 0 to 9 refer to the first through 10th shown name fragments. Referred name fragments can be normal name fragments or name fragments with template arguments. For example, in, 0 refers to  , and 1 (not 2) refers to.

Generally, the back reference table is kept during the entire mangling process. This means you can use a back reference to the function name in the function arguments (which appear after the function name). However, in the template argument list, the back reference table is separately created.

For example, assume. In, 0 refers to  , 1 refers to  , and 2 refers to. This relation doesn't change wherever it appears.

Encoded Number
In name mangling, sometimes numbers must be represented (e.g. array indices). There are simple rules for this:
 * to  represents numbers 1 to 10.
 * represents a hexadecimal number, where num consists of hexadecimal digits A (which means 0) to P (15). For example  means number 0x123, or 291 in decimal notation.
 * represents the number 0.
 * If allowed, the prefix  represents a minus sign. Note that both   and   represent number 0.

Data Type
The table below shows the various data type and modifiers. ^ Visible when function is passed to  operator. Uses pointer type syntax.

^ See Function section.

The code  represents   when it appears in as a return type or pointer type, otherwise it indicates a cointerface. The code  (meaning ellipsis) appears only at the end of an argument list.

Primitive & Extended Type
Primitive types are represented as one character, and extended types are represented as one character with a preceding.

Back Reference
Decimal digits  to   refer to the first through 10th shown type in the argument list. (This means return type cannot be a referent.) Back references can refer to any non-primitive type, including an extended type. Of course back references can refer to prefixed types such as, but cannot refer to prefixless types — say,   in.

With back references for names, in a template argument list the back reference table is separately created. The function argument list has no such scoping rule, though it can be confuseing sometimes. For example, assume  is the first shown non-primitive type. Then  refers to ,   refers to  , and finally   refers to 'function pointer'.

Type Modifier
A type modifier is used to make a pointer or reference. Type modifiers look like this:
 * Modifier type
 * Optional: Managed C++ property ( for ,   for  )
 * CV-class modifier
 * Optional: Array property (not for functions)
 * Prefix Y
 * Encoded unsigned number of dimensions
 * Array indices as encoded unsigned numbers, one for each dimension
 * Referred type info (see below)

There are ten types of type modifier:

For normal types, referred type info is data type. For functions, it looks like the following. (It depends on the CV-class modifier)
 * Conditional: CV-class modifier, if member function
 * Function property

Complex Type (union, struct, class, coclass, cointerface)
Complex types look like this:
 * Kind of complex type (, ,  , ...)
 * Qualification without a basic name

Enumerated Type (enum)
An enumerated type starts with the prefix. It looks like this:
 * Prefix
 * Real type for enum
 * Qualification without basic name

The real type for an enum is represented as follows:

Note that in modern versions of Visual Studio, it will usually (if not always) generate enum symbols with a type symbol of, regardless of the real underlying type. Note that this doesn't affect the underlying type in any way, but appears to be for the sake of compiler simplicity.

Array
An array (not pointer to array) starts with the prefix. It looks like this:
 * Prefix
 * CV-class modifier
 * Data type within array

You can use multi-dimensional array like, but only the outermost CV-class modifier is affected. (In this case  means , not  )

Template Parameter
Template parameters are used to represent type and non-type template arguments. They can be used only in a template argument list.

The table below is a list of known template parameters. a, b, c represent encoded signed numbers, and x, y, z represent encoded unsigned numbers.

 ^ Pointer to member variable v in X is represented as the integer

 ^ The pointer syntax is also used for lvalue references and pointers to member functions.

Argument List
An argument list is a sequence of data types. The list can be one of the following:
 * (means, also terminating list)
 * arg1 arg2 ... argN  (meaning a normal list of data types. Note that N can be zero)
 * arg1 arg2 ... argN  (meaning a list with trailing ellipsis)

Template Argument List
A template argument list is the same as an argument list, except that template parameters can be used.

CV-class Modifier
The following table shows CV-class modifiers. CV-class modifier can have zero or more prefixes: Modifiers have trailing parameters as follows:
 * Conditional: Qualification without basic name, if member
 * Conditional: CV-class modifier of function, if member function
 * Conditional: __based property, if used

A CV-class modifier is usually used in reference/pointer types, but it is also used in other places with some restrictions:
 * Modifier of function: can only have const, volatile attribute, optionally with prefixes.
 * Modifier of data: cannot have function property.

__based Property
__based property represents Microsoft's __based attribute extension to C++. This property can be one of the following:
 * (means )
 * name (means, where name is a qualification without a basic name)
 * (means no )

Function Property
A function property represents the prototype of a function. It looks like this:
 * Calling convention of function
 * Data type of returned value, or  for
 * Argument list
 * throw attribute

The following table shows calling conventions of functions:

The argument list for the  attribute is the same as any other argument list, but if this list is , it means there is no   attribute. If you want to represent  you have to use   to terminate the list.

Function
Typical type information in a function name looks like this:
 * Optional: Prefix  (means function is managed, either as Managed C++ or C++/CLI)
 * Optional: Prefix  (means __based property is used)
 * Access level and function type
 * Conditional: __based property, if used
 * Conditional: adjustor property (as encoded unsigned number), if thunk function
 * Conditional: CV-class modifier of function, if non-static member function
 * Function property

The table below shows codes for access level and function type: This kind of thunk function is always virtual, and used to represent the logical  adjustor property, which means an offset to the true   value in some multiple inheritance situations.

Data
Type information in a data name looks like this:
 * Access level
 * Data type
 * CV-class modifier

The table below shows codes for access level: The CV-class modifier should be appropriate for data (not a 'function' modifier).

Thunk Function
There are several kinds of thunk function.