Itanium C++ ABI ($Revision: 1.86 $)

This document was 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.

In this document, we specify the Application Binary Interface for C++ programs, that is, the object code interfaces between user C++ code and the implementation-provided system 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.

In general, this document is written as a generic specification, to be usable by C++ implementations on a variety of architectures. However, it does contain processor-specific material for the Itanium 64-bit ABI, identified as such. Where structured data layout is described, we generally assume Itanium psABI member sizes. An implementation for a 32-bit ABI would typically just change the sizes of members as appropriate (i.e. pointers and long ints would become 32 bits), but sometimes an order change would be required for compactness, and we note more substantive changes.

The descriptions below make use of the following definitions:

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

• 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.

This ABI specifies a number of type and function APIs supplemental to those required by the ISO C++ Standard. A header file named cxxabi.h 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.

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

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:

• are expected to be called by users from C code, e.g. longjmp_unwind; or
• are expected to be called only implicitly by compiled code, and are likely to be implemented in C.

1.4.1 Runtime Libraries

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

There are two principal reasons for this:

1. 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.

2. 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.

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:

• A program which uses only the standalone standard library interfaces (Chapter 18) does not depend on the problematic template features.

• 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.

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:

• 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

• the implicit compiler support library, which provides other interfaces implicitly assumed by the compiler and used to implement either standard features or extensions.

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.

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

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:

• the size of an object, sizeof(O);
• the alignment of an object, align(O); and
• the offset within O, offset(C), of each data component C, i.e. base or member.

For purposes internal to the specification, we also specify:

• dsize(O): the data size of an object, which is the size of O without tail padding.

• nvsize(O): the non-virtual size of an object, which is the size of O without virtual bases.

• nvalign(O): the non-virtual alignment of an object, which is the alignment of O without virtual bases.

2.5.1 General

A virtual table (vtable) 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.

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:

• Offsets are of type ptrdiff_t unless otherwise stated.
• Data pointers have normal pointer size and alignment.
• On Itanium, function pointers are pairs: the function address follwed 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.

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 address point of the virtual table. The virtual table may therefore contain components at either positive or negative offsets from its address point.

2.5.2 Virtual Table Components and Order

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.

Following the primary virtual table of a derived class are secondary virtual tables 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 virtual table group. 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:

• 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.)

• 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).

2.5.3 Virtual Table Construction

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.

Category 0: Trivial

• No virtual base classes.
• No virtual functions.

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

Category 1: Leaf

• No inherited virtual functions.
• No virtual base classes.
• Declares virtual functions.

The virtual table contains offset-to-top and RTTI fields followed by virtual function pointers. There is one function pointer entry for each virtual function declared in the class, in declaration order, with any implicitly-defined virtual destructor pair last.

Category 2: Non-Virtual Bases Only

• Only non-virtual proper base classes.
• Inherits virtual functions.

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:

• The offset-to-top and RTTI fields contain information for the class, rather than for the base class.

• 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).

For a proper base class Base, and a derived class Derived for which we are constructing this set of virtual tables, we shall refer to the virtual table for Base as Base-in-Derived. 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.

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 declared in the derived class (in declaration order) for which one of the following two conditions holds:

• The virtual function does not override any function already appearing in the virtual table.
• The virtual function overrides a function (or functions) appearing in the virtual table, but the return type of the overrider is substantively different from the return type of the function(s) already present. If the return types are different, they are both pointer-to-class types, or both reference-to-class types. Let B and D denote the classes, where D is derived from B. The types are substantively different if B is a morally virtual base of D or if B is not located at offset zero in D.

The primary virtual table can be viewed as two virtual tables accessed from a shared virtual table pointer.

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.

Category 3: Virtual Bases Only

Structure:

• Only virtual base classes (but those may have non-virtual bases).
• The virtual base classes are neither empty nor nearly empty.

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.

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.

• 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.

• 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.

• 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.

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.

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.

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 following function pointer entries, following those of any primary base's virtual table, in the virtual functions' declaration order:

• Entries for virtual functions introduced by this class, i.e. those not declared by any of its bases.
• Entries for overridden virtual functions from the base classes, called replicated entries because they are already in the secondary virtual tables of the class.

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.

Category 4: Complex

Structure:

• 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.

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:

• 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.

• As for the non-virtual base case, virtual function pointer entries from the derived class introductions occur only after the entries from the primary base class. There are entries for overridden virtual functions from the primary base class only if the result types are different (covariant). For purposes of this case, the two types are considered different if one of them is a non-primary or virtual base class of the other.

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.

Consider the following inheritance hierarchy:

  struct S { virtual void f() };
  struct T : virtual public S {};
  struct U : virtual public T {};
  struct V : public T, virtual public U {};

  struct W : public T {};

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.

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.

2.6.1 General

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.

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.

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.

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.

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.

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

  struct S {};
  struct T: virtual S {};
  struct U {};
  struct V: virtual T, virtual U {};

2.6.2 VTT Order

An array of virtual table addresses, called the VTT, 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.)

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

1. Primary virtual pointer: address of the primary virtual table for the complete object D.

2. Secondary VTTs: 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.

   This construction is applied recursively.

3. Secondary virtual pointers: 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.

   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.

   The order in which the virtual pointers appear in the VTT is inheritance graph preorder.

   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.

   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.

   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.

4. Virtual VTTs: For each proper virtual base classes in inheritance graph preorder, construct a sub-VTT as in (2) above.

   The virtual VTT addresses come last because they are only passed to the virtual base class constructors for the complete object.

Each virtual table address in the VTT is the address to be assigned to the respective virtual pointer, i.e. the address of the first virtual function pointer in the virtual table, not of the first vcall offset.

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 subclass 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.

When operator new 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.

Specifically:

• 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.

  (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.)

• No cookie is required if the new operator being used is ::operator new[](size_t, void*).

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

  These rules have the following consequences:

  • The array elements and the cookie are all aligned naturally.
  • Padding will be required if sizeof(size_t) is smaller than the array element alignment, and if present will precede the cookie.

Given the above, the following is pseudocode for processing new(ARGS) T[n]:

  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

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 guard variables name 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.

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.

2.9.1 General

The C++ programming language definition implies that information about types be available at run time for three distinct purposes:

1. to support the typeid operator,
2. to match an exception handler with a thrown object, and
3. to implement the dynamic_cast operator.

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.

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.

2.9.2 Place of Emission

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.

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, 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. (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 std::bad_alloc.)

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

  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);
    };
  }

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.

2.9.6 std::type_info::name()

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

• 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.)

• Converts the B* to point to this subobject. (Call the resulting pointer `a'.)

• Uses the virtual table pointer contained in the A subobject to locate the function pointer through which to perform the call.

• Calls through this function pointer, passing `a' as the this pointer.

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.)

3.2.5 Implementation

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:

  extern "C" void __cxa_pure_virtual ();

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.

3.3.4.1 Motivation

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.

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.

3.3.4.2 Source Code API

A user may specify the construction priority with the pragma:

    #pragma priority ( <priority> )

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.

3.3.4.3 Object File Representation

Initialization priority is represented in the object file by elements of a target-specific section type, SHT_IA_64_PRIORITY_INIT, with section ID 0x79000000 on Itanium, and section name .priority_init, and attributes allowing writing but not execution. The elements are structs:

	typedef struct {
	  ElfXX_Word	pi_pri;
	  ElfXX_Addr	pi_addr;
	} ElfXX_Priority_Init;

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.

3.3.4.4 Runtime Library Support

Each implementation supporting priority initialization shall provide a runtime library function with prototype:

    void __cxa_priority_init ( ElfXX_Priority_Init *pi, int cnt );

3.3.4.5 Linker Processing

The only required static linker processing is to concatenate the SHT_IA_64_PRIORITY_INIT 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.

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 SHT_IA_64_PRIORITY_INIT section, and (2) provide initial and final DT_INIT_ARRAY entries. The initial DT_INIT_ARRAY entry would need to sort the SHT_IA_64_PRIORITY_INIT section and call __cxa_priority_init to run the constructors with negative priority (in the source). The final DT_INIT_ARRAY entry would need to call __cxa_priority_init to run the constructors with non-negative priority. Other DT_INIT_ARRAY entries would thus run at the proper point in the priority sequence.

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

3.3.5.1 Motivation

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 atexit 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 dlclose prior to program termination.

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

3.3.5.2 Runtime Data Structure

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

• A function pointer (a pointer to a function descriptor on Itanium).
• A void* operand to be passed to the function.
• A void* handle for the home DSO of the entry (below).

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

3.3.5.3 Runtime API

1. Object construction:

   After constructing a global (or local static) object, that will require destruction on exit, a termination function is registered as follows:

   extern "C" int __cxa_atexit ( void (*f)(void *), void *p, void *d ); This registration, e.g. __cxa_atexit(f,p,d), is intended to cause the call f(p) when DSO d is unloaded, before all such termination calls registered before this one. It returns zero if registration is successful, nonzero on failure.

   The registration function is not called from within the constructor.

2. User atexit calls:

   When the user registers exit functions with atexit, they should be registered with NULL parameters and DSO handles, i.e.

   __cxa_atexit ( f, NULL, NULL ); It is expected that implementations supporting both C and C++ will integrate this capability into the libc atexit implementation so that C-only DSOs will nevertheless interact with C++ programs in a C++-standard-conforming manner. No user interface to __cxa_atexit is supported, so the user is not able to register an atexit function with a parameter or a home DSO.

3. Termination:

   When linking any DSO containing a call to __cxa_atexit, the linker should define a hidden symbol __dso_handle, 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):

   extern "C" void __cxa_finalize ( void *d ); The parameter passed should be &__dso_handle.

   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 __cxa_atexit, but they can be safely included in all objects.

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

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

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

Since __cxa_atexit and __cxa_finalize 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.

Synopsis:

namespace abi {
  extern "C" char* __cxa_demangle (const char* mangled_name,
				   char* buf,
				   size_t* n,
				   int* status);
}

• mangled-name 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.

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

• status 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.

Behavior: 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 __cxa_demangle.

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:

• 0: success
• -1: memory allocation failure
• -2: invalid mangled name
• -3: invalid arguments (e.g. buf nonnull and n null)

Memory management:

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

5.1.1 General

This section specifies the mangling, 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:

• Non-terminals are delimited by diamond braces: "<>".
• Italics in non-terminals are modifiers to be ignored, e.g. <function name> is the same as <name>.
• Spaces are to be ignored.
• Text beginning with '#' is comments, to be ignored.
• Tokens in square brackets "[]" are optional.
• Tokens are placed in parentheses "()" for grouping purposes.
• '*' repeats the preceding item 0 or more times.
• '+' repeats the preceding item 1 or more times.
• All other characters are terminals, representing themselves.