abi.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
               "http://www.w3.org/TR/html4/strict.dtd">
<HTML>

<HEAD>
<title>Itanium C++ ABI</title>

<link rel=stylesheet href=code.css type="text/css">

</HEAD>

<BODY>

<hr />
<h1>Itanium C++ ABI</h1>
<p> <hr> <p>

<h2> Contents </h2>

<ul>
<li><a href="#acknowledgements">Acknowledgements</a></li>
<li> <a href=#intro> Chapter 1: Introduction </a>
  <ul>
  <li> <a href=#definitions>	1.1 Definitions </a>
  <li> <a href=#limits>		1.2 Limits </a>
  <li> <a href=#namespace>	1.3 Namespace and Header </a>
  <li> <a href=#scope>		1.4 Scope of This ABI </a>
  <li> <a href=#docs>		1.5 Base Documents </a>
  </ul>
<li> <a href=#layout> Chapter 2: Data Layout </a>
  <ul>
  <li> <a href=#general>	2.1 General </a>
  <li> <a href=#pod>		2.2 POD Data Types </a>
  <li> <a href=#member-pointers> 2.3 Member Pointers </a>
  <li> <a href=#class-types>	2.4 Non-POD Class Types </a>
  <li> <a href=#vtable>		2.5 Virtual Table Layout </a>
  <li> <a href=#vtable-ctor> 2.6 Virtual Tables During Object Construction </a>
  <li> <a href=#array-cookies>	2.7 Array Operator <code>new</code> Cookies </a>
  <li> <a href=#guards>		2.8 Initialization Guard Variables </a>
  <li> <a href=#rtti>		2.9 Run-Time Type Information (RTTI) </a>
  </ul>
<li> <a href=#calls> Chapter 3: Code Emission and APIs </a>
  <ul>
  <li> <a href=#functions>   3.1 Functions</a>
  <li> <a href=#vcall>       3.2 Virtual Calls</a>
  <li> <a href=#obj-ctor>    3.3 Construction and Destruction APIs</a>
  <li> <a href=#demangler>   3.4 Demangler API</a>
  </ul>
<li> <a href=abi-eh.html> Chapter 4: Exception Handling </a>
<li> <a href=#linkage> Chapter 5: Linkage and Object Files </a>
  <ul>
  <li> <a href=#mangling>	5.1 External Names (a.k.a. Mangling)</a>
  <li> <a href=#vague>		5.2 Vague Linkage </a>
  <li> <a href=#unwind>		5.3 Unwind Table Location </a>
  </ul>
<li> <a href=#revisions> Appendix R: Revision History</a>
</ul>

<p> <hr> <p>
<a name="acknowledgements">
<h2><a href="#acknowledgements"> Acknowledgements</a></h2>
<p> <hr> <p>

<p>This document was originally developed jointly by an informal
industry coalition consisting of (in alphabetical order) CodeSourcery,
Compaq, EDG, HP, IBM, Intel, Red Hat, and SGI.  Additional contributions
were provided by a variety of individuals.  It is now developed as an
open-source project with contributions from a variety of individuals
and companies.</p>

<p> <hr> <p>
<a name="intro">
<h2><a href="#intro"> Chapter 1: Introduction </a></h2>
<p> <hr> <p>

In this document, we specify the Application Binary Interface (ABI)
for C++ programs: that is, the object code interfaces between different
user-provided C++ program fragments and between those fragments and
the implementation-provided runtime and libraries.  This includes the
memory layout for C++ data objects, including both predefined and
user-defined data types, as well as internal compiler generated
objects such as virtual tables.  It also includes function calling
interfaces, exception handling interfaces, global naming, and various
object code conventions.

<p>
In general, this document is meant to serve as a generic specification
which can be used by C++ implementations on a variety of platforms.
It does this by layering on top of a platform's base C ABI.  However,
it was originally written for the Itanium architecture, and some parts
still directly make Itanium-specific or 64-bit-specific assumptions.
There is an ongoing project to restate the entire C++ ABI specification
in terms of portable C concepts that are defined in the C ABI.  In
the meantime, it is usually straightforward to recognize these
unportable assumptions and translate them appropriately, e.g. by
replacing a 64-bit pointer with a 32-bit pointer.

<p>
This document is not an authoritative definition of the C++ ABI for
any particular platform.  Platform vendors retain the ultimate power
to define the C++ ABI for their platform.  Platforms using this ABI
for C++ should declare that they do so, either unmodified or with a
certain set of changes.

<p>
While this ABI has generally stood up well, there are some parts of it
that are now seen as mistakes.  This document includes several
recommendations for platforms adopting this ABI with no need to
interoperate with existing C++ object code.  These recommendations
appear as follows:

<blockquote>
  <span class="future-abi">Recommendation for new platforms: consider
  forbidding the use of function templates on your platform so that
  the ABI can remove these expression-mangling rules.</span>
</blockquote>

<p>
Platforms adopting any of these recommendations should describe the
exact changes they've made in their platform ABI documentation,
as the set of recommendations in this document may change over time.

<p> <hr> <p>
<a name="definitions">
<h3><a href="#definitions"> 1.1 Definitions </a></h3>

<p>
The descriptions below make use of the following definitions:

<dl>

<p>
<dt> <i>alignment</i> of a type T (or object X)</dt>
<dd>
A value A such that any object X of type T has an address satisfying
the constraint that &X modulo A == 0.

<p>
<dt> <i>base class</i> of a class T</dt>
<dd>
When this document refers to base classes of a class T,
unless otherwise specified,
it means T itself as well as all of the classes from which it is derived,
directly or indirectly, virtually or non-virtually.
We use the term&nbsp; <i>proper base class</i>
to exclude T itself from the list.

<p>
<dt> <i>base object destructor</i> of a class T</dt>
<dd>
A function that runs the destructors for non-static data members of T and
non-virtual direct base classes of T.

<p>
<dt> <i>basic ABI properties</i> of a type T</dt>
<dd>
The basic representational properties of a type decided by the base C ABI,
including its size, its alignment, its treatment by calling conventions,
and the representation of pointers to it.

<p>
<dt> <i>complete object destructor</i> of a class T</dt>
<dd>
A function that, in addition to the actions required of a base
object destructor, runs the destructors for the virtual base classes of T.

<p>
<dt> <i>deleting destructor</i> of a class T</dt>
<dd>
A function that, in addition to the actions required of a complete
object destructor, calls the appropriate deallocation function
(i.e,. <code>operator delete</code>) for T.

<p>
<dt> <i>direct base class order</i> </dt>
<dd>
When the direct base classes of a class are viewed as an ordered set,
the order assumed is the order declared, left-to-right.

<p>
<dt> <i>diamond-shaped inheritance</i> </dt>
<dd>
A class has diamond-shaped inheritance iff it has a virtual base class
that can be reached by distinct inheritance graph paths through
more than one direct base.

<p>
<dt> <i>dynamic class</i> </dt>
<dd>
A class requiring a virtual table pointer
(because it or its bases have one or more virtual member functions or
virtual base classes).

<p>
<dt> <i>empty class</i> </dt>
<dd>
A class with no non-static data members other than empty data members,
no unnamed bit-fields other than zero-width bit-fields,
no virtual functions, no virtual base classes,
and no non-empty non-virtual proper base classes.

<p>
<dt> <i>empty data member</i> </dt>
<dd>
A potentially-overlapping non-static data member of empty class type.

<p>
<dt> <i>inheritance graph</i> </dt>
<dd>
A graph with nodes representing a class and all of its subobjects,
and arcs connecting each node with its direct bases.

<p>
<dt> <i>inheritance graph order</i> </dt>
<dd>
The ordering on a class object and all its subobjects obtained
by a depth-first traversal of its inheritance graph,
from the most-derived class object to base objects,
where:

<ul>
<p>
<li> No node is visited more than once.
(So, a virtual base subobject, and all of its base subobjects,
will be visited only once.)

<p>
<li>
The subobjects of a node are visited in the order in which they
were declared.
(So, given&nbsp; <code>class A : public B, public C</code>,
A is walked first,
then B and its subobjects,
and then C and its subobjects.)
</ul>

<p>
Note that the traversal may be preorder or postorder.
Unless otherwise specified,
preorder (derived classes before their bases) is intended.

<p>
<a name="instantiation-dependent"></a>
<dt> <i>instantiation-dependent</i> </dt>
<dd>
An expression is <i>instantiation-dependent</i> if it is type-dependent or value-dependent,
or it has a subexpression that is type-dependent or value-dependent.  For example, if
<code>p</code> is a type-dependent identifier, the expression <code>sizeof(sizeof(p))</code>
is neither type-dependent, nor value-dependent, but it is instantiation-dependent (and could
turn out to be invalid if after substitution of template arguments <code>p</code> turns out to
have an incomplete type).

Similarly, a type expressed in source code is <i>instantiation-dependent</i> if the source
form includes an <i>instantiation-dependent</i> expression.  For example, the type form
<code>double[sizeof(sizeof(p))]</code> (with <code>p</code> a type dependent identifier)
is instantiation-dependent.

<p>
<dt> <i>morally virtual</i> </dt>
<dd>
A subobject X is a <i>morally virtual</i> base of Y if X is either a
virtual base of Y, or the direct or indirect base of a virtual base of
Y.

<p>
<dt> <i>nearly empty class</i> </dt>
<dd>
A class that contains a virtual pointer, but no other data except
(possibly) virtual bases.  In particular, it:
<ul>
<li> has no non-static data members and no non-zero-width unnamed bit-fields,
<li> has no direct base classes that are not either empty, nearly empty,
     or virtual,
<li> has at most one non-virtual, nearly empty direct base class, and
<li> has no proper base class that is empty, not morally virtual, and
     at an offset other than zero.
</ul>
Such classes may be primary base classes even if virtual,
sharing a virtual pointer with the derived class.

<p>
<a name="non-trivial">
<dt> <i>non-trivial for the purposes of calls</i><dt>
<dd>
<p>A type is considered non-trivial for the purposes of calls if:
<ul>
<li>it has a non-trivial copy constructor, move constructor, or destructor, or
<li>all of its copy and move constructors are deleted.
</ul>
</p>

<p>This definition, as applied to class types, is intended to be the
complement of the definition in [class.temporary]p3 of types for which
an extra temporary is allowed when passing or returning a type.  A type
which is trivial for the purposes of the ABI will be passed and returned
according to the rules of the base C ABI, e.g. in registers; often
this has the effect of performing a trivial copy of the type.
</p>
</dd>

<p>
<a name="POD" />
<dt> <i>POD for the purpose of layout</i><dt>
<dd>
<p>
In general, a type is considered a POD for the purposes of layout if
it is a POD type (in the sense of ISO C++
<span class=cxxref>[basic.types]</span>). However, a
type is not considered to be a POD for the purpose of layout if it is:
<ul>
<li>a POD-struct or POD-union (in the sense of ISO C++
<span class=cxxref>[class]</span>) with a
bit-field whose declared width is wider than the declared type
of the bit-field, or
<li>an array type whose element type is not a POD for the purpose of layout, or
<li>a POD-struct with one or more potentially-overlapping non-static
data members.
</ul>
Where references to the ISO C++ are made in this paragraph, the Technical
Corrigendum 1 version of the standard is intended.
</p>

<p>
<img src="warning.gif" alt="<b>NOTE</b>:">
There have been multiple published revisions to the ISO C++ standard,
and each one has included a different definition of POD.  To ensure
interoperation of code compiled according to different revisions of
the standard, it is necessary to settle on a single definition for a
platform.  A platform vendor may choose to follow a different revision
of the standard, but by default, the definition of POD under this ABI
is the definition from the 2003 revision (TC1).
</p>

<p>
Being tied to the TC1 definition of POD does not prevent compilers
from being fully compliant with later revisions.  This ABI uses the
definition of POD only to decide whether to allocate objects in the
tail-padding of a base-class subobject.  While the standards have
broadened the definition of POD over time, they have also forbidden
the programmer from directly reading or writing the underlying bytes
of a base-class subobject with, say, <tt>memcpy</tt>.  Therefore,
even in the most conservative interpretation, implementations may
freely allocate objects in the tail padding of any class which would
not have been POD in C++98.  This ABI is in compliance with that.
</p>
</dd>

<p>
<dt> <i>potentially-overlapping subobject</i> </dt>
<dd>
A base class subobject or a non-static data member declared with
the <tt>[[no_unique_address]]</tt> attribute.

<p>
<dt> <i>primary base class</i> </dt> <dd> For a dynamic class, the
unique base class (if any) with which it shares the virtual pointer at
offset 0.

<p>
<dt> <i>secondary virtual table</i> </dt>
<dd>
The instance of a virtual table for a base class
that is embedded in the virtual table of a class derived from it.

<p>
<dt> <i>thunk</i> </dt>
<dd>
A segment of code associated (in this ABI) with a target function,
which is called instead of the target function for the purpose of
modifying parameters (e.g. <code>this</code>)
or other parts of the environment
before transferring control to the target function,
and possibly making further modifications after its return.
A thunk may contain as little as an instruction to be executed prior to
falling through to an immediately following target function,
or it may be a full function with its own stack frame that does
a full call to the target function.

<p>
<dt> <i>vague linkage</i> </dt>
<dd>
The treatment of entities --
e.g. inline functions, templates, virtual tables --
with external linkage that can be
defined in multiple translation units,
while the ODR requires that the program
behave as if there were only a single definition.

<p>
<dt> <i>virtual table</i> (or <i>vtable</i>) </dt>
<dd>
A dynamic class has an associated table
(often several instances, but not one per object)
which contains information about its dynamic attributes,
e.g. virtual function pointers, virtual base class offsets, etc.

<p>
<dt> <i>virtual table group</i> </dt>
<dd>
The primary virtual table for a class along with all of the associated
secondary virtual tables for its proper base classes.

</dl>

<p> <hr> <p>
<a name="limits">
<h3><a href="#limits"> 1.2 Limits </a></h3>

<p>
Various representations specified by this ABI impose limitations on
conforming user programs.
These include, for the 64-bit Itanium ABI:

<ul>
<p>
<li>
The offset of a non-virtual base subobject in the full object containing
it must be representable by a 56-bit signed integer
(due to RTTI implementation).
This implies a practical limit of 2**55 bytes on the size of a class.

</ul>


<p> <hr> <p>
<a name="namespace">
<h3><a href="#namespace"> 1.3 Namespace and Header </a></h3>

<p>
This ABI specifies a number of type and function APIs supplemental
to those required by the ISO C++ Standard.
A header file named <code>cxxabi.h</code> will be provided by
implementations that declares these APIs.
The reference header file included with this ABI definition
shall be the authoritative definition of the APIs.

<p>
These APIs will be placed in a namespace <code>__cxxabiv1</code>.
The header file will also declare a namespace alias <code>abi</code>
for <code>__cxxabiv1</code>.
It is expected that users will use the alias,
and the remainder of the ABI specification will use it as well.

<p>
In general,
API objects defined as part of this ABI are assumed to be extern "C++".
However, some (many?) are specified to be extern "C" if they:
<ul>
<li> are expected to be called by users from C code,
     e.g. <code>longjmp_unwind</code>; or
<li> are expected to be called only implicitly by compiled code,
     and are likely to be implemented in C.
</ul>


<p> <hr> <p>
<a name="scope">
<h3><a href="#scope"> 1.4 Scope of This ABI </a></h3>

<a name="scope-library">
<h3><a href="#scope-library"> 1.4.1 Runtime Libraries </a></h3>

<p>
The objective of a full ABI is to allow arbitrary mixing of object
files produced by conforming implementations,
by fully specifying the <b>binary interface</b> of application programs.
We do not fully achieve this objective.

<p>
There are two principal reasons for this:

<ol type=I>
<p>
<li>
We start from the Itanium processor-specific ABI as the standard for the
underlying C interfaces.
At this time, however,
the psABI does not attempt to specify the supported C library interfaces.

<p>
<li>
More fundamental is the definition of the Standard C++ Library.
As the standard interface makes heavy use of templates,
most user object files will end up with embedded template
instantiations.
Vendors are allowed to use helper functions and data in their
implementations of these templates,
and quite reasonably do so,
with the result that a typical user object file will contain references
to such helper objects specific to the implementation where compiled.
We have not attempted to constrain the interface at this level,
because we do not consider doing so feasible at this time.
</ol>

<p>
Notwithstanding these problems,
because this ABI does completely specify the data model
and certain library interfaces that inherently interact between objects
(e.g. construction, destruction, and exceptions),
it is our intent that interoperation of object files produced by
different compilers be possible in the following cases:

<ul>
<p>
<li>
A program which uses only the standalone standard library interfaces
(Chapter 18) does not depend on the problematic template features.

<p>
<li>
Since the standard library headers for an implementation presumably
match the interfaces of the standard library on that implementation,
a program compiled with the target system's headers,
even if a mixture of compilers is used,
should function properly on that system.

</ul>

<p>
Even these cases can fail if the compiler makes use of
implementation-defined library interfaces to implement runtime
functionality without explicit user reference,
e.g. a software divide function.
We can distinguish between:
<ul>
<li> the standard support library,
    which provides interfaces required by the C++ Standard Library
    specification and the vendor header files required for it,
    as well as interfaces required by this ABI; and
<p>
<li> the implicit compiler support library,
    which provides other interfaces implicitly assumed by the compiler
    and used to implement either standard features or extensions.
</ul>

<p>
An implementation shall place its standard support library in a DSO
named <code>libcxa.so</code> on Itanium systems,
or in auxiliary DSOs automatically loaded by it.
It shall place implicit compiler support
in a library separate from the standard support library,
with any external names chosen to avoid conflicts between vendors
(e.g. by including a vendor identifier as part of the names).
This allows a program to function properly if linked with the
target's standard support library and the implicit compiler support
libraries from any implementations used to build components.


<a name="scope-templates">
<h3><a href="#scope-templates"> 1.4.2 Export Templates </a></h3>

<p>
This ABI does not specify the treatment of export templates,
as there are no working implementations to serve as models at this time.
We hope to address this weakness in the future when implementation
experience is available.

<p> <hr> <p>
<a name="docs">
<h3><a href="#docs"> 1.5 Base Documents </a></h3>

<p>
A number of other documents provide a basis on which this ABI is built,
and are occasionally referenced herein:

<ul>
<p>
<li> [gABI]
The <b>System V Application Binary Interface</b>,
otherwise known as the <i>Generic ABI</i>.
This document describes processor-independent object file formats
and binary software interfaces for C under Unix.
A somewhat out-of-date version is available from the SCO website,
<a href=http://www.caldera.com/developers/devspecs/>
http://www.caldera.com/developers/devspecs/</a>.
A newer version, produced in conjunction with the next document,
should be released in the future.
Included by reference in this ABI.

<p>
<li> [psABI]
The Intel <b>Unix System V Application Binary Interface,
Itanium Processor Supplement</b>.
This document describes Itanium processor-specific object file formats
and binary software interfaces, primarily for C, under Unix.
Available from the Intel Itanium software developer website,
<a href="http://www.intel.com/design/itanium/downloads/245370.htm">
http://www.intel.com/design/itanium/downloads/245370.htm</a>.
Included by reference in this ABI.

<p>
<li> [SWCONV]
The Intel <b>Itanium Software Conventions and Runtime Architecture Guide</b>.
This document describes Itanium processor-specific binary software interfaces,
notably including register usage, subprogram calling conventions, and
stack unwind facilities, under all systems.
Available from the Intel Itanium software developer website,
<a href="https://www.intel.com/content/dam/www/public/us/en/documents/guides/itanium-software-runtime-architecture-guide.pdf">
https://www.intel.com/content/dam/www/public/us/en/documents/guides/itanium-software-runtime-architecture-guide.pdf</a>.
Included by reference in this ABI.

<p>
<li> [ABI-EH]
The <a href=abi-eh.html><b>C++ ABI for Itanium: Exception Handling</b></a>.
Its Level II is considered an integral part of this document (Chapter 4).
It also contains the base specification of unwind support for [psABI].

<p>
<li> [C++FDIS]
The <b>Final Draft International Standard, Programming Language C++</b>,
ISO/IEC FDIS 14882:1998(E).
References herein to the "C++ Standard," or to just the "Standard,"
are to this document.

</ul>


<p> <hr> <p>
<a name="layout">
<h2><a href="#layout"> Chapter 2: Data Layout </a></h2>
<p> <hr> <p>


<a name="general">
<h3><a href="#general"> 2.1 General </a></h3>

<p>
In what follows, we define the memory layout for C++ data objects.
Specifically, for each type, we specify the following information about
an object O of that type:
<ul>
<li> the <i>size</i> of an object, <i>sizeof</i>(O);
<li> the <i>alignment</i> of an object, <i>align</i>(O); and
<li> the <i>offset</i> within O, <i>offset</i>(C),
     of each data component C, i.e. base or member.
</ul>

<p> For purposes internal to the specification,
we also specify:

<ul>
<li> <i>dsize</i>(O):
the <i>data size</i> of an object, which is the size of O without tail
padding.

<p>
<li> <i>nvsize</i>(O):
the <i>non-virtual size</i> of an object, which is the size of O
without virtual bases.

<p>
<li> <i>nvalign</i>(O):
the <i>non-virtual alignment</i> of an object, which is the alignment of O
without virtual bases.

</ul>


<p> <hr> <p>
<a name="pod">
<h3><a href="#pod"> 2.2 POD Data Types </a></h3>

<p>
The size and alignment of a type which is a <a href="#POD">POD for the
purpose of layout<a> is as specified by the base C ABI, with the
following provisos:
</p>

<ul>
<li>If the base ABI specifies rules for the C99 type <code>_Bool</code>,
then <code>bool</code> follows those rules.  Otherwise, it has size
and alignment 1.</li>

<li>If the base ABI does not specify rules for empty classes, then an
empty class has size and alignment 1.</li>

<li>The types <code>T &</code> and <code>T &&</code> are treated
exactly like the pointer type <code>T *</code>.</li>

<li>A member pointer type is treated exactly as if it were the C type
<a href="#member-pointers">described below</a>.</li>
</ul>

<p>
The <i>dsize</i>, <i>nvsize</i>, and <i>nvalign</i> of these types are
defined to be their ordinary size and alignment.  These properties
only matter for non-empty class types that are used as base classes.
We ignore tail padding for PODs because an early version of the
standard did not allow us to use it for anything else and because it
sometimes permits faster copying of the type.
</p>

<p> <hr> <p>
<a name="member-pointers"></a>
<h3><a href="#member-pointers"> 2.3 Member Pointers </a></h3>

<a name="data-member-pointers"></a>
<h4><a href="#data-member-pointers"> 2.3.1 Data Member Pointers </a></h4>

<p>
The basic ABI properties of data member pointer types are those
of <code>ptrdiff_t</code>.

<p>
A data member pointer is represented as the data member's offset in bytes
from the address point of an object of the base type, as a
<code>ptrdiff_t</code>.

<p>
A null data member pointer is represented as an offset of <code>-1</code>.
Unfortunately, it is possible to generate a data member pointer with an
offset of <code>-1</code> using explicit derived-to-base conversions.
If this is done, implementations following this ABI may misbehave.
<span class="future-abi">Recommendation for new platforms: consider using
a different representation for data member pointers, such as left-shifting
the offset by one and using a non-zero low bit to indicate a non-null
value.</span>

<p>
Note that by <code>[dcl.init]</code>, "zero initialization" of a data
member pointer object stores a null pointer value into it.  Under this
representation, that value has a non-zero bit representation.  On most
modern platforms, data member pointers are the only type with this
property.

<p>
Base-to-derived and derived-to-base conversions of a non-null data member
pointer can be performed by adding or subtracting (respectively) the static
offset of the base within the derived class.  The C++ standard does not
permit base-to-derived and derived-to-base conversions of member pointers
to cross a <code>virtual</code> base relationship, and so a static offset
is always known.

<a name="member-function-pointers"></a>
<h4><a href="#member-function-pointers"> 2.3.2 Member Function Pointers </a></h4>

<p>
Several different representions of member function pointers are in use.
The standard representation relies on several assumptions about the
platform, such as that the low bit of a function pointer to a non-virtual
member function is always zero.  For platforms where this is not reasonable
to guarantee, an alternate representation must be used.  One such
representation, used on the 32-bit ARM architecture, is also described here.

<p>
In all representations, the basic ABI properties of member function
pointer types are those of the following class, where <code>fnptr_t</code>
is the appropriate function-pointer type for a member function of this type:

<pre>
  struct {
    fnptr_t ptr;
    ptrdiff_t adj;
  };
</pre>

<p>
A member function pointer for a non-virtual member function is represented
with <code>ptr</code> set to a pointer to the function, using the base
ABI's representation of function pointers.

<p>
In the standard representation, a member function pointer for a virtual
function is represented with <code>ptr</code> set to 1 plus the function's
v-table entry offset (in bytes), converted to a function pointer as if by
<code>reinterpret_cast&lt;fnptr_t&gt;(uintfnptr_t(1 + offset))</code>,
where <code>uintfnptr_t</code> is an unsigned integer of the same
size as <code>fnptr_t</code>.

<p>
In both of these cases, <code>adj</code> stores the offset (in bytes)
which must be added to the <code>this</code> pointer before the call.

<p>
In the standard representation, a null member function pointer is
represented with <code>ptr</code> set to a null pointer.  The value
of <code>adj</code> is unspecified for null member function pointers.

<p>
The standard representation relies on some assumptions which are
true for most platforms:

<ul compact>
  <li>The low bit of a function pointer to a non-static member function
    is never set.  On most platforms, this is either always true or
    can be made true at little cost.  For example, on platforms where
    a function pointer is just the address of the first instruction in the
    function, the implementation can ensure that this addresss is always
    sufficiently aligned to make the low bit zero for non-static member
    functions; often this is required by the underlying architecture.</li>

  <li>A null function pointer can be distinguished from a virtual
    offset value.  On most platforms, this is always true because the
    null function pointer is the zero value.</li>

  <li>The offset to a v-table entry is never odd.  On most platforms,
    the size of a v-table entry is even because the architecture is
    byte-addressed and pointers are even-sized.</li>

  <li>A virtual call can be performed knowing only the addresss of a
    v-table entry and the type of the virtual function.  On most
    platforms, a v-table entry is equivalent to a function pointer,
    and the type of that function pointer can be determined from the
    member pointer type.</li>
</ul>

<p>
However, there are exceptions.  For example, on the 32-bit ARM
architecture, the low bit of a function pointer determines whether
the function begins in THUMB mode.  Such platforms must use an
alternate representation.

<p>
In the 32-bit ARM representation, the <code>this</code>-adjustment
stored in <code>adj</code> is left-shifted by one, and the low bit
of <code>adj</code> indicates whether <code>ptr</code> is a function
pointer (including null) or the offset of a v-table entry.  A virtual
member function pointer sets <code>ptr</code> to the v-table entry
offset as if by
<code>reinterpret_cast&lt;fnptr_t&gt;(uintfnptr_t(offset))</code>.
A null member function pointer sets <code>ptr</code> to a null
function pointer and must ensure that the low bit of <code>adj</code>
is clear; the upper bits of <code>adj</code> remain unspecified.

<p>A member function pointer is null if <code>ptr</code> is equal
to a null function pointer and (only when using the 32-bit ARM
representation) the low bit of <code>adj</code> is clear.

<p>Two member function pointers are equal if they are both null or
if their corresponding values of <code>ptr</code> and <code>adj</code>
are equal.  Note that the C++ standard does not require member pointers
to the same virtual member function to compare equal; implementations
using this ABI will do so, but only if the member pointers are built
using the same v-table offset, which they may not be in the presence
of multiple inheritance or overrides with covariant return types.

<p>
Base-to-derived and derived-to-base conversions of a member function
pointer can be performed by adding or subtracting (respectively) the
static offset of the base within the derived class to the stored
<code>this</code>-adjustment value.  In the standard representation,
this simply means adding it to <code>adj</code>; in the 32-bit ARM
representation, the addend must be left-shifted by one.  Because the
adjustment does not factor into whether a member function pointer is
null, this addition can be done unconditionally when performing a
conversion.

<p>
A call is performed as follows:

<ol>
  <li>Add the stored adjustment to the <code>this</code> address.</li>
  <li>If the member pointer stores a v-table entry offset, load the
    v-table from the adjusted <code>this</code> address and call
    the v-table entry at the stored offset.</li>
  <li>Otherwise, call the stored function pointer.</li>
</ol>

<p> <hr> <p>
<a name="class-types">
<h3><a href="#class-types"> 2.4 Non-POD Class Types </a></h3>

For a class type C which is not a <a href="#POD">POD for the purpose
of layout</a>, assume that all component types (i.e. proper base
classes and non-static data member types) have been laid out, defining
size, data size, non-virtual size, alignment, and non-virtual
alignment.

(See the description of these terms in
<a href=#general><b>General</b></a> above.)
Layout (of type C) is done using the following procedure.

<ol type=I>
<p>
<li> <h5> Initialization </h5>
  <ol type=1>
  <p>
  <li> Initialize sizeof(C) to zero, align(C) to one, dsize(C) to zero.

  <p>
  <li> If C is a dynamic class type:
      <ol type=a>
      <p>
      <li> Identify all virtual base classes, direct or indirect,
	   that are primary base classes for some other direct or indirect
	   base class.
	   Call these <i>indirect primary base classes</i>.

      <p>
      <li> If C has a dynamic base class,
	   attempt to choose a primary base class B.
	   It is the first (in direct base class order)
	   non-virtual dynamic base class, if one exists.
	   Otherwise, it is a nearly empty virtual base class,
	   the first one in (preorder) inheritance graph order which
	   is not an indirect primary base class if any exist,
	   or just the first one if they are all indirect primaries.

      <p>
      <li> If C has no primary base class, allocate the virtual table
           pointer for C at offset zero, and set sizeof(C), align(C),
           and dsize(C) to the appropriate values for a pointer (all 8
           bytes for Itanium 64-bit ABI).
      </ol>
  </ol>

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
Case (2b) above is now considered to be an error in the design.  The
use of the first indirect primary base class as the derived class'
primary base does not save any space in the object, and will cause
some duplication of virtual function pointers in the additional copy
of the base classes virtual table.

<p>
The benefit is that using the derived class virtual pointer as the base
class virtual pointer will often save a load,
and no adjustment to the <code>this</code> pointer will be required for
calls to its virtual functions.

<p> 
It was thought that 2b would allow the compiler to avoid
adjusting <code>this</code> in some cases, but this was incorrect, as
the <a href=#vcall>virtual function call algorithm</a> requires that
the function be looked up through a pointer to a class that defines
the function, not one that just inherits it.  Removing that
requirement would not be a good idea, as there would then no longer be
a way to emit all thunks with the functions they jump to.  For
instance, consider this example:
<blockquote><code><pre>
struct A { virtual void f(); };
struct B : virtual public A { int i; };
struct C : virtual public A { int j; };
struct D : public B, public C {};
</pre></code></blockquote>

<p>
When B and C are declared, A is a primary base in each case, so although
vcall offsets are allocated in the A-in-B and A-in-C vtables, no
<code>this</code> adjustment is required and no thunk is generated.
However, inside D objects, A is no longer a primary base of C, so if we
allowed calls to <code>C::f()</code> to use the copy of A's vtable in the C
subobject, we would need to adjust <code>this</code> from <code>C*</code>
to <code>B::A*</code>, which would require a third-party thunk.  Since we
require that a call to <code>C::f()</code> first convert to
<code>A*</code>, C-in-D's copy of A's vtable is never referenced, so this
is not necessary.
</i>

<p>
<li> <h5> Allocation of Members Other Than Virtual Bases </h5>
<p>
For each data component D (first the primary base of C, if any, then
the non-primary, non-virtual direct base classes in declaration order,
then the non-static data members and unnamed bit-fields in declaration
order), allocate as follows:

  <ol type=1>

  <p>
  <li> If D is a (possibly unnamed) bit-field whose declared type is
       <code>T</code> and whose declared width is <code>n</code> bits:

       <p>
       There are two cases depending on <code>sizeof(T)</code>
       and <code>n</code>:

       <ol type=a>
       <p>
       <li>
       If <code>sizeof(T)*8 >= n</code>,
       the bit-field is allocated as required by the base C ABI,
       subject to the constraint that a bit-field is never placed in the
       tail padding of a base class of C.

       <p>
       If dsize(C) > 0, and the byte at offset dsize(C) - 1 is
       partially filled by a bit-field, and that bit-field is also a
       data member declared in C (but not in one of C's proper base
       classes), the next available bits are the unfilled bits at
       offset dsize(C) - 1.  Otherwise, the next available bits are at
       offset dsize(C).
       
       <p>
       Update align(C) to max (align(C), align(T)).

       <p>
       <li>
       If <code>sizeof(T)*8 < n</code>,
       let T' be the largest integral POD type with
       <code>sizeof(T')*8 <= n</code>.
       The bit-field is allocated starting at the next offset aligned
       appropriately for T', with length n bits.
       The first <code>sizeof(T)*8</code> bits are used to hold the
       value of the bit-field,
       followed by <code>n - sizeof(T)*8</code> bits of padding.
	<p>
	Update align(C) to max (align(C), align(T')).
       </ol>

       <p>
       In either case,
       update dsize(C) to include the last byte
       containing (part of) the bit-field,
       and update sizeof(C) to max(sizeof(C),dsize(C)).

  <p>
  <li> If D is not an empty base class and D is not an empty data member:

	<p>
        Start at offset dsize(C),
	incremented if necessary for alignment
	to nvalign(D) for base classes or
	to align(D) for data members.
	Place D at this offset unless doing so would result in two
	components (direct or indirect) of the same type having the
	same offset.
	If such a component type conflict occurs,
	increment the candidate offset by nvalign(D)
	for base classes or by align(D) for data members
	and try again,
	repeating until success occurs
	(which will occur no later than sizeof(C) rounded up to the
	required alignment).

	<p>
	If D is a base class, this step allocates only its non-virtual
	part, i.e. excluding any direct or indirect virtual bases.

	<p>
	If D is a base class, update sizeof(C) to max (sizeof(C),
	offset(D)+nvsize(D)).
	Otherwise, if D is a potentially-overlapping data member,
	update sizeof(C) to max (sizeof(C), offset(D)+max (nvsize(D), dsize(D))).
	Otherwise, if D is a data member,
	update sizeof(C) to max (sizeof(C), offset(D)+sizeof(D)).

	<p>
	If D is a base class (not empty in this case),
	update dsize(C) to offset(D)+nvsize(D),
	and align(C) to max (align(C), nvalign(D)).
	If D is a potentially-overlapping data member,
	update dsize(C) to offset(D)+max (nvsize(D), dsize(D)),
	align(C) to max (align(C), align(D)).
	If D is any other data member,
	update dsize(C) to offset(D)+sizeof(D),
	align(C) to max (align(C), align(D)).
        </p>

  <p>
  <li> If D is an empty proper base class or an empty data member:

        <p>
	Its allocation is similar to case (2) above,
	except that additional candidate offsets are considered before
	starting at dsize(C).
	First, attempt to place D at offset zero.
	If unsuccessful (due to a component type conflict),
	proceed with attempts at dsize(C) as for non-empty bases and members.
	As for that case, if there is a type conflict at dsize(C)
	(with alignment updated as necessary),
	increment the candidate offset by nvalign(D),
	and try again,
	repeating until success occurs.

	<p>
	Once offset(D) has been chosen, update sizeof(C) to max (sizeof(C),
	offset(D)+sizeof(D)), and update align(C) to max (alignof(C),
	nvalign(D)) for a base class or max (alignof(C), align(D)) for
	a data member.  Since D is empty, no update of dsize(C) is needed.

  </ol>

  <p>
  After all such components have been allocated, set nvalign(C) =
  align(C) and nvsize(C) = sizeof(C).  The values of nvalign(C) and
  nvsize(C) will not change during virtual base allocation.  Note that
  nvsize(C) need not be a multiple of nvalign(C).

<p><a name="a17">
<li> <h5> Virtual Base Allocation </h5>
<p>

<p>
Finally allocate any direct or indirect virtual base classes
(except the primary base class or any indirect primary base classes)
as we did non-virtual base classes
in step II-2 (if not empty) or II-3 (if empty),
in inheritance graph order.
Update sizeof(C) to max (sizeof(C), offset(D)+nvsize(D)).
If non-empty, also update align(C) and dsize(C) as in II-2.

<p>
The primary base class has already been allocated in I-2b.  Any
indirect primary base class E of the current class C, i.e. one that
has been chosen as the primary base class of some other base class
(direct or indirect, virtual or non-virtual) of C, will be allocated
as part of that other base class, and is not allocated here.  If E is
a primary base class of more than one other base, the instance used as
its allocation in C shall be the first such in the inheritance graph
order.

<i>
<p>
Consider:
<pre><code>
  struct R { virtual void r (); };
  struct S { virtual void s (); };
  struct T : virtual public S { virtual void t (); };
  struct U : public R, virtual public T { virtual void u (); };

</code></pre>

R is the primary base class for U since it is the first direct
non-virtual dynamic base.
Then, since an inheritance-order walk of U is { U, R, T, S }
the T base is allocated next.
Since S is a primary base of T,
there is no need to allocate it separately.
However, given:

<pre><code>
  struct V : public R, virtual public S, virtual public T {
    virtual void v ();
  };

</code></pre>

the inheritance-order walk of V is { V, R, S, T }.
Nevertheless, although S is considered for allocation first as a virtual base,
it is not allocated separately because it is a primary base of T,
another base.
Thus sizeof (V) == sizeof (U),
and the full layout is equivalent to the C struct:
</i>

<pre><code>
  struct X {
    R r;
    T t;
  };

</code></pre>

<p>
<li> <h5> Finalization </h5>
<p>
For each potentially-overlapping non-static data member D of C,
update sizeof(C) to max (sizeof(C), offset(D)+sizeof(D)). Example:

<pre><code>
  struct alignas(16) A { ~A(); }; // dsize 0, nvsize 0, size 16
  struct B : A {}; // dsize 0, nvsize 16, size 16
  struct X : virtual A, virtual B {}; // dsize 8, nvsize 8, size 32
  struct Y { [[no_unique_address]] X x; char c; }; // dsize 9, nvsize 9, size 32
</code></pre>

<p>
Then, round sizeof(C) up to a non-zero multiple of align(C).  If C is a POD,
but not a POD for the purpose of layout, set dsize(C) = nvsize(C) = sizeof(C).

</ol>


<p> <hr> <p>
<a name="vtable">
<h3><a href="#vtable"> 2.5 Virtual Table Layout </a></h3>

<p>
<a name="vtable-general">
<h4><a href="#vtable-general"> 2.5.1 General </a></h4>

<p>
A <i>virtual table</i> (<i>vtable</i>) is a table of information used
to dispatch virtual functions,
to access virtual base class subobjects,
and to access information for runtime type identification (RTTI).
Each class that has virtual member functions or virtual bases
has an associated set of virtual tables.
There may be multiple virtual tables for a particular class,
if it is used as a base class for other classes.
However, the virtual table pointers within all the objects (instances)
of a particular most-derived class point to the same set of virtual tables.

<p>
A virtual table consists of a sequence of offsets, data pointers,
and function pointers, as well as structures composed of such items.
We will describe below the sequence of such items.
Their offsets within the virtual table are determined by that allocation
sequence and the natural ABI size and alignment,
just as a data struct would be.  In particular:
<ul>
<li> Offsets are of type <code>ptrdiff_t</code> unless otherwise stated.
<li> Data pointers have normal pointer size and alignment.
<li> On Itanium, function pointers are pairs: the function address followed
by the global pointer value that should be used when calling the
function, aligned as for a pointer.  On other
platforms, function pointers are represented as they would be in any
other context.
</ul>

<p>
In general, what we consider the address of a virtual table
(i.e. the address contained in objects pointing to a virtual table)
may not be the beginning of the virtual table.
We call it the <i>address point</i> of the virtual table.
The virtual table may therefore contain components at either positive or
negative offsets from its address point.

<p>
<a name="vtable-components">
<h4><a href="#vtable-components"> 2.5.2 Virtual Table Components and Order </a></h4>

<p>
This section describes the usage and relative order of various
components that may appear in virtual tables.
Precisely which components are present in various possible virtual
tables is specified in the next section.
If present, components are present in the order described,
except for the exceptions specified.

<ul>
<p>
<li>
<i>Virtual call (vcall) offsets</i> are used
to perform pointer adjustment for virtual functions
that are declared in a virtual base class or its subobjects
and overridden in a class derived from it.
These entries are allocated in the virtual table for the virtual base class
that is most immediately derived from the base class containing the
overridden virtual function declaration.
They are used
to find the necessary adjustment from the virtual base to the
derived class containing the overrider,
if any.
When a virtual function is invoked via a virtual base,
but has been overridden in a derived class,
the overriding function first adds a fixed offset to adjust the
<code>this</code> pointer to the virtual base,
and then adds the value contained at the vcall offset
in the virtual base to its <code>this</code> pointer
to get the address of the derived object where the function was overridden.
These values may be positive or negative.
These are first in the virtual table if present,
ordered as specified in categories 3 and 4 of
<a href="#vtable-construction">Section 2.5.3</a> below.

<p>
<li>
<a name="q1">
<i>Virtual Base (vbase) offsets</i> are used to access
the virtual bases of an object.
Such an entry is added to the derived class object address
(i.e. the address of its virtual table pointer)
to get the address of a virtual base class subobject.
Such an entry is required for each virtual base class.
The values can be positive or negative.

<br>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
However, in classes sharing a virtual table with a primary base class,
the vcall and vbase offsets added by the derived class all come before
the vcall and vbase offsets required by the base class,
so that the latter may be laid out as required by the base class
without regard to additions from the derived class(es).
</i>

<p>
<li>
The <i>offset to top</i> holds the displacement to the top of the object
from the location within the object of the virtual table pointer
that addresses this virtual table,
as a&nbsp; <code>ptrdiff_t</code>.
It is always present.
The offset provides a way to find the top of the object from any base
subobject with a virtual table pointer.
This is necessary for dynamic_cast&lt;void*&gt; in particular.

<br>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
In a complete object virtual table,
and therefore in all of its primary base virtual tables,
the value of this offset will be zero.
For the secondary virtual tables of other non-virtual bases,
and of many virtual bases,
it will be negative.
Only in some construction virtual tables will some virtual base virtual
tables have
positive offsets, due to a different ordering of the virtual bases in
the full object than in the subobject's standalone layout.
</i>

<p>
<li>
The <i>typeinfo pointer</i> points to the typeinfo object used for RTTI.
It is always present.
All entries in each of the virtual tables for a given class must point to the
same typeinfo object.
A correct implementation of typeinfo equality is to check pointer equality,
except for pointers (directly or indirectly) to incomplete types.
The typeinfo pointer is a valid pointer for polymorphic classes,
i.e. those with virtual functions,
and is zero for non-polymorphic classes.

<p>
<li>
The virtual table address point points here,
i.e. this is the virtual table address
contained in an object's virtual pointer.
This address must have the alignment required for pointers.

<p>
<li>
<i>Virtual function pointers</i> are used for virtual function dispatch.
Each pointer holds either the address of a virtual function of the class,
or the address of a secondary entry point that performs certain
adjustments before transferring control to a virtual function.

<p>
The form of a virtual function pointer is specified by the
processor-specific C++ ABI for the implementation.
In the specific case of 64-bit Itanium shared library builds,
a virtual function pointer entry contains a pair of components
(each 64 bits):
the value of the target GP value and the actual function address.
That is, rather than being a normal function pointer,
which points to such a two-component descriptor,
a virtual function pointer entry is the descriptor.

<p>
The order of the virtual function pointers in a virtual table is
the order of declaration of the corresponding member functions in the class.
If an implicitly-declared copy assignment operator, move assignment operator,
or destructor is virtual, it is treated as if it were declared at the end of
the class, in that order.
(Implicitly-declared assignment operators may be virtual if
a base class declares a virtual assignment operator
taking a reference to a derived class type.)

<p>
An entry is added for every virtual function in a class,
including deleted functions, unless:
<ul>
<li>the function is <tt>consteval</tt> or
<li>the function overrides a function from the primary base and
that override does not require a return-type adjustment.
</ul>

<p>
An override requires a return-type adjustment if
the return types are different and
have potentially incompatible representations.
C++ permits an override to differ in return type from the overridden function
only if both types are pointer-to-class or reference-to-class types and
the class type <tt>B</tt> in the overridden function is
an unambiguous base class of the class type <tt>D</tt> in the override.
For the purposes of vtable layout,
these types are considered to have potentially incompatible representations if:
<ul>
<li>
<tt>B</tt> is a morally virtual base of <tt>D</tt>
(even if <tt>D</tt> is <tt>final</tt> and
the offset of <tt>B</tt> within <tt>D</tt> is known to be zero) or
<li>
the (static) offset of <tt>B</tt> within <tt>D</tt> is non-zero.
</ul>

<p>
When a derived class and its primary base share a virtual table,
the virtual function entries introduced by the derived class follow
those for the primary base,
so that the layout of the primary base's embedded virtual table
is the same as that of its standalone virtual table.
In particular, if the derived class overrides a base class virtual
function with a different (covariant) return type,
the entry for the derived class comes after the primary base's
embedded virtual table in declaration order,
and is the entry used for calls from the derived class without adjustment.
The entry in the embedded primary virtual table points to a routine
that adjusts the result pointer before returning.

<p>
The entries for virtual destructors are actually pairs of entries.
The first destructor,
called the complete object destructor,
performs the destruction without calling delete() on the object.
The second destructor,
called the deleting destructor,
calls delete() after destroying the object.
Both destroy any virtual bases;
a separate, non-virtual function,
called the base object destructor,
performs destruction of the object but
not its virtual base subobjects, and does not call delete().

</ul>

<p>
Following the primary virtual table of a derived class are
<i>secondary virtual tables</i> for each of its proper base classes,
except any primary base(s) with which it shares its primary virtual table.
These are copies of the virtual tables for the respective base classes
(copies in the sense that they have the same layout,
though the fields may have different values).
We call the collection consisting of a primary virtual table along with all of
its secondary virtual tables a <i>virtual table group</i>.
The order in which they occur is the same as the order in which the
base class subobjects are considered for allocation in the derived object:

<ul>
<p>
<li>
First are the virtual tables of direct non-primary, non-virtual proper bases,
in the order declared,
including their secondary virtual tables for non-virtual bases in the order
they appear in the standalone virtual table group for the base.
(Thus the effect is that these virtual tables occur in inheritance graph order,
excluding primary bases and virtual bases.)

<p>
<li>
Then come the virtual base virtual tables,
also in inheritance graph order,
and again excluding primary bases
(which share virtual tables with the classes for which they are primary).
</ul>

<p>
This ABI does not make guarantees about the layout of other virtual
tables in a virtual table group relative to a virtual table pointer
in an object or a VTT. It guarantees only the layout of the
<a href="#mangling-special-vtables">global symbol</a> for that virtual table
group. It does not guarantee that the virtual table pointers actually
installed in an object or a VTT will point into that global symbol.

<p>
<a name="vtable-construction">
<h4><a href="#vtable-construction"> 2.5.3 Virtual Table Construction </a></h4>

<p>
In this section, we describe how to construct the virtual table for an class,
given virtual tables for all of its proper base classes.
To do so, we divide classes into several categories,
based on their base class structure.

<p>
<h5> Category 0: Trivial </h5>

Structure:
<ul>
<li> No virtual base classes.
<li> No virtual functions.
</ul>

<p>
Such a class has no associated virtual table,
and an object of such a class contains no virtual pointer.

<p>
<h5> Category 1: Leaf </h5>

Structure:
<ul>
<li> No inherited virtual functions.
<li> No virtual base classes.
<li> Declares virtual functions.
</ul>

<p>
The virtual table contains offset-to-top and RTTI fields
followed by virtual function pointers (as specified above).

<p>
<h5> Category 2: Non-Virtual Bases Only </h5>

Structure:
<ul>
<li> Only non-virtual proper base classes.
<li> Inherits virtual functions.
</ul>

<p>

The class has a virtual table for each proper base class that has a
virtual table.  The secondary virtual table for a base class B has the
same contents as the primary virtual table for B, except that:

<ul>
<p>
<li> The offset-to-top and RTTI fields
     contain information for the class,
     rather than for the base class. 

<p>
<li> The function pointer entries for virtual functions inherited from
     the base class and overridden by this class are replaced with the
     addresses of the overriding functions
     (or the corresponding adjustor secondary entry points).
</ul>

<p>
For a proper base class <code>Base</code>,
and a derived class <code>Derived</code> for which we are constructing
this set of virtual tables,
we shall refer to the virtual table for <code>Base</code> as
<code>Base-in-Derived</code>.
The virtual pointer of each base subobject of an object of the
derived class will point to the corresponding base virtual table in this set.

<p>
The primary virtual table for the derived class contains entries for
each of the functions in the primary base class virtual table,
replaced by new overriding functions as appropriate.  Following these
entries, there is an entry for each virtual function pointer for the
derived class (as specified above).

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
The primary virtual table can be viewed as two virtual tables accessed
from a shared virtual table pointer. 
</i>

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
A benefit of replicated virtual function entries (i.e., entries that
appear both in the primary virtual table and in a secondary virtual
table) is that they reduce the number of this pointer adjustments
during virtual calls.  Without replication, there would be more cases
where the this pointer would have to be adjusted to access a secondary
virtual table prior to the call.  These additional cases would be
exactly those where the function is overridden in the derived class,
implying an additional thunk adjustment back to the original pointer.
Replication saves two 'this' adjustments for each virtual call to an
overridden function originally introduced by a non-primary proper base
class.
</i>

<p>
<h5> Category 3: Virtual Bases Only </h5>

<p>
Structure:
<ul>
<li> Only virtual base classes
(but those may have non-virtual bases).
<li> The virtual
base classes are neither empty nor nearly empty.
</ul>

<p>
The class has a virtual table for each virtual base class
that has a virtual table.
These are all secondary virtual tables,
because there are no empty or nearly empty base classes to be primary,
and they are constructed from copies of the base class
full object virtual tables according to the same rules as in Category 2,
except that the virtual table for a virtual base A also includes a vcall
offset entry for each virtual function represented in A's primary
virtual table and the secondary virtual tables from A's non-virtual bases.

<p>
The vcall offsets in the secondary virtual table for a virtual base A are
ordered as described next.
We describe the ordering from the entry closest to the virtual table address
point to that furthest.
Since the vcall offsets precede the virtual table address point,
this means that the memory address order is the reverse of that
described.
<ul>
<p>
<li>
If virtual base A has a primary base class P sharing its virtual table,
P's vcall offsets come first,
in the same order they would appear if P itself were the virtual base.

<p>
<li>
Next come vcall offsets for each virtual function declared in A,
in declaration order.
Note that even for an overriding virtual function with covariant return
types, only one vcall offset is present,
as it can be shared by both virtual table entries.

<p>
<li>
Finally come vcall offsets for virtual functions declared in
non-virtual bases of A other than P.
These bases are considered in inheritance graph preorder,
and the vcall offsets for multiple functions declared in one of them
are in declaration order.
</ul>

<p>
If the above listing of vcall offsets includes more than one
for a particular virtual function signature,
only the first one (closest to the virtual table address point) is allocated.
That is, an offset from primary base P (and its non-virtual bases)
eliminates any from A or its other bases,
an offset from A eliminates any from the non-primary bases,
and an offset from a non-primary base B of A eliminates any from the
bases of B.

<p>
<i>
Note that there are no vcall offsets for virtual functions declared in
a virtual base class V of A and never overridden within A or its
non-virtual bases.
Calls to such functions will use the vcall offset in V's virtual table.
</i>

<p>
The class also has a virtual table that is not copied from the virtual base
class virtual tables.
This virtual table is the primary virtual table of the class
and is addressed by the virtual table pointer at the top of the object,
which is not shared
because there are no nearly empty virtual bases to be primary.
It holds the virtual function pointer entries for the class.
This includes all entries overridden from base classes,
because there is no primary base class;
such entries are known as replicated entries
because they are already in the secondary virtual tables of the class.
</ul>

<p>
The primary virtual table also has virtual base offset entries
to allow finding the virtual base subobjects.
There is one virtual base offset entry for each virtual base class,
direct or indirect.
The entries are in the reverse of the inheritance graph order.
That is, the entry for the leftmost virtual
base is closest to the address point of the virtual table.


<p>
<h5> Category 4: Complex </h5>

<p>
Structure:
<ul>
<li> None of the above,
     i.e. directly or indirectly inherits both virtual and non-virtual
     proper base classes, or at least one nearly empty virtual base class.
</ul>

<p>
The rules for constructing virtual tables of the class are a combination of
the rules from Categories 2 and 3,
and can generally be determined inductively.
The differences are mostly due to the fact that virtual base classes
can now have (nearly empty) primary bases:

<ul>
<p>
<li>
    If virtual base A has a primary virtual base class P
    sharing its virtual table,
    P's vbase and vcall offsets come first in the primary virtual table,
    in the same order they would appear if P itself were the virtual base,
    and those from A that do not replicate those from P precede them.

<p>
<li> As for the non-virtual base case,
    the virtual function pointer entries from the derived class
    (specified above) appear after the entries from the primary base
    class.

</ul>

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>For an S-as-T virtual table,
the vbase offset entries from the primary virtual table for T
are replaced with appropriate offsets given the completed hierarchy.
</i>

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
Consider the following inheritance hierarchy:
<code><pre>
  struct S { virtual void f() };
  struct T : virtual public S {};
  struct U : virtual public T {};
  struct V : public T, virtual public U {};
</pre></code>
<p>
T's virtual table contains a virtual base offset for S.
U's virtual table contains virtual base offsets for S and T.
V's virtual table contains virtual base offsets for S, U, and T
(in reverse inheritance graph preorder),
where the vbase offset for T is for the virtual base of U,
not for the non-virtual direct base of V.

<p>
Consider in addition:
<code><pre>
  struct W : public T {};
</pre></code>
<p>
T is a primary base class for W.
Therefore, its virtual base offset for S in its embedded T-in-W virtual
table
is the only one present.
</i>

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
The above-described virtual table group layout would allow all
non-virtual secondary base class virtual tables in a group to be
accessed from a virtual pointer for one of them,
since the relative offsets would be fixed.
(Since the primary virtual table could end up being embedded,
as the primary base class virtual table,
in another virtual table with additional virtual pointers separating it
from its secondary virtual tables,
this observation is not true of the primary virtual table.)
However, since construction virtual table groups may be organized
differently (see below),
an implementation may not depend on this relationship between
secondary virtual tables.
This tradeoff was made because the space savings resulting from not
requiring construction virtual tables to occur in complete groups
was considered more important than potential sharing of virtual
pointers.
</i>


<p> <hr> <p>
<a name="vtable-ctor">
<h3><a href="#vtable-ctor"> 2.6 Virtual tables During Object Construction </a></h3>

<p>
<a name="vtable-ctor-general">
<h4><a href="#vtable-ctor-general"> 2.6.1 General </a></h4>

<p>
In some situations,
a special virtual table called a construction virtual table is used during
the execution of proper base class constructors and destructors.
These virtual tables are for specific cases of virtual inheritance.

<p>
During the construction of a class object, the object assumes the type
of each of its proper base classes, as each base class subobject is
constructed.  RTTI queries in the base class constructor will return
the type of the base class, and virtual calls will resolve to member
functions of the base class rather than the complete class.  RTTI
queries, dynamic casts and virtual calls of the object under
construction statically converted to bases of the base under
construction will dynamically resolve to the type of the base under
construction.

Normally,  this behavior is accomplished by setting,
in the base class constructor,
the object's virtual table pointers to the addresses of the
virtual tables for the base class.

<p>
However, if the base class has direct or indirect virtual bases, the  
virtual table pointers have to be set to the addresses of construction
virtual tables.
This is because the normal proper base class virtual tables may not hold  
the correct virtual base index values to access the virtual bases of  
the object under construction,
and adjustment addressed by these virtual tables may hold
the wrong this parameter adjustment if the adjustment is to cast
from a virtual base to another part of the object. The problem is
that a complete object of a proper base class and a complete object of a
derived class do not have virtual bases at the same offsets.

<p>
A construction virtual table holds the virtual function addresses,
offset-to-top,
and RTTI information associated with the base class,
and virtual base offsets and addresses of adjustor entry points with their
parameter adjustments associated with objects of the complete class.

<p>
To ensure that the virtual table pointers are set to the appropriate
virtual tables during proper base class construction,
a table of virtual table pointers,  
called the VTT, which holds the addresses of construction and
non-construction virtual tables is generated for the complete class. The
constructor for the complete class passes to each proper base class
constructor a pointer to the appropriate place in the VTT where the  
proper base class constructor can find its set of virtual tables.
Construction virtual tables are used in a similar way during the
execution of proper base class destructors.

<p>
<img src="warning.gif" alt="NOTE">
<i>
When a complete object constructor is constructing a virtual base, it
must be wary of using the vbase offsets in the virtual table, since
the possibly shared virtual pointer may point to a construction
virtual table of an unrelated base class. 

For instance, in
<pre><code>
  struct S {};
  struct T: virtual S {};
  struct U {};
  struct V: virtual T, virtual U {};
</code></pre>
the virtual pointers for T and V are in the same place.  When V's 
constructor is about to construct U, that virtual pointer points to
a virtual table for T, and therefore cannot be used to locate U.
</i>
</p>

<p>
<a name="vtable-ctor-vtt">
<h4><a href="#vtable-ctor-vtt"> 2.6.2 VTT Order </a></h4>

<p>
An array of virtual table addresses, called the <i><b>VTT</b></i>,
is declared for each class type that has
indirect or direct virtual base classes.
(Otherwise,
each proper base class may be initialized
using its complete object virtual table group.)

<p>
The elements of the VTT array for a class D are in this order:

<ol type=1>
<li>
<i>Primary virtual pointer</i>:
address of the primary virtual table for the complete object D.

<p>
<li>
<i>Secondary VTTs</i>:

for each direct non-virtual proper base class B of D that requires a
VTT, in declaration order, a sub-VTT for B-in-D, structured like the
main VTT for B, with a primary virtual pointer, secondary VTTs, and
secondary virtual pointers, but without virtual VTTs.

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
This construction is applied recursively.
</i>

<p>
<li>
<i>Secondary virtual pointers</i>:

for each base class X which (a) has virtual bases or is reachable
along a virtual path from D, and (b) is not a non-virtual primary
base, the address of the virtual table for X-in-D or an appropriate
construction virtual table.

<p>X is reachable along a virtual path from D if there exists a path
X, B1, B2, ..., BN, D in the inheritance graph such that at least one
of X, B1, B2, ..., or BN is a virtual base class.</p>

<p>The order in which the virtual pointers appear in the VTT is
inheritance graph preorder.</p>

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
There are virtual pointers for direct and indirect base classes.
Although primary non-virtual bases do not get secondary virtual
pointers, they do not otherwise affect the ordering.
</i>

<p>
<i>
Primary virtual bases require a secondary virtual pointer in the VTT
because the derived class with which they will share a virtual pointer
is determined by the most derived class in the hierarchy.
</i>

<p>
<i>
Secondary virtual pointers may be required for base classes that do
not require secondary VTTs.  A virtual base with no virtual bases of
its own does not require a VTT, but does require a virtual pointer
entry in the VTT.
</i>

<p>
<li>
<i>Virtual VTTs</i>:
For each proper virtual base classes in
inheritance graph preorder, construct a sub-VTT as in (2) above.

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
The virtual VTT addresses come last because they are only passed
to the virtual base class constructors for the complete object.
</i>

</ol>

<p>
Each virtual table address in the VTT is the address to be assigned to the
respective virtual pointer,
i.e. the address past the end of the typeinfo pointer
(the address of the first virtual function pointer, if there are any),
not of the first vcall offset.

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
It is required that the VTT for a complete class D be identical in
structure to the sub-VTT for the same class D as a base of another
class E derived from it,
so that the constructors for D can depend on that structure.
Therefore, the various components of its VTT are present based on the
rules given, even if they point to the
D complete object virtual table or its secondary virtual tables.
That is, secondary VTTs are present for all bases with virtual bases
(including the virtual bases themselves,
which have their secondary VTTs in the virtual VTT section),
and secondary virtual pointers are present for all bases with either
virtual bases or virtual function declarations overridden along a
virtual path.
The only exception is that a primary non-virtual base class does not
require a secondary virtual pointer.

<p>
Parts (1) and (3) of a primary (not secondary, i.e. nested) VTT,
that is the primary and secondary virtual pointers,
are used for the final initialization of an object's virtual pointers
before the full-object initialization and later use,
and must therefore point to the main virtual table group for the class.
Those bases which do not have secondary virtual pointers in the VTT
have their virtual pointers explicitly initialized to the main virtual
table group by the constructors
(see <a href=#subobj-ctor>Subobject Construction and Destruction</a>).

<p>
The virtual pointers in the secondary VTTs and virtual VTTs are used for
subobject construction,
and may always point to special construction virtual tables laid out as
described in the following subsections.
However, it will sometimes be possible to use either the full-object
virtual table for the base class,
or its secondary virtual table for the full class being constructed.
This ABI does not specify a choice,
nor does it specify names for the construction virtual tables,
so the constructors must use the VTT rather than assuming that a
particular construction virtual table exists.

<p>
For example, suppose we have the following hierarchy:
</i>
<code><pre>
  class A1 { int i; };
  class A2 { int i; virtual void f(); };
  class V1 : public A1, public A2 { int i; };
	// A2 is primary base of V1, A1 is non-polymorphic
  class B1 { int i; };
  class B2 { int i; };
  class V2 : public B1, public B2, public virtual V1 { int i; };
	// V2 has no primary base, V1 is secondary base
  class V3 {virtual void g(); };
  class C1 : public virtual V1 { int i; };
	// C1 has no primary base, V1 is secondary base
  class C2 : public virtual V3, public virtual V2 { int i; };
	// C2 has V3 primary (nearly-empty virtual) base, V2 is secondary base
  class X1 { int i; };
  class C3 : public X1 { int i; };
  class D : public C1, public C2, public C3 { int i;  };
	// C1 is primary base, C2 is secondary base, C3 is non-polymorphic

</pre></code>

<i>
Then the VTT for D would appear in the following order,
where indenting indicates the sub-VTT structure,
and asterisks (*) indicate that construction virtual tables instead of
complete object virtual tables are required.
</i>
<code><pre>
  // 1. Primary virtual pointer:
  [0] D has virtual bases (complete object vptr)

  // 2. Secondary VTTs:
  [1]  C1 * (has virtual base)
  [2]     V1-in-C1 in D (secondary vptr)

  [3]  C2 * (has virtual bases)
  [4]    V3-in-C2 in D (primary vptr)
  [5]    V2-in-C2 in D (secondary vptr)
  [6]    V1-in-C2 in D (secondary vptr)

  // 3. Secondary virtual pointers:
    // (no C1-in-D -- primary base)
  [7]    V1-in-D (V1 is virtual)
  [8]  C2-in-D (preorder; has virtual bases)
  [9]    V3-in-D (V3 is virtual)
  [10]    V2-in-D (V2 is virtual)
    // (For complete object D VTT, these all can point to the
    // secondary vtables in the D vtable, the V3-in-D entry
    // will be the same as the C2-in-D entry, as that is the active
    // V3 virtual base in the complete object D.  In the sub-VTT for
    // D in a class derived from D, some might be construction
    // virtual tables.)

  // 4. Virtual VTTs:
    // (V1 has no virtual bases).
  [11] V2 * (V2 has virtual bases)
  [12]   V1-in-V2 in D * (secondary vptr, V1 is virtual)
	   (A2 is primary base of V1)
    // (V3 has no virtual bases)

</pre></code>

<p>
<i>
If A2 is a virtual base of V1,
the VTT will contain more elements
(exercise left to the astute reader).
</i>

<p>
<a name="vtable-ctor-layout">
<h4><a href="#vtable-ctor-layout"> 2.6.3 Construction Virtual Table Layout </a></h4>

<p>
The construction virtual tables for a complete object are 
emitted in the same object file as the virtual table.
</font>
So the virtual table structures for a complete object of class C include,
in no particular order:

<ul>
<li>
the main virtual table group for C,
i.e. the virtual table to which the primary virtual pointer
(at offset 0) points,
along with its proper base class virtual tables
in order of allocation,
including virtual base class virtual tables;

<li>
any construction virtual tables required for non-virtual and virtual bases;
and

<li>
the VTT array for C, providing location information for the above.
</ul>

<p>
The VTT array is referenced via its own mangled external name,
and the construction virtual tables are accessed via the VTT array,
so the latter do not have external names.


<p>
<a name="vtable-ctor-entries">
<h4><a href="#vtable-ctor-entries"> 2.6.4 Construction Virtual Table entries </a></h4>

<p>
The construction virtual table group for a
proper base class subobject B (of derived class D)
does not have the same entries in the same
order as the main virtual table group for a complete object B,
as described in <a href=#vtable>Virtual Table Layout</a> above.
Some of the base class subobjects may not need construction virtual tables,
which will therefore not be present in the construction virtual table group,
even though the subobject virtual tables are present in the main virtual
table group
for the complete object.

<p>
The <i>values</i> of some construction virtual table entries will differ
from the corresponding entries in either the main virtual table
group for B or the virtual table group for B-in-D,
primarily because the virtual bases of B will be at different relative
offsets in a D object than in a standalone B object,
as follows:

<ol>
<li>
Virtual base class offsets reflect the positions of the virtual base
classes in the full D object.

<li>
Similarly, vcall offsets reflect the relative positions of the
overridden and overriding classes within the complete object D.

<li>
The offset-to-top fields refer to B
(and B's in particular will therefore be zero).

<li>
The RTTI pointers point to B's RTTI.

<li>
Only functions in B and its base classes are considered for virtual
function resolution.
</ol>


<p> <hr> <p>
<a name="array-cookies">
<h3><a href="#array-cookies"> 2.7 Array Operator <code>new</code> Cookies </a></h3>

<p>
When operator <code>new</code> is used to create a new array,
a cookie is usually stored to remember the allocated length
(number of array elements)
so that it can be deallocated correctly.

<p>
Specifically:
<ul>
<p>
<li> No cookie is required if the array element type T has a trivial
    destructor (12.4 [class.dtor])
    and the usual (array) deallocation function
    (3.7.3.2 [basic.stc.dynamic.deallocation])
    function does not take two arguments.

    <p>
    (Note: if the usual array deallocation function takes two arguments,
    then it is a member function whose second argument is of type size_t.
    The standard guarantees (12.5 [class.free])
    that this function will be passed the
    number of bytes allocated with the previous array new expression.)

<p>
<li> No cookie is required if the <code>new</code> operator being used
    is <code>::operator new[](size_t, void*)</code>.

<p>
<li> Otherwise, this ABI requires a cookie, setup as follows:
  <ul>
  <li> The cookie will have size <code>sizeof(size_t)</code>.
  <li> Let <code>align</code> be the maximum alignment of
  <code>size_t</code> and an element of the array to be allocated.
  <li> Let <code>padding</code> be the maximum of
  <code>sizeof(size_t)</code> and <code>align</code> bytes.
  <li> The space allocated for the array will be the space required
  by the array itself plus <code>padding</code> bytes.
  <li> The alignment of the space allocated for the array will be
  <code>align</code> bytes.
  <li> The array data will begin at an offset of <code>align</code> bytes
  from the space allocated for the array.
  <li> The cookie will be stored in the <code>sizeof(size_t)</code> bytes
  immediately preceding the array data.
  </ul>

  <i>
  <p>
  These rules have the following consequences:
  <ul>
  <li> The array elements and the cookie are all aligned naturally.
  <li> Padding will be required if <code>sizeof(size_t)</code>
  is smaller than the array element alignment,
  and if present will precede the cookie.
  </ul>
  </i>

</ul>

<p>
Given the above, the following is pseudocode for processing
<code>new(ARGS) T[n]</code>:
<code><pre>
  if T has a trivial destructor (C++ standard, 12.4/3)
    padding = 0
  else if we're using ::operator new[](size_t, void*)
    padding = 0
  else
    padding = max(sizeof(size_t), alignof(T))

  p = operator new[](n * sizeof(T) + padding, ARGS)
  p1 = (T*) ( (char *)p + padding )

  if padding > 0
    *( (size_t *)p1 - 1) = n

  for i = [0, n)
    create a T, using the default constructor, at p1[i]

  return p1
</pre></code>


<p> <hr> <p>
<a name="guards">
<h3><a href="#guards"> 2.8 Initialization Guard Variables </a></h3>

<p>
If a function-scope static variable or a static data member with vague
linkage (i.e., a static data member of a class template) is
dynamically initialized, then there is an associated guard variable
which is used to guarantee that construction occurs only once.  The <a
href="#mangling-special-guards">guard variable's name</a> is mangled
based on the mangling of the guarded object name.  Thus, for
function-scope static variables, if multiple instances of the function
body are emitted (e.g., due to inlining), each function uses the same
guard variable to ensure that the function-scope static is initialized
only once.  Similarly, if a static data member is instantiated in
multiple object files, the initialization code in each object file
will use the same guard variable to ensure that the static data member
is initialized only once.

<p>
The size of the guard variable is 64 bits.
The first byte (i.e. the byte at the address of the full variable)
shall contain the value 0 prior to initialization of
the associated variable, and 1 after initialization is complete.
Usage of the other bytes of the guard variable is implementation-defined.

<p>
See <a href=#once-ctor>Section 3.3.3</a>
for the API for references to this guard variable.


<p> <hr> <p>
<a name="rtti">
<h3><a href="#rtti"> 2.9 Run-Time Type Information (RTTI) </a></h3>

<p>
<a name="rtti-general">
<h4><a href="#rtti-general"> 2.9.1 General </a></h4>

<p>
The C++ programming language definition implies that information about
types be available at run time for three distinct purposes:
<ol type=a>
<li> to support the typeid operator,
<li> to match an exception handler with a thrown object, and
<li> to implement the dynamic_cast operator.
</ol>
(c) only requires type information about dynamic class types,
but (a) and (b) may apply to other types as well;
for example, when a pointer to an int is thrown,
it can be caught by a handler that catches "int const*".

<p>
It is intended that two type_info pointers point to equivalent type
descriptions if and only if the pointers are equal.
An implementation must satisfy this constraint,
e.g. by using symbol preemption, COMDAT sections, or other mechanisms.

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
Note that the full structure described by an RTTI descriptor may
include incomplete types not required by the Standard to be completed,
although not in contexts where it would cause ambiguity.
Therefore, any cross-references within the RTTI to types not known to
be complete must be weak symbol references.
</i>

<p>
<a name="rtti-emission">
<h4><a href="#rtti-emission"> 2.9.2 Place of Emission </a></h4>

<p>
It is desirable to minimize the number of places where a
particular bit of RTTI is emitted.
For dynamic class types,
a similar problem occurs for virtual function tables,
and hence the RTTI descriptor should be emitted
with the primary virtual table for that type.
For other types, they must be emitted at the location
where their use is implied:
the object file containing the typeid, throw or catch.

<p>
Basic type information (e.g. for "int", "bool", etc.)
will be kept in the run-time support library.
Specifically, the run-time support library
should contain type_info objects for the types
X, X* and X const*,
for every X in: void, std::nullptr_t,
bool, wchar_t, char, unsigned char, signed char,
short, unsigned short, int, unsigned int, long, unsigned long, long long,
unsigned long long, float, double, long double, char8_t, char16_t, char32_t,
and the IEEE 754r decimal and half-precision floating point types.
Each of the type_info objects for X shall have type
<code>abi::__fundamental_type_info</code> (or a type derived therefrom),
whereas the objects corresponding to X* and X const* shall have type
<code>abi::__pointer_type_info</code> (or a type derived therefrom).
(Note that various other type_info objects for class types may reside
in the run-time support library by virtue of the preceding rules,
e.g. that of <code>std::bad_alloc</code>.)


<p>
<a name="typeid">
<h4><a href="#typeid"> 2.9.3 The <code>typeid</code> Operator</a></h4>

<p>
The typeid operator produces a reference to a std::type_info structure
with the following public interface (18.5.1):

<pre><code>
  namespace std {
    class type_info {
      public:
	virtual ~type_info();
	bool operator==(const type_info &) const;
	bool operator!=(const type_info &) const;
	bool before(const type_info &) const;
	const char* name() const;
      private:
	type_info (const type_info& rhs);
	type_info& operator= (const type_info& rhs);
    };
  }
</pre></code>

<p>
After linking and loading,
only one std::type_info structure is accessible via the external name
defined by this ABI for any particular complete type symbol
(see <a href=#vague-rtti>Vague Linkage</a>).
Therefore,
except for direct or indirect pointers to incomplete types,
the equality and inequality operators can be
written as address comparisons
when operating on those type_info objects:
two type_info structures describe the same type
if and only if they are the same structure (at the same address).
However, in the case of pointer types,
directly or indirectly pointing to incomplete class types,
a more complex comparison is required,
described below with the RTTI layout of pointer types.

<p>
The <code>name()</code> member function returns the address of an
NTBS, unique to the type, containing
the <a href="#mangling-type">mangled name</a> of the type.
The <a href="#mangling-special">mangled name of the NTBS</a> is also
defined by the ABI to allow consistent reference to it, and
the <a href=#vague-rtti>Vague Linkage</a> section specifies how to
produce a unique copy.

<p>
In a flat address space
(such as that of the Itanium architecture),
the <code>operator==</code>, <code>operator!=</code>, and <code>before()</code>
members are easily implemented in terms of
an address comparison of the name NTBS.

<p>
This implies that the type information must keep a description of the public,
unambiguous inheritance relationship of a type, as well as the const
and volatile qualifications applied to types.


<p>
<a name="rtti-layout">
<h4><a href="#rtti-layout"> 2.9.4 RTTI Layout </a></h4>

<ol type=1>

<p>
<li>
The class definitions below are to be interpreted as implying a memory
layout following the class layout rules for the host ABI.
They specify data members only,
except for the Standard-specified member functions of the
<code>std::type_info</code> class given below,
and do not imply anything about the member functions of these classes.
Virtual member functions of these classes may only be used within the
target systems' respective runtime libraries.
The data members must be laid out exactly as specified.

<p>
<li>
Every virtual table shall contain one entry describing the offset from a
virtual pointer for that virtual table to the origin of the object
containing that virtual pointer
(or equivalently: to the virtual pointer for the primary virtual table).
This entry is directly useful to implement dynamic_cast&lt;void cv*>,
but is also needed for the other truly dynamic casts.
This entry is located two words ahead of the location
pointed to by the virtual pointer (i.e., entry "-2").
This entry is present in all virtual tables,
even for classes having virtual bases but no virtual functions.

<p>
<li>
Every virtual table shall contain one entry that is a pointer to an object
derived from <code>std::type_info</code>.
This entry is located at the word preceding the location
pointed to by the virtual pointer (i.e., entry "-1").
The entry is allocated in all virtual tables;
for classes having virtual bases but no virtual functions,
the entry is zero.

<p>
We add one pointer to the
<code>std::type_info</code> class in addition to the virtual table
pointer implied by its virtual destructor:
<pre><code>
      class type_info {
	 ... // See <a href="#typeid">section 2.9.3</a>
	private:
	 const char *__type_name;
      };

</pre></code>
<ul>
<li> The class will contain a virtual pointer before the explicit members.
<li> <code>__type_name</code> is a pointer to a NTBS
    representing the mangled name of the type.
</ul>

<p>
The possible derived types are:
<ul>
  <li> <code>abi::__fundamental_type_info</code> 
  <li> <code>abi::__array_type_info</code> 
  <li> <code>abi::__function_type_info</code> 
  <li> <code>abi::__enum_type_info</code> 
  <li> <code>abi::__class_type_info</code> 
  <li> <code>abi::__si_class_type_info</code> 
  <li> <code>abi::__vmi_class_type_info</code> 
  <li> <code>abi::__pbase_type_info</code> 
  <li> <code>abi::__pointer_type_info</code> 
  <li> <code>abi::__pointer_to_member_type_info</code> 
</ul>

<p>
<li>
<code>abi::__fundamental_type_info</code> adds no data members
to <code>std::type_info</code>;

<p>
<li>
<code>abi::__array_type_info</code> and
<code>abi::__function_type_info</code> do not add data
members to <code>std::type_info</code>
(these types are only produced by the typeid operator;
they decay in other contexts).&nbsp;&nbsp;
<code>abi::__enum_type_info</code> does not add data members either.

<p>
<li>
Three different types are used to represent user type information:

<ol type=a>
<p>
<li>
<code>abi::__class_type_info</code> is used for class types having no bases,
and is also a base type for the other two class type representations.
<pre><code>
      class __class_type_info : public std::type_info {}

</pre></code>

<p>
This RTTI class may
also be used for incomplete class types when referenced by a pointer RTTI,
in which case it must be prevented from preempting
the RTTI for the complete class type,
for instance by emitting it as a static object (without external linkage).

<p>
Two <code>abi::__class_type_info</code> objects can always be compared,
for equality (i.e. of the types represented) or ordering,
by comparison of their name NTBS addresses.
In addition, complete class RTTI objects
may also be compared for equality
by comparison of their type_info addresses.

<p>
<li>
For classes containing only a single, public, non-virtual base
at offset zero (i.e. the derived class is dynamic iff the base is),
class <code>abi::__si_class_type_info</code> is used.
It adds to <code>abi::__class_type_info</code> 
a single member pointing to the type_info structure for the base type,
declared "<code>__class_type_info const *__base_type</code>".
<pre><code>
      class __si_class_type_info : public __class_type_info {
	public:
	  const __class_type_info *__base_type;
      };

</pre></code>

<a name="vmi">
<p>
<li>
For classes with bases that do not satisfy the
<code>__si_class_type_info</code> constraints,
<code>abi::__vmi_class_type_info</code> is used.
It is derived from <code>abi::__class_type_info</code>:
<pre><code>
      class __vmi_class_type_info : public __class_type_info {
	public:
	  unsigned int __flags;
	  unsigned int __base_count;
	  __base_class_type_info __base_info[1];

	  enum __flags_masks {
	    __non_diamond_repeat_mask = 0x1,
	    __diamond_shaped_mask = 0x2
	  };
      };

</pre></code>
  <ul>
  <p>
  <li> <code>__flags</code> is a word with flags describing details
      about the class structure,
      which may be referenced by using the
      <code>__flags_masks</code> enumeration.
	<ul>
	<li> 0x01: class has non-diamond repeated inheritance
	<li> 0x02: class is diamond shaped
	</ul>
      These flags refer to both direct and indirect bases.
      The type of the <code>__flags</code> field is defined by each psABI,
      but must be at least 16 bits.
      For the 64-bit Itanium ABI, it will be unsigned int (32 bits).

  <p>
  <li> <code>__base_count</code> is a word with the number of
      direct proper base class descriptions that follow.
      The type of the <code>__base_count</code> field is defined by each psABI.
      For the 64-bit Itanium ABI, it will be unsigned int (32 bits).

  <p>
  <li> <code>__base_info[]</code> is an array of base class descriptions --
       one for every direct proper base.
       Each description is of the type:
<pre><code>
      struct abi::__base_class_type_info {
	public:
         const __class_type_info *__base_type;
	 long __offset_flags;

	 enum __offset_flags_masks {
	   __virtual_mask = 0x1,
	   __public_mask = 0x2,
	   __offset_shift = 8
	 };

      };
</pre></code>

      <p>
      The <code>__base_type</code>
      member points to the RTTI for the base type.

      <p>
      All but the lower 8 bits of <code>__offset_flags</code> are a
      signed offset.  For a non-virtual base, this is the offset in
      the object of the base subobject.  For a virtual base, this is
      the offset in the virtual table of the virtual base offset for
      the virtual base referenced (negative).

      <p>
      The low-order byte of <code>__offset_flags</code> contains flags,
      as given by the masks from the enumeration
      <code>__offset_flags_masks</code>:
	<ul>
	<li> 0x1: Base class is virtual
	<li> 0x2: Base class is public
	</ul>

  </ul>

<p>
Note that the resulting structure is variable-length,
with the actual size depending on the number of trailing base class
descriptions.

</ol>

<p>
<li>
<code>abi::__pbase_type_info</code> is a base for both pointer types and
pointer-to-member types.
It adds two data members:
<pre><code>
      class __pbase_type_info : public std::type_info {
	public:
	  unsigned int __flags;
	  const std::type_info *__pointee;

	  enum __masks {
	    __const_mask = 0x1,
	    __volatile_mask = 0x2,
	    __restrict_mask = 0x4,
	    __incomplete_mask = 0x8,
	    __incomplete_class_mask = 0x10,
	    __transaction_safe_mask = 0x20
	    __noexcept_mask = 0x40
	  };
      };

</pre></code>


<ul>
  <p>
  <li> <code>__flags</code> is a flag word describing the
      cv-qualification and other attributes of the type pointed to
      (e.g., "int volatile*" should have the
      "volatile" bit set in that word).
      For pointer to function and pointer-to-member-function types,
      <code>__flags</code> is also used to indicate a "qualification" of sorts
      for the pointed-to (member) function type.  That is the case for
      <code>__transaction_safe_mask</code> and <code>__noexcept_mask</code>
      where <code>__pointee</code> is a pointer to the "unqualified" version of
      the function type (e.g., one without the exception specification in the
      case of <code>__noexcept_mask</code>).
  <p>
  <li> <code>__pointee</code> is a pointer to the
      <code>std::type_info</code> derivation for the unqualified type
      being pointed to.
</ul>

<p>
Note that the <code>__flags</code>
bits should not be folded
into the pointer to allow future definition of additional flags.
It contains the following bits,
and may be referenced using the flags defined in the
<code>__masks</code> enum:
<ul>
<li> 0x1: <code>__pointee</code> type has const qualifier
<li> 0x2: <code>__pointee</code> type has volatile qualifier
<li> 0x4: <code>__pointee</code> type has restrict qualifier
<li> 0x8: <code>__pointee</code> type is incomplete
<li> 0x10: class containing <code>__pointee</code>
	  is incomplete (in pointer to member)
<li> 0x20: <code>__pointee</code> type is function type without the
	  transaction-safe indication
<li> 0x40: <code>__pointee</code> type is function type without the
	  exception specification
</ul>

<p>
When the <code>abi::__pbase_type_info</code> is for a direct
or indirect pointer to an incomplete class type,
the incomplete target type flag is set.
When it is for a direct or indirect pointer to a member of
an incomplete class type,
the incomplete class type flag is set.
In addition, it and all of the intermediate
<code>abi::__pointer_type_info</code> structs in the chain
down to the <code>abi::__class_type_info</code> for the
incomplete class type must be prevented from resolving to the
corresponding type_info structs for the complete class type,
possibly by making them local static objects.
Finally, a dummy class RTTI is generated for the incomplete type
that will not resolve to the final complete class RTTI
(because the latter need not exist),
possibly by making it a local static object.

<p>
Two <code>abi::__pbase_type_info</code> objects can always be compared
for equality (i.e. of the types represented) or ordering
by comparison of their name NTBS addresses.
In addition,
unless either or both have either of the incomplete flags set,
equality can be tested by comparing the type_info addresses.

<p>
<li>
<code>abi::__pointer_type_info</code> is derived from
<code>abi::__pbase_type_info</code> with no additional data members.

<p>
<li>
The <code>abi::__pointer_to_member_type_info</code> type adds one field
to <code>abi::__pbase_type_info</code>:
<pre><code>
      class __pointer_to_member_type_info : public __pbase_type_info {
	public:
	  const abi::__class_type_info *__context;
      };

</pre></code>
<ul>
<li> <code>__context</code> is a pointer to an
    <code>abi::__class_type_info</code> corresponding to the class type
    containing the member pointed to (e.g., the "A" in "int A::*")
</ul>

</ol>

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
Note that this ABI requires elsewhere that a virtual table be emitted for a
dynamic type in the object where the first non-inline virtual function
member is defined, if any, or everywhere referenced if none.
Therefore, an implementation should include at least one
non-inline virtual function member and define it in the library,
to avoid having user code inadvertently preempt the virtual table.
Since the Standard requires a virtual destructor,
and it will rarely be called,
it is a good candidate for this role.
</i>

<a name="rtti-name">
<h4><a href="#rtti-name"> 2.9.5 <code>std::type_info::name()</code> </a></h4>
<p>
The null-terminated byte string returned by this routine is
the <a href=#mangling>mangled name</a> of the type.

<p>
<a name="dynamic_cast">
<h4><a href="#dynamic_cast"> 2.9.6 The <code>dynamic_cast</code> Operator </a></h4>

<p>
Although dynamic_cast can work on pointers and references,
from the point of view of representation we need only to worry
about polymorphic class types.
Also, some kinds of dynamic_cast operations are handled at compile time
and do not need any RTTI.
There are then three kinds of truly dynamic cast operations:
<ul>
<li> dynamic_cast&lt;void cv*&gt;, which returns a pointer to the complete lvalue,
<li> dynamic_cast operation from a proper base class to a derived class, and
<li> dynamic_cast across the hierarchy which can be seen as a cast to
	the complete lvalue and back to a sibling base.
</ul>

<p>
The most common kind of dynamic_cast is base-to-derived in a singly
inherited hierarchy.

<p>
<a name="dynamic_cast-algorithm">
<h4><a href="#dynamic_cast-algorithm"> 2.9.7 The <code>dynamic_cast</code> Algorithm </a></h4>

<p>
Dynamic casts to "void cv*" are inserted inline at compile time.
So are dynamic casts of null pointers and dynamic casts that are really
static.

<p>
This leaves the following test to be implemented in the run-time
library for truly dynamic casts of the form "dynamic_cast&lt;T&gt;(v)":
(see [expr.dynamic_cast] 5.2.7/8)

<ul>
<p>
<li>
If, in the most derived object pointed (referred) to by v, v points
(refers) to a public base class subobject of a T object
[note: this can be checked at compile time],
and if only one object of type T is derived
from the subobject pointed (referred) to by v,
the result is a pointer (an lvalue referring) to that T object.

<p>
<li>
Otherwise, if v points (refers) to a public base class subobject
of the most derived object,
and the type of the most derived object has an
unambiguous public base class of type T,
the result is a pointer
(an lvalue referring)
to the T subobject of the most derived object. 

<p>
<li>
Otherwise, the run-time check fails.
</ul>

<p>
The first check corresponds to a "base-to-derived cast" and the second
to a "cross cast".
These tests are implemented by abi::__dynamic_cast:

<pre><code>
   extern "C" 
   void* __dynamic_cast ( const void *sub,
			  const abi::__class_type_info *src,
			  const abi::__class_type_info *dst,
			  std::ptrdiff_t src2dst_offset);
   /* sub: source address to be adjusted; nonnull, and since the
    *      source object is polymorphic, *(void**)sub is a virtual
    pointer.
    * src: static type of the source object.
    * dst: destination type (the "T" in "dynamic_cast&lt;T&gt;(v)").
    * src2dst_offset: a static hint about the location of the
    *    source subobject with respect to the complete object;
    *    special negative values are:
    *       -1: no hint
    *       -2: src is not a public base of dst
    *       -3: src is a multiple public base type but never a
    *           virtual base type
    *    otherwise, the src type is a unique public nonvirtual
    *    base type of dst at offset src2dst_offset from the
    *    origin of dst.
    */

</pre></code>

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
Rationale: 
<ul>
<p>
<li> A simple dynamic_cast algorithm that is efficient in the common
    case of base-to-most-derived cast case is preferable to more
    sophisticated ideas that handle deep-base-to-in-between-derived
    casts more efficiently at a slight cost to the common case.
    Hence, an earlier scheme of providing a hash-table into the
    list of base classes
    (as is done e.g. in the HP aC++ compiler)
    was dropped.
<p>
<li> For similar reasons,
    we only keep direct base information about a class type.
    Indirect base information can be found by chasing type_info pointers
    (and care should be taken to determine ambiguous base class types).
<p>
<li> The GNU egcs development team has implemented an idea of this ABI
    group to accelerate dynamic_cast operations by a-posteriori
    checking a "likely outcome".
    This is the purpose of the src2dst_offset hint.
    An implementation is free to always pass -1 (no hint),
    or to always ignore the hint in __dynamic_cast.
</ul>
</i>

<p>
<a name="exception-matching-algorithm">
<h4><a href="#exception-matching-algorithm"> 2.9.8 The Exception Handler Matching Algorithm </a></h4>

<p>
Since the RTTI related exception handling routines are "personality specific",
no interfaces need to be specified in this document
(beyond the layout of the RTTI data).


<p> <hr> <p>
<a name="calls">
<h2><a href="#calls"> Chapter 3: Code Emission and APIs </a></h2>
<p> <hr>

<p>
This chapter describes how to define and call functions.
It also specifies the APIs of a variety of runtime utility routines
required to be part of the support library of an ABI-conforming
implementation for use by compiled code.
In addition, reference is made to the separate description of
<a href=abi-eh.html>exception handling</a> in this ABI,
which defines a large number of runtime utility routine APIs.

<p>
<a name="functions">
<h3><a href="#functions">3.1 Functions</a></h3>
</a>

<p>
In general, the calling conventions and rules for defining C++
functions in this ABI follow those specified for functions of
the corresponding type in the base C ABI.  The corresponding type
is mostly determined by translating C++ constructs to their
obvious C analogues.  This section specifies the behavior of
of features without analogues in C, as well as some exceptions
and extra rules required by C++-specific semantics.

<p>
<a name="function-defs">
<h4><a href="#function-defs">3.1.1 Function Definitions</a></h4>

<p>
For the most part, non-static member functions, including constructors
and destructors, are defined as if they were ordinary functions except
for the addition of the implicit parameters to the prototype as
described in the <a href="#parameters">section on parameters</a>.

<p>
The rules for <a href="#member-function-pointers">member function
pointers</a> may require aligning the first instruction of ordinary
non-static member functions (i.e. not constructors or destructors)
to a higher value than the platform would normally require.

<a name="parameters">
<h4><a href="#parameters">3.1.2 Parameters</a></h4>
</a>

<p>
<a name="this-parameters">
<h5><a href="#this-parameters">3.1.2.1 <code>this</code> Parameters</a></h5>

<p>
Non-static member functions, including constructors and destructors,
take an implicit <code>this</code> parameter of pointer type.  It is
passed as if it were the first parameter in the function prototype,
except as modified for <a href="#non-trivial-return-values">non-trivial
return values</a>.

<p>
<a name="vtt-parameters">
<h5><a href="#vtt-parameters">3.1.2.2 <code>VTT</code> Parameters</a></h5>

<p>
Base-subobject constructors and destructors for classes with virtual
bases take an implicit <a href="#vtable-ctor"><code>VTT</code></a>
parameter of pointer type.  It is passed as if it were the second
parameter in the function prototype, immediately following the
<code>this</code> parameter, except as modified for
<a href="#non-trivial-return-values">non-trivial return values</a>.

<p>
<a name="non-trivial-parameters">
<h5><a href="#non-trivial-parameters">3.1.2.3 Non-Trivial Parameters</a></h5>

<p>
If a parameter type is a class type that is
<a href="#non-trivial">non-trivial for the purposes of calls</a>, the
caller must allocate space for a temporary and pass that temporary by
reference.  Specifically:

<ul>
 <li>Space is allocated by the caller in the usual manner for a temporary,
   typically on the stack.</li>
 <li>The caller evaluates the argument in the space provided.</li>
 <li>The function is called, passing the address of the temporary as the
   appropriate argument.  In the callee, the address passed is used
   as the address of the parameter variable.</li>
 <li>If the type has a non-trivial destructor, the caller calls that
   destructor after control returns to it (including when the caller
   throws an exception).
 <li>If necessary (e.g. if the temporary was allocated on the heap),
   the caller deallocates space after return and destruction.
</ul>

<p>
A C-style variadic argument of a type that is non-trivial for the
purposes of calls is passed the same way: the address of the temporary
is passed using the normal variadic mechanism, and <code>va_arg</code> in
the callee retrieves the address and treats it as a reference to the
temporary.

<a name="special-class-parameters">
<h5><a href="#special-class-parameters">3.1.2.4 Parameters of Special Class Type</a></h5>

<p>
An argument of class
<code>std::decimal::decimal32</code>,
<code>std::decimal::decimal64</code>, or
<code>std::decimal::decimal128</code> as defined in TR 24733
is passed the same as the corresponding native decimal
floating-point scalar type.

<p>
<a name="reference-parameters">
<h5><a href="#reference-parameters">3.1.2.5 Reference Parameters</a></h5>

<p>
Reference parameters are handled by passing a pointer to the object
bound to the reference.

<p>
<a name="empty-parameters">
<h5><a href="#empty-parameters">3.1.2.6 Empty Parameters</a></h5>

<p>
Arguments of empty class types that are not non-trivial for the purposes
of calls are passed no differently from ordinary classes.

<p>
On Itanium, the NaT bit must be set on all registers that are associated
with the argument.

<p>
<a name="return-values">
<h4><a href="#return-values">3.1.3 Return Values</a></h4>

<p>
<a name="non-trivial-return-values">
<h5><a href="#non-trivial-return-values">3.1.3.1 Non-trivial Return Values</a></h5>

<p>
If the return type is a class type that is
<a href="#non-trivial">non-trivial for the purposes of calls</a>,
the caller passes an address as an implicit parameter.
The callee then constructs the return value into this address.
If the return type has a non-trivial destructor, the caller is responsible
for destroying the temporary when control is returned to it <i>normally</i>.
If an exception is thrown out of the callee after the return value is
constructed but before control returns to the caller, e.g. by a
throwing destructor, it is the callee's responsibility to destroy the
return value before propagating the exception to the caller.  Thus,
in general, the caller is responsible for destroying the return value
after, and only after, the callee returns control to the caller normally.

<p>
The address passed need not be of temporary memory; copy elision may
cause it to point anywhere, including to global or heap-allocated memory.

<p>
C ABIs usually provide treatment for "indirect" return values, e.g. when
returning a large aggregate that cannot fit in registers.  In some cases,
this treatment may not be suitable for non-trivial C++ return values, such
as if the convention requires implicit copying or does not permit the
return value to be constructed at an arbitrary address.  If the treatment
exists and is suitable, it is used for non-trivial return values.
Otherwise, the pointer is passed as if it were the first parameter in
the function prototype, preceding all other parameters, including the
<code>this</code> and <code>VTT</code> parameters.

<p>
<a name="special-class-return-values">
<h5><a href="#special-class-return-values">3.1.3.2 Return Values of Special Class Type</a></h5>

<p>
A return value of class
<code>std::decimal::decimal32</code>,
<code>std::decimal::decimal64</code>, or
<code>std::decimal::decimal128</code> as defined in TR 24733 is
returned the same as the corresponding native decimal floating-point
scalar type.

<p>
<a name="reference-return-values">
<h5><a href="#reference-return-values">3.1.3.3 Reference Return Values</a></h5>

<p>
A return value of reference type is returned as a pointer to the object
bound to the reference.

<p>
<a name="empty-return-values">
<h5><a href="#emptty-return-values">3.1.3.4 Empty Return Values</a></h5>

<p>
A return value of an empty class type that is not non-trivial for
the purposes of calls will be returned as though it were the
following C type:

<pre>struct { char c; };</pre>

<p>
On Itanium, the NaT bit must not be set for any register associated with
this return value.

<p>
<a name="return-value-ctor">
<h5><a href="#return-value-ctor">3.1.3.5 Constructor Return Values</a></h5>

<p>
Constructors return <code>void</code> results.

<p>
Some platforms are known to modify this rule to specify that constructors
return a pointer to <code>this</code>.  This may permit more efficient
code generation in the caller.

<p>
<a name="return-value-dtor">
<h5><a href="#return-value-dtor">3.1.3.6 Destructor Return Values</a></h5>

<p>
Destructors return <code>void</code> results.

<p>
Some platforms are known to modify this rule to specify that destructors
return a pointer to <code>this</code>.  This may permit more efficient
code generation in the caller.  This modified rule does not apply to
deleting destructors.  It also does not apply when making a virtual call
to a complete-object destructor, so that
<a href="#vtable-components"><code>this</code>-adjustment thunks</a>
do not need to adjust the return value after the call.

<p>
<a name="vcall">
<h3><a href="#vcall">3.2 Virtual Calls</a></h3>
</a>

<p>
<a name="vcall-general">
<h4><a href="#vcall-general"> 3.2.1 General </a></h4>

<p>
This section sketches the calling convention for virtual functions,
based on the above virtual table layout.
<i>See also the <a href=abi-examples.html#vcall>ABI examples</a>
document for motivating examples and potential implementations.</i>

<p>
We explain, at a high level,
what information must be present in the virtual table for a class A
which declares a virtual function f in order that,
given an pointer of type A*,
the caller can call the virtual function f.
This section does not specify exactly where that information is located
(see above),
nor does it specify how to convert a pointer to a class
derived from A to an A*,
if that is required.

<p>
When this section uses the term <i>function pointer</i> it is understood
that this term may refer either to a traditional function pointer
(i.e., a pointer to a GP/address pair) or a GP/address pair itself.
Which of these alternatives is actually used
is specified elsewhere in the ABI,
but is independent of the description in this section.

<p>
Throughout this section,
we assume that A is the class for which we are creating a virtual table,
B is the most derived class in the hierarchy,
and C is the class that contains C::f,
the unique final overrider for A::f.
This section specifies the contents of the f entry in the A-in-B virtual
table.
(If A is primary base in the hierarchy,
then the A-in-B virtual table will be shared
with the derived class virtual table --
but the contents of the A portion of that virtual table
will still be as specified here.)

<p>
In all cases, the <i>non-adjusting entry point</i> for a virtual
function expects the `this' pointer to point to an instance of the
class in which the virtual function is defined.
In other words, the non-adjusting entry point for C::f will expect
that its `this' pointer points to a C object.

<p>
<a name="vcall.vtable">
<h4><a href="#vcall.vtable"> 3.2.2 Virtual Table Components </a></h4>

<p>
For each virtual function declared in a class C,
we add an entry to its virtual table if one is not already there
(i.e. if it is not overriding a function in its primary base).
In particular, a declaration which overrides a function inherited from
a secondary base gets a new slot in the primary virtual table.
We do this to avoid useless adjustments when calling a virtual
function through a pointer to the most derived class.

<p>
The content of this entry for class A is a function pointer,
as determined by one of the following cases.
Recall that we are dealing with a hierarchy where B is most derived,
A is a direct (or indirect) base of B defining f,
and C contains the unique final overrider C::f of A::f.

<ol type=1>
<p>
<li> A = C
<p>
(In this case, we are creating either the primary virtual table for A,
or the A-in-B secondary virtual table.)
<p>
The virtual table contains a function pointer pointing to the
non-adjusting entry point for A::f.

<p>
<li> A != C
<p>
In this case, we are creating the A-in-B secondary virtual table.
<p>
The virtual table contains a pointer to an entry point that performs the
adjustment from an A* to a C*,
and then transfers control to the non-adjusting entry point for C::f.
</ol>

<p>
There are some exceptions to this determination of function pointers:
<ul>
<li>If the member function is deleted, no specific requirement is made
for the corresponding virtual table entry.  It may point to
__cxa_deleted_virtual (see <a href=#deleted-virtual>3.2.7 Deleted Virtual Function API</a>)
or to a wrapper function for __cxa_deleted_virtual (e.g., to adapt the calling convention).
It may also simply be null in such cases.
</li>
<li>Similarly, if C::f is a pure virtual function, no specific requirement is made
for the corresponding virtual table entry.  It may point to
__cxa_pure_virtual (see <a href=#pure-virtual>3.2.6 Pure Virtual Function API</a>)
or to a wrapper function for __cxa_pure_virtual (e.g., to adapt the calling convention).
It may also simply be null in such cases.
</li>
</ul>

<p>
When a class is used as a virtual base,
we add a vcall offset slot to the beginning of its virtual table for each of
the virtual functions it provides,
whether in its primary or secondary virtual tables.
Derived classes which override these functions may use the slots to
determine the adjustment necessary.


<p>
<a name="vcall.callee">
<h4><a href="#vcall.callee"> 3.2.3 Callee </a></h4>

<p>
For each direct or indirect base A of C that is not a morally virtual
base of C,
the compiler must emit, in the same object file as the code for C::f,
an <i>A-adjusting entry point</i> for C::f.
This entry point will expect that its <code>this</code> pointer
points to an A*,
and will convert it to a C*
(which merely requires adding a constant offset)
before transferring control to the non-adjusting entry point for C::f.

<p>
For each direct or indirect virtual base V of C such that V declares f,
the compiler must emit, in the same object file as the code for C::f,
a <i>V-adjusting entry point</i> for C::f.
This entry point will expect that its <code>this</code> pointer
points to the unique virtual V subobject of C.
(Note that there may in general be multiple V subobjects of C,
but that only one of them will be virtual.)
This entry point must load the vcall offset corresponding to f located
in the virtual table for V obtained via its <code>this</code> pointer,
extract the vcall offset corresponding to f located in that virtual table,
and add this offset to the <code>this</code> pointer.
(Note that, as specified in the data layout document,
when V is used as a virtual base,
its virtual table contains vcall offsets for every virtual function
declared in V or any of its bases.)
Then,
this entry point must transfer control to the non-adjusting entry point.

<a name="morally-virtual">
<p>
For each morally virtual base M of C
such that M is <i><b>not</b></i> a virtual base
(and therefore must be a subobject of a virtual base V),
and such that M declares f,
the compiler must emit,
in the same object file as the code for C::f,
an <i>M-adjusting entry point</i> for C::f.
This entry point will expect that its <code>this</code> pointer
points to an M*,
and will convert it to a V* (a fixed offset),
where V is the nearest virtual base to M
along the inheritance path from C to M.
Then, it will convert the V* to a C* by using the vcall offset
stored in the V's virtual table.

<p>
<a name="vcall.caller">
<h4><a href="#vcall.caller"> 3.2.4 Caller </a></h4>

<p>
When calling a virtual function f,
through a pointer of static type B*,
the caller

<ul>
<p>
<li>Selects a (possibly improper) subobject A of B
    such that A declares f.
    (In general, A may be the same as B.)
    (Note that A need not define f;
    it may contain either a definition of f,
    or a declaration of f as a pure virtual function.)

<p>
<li>Converts the B* to point to this subobject.
    (Call the resulting pointer `a'.)

<p>
<li>Uses the virtual table pointer contained in the A subobject to locate
    the function pointer through which to perform the call.

<p>
<li>Calls through this function pointer,
    passing `a' as the <code>this</code> pointer.
</ul>

<i>
<p>
(Note that in general it will be optimal to select the class which
contained the final overrider (i.e., C)
as the class to which the B* should be converted.
This class is always a satisfactory choice,
since it is known to contain a definition of f.
In addition, if the dynamic type of the object is B,
then C::f will be the function ultimately selected by the call,
which means that C's virtual table will
contain a pointer to the non-adjusting entry point,
meaning that no additional adjustments to the <code>this</code>
pointer will be required.

<p>
However, there may be cases in which choosing a different base
subobject could be superior.
For example, if there is an alternate base D which also declares f,
and a pointer to the D subobject is already available,
then it may be better to use the D subobject rather
than converting the B* to a C*,
in order to avoid the cost of the conversion.)
</i>


<p>
<a name="vcall.implementation">
<h4><a href="#vcall.implementation"> 3.2.5 Implementation </a></h4>

<p>
Note that the ABI only specifies the multiple entry points
for a virtual function and its associated thunks;
how those entry points are provided is unspecified.
An existing compiler which uses thunks with a different means of
adjusting the virtual table pointers
can be made compliant with this ABI by only adding the vcall offsets --
the thunks need not use them.
A more efficient implementation would be to emit all of the thunks
immediately before the non-adjusting entry point to the function.
Another might emit a new copy of the function for each entry point;
this is a quality of implementation issue.
<i>See further discussion of implementation in the
<a href=abi-examples.html#vcall-impl>ABI examples</a> document.</i>
</ul>


<p>
<a name="pure-virtual">
<h4><a href="#pure-virtual"> 3.2.6 Pure Virtual Function API </a></h4>

<p>
An implementation shall provide a standard entry point that a compiler
may reference in virtual tables to indicate a pure virtual function.
Its interface is:

<code><pre>
  extern "C" void __cxa_pure_virtual ();
</pre></code>

<p>
This routine will only be called if the user calls a non-overridden
pure virtual function, which has undefined behavior according to the
C++ Standard.
Therefore, this ABI does not specify its behavior,
but it is expected that it will terminate the program,
possibly with an error message.
</p>

<a name="deleted-virtual">
<h4><a href="#deleted-virtual"> 3.2.7 Deleted Virtual Function API</a></h4>

<p>
An implementation shall provide a standard entry point that a compiler
will reference in virtual tables to indicated a deleted virtual
function.  Its interface is:
</p>

<code><pre>
  extern "C" void __cxa_deleted_virtual ();
</pre></code>

<p>This routine shall not return and while this ABI does not otherwise
specify its behavior, it is expected that it will terminate the program,
possibly with an error message.
</p>

<p>
<a name="obj-ctor">
<h3><a href="#obj-ctor"> 3.3 Construction and Destruction APIs </a></h3>
</a>

<p>
This section describes APIs to be used for the construction and
destruction of objects.
This includes:
<ul>
<li> <a href=#subobj-ctor> 3.3.1 Subobject Construction and Destruction</a>
<li> <a href=#inh-ctor>    3.3.2 Construction by Inherited Constructor</a>
<li> <a href=#once-ctor>   3.3.3 One-time Construction API </a>
<li> <a href=#array-ctor>  3.3.4 Array Construction and Destruction API </a>
<li> <a href=#ctor-order>  3.3.5 Controlling Object Construction Order </a>
<li> <a href=#dso-dtor>    3.3.6 DSO Object Destruction API </a>
</ul>


<p>
<a name="subobj-ctor">
<h4><a href="#subobj-ctor"> 3.3.1 Subobject Construction and Destruction </a></h4>
</a>

<p>
The complete object constructors and destructors find the VTT,
described in Section 2.6, Virtual Tables During Object Construction,
via its mangled name.  They pass the address of the subobject's
sub-VTT entry in the VTT as a second parameter when calling the base
object constructors and destructors.  The base object constructors and
destructors use the addresses passed to initialize the primary virtual
pointer and virtual pointers that point to the classes which either
have virtual bases or override virtual functions with a virtual step
(have vcall offsets needing adjustment).

<p>
If a constructor calls constructors for base class
subobjects that do not need construction virtual tables,
e.g. because they have no virtual bases,
the construction virtual table parameter is not passed to the base class
subobject constructor,
and the base class subobject constructors use
their complete object virtual tables for initialization.

<p>
If a class has a non-virtual destructor, and a deleting destructor is
emitted for that class, the deleting destructor must correctly
handle the case that the <code>this</code> pointer is
<code>NULL</code>.  All other destructors, including deleting
destructors for classes with a virtual destructor, may assume that the
<code>this</code> pointer is not <code>NULL</code>.

<p>
<i>
Suppose we have a subobject class D that needs a construction virtual table,
derived from a base B that needs a construction virtual table as part of D,
and possibly from others that do not need construction virtual tables.
Then the sub-VTT and constructor code for D would look like the following:
</i>

<p>
<code><pre>
     // Sub-VTT for D (embedded in VTT for its derived class X):
     static vtable *__VTT__1D [1+n+m] =
	{ D primary vtable,
	  // The sub-VTT for B-in-D in X may have further structure:
	  B-in-D sub-VTT (n elements),
	  // The secondary virtual pointers for D's bases have elements
	  // corresponding to those in the B-in-D sub-VTT,
	  // and possibly others for virtual bases of D:
	  D secondary virtual pointer for B and bases (m elements) }; 

     D ( D *this, vtable **ctorvtbls )
     {
	// (The following will be unwound, not a real loop):
	for ( each base A of D ) {

	   // A "boring" base is one that does not need a ctorvtbl:
	   if ( ! boring(A) ) {
	     // Call subobject constructors with sub-VTT index
	     // if the base needs it -- only B in our example:
	      A ( (A*)this, ctorvtbls + sub-VTT-index(A) ); 

	   } else {
	     // Otherwise, just invoke the complete-object constructor:
	      A ( (A*)this );
	   }
	}

        // Initialize virtual pointer with primary ctorvtbls address
	// (first element):
        this->vptr = ctorvtbls+0;	// primary virtual pointer

	// (The following will be unwound, not a real loop):
	for ( each subobject A of D ) {
	
	   // Initialize virtual pointers of subobjects with ctorvtbls
	   // addresses for the bases 
	   if ( ! boring(A) ) {
	      ((A*)this)->vptr = ctorvtbls + 1+n + secondary-vptr-index(A);
		   // where n is the number of elements in the sub-VTTs
	    
	   } else {
	     // Otherwise, just use the complete-object vtable:
	      ((A *)this)->vptr = &(A-in-D vtable);
	   }
	}

        // Code for D constructor.
	...
      }
</pre></code>

</table>

<p>
A test program for this can be found in the
<a href=abi-examples.html#vtable-ctor>ABI Examples</a> document.


</dl>


<p>
<a name="inh-ctor"></a>
<h4><a href="#inh-ctor"> 3.3.2 Construction by Inherited Constructor</a></h4>

<p>
A constructor inherited from a base class can be used to initialize a derived
class object, if it is explicitly inherited by a <code>using</code>
declaration.  Formally, such initialization is not performed by a derived class
constructor, and instead the initialization expression itself directly
initializes each base class (recursively, if the constructor is inherited from
an indirect base class) and each non-static data member. To reduce code
duplication, this ABI permits such initialization to be factored out into an
<i>inheriting constructor</i> function.

<p>
An inheriting constructor describes the initialization that would be performed
when a constructor inherited from a base class is selected to initialize a
derived class, including the default-initialization of the other base classes
and the non-static data members of the derived class. If the inheriting
constructor is a base subobject constructor and the inherited constructor
constructs a morally virtual base subobject, the inheriting constructor does
not take any user-declared parameters; otherwise, it takes the same parameters
as the inherited constructor. In all other respects, an inheriting constructors
behaves the same as a constructor of the derived class.  For example:

<code><pre>
struct X { X(); };
struct A { A(int); };
struct B : A { using A::A; };
struct C : virtual B { using B::B; X x; };
struct D : C { using C::C; };
C c(0);
D d(0);

// The initializations of c and d behave as if they call C::C<sub>complete A(int)</sub>(0) and D::D<sub>complete A(int)</sub>(0):
D::D<sub>complete A(int)</sub>(int n) : B<sub>base A(int)</sub>(n), C<sub>base A(int)</sub>() {}	// _ZN1DCI11AEi
C::C<sub>complete A(int)</sub>(int n) : B<sub>base A(int)</sub>(n), x() {}      <sub></sub>     	// _ZN1CCI11AEi
C::C<sub>base A(int)</sub>() : /*no init for vbase B*/ x() {}        <sub></sub><sub></sub>     	// _ZN1CCI21AEi
B::B<sub>base A(int)</sub>(int n) : A(n) {}                          <sub></sub><sub></sub>     	// _ZN1BCI21AEi
</pre></code>

<p>
Inheriting constructors are not permitted to make copies of their parameters
when passing them to the inherited constructor. If it would not be possible to
transparently forward all parameters from the inheriting constructor to the
inherited constructor, an inheriting constructor cannot be used, and a
different implementation technique (such as emitting the initialization inline)
must be used instead.


<p>
<a name="once-ctor"></a>
<h4><a href="#once-ctor"> 3.3.3 One-time Construction API </a></h4>

<p>
As described in <a href=#guards>Section 2.8</a>, certain objects with
static storage duration have associated guard variables used to
support the requirement that they be initialized exactly once, the
first time the scope declaring them is entered.  An implementation
that does not anticipate supporting multi-threading may simply check
the first byte (i.e., the byte with lowest address) of that guard
variable, initializing if and only if its value is zero, and then
setting it to a non-zero value.

<p>
However, an implementation intending to support
automatically thread-safe, one-time initialization
(as opposed to requiring explicit user control for thread safety)
may make use of the following API functions:

<dl>

<dt><code><pre>
extern "C" int __cxa_guard_acquire ( __int64_t *guard_object );
</pre></code></dt>
<dd>
<p>
Returns 1 if the initialization is not yet complete; 0 otherwise.
This function is called before initialization takes place.  If this
function returns 1, either <code>__cxa_guard_release</code> or
<code>__cxa_guard_abort</code> must be called with the same argument.
The first byte of the <code>guard_object</code> is not modified by this 
function.

<p>
A thread-safe implementation will probably guard access to the first
byte of the <code>guard_object</code> with a mutex.  If this function
returns 1, the mutex will have been acquired by the calling thread.
</p>

</dd>

<dt><code><pre>
extern "C" void __cxa_guard_release ( __int64_t *guard_object );
</pre></code></dt>
<dd>
<p>
Sets the first byte of the guard object to a non-zero value.  This
function is called after initialization is complete.
</p>

<p> 
A thread-safe implementation will release the mutex acquired by
<code>__cxa_guard_acquire</code> after setting the first byte of the
guard object.
</p>

</dd>

<dt><code><pre>
extern "C" void __cxa_guard_abort ( __int64_t *guard_object );
</pre></code></dt>
<dd>

<p>
This function is called if the initialization terminates by throwing
an exception.
</p>

<p> 
A thread-safe implementation will release the mutex acquired by
<code>__cxa_guard_acquire</code>.
</p>

</dd>

</dl>

</pre></code>


<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>

<p>
The following is pseudo-code showing how these functions can be used:
<blockquote><code><pre>
  if (<i>obj_guard.first_byte</i> == 0) {
    if ( __cxa_guard_acquire (<i>&amp;obj_guard</i>) ) {
      try {
	<i>... initialize the object ...</i>;
      } catch (...) {
        __cxa_guard_abort (<i>&amp;obj_guard</i>);
        throw;
      }
      <i>... queue object destructor with __cxa_atexit() ...</i>;
      __cxa_guard_release (<i>&amp;obj_guard</i>);
    }
  }
</pre></code></blockquote>

<p>
An implementation need not include the simple inline test of the
initialization flag in the guard variable around the above sequence.
If it does so,
the cost of this scheme,
when run single-threaded with minimal versions of the above functions,
will be two extra function calls,
each of them accessing the guard variable,
the first time the scope is entered.

<p>
An implementation supporting thread-safety on multiprocessor systems
must also guarantee that references to the initialized object do not
occur before the load of the initialization flag.
On Itanium, this can be done by using a <code>ld1.acq</code> operation to
load the flag.

<p>
The intent of specifying an 8-byte structure for the guard variable,
but only describing one byte of its contents,
is to allow flexibility in the implementation of the API above.
On systems with good small lock support,
the second word might be used for a mutex lock.
On others, it might identify (as a pointer or index)
a more complex lock structure to use.
</i>


<p>
<a name="array-ctor">
<h4><a href="#array-ctor"> 3.3.4 Array Construction and Destruction API </a></h4>

<p>
An ABI-compliant system shall provide several runtime routines for use
in array construction and destruction.
They may be used by compilers, but their use is not required.
The required APIs are:

<dl>

<dt><code><pre>
extern "C" void * __cxa_vec_new (
	    size_t element_count,
	    size_t element_size,
	    size_t padding_size,
	    void (*constructor) ( void *this ),
	    void (*destructor) ( void *this ) );
</pre></code></dt>
<dd>
<p>Equivalent to <code>
<pre>
  __cxa_vec_new2(element_count, element_size, padding_size, constructor,
                 destructor, &::operator new[], &::operator delete[])
</pre></code></p>
</dd>

<dt><code><pre>
extern "C" void * __cxa_vec_new2 (
	    size_t element_count,
	    size_t element_size,
	    size_t padding_size,
	    void (*constructor) ( void *this ),
	    void (*destructor) ( void *this ),
	    void* (*alloc) ( size_t size ),
	    void (*dealloc) ( void *obj ) );
</pre></code></dt>
<dd>
<p>Given the number and size of elements for an array and the
non-negative size of prefix padding for a cookie, allocate space
(using <code>alloc</code>) for the array preceded by the specified
padding, initialize the cookie if the padding is non-zero, and call
the given constructor on each element.  Return the address of the
array proper, after the padding.</p>

<p>If <code>alloc</code> throws an exception, rethrow the exception.
If <code>alloc</code> returns <code>NULL</code>, return
<code>NULL</code>.  If the <code>constructor</code> throws an
exception, call <code>destructor</code> for any already constructed
elements, and rethrow the exception.  If the <code>destructor</code>
throws an exception, call <code>std::terminate</code>.</p>

<p>The constructor may be <code>NULL</code>, in which case it must
not be called.  If the <code>padding_size</code> is zero, the
<code>destructor</code> may be <code>NULL</code>; in that case it must
not be called.</p>

<p>Neither <code>alloc</code> nor <code>dealloc</code> may be
<code>NULL</code>.</p>

<p>If the computed size of the allocated array object (including space
for a cookie, if specified) would exceed the implementation-defined
limit, <code>std::bad_array_new_length</code> is thrown.</p>

</dd>

<dt><code><pre>
extern "C" void * __cxa_vec_new3 (
	    size_t element_count,
	    size_t element_size,
	    size_t padding_size,
	    void (*constructor) ( void *this ),
	    void (*destructor) ( void *this ),
	    void* (*alloc) ( size_t size ),
	    void (*dealloc) ( void *obj, size_t size ) );
</pre></code></dt>
<dd>
Same as <code>__cxa_vec_new2</code> except that the deallocation
function takes both the object address and its size.
</dd>

<dt><code><pre>
extern "C" void __cxa_throw_bad_array_new_length (void);
</pre></code></dt>
<dd>
Unconditionally throws <code>std::bad_array_new_length</code>.
May be invoked by the compiler when the number of array elements
expression of a <code>new[]</code> operation violates the requirements
of the C++ standard.
</dd>

<dt><code><pre>
extern "C" void __cxa_vec_ctor (
	    void *array_address,
	    size_t element_count,
	    size_t element_size,
	    void (*constructor) ( void *this ),
	    void (*destructor) ( void *this ) );
</pre></code></dt>
<dd>
Given the (data) address of an array,
not including any cookie padding,
and the number and size of its elements,
call the given constructor on each element.
If the constructor throws an exception,
call the given destructor for any already-constructed elements,
and rethrow the exception.
If the destructor throws an exception,
call <code>terminate()</code>.
The constructor and/or destructor pointers may be NULL.
If either is NULL, no action is taken when it would have been called.
</dd>

<dt><code><pre>
extern "C" void __cxa_vec_dtor (
	    void *array_address,
	    size_t element_count,
	    size_t element_size,
	    void (*destructor) ( void *this ) );
</pre></code></dt>
<dd>
Given the (data) address of an array,
the number of elements,
and the size of its elements,
call the given destructor on each element.
If the destructor throws an exception,
rethrow after destroying the remaining elements if possible.
If the destructor throws a second exception, call <code>terminate()</code>.
The destructor pointer may be NULL,
in which case this routine does nothing.
</dd>

<dt><code><pre>
extern "C" void __cxa_vec_cleanup (
	    void *array_address,
	    size_t element_count,
	    size_t element_size,
	    void (*destructor) ( void *this ) );
</pre></code></dt>
<dd>
Given the (data) address of an array,
the number of elements,
and the size of its elements,
call the given destructor on each element.
If the destructor throws an exception, call <code>terminate()</code>.
The destructor pointer may be NULL,
in which case this routine does nothing.
</dd>

<dt><code><pre>
extern "C" void __cxa_vec_delete (
	    void *array_address,
	    size_t element_size,
	    size_t padding_size,
	    void (*destructor) ( void *this ) );
</pre></code></dt>
<dd>
<p>
If the <code>array_address</code> is <code>NULL</code>, return
immediately.  Otherwise, given the (data) address of an array, the
non-negative size of prefix padding for the cookie, and the size of
its elements, call the given destructor on each element, using the
cookie to determine the number of elements, and then delete the space
by calling <code>::operator delete[](void *)</code>.
If the destructor throws an exception, rethrow after (a) destroying
the remaining elements, and (b) deallocating the storage.  If the
destructor throws a second exception, call <code>terminate()</code>.
If padding_size is 0, the destructor pointer must be NULL.  If the
destructor pointer is NULL, no destructor call is to be made.
</p>

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
The intent of this function is to permit an implementation to call
this function when confronted with an expression of the form
<code>delete[] p</code> in the source code, provided that the default
deallocation function can be used.  Therefore, the semantics
of this function are consistent with those required by the standard.
The requirement that the deallocation function be called even if the
destructor throws an exception derives from the resolution to DR 353
to the C++ standard, which was adopted in April, 2003.
</p>
</dd>

<dt><code><pre>
extern "C" void __cxa_vec_delete2 (
	    void *array_address,
	    size_t element_size,
	    size_t padding_size,
	    void (*destructor) ( void *this ),
	    void (*dealloc) ( void *obj ) );
</pre></code></dt>
<dd>
Same as <code>__cxa_vec_delete</code>,
except that the given function is used for deallocation
instead of the default delete function.
If <code>dealloc</code> throws an exception,
the result is undefined.
The <code>dealloc</code> pointer may not be NULL.
</dd>

<dt><code><pre>
extern "C" void __cxa_vec_delete3 (
	    void *array_address,
	    size_t element_size,
	    size_t padding_size,
	    void (*destructor) ( void *this ),
	    void (*dealloc) ( void *obj, size_t size ) );
</pre></code></dt>
<dd>
Same as <code>__cxa_vec_delete</code>,
except that the given function is used for deallocation
instead of the default delete function.
The deallocation function takes both the object address and its size.
If <code>dealloc</code> throws an exception,
the result is undefined.
The <code>dealloc</code> pointer may not be NULL.
</dd>

<a name="array-copy-ctor"></a>
<dt><code><pre>
extern "C" void __cxa_vec_cctor (
	    void *dest_array,
	    void *src_array,
	    size_t element_count,
	    size_t element_size,
	    void (*constructor) (void *destination, void *source),
	    void (*destructor) (void *));
</pre></code></dt>
<dd>
Given the (data) addresses of a destination and a source array,
an element count and an element size,
call the given copy constructor to copy each element from the
source array to the destination array.  The copy constructor's
arguments are the destination address and source address, respectively.
If an exception occurs,
call the given destructor (if non-NULL) on each copied element and rethrow.
If the destructor throws an exception, call <code>terminate()</code>.
The constructor and or destructor pointers may be NULL.
If either is NULL, no action is taken when it would have been called.
</dd>

</dl>


<p>
<a name="ctor-order">
<h4><a href="#ctor-order"> 3.3.5 Controlling Object Construction Order </a></h4>

<p>
<a name="ctor-order-motivation">
<h5><a href="#ctor-order-motivation"> 3.3.5.1 Motivation </a></h5>

<p>
<i>
The only requirement of the C++ Standard with respect to file scope
object construction order is that file scope objects
in a single object file are constructed in declaration order.
However, building large programs sometimes requires careful attention
to construction ordering for objects in different object files,
and a number of vendors have provided extra-lingual facilities to
control it.
This ABI does not require an implementation to support this capability,
but it specifies such a facility for those implementations that do.
</i>

<p>
This facility only controls construction order within a singled linked
object (executable or DSO).
Construction order between linked objects is determined by the
initialization ordering specified in the base ABI.

<p>
<a name="ctor-order-pragma">
<h5><a href="#ctor-order-pragma"> 3.3.5.2 Source Code API </a></h5>

<p>
A user may specify the construction priority with the pragma:
<code><pre>
    #pragma priority ( &lt;priority&gt; )
</pre></code>

The &lt;priority&gt; parameter specifies a 32-bit signed initialization
priority, with lower numbers meaning earlier initialization.
The range of priorities [MIN_INT .. MIN_INT+1023] is reserved
to the implementation.
The pragma applies to all file scope variables in the file where it
appears, from the point of appearance to the next priority pragma or
the end of the file.
Objects defined before any priority pragmas have a default priority of zero,
as do initialization actions specified by other means,
e.g. <code>DT_INIT_ARRAY</code> entries.
For consistency with the C++ Standard requirements on initialization order,
behavior is undefined unless the priorities appearing in a single file,
including any default zero priorities,
are in non-decreasing numeric (non-increasing priority) order.

<p>
Initialization entries with the same priority from different files
(or from other sources such as link command options)
will be executed in an unspecified order.

<p>
<a name="ctor-order-object-file">
<h5><a href="#ctor-order-object-file"> 3.3.5.3 Object File Representation </a></h5>

<p>
Initialization priority is represented in the object file by elements
of a target-specific section type,
<code><b>SHT_IA_64_PRIORITY_INIT</b></code>,
with section ID <code>0x79000000</code> on Itanium,
and section name <code>.priority_init</code>,
and attributes allowing writing but not execution.
The elements are structs:
<code><pre>
	typedef struct {
	  ElfXX_Word	pi_pri;
	  ElfXX_Addr	pi_addr;
	} ElfXX_Priority_Init;
</pre></code>
The field <code>pi_addr</code> is a function pointer,
as defined by the base ABI
(a pointer to a function descriptor on Itanium).
The function takes a single <code>unsigned int</code> priority parameter,
which performs some initialization at priority <code>pi_pri</code>.
The priority value is obtained from the signed int in the source pragma
by subtracting MIN_INT, so the default priority is -MIN_INT.
The section header field <code>sh_entsize</code> is 8 for ELF-32,
or 16 for ELF-64.

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
An implementation may initialize as many (or as few) objects of the
same priority as it chooses in a single such initialization function,
as long as the sequence of such initialization entries for a given file
preserves the source code order of objects to be initialized.
</i>


<p>
<a name="ctor-order-runtime">
<h5><a href="#ctor-order-runtime"> 3.3.5.4 Runtime Library Support </a></h5>

<p>
Each implementation supporting priority initialization shall provide
a runtime library function with prototype:
<code><pre>
    void __cxa_priority_init ( ElfXX_Priority_Init *pi, int cnt );
</pre></code>

It will be called with the address of a <code>cnt</code>-element
(sub-)vector of the priority initialization entries,
and must call each of them in order.
It will be called with the GP of the initialization entries.

<p>
<a name="ctor-order-linker">
<h5><a href="#ctor-order-linker"> 3.3.5.5 Linker Processing </a></h5>

<p>
The only required static linker processing is to concatenate the
<code>SHT_IA_64_PRIORITY_INIT</code> sections in link order,
which, given equal section IDs, section names, and section attributes
as specified above, is the default behavior specified by the generic
ABI for unknown section types.

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
Given minimum static linker processing,
an implementation supporting priority initialization would need to
include bracketing files in the link command that
(1) label the ends of the <code>SHT_IA_64_PRIORITY_INIT</code> section,
and (2) provide initial and final <code>DT_INIT_ARRAY</code> entries.
The initial <code>DT_INIT_ARRAY</code> entry would need to sort the
<code>SHT_IA_64_PRIORITY_INIT</code> section and call
<code>__cxa_priority_init</code> to run the constructors with negative
priority (in the source).
The final <code>DT_INIT_ARRAY</code> entry would need to call
<code>__cxa_priority_init</code> to run the constructors with
non-negative priority.
Other <code>DT_INIT_ARRAY</code> entries would thus run at the proper
point in the priority sequence.

<p>
A more ambitious linker implementation could sort the
<code>SHT_IA_64_PRIORITY_INIT</code> section at link time and fabricate
the code to call <code>__cxa_priority_init</code> at the beginning and
end.
At the extreme, it could even include other <code>DT_INIT_ARRAY</code>
entries in the <code>SHT_IA_64_PRIORITY_INIT</code> sequence at the
appropriate places and emit exactly one call to
<code>__cxa_priority_init</code>,
with no other entries in the <code>DT_INIT_ARRAY</code> section.

</i>


<p>
<a name="dso-dtor">
<h4><a href="#dso-dtor"> 3.3.6 DSO Object Destruction API </a></h4>

<p>
<a name="dso-dtor-motivation">
<h5><a href="#dso-dtor-motivation"> 3.3.6.1 Motivation </a></h5>

<p>
The C++ Standard requires that destructors be called for global objects
when a program exits in the opposite order of construction.
Most implementations have handled this by calling the C library
<code>atexit</code> routine to register the destructors.
This is problematic because the 1999 C Standard only requires that the
implementation support 32 registered functions,
although most implementations support many more.
More important,
it does not deal at all with the ability in most implementations to
remove DSOs from a running program image by calling
<code>dlclose</code> prior to program termination.

<p>
The API specified below is intended to provide
standard-conforming treatment during normal program exit,
which includes executing <code>atexit</code>-registered functions
in the correct sequence relative to constructor-registered destructors,
and reasonable treatment during early DSO unload (e.g. <code>dlclose</code>).

<p>
<a name="dso-dtor-runtime-data">
<h5><a href="#dso-dtor-runtime-data"> 3.3.6.2 Runtime Data Structure </a></h5>

<p>
The runtime library shall maintain a list of termination functions
with the following information about each:

<ul>
<li> A function pointer (a pointer to a function descriptor on Itanium).
<li> A void* operand to be passed to the function.
<li> A void* handle for the <i>home DSO</i> of the entry (below).
</ul>

<p>
The representation of this structure is implementation defined.
All references are via the API described below.

<p>
<a name="dso-dtor-runtime-api">
<h5><a href="#dso-dtor-runtime-api"> 3.3.6.3 Runtime API </a></h5>

<ol type=A>
<p>
<li> Object construction:
<p>
After constructing a global (or local static) object,
that will require destruction on exit,
a termination function is <i>registered</i> as follows:
<center><code>
extern "C" int __cxa_atexit ( void (*f)(void *), void *p, void *d );
</code></center>
This registration, e.g. <code>__cxa_atexit(f,p,d)</code>,
is intended to cause the call <code>f(p)</code> when DSO <code>d</code> is unloaded,
before all such termination calls registered before this one.
It returns zero if registration is successful, nonzero on failure.

<p>
The registration function is not called from within the constructor.

<p>
<li> User <code>atexit</code> calls:
<p>
When the user registers exit functions with <code>atexit</code>,
they should be registered with NULL parameters and DSO handles, i.e.
<center><code>
    __cxa_atexit ( f, NULL, NULL );
</code></center>
It is expected that implementations supporting both C and C++ will
integrate this capability into the libc <code>atexit</code>
implementation so that C-only DSOs will nevertheless interact with C++
programs in a C++-standard-conforming manner.
No user interface to <code>__cxa_atexit</code> is supported,
so the user is not able to register an <code>atexit</code> function
with a parameter or a home DSO.

<p>
<li> Termination:
<p>
When linking any DSO containing a call to <code>__cxa_atexit</code>,
the linker should define a hidden symbol <code>__dso_handle</code>,
with a value which is an address in one of the object's segments.
(It does not matter what address,
as long as they are different in different DSOs.)
It should also include a call to the following function in the FINI
list (to be executed first):
<center><code>
extern "C" void __cxa_finalize ( void *d );
</code></center>
The parameter passed should be <code>&__dso_handle</code>.

<p>
Note that the above can be accomplished either by explicitly providing
the symbol and call in the linker, or by implicitly including a
relocatable object in the link with the necessary definitions,
using a .fini_array section for the FINI call.
Also, note that these can be omitted for an object with no calls to
<code>__cxa_atexit</code>, but they can be safely included in all objects.

<p>
When <code>__cxa_finalize(d)</code> is called,
it should walk the termination function list,
calling each in turn if <code>d</code> matches
<code>__dso_handle</code> for the termination function entry.
If <code>d == NULL</code>, it should call all of them.
Multiple calls to <code>__cxa_finalize</code> shall not result in
calling termination function entries multiple times;
the implementation may either remove entries or mark them finished.

<p>
When the main program calls <code>exit</code>,
it must call any remaining <code>__cxa_atexit</code>-registered functions,
either by calling <code>__cxa_finalize(NULL)</code>,
or by walking the registration list itself.

<p>
Note that the destructors must be called by <code>__cxa_finalize()</code>
in the opposite of the order in which they were enqueued by
<code>__cxa_atexit</code>.

</ol>

<p>
Since <code>__cxa_atexit</code> and <code>__cxa_finalize</code>
must both manipulate the same termination function list,
they must be defined in the implementation's runtime library,
rather than in the individual linked objects.


<p>
<a name="demangler">
<h3><a href="#demangler"> 3.4 Demangler API </a></h3>

<p>
<b>Synopsis</b>:
<code><pre>
namespace abi {
  extern "C" char* __cxa_demangle (const char* mangled_name,
				   char* buf,
				   size_t* n,
				   int* status);
}
</pre>
</code>

<ul>
<p>
<li>
<code>mangled-name</code>
is a pointer to a null-terminated array of characters.
It may be either an external name, i.e. with a "_Z" prefix,
or an internal NTBS mangling, e.g. of a type for type_info.

<p>
<li>
<code>buf</code> may be null.
If it is non-null, then <code>n</code> must also be nonnull,
and <code>buf</code> is a pointer to an array, of at least <code>*n</code> characters,
that was allocated using malloc.

<p>
<li>
<code>status</code> points to an int that is used as an error indicator.
It is permitted to be null,
in which case the user just doesn't get any detailed error information.
</ul>

<p>
<b>Behavior</b>:
The return value is a pointer to a null-terminated array 
of characters, the demangled name.
Ambiguities are possible between extern "C" object names and type 
manglings,
e.g. "i" may be either an object named "i" or the built-in "int" type.
Such ambiguous arguments are assumed to be type manglings.  If the user has 
a set of external names to demangle, they should check that the names are
in fact mangled (that is, begin with "_Z") before passing them to 
<code>__cxa_demangle</code>.

<p>
If there is an error in demangling, the return value is a null pointer.
The user can examine *status to find out what kind of error occurred.
Meaning of error indications:
<ul>
<li> 0:  success
<li> -1: memory allocation failure
<li> -2: invalid mangled name
<li> -3: invalid arguments (e.g. buf nonnull and n null)
</ul>

<p>
<b>Memory management</b>: 
<ul>
<li> If <code>buf</code> is a null pointer,
    <code>__cxa_demangle</code> allocates a new buffer with
    <code>malloc</code>.  It stores the size of the buffer in
    <code>*n</code>, if <code>n</code> is not <code>NULL</code>.

 <li>If <code>buf</code> is not a null pointer, it must have been
    allocated with <code>malloc</code>.  If <code>buf</code> is not
    big enough to store the resulting demangled name,
    <code>__cxa_demangle</code> must either a) call <code>free</code>
    to deallocate <code>buf</code> and then allocate a new buffer
    with <code>malloc</code>, or b) call <code>realloc</code> to
    increase the size of the buffer.  In either case, the new buffer
    size will be stored in <code>*n</code>.
</ul>


<p> <hr> <p>
<a name="exceptions">
<h2><a href="#exceptions"> Chapter 4: Exception Handling </a></h2>
<p> <hr> <p>
See <a href="abi-eh.html">Exception Handling</a> document,
currently just the base psABI-level material,
and the
HP <a href="exceptions.pdf">exception handling</a> working paper,
8 December 1999.


<p> <hr> <p>
<a name="layout">
<h2><a href="#layout"> Chapter 5: Linkage and Object Files </a></h2>
<p> <hr> <p>


<a name="mangling">
<h3><a href="#mangling"> 5.1 External Names (a.k.a. Mangling) </a></h3>

<p>
<a name="mangling-general">
<h4><a href="#mangling-general"> 5.1.1 General </a></h4>

<p>
This section specifies the <i>mangling</i>, i.e. encoding,
of external names (external in the sense of being visible
outside the object file where they occur).  The encoding is
formalized as a derivation grammar along with the explanatory
text, in a modified BNF with the following conventions:
<ul>
<li> Alternatives are given on separate lines.
<li> References to non-terminals are delimited by angle brackets
     <code class=mangle>&lt;&gt;</code>.
<li> Italicized text in references to non-terminals describes or
     limits what is mangled by the reference, but it does not
     affect the formal grammar.  For example,
     <code class=mangle>&lt;<i>function</i> <a href="#mangle.name">name</a>&gt;</code> is the same as
     <code class=mangle>&lt;<a href="#mangle.name">name</a>&gt;</code>,
     but it means this derivation rule should be used only for
     the names of functions.
<li> Spaces are to be ignored.
<li> Text beginning with <code class=mangle>#</code> is a comment,
     to be ignored until the end of the line.  Comments are often
     used to describe in what case an alternative should be used.
<li> Sequences of items in square brackets
     <code class=mangle>[]</code> are optional.
<li> Sequences of items in parentheses
     <code class=mangle>()</code> are groups for the purposes of
     <code class=mangle>*</code> and <code class=mangle>+</code>.
<li> An asterisk <code class=mangle>*</code> allows the preceding
     item to repeat 0 or more times.
<li> A plus sign <code class=mangle>+</code> allows the preceding
     item to repeat 1 or more times.
<li> All other characters are terminals, representing themselves.
</ul>

<p>
See the separate <a href=abi-mangling.html>table</a>
summarizing the encoding characters used as terminals.
Also see additional <a href=abi-examples.html#mangling>mangling examples</a>
in the separate ABI examples document.

<p>
In the various explanatory examples,
we use <code>Ret?</code> for an unknown function return type
(i.e. that is not given by the mangling),
or <code>Type?</code> for an unknown data type.

<p>
Mangled names containing <code class=mangle>$</code> or
<code class=mangle>.</code> are reserved for private implementation
use. Names produced using such extensions are inherently non-portable
and should be given internal linkage where possible.

<p>
<a name="mangling-structure">
<h4><a href="#mangling-structure"> 5.1.2 General Structure </a></h4>

<p>
Entities with C linkage and global namespace variables are not mangled.
Mangled names have the general structure:
<pre><font color=blue><code>
    &lt;<a name="mangle.mangled-name">mangled-name</a>&gt; ::= _Z &lt;<a href="#mangle.encoding">encoding</a>&gt;
                   ::= _Z &lt;<a href="#mangle.encoding">encoding</a>&gt; . &lt;vendor-specific suffix&gt;
    &lt;<a name="mangle.encoding">encoding</a>&gt; ::= &lt;<i>function</i> <a href="#mangle.name">name</a>&gt; &lt;<a href="#mangle.bare-function-type">bare-function-type</a>&gt;
	       ::= &lt;<i>data</i> <a href="#mangle.name">name</a>&gt;
	       ::= &lt;<a href="#mangle.special-name">special-name</a>&gt;
</pre></font></code>

Thus, a name is mangled by prefixing "_Z" to an encoding of its name,
and in the case of functions its type (to support overloading).
At this top level,
function types do not have the special delimiter characters required
when nested (see below).  Furthermore, in the case of instances (or
explicit specializations) of function templates and member function
templates (but not ordinary member functions of class templates), the 
<code>&lt;<a href="#mangle.bare-function-type">bare-function-type</a>&gt;</code> encoding is that of the type
expressed in the template (i.e., one likely involving template
parameters).
The type is omitted for variables and static data members.

<p>
A <code>&lt;<a href="#mangle.mangled-name">mangled-name</a>&gt;</code>
containing a period represents a vendor-specific version or portion
of the entity named by the <code>&lt;<a href="#mangle.encoding">encoding</a>&gt;</code>
prior to the first period. There is no restriction on the characters
that may be used in the suffix following the period.

<p>
ABI mangling is designed to ensure that entities receive the
same mangling if and only if they are the same entity according
to the C++ standard's one-definition rule (ODR) and the
various rules for declaration matching (such as
<span class=cxxref>[over.dcl]</span> and
<span class=cxxref>[temp.over]</span>.  Those rules are quite
complex, and they dictate the results of mangling, and so it
should not be surprising that the mangling rules are also complex.
The ABI must be closely involved with the evolution of those
language rules to ensure that they remain implementable with
mangling.  When the rules say that an ODR violation has
undefined behavior, that is often because it is impractical to
ensure that the entities involved will have different manglings.
Similarly, when the rules forbid certain constructs from the
signature of a declaration, that is often because that construct
would create unreasonable problems for mangling.

<p>
Mangling must sometimes be able to distinguish entities that
are not equivalent under the ODR and declaration-matching
rules.  This is true even if the entities would not be
distinguishable by C++ code because, say, every name lookup
which included both of them would be ambiguous.  For example,
different translation units might declare similar but not
eqivalent function templates in the same namespace:

<pre>// a.cpp:
template &lt;int&rt; void foo() {}
template &lt;&rt; void foo<0>();

// b.cpp:
template &lt;long&rt; void foo() {}
template &lt;&rt; void foo<0>();</pre>

<p>
The C++ standard grants implementations broad flexibility to
ignore certain kinds of differences.  For example, the rules
in <span class=cxxref>[temp.over.link]</span> for
functionally-equivalent function templates could be used to
shorten manglings in certain cases where instantiation-dependence
provably has no effect.  This ABI generally does not take
advantage of that flexibility.

<a name="mangling.dependent">
<h5><a href="#mangling.dependent">Dependent constructs in templates</a></h5>

<p>
It is sometimes necessary to mangle unresolved and uninstantiated
language constructs such as types and expressions that appear
within templates.  This accounts for a lot of the complexity of
entity mangling in this ABI.

<p>
In many places, the mangling grammar formally allows a single
construct to be mangled in one of several different ways.
Usually there is one production which allows a fully-resolved
value or entity reference, and there is another production that
allows an expression or unresolved entity reference.  As an
example, this can be clearly seen in the mangling for
<a href="#mangle.array-type">array types</a>, which gives
one mangling for a constant bound and another for an expression.

<p>
There are two reasons for this.  First, manglings using the
fully-resolved case are often significantly more compact.
More importantly, though, the language often treat dependent
and non-dependent constructs differently.  For example,
<span class=cxxref>[temp.over.link]</span> gives rules for
when two expressions that involve template parameters are
considered equivalent, and those rules are reflected in
this ABI's expression mangling rules.  Conversely, expressions
that don't involve template parameters but are used in
constant-evaluated contexts (such an array length) are
considered to be equivalent if and only if they resolve
to the same value.  Mangling a non-dependent expression using
its expression structure could incorrectly produce different
manglings for different expressions that resolve to the same
value, and it could incorrectly produce the same mangling for
xpressions that resolve to different values but happen to be
spelled the same.

<p>
It is therefore important to use the right production given
the dependence of the construct in question.  The standard
defines several different kinds of dependence, such as
<i>value dependence</i> and <i>type dependence</i>.  In
general, the rule that should be used in mangling is
<a href="#instantiation-dependent"><i>instantiation
dependence</i></a>: if a construct in instantiation-dependent,
it should use the general production, and otherwise it
should use the narrow production.  The grammar below will
state clearly when certain productions are only for
instantiation-dependent cases.

<a name="mangle.anonymous">
<h5><a href="#mangling.anonymous">Anonymous entities</a></h5>

<p>
For the purposes of mangling, the name of an anonymous union is
considered to be the name of the first named data member found by a
pre-order, depth-first, declaration-order walk of the data members of
the anonymous union.  If there is no such data member (i.e., if all of
the data members in the union are unnamed), then there is no way for a
program to refer to the anonymous union, and there is therefore no
need to mangle its name.
</p>

<p>
All of these examples:
<blockquote><code><pre>
union { int i; int j; };
union { union { int : 7 }; union { int i; }; };
union { union { int j; } i; };
</pre></code></blockquote>
are considered to have the name <code>i</code> for the purposes of
mangling.
</p>

<a name="mangle.name">
<h5><a href="#mangle.name">Names</a></h5>

<p>In general, the mangling of an entity's name depends on where it is
declared.  Entities declared at global scope, or in namespace
<code>std</code>, are mangled as unscoped names.  Entities declared
within a function, including members of local classes, are mangled
with &lt;<a href="#mangle.local-name">local-name</a>&gt;.  Entities
declared in a namespace or class scope are mangled with
&lt;<a href="#mangle.nested-name">nested-name</a>&gt;.  When the actual
entity is not known statically, as can occur in a dependent function
template signature, the name is mangled with
&lt;<a href="#mangle.unresolved-name">unresolved-name</a>&gt;.

<p>The manglings of template specializations and non-template entities
closely overlap, but they can generally be disambiguated by whether
the name is followed by the <code><font color="blue">I</font></code>
which starts a &lt;<a href="#mangle.template-args">template-args</a>&gt;
production.

<pre><font color=blue><code>
    &lt;name&gt; ::= &lt;<a href="#mangle.nested-name">nested-name</a>&gt;
	   ::= &lt;<a href="#mangle.unscoped-name">unscoped-name</a>&gt;
	   ::= &lt;<a href="#mangle.unscoped-template-name">unscoped-template-name</a>&gt; &lt;<a href="#mangle.template-args">template-args</a>&gt;
	   ::= &lt;<a href="#mangle.local-name">local-name</a>&gt;	# See <a href="#mangling-scope">Scope Encoding</a> below

    &lt;<a name="mangle.unscoped-name">unscoped-name</a>&gt; ::= &lt;<a href="#mangle.unqualified-name">unqualified-name</a>&gt;
		    ::= St &lt;<a href="#mangle.unqualified-name">unqualified-name</a>&gt;   # ::std::

    &lt;<a name="mangle.unscoped-template-name">unscoped-template-name</a>&gt; ::= &lt;<a href="#mangle.unscoped-name">unscoped-name</a>&gt;
			     ::= &lt;<a href="#mangle.substitution">substitution</a>&gt;
</pre></font></code>

<p>A &lt;<a href="#mangle.nested-name">nested-name</a>&gt; recursively
breaks down the enclosing scope until the global scope is reached.  A
&lt;<a href="#mangle.prefix">prefix</a>&gt; refers to a scope;
confusingly, a &lt;<a href="#mangle.template-prefix">template-prefix</a>&gt;
actually refers to a template name (without template arguments).

<p>Class and namespace members are always mangled with a
&lt;<a href="#mangle.nested-name">nested-name</a>&gt;, even if they are
template specializations and there is an existing substitution for the
template (and therefore the name could in principle be mangled as if
it were a &lt;<a href="#mangle.unscoped-template-name">unscoped-template-name</a>&gt;).

<p>When a &lt;<a href="#mangle.nested-name">nested-name</a>&gt; refers
to a non-static class member function, the CV-qualifiers and
ref-qualifiers of the function are prefixed to the compound name.
This prefix is required even when the member function is a
specialization of a substituted template and therefore those
qualifiers could be inferred from the substitution target.

<pre><code><font color=blue>
    &lt;<a name="mangle.nested-name">nested-name</a>&gt; ::= N [&lt;<a href="#mangle.CV-qualifiers">CV-qualifiers</a>&gt;] [&lt;<a href="#mangle.ref-qualifier">ref-qualifier</a>&gt;] &lt;<a href="#mangle.prefix">prefix</a>&gt; &lt;<a href="#mangle.unqualified-name">unqualified-name</a>&gt; E
		  ::= N [&lt;<a href="#mangle.CV-qualifiers">CV-qualifiers</a>&gt;] [&lt;<a href="#mangle.ref-qualifier">ref-qualifier</a>&gt;] &lt;<a href="#mangle.template-prefix">template-prefix</a>&gt; &lt;<a href="#mangle.template-args">template-args</a>&gt; E

    &lt;<a name="mangle.prefix">prefix</a>&gt; ::= &lt;<a href="#mangle.unqualified-name">unqualified-name</a>&gt;                 # global class or namespace
             ::= &lt;<a href="#mangle.prefix">prefix</a>&gt; &lt;<a href="#mangle.unqualified-name">unqualified-name</a>&gt;        # nested class or namespace
	     ::= &lt;<a href="#mangle.template-prefix">template-prefix</a>&gt; &lt;<a href="#mangle.template-args">template-args</a>&gt;  # class template specialization
             ::= &lt;<a href="#mangle.closure-prefix">closure-prefix</a>&gt;                   # initializer of a variable or data member
             ::= &lt;<a href="#mangle.template-param">template-param</a>&gt;                   # template type parameter
             ::= &lt;<a href="#mangle.decltype">decltype</a>&gt;                         # decltype qualifier
	     ::= &lt;<a href="#mangle.substitution">substitution</a>&gt;

    &lt;<a name="mangle.template-prefix">template-prefix</a>&gt; ::= &lt;<i>template</i> <a href="#mangle.unqualified-name">unqualified-name</a>&gt;           # global template
                      ::= &lt;<a href="#mangle.prefix">prefix</a>&gt; &lt;<i>template</i> <a href="#mangle.unqualified-name">unqualified-name</a>&gt;  # nested template
                      ::= &lt;<a href="#mangle.template-param">template-param</a>&gt;                      # template template parameter
                      ::= &lt;<a href="#mangle.substitution">substitution</a>&gt;

    &lt;<a name="mangle.unqualified-name">unqualified-name</a>&gt; ::= [&lt;<a href="#mangle.module-name">module-name</a>&gt;] &lt;<a href="#mangle.operator-name">operator-name</a>&gt; [&lt;<a href="#mangle.abi-tags">abi-tags</a>&gt;]
                       ::= &lt;<a href="#mangle.ctor-dtor-name">ctor-dtor-name</a>&gt;  
                       ::= [&lt;<a href="#mangle.module-name">module-name</a>&gt;] &lt;<a href="#mangle.source-name">source-name</a>&gt;   
                       ::= [&lt;<a href="#mangle.module-name">module-name</a>&gt;] &lt;<a href="#mangle.unnamed-type-name">unnamed-type-name</a>&gt;   
                       ::= [&lt;<a href="#mangle.module-name">module-name</a>&gt;] DC &lt;<a href="#mangle.source-name">source-name</a>&gt;+ E      # structured binding declaration

    &lt;<a name="mangle.source-name">source-name</a>&gt; ::= &lt;<i>positive length</i> <a href="#mangle.number">number</a>&gt; &lt;<a href="#mangle.identifier">identifier</a>&gt;
    &lt;<a name="mangle.identifier">identifier</a>&gt; ::= &lt;<i>unqualified source code identifier</i>>

</pre></code></font>

<p>
&lt;<a href="#mangle.identifier">identifier</a>&gt; is a pseudo-terminal representing the characters in the unqualified identifier for the entity in the source code.  This ABI does not yet specify a mangling for identifiers containing characters outside of <code>_A-Za-z0-9</code>.

<p>
Note that &lt;<a href="#mangle.source-name">source-name</a>&gt; in the productions for &lt;<a href="#mangle.unqualified-name">unqualified-name</a>&gt;
may be either a function or data object name when derived from &lt;<a href="#mangle.name">name</a>&gt;,
or a class or enum name when derived from &lt;<a href="#mangle.type">type</a>&gt;.

<a name="mangle.module">
<h5><a href="mangle.module">Modules</a></h5>

<p>C++20 modules add a new linkage kind &mdash; module-linkage. This
is implemented by extending the mangling scheme to encode module
attachment. The symbols themselves will have the existing external
and/or weak/comdat ELF linkage. The <em>strong-ownership</em> model is
implemented &mdash; the symbols of exported entities with named-module
attachment are mangled with a module-name component.

<pre><code><font color=blue>
    &lt;<a name="mangle.module-name">module-name</a>&gt; ::= &lt;<a href="#mangle.module-component">module-component</a>&gt;
                  ::= &lt;<a href="#mangle.module-component">module-name</a>&gt; &lt;<a href="#mangle.module-component">module-component</a>&gt;
                  ::= &lt;<a href="#mangle.substitution">substitution</a>&gt;
    &lt;<a name="mangle.module-component">module-component</a>&gt; ::= W &lt;<a href="#mangle.source-name">source-name</a>&gt;
                       ::= W P &lt;<a href="#mangle.source-name">source-name</a>&gt;  # First component of partition
</font></code></pre>

<p>The &lt;module-name&gt; component is prefixed to the
namespace-scope entity with named-module attachment.  Module
partitions are only applicable for global initializers.
&lt;module-name&gt;s are substitutable, using the same sequence
numbering as other substitutable components. However, the
&lt;module-name&gt; substitutions are orthogonal, and attach
independently to the
&lt;<a href="#mangle.source-name">source-name</a>&gt; they prefix. If
the &lt;<a href="#mangle.source-name">source-name</a>&gt; is
subtitutable, its substitituion includes its module attachment.
Notice this introduces an ambiguity in the grammar, which can be
resolved by inspecting whether a substition refers to a
&lt;module-name&gt; or another entity.

For example:
<pre>
  export module Foo:part;
  export struct Quux;
  export void Foo (Quux *) {}; //  mangles as _ZW3Foo3FooPS_4Quux
</pre>

<a name="mangle.abi-tag">
<h5><a href="#mangle.abi-tag">ABI tags</a></h5>

<p>The GNU <code>abi_tag</code> attribute can be applied to a variable,
function, inline namespace, class, or enumeration.  The
&lt;<a href="#mangle.unqualified-name">unqualified-name</a>&gt; for a tagged
variable, function, or type includes a representation of the tags on that
entity, in alphabetical order:
<pre><code><font color=blue>
    &lt;<a name="mangle.abi-tags">abi-tags</a>&gt; ::= &lt;<a href="#mangle.abi-tag">abi-tag</a>&gt; [&lt;<a href="#mangle.abi-tags">abi-tags</a>&gt;]
    &lt;<a name="mangle.abi-tag">abi-tag</a>&gt; ::= B &lt;<a href="#mangle.source-name">source-name</a>&gt;
</font></code></pre>

For example:
<pre>
  struct [[gnu::abi_tag ("foo","bar")]] A { }; // mangles as 1AB3barB3foo
</pre>

If a name that would use a built-in
&lt;<a href="#mangle.substitution">substitution</a>&gt; has ABI tags, the tags
are appended to the substitution; the result is a substitutable component.

<pre>
  namespace std
  {
    template &lt;class T&gt; struct char_traits { /* ... */ };
    template &lt;class T&gt; struct allocator { /* ... */ };
    template &lt;class T, class R = char_traits&lt;T&gt;, class A = allocator&lt;T&gt;&gt;
      struct [[gnu::abi_tag ("X")]] basic_string { /* ... */ };
    using string = basic_string&lt;char&gt;;
  }

  void f(std::string, std::string) { } // mangles as _Z1fSsB1XS_
</pre>

If part of a declaration's type is not represented in the mangling, i.e. the
type of a variable or a return type that is not represented in the mangling of
a function, any ABI tags on that type (or components of a compound type) that
are not also present in a mangled part of the type are applied to the name of
the declaration.  Note that there is no similar tag propagation from members or
bases to a class type, as that would be impossible for incomplete types.

<p>Note that for member functions of a class template that are not member
templates, the type in question is that of the instantiation, so tags that
appear only in the template do not affect mangling:

<pre>
  struct [[gnu::abi_tag ("foo")]] A
  {
    template &lt;class T&gt; static T f();
    template &lt;class T&gt; static A g();
  };

  template &lt;class T> struct B
  {
    static decltype(A::f&lt;T&gt;()) fa(decltype(A::f&lt;T&gt;()));
    static decltype(A::f&lt;T&gt;()) fv();
    static decltype(A::g&lt;T&gt;()) ga(decltype(A::g&lt;T&gt;()));
    static decltype(A::g&lt;T&gt;()) gv();
  };

  int main()
  {
    // decltype(A::f&lt;T&gt;()) resolves to int
    B&lt;int&gt;::fa(0);   // _ZN1BIiE2faEi
    B&lt;int&gt;::fv();    // _ZN1BIiE2fvEv
    // decltype(A::g&lt;T&gt;()) resolves to A, which has a tag
    B&lt;int&gt;::ga(A()); // _ZN1BIiE2gaE1AB3foo
    B&lt;int&gt;::gv();    // _ZN1BIiE2gvB3fooEv
  }
</pre>

<p>If no arguments are specified for the attribute on an inline namespace, the
namespace has its own name as a tag.  Tags on an inline namespace are not
represented in the mangled name of the namespace, but they are subject to the
above tag propagation.  For example:

<pre>
  inline namespace [[gnu::abi_tag]] Foo {
    struct A {};
    A f() { } // mangles as _ZN3Foo1fEv
  }
  template &lt;class T&gt; struct B { };
  typedef void (*fp)(B&lt;A&gt;);
  fp p;      // mangles as _Z1pB3Foo
  A g(A) { } // mangles as _Z1gN3Foo1AE
</pre>

<a name="mangle.number">
<h5><a href="#mangle.number">Numbers</a></h5>

<pre><code><font color=blue>    &lt;<a name="mangle.number">number</a>&gt; ::= [n] &lt;<i>non-negative decimal integer</i>>
</font></code></pre>

<p>
&lt;<a href="#mangle.number">number</a>&gt; is a pseudo-terminal representing a decimal integer,
with a leading 'n' for negative integers.
It is used in &lt;<a href="#mangle.source-name">source-name</a>&gt; to provide the byte
length of the following identifier.
&lt;<a href="#mangle.number">number</a>&gt;s appearing in mangled names never have leading zeroes,
except for the value zero, represented as '0'.

<a name="mangle.seq-id">
<h5><a href="#mangle.seq-id">Sequence numbers</a></h5>

<pre><code><font color=blue>    &lt;seq-id&gt; ::= &lt;<i>0-9A-Z</i>&gt;+
</font></code></pre>

<p>A &lt;<a href="#mangle.seq-id">seq-id</a>&gt; is a sequence number in base 36, using digits and upper case letters.  Generally, wherever &lt;<a href="#mangle.seq-id">seq-id</a>&gt; appears, the first element is encoded by the absence of a number, and the remainder of the sequence is encoded starting at 0.  As with &lt;<a href="#mangle.number">number</a>&gt;, a &lt;<a href="#mangle.seq-id">seq-id</a>&gt; has a leading zero only if that is the only digit.

<p>For example, <a href="#mangle.compression">substitutions</a> are mangled as <code><font color=blue>S [&lt;<a href="#mangle.seq-id">seq-id</a>&gt;] _</font></code>.  The first substitutable entity is encoded as <code>S_</code>, i.e. with no number.  The second is encoded as <code>S0_</code>, the third as <code>S1_</code>, the twelfth as <code>SA_</code>, the thirty-eighth as <code>S10_</code>, etc.

<p><a name="mangling-operator">
<h4><a href="#mangling-operator"> 5.1.3 Operator Encodings </a></h4>

<p>
Operators appear as function names,
and in nontype template argument expressions.
Unlike Cfront,
unary and binary operators using the same symbol have different encodings.
Most operators are encoded using exactly two letters,
the first of which is lowercase.

<pre><font color=blue><code>
  &lt;<a name="mangle.operator-name">operator-name</a>&gt; ::= nw	# new           
		  ::= na	# new[]
		  ::= dl	# delete        
		  ::= da	# delete[]      
		  ::= aw	# co_await      
		  ::= ps        # + (unary)
		  ::= ng	# - (unary)     
		  ::= ad	# & (unary)     
		  ::= de	# * (unary)     
		  ::= co	# ~             
		  ::= pl	# +             
		  ::= mi	# -             
		  ::= ml	# *             
		  ::= dv	# /             
		  ::= rm	# %             
		  ::= an	# &             
		  ::= or	# |             
		  ::= eo	# ^             
		  ::= aS	# =             
		  ::= pL	# +=            
		  ::= mI	# -=            
		  ::= mL	# *=            
		  ::= dV	# /=            
		  ::= rM	# %=            
		  ::= aN	# &=            
		  ::= oR	# |=            
		  ::= eO	# ^=            
		  ::= ls	# <<            
		  ::= rs	# >>            
		  ::= lS	# <<=           
		  ::= rS	# >>=           
		  ::= eq	# ==            
		  ::= ne	# !=            
		  ::= lt	# <             
		  ::= gt	# >             
		  ::= le	# <=            
		  ::= ge	# >=            
		  ::= ss	# &lt;=>           
		  ::= nt	# !             
		  ::= aa	# &&            
		  ::= oo	# ||            
		  ::= pp	# ++ (postfix in &lt;<a href="#mangle.expression">expression</a>&gt; context)
		  ::= mm	# -- (postfix in &lt;<a href="#mangle.expression">expression</a>&gt; context)           
		  ::= cm	# ,             
		  ::= pm	# ->*           
		  ::= pt	# ->            
		  ::= cl	# ()            
		  ::= ix	# []            
		  ::= qu	# ?             
		  ::= cv &lt;<a href="#mangle.type">type</a>&gt;	# (cast)
                  ::= li &lt;<a href="#mangle.source-name">source-name</a>&gt;          # operator ""
		  ::= v &lt;<a href="#mangle.digit">digit</a>&gt; &lt;<a href="#mangle.source-name">source-name</a>&gt;	# vendor extended operator
</pre></font></code>

<p>
Vendors who define builtin extended operators (e.g. <code>__imag</code>)
shall encode them as a 'v' prefix followed by
the operand count as a single decimal digit, and
the name in &lt;length,ID> form.
</p>

<p><img src=warning.gif alt="<b>NOTE</b>:" /><i> 
For a user-defined conversion operator the result type (i.e., the type
to which the operator converts) is part of the mangled name of the
function.  If the conversion operator is a member template, the result
type will appear before the template parameters.  There may be forward
references in the result type to the template parameters.
</i></p>

<p>
<a name="mangling-special">
<h4><a href="#mangling-special"> 5.1.4 Other Special Functions and Entities </a></h4>

<p>
<a name="mangling-special-vtables">
<h5><a href="#mangling-special-vtables"> 5.1.4.1 Virtual Tables and RTTI </a></h5>

<p>
Associated with a virtual table are several entities with mangled
external names: the virtual table itself, the VTT for construction,
the typeinfo structure, and the name it references.
Each has a &lt;<a href="#mangle.special-name">special-name</a>&gt; encoding that is a simple two-character code,
prefixed to the type encoding for the class to which it applies.

<pre><font color=blue><code>
  &lt;<a name="mangle.special-name">special-name</a>&gt; ::= TV &lt;<a href="#mangle.type">type</a>&gt;	# virtual table
		 ::= TT &lt;<a href="#mangle.type">type</a>&gt;	# VTT structure (construction vtable index)
		 ::= TI &lt;<a href="#mangle.type">type</a>&gt;	# typeinfo structure
		 ::= TS &lt;<a href="#mangle.type">type</a>&gt;	# typeinfo name (null-terminated byte string)
</pre></font></code>

<p>
<a name="mangling-special-thunks">
<h5><a href="#mangling-special-thunks"> 5.1.4.2 Virtual Override Thunks </a></h5>

<p>
Virtual function override thunks come in two forms.
Those overriding from a non-virtual base,
with fixed <code>this</code> adjustments,
use a "Th" prefix and encode the required adjustment offset,
probably negative, indicated by a 'n' prefix,
and the encoding of the target function.
Those overriding from a virtual base must encode two offsets
after a "Tv" prefix.
The first is the constant adjustment to the nearest virtual base
(of the full object),
of which the defining object is a non-virtual base.
It is coded like the non-virtual case,
with a 'n' prefix if negative.
The second offset identifies the vcall offset in the nearest virtual base,
which will be used to finish adjusting <code>this</code> to the full object.
After these two offsets comes the encoding of the target function.
The target function encodings of both thunks incorporate the function type;
no additional type is encoded for the thunk itself.

<pre><font color=blue><code>
  &lt;<a name="mangle.special-name">special-name</a>&gt; ::= T &lt;<a href="#mangle.call-offset">call-offset</a>&gt; &lt;<i>base</i> <a href="#mangle.encoding">encoding</a>&gt;
		      # <i>base</i> is the nominal target function of thunk
  &lt;<a name="mangle.call-offset">call-offset</a>&gt; ::= h &lt;<a href="#mangle.nv-offset">nv-offset</a>&gt; _
		::= v &lt;<a href="#mangle.v-offset">v-offset</a>&gt; _
  &lt;<a name="mangle.nv-offset">nv-offset</a>&gt; ::= &lt;<i>offset</i> <a href="#mangle.number">number</a>&gt;
		      # non-virtual base override
  &lt;<a name="mangle.v-offset">v-offset</a>&gt;  ::= &lt;<i>offset</i> <a href="#mangle.v-offset">number</a>&gt; _ &lt;<i>virtual offset</i> <a href="#mangle.number">number</a>&gt;
		      # virtual base override, with vcall offset

</pre></font></code>

<p>
Virtual function override thunks with covariant returns are twice as complex.  
Just as normal virtual function override thunks must adjust the <i>this</i>
pointer before calling the base function,
those with covariant returns must adjust the return pointer after they
return from the base function.
So the mangling must also encode a fixed offset to a non-virtual base,
and possibly an offset to a vbase offset in the vtable to get to the
virtual base containing the result subobject.
We achieve this by encoding two &lt;<a href="#mangle.call-offset">call-offset</a>&gt; components,
either of which may be either virtual or non-virtual.

<pre><font color=blue><code>
  &lt;<a name="mangle.special-name">special-name</a>&gt; ::= Tc &lt;<a href="#mangle.call-offset">call-offset</a>&gt; &lt;<a href="#mangle.call-offset">call-offset</a>&gt; &lt;<i>base</i> <a href="#mangle.encoding">encoding</a>&gt;
		      # <i>base</i> is the nominal target function of thunk
		      # first <i>call-offset</i> is 'this' adjustment
		      # second <i>call-offset</i> is result adjustment

</pre></font></code>

<p>
<a name="mangling-special-ctor-dtor">
<h5><a href="#mangling-special-ctor-dtor"> 5.1.4.3 Constructors and Destructors </a></h5>

<p>
Constructors and destructors are simply special cases of
&lt;<a href="#mangle.unqualified-name">unqualified-name</a>&gt;,
where the final &lt;<a href="#mangle.unqualified-name">unqualified-name</a>&gt; of a nested name
is replaced by one of the following:

<pre><font color=blue><code>
  &lt;<a name="mangle.ctor-dtor-name">ctor-dtor-name</a>&gt; ::= C1			# complete object constructor
		   ::= C2			# base object constructor
		   ::= C3			# complete object allocating constructor
		   ::= CI1 &lt;<i>base class</i> <a href="#mangle.type">type</a>&gt;	# complete object <a href="#inh-ctor">inheriting constructor</a>
		   ::= CI2 &lt;<i>base class</i> <a href="#mangle.type">type</a>&gt;	# base object <a href="#inh-ctor">inheriting constructor</a>
		   ::= D0			# deleting destructor
		   ::= D1			# complete object destructor
		   ::= D2			# base object destructor
</pre></font></code>

<p>
The &lt;<i>base class</i> <a href="#mangle.type">type</a>&gt; in an inheriting
constructor mangling identifies the base class in which the inherited
constructor was originally declared.

<p>
Some of the symbols for constructor and destructor variants are <a
href="#vague-ctor">optional</a>.

<p>
<a name="mangling-special-guards">
<h5><a href="#mangling-special-guards"> 5.1.4.4 Guard Variables </a></h5>

<p>
Initialization of certain objects with static storage duration
requires a <a href="#guards">guard variable</a> to prevent multiple
initialization.  The mangled name of a guard variable is the name of
the guarded variable prefixed with <code>GV</code>.

<pre><font color=blue><code>
  &lt;<a name="mangle.special-name">special-name</a>&gt; ::= GV &lt;<i>object</i> <a href="#mangle.name">name</a>&gt;	# Guard variable for one-time initialization
			# No &lt;<a href="#mangle.type">type</a>&gt;

</pre></font></code>

<p>
<a name="mangling-special-temporaries">
<h5><a href="#mangling-special-temporaries"> 5.1.4.5 Lifetime-Extended Temporaries </a></h5>

<p>
The initializers of objects with static storage duration may introduce
temporaries whose lifetime is extended to have static storage
duration; this may also apply recursively to the initializers of
those temporaries.  If an initializer is visible to multiple
translation units, those translation units must agree on the addresses
of the temporaries.  Therefore the temporaries must be given a
consistent name and <a href="#vague">vague linkage</a>.  The mangled
name of a temporary is the name of the non-temporary object in whose
initializer they appear, prefixed with <code>GR</code> and suffixed
with a sequence number mangled using the usual rules for a <code><a
href="#mangle.seq-id">seq-id</a></code>.  Temporaries are numbered
with a pre-order, depth-first, left-to-right walk of the complete
initializer.

<pre><font color=blue><code>
  &lt;<a name="mangle.special-name">special-name</a>&gt; ::= GR &lt;<i>object</i> <a href="#mangle.name">name</a>&gt; _             # First temporary
  &lt;<a name="mangle.special-name">special-name</a>&gt; ::= GR &lt;<i>object</i> <a href="#mangle.name">name</a>&gt; &lt;<a href="#mangle.seq-id">seq-id</a>&gt; _    # Subsequent temporaries
</code></font></pre>

<p>For example, consider the following code:

<pre>
struct A { const int (&x)[3]; };
struct B { const A (&x)[2]; };
template &lt;typename T&gt; B &&b = { { { { 1, 2, 3 } }, { { 4, 5, 6 } } } };
B &temp = b&lt;void&gt;;
</pre>

<ul compact>
<li><code>_ZGR1bIvE_</code> is the 'B' object that 'temp' would refer to.
<li><code>_ZGR1bIvE0_</code> is the array of 'A' object references.
<li><code>_ZGR1bIvE1_</code> is the object containing the first array of ints, {1, 2, 3}.
<li><code>_ZGR1bIvE2_</code> is the object containing the second array of ints, {4, 5, 6}.
</ul>

<p>
<a name="mangling-transaction-safe">
<h5><a href="#mangling-transaction-safe"> 5.1.4.6 Transaction-Safe Function
Entry Points</a></h5> A function declared transaction-safe or
[[optimize_for_synchronized]] has two entry points: the normal function
mangling, used for calls from a non-transaction context, and another entry
point used for calls during a transaction.  The mangled name of the transaction entry point is the normal mangling prefixed with GTt.

<pre><font color=blue><code>
  &lt;special-name&gt; ::= GTt &lt;encoding&gt;
</pre></font></code>

<a name="mangling-module-initializer">
<h5><a href="#mangling-module-initializer">5.1.4.7 Module Initializer
Function</a></h5>

<p>Namespace-scope static objects with dynamic-initializers that are
defined in importable named-module translation units are initialized
by an idempotent initializer function. These initializer functions are
called by importing translation-units, prior to their own dynamic
initialization of such objects. (Therefore the module-initializer
function of an importable unit will call the module-initializer
functions of its own imports.)  It is permitted to omit calls to
module-initializer functions that are known to be indirectly called by
another called module-initializer.  It is also permitted to omit calls
to module-initializer functions known to have no dynamic
initializations. It is unspecified how an implementation arranges any
indirect module-initializer functions of that module-initializer.

<p>A module-initializer function must arrange to be called during the
usual (non-modular) dynamic initialization process, for instance by
adding a pointer to it in the <code>.init_array</code> section.

<pre><code><font color=blue>
  &lt;special-name&gt;:= GI &lt;module-name&gt;
</font></code></pre>

<p>The &lt;module-name&gt; includes any partition component.

<a name="mangling-type">
<h4><a href="#mangling-type">5.1.5 Type encodings</a></h4>

<p>
Types are encoded according to their compound structure: the tree of
type constructors, such as <code>const</code> and <code>*</code>,
that uniquely determine the type.  The mangling of function template
signatures necessitates the ability to encode the compound structure
of dependent types.

<p>
Simple forms of type structure, such as reference and pointer types, are
encoded with a single-character prefix.  More complex forms of type
structure, such as qualifiers and function types, require individual
discussion below.

<pre><font color=blue><code>
  &lt;<a name="mangle.type">type</a>&gt; ::= &lt;<a href="#mangle.builtin-type">builtin-type</a>&gt;
         ::= &lt;<a href="#mangle.qualified-type">qualified-type</a>&gt;
         ::= &lt;<a href="#mangle.function-type">function-type</a>&gt;
         ::= &lt;<a href="#mangle.class-enum-type">class-enum-type</a>&gt;
         ::= &lt;<a href="#mangle.array-type">array-type</a>&gt;
         ::= &lt;<a href="#mangle.pointer-to-member-type">pointer-to-member-type</a>&gt;
         ::= &lt;<a href="#mangle.template-param">template-param</a>&gt;
         ::= &lt;<a href="#mangle.template-template-param">template-template-param</a>&gt; &lt;<a href="#mangle.template-args">template-args</a>&gt;
         ::= &lt;<a href="#mangle.decltype">decltype</a>&gt;
         ::= P &lt;<a href="#mangle.type">type</a>&gt;        # pointer
         ::= R &lt;<a href="#mangle.type">type</a>&gt;        # l-value reference
         ::= O &lt;<a href="#mangle.type">type</a>&gt;        # r-value reference (C++11)
         ::= C &lt;<a href="#mangle.type">type</a>&gt;        # complex pair (C99)
         ::= G &lt;<a href="#mangle.type">type</a>&gt;        # imaginary (C99)
         ::= &lt;<a href="#mangle.substitution">substitution</a>&gt;  # See <a href=#mangling-compression>Compression</a> below
</pre></font></code>

<a name="mangle.qualified-type">
<h5><a href="#mangle.qualified-type">5.1.5.1 Qualified types</a></h5>

<pre><font color=blue><code>
  &lt;qualified-type&gt;     ::= &lt;<a href="#mangle.qualifiers">qualifiers</a>&gt; &lt;<a href="#mangle.type">type</a>&gt;

  &lt;<a name="mangle.qualifiers">qualifiers</a>&gt;         ::= &lt;<a href="#mangle.extended-qualifier">extended-qualifier</a>&gt;* &lt;<a href="#mangle.CV-qualifiers">CV-qualifiers</a>&gt;
  &lt;<a name="mangle.extended-qualifier">extended-qualifier</a>&gt; ::= U &lt;<a href="#mangle.source-name">source-name</a>&gt; [&lt;<a href="#mangle.template-args">template-args</a>&gt;] # vendor extended type qualifier
  &lt;<a name="mangle.CV-qualifiers">CV-qualifiers</a>&gt;      ::= [r] [V] [K] 	  # restrict (C99), volatile, const

  &lt;<a name="mangle.ref-qualifier">ref-qualifier</a>&gt;      ::= R              # &amp; ref-qualifier
  &lt;<a name="mangle.ref-qualifier">ref-qualifier</a>&gt;      ::= O              # &amp;&amp; ref-qualifier
</pre></font></code>

<p>
Vendors who define extended type qualifiers (e.g. <code>_near</code> and
<code>_far</code> for pointers) shall encode them as a 'U' prefix, followed
by the name in &lt;length,ID&gt; form, followed optionally by any arguments
to the qualifier.  It is recommended that the encoded name be the
preferred name used in source code; known exceptions are <a href="#mangling-vendor-qualifier-exceptions">listed below</a>.

<p>
In cases where multiple order-insensitive qualifiers are present,
they should be ordered (beginning closest to the base type) 'K', 'V', 'r',
and 'U' (farthest from the base type), with the 'U' qualifiers in
alphabetical order by the vendor name (with alphabetically earlier names
closer to the base type).  For example,
<code>int* volatile const restrict _far</code> has mangled type name
<code>U4_farrVKPi</code>.  <i>Vendors must therefore specify which of their
extended qualifiers are considered order-insensitive.</i>  This need not
necessarily be resolved on the basis of whether their language translators
impose an order in source code.  They are encouraged to resolve questionable
cases as being order-insensitive to maximize consistency in mangling.
</i>

<p>
For purposes of substitution, given a qualified type, the base type
is substitutible and the type with all the K, V, and r qualifiers plus
any vendor extended types in the same order-insensitive set is substitutible;
however, types with only a subset of those qualifiers are not.
That is, given a type <code>const volatile foo</code>,
the fully qualified type or foo may be substituted,
but not <code>volatile foo</code> nor <code>const foo</code>.

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
The restrict qualifier is part of the C99 standard,
but is strictly an extension to C++ at this time.
There is no standard specification of whether the restrict attribute
is part of the type for overloading purposes.
An implementation should include its encoding in the mangled name
if and only if it also treats it as a distinguishing attribute for
overloading purposes.
This ABI does not specify that choice.
</i>

<a name="mangling-vendor-qualifier-exceptions">
<h6>Known exceptions to the extended qualifier rules</h6>

<ul compact>
<li>
The GNU <code>address_space(N)</code> qualifier is mangled
using the name <code>AS</code>.  For historical reasons, if
the argument expression is not
<a href="#instantiation-dependent">instantiation-dependent</a>,
its value is incorporated directly into the
&lt;<a href="#mangle.source-name">source-name</a>&gt; of the
qualifier; otherwise it is encoded as a qualifier argument.

<p>
For example, <code>int __attribute__((address_space(3))) *</code> is
encoded as <code>PU3AS3i</code>, but
<code>int __attribute__((address_space(K))) *</code>
(in which <code>K</code> is a reference to the first
template parameter) is encoded as <code>PU2ASIT_Ei</code>.

</ul>

<a name="mangling-builtin">
<h5><a href="#mangling-builtin">5.1.5.2 Builtin types</a></h5>

<p>
Builtin types are represented by single-letter codes:

<pre><font color=blue><code>
  &lt;<a name="mangle.builtin-type">builtin-type</a>&gt; ::= v	# void
		 ::= w	# wchar_t
		 ::= b	# bool
		 ::= c	# char
		 ::= a	# signed char
		 ::= h	# unsigned char
		 ::= s	# short
		 ::= t	# unsigned short
		 ::= i	# int
		 ::= j	# unsigned int
		 ::= l	# long
		 ::= m	# unsigned long
		 ::= x	# long long, __int64
		 ::= y	# unsigned long long, __int64
		 ::= n	# __int128
		 ::= o	# unsigned __int128
		 ::= f	# float
		 ::= d	# double
		 ::= e	# long double, __float80
		 ::= g	# __float128
		 ::= z	# ellipsis
                 ::= Dd # IEEE 754r decimal floating point (64 bits)
                 ::= De # IEEE 754r decimal floating point (128 bits)
                 ::= Df # IEEE 754r decimal floating point (32 bits)
                 ::= Dh # IEEE 754r half-precision floating point (16 bits)
                 ::= DF &lt;<a href="#mangle.number">number</a>&gt; _ # ISO/IEC TS 18661 binary floating point type _FloatN (N bits)
                 ::= DB &lt;<a href="#mangle.number">number</a>&gt; _        # C23 signed _BitInt(N)
                 ::= DB &lt;<i>instantiation-dependent</i> <a href="#mangle.expression">expression</a>&gt; _ # C23 signed _BitInt(N)
                 ::= DU &lt;<a href="#mangle.number">number</a>&gt; _        # C23 unsigned _BitInt(N)
                 ::= DU &lt;<i>instantiation-dependent</i> <a href="#mangle.expression">expression</a>&gt; _ # C23 unsigned _BitInt(N)
                 ::= Di # char32_t
                 ::= Ds # char16_t
                 ::= Du # char8_t
                 ::= Da # auto
                 ::= Dc # decltype(auto)
                 ::= Dn # std::nullptr_t (i.e., decltype(nullptr))
		 ::= u &lt;<a href="#mangle.source-name">source-name</a>&gt; [&lt;<a href="#mangle.template-args">template-args</a>&gt;] # vendor extended type
</pre></font></code>

<p>
Vendors who define builtin extended types shall encode them
as a 'u' prefix followed by the name in &lt;length,I&gt; form,
followed by any arguments to the extended type.

<a name="mangle.function-type">
<h5><a href="#mangle.function-type">5.1.5.3 Function types</a></h5>

<p>
Function types are composed from their parameter types and possibly the
result type.
Except at the outer level type of an &lt;<a href="#mangle.encoding">encoding</a>&gt;,
or in the &lt;<a href="#mangle.encoding">encoding</a>&gt; of an otherwise delimited external name in a
&lt;<a href="#mangle.template-param">template-param</a>&gt; or &lt;<a href="#mangle.local-name">local-name</a>&gt; function encoding,
these types are delimited by an "F..E" pair.
For purposes of substitution
(see <a href=#mangling-compression>Compression</a> below),
delimited and undelimited function types are considered the same.

<p>
Whether the mangling of a function type includes the return type
depends on the context and the nature of the function.
The rules for deciding whether the return type is included are:
<ol>
<li> Template functions (names or types) have return types encoded,
     with the exceptions listed below.
<li> Function types not appearing as part of a function name mangling,
     e.g. parameters, pointer types, etc., have return type encoded,
     with the exceptions listed below.
<li> Non-template function names do not have return types encoded.
</ol>
The exceptions mentioned in (1) and (2) above,
for which the return type is never included, are
<ul>
<li> Constructors.
<li> Destructors.
<li> Conversion operator functions, e.g. <code>operator int</code>.
</ul>

<p>
Empty parameter lists,
whether declared as <code>()</code> or conventionally as <code>(void)</code>,
are encoded with a void parameter specifier (v).
Therefore function types always encode at least one parameter type,
and function manglings can always be distinguished from data manglings
by the presence of the type.
Member functions do not encode the types of
implicit parameters, either <code>this</code> or the VTT parameter.

<p>
The mangling of CV-qualifiers and ref-qualifiers on a function type
differs according to context. When mangling the name of a non-static
member function, the CV-qualifiers and ref-qualifiers of that function
are encoded at the beginning of
the <code>&lt;<a href="#mangle.nested-name">nested-name</a>&gt;</code>
as described above. Otherwise, they are encoded as part of the
function type as described below.
</p>

<p>
When an exception-specification (i.e., <code>noexcept</code>,
<code>noexcept(expression)</code>, or <code>throw(type(s))</code>) is part of
the function type, it is mangled according to
<code>&lt;<a href="#mangle.exception-spec">exception-spec</a>&gt;</code> as
described below.
A non-instantiation-dependent, potentially-throwing exception specification is
not mangled.
</p>

<p>
A transaction-safe function type is encoded with a "Dx" before the "F".  This
affects only type mangling; a transaction-safe function has the same mangling
as a non-transaction-safe function.
</p>

<p>
A "Y" prefix for the bare function type encodes extern "C" in
implementations which distinguish between function types with "C" and
"C++" language linkage. This affects only type mangling, since extern
"C" function objects have unmangled names.
</p>

<pre><font color=blue><code>
  &lt;function-type&gt; ::= [&lt;<a href="#mangle.CV-qualifiers">CV-qualifiers</a>&gt;] [&lt;<a href="#mangle.exception-spec">exception-spec</a>&gt;] [Dx] F [Y] &lt;<a href="#mangle.bare-function-type">bare-function-type</a>&gt; [&lt;<a href="#mangle.ref-qualifier">ref-qualifier</a>&gt;] E
  &lt;<a name="mangle.bare-function-type">bare-function-type</a>&gt; ::= &lt;<i>signature</i> <a href="#mangle.type">type</a>&gt;+
	# types are possible return type, then parameter types
  &lt;<a name="mangle.exception-spec">exception-spec&gt; ::= Do                # non-throwing exception-specification (e.g., noexcept, throw())
                   ::= DO &lt;<a href="#mangle.expression">expression</a>&gt; E # computed (instantiation-dependent) noexcept
                   ::= Dw &lt;<a href="#mangle.type">type</a>&gt;+ E      # dynamic exception specification with instantiation-dependent types

</pre></font></code>

<p>
For the purposes of substitution, the CV-qualifiers and ref-qualifier
of a function type are an indivisible part of the type; that is, when
mangling <code>void () const</code>, <code>void ()</code> is not a
substitution candidate.
</p>

<p>
When a function parameter is a C++11 function parameter pack, its type
is mangled with <code>Dp &lt;<a href="#mangle.type">type</a>&gt;</code>, i.e., its type is a pack
expansion:
<pre><font color="blue"><code> &lt;<a name="mangle.type">type</a>&gt;  ::= Dp &lt;<a href="#mangle.type">type</a>&gt;          # pack expansion (C++11)
</code></font></pre>
</p>

<a name="mangle.decltype">
<h5><a href="#mangle.decltype">5.1.5.4 C++11 <code>decltype</code></a></h5>

<p>
The C++11 <code>decltype</code> type is encoded with
either <code>Dt</code> or <code>DT</code>, depending on how
the <code>decltype</code> type was parsed.  (See farther <a href=#expressions>below</a> for
the encoding of expressions.)

<pre><font color="blue"><code> &lt;decltype&gt;  ::= Dt &lt;<a href="#mangle.expression">expression</a>&gt; E  # decltype of an id-expression or class member access (C++11)
             ::= DT &lt;<a href="#mangle.expression">expression</a>&gt; E  # decltype of an expression (C++11)
</code></font></pre>
If the operand expression of <code>decltype</code> is not
<a href=#instantiation-dependent>instantiation-dependent</a>
then the resulting type is encoded directly.  For example:
<code><pre>
          int x;
          template&lt;class T> auto f(T p)->decltype(x);
            // The return type in the mangling of the template signature
            // is encoded as "i".
          template&lt;class T> auto f(T p)->decltype(p);
            // The return type in the mangling of the template signature
            // is encoded as "Dtfp_E".
          void g(int);
          template&lt;class T> auto f(T p)->decltype(g(p));
            // The return type in the mangling of the template signature
            // is encoded as "DTcl1gfp_E".
</pre></code>

<a name="mangling.named">
<h5><a href="#mangling.named">5.1.5.5 Class, union, and enum types</a></h5>

<p>
A class, union, or enum type is simply a name.
It may be a simple &lt;<a href="#mangle.unqualified-name">unqualified-name</a>&gt;,
with or without a template argument list,
or a more complex &lt;<a href="#mangle.nested-name">nested-name</a>&gt;.
Thus, it is encoded like a function name,
except that no CV-qualifiers are present in a nested name specification.

<pre><code><font color=blue>
  &lt;<a name="mangle.class-enum-type">class-enum-type</a>&gt; ::= &lt;<a href="#mangle.name">name</a>&gt;     # non-dependent type name, dependent type name, or dependent typename-specifier
                    ::= Ts &lt;<a href="#mangle.name">name</a>&gt;  # dependent elaborated type specifier using 'struct' or 'class'
                    ::= Tu &lt;<a href="#mangle.name">name</a>&gt;  # dependent elaborated type specifier using 'union'
                    ::= Te &lt;<a href="#mangle.name">name</a>&gt;  # dependent elaborated type specifier using 'enum'
</pre></font></code>

<p>
An exception, however, is that class <code>std::decimal::decimal32</code>,
<code>std::decimal::decimal64</code>, or <code>std::decimal::decimal128</code>
as defined in TR 24733 uses the same encoding as the corresponding native
decimal-floating point scalar type.

</p><p>
Unnamed class, union, and enum types that aren't closure types, that
haven't acquired a "name for linkage purposes" (through a typedef), and
that aren't anonymous union types, follow
the same rule when they are defined in class scopes,
with the underlying &lt;<a href="#mangle.unqualified-name">unqualified-name</a>&gt; an &lt;<a href="#mangle.unnamed-type-name">unnamed-type-name</a>&gt; of
the form
<pre><code><font color=blue>  &lt;<a name="mangle.unnamed-type-name">unnamed-type-name</a>&gt; ::= Ut [ &lt;<i>nonnegative</i> <a href="#mangle.number">number</a>&gt; ] _ 
</pre></font></code>

The number is omitted for the first unnamed type in the class; it is
n-2 for the nth unnamed type (in <a href="#lexical-ordering">lexical order</a>)
otherwise.
<p>
(The mangling of such unnamed types defined in namespace scope is
generally unspecified because they do not have to match across
translation units.  An implementation must only ensure that naming
collisions are avoided.  The mangling of such unnamed types in local
scopes is described in <a href=#mangling-scope>Scope Encoding</a>.
The encoding of closure types is described in a
<a href=#closure-types>Closure Types (Lambdas)</a>.)

<p>
For example:
<code><pre>
	struct S { static struct {} x; };
	typedef decltype(S::x) TX;  // Type mangled as N1SUt_E
	TX S::x;                    // _ZN1S1xE
	void f(TX) {}               // _Z1fN1SUt_E
</pre></code>

<a name="mangle.array-type">
<h5><a href="#mangle.array-type">5.1.5.6 Array types</a></h5>

<p>
Array types encode their array bound and element type.  Note that
"array" parameters to functions are encoded as pointer types.
The array bound (but not the <code class=mangle>_</code> separator)
is omitted for incomplete array types (e.g. <code>int[]</code>)
and C99 variable-length array types.

<pre><font color=blue><code>
  &lt;array-type&gt; ::= A [&lt;<i>array bound</i> <a href="#mangle.number">number</a>&gt;] _ &lt;<i>element</i> <a href="#mangle.type">type</a>&gt;
	       ::= A &lt;<i>instantiation-dependent array bound</i> <a href="#mangle.expression">expression</a>&gt; _ &lt;<i>element</i> <a href="#mangle.type">type</a>&gt;
</pre></font></code>

<p>
The second rule is used when the array bound is an
<a href="#instantiation-dependent">instantiation-dependent</a>
expression.  For example:
<pre><code>    template&lt;int I&gt; void foo (int (&amp;)[I + 1]) { }

    // Mangled as _Z3fooILi2EEvRAplT_Li1E_i
    template void foo&lt;2&gt; (int (&amp;)[3]);
</pre></code>

<a name="mangle.pointer-to-member-type">
<h5><a href="#mangle.pointer-to-member-type">5.1.5.7 Pointer-to-member types</a></h5>

<p>
Pointer-to-member types encode the class and member types:

<pre><font color=blue><code>  &lt;pointer-to-member-type&gt; ::= M &lt;<i>class</i> <a href="#mangle.type">type</a>&gt; &lt;<i>member</i> <a href="#mangle.type">type</a>&gt;</pre></font></code>

<p>For example,
<pre><code>    void f (void (A::*)() const &) {}</code></pre>
produces the mangled name "<code>_Z1fM1AKFvvRE</code>".

<a name="mangle.template-param">
<h5><a href="#mangle.template-param">5.1.5.8 Template parameters</a></h5>

<p>
A reference to a template parameter is mangled using the index
of the parameter, with a special mangling for the first parameter.
The sequence of parameters is therefore <code class=mangle>T_</code>,
<code class=mangle>T0_</code>, <code class=mangle>T1_</code>, and so on.

<pre><code><font color=blue>
  &lt;template-param&gt; ::= T_ # first template parameter
                   ::= T &lt;<i>parameter-2 non-negative</i> <a href="#mangle.number">number</a>&gt; _
  &lt;<a name="mangle.template-template-param">template-template-param</a>&gt; ::= &lt;<a href="#mangle.template-param">template-param</a>&gt;
                            ::= &lt;<a href="#mangle.substitution">substitution</a>&gt;
</font></code></pre>

<p>
For example:
<pre><code>
    template&lt;class T&gt; void f(T) {}

    // Mangled as "_Z1fIiEvT_"
    template void f(int);

</code></pre>

<p>
Note that a template parameter reference is a
<a href="#mangling-compression">substitution candidate</a>.
As a substitution, it is treated as distinct from the actual
template argument, including in recursive positions.
For example, in the mangling of the following function template
specialization, the first incidence of <code>T*</code> is not
substituted despite being known (in this specialization) to be
the same type as <code>int*</code>, and the second incidence
is substituted with the substitution derived from the first
incidence, not that from the incidence of <code>int*</code>.

<pre><code>
    template&lt;class T&gt; void f(int*, T*, T*) {}

    // Mangled as "_Z1fIiEvPiPT_S2_"
    template void f(int*, int*, int*);

</code></pre>

<p>
Typically, only references to function template parameters occurring
within the dependent signature of the template are mangled this way.
In other contexts, template instantiation replaces references
to template parameters with the actual template arguments, and mangling
should mangle such references exactly as if they were that template
argument.  For example:

<pre><code>
    template&lt;class T&gt; class A {
      template&lt;class U&gt; void f(T, U) {}
    };

    // Mangled as "_ZN1AIiE1fIfEEviT_"
    template void A&lt;int&gt;::f(int, float);

</code></pre>

</p>

<a name="mangle.function-param">
<h5><a href="#mangle.function-param">5.1.5.9 Function parameter references</a></h5>

<p>
Function parameters referenced in other parameter types or in
late-specified return types are handled similarly to template
parameters, but involve a few more subtleties.</p>
<p>
Let L be the number of function prototype scopes from the innermost one
(in which the parameter reference occurs) up to (and including) the one
containing the declaration of the referenced parameter.  If the parameter
declaration clause of the innermost function prototype scope has been
completely seen, it is not counted (in that case -- which is perhaps the
most common -- L can be zero).  For example:
<code><pre>          template&lt;class T> void f(T p, decltype(p));                         // L = 1
          template&lt;class T> void g(T p, decltype(p) (*)());          // L = 1
          template&lt;class T> void h(T p, auto (*)()->decltype(p));    // L = 1
          template&lt;class T> void i(T p, auto (*)(T q)->decltype(q)); // L = 0
          template&lt;class T> void j(T p, auto (*)(decltype(p))->T);   // L = 2
          template&lt;class T> void k(T p, int (*(*)(T p))[sizeof(p)]); // L = 1
</pre></code>
</p>

<pre><code><font color="blue">
  &lt;function-param&gt; ::= fp &lt;<i>top-level</i> <a href="#mangle.CV-qualifiers">CV-qualifiers</a>&gt; _                                     # L == 0, first parameter
		   ::= fp &lt;<i>top-level</i> <a href="#mangle.CV-qualifiers">CV-qualifiers</a>&gt; &lt;<i>parameter-2 non-negative</i> <a href="#mangle.number">number</a>&gt; _   # L == 0, second and later parameters
		   ::= fL &lt;L-1 non-negative <a href="#mangle.number">number</a>&gt; p &lt;<i>top-level</i> <a href="#mangle.CV-qualifiers">CV-qualifiers</a>&gt; _         # L > 0, first parameter
		   ::= fL &lt;L-1 non-negative <a href="#mangle.number">number</a>&gt; p &lt;<i>top-level</i> <a href="#mangle.CV-qualifiers">CV-qualifiers</a>&gt;
                                                    &lt;<i>parameter-2 non-negative</i> <a href="#mangle.number">number</a>&gt; _   # L > 0, second and later parameters
		   ::= fpT                                                                # this
</font></code></pre>
Note that top-level cv-qualifiers specified on a parameter type do not
affect the function type directly (i.e., <code>int(*)(T)</code> and
<code>int(*)(T const)</code> are the same type), but in expression
contexts (such as decltype arguments) they do matter and must therefore
be encoded in <code>&lt;<a href="#mangle.function-param">function-param</a>&gt;</code>, unless the parameter
is used as an rvalue of a known non-class type (in the latter case the
qualifier cannot affect the semantics of the expression).  For example:
<code><pre>
          template&lt;typename T> void f(T const p, decltype(p)*);
            // The specialization f&lt;int&gt; has type void(int, int const*)
            // and is encoded as _Z1fIiEvT_PDtfL0pK_E
</pre></code>

<a name="mangle.template-args">
<a name="mangle.template-arg">
<h5><a href="#mangle.template-arg">5.1.5.10 Template Arguments</a></h5>
</a></a>

<p>
Template argument lists appear after the unqualified template name,
and are bracketed by I/E.  This is used in names for specializations
in particular, but also in types and scope identification.  Template
argument packs are bracketed by J/E to distinguish them from other
arguments.

<pre><font color=blue><code>
  &lt;template-args&gt; ::= I &lt;<a href="#mangle.template-arg">template-arg</a>&gt;+ E

  &lt;template-arg&gt; ::= &lt;<a href="#mangle.type">type</a>&gt;                                             # type or template
                 ::= X &lt;<a href="#mangle.expression">expression</a>&gt; E                                   # expression
                 ::= &lt;<a href="#mangle.expr-primary">expr-primary</a>&gt;                                     # simple expressions
                 ::= J &lt;<a href="#mangle.template-arg">template-arg</a>&gt;* E                                # argument pack
</code></font></pre>

<p>
Type arguments appear using their regular encoding.
For example, the template class "A&lt;char, float&gt;" is encoded as "1AIcfE".
A slightly more involved example is
a dependent function parameter type "A&lt;T2&gt;::X"
(T2 is the second template parameter)
which is encoded as "N1AIT0_E1XE",
where the "N...E" construct is used to describe a qualified name.

<a name="expressions">
<h4><a href="#expressions">5.1.6 Expressions</a></h4>

<p>
Expressions must be mangled in several contexts.

<p>
When mangling the name of a specialized template, non-type
template arguments are mangled as expressions.  These
expressions are typically very simple, and they do not
necessarily reflect any argument expression that was used
in source.  See the section on mangling
<a href="#mangle.template-args">template arguments</a> for
more detail.

<p>
More generally, when mangling the signature of a function
template, any
<a href="#instantiation-dependent">instantiation-dependent</a>
expressions (e.g. in an array bound, <code>decltype</code>,
or template argument) must be mangled in order to properly
distinguish templates that are different under the ODR.
See the section on <a href="#mangling.dependent">dependent
mangling</a>.  As a result, nearly the entire expression
grammar of C++ is subject to mangling, with only a few
exceptions (like lambdas) that are explicitly disallowed
in function signatures.

<p>
In general, expression manglings reflect a prefix traversal of the
syntactic expression tree, with parentheses omitted.  (Parentheses
may be ignored because they are implicit in the prefix representation
and typically do not affect semantics.  However, a parenthesized
<code>&lt;<a href="#mangle.unresolved-name">unresolved-name</a>&gt;</code>
must be mangled differently because the parentheses act to suppress
argument-dependent lookup.)  Unless explicitly stated otherwise, the
expression is mangled without constant folding or other
simplification.

<p>
Each expression mangling begins with a code (typically two letters)
indicating the kind of expression, which dictates the form of
the rest of the mangling.  For overloadable operators, this code is
the same as the <code>&lt;<a href="#mangle.operator-name">operator-name</a>&gt;</code>.

<p>For example, if <code>J</code> is the third template parameter,
"B&lt;(J+1)/2&gt;" becomes "1BI Xdv pl T1_ Li1E Li2E E E" (the blanks
are present only to visualize the decomposition).  

<p>
If the operand of a <code>sizeof</code> or <code>alignof</code> operator
is not <a href="#instantiation-dependent">instantiation-dependent</a>,
it is encoded as an integer literal reflecting the result of the
operator.  If the result of the operator is implicitly converted to
a known integer type, that type is used for the literal; otherwise,
the type of <code>std::size_t</code> or <code>std::ptrdiff_t</code> is used.
For example:
<code><pre>
          template&lt;class T, int N> struct S1 {};
          template&lt;class T, T N> struct S2 {};
          template&lt;class T> void f(S1&lt;T, sizeof(long double)>);
            // The sizeof(...) is not instantiation-dependent, and converted to int:
            // the result is encoded as "Li16E" for 16-byte long double types.
          template&lt;class T> void f(S2&lt;T, sizeof(long double)>);
            // The sizeof(...) is not instantiation-dependent, and converted to an
            // unknown type: the result is encoded as "Lm16E" for 16-byte long double
            // types and std::size_t a synonym for "unsigned long".
          template&lt;class T> void f(S2&lt;T, sizeof(T*)>);
            // The sizeof(...) is instantiation-dependent (even though its value may
            // be known if all pointers have the same size): It is encoded as "stPT_".
</pre></code>
</p>

<pre><font color=blue><code>
  &lt;<a name="mangle.expression">expression</a>&gt; ::= &lt;<i>unary</i> <a href="#mangle.operator-name">operator-name</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;
               ::= &lt;<i>binary</i> <a href="#mangle.operator-name">operator-name</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;
               ::= &lt;<i>ternary</i> <a href="#mangle.operator-name">operator-name</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;
               ::= pp_ &lt;<a href="#mangle.expression">expression</a>&gt;                                     # prefix ++
               ::= mm_ &lt;<a href="#mangle.expression">expression</a>&gt;                                     # prefix --
               ::= cl &lt;<a href="#mangle.expression">expression</a>&gt;+ E                                   # expression (expr-list), call
               ::= cv &lt;<a href="#mangle.type">type</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;                               # type (expression), conversion with one argument
               ::= cv &lt;<a href="#mangle.type">type</a>&gt; _ &lt;<a href="#mangle.expression">expression</a>&gt;* E                          # type (expr-list), conversion with other than one argument
               ::= tl &lt;<a href="#mangle.type">type</a>&gt; &lt;<a href="#mangle.braced-expression">braced-expression</a>&gt;* E                     # type {expr-list}, conversion with braced-init-list argument
               ::= il &lt;<a href="#mangle.braced-expression">braced-expression</a>&gt;* E                            # {expr-list}, braced-init-list in any other context
               ::= [gs] nw &lt;<a href="#mangle.expression">expression</a>&gt;* _ &lt;<a href="#mangle.type">type</a>&gt; E                     # new (expr-list) type
               ::= [gs] nw &lt;<a href="#mangle.expression">expression</a>&gt;* _ &lt;<a href="#mangle.type">type</a>&gt; &lt;<a href="#mangle.initializer">initializer</a>&gt;         # new (expr-list) type (init)
               ::= [gs] na &lt;<a href="#mangle.expression">expression</a>&gt;* _ &lt;<a href="#mangle.type">type</a>&gt; E                     # new[] (expr-list) type
               ::= [gs] na &lt;<a href="#mangle.expression">expression</a>&gt;* _ &lt;<a href="#mangle.type">type</a>&gt; &lt;<a href="#mangle.initializer">initializer</a>&gt;         # new[] (expr-list) type (init)
               ::= [gs] dl &lt;<a href="#mangle.expression">expression</a>&gt;                                 # delete expression
               ::= [gs] da &lt;<a href="#mangle.expression">expression</a>&gt;                                 # delete[] expression
               ::= dc &lt;<a href="#mangle.type">type</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;                               # dynamic_cast&lt;type&gt; (expression)
               ::= sc &lt;<a href="#mangle.type">type</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;                               # static_cast&lt;type&gt; (expression)
               ::= cc &lt;<a href="#mangle.type">type</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;                               # const_cast&lt;type&gt; (expression)
               ::= rc &lt;<a href="#mangle.type">type</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;                               # reinterpret_cast&lt;type&gt; (expression)
               ::= ti &lt;<a href="#mangle.type">type</a>&gt;                                            # typeid (type)
               ::= te &lt;<a href="#mangle.expression">expression</a>&gt;                                      # typeid (expression)
               ::= st &lt;<a href="#mangle.type">type</a>&gt;                                            # sizeof (type)
               ::= sz &lt;<a href="#mangle.expression">expression</a>&gt;                                      # sizeof (expression)
               ::= at &lt;<a href="#mangle.type">type</a>&gt;                                            # alignof (type)
               ::= az &lt;<a href="#mangle.expression">expression</a>&gt;                                      # alignof (expression)
               ::= nx &lt;<a href="#mangle.expression">expression</a>&gt;                                      # noexcept (expression)
               ::= &lt;<a href="#mangle.template-param">template-param</a>&gt;
               ::= &lt;<a href="#mangle.function-param">function-param</a>&gt;
               ::= dt &lt;<a href="#mangle.expression">expression</a>&gt; &lt;<a href="#mangle.unresolved-name">unresolved-name</a>&gt;                    # expr.name
               ::= pt &lt;<a href="#mangle.expression">expression</a>&gt; &lt;<a href="#mangle.unresolved-name">unresolved-name</a>&gt;                    # expr-&gt;name
               ::= ds &lt;<a href="#mangle.expression">expression</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;                         # expr.*expr
               ::= sZ &lt;<a href="#mangle.template-param">template-param</a>&gt;                                  # sizeof...(T), size of a template parameter pack
               ::= sZ &lt;<a href="#mangle.function-param">function-param</a>&gt;                                  # sizeof...(parameter), size of a function parameter pack
               ::= sP &lt;<a href="#mangle.template-arg">template-arg</a>&gt;* E                                 # sizeof...(T), size of a captured template parameter pack from an alias template
               ::= sp &lt;<a href="#mangle.expression">expression</a>&gt;                                      # expression..., pack expansion
               ::= fl &lt;<i>binary</i> <a href="#mangle.operator-name">operator-name</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;               # (... operator expression), unary left fold
               ::= fr &lt;<i>binary</i> <a href="#mangle.operator-name">operator-name</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;               # (expression operator ...), unary right fold
               ::= fL &lt;<i>binary</i> <a href="#mangle.operator-name">operator-name</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;  # (expression operator ... operator expression), binary left fold
               ::= fR &lt;<i>binary</i> <a href="#mangle.operator-name">operator-name</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt; &lt;<a href="#mangle.expression">expression</a>&gt;  # (expression operator ... operator expression), binary right fold
               ::= tw &lt;<a href="#mangle.expression">expression</a>&gt;                                      # throw expression
               ::= tr                                                   # throw with no operand (rethrow)
               ::= u &lt;<a href="#mangle.source-name">source-name</a>&gt; &lt;<a href="#mangle.template-arg">template-arg</a>&gt;* E                    # vendor extended expression
               ::= &lt;<a href="#mangle.unresolved-name">unresolved-name</a>&gt;                                    # f(p), N::f(p), ::f(p),
                                                                        # freestanding dependent name (e.g., T::x),
                                                                        # objectless nonstatic member reference
               ::= &lt;<a href="#mangle.expr-primary">expr-primary</a>&gt;

  &lt;<a name="mangle.unresolved-name">unresolved-name</a>&gt; ::= [gs] &lt;<a href="#mangle.base-unresolved-name">base-unresolved-name</a>&gt;                     # x or (with "gs") ::x
                    ::= sr &lt;<a href="#mangle.unresolved-type">unresolved-type</a>&gt; &lt;<a href="#mangle.base-unresolved-name">base-unresolved-name</a>&gt;     # T::x / decltype(p)::x
                    ::= srN &lt;<a href="#mangle.unresolved-type">unresolved-type</a>&gt; &lt;<a href="#mangle.unresolved-qualifier-level">unresolved-qualifier-level</a>&gt;+ E &lt;<a href="#mangle.base-unresolved-name">base-unresolved-name</a>&gt;
                                                                        # T::N::x /decltype(p)::N::x
                    ::= [gs] sr &lt;<a href="#mangle.unresolved-qualifier-level">unresolved-qualifier-level</a>&gt;+ E &lt;<a href="#mangle.base-unresolved-name">base-unresolved-name</a>&gt;  
                                                                        # A::x, N::y, A&lt;<a href="#mangle.T">T</a>&gt;::z; "gs" means leading "::"

  &lt;<a name="mangle.unresolved-type">unresolved-type</a>&gt; ::= &lt;<a href="#mangle.template-param">template-param</a>&gt; [ &lt;<a href="#mangle.template-args">template-args</a>&gt; ]            # T:: or T&lt;X,Y&gt;::
                    ::= &lt;<a href="#mangle.decltype">decltype</a>&gt;                                      # decltype(p)::
                    ::= &lt;<a href="#mangle.substitution">substitution</a>&gt;

  &lt;<a name="mangle.unresolved-qualifier-level">unresolved-qualifier-level</a>&gt; ::= &lt;<a href="#mangle.simple-id">simple-id</a>&gt;

  &lt;<a name="mangle.simple-id">simple-id</a>&gt; ::= &lt;<a href="#mangle.source-name">source-name</a>&gt; [ &lt;<a href="#mangle.template-args">template-args</a>&gt; ]

  &lt;<a name="mangle.base-unresolved-name">base-unresolved-name</a>&gt; ::= &lt;<a href="#mangle.simple-id">simple-id</a>&gt;                                # unresolved name
                         ::= on &lt;<a href="#mangle.operator-name">operator-name</a>&gt;                         # unresolved operator-function-id
                         ::= on &lt;<a href="#mangle.operator-name">operator-name</a>&gt; &lt;<a href="#mangle.template-args">template-args</a>&gt;         # unresolved operator template-id
                         ::= dn &lt;<a href="#mangle.destructor-name">destructor-name</a>&gt;                       # destructor or pseudo-destructor;
                                                                        # e.g. ~X or ~X&lt;N-1>

  &lt;<a name="mangle.destructor-name">destructor-name</a>&gt; ::= &lt;<a href="#mangle.unresolved-type">unresolved-type</a>&gt;                               # e.g., ~T or ~decltype(f())
                    ::= &lt;<a href="#mangle.simple-id">simple-id</a>&gt;                                     # e.g., ~A&lt;2*N>

  &lt;<a name="mangle.expr-primary">expr-primary</a>&gt; ::= L &lt;<a href="#mangle.type">type</a>&gt; &lt;<i>value</i> <a href="#mangle.number">number</a>&gt; E                          # integer literal
                 ::= L &lt;<a href="#mangle.type">type</a>&gt; &lt;<i>value</i> <a href="#mangle.float">float</a>&gt; E                           # floating literal
                 ::= L &lt;<i>string</i> <a href="#mangle.type">type</a>&gt; E                                  # string literal
                 ::= L &lt;<i>nullptr</i> <a href="#mangle.type">type</a>&gt; E                                 # nullptr literal (i.e., "LDnE")
                 ::= L &lt;<i>pointer</i> <a href="#mangle.type">type</a>&gt; 0 E                               # null pointer template argument
		 ::= L &lt;<a href="#mangle.type">type</a>&gt; &lt;<i>real-part</i> <a href="#mangle.float">float</a>&gt; _ &lt;<i>imag-part</i> <a href="#mangle.float">float</a>&gt; E   # complex floating point literal (C 2000)
                 ::= L _Z &lt;<a href="#mangle.encoding">encoding</a>&gt; E                                  # external name

  &lt;<a name="mangle.braced-expression">braced-expression</a>&gt; ::= &lt;<a href="#mangle.expression">expression</a>&gt;
                      ::= di &lt;<i>field</i> <a href="#mangle.source-name">source-name</a>&gt; &lt;<a href="#mangle.braced-expression">braced-expression</a>&gt;    # .name = expr
                      ::= dx &lt;<i>index</i> <a href="#mangle.expression">expression</a>&gt; &lt;<a href="#mangle.braced-expression">braced-expression</a>&gt;     # [expr] = expr
                      ::= dX &lt;<i>range begin</i> <a href="#mangle.expression">expression</a>&gt; &lt;<i>range end</i> <a href="#mangle.expression">expression</a>&gt; &lt;<a href="#mangle.braced-expression">braced-expression</a>&gt;
                                                                        # [expr ... expr] = expr

  &lt;<a name="mangle.initializer">initializer</a>&gt; ::= pi &lt;<a href="#mangle.expression">expression</a>&gt;* E                                  # parenthesized initialization
</pre></code></font>

<p>A production for &lt;<a href="#mangle.expression">expression</a>&gt; that directly specifies an operation code (e.g., for the <code>-></code> operator)
takes precedence over one that is expressed in terms of (unary/binary/ternary) &lt;<a href="#mangle.operator-name">operator-name</a>&gt;.
</p>
<p>The optional "<code>gs</code>" prefix on some of the productions indicates that the corresponding
source construct (name, new-expression, or delete-expression) includes a global-scope qualifier 
(e.g., <code>::x</code>).
</p>

<p><code>tl</code> is used for direct-list-initializations, where the type name is directly followed by a braced-init-list; e.g., <code>MyArray{1,2,3}</code> should be mangled <code>tl7MyArrayLi1ELi2ELi3EE</code>.  If the braced-init-list is parenthesized, this is not a direct-list-initialization, and it should be mangled with <code>cv</code> and a nested <code>il</code>; for example, <code>MyArray({1,2,3})</code> should be mangled <code>cv7MyArrayilLi1ELi2ELi3EE</code>.</p>

<p>If an implementation supports the full C99 designated initializer syntax (as an extension), a designator list comprising multiple designators results in
multiple nested &lt;<a href="#mangle.braced-expression">braced-expression</a>&gt;s. For example, <code>X{.a.b[3] = 1}</code> should be mangled <code>tl1Xdi1adi1bdxLi3ELi1EE</code>.</p>

<a name="mangling.literal">
<h5><a href="#mangling.literal">5.1.6.1 Literals</a></h5>

<p>
Literal arguments, e.g. "A&lt;42L&gt;",
are encoded with their type and value.
Negative integer values are preceded with "n";
for example, "A&lt;-42L&gt;" becomes "1AILln42EE".
The bool value false is encoded as 0, true as 1.

<p>
Floating-point literals are encoded using a fixed-length lowercase
hexadecimal string corresponding to the internal representation,
high-order bytes first.  For example: "Lf bf800000 E" is -1.0f on
platforms conforming to IEEE 754.

<p>
The encoding for a literal of an enumerated type is the encoding of the
type name followed by the encoding of the numeric value of the literal
in its base integral type
(which deals with values that don't have names declared in the type).

<p>
String literals are encoded using their type, but not their value. 
For example, L"abc" and L"123" are both encoded as "LA4_KwE"
("array [4] of const wchar_t").

<p>
The pointer literal expression <code>nullptr</code> is encoded as
"LDnE".  In contrast, a template argument which happens to be a null
pointer (an extension made standard in C++11) is mangled as if it were
a literal <code>0</code> of the appropriate pointer type; for example,
"LPi0E" or "LDn0E".  This inconsistency is an unfortunate accident.

<a name="mangling.declaration-reference">
<h5><a href="#mangling.declaration-reference">5.1.6.2 References to declared entities</a></h5>

<p>
A reference to an entity with external linkage is encoded with
"L&lt;mangled name&gt;E".
For example:
<code><pre>
          void foo(char); // mangled as _Z3fooc
          template&lt;void (&)(char)&gt; struct CB;
          // CB&lt;foo&gt; is mangled as "2CBIL_Z3foocEE"
</pre></code>

<p>
The &lt;<a href="#mangle.encoding">encoding</a>&gt; of an extern "C" function is treated like
global-scope data,
i.e. as its &lt;<a href="#mangle.source-name">source-name</a>&gt; without a type.
For example:
<code><pre>
          extern "C" bool IsEmpty(char *); // (un)mangled as IsEmpty
          template&lt;void (&)(char *)> struct CB;
          // CB&lt;IsEmpty&gt; is mangled as "2CBIL_Z7IsEmptyEE"

</pre></code>

<p>
When encoding template signatures, a name appearing in the source code
cannot always be resolved to a specific entity: In such cases the
<code>&lt;<a href="#mangle.encoding">encoding</a>&gt;</code> production (via
<code>&lt;<a href="#mangle.expr-primary">expr-primary</a>&gt;</code>) does not apply, and instead the
<code>&lt;<a href="#mangle.unresolved-name">unresolved-name</a>&gt;</code> encoding is used.  For example:
<code><pre>
          template&lt;class T> auto f(T p)->decltype(p->x);
            // The return type in the mangling of the template signature
            // is encoded as "Dtptfp_1xE".
          template&lt;class T> auto f(T p)->decltype(T::X::y);
            // The return type in the mangling of the template signature
            // is encoded as "DtsrNT_1XE1yE" (note how &lt;<a href="#mangle.type">type</a>&gt; is a
            // &lt;<a href="#mangle.nested-name">nested-name</a>&gt; for T::X in this case).
          template&lt;class T> auto f(T p)->decltype(p->::A::B::x);
            // The return type in the mangling of the template signature
            // is encoded as "Dtptfp_gssr1A1BE1xE".
          template&lt;class T> auto f(T p)->decltype(p->x)::Y;
            // The return type in the mangling of the template signature
            // is encoded as "NDtptfp_1xE1YE".
</pre></code>
In the case of member selection operations, the <code>&lt;<a href="#mangle.unresolved-name">unresolved-name</a>&gt;</code> 
is used even if the indicated member is actually known.  Similarly,
an <code>&lt;<a href="#mangle.unresolved-qualifier-level">unresolved-qualifier-level</a>&gt;</code> may encode a known
class type.
That production is also used for references to nonstatic members with no
associated expression designating the enclosing object (a C++11 feature).
For example:
<code><pre>          struct Q { int x; } q;
          template&lt;class T> auto f(T p)->decltype(p.x + q.x);
            // The return type in the mangling of the template signature
            // is encoded as "DTpldtfp_1xdtL_Z1qE1xE".
          template&lt;class T> auto f(T p)->decltype(p.x + Q::x);
            // The return type in the mangling of the template signature
            // is encoded as "DTpldtfp_1xsr1QE1xE".
          template&lt;class T> struct X { static T x; };
          struct B: X&lt;int&gt; {};
          struct D: B {} d;
          template&lt;class T&gt; auto f(T p)->decltype(p+d.B::X&lt;T&gt;::x);
            // The return type in the mangling of the template signature
            // is encoded as "DTplfp_dtL_Z1dEsr1B1XIT_EE1xE".  (The
            // "1B" part is a &lt;<a href="#mangle.unresolved-qualifier-level">unresolved-qualifier-level</a>&gt; encoding
            // a resolved type.)
</pre></code>
If the <code>&lt;<a href="#mangle.unresolved-name">unresolved-name</a>&gt;</code> refers to an operator for
which both unary and binary manglings are available, the mangling
chosen is the mangling for the binary version.
For example:
<code><pre>
          template&lt;class T> auto f(T p)->decltype(&T::operator-);
            // The return type in the mangling of the template signature
            // is encoded as "DTadsrT_onmiE".
</pre></code>
</p>

<a name="mangling-scope">
<h4><a href="#mangling-scope">5.1.7 Scope Encoding</a></h4>

<p>Entities declared in non-global scopes must include their scope in
their mangled name.  For entities declared outside of function
definitions, this is dictated by the rules laid out for &lt;<a
href="#mangle.name">name</a>&gt;.  Entities declared within function
definitions usually do not require a well-defined mangling because
only one translation unit has access to the entity.  However,
different translation units must agree about the address of entities
declared within inline functions, including template specializations.
Therefore this ABI defines a mangling for even local entities.

<p>The mangling of a local entity is composed of three elements: the
mangling of the enclosing function, the mangling of the entity
relative to the function, and an optional discriminator within the
function:

<code><pre><font color=blue>  &lt;<a name="mangle.local-name">local-name</a>&gt; ::= Z &lt;<i>function</i> <a href="#mangle.encoding">encoding</a>&gt; E &lt;<i>entity</i> <a href="#mangle.name">name</a>&gt; [&lt;<a href="#mangle.discriminator">discriminator</a>&gt;]
               ::= Z &lt;<i>function</i> <a href="#mangle.encoding">encoding</a>&gt; E s [&lt;<a href="#mangle.discriminator">discriminator</a>&gt;]

  &lt;<a name="mangle.discriminator">discriminator</a>&gt; ::= _ &lt;<i>non-negative</i> <a href="#mangle.number">number</a>&gt;      # when number < 10
                  ::= __ &lt;<i>non-negative</i> <a href="#mangle.number">number</a>&gt; _   # when number >= 10
</font></pre></code>

<p>The enclosing function is the closest function enclosing the
entity.  That is, when an entity <i>E</i> is declared within a
function that is itself local to another function, the
&lt;<a href="#mangle.encoding">encoding</a>&gt; beginning the
mangling of <i>E</i> will itself be a
&lt;<a href="#mangle.local-name">local-name</a>&gt;,
perhaps recursively.

<p>The name of a declared local entity is mangled with the rules for
&lt;<a href="#mangle.name">name</a>&gt; as if the function were the
global scope.  That is, an entity declared directly within the
function (e.g. a local type or <code>static</code> local variable) is
mangled using an unscoped name, whereas a member of a local type will
be mangled with a &lt;<a href="#mangle.nested-name">nested-name</a>&gt;.

<p>It is possible to declare multiple entities with the same name
within a function if they are declared in different scopes.  In this
case, a discriminator must be added to the
&lt;<a href="#mangle.local-name">local-name</a>&gt;.  Entities with
the same "top-level" name are numbered in
<a href="#lexical-ordering">lexical order</a> within
the function definition.  A discriminator is added only for the second
and later occurrences of the same name, and so the
&lt;<a href="#mangle.number">number</a>&gt; in the discriminator
is actually <i>n-2</i> for the <i>n</i>th occurrence.  "Top-level"
here means the name declared directly in the local scope; e.g.,
if there are three classes named <code>X</code> in a given function
<code>g</code>, and only the third has a member function <code>f</code>,
the name of <code>X::f</code> in <code>g</code> will still include
the discriminator <font color="blue"><code>_1</code></font> (because
<i>3 - 2 == 1</i>).

<p>For unnamed local types (excluding types with a name for linkage
purposes), the "name" is encoded as an
&lt;<a href="#mangle.unnamed-type-name">unnamed-type-name</a>&gt; of
the form

<pre><code><font color=blue> &lt;<a name="mangle.unnamed-type-name">unnamed-type-name</a>&gt; ::= Ut [&lt;<i>nonnegative</i> <a href="#mangle.number">number</a>&gt; ] _
</pre></font></code>

where the number is is omitted for the first unnamed type in the
function, and <i>n</i>-2 for the <i>n</i>th unnamed type
(in <a href="#lexical-ordering">lexical order</a>) otherwise.

<p>
For example:
<code><pre>
	inline void g(int) {
	  { struct S {}; }
	  { struct S {}; }
	  { struct S {}; }
	  struct S {        // Fourth occurrence: _2
	    void f(int) {   // _ZZ1giEN1S1fE_2i
	      struct {} x1;
	      struct {} x2;
	      struct {      // Third occurrence: 1_, i.e.
	                    // _ZZZ1giEN1S1fE_2iEUt1_
	        int fx() {  // _ZZZ1giEN1S1fE_2iENUt1_2fxEv
 	          return 3;
                }
	      } x3;
	      x3.fx();
	    }
	  } s;
	  s.f(1);
	}
</pre></code>


<p>
The second production in &lt;<a href="#mangle.local-name">local-name</a>&gt;
is used for string literals.  The discriminator is used only if there
is more than one, for the second and subsequent ones.  In this case
again &lt;<a href="#mangle.number">number</a>&gt; is <i>n</i>-2 for
the <i>n</i>th distinct string literal, in
<a href="#lexical-ordering">lexical order</a>, appearing in
the function.  Multiple references to the same string literal produce
one string object with one name in the sequence.  <i>Note that this
assumes that the same string literal occurring twice in a given
function in fact represents a single entity, i.e. has a unique
address.</i>

<p>
For entities in constructors and destructors, the mangling of the
complete object constructor or destructor is used as the base function
name, i.e. the <font color="blue"><code>C1</code></font> or <font
color="blue"><code>D1</code></font> version.  This yields mangled
names that are consistent across the versions.

<p>
Example:
<code><pre>
	inline char const* g() {
	  "str1";                   // First string in g()
	  struct B {};
	  struct S: B {
	    S()                     // Complete object ctor: _ZZ1gvEN1SC1Ev
	      : msg("str2") {}      // First string in g()::S::S():
	                            //      _ZZZ1gvEN1SC1EvEs
	    char const *msg;
	  } s;
	  "str3";                   // Second string in g()
	  static char const *str4a  // _ZZ1gvE5str4a
	     = "str4";              // Third string in g() (n-2 == 1):
	                            //      _ZZ1gvEs_1
	  static char const *str4b  // _ZZ1gvE5str4b
	     = "str4";              // Still the third string (_ZZ1gvEs_1)
	  return str4b;
	}
</pre></code>

See additional examples in the
<a href=abi-examples.html#mangling-ex>ABI examples</a> document.


<p>
<a name="closure-types">
<h4><a href="#closure-types">5.1.8 Closure Types (Lambdas)</a></h4>

<p>
A lambda expression introduces a unique class type called
<i>closure type</i>.  In some contexts, such closure types are
unique to the translation unit: This ABI therefore does not specify an
encoding for such cases (but an implementation must ensure that any
internal encoding does not conflict with this ABI).
<p>
For example:
<code><pre>namespace N {
  int n = []{ return 1; }();  // Closure type internal to
}                             // the translation unit.
</pre></code>

In the following contexts, however, the one-definition rule requires
closure types in different translation units to "correspond":
<ul>
<li>default arguments appearing in class definitions</li>
<li>default member initializers</li>
<li>the bodies of inline or templated functions</li>
<li>the initializers of inline or templated variables</li>
</ul>

In all these contexts, the encoding of the closure types builds on an
underlying &lt;<a href="#mangle.unqualified-name">unqualified-name</a>&gt; that is an &lt;<a href="#mangle.unnamed-type-name">unnamed-type-name</a>&gt; of
the form
<pre><code><font color=blue>  &lt;<a name="mangle.unnamed-type-name">unnamed-type-name</a>&gt; ::= &lt;<a href="#mangle.closure-type-name">closure-type-name</a>&gt;

  &lt;<a name="mangle.closure-type-name">closure-type-name</a>&gt; ::= Ul &lt;<a href="#mangle.lambda-sig">lambda-sig</a>&gt; E [ &lt;<i>nonnegative</i> <a href="#mangle.number">number</a>&gt; ] _ 
</pre></font></code>
with
<pre><code><font color=blue>  &lt;<a name="mangle.lambda-sig">lambda-sig</a>&gt; ::= &lt;<i>parameter</i> <a href="#mangle.type">type</a>&gt;+  # Parameter types or "v" if the lambda has no parameters
</pre></font></code>
The number is omitted for the first closure type with a given
&lt;<a href="#mangle.lambda-sig">lambda-sig</a>&gt; in a given context; it is n-2 for the nth closure
type (in <a href="#lexical-ordering">lexical order</a>)
with that same &lt;<a href="#mangle.lambda-sig">lambda-sig</a>&gt; and context.
<p>

<p>
If the context is the body of a function (inline and/or template), the
closure type is encoded like any other local entity (see
<a href=#mangling-scope>Scope Encoding</a> above).  For example:
<code><pre>
	template&lt;typename F> int algo(F fn) { return fn(); }
	inline void g(int n) {
	  int bef(int i = []{ return 1; }());
	    // Default arguments of block-extern function declarations
	    // remain in the context of the encloding function body.
	    // The closure type is encoded as Z1giEUlvE_.
	    // The call operator of that type is _ZZ1giENKUlvE_clEv.

	  algo([=]{return n+bef();});
	    // The captured entities do not participate in &lt;<a href="#mangle.lambda-sig">lambda-sig</a>&gt;
	    // and so this closure type has the same &lt;<a href="#mangle.lambda-sig">lambda-sig</a>&gt; as
	    // the previous one.  It encoding is therefore Z1giEUlvE0_
	    // and the call operator is _ZZ1giENKUlvE0_clEv.  The
	    // instance of "algo" being called is then
	    // _Z4algoIZ1giEUlvE0_EiT_.
	}
</pre></code>

<p>
If the context is a default argument (of a member function parameter)
appearing in a class definition, the closure class and its members are encoded as follows:
<code><pre><font color=blue>  &lt;<a href="#mangle.local-name">local-name</a>&gt; ::= Z &lt;<i>function</i> <a href="#mangle.encoding">encoding</a>&gt; Ed [ &lt;<i>parameter</i> <a href="#mangle.number">number</a>&gt; ] _ &lt;<i>entity</i> <a href="#mangle.name">name</a>&gt;
</font></pre></code>
The parameter number is omitted for the last parameter, 0 for the second-to-last parameter, 1 for the third-to-last parameter, etc. 
The <code>&lt;<i>entity</i> <a href="#mangle.name">name</a>&gt;</code> will of course contain a
<code>&lt;<a href="#mangle.closure-type-name">closure-type-name</a>&gt;</code>: Its numbering will be local to the
particular argument in which it appears -- other default arguments do
not affect its encoding.
 For example:
<code><pre>
	struct S {
	  void f(int = []{return 1;}()
	           // Type: ZN1S1fEiiEd0_UlvE_
	           // Operator: _ZZN1S1fEiiEd0_NKUlvE_clEv
	             + []{return 2;}(),
	           // Type: ZN1S1fEiiEd0_UlvE0_
	           // Operator: _ZZN1S1fEiiEd0_NKUlvE0_clEv
	         int = []{return 3;}());
	           // Type: ZN1S1fEiiEd_UlvE_
	           // Operator: _ZZN1S1fEiiEd_NKUlvE_clEv
	} s;
</pre></code>


<a name="mangle.closure-prefix"><p>
If the context of a closure type is an initializer for a class
member (static or nonstatic), inline variable, or variable template,
it is encoded in a qualified name with a
<code>&lt;<a href="#mangle.prefix">prefix</a>&gt;</code> of the form:
<code><pre><font color=blue>
    &lt;closure-prefix&gt; ::= [ &lt;<a href="#mangle.prefix">prefix</a>&gt; ] &lt;<i>variable or member</i> <a href="#mangle.unqualified-name">unqualified-name</a>&gt; M
                     ::= &lt;<i>variable template</i> <a href="#mangle.template-prefix">template-prefix</a>&gt; &lt;<a href="#mangle.template-args">template-args</a>&gt; M
</font></pre></code>
For example:
<code><pre>
	template&lt;typename T> struct S {
	  static int x;
	};
	template&lt;typename T> int S&lt;T&gt;::x = []{return 1;}();
	template int S&lt;int&gt;::x;
	  // Type of lambda in intializer of S&lt;int&gt;::x: N1SIiE1xMUlvE_E
	  // Corresponding operator(): _ZNK1SIiE1xMUlvE_clEv
</pre></code>

<p>
In a generic lambda, uses of <code>auto</code> in the parameter list
are mangled as the corresponding artificial template type parameter.
This is never ambiguous with a lambda parameter whose type is an
enclosing template type parameter, because lambdas are never mangled
in a dependent context (they are forbidden from appearing in function
signatures).  A &lt;<a
href="#mangle.template-param">template-param</a>&gt; in a &lt;<a
href="#mangle.lambda-sig">lambda-sig</a>&gt; can only ever refer to a
template parameter of a generic lambda.

<p>
<a name="lexical-ordering">
<h4><a href="#lexical-ordering">5.1.9 Lexical ordering</a></h4>

<p>
Lexical ordering is used for numbering local entities (named and unnamed
local classes and enumerations, closure types, and static local variables)
when there is no other way of distinguishing them.  Except as described below,
all local entities are to be numbered, even if subsequent optimization makes
some of them unnecessary, or no mangled name is actually required for
some of them.

<p>
The order of entities is the source order of a key token unique to the
entity as if:

<ul>
<li>the discarded sub-statements of <tt>if constexpr</tt> within a
template did not exist and
<li>pack expansions were lexically expanded.
</ul>

<p>In all cases, this is meant to imitate the numbering that would
be produced by a simple implementation which numbered entities as it
processed the source and recursively expanded packs.  Since discarded
substatements of <tt>if constexpr</tt> are still processed in
non-template code, entities within them are still numbered.

<p>Entities may be lexically nested without being in different
contexts for the purposes of mangling.  For example, the lambdas in
<code>[x = []{}]{}</code> are both part of the enclosing context.
The order of such entities is determined by the source order of a key
token in the entity.  In general, this token is the first token
past which the signature of the entity (as is necessary to mangle it)
is known:

<ul>
<li>The key token of a class or enum is the end of the
  <code>enum-head-name</code> (<code>enum-key</code> if unnamed) or
  <code>class-head-name</code> (<code>class-key</code> if unnamed)
  in its first declaration.
<li>The key token of a lambda is its closing brace (<code>}</code>).
<li>The key token of a static local variable is the last token of its
  <code>declarator</code> (not its initializer).
</ul>

<p>
All entities from one expansion of a pack are considered to occur
lexically before any entities from the next expansion of the same pack,
but the ordering is otherwise based on the original token sequence.
This is expected to match the numbering that would be established for
the corresponding non-template generated by substitution into the template.
As a consequence of these rules, the entity instantiated for a particular
source construct can have a different mangling number in different
instantiations of the same template.  An entity appearing in the original
source may also go entirely un-numbered if it appears in a discarded
sub-statement of <code>if constexpr</code> or in a pack expansion of an
empty pack.  For example:

<code><pre>
void g(...);
template&lt;bool b, typename ...T> void f() {
  if constexpr(b) { []{}; }
  g(([]{}, []{ static T n; return &amp;n; }())...);
}

// The first lambda is discarded and does not receive a number.
// The variables passed to g are therefore mangled as
// _ZZZ1fILb0EJiiEEvvENKUlvE0_clEvE1n and
// _ZZZ1fILb0EJiiEEvvENKUlvE2_clEvE1n.
template void f&lt;false, int, int>();

// The variable passed to g is mangled as
// _ZZZ1fILb1EJiEEvvENKUlvE1_clEvE1n and
template void f&lt;true, int>();

// Both lambdas are numbered; returns _ZZZ1hvENKUlvE0_clEvE1n.
inline int *h() {
  if constexpr(false) { []{}; }
  return []{ static int n; return &amp;n; }();
}
</pre></code>

<p>
Note that the numbering of entities appearing within a
<code>mem-initializer-list</code> reflects the order that the
initializers appear in the source, which may be different from the
order in which the initializers will be executed when the program runs.

<p>
<a name="mangling-compression">
<h4><a href="#mangling-compression">5.1.10 Compression</a></h4>

<p>
To minimize the length of external names,
we use two mechanisms,
a substitution encoding to eliminate repetition of name components,
and abbreviations for certain common names.
Each non-terminal in the grammar above for which &lt;<a href="#mangle.substitution">substitution</a>&gt;
appears on the right-hand side is both a source of future substitutions
and a candidate for being substituted.
There are two exceptions that appear to be substitution
candidates from the grammar, but are explicitly excluded:
<ul>
<li> &lt;<a href="#mangle.builtin-type">builtin-type</a>&gt; other than vendor extended types, and
<li> function and operator names other than extern "C" functions.
</ul>

<p>
<i>
All substitutions are for entities that would appear in a symbol table.
In particular,
we make substitutions for prefixes of qualified names,
but not for arbitrary components of them.
Thus, the components ::n1::foo() and ::n2:foo() appearing in the same
name would not result in substituting for the second "foo."
Similarly, we do not substitute for expressions,
though names appearing in them might be substituted.
The reason for this is to facilitate implementations that use the
symbol table to keep track of components that might be substitutable.

<p>
Note that the above exclusion of function and operator names from
consideration for substitution does <u>not</u> exclude the full
function entity, i.e. its name plus its signature encoding.
</i>

<p>
Logically, the substitutable components of a mangled name are
considered left-to-right,
components before the composite structure of which they are a part.
If a component has been encountered before,
it is substituted as described below.
This decision is independent of whether its components have been substituted,
so an implementation may optimize by considering large structures
for substitution before their components.
If a component has not been encountered before,
its mangling is identified,
and it is added to a dictionary of substitution candidates.
No entity is added to the dictionary twice.

<p>
The type of a non-static member function is considered to be
different, for the purposes of substitution, from the type of a
namespace-scope or static member function whose type appears similar.
The types of two non-static member functions are considered to be
different, for the purposes of substitution, if the functions are
members of different classes.  In other words, for the purposes of
substitution, the class of which the function is a member is
considered part of the type of function.
</p>

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>
Therefore, in the following example:
<blockquote><code><pre>
typedef void T();
struct S {};
void f(T*, T (S::*)) {}
</pre></code></blockquote>
the function <code>f</code> is mangled as
<code>_Z1fPFvvEM1SFvvE</code>; the type of the member function pointed
to by the second parameter is not considered the same as the type of
the function pointed to by the first parameter.  Both function types
are, however, entered the substitution table; subsequent references to
either variant of the function type will result in the use of
substitutions.
</i></p>

<p>
Substitutions are mangled using the usual rules for &lt;<a href="#mangle.seq-id">seq-id</a>&gt;:

<pre><font color=blue><code>
  &lt;<a name="mangle.substitution">substitution</a>&gt; ::= S &lt;<a href="#mangle.seq-id">seq-id</a>&gt; _
		 ::= S_

</pre></font></code>

<p>Substitutable components are numbered left-to-right.  A component
is earlier in the substitution dictionary than the structure of which
it is a part.  All substitutable components are numbered, except those
that have already been numbered for substitution.  For example:

<code><pre>
   "_ZN1N1TIiiE2mfES0_IddE": Ret? N::T&lt;int, int&gt;::mf(N::T&lt;double, double&gt;)
</pre></code>

since the substitutions generated for this name are:
<code><pre>
   "S_" == N (qualifier is less recent than qualified entity)
   "S0_" == N::T (template-id comes before template)
	(int is builtin, and isn't considered)
   "S1_" == N::T&lt;int, int&gt;
   "S2_" == N::T&lt;double, double&gt;
</pre></code>

<p>
Note that substitutable components are the represented symbolic constructs,
not their associated mangling character strings.
Thus, a substituted object matches its unsubstituted form,
and a delimited &lt;<a href="#mangle.function-type">function-type</a>&gt; matches its &lt;<a href="#mangle.bare-function-type">bare-function-type</a>&gt;.

<p>
In addition,
the following catalog of abbreviations of the form "Sx" are used:
<pre><font color=blue><code>
   &lt;<a name="mangle.substitution">substitution</a>&gt; ::= St # ::std::
   &lt;<a name="mangle.substitution">substitution</a>&gt; ::= Sa # ::std::allocator
   &lt;<a name="mangle.substitution">substitution</a>&gt; ::= Sb # ::std::basic_string
   &lt;<a name="mangle.substitution">substitution</a>&gt; ::= Ss # ::std::basic_string &lt; char,
						 ::std::char_traits&lt;char&gt;,
						 ::std::allocator&lt;char&gt; &gt;
   &lt;<a name="mangle.substitution">substitution</a>&gt; ::= Si # ::std::basic_istream&lt;char,  std::char_traits&lt;char&gt; &gt;
   &lt;<a name="mangle.substitution">substitution</a>&gt; ::= So # ::std::basic_ostream&lt;char,  std::char_traits&lt;char&gt; &gt;
   &lt;<a name="mangle.substitution">substitution</a>&gt; ::= Sd # ::std::basic_iostream&lt;char, std::char_traits&lt;char&gt; &gt;

</pre></font></code>

<p>
Note that the abbreviation St does not require N...E delimiters unless
either followed by more than one additional composite name component,
or preceded by CV-qualifiers or a ref-qualifier for a member function.
For example:
<code><pre>
   "_ZSt5state": ::std::state
   "_ZNSt3_In4wardE": ::std::_In::ward
</pre></code>


<p> <hr> <p>
<a name="vague">
<h3><a href="#vague"> 5.2 Vague Linkage </a></h3>

<p>
Many objects in C++ are not clearly part of a single object file,
but are required by the ODR to have a single definition.
This section identifies, for such objects,
where (i.e. in which objects) they should be emitted,
and what special treatment might be required if duplicates are possible.

<p>
In many cases,
we will deal with duplicates by putting possibly duplicated objects
in distinct ELF sections or groups of sections,
and using the COMDAT feature of <code>SHT_GROUP</code> sections in the
gABI to remove duplicates.
We will refer to this simply as using a COMDAT group,
and specify the symbol to be used to identify duplicates in the
<code>SHT_GROUP</code> section.
<i>
COMDAT groups are a new gABI feature specified during the Itanium ABI
definition, and may not be implemented everywhere immediately.
See the separate <a href=abi-examples.html#vague>ABI examples</a>
document for a discussion of alternatives pending COMDAT implementation.
</i>

<p>
Note that nothing in this section should be construed to require COMDAT
usage for objects with internal linkage unless they may in fact be
referenced outside the translation unit where they appear,
for instance due to inlining.


<p>
<a name="vague-inline">
<h4><a href="#vague-inline"> 5.2.1 Out-of-line Functions </a></h4>

<p>
It may sometimes be necessary or desirable to reference an out-of-line
copy of a function declared inline,
i.e. to reference a global symbol naming the function.
This may occur because the implementation cannot, or chooses not to,
inline the function, or because it needs an address rather than a call.
In such a case,
the function is to be emitted in each object where its name is referenced.
A COMDAT group is used to eliminate duplicates,
with the mangled name of the function as the identifying symbol.


<p>
<a name="vague-static">
<h4><a href="#vague-static"> 5.2.2 Static Data </a></h4>

<p>
Inline functions, whether or not declared as such,
and whether they are inline or out-of-line copies,
may reference static data or character string literals,
that must be kept in common among all copies
by using the local symbol mangling defined above.
These objects are named according to the rules for local names in the
<a href=#mangling-scope> Scope Encoding </a> section above,
and the definition of each is emitted in a COMDAT group,
identified by the symbol name described in the
<a href=#mangling-scope> Scope Encoding </a> section above.
Each COMDAT group must be emitted in any object with references
to the symbol for the object it contains, whether inline or out-of-line.

<p>
Some objects with static storage duration have associated guard variables
used to ensure that they are initialized only once
(see <a href=once-ctor>3.3.3</a>).
If the object is emitted using a COMDAT group,
the guard variable must be too.
It is suggested that it be emitted in the same COMDAT group as the
associated data object,
but it may be emitted in its own COMDAT group,
identified by its name.
In either case, it must be weak.


<p>
<a name="vague-vtable">
<h4><a href="#vague-vtable"> 5.2.3 Virtual Tables</a></h4>

<p>
The virtual table for a class is emitted in the same object containing
the definition of its <i>key function</i>,
i.e. the first non-pure virtual function
that is not inline at the point of class definition.
If there is no key function, it is emitted everywhere used.
The emitted virtual table includes the full virtual table group for the class,
any new construction virtual tables required for subobjects,
and the VTT for the class.
They are emitted in a COMDAT group,
with the virtual table mangled name as the identifying symbol.
<i>
Note that if the key function is not declared inline in the class definition,
but its definition later is always declared inline,
it will be emitted in every object containing the definition.</i>
A constexpr or consteval function is always declared constexpr or consteval on
its first declaration, and is implicitly inline, so is never a key function.

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>In the abstract, a pure virtual destructor could be used as the key
function, as it must be defined even though it is pure.  However, the
ABI committee did not realize this fact until after the specification
of key function was complete; therefore a pure virtual destructor
cannot be the key function.</i>

<p>
<a name="vague-rtti">
<h4><a href="#vague-rtti"> 5.2.4 Typeinfo</a></h4>

<p>
The RTTI std::type_info structure for a complete class type is
emitted in the same object as its virtual table if dynamic,
or everywhere referenced if not.
The RTTI std::type_info structure for an incomplete class type is
emitted wherever referenced.
The RTTI std::type_info structures for various basic types as
specified by the <a href=#rtti>Run-Time Type Information</a> section
are provided by the runtime library.
The RTTI name NTBS objects are emitted with each referencing
std::type_info object.

<p>
The RTTI std::type_info structures for complete class types and basic
types are emitted in COMDAT groups identified by their mangled names.
The RTTI std::type_info structures for incomplete class types
are emitted with other than the ABI-defined complete type mangled names;
an implementation may choose to emit them as local static objects,
or in COMDAT groups with implementation-defined names and COMDAT identifiers.
The RTTI name NTBS objects are emitted in separate COMDAT groups
identified by the NTBS mangled names
as weak symbols.

<p>
<a name="vague-ctor">
<h4><a href="#vague-ctor"> 5.2.5 Constructors and Destructors</a></h4>

<p>
Constructors and destructors for a class, whether implicitly-defined
or user-defined, are emitted under the same rules as other functions.
That is, user-defined constructors or destructors, unless the function
is declared inline, or has internal linkage, are emitted where
defined, with their complete, and base object variants.  For
destructors, in classes with a virtual destructor, the deleting
variant is emitted as well.  A user-defined constructor or destructor
with non-inline, internal linkage is emitted where defined, with only
the variants actually referenced.  Implicitly-defined or inline
user-defined constructors and destructors are emitted where
referenced, each in its own COMDAT group identified by the constructor
or destructor name.

<p>
This ABI does not require the generation or use of allocating constructors or
inheriting constructors, and does not require the generation or use of deleting
destructors for classes without a virtual destructor.  However, if an
implementation emits such functions, it must use the external names specified
in this ABI.  If such a function has external linkage, it must be emitted
wherever referenced, in a COMDAT group whose name is the external name of the
function.

<p>
<a name="vague-itemplate">
<h4><a href="#vague-itemplate"> 5.2.6 Instantiated Templates</a></h4>

<p>
An instantiation of a class template requires:

<ul>
<p>
<li> In the object where instantiated,
    the virtual table, any subobject construction virtual tables, and the VTT,
    are emitted in a COMDAT identified by the virtual table mangled name.
<p>
<li> 
    Any static member data object is emitted in a COMDAT identified by
    its mangled name,
    in any object file with a reference to its name symbol.
<p>
<li> In the object where instantiated,
    virtual member functions are emitted in COMDAT groups
    identified by the function name.
<p>
<li> A non-inline, non-virtual member function is emitted in any object
    where its symbol is referenced
    (i.e. if the function is called without inlining,
    or its name is referenced without calling it),
    in a COMDAT group identified by the function name.
</ul>

<p>
An instantiation of a function template or member function template
is emitted in any object where its symbol is referenced (non-inline),
in a COMDAT group identified by the function name.


<p> <hr> <p>
<a name="unwind">
<h3><a href="#unwind"> 5.3 Unwind Table Location </a></h3>

<p>
As described in the Itanium psABI,
Itanium implementations shall produce unwind table entries in a
<code>SHT_IA_64_UNWIND</code> section,
and unwind information descriptors in a section that will be linked
with the associated code.
Itanium linkers shall put the unwind table,
the unwind information table,
and the associated code in a single text segment,
with a <code>PT_IA_64_UNWIND</code> program table entry identifying the
unwind table location.


<p>
<hr>

<p> <hr> <p>

<h2><a name="revisions">Appendix R: Revision History</a></h2>
<p> <hr>
<p class="revision"><span class="date">[160602]</span>
  Describe <code>abi_tag</code> mangling.</p>

<p class="revision"><span class="date">[160907]</span>
  Introduce layout restrictions on virtual table pointers stored in objects and VTTs.</p>

<p class="revision"><span class="date">[151021]</span>
  Support transaction-safe functions.</p>

<p class="revision"><span class="date">[151019]</span>
  Add mangling for unresolved names rooted in template
  template parameters.</p>

<p class="revision"><span class="date">[150518]</span>
  Allow arbitrary arguments (encoded as template arguments)
  in the mangling of vendor-specific type qualifiers.</p>

<p class="revision"><span class="date">[150502]</span>
  Clarify mangling of nested and local names and correct
  an ambiguity in prefix mangling.</p>

<p class="revision"><span class="date">[150204]</span>
  Fix alignment calculation for empty proper base classes.</p>

<p class="revision"><span class="date">[150204]</span>
  Add mangling for lifetime-extended temporaries.</p>

<p class="revision"><span class="date">[150204]</span>
  Add mangling for captured template parameter packs.</p>

<p class="revision"><span class="date">[150204]</span>
  Add mangling for braced initializer lists.</p>

<p class="revision"><span class="date">[150204]</span>
  Define behavior for variadic arguments of non-trivial type.</p>

<p class="revision"><span class="date">[140427]</span>
  Add mangling for dependent elaborated type specifiers.</p>

<p class="revision"><span class="date">[130911]</span>
  Add mangling for null template arguments.</p>

<p class="revision"><span class="date">[130710]</span>
  Add mangling for <code>operator ""</code>.</p>

<p class="revision"><span class="date">[130617]</span>
  Fix an editorial error in the mangling of floating-point literals.</p>

<p class="revision"><span class="date">[130606]</span>
  Clarify rules for POD types in the face of the C++11 changes to the
  definition of POD.  Minor restructuring for clarity in the mangling
  section.</p>

<p class="revision"><span class="date">[130422]</span>
  Add mangling for <code>decltype(auto)</code>.</p>

<p class="revision"><span class="date">[130403]</span>
  Add mangling for ref-qualifiers on function types.</p>

<p class="revision"><span class="date">[121211]</span>
  Add <code>__cxa_throw_bad_array_new_length</code> mangling.</p>

<p class="revision"><span class="date">[120925]</span>
  Add <code>noexcept</code> mangling.</p>

<p class="revision"><span class="date">[110306]</span>
  Update description of mangling for argument packs.</p>

<p class="revision"><span class="date">[110306]</span>
  Update description of mangling for argument packs.</p>

<p class="revision"><span class="date">[110301]</span>
  Change mangling for argument packs.</p>

<p class="revision"><span class="date">[101124]</span> 
  Revise mangling specification to cover instantiation-dependent
  expressions.</p>

<p class="revision"><span class="date">[100625]</span>
  Add <code>nullptr_t</code> mangling.</p>

<p class="revision"><span class="date">[100212]</span>
  Permit mangling of additional expression forms as template
  arguments.</p>

<p class="revision"><span class="date">[091124]</span>
  Document passing for IEEE 754r decimal and half-precision floating
  point types.</p>

<p class="revision"><span class="date">[091113]</span>
  Document mangling for IEEE 754r decimal and half-precision floating
  point types.</p>

<p class="revision"><span class="date">[091007]</span>
  Document handling of lambdas.</p>

<p class="revision"><span class="date">[090715]</span>
  Document handling of deleted virtual functions.</p>

<p class="revision"><span class="date">[090312]</span>
  Remove type stub expressions. Add mangling for <code>alignof</code>,
  function parameters, and a different mangling for N-argument
  function casts.</p>

<p class="revision"><span class="date">[090102]</span>
  Remove mangling for N-argument functional casts.</p>

<p class="revision"><span class="date">[081210]</span>
  Add manglings for type stub expressions, call expressions, char*_t,
  and N-argument functional casts.  Change argument pack mangling.</p>

<p class="revision"><span class="date">[080707]</span>
  Add manglings for IEEE 754r decimal and half-precision floating
  point types.</p>

<p class="revision"><span class="date">[072507]</span>
  Add mangling for variadic templates and decltype.</p>

<p class="revision"><span class="date">[071207]</span>
  Add mangling for rvalue references.</p>

<p class="revision"><span class="date">[031006]</span>
  Clarify that guard variables are used to guard static data members
  of class templates, as well as function-scope statics.</p>

<p class="revision"><span class="date">[030806]</span>
  Specify that function pointers in virtual tables are address/GP
  pairs on Itanium.</p>

<p class="revision"><span class="date">[050504]</span>
  Remove use of <code>out0</code> for by-value return types on
  Itanium.</p>

<p class="revision"><span class="date">[050211]</span>
  Reverse treatment of ambiguous arguments to __cxa_demangle (3.4).</p>

<p class="revision"><span class="date">[041118]</span>
  Clarify the layout of bit-fields.</p>

<p class="revision"><span class="date">[041025]</span>
  Indicate that the TC1 definition of POD is intended in the section
  defining a &quot;POD for the purpose of layout&quot;.  Clearly
  indicate that an array whose elements are not PODs for the purpose
  of layout is itself not a POD for the purpose of layout.</p>

<p class="revision"><span class="date">[040923]</span>
  Clarify behavior of <code>__cxa_vec_delete</code>.</p>

<p class="revision"><span class="date">[040219]</span>
  Clarify substition of member function types.</p>

<p class="revision"><span class="date">[031128]</span>
  Fix alphabetization of company names.</p>

<p class="revision"><span class="date">[031123]</span>
  Add note about forward references to template parameters in member
  template conversion operators.</p>

<p class="revision"><span class="date">[031102]</span>
  Specify the behavior of <code>__cxa_vec_delete</code> when the
  <code>array_address</code> is <code>NULL</code>.</p>

<p class="revision"><span class="date">[030905]</span>
  Specify the behavior of <code>__cxa_vec_new</code>,
  <code>__cxa_vec_new2</code>, and <code>__cxa_vec_new3</code> in
  the event that the allocation function returns <code>NULL</code>.</p>

<p class="revision"><span class="date">[030609]</span>
  Use <code>void*</code> instead of <code>dso_handle</code>.</p>

<p class="revision"><span class="date">[030518]</span>
  Specify behavior of <code>__cxa_vec_new2</code> and
  <code>__cxa_vec_new3</code> when the deallocation function
  throws an exception.</p>

<p class="revision"><span class="date">[030518]</span>
  Define &quot;POD for the purpose of layout.&quot;</p>

<p class="revision"><span class="date">[030316]</span>
  Add acknowledgements section.</p>

<p class="revision"><span class="date">[030313]</span>
  Correct broken links and incorrect formatting.</p>

<p class="revision"><span class="date">[030103]</span>
  Clarify definition of substantively different types.

<p class="revision"><span class="date">[021222]</span>
  Document mangling for anonymous unions.</p>

<p class="revision"><span class="date">[021204]</span>
  Remove note about 32-bit RTTI variation.</p>

<p class="revision"><span class="date">[021125]</span>
  Clarify guard functions.</p>

<p class="revision"><span class="date">[021110]</span>
  Clarify definition of nearly empty class.</p>

<p class="revision"><span class="date">[021110]</span>
  Clarify ordering of string literals in mem-initializer-list.</p>

<p class="revision"><span class="date">[021110]</span>
  Remove unnecessary V-adjusting thunks.</p>

<p class="revision"><span class="date">[021110]</span>
  Clarify VTT contents.</p>

<p class="revision"><span class="date">[021021]</span>
  Specify place and manner of emission for deleting destructors.</p>

<p class="revision"><span class="date">[021021]</span>
  Clarify mangling of pointer-to-member functions.</p>

<p class="revision"><span class="date">[021016]</span>
  Clarify mangling of floating-point literals.</p>

<p class="revision"><span class="date">[021014]</span>
  Clarify use of <code>sr</code> in mangling.</p>

<p class="revision"><span class="date">[021011]</span>
  Add mangling for unary plus.</p>

<p class="revision"><span class="date">[021008]</span>
  Make the names used for constructors and destructor entry
  points consistent throughout.</p>

<p class="revision"><span class="date">[021008]</span>
  Define manglings for typename types.</p>

<p class="revision"><span class="date">[020916]</span>
  Clarify ordering of functions in virtual function table.
  Correct mangling substitution example.</p>

<p class="revision"><span class="date">[020906]</span>
  Add ternary expression variant.
  Remove use of &quot;low-order&quot; to describe bytes in
  guard variables.</p>

<p class="revision"><span class="date">[020827]</span>
  Clarify definition of nearly empty class, dsize, nvsize, nvalign.</p>

<p class="revision"><span class="date">[020827]</span>
  Clarify handling of tail-padding.</p>

<p class="revision"><span class="date">[020326]</span>
  Clarify wording in <code>__cxa_demangle</code> memory management
  specification.</p>

<p class="revision"><span class="date">[020220]</span>
  Clarify pointer to member function mangling (5.1.5).</p>

<p class="revision"><span class="date">[010407]</span>
  Don't assume that virtual functions can be called through
  intermediate bases.
  Add notes about missed opportunities.
  The VTT parm isn't mangled, either.</p>

<p class="revision"><span class="date">[010315]</span>
  Many outstanding updates.
  Empty classes passed as ordinary classes (3.1.3).
  Secondary virtual pointers for subobjects reachable via a
  virtual path (text of 2.6.1, text and example in 2.6.2).
  Note about locating virtual bases statically during
  construction (2.6.1).
  Rename IA-64 to Itanium throughout.
  Add __cxa_vec_cleanup (3.3.4).</p>

<p class="revision"><span class="date">[000817]</span>
  Updates from 17 August meeting, email.</p>

<p class="revision"><span class="date">[000807]</span>
  Added base document section (1.5).
  Further RTTI field name cleanup (2.9.4).
  Update proposed one-time construction API (3.3.3).
  Update proposed object construction priority API (3.3.5).
  Removed &lt;name&gt; substitution (5.1.2).
  COMDAT not generally necessary for internal linkage (5.2).
  COMDAT for local static guard variables (5.2.2).</p>

<p class="revision"><span class="date">[000727]</span>
  Updates from 20 July meeting.
  Added section on controlling object construction order (3.3.5).</p>

<p class="revision"><span class="date">[000707]</span>
  Introduce consistent type_info field names (2.9.4).
  Removed vmi flags for publicly/non-publicly inherited bases (2.9.4).
  Collect all construction/destruction APIs in one section (3.3).
  Added one-time initialization API (3.3.3).
  Vector construction/destruction routines are extern "C" (3.3.4).
  Added routines for vector construction/destruction (3.3.4).
  Added copy construction runtime API (3.3.4).
  Make Alex's changes in mangling grammar (5.1).
  Add &lt;special-name&gt; cases for covariant override thunks (5.1.4).
  Allow expressions as array type dimensions (5.1.5).
  Discuss vague linkage for virtual function override thunks (5.2.6).</p>

<p class="revision"><span class="date">[000621]</span>
  Add scope section 1.4.
  Specify guard variables and vague linkage of static data (5.2.2)
  and instantiated templates (5.2.4).
  Clarify vcall offsets (2.5.3), VTT (2.6.2), mangling compression rules
  (5.1.7), and mangling examples.</p>

<p class="revision"><span class="date">[000511]</span>
  Specify 32-bit form of vmi_offset_flags.
  Add export template note.</p>

<p class="revision"><span class="date">[000505]</span>
  Updates from 4 May meeting.
  VTT is preorder, like everything else.
  Add issue C-3 destructor API.
  Added demangler API.
  Yet another try at the nested-name mangling grammar.
  Don't mangle builtin types (except vendor extended ones).
  Reverse mangling substitution order, and fix mangling
  substitution examples.
  Add vague linkage information for instantiated templates.
  Specify location of unwind tables.</p>

<p class="revision"><span class="date">[000502]</span>
  Fixed mangling of template parameters again.</p>

<p class="revision"><span class="date">[000427]</span>
  Reorganization and section numbering.
  Added <a href=#normal-call>non-virtual function calling
  conventions</a>.</p>

<p class="revision"><span class="date">[000417]</span>
  Updates from 17 April meeting.
  Clarify order of vcall offsets.
  More elaboration of construction virtual table.
  Specification of COMDAT RTTI name.
  Reorganization of pointer RTTI.
  Modify mangling grammar to clarify substitution in compound names.
  Clarify Vague Linkage section.</p>

<p class="revision"><span class="date">[000407]</span>
  Updates from 6 April meeting, email.
  More elaboration of construction vtable.
  Updates/issues in RTTI.
  Minor mangling changes.
  Added Vague Linkage section.</p>

<p class="revision"><span class="date">[000327]</span>
  Updates from 30 March meeting.
  Define base classes to include self, proper base classes.
  Modify local function mangling per JFW proposal.</p>

<p class="revision"><span class="date">[000327]</span>
  Updates from 23 March meeting.
  Adopt construction vtable Proposal B, and rewrite.
  Further work on mangling, especially substitution.</p>

<p class="revision"><span class="date">[000320]</span>
  Clarify class size limit.
  Editorial changes in vtable components description.
  Add alternate to construction vtable proposal.
  Clarification in array cookie specification.
  Removed COMMON proxy from class RTTI.
  Extensive changes to mangling writeup.</p>

<p class="revision"><span class="date">[000314]</span>
  Construction vtable modifications.
  RTTI modifications for incomplete class types.
  Mangling rework: grammar, new constructs, function return types.</p>

<p class="revision"><span class="date">[000309]</span>
  Add limits section.
  Specify NULL member pointer values.
  Combine vtable content and order sections; clarify ordering.
  Specify when distinct virtual function entries are needed for
  overriders.
  Define (and modify) vector constructor/destructor runtime APIs.
  Virtual base offsets are promoted from non-virtual bases.</p>

<p class="revision"><span class="date">[000228]</span>
  Add thunk definition.
  Revise inheritance graph order definition.
  Fix member function pointer description (no division by two).
  Move bit-field allocation description (much modified)
  to the non-virtual-base allocation description.
  Replace virtual function calling convention description.</p>

<p class="revision"><span class="date">[000228]</span>
  Add thunk definition.
  Revise inheritance graph order definition.
  Fix member function pointer description (no division by two).
  Move bit-field allocation description (much modified)
  to the non-virtual-base allocation description.
  Replace virtual function calling convention description.</p>

<p class="revision"><span class="date">[000217]</span>
  Add excess-size bit-field specification.
  Add namespace/header section.
  Touch up array new cookies.
  Remove construction vtable example to new file.
  Add mangling proposal.</p>

<p class="revision"><span class="date">[000214]</span>
  Complete array new cookie specification.
  Remove unnecessary RTTI flags.
  Correct repeated inheritance flag description.
  Move all type_info subclasses in namespace abi, not namespace std.
  Note requirements for an implementation to prevent users from
  emitting invalid vtables for RTTI classes.
  Include construction vtable proposal.</p>

<p class="revision"><span class="date">[000203]</span>
  Incorporate discussion of 3 Febrary.
  Remove __reference_type_info (issue A-22).
  Restructure struct RTTI and flags (issue A-23).
  Clarify __base_class_info layout.</p>

<p class="revision"><span class="date">[000125]</span>
  Incorporate discussion of 20 January, generally clarifications.
  Resolved A-19 (choice of a primary virtual base).
  Answered Nathan's questions about RTTI.
  Included RTTI "Deliberations" as rationale notes in the specification,
  or removed redundant ones.
  Added array operator new section.</p>

<p class="revision"><span class="date">[000119]</span>
  Clarify when virtual base offsets are required.
  Note that a vtable has offset-to-top and RTTI entries for classes
  with virtual bases even if there are no virtual functions.
  Resolve allocation of a virtual base class that is a primary base
  for another base (A-17).
  Resolve choice of a primary virtual base class that is a primary
  base for another base (A-19).
  Describe the (non-)effect of virtual bases on the alignment of
  the non-virtual part of a class as the base of another class (A-18).</p>

<p class="revision"><span class="date">[991230]</span>
  Integrate proposed resolution of A-16, A-17 in base class layout.
  Add outstanding questions list, and clean up questions in text.</p>

<p class="revision"><span class="date">[991229]</span>
  Clarify definition of nearly empty class, layout of virtual bases.</p>

<p class="revision">font color=blue>[991203]</span>
  Added description of vfunc calling convention from Jason.</p>

<p class="revision"><span class="date">[991104]</span>
  Noted pair of vtable entries for virtual destructors.</p>

<p class="revision"><span class="date">[991019]</span>
  Modified RTTI proposal for 14 October decisions.</p>

<p class="revision"><span class="date">[991006]</span>
  Added RTTI proposal.</p>

<p class="revision"><span class="date">[990930]</span>
  Updated to new vtable layout proposal.</p>

<p class="revision"><span class="date">[990811]</span>
  Described member pointer representations, virtual table layout.</p>

<p class="revision"><span class="date">[990730]</span>
  Selected first variant for empty base allocation; removed others.</p>

<hr>

</BODY>
</HTML>