abi-eh.html

<HTML>

<HEAD>
<title>C++ ABI for Itanium: Exception Handling</title>

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

</HEAD>

<BODY>

<hr />
<h1>Itanium C++ ABI: Exception Handling ($Revision: 1.22 $)</h1>
<p> <hr> <p>

<h2> Contents </h2>

<ul>
<li> <a href=#intro> Introduction </a>
  <ul>
  <li> <a href=#defs> Definitions </a>
  <li> <a href=#docs> Base Documents </a>
  <!--
  <li> <a href=#issues> Open Issues </a>
  -->
  </ul>
<li> <a href=#layout> Level I: Base ABI </a>
  <ul>
  <li> <a href=#base-framework>	1.1 Exception Handler Framework </a>
  <li> <a href=#base-data>	1.2 Data Structures </a>
  <li> <a href=#base-throw>	1.3 Throwing an Exception </a>
  <li> <a href=#base-om>	1.4 Exception Object Management </a>
  <li> <a href=#base-context>	1.5 Context Management </a>
  <li> <a href=#base-personality> 1.6 Personality Routine </a>
  </ul>
<li> <a href=#cxx-abi> Level II: C++ ABI </a>
  <ul>
  <li> <a href=#cxx-intro>	2.1 Introduction </a>
  <li> <a href=#cxx-data>	2.2 Data Structures </a>
  <li> <a href=#cxx-init>	2.3 Standard Runtime Initialization </a>
  <li> <a href=#cxx-throw>	2.4 Throwing an Exception</a>
  <li> <a href=#cxx-catch>	2.5 Catching an Exception</a>
  <li> <a href=#cxx-aux>	2.6 Auxiliary Runtime APIs</a>
  </ul>
<li> <a href=#cxx-abi> Level III: Implementation </a>
  <ul>
  <li> <a href=#imp-intro>	3.1 Introduction </a>
  <li> <a href=#imp-data>	3.2 Data Structures </a>
  <li> <a href=#imp-init>	3.3 Runtime Initialization </a>
  <li> <a href=#imp-throw>	2.4 Throwing an Exception</a>
  <li> <a href=#imp-catch>	2.5 Catching an Exception</a>
  </ul>
<li> <a href=#revisions> Appendix R: Revision History</a>
</ul>


<p> <hr> <p>
<a name=intro></a>
<h3> Introduction </h3>

In this document, we define the C++ exception handling ABI,
at three levels:
<ol type=I>
<li> the <a href=#base-abi>base ABI</a>,
    interfaces common to all languages and implementations;
<li> the <a href=#cxx-abi>C++ ABI</a>,
    interfaces necessary for interoperability of C++ implementations; and
<li> the specification of a particular runtime implementation.
</ol>

<p>
This specification is based on the general model described roughly in the
<a href="http://download.intel.com/design/Itanium/Downloads/245358.pdf">
Itanium Software Conventions and Runtime Architecture Guide</a>.
However, the Level I (base ABI) specification here contradicts that
document in some particulars,
and is being proposed as a modification.
That document describes a framework which can be used by an arbitrary
implementation, with a complete definition of the stack unwind mechanism,
but no significant constraints on the language-specific processing.
In particular, it is not sufficient to guarantee that two object files
compiled by different C++ compilers could interoperate,
e.g. throwing an exception in one of them and catching it in the other.

<p>
In Section I below, we will elaborate missing details from this base
document, largely in the form of specifying the APIs to be used in
accessing the language-independent stack unwind facilities,
namely the unwind descriptor tables and the personality routines.
This specification should be implemented by any Itanium psABI-compliant
system.

<p>
In Section II below, we will specify the API of the C++ exception
handling facilities, specifically for raising and catching exceptions.
These APIs should be implemented by any C++ system compliant with the
Itanium C++ ABI.
<i>Note that the level II and level III specifications are not
completed at this time.</i>


<p> <hr> <p>
<a name=defs></a>
<h4> Definitions </h4>

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

<dl>
<p>
<dt><b><i>landing pad</i></b></dt>:
<dd> 
A section of user code intended to catch, or otherwise clean up after,
an exception.
It gains control from the exception runtime via the personality routine,
and after doing the appropriate processing either merges into the
normal user code or returns to the runtime by resuming
or raising a new exception.

</dl>


<p> <hr> <p>
<a name=docs></a>
<h4> Base Documents </h4>

<p>
This document is based on the
<a href=abi.html><b>C++ ABI for Itanium</b></a>,
and the Level II specification below is considered to be part of that
document (Chapter 4).
See <a href=abi.html#docs>Base Documents</a> in that document for
further references.


<!--
<font color=red>
<p> <hr> <p>
<a name=issues></a>
<h4> Open Issues </h4>
The following open issues remain to be resolved in this document:
<ol>
<p>
<li>
...
</ol>
</font>
-->


<p> <hr> <p>
<a name=base-abi></a>
<h3> Level I. Base ABI </h3>

<p>
This section defines the Unwind Library interface,
expected to be provided by any Itanium psABI-compliant system.
This is the interface on which the C++ ABI exception-handling
facilities are built.
We assume as a basis the unwind descriptor tables described in the base
<a
href="http://www.intel.com/design/itanium/downloads/245358.htm">Itanium
Software Conventions &amp; Runtime Architecture Guide</a>. 
Our focus here will on the APIs for accessing those structures.

<p>
It is intended that nothing in this section be specific to C++,
though some parts are clearly intended to support C++ features.

<p>
The unwinding library interface consists of at least the following
routines:
<code><pre>
  _Unwind_RaiseException,
  _Unwind_Resume,
  _Unwind_DeleteException,
  _Unwind_GetGR,
  _Unwind_SetGR,
  _Unwind_GetIP,
  _Unwind_SetIP,
  _Unwind_GetRegionStart,
  _Unwind_GetLanguageSpecificData,
  _Unwind_ForcedUnwind
</pre></code>

In addition, two datatypes are defined
(<code>_Unwind_Context</code> and <code>_Unwind_Exception</code>)
to interface a calling runtime (such as the C++ runtime)
and the above routines.
All routines and interfaces behave as if defined
<code>extern "C"</code>.
In particular, the names are not mangled.
All names defined as part of this interface have a
"<code>_Unwind_</code>" prefix.

<p>
Lastly, a language and vendor specific personality routine will be stored
by the compiler in the unwind descriptor for the stack frames requiring
exception processing.
The personality routine is called by the unwinder to handle
language-specific tasks such as identifying the frame handling a
particular exception.

<p>
<a name=base-framework></a>
<h4> 1.1  Exception Handler Framework </h4>

<p>
<h5> Reasons for Unwinding </h5>

<p>
There are two major reasons for unwinding the stack:
<ul>
<li> exceptions, as defined by languages that support them (such as C++)
<li> "forced" unwinding (such as caused by <code>longjmp</code>
or thread termination).
</ul>
The interface described here tries to keep both similar.
There is a major difference, however.

<ul>
<p>
<li>
In the case an exception is thrown,
the stack is unwound while the exception propagates,
but it is expected that the personality routine for each stack frame
knows whether it wants to catch the exception or pass it through.
This choice is thus delegated to the personality routine,
which is expected to act properly for any type of exception,
whether "native" or "foreign".
Some guidelines for "acting properly" are given below.

<p>
<li>
During "forced unwinding", on the other hand,
an external agent is driving the unwinding.
For instance, this can be the <code>longjmp</code> routine.
This external agent, not each personality routine,
knows when to stop unwinding.
The fact that a personality routine is not given a choice about
whether unwinding will proceed is indicated by the _UA_FORCE_UNWIND flag.

</ul>

<p>
To accomodate these differences, two different routines are proposed.
<code>_Unwind_RaiseException</code> performs exception-style unwinding,
under control of the personality routines.
<code>_Unwind_ForcedUnwind</code>, on the other hand,
performs unwinding,
but gives an external agent the opportunity to intercept
calls to the personality routine.
This is done using a proxy personality routine,
that intercepts calls to the personality routine,
letting the external agent override
the defaults of the stack frame's personality routine.

<p>
As a consequence, it is not necessary for each personality routine
to know about any of the possible external agents that may cause an unwind.
For instance,
the C++ personality routine need deal only with C++ exceptions
(and possibly disguising foreign exceptions),
but it does not need to know anything specific about unwinding done
on behalf of <code>longjmp</code> or pthreads cancellation.

<p>
<h5> The Unwind Process </h5>

<p>
The standard ABI exception handling / unwind process begins with
the raising of an exception,
in one of the forms mentioned above.
This call specifies an exception object and an exception class.

<p>
The runtime framework then starts a two-phase process:

<ul>
<p>
<li>
In the <i>search</i> phase,
the framework repeatedly calls the personality routine,
with the <code>_UA_SEARCH_PHASE</code> flag as described below,
first for the current PC and register state,
and then unwinding a frame to a new PC at each step,
until the personality routine reports either success
(a handler found in the queried frame)
or failure (no handler) in all frames.
It does not actually restore the unwound state,
and the personality routine must access the state through the API.
<p>
<li>
If the search phase reports failure,
e.g. because no handler was found,
it will call <code>terminate()</code> rather than commence phase 2.
<p>
If the search phase reports success,
the framework restarts in the <i>cleanup</i> phase.
Again, it repeatedly calls the personality routine,
with the <code>_UA_CLEANUP_PHASE</code> flag as described below,
first for the current PC and register state,
and then unwinding a frame to a new PC at each step,
until it gets to the frame with an identified handler.
At that point, it restores the register state,
and control is transferred to the user landing pad code.

</ul>

<p>
Each of these two phases uses both the unwind library and the
personality routines,
since the validity of a given handler and the mechanism for
transferring control to it are language-dependent,
but the method of locating and restoring previous stack frames
is language independent.

<p>
A two-phase exception-handling model is not strictly necessary to
implement C++ language semantics,
but it does provide some benefits.
For example, the first phase allows an exception-handling mechanism
to <i>dismiss</i> an exception before stack unwinding begins,
which allows <i>resumptive</i> exception handling
(correcting the exceptional condition and resuming execution at
the point where it was raised).
While C++ does not support resumptive exception handling,
other languages do, and the two-phase model allows C++ to coexist with
those languages on the stack.

<p>
Note that even with a two-phase model,
we may execute each of the two phases more than once for a single exception,
as if the exception was being thrown more than once.
For instance, since it is not possible to determine if
a given catch clause will rethrow or not without executing it,
the exception propagation effectively stops at each catch clause,
and if it needs to restart, restarts at phase 1.
This process is not needed for destructors (cleanup code),
so the phase 1 can safely process all destructor-only frames at once
and stop at the next enclosing catch clause.

<p>
For example, if the first two frames unwound contain only cleanup code,
and the third frame contains a C++ catch clause,
the personality routine in phase 1 does not indicate that it found a
handler for the first two frames.
It must do so for the third frame,
because it is unknown how the exception will propagate out of
this third frame,
e.g. by rethrowing the exception or throwing a new one in C++.

<p>
The API specified by the Itanium psABI for implementing this framework is
described in the following sections.


<p>
<a name=base-data></a>
<h4> 1.2  Data Structures </h4>

<p>
<b> Reason Codes </b>
<p>
The unwind interface uses reason codes in several contexts to identify
the reasons for failures or other actions, defined as follows:
<code><pre>
    typedef enum {
	_URC_NO_REASON = 0,
	_URC_FOREIGN_EXCEPTION_CAUGHT = 1,
	_URC_FATAL_PHASE2_ERROR = 2,
	_URC_FATAL_PHASE1_ERROR = 3,
	_URC_NORMAL_STOP = 4,
	_URC_END_OF_STACK = 5,
	_URC_HANDLER_FOUND = 6,
	_URC_INSTALL_CONTEXT = 7,
	_URC_CONTINUE_UNWIND = 8
    } _Unwind_Reason_Code;
</pre></code>
The interpretations of these codes are described below.

<p>
<b> Exception Header </b>
<p>
The unwind interface uses a pointer to an exception header object
as its representation of an exception being thrown.
In general, the full representation of an exception object is
language- and implementation-specific,
but it will be prefixed by a header understood by the unwind interface,
defined as follows:
<code><pre>
    typedef void (*_Unwind_Exception_Cleanup_Fn)
		(_Unwind_Reason_Code reason,
		 struct _Unwind_Exception *exc);

    struct _Unwind_Exception {
	    uint64			 exception_class;
	    _Unwind_Exception_Cleanup_Fn exception_cleanup;
	    uint64			 private_1;
	    uint64			 private_2;
    };
</pre></code>

<p>
An <code>_Unwind_Exception</code> object must be double-word aligned.
The first two fields are set by user code prior to raising the exception,
and the latter two should never be touched except by the runtime.

<p>
The <code>exception_class</code> field is a language- and
implementation-specific identifier of the kind of exception.
It allows a personality routine to distinguish between native and
foreign exceptions, for example.
By convention, the high 4 bytes indicate the vendor
(for instance HP\0\0),
and the low 4 bytes indicate the language.
For the C++ ABI described in this document,
the low four bytes are C++\0.

<p>
The <code>exception_cleanup</code> routine is called whenever an
exception object needs to be destroyed by a different runtime than
the runtime which created the exception object,
for instance if a Java exception is caught by a C++ <i>catch</i>
handler.
In such a case, a reason code (see above) indicates why the
exception object needs to be deleted:
<ul>
<p>
<li> <code>_URC_FOREIGN_EXCEPTION_CAUGHT</code> = 1:
    This indicates that a different runtime caught this exception.
    Nested foreign exceptions,
    or rethrowing a foreign exception,
    result in undefined behaviour.
<p>
<li> <code>_URC_FATAL_PHASE1_ERROR</code> = 3:
    The personality routine encountered an error during phase 1,
    other than the specific error codes defined.
<p>
<li> <code>_URC_FATAL_PHASE2_ERROR</code> = 2:
    The personality routine encountered an error during phase 2,
    for instance a stack corruption.
    <p>
    <img src=warning.gif alt="<b>NOTE</b>:">
    Normally, all errors should be reported during phase 1 by returning
    from <code>_Unwind_RaiseException</code>.
    However, landing pad code could cause stack corruption
    between phase 1 and phase 2.
    For a C++ exception, the runtime should call <code>terminate()</code>
    in that case.
</ul>

<p>
The private unwinder state
(<code>private_1</code> and <code>private_2</code>)
in an exception object should be neither read by nor written to
by personality routines or other parts of the language-specific runtime.
It is used by the specific implementation of the unwinder on the host
to store internal information,
for instance to remember the final handler frame between unwinding
phases.

<p>
In addition to the above information,
a typical runtime such as the C++ runtime will add language-specific
information used to process the exception.
This is expected to be a contiguous area of memory after the
<code>_Unwind_Exception</code> object,
but this is not required as long as the matching personality routines
know how to deal with it,
and the <code>exception_cleanup</code> routine de-allocates it properly.

<p>
<b> Unwind Context </b>
<p>
The <code>_Unwind_Context</code> type is an opaque type
used to refer to a system-specific data structure
used by the system unwinder.
This context is created and destroyed by the system,
and passed to the personality routine during unwinding.
<p>
<code><pre>
    struct _Unwind_Context
</pre></code>


<p>
<a name=base-throw></a>
<h4> 1.3  Throwing an Exception </h4>

<p>
<h5> _Unwind_RaiseException </h5>

<code><pre>
   _Unwind_Reason_Code _Unwind_RaiseException
	      ( struct _Unwind_Exception *exception_object );
</pre></code>

<p>
Raise an exception,
passing along the given exception object,
which should have its <code>exception_class</code> and
<code>exception_cleanup</code> fields set.
The exception object has been allocated by the language-specific runtime,
and has a language-specific format,
except that it must contain an <code>_Unwind_Exception</code> struct
(see <i>Exception Header</i> above).
<code>_Unwind_RaiseException</code> does not return,
unless an error condition is found
(such as no handler for the exception,
bad stack format, etc.).
In such a case, an <code>_Unwind_Reason_Code</code> value is returned.
Possibilities are:
<ul>
<p>
<li> <code>_URC_END_OF_STACK</code>:
    The unwinder encountered the end of the stack during phase 1,
    without finding a handler.
    The unwind runtime will not have modified the stack.
    The C++ runtime will normally call <code>uncaught_exception()</code>
    in this case.
<p>
<li> <code>_URC_FATAL_PHASE1_ERROR</code>:
    The unwinder encountered an unexpected error during phase 1,
    e.g. stack corruption.
    The unwind runtime will not have modified the stack.
    The C++ runtime will normally call <code>terminate()</code> in this case.
</ul>

<p>
If the unwinder encounters an unexpected error during phase 2,
it should return <code>_URC_FATAL_PHASE2_ERROR</code> to its caller.
<i>
In C++, this will usually be <code>__cxa_throw</code>,
which will call <code>terminate()</code>.

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
The unwind runtime will likely have modified the stack
(e.g. popped frames from it) or register context,
or landing pad code may have corrupted them.
As a result, the the caller of <code>_Unwind_RaiseException</code>
can make no assumptions about the state of its stack or registers.
</i>

<p>
<a name=forced></a>
<h5> _Unwind_ForcedUnwind </h5>

<code><pre>
    typedef _Unwind_Reason_Code (*_Unwind_Stop_Fn)
		(int version,
		 _Unwind_Action actions,
		 uint64 exceptionClass,
		 struct _Unwind_Exception *exceptionObject,
		 struct _Unwind_Context *context,
		 void *stop_parameter );

    _Unwind_Reason_Code _Unwind_ForcedUnwind
	      ( struct _Unwind_Exception *exception_object,
		_Unwind_Stop_Fn stop,
		void *stop_parameter );
</pre></code>

<p>
Raise an exception for forced unwinding,
passing along the given exception object,
which should have its <code>exception_class</code> and
<code>exception_cleanup</code> fields set.
The exception object has been allocated by the language-specific runtime,
and has a language-specific format,
except that it must contain an <code>_Unwind_Exception</code> struct
(see <i>Exception Header</i> above).

<p>
Forced unwinding is a single-phase process
(phase 2 of the normal exception-handling process).
The <code>stop</code> and <code>stop_parameter</code> parameters
control the termination of the unwind process,
instead of the usual personality routine query.
The <code>stop</code> function parameter is called for each unwind frame,
with the parameters described for the usual personality routine below,
plus an additional <code>stop_parameter</code>.

<p>
When the <code>stop</code> function identifies the destination frame,
it transfers control (according to its own, unspecified, conventions)
to the user code as appropriate without returning,
normally after calling <code>_Unwind_DeleteException</code>.
If not, it should return
an <code>_Unwind_Reason_Code</code> value as follows:
<ul>
<p>
<li> <code>_URC_NO_REASON</code>:
    This is not the destination frame.
    The unwind runtime will call
    the frame's personality routine with the
    <code>_UA_FORCE_UNWIND</code> and <code>_UA_CLEANUP_PHASE</code> flags
    set in <code>actions</code>,
    and then unwind to the next frame
    and call the <code>stop</code> function again.
<p>
<li> <code>_URC_END_OF_STACK</code>:
    In order to allow  <code>_Unwind_ForcedUnwind </code> to perform
    special processing when it reaches the end of the stack,
    the unwind runtime will call it after the last frame is rejected,
    with a NULL stack pointer in the context,
    and the <code>stop</code> function must catch this condition
    (i.e. by noticing the NULL stack pointer).
    It may return this reason code if it cannot handle end-of-stack.
<p>
<li> <code>_URC_FATAL_PHASE2_ERROR</code>:
    The <code>stop</code> function may return this code for other fatal
    conditions, e.g. stack corruption.
</ul>
If the <code>stop</code> function returns any reason code other than
<code>_URC_NO_REASON</code>,
the stack state is indeterminate from the point of view of the caller
of <code>_Unwind_ForcedUnwind</code>.
Rather than attempt to return, therefore,
the unwind library
should return <code>_URC_FATAL_PHASE2_ERROR</code> to its caller.

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i> Example:  <code>longjmp_unwind()</code>
<p>
The expected implementation of <code>longjmp_unwind()</code> is as follows.
The <code>setjmp()</code> routine will have saved the state to be
restored in its customary place, including the frame pointer.
The <code>longjmp_unwind()</code> routine will call
<code>_Unwind_ForcedUnwind </code> with a <code>stop</code> function
that compares the frame pointer in the context record with the saved
frame pointer.
If equal, it will restore the <code>setjmp()</code> state as customary,
and otherwise it will return <code>_URC_NO_REASON</code> or
<code>_URC_END_OF_STACK</code>.
</i>

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
<i>If a future requirement for two-phase forced unwinding were identified,
an alternate routine could be defined to request it,
and an <code>actions</code> parameter flag defined to support it.
</i>

<p>
<h5> _Unwind_Resume </h5>

<code><pre>
    void _Unwind_Resume (struct _Unwind_Exception *exception_object);
</pre></code>

<p>
Resume propagation of an existing exception
e.g. after executing cleanup code in a partially unwound stack.
A call to this routine is inserted at the end of a landing pad that
performed cleanup, but did not resume normal execution.
It causes unwinding to proceed further.

<p>
<img src=warning.gif alt="<b>NOTE 1</b>:">
<code>_Unwind_Resume</code> should not be used to implement rethrowing.
To the unwinding runtime,
the catch code that rethrows was a handler,
and the previous unwinding session was terminated before entering it.
Rethrowing is implemented by calling <code>_Unwind_RaiseException</code>
again with the same exception object.

<p>
<img src=warning.gif alt="<b>NOTE 2</b>:">
This is the only routine in the unwind library which is expected
to be called directly by generated code:
it will be called at the end of a landing pad in a "landing-pad" model.


<p>
<a name=base-om></a>
<h4> 1.4  Exception Object Management </h4>

<p>
<h5> _Unwind_DeleteException </h5>

<code><pre>
    void _Unwind_DeleteException
	      (struct _Unwind_Exception *exception_object);
</pre></code>

<p>
Deletes the given exception object.
If a given runtime resumes normal execution
after catching a foreign exception,
it will not know how to delete that exception.
Such an exception will be deleted by calling
<code>_Unwind_DeleteException</code>.
This is a convenience function that calls the function pointed
to by the <code>exception_cleanup</code> field of the exception header.


<p>
<a name=base-context></a>
<h4> 1.5  Context Management </h4>

These functions are used for communicating information about the unwind
context (i.e. the unwind descriptors and the user register state)
between the unwind library and the personality routine and landing pad.
They include routines to read or set the context record images of
registers in the stack frame corresponding to a given unwind context,
and to identify the location of the current unwind descriptors
and unwind frame.

<p>
<h5> _Unwind_GetGR </h5>

<code><pre>
    uint64 _Unwind_GetGR
	    (struct _Unwind_Context *context, int index);
</pre></code>

<p>
This function returns the 64-bit value of the given general register.
The register is identified by its index:
0 to 31 are for the fixed registers, and
32 to 127 are for the stacked registers.

<p>
During the two phases of unwinding,
only GR1 has a guaranteed value,
which is the Global Pointer (GP)
of the frame referenced by the unwind context.
If the register has its NAT bit set,
the behaviour is unspecified.

<p>
<h5> _Unwind_SetGR </h5>

<code><pre>
    void _Unwind_SetGR
	  (struct _Unwind_Context *context,
	   int index,
	   uint64 new_value);
</pre></code>

<p>
This function sets the 64-bit value of the given register,
identified by its index as for <code>_Unwind_GetGR</code>.
The NAT bit of the given register is reset.

<p>
The behaviour is guaranteed only if the function is called
during phase 2 of unwinding,
and applied to an unwind context representing a handler frame,
for which the personality routine will return <code>_URC_INSTALL_CONTEXT</code>.
In that case, only registers GR15, GR16, GR17, GR18 should be used.
These scratch registers are reserved for passing arguments between
the personality routine and the landing pads.

<p>
<h5> _Unwind_GetIP </h5>

<code><pre>
    uint64 _Unwind_GetIP
	    (struct _Unwind_Context *context);
</pre></code>

<p>
This function returns the 64-bit value of the instruction pointer (IP).

<p>
During unwinding, the value is guaranteed to be the address of the
bundle immediately following the call site
in the function identified by the unwind context.
This value may be outside of the procedure fragment for a
function call that is known to not return
(such as <code>_Unwind_Resume</code>).

<p>
<h5> _Unwind_SetIP </h5>

<code><pre>
    void _Unwind_SetIP
	    (struct _Unwind_Context *context,
	     uint64 new_value);
</pre></code>

<p>
This function sets the value of the instruction pointer (IP)
for the routine identified by the unwind context.

<p>
The behaviour is guaranteed only when this function is called for an
unwind context representing a handler frame,
for which the personality routine will return <code>_URC_INSTALL_CONTEXT</code>.
In this case, control will be transferred to the given address,
which should be the address of a landing pad.

<p>
<a name=lsda></a>
<h5> _Unwind_GetLanguageSpecificData </h5>

<code><pre>
    uint64 _Unwind_GetLanguageSpecificData
	    (struct _Unwind_Context *context);
</pre></code>

<p>
This routine returns the address of the language-specific data area for
the current stack frame.

<p>
<img src=warning.gif alt="<b>NOTE</b>:">
This routine is not stricly required:
it could be accessed through <code>_Unwind_GetIP</code> using
the documented format of the <code>UnwindInfoBlock</code>,
but since this work has been done for finding
the personality routine in the first place,
it makes sense to cache the result in the context.
We could also pass it as an argument to the personality routine.

<p>
<h5> _Unwind_GetRegionStart </h5>

<code><pre>
    uint64 _Unwind_GetRegionStart
	    (struct _Unwind_Context *context);
</pre></code>

<p>
This routine returns the address of the beginning of the procedure or
code fragment described by the current unwind descriptor block.

<p>
This information is required to access any data stored relative to the
beginning of the procedure fragment.
For instance, a call site table might be stored relative to the
beginning of the procedure fragment that contains the calls.
During unwinding, the function returns the start of the procedure
fragment containing the call site in the current stack frame.


<p>
<a name=base-personality></a>
<h4> 1.6  Personality Routine </h4>

<p>
<code><pre>
    _Unwind_Reason_Code (*__personality_routine)
	    (int version,
	     _Unwind_Action actions,
	     uint64 exceptionClass,
	     struct _Unwind_Exception *exceptionObject,
	     struct _Unwind_Context *context);
</pre></code>

<p>
The personality routine is the function in the C++ (or other language)
runtime library which serves as an interface between the system unwind
library and language-specific exception handling semantics.
It is specific to the code fragment described by an unwind info block,
and it is always referenced via the pointer in the unwind info block,
and hence it has no psABI-specified name.

<p>
<h5> 1.6.1  Parameters </h5>

<p>
The personality routine parameters are as follows:
<dl>

<p>
<dt><code>version</code>
<dd>Version number of the unwinding runtime,
used to detect a mis-match between the unwinder conventions and the
personality routine, or to provide backward compatibility.
For the conventions described in this document,
<code>version</code> will be 1.

<p>
<dt><code>actions</code>
<dd>Indicates what processing the personality routine is expected to perform,
as a bit mask.
The possible actions are described below.

<p>
<dt><code>exceptionClass</code>
<dd>An 8-byte identifier specifying the type of the thrown exception.
By convention, the high 4 bytes indicate the vendor
(for instance HP\0\0),
and the low 4 bytes indicate the language.
For the C++ ABI described in this document,
the low four bytes are C++\0.
<p>
<img src=warning.gif alt="<b>NOTE</b>:">
This is not a null-terminated string.
Some implementations may use no null bytes.

<p>
<dt><code>exceptionObject</code>
<dd>The pointer to a memory location recording the necessary information
for processing the exception according to the semantics of a given language
(see the <i>Exception Header</i> section above).

<p>
<dt><code>context</code>
<dd>Unwinder state information for use by the personality routine.
This is an opaque handle used by the personality routine in particular
to access the frame's registers
(see the <i>Unwind Context</i> section above).

<p>
<dt>return value
<dd>The return value from the personality routine indicates
how further unwind should happen,
as well as possible error conditions.
See the following section.

</dl>

<p>
<h5> 1.6.2  Personality Routine Actions </h5>

<p>
The <code>actions</code> argument to the personality routine is
a bitwise <code>OR</code> of one or more of the following constants:
<code><pre>
    typedef int _Unwind_Action;
    static const _Unwind_Action _UA_SEARCH_PHASE = 1;
    static const _Unwind_Action _UA_CLEANUP_PHASE = 2;
    static const _Unwind_Action _UA_HANDLER_FRAME = 4;
    static const _Unwind_Action _UA_FORCE_UNWIND = 8;
</pre></code>

<dl>

<p>
<dt><code> _UA_SEARCH_PHASE </code>
<dd> Indicates that the personality routine should
check if the current frame contains a handler,
and if so return <code>_URC_HANDLER_FOUND</code>,
or otherwise return <code>_URC_CONTINUE_UNWIND</code>.
<code>_UA_SEARCH_PHASE</code> cannot be set
at the same time as <code>_UA_CLEANUP_PHASE</code>.

<p>
<dt><code> _UA_CLEANUP_PHASE </code>
<dd> Indicates that the personality routine should
perform cleanup for the current frame.
The personality routine can perform this cleanup itself,
by calling nested procedures,
and return <code>_URC_CONTINUE_UNWIND</code>.
Alternatively, it can setup the registers (including the IP)
for transferring control to a "landing pad",
and return <code>_URC_INSTALL_CONTEXT</code>.

<p>
<dt><code> _UA_HANDLER_FRAME </code>
<dd> During phase 2,
indicates to the personality routine that the current frame is
the one which was flagged as the handler frame during phase 1.
The personality routine is not allowed to change its mind
between phase 1 and phase 2,
i.e. it must handle the exception in this frame in phase 2.

<p>
<dt><code> _UA_FORCE_UNWIND </code>
<dd> During phase 2,
indicates that no language is allowed to "catch" the exception.
This flag is set while unwinding the stack
for <code>longjmp</code> or during thread cancellation.
User-defined code in a catch clause may still be executed,
but the catch clause must resume unwinding with a call to
<code>_Unwind_Resume</code> when finished.

</dl>

<p>
<a name=landing></a>
<h5> 1.6.3  Transferring Control to a Landing Pad </h5>

<p>
If the personality routine determines that it should
transfer control to a landing pad (in phase 2),
it may set up registers (including IP) with suitable values
for entering the landing pad
(e.g. with landing pad parameters),
by calling the context management routines above.
It then returns <code>_URC_INSTALL_CONTEXT</code>.

<p>
Prior to executing code in the landing pad,
the unwind library restores registers not altered by the personality routine,
using the context record,
to their state in that frame before the call that threw the exception,
as follows.
All registers specified as callee-saved by the base ABI are restored,
as well as scratch registers GR15, GR16, GR17 and GR18 (see below).
Except for those exceptions,
scratch (or caller-saved) registers are not preserved,
and their contents are undefined on transfer.
The accessibility of registers in the frame will be restored to that
at the point of call,
i.e. the same logical registers will be accessible,
but their mappings to physical registers may change.
Further,
the state of stacked registers beyond the current frame is unspecified,
i.e. they may be either in physical registers or on the register stack.

<p>
The landing pad can either resume normal execution
(as, for instance, at the end of a C++ catch),
or resume unwinding by calling <code>_Unwind_Resume</code>
and passing it the <code>exceptionObject</code> argument
received by the personality routine.
<code>_Unwind_Resume</code> will never return.

<p>
<code>_Unwind_Resume</code> should be called if and only if
the personality routine did not return <code>_Unwind_HANDLER_FOUND</code>
during phase 1.
As a result, the unwinder can allocate resources (for instance memory)
and keep track of them in the exception object reserved words.
It should then free these resources
before transferring control to the last (handler) landing pad.
It does not need to free the resources before entering non-handler
landing-pads, since <code>_Unwind_Resume</code> will ultimately be called.

<p>
The landing pad may receive arguments from the runtime,
typically passed in registers set using <code>_Unwind_SetGR</code>
by the personality routine.
For a landing pad that can call to <code>_Unwind_Resume</code>,
one argument must be the <code>exceptionObject</code> pointer,
which must be preserved to be passed to <code>_Unwind_Resume</code>.

<p>
The landing pad may receive other arguments,
for instance a <i>switch value</i>
indicating the type of the exception.
Four scratch registers are reserved for this use
(GR15, GR16, GR17 and GR18.)

<p>
<h5> 1.6.4  Rules for Correct Inter-Language Operation </h5>

<p>
The following rules must be observed for correct operation
between languages and/or runtimes from different vendors:

<p>
An exception which has an unknown class must not be altered by the
personality routine.
The semantics of foreign exception processing depend on the
language of the stack frame being unwound.
This covers in particular how exceptions from a foreign language are
mapped to the native language in that frame.

<p>
If a runtime resumes normal execution,
and the caught exception was created by another runtime,
it should call <code>_Unwind_DeleteException</code>.
This is true even if it understands the exception object format
(such as would be the case between different C++ runtimes).

<p>
A runtime is not allowed to catch an
exception if the <code>_UA_FORCE_UNWIND</code> flag was passed to 
the personality routine.

<p>
<img src=warning.gif>
<i>
Example: Foreign Exceptions in C++.
In C++, foreign exceptions can be caught by a catch(...) statement.
They can also be caught as if they were of a
<code>__foreign_exception</code> class, defined in &lt;exception>.
The <code>__foreign_exception</code> may have subclasses,
such as <code>__java_exception</code> and <code>__ada_exception</code>,
if the runtime is capable of identifying some of the foreign languages.
</i>

<p>
The behavior is undefined in the following cases:

<ul>
<p>
<li>
A <code>__foreign_exception</code> catch argument is accessed in any way
(including taking its address).

<p>
<li>
A <code>__foreign_exception</code> is active at the same time as
another exception
(either there is a nested exception while catching the foreign exception,
or the foreign exception was itself nested).

<p>
<li>
<code>uncaught_exception</code>(), <code>set_terminate</code>(),
<code>set_unexpected</code>(), <code>terminate</code>(), or
<code>unexpected</code>() is called at a time a foreign exception exists
(for example, calling <code>set_terminate</code>()
during unwinding of a foreign exception).
</ul>

<p>
All these cases might involve accessing C++ specific content of the
thrown exception,
for instance to chain active exceptions.

<p>
Otherwise, a catch block catching a foreign exception is allowed:

<ul>

<p>
<li>
to resume normal execution,
thereby stopping propagation of the foreign
exception and deleting it, or

<p>
<li>
to rethrow the foreign exception.
In that case,
the original exception object must be unaltered by the C++ runtime.
</ul>

<p>
A catch-all block may be executed during forced unwinding.
For instance, a <code>longjmp</code> may execute code in a
<code>catch(...)</code> during stack unwinding.
However, if this happens,
unwinding will proceed at the end of the catch-all block,
whether or not there is an explicit rethrow.

<p>
Setting the low 4 bytes of exception class to C++\0 is reserved for use
by C++ runtimes compatible with the common C++ ABI.


<p> <hr> <p>
<a name=cxx-abi></a>
<h3> Level II: C++ ABI </h3>


<p>
<a name=cxx-intro></a>
<h4> 2.1  Introduction </h4>

<p>
The second level of specification is the minimum required to allow
interoperability in the sense described above.
This level requires agreement on:

<ul>
<p>
<li>
Standard runtime initialization,
e.g. pre-allocation of space for out-of-memory exceptions.

<p>
<li>
The layout of the exception object created by a throw and processed by
a catch clause.

<p>
<li>
When and how the exception object is allocated and destroyed.

<p>
<li>
The API of the personality routine,
i.e. the parameters passed to it,
the logical actions it performs,
and any results it returns
(either function results to indicate success, failure, or continue,
or changes in global or exception object state),
for both the phase 1 handler search and the phase 2 cleanup/unwind.

<p>
<li>
How control is ultimately transferred back to the user program at a
catch clause or other resumption point.
That is, will the last personality routine transfer control directly to
the user code resumption point,
or will it return information to the runtime allowing the latter to do so?

<p>
<li>
Multithreading behavior.

</ul>


<p>
<a name=cxx-data></a>
<h4> 2.2  Data Structures </h4>

<p>
<a name=cxx-exc-object></a>
<h5> 2.2.1  C++ Exception Objects </h5>

<p>
A complete
C++ exception object consists of a header,
which is a wrapper around an unwind object header with additional C++
specific information,
followed by the thrown C++
exception object itself.
The structure of the header is as follows:
<code><pre>
      struct __cxa_exception { 
	std::type_info *	exceptionType;
	void (*exceptionDestructor) (void *); </font>
	unexpected_handler	unexpectedHandler;
	terminate_handler	terminateHandler;
	__cxa_exception *	nextException;

	int			handlerCount;
	int			handlerSwitchValue;
	const char *		actionRecord;
	const char *		languageSpecificData;
	void *			catchTemp;
	void *			adjustedPtr;

	_Unwind_Exception	unwindHeader;
      };
</pre></code>

<p>
The fields in the exception object are as follows:

<ul>
<p>
<li>
The <code>exceptionType</code> field encodes the type of
the thrown exception.
The <code>exceptionDestructor</code> field
contains a function pointer to a destructor
for the type being thrown,
and may be NULL.
These pointers must be stored in the exception object
since non-polymorphic and built-in types can be thrown.

<p>
<li>
The fields <code>unexpectedHandler</code> and <code>terminateHandler</code>
contain pointers to the <code>unexpected</code> and <code>terminate</code>
handlers at the point where the exception is thrown.
<i>
The <b>ISO C++ Final Draft International Standard</b> [lib.unexpected]
(18.6.2.4) states that the handlers to be used are those active
immediately after evaluating the throw argument.
If destructors change the active handlers during unwinding,
the new values are not used until unwinding is complete.
</i>

<p>
<li>
The <code>nextException</code> field is used to create a linked list
of exceptions (per thread).

<p>
<li>
The <code>handlerCount</code> field contains a count of how many
handlers have caught this exception object.
It is also used to determine exception life-time
(see Section ??? [was 11.12]).

<p>
<li>
The <code>handlerSwitchValue</code>, <code>actionRecord</code>,
<code>languageSpecificData</code>, <code>catchTemp</code>,
and <code>adjustedPtr</code> fields cache information that is best
computed during pass 1, but useful during pass 2.
By storing this information in the exception object,
the cleanup phase can avoid re-examining action records.
These fields are reserved for use of the personality routine for the
stack frame containing the handler to be invoked.

<p>
<li>
The <code>unwindHeader</code> structure is used to allow correct
operation of exception in the presence of multiple languages or
multiple runtimes for the same language.
The <code>_Unwind_Exception</code> type is described in
<a href=#base-data>Section 1.2</a>.

</ul>

<p>
By convention, a <code>__cxa_exception</code> pointer points at the
C++ object representing the exception being thrown,
immediately following the header.
The header structure is accessed at a negative offset from the
<code>__cxa_exception</code> pointer.
<i>
This layout allows consistent treatment of exception objects from
different languages (or different implementations of the same language),
and allows future extensions of the header structure while
maintaining binary compatibility.
</i>

<p>
<i>
Version information is not required,
since the general unwind library framework specifies
an exception class identifier,
which will change should the layout of the exception object
change significantly.
</i>

<p>
<a name=cxx-exc-stack></a>
<h5> 2.2.2  Caught Exception Stack </h5>

<p>
Each thread in a C++ program has access to an object of the following
class:
<code><pre>
      struct __cxa_eh_globals {
	__cxa_exception *	caughtExceptions;
	unsigned int		uncaughtExceptions;
      };
</pre></code>

<p>
The fields of this structure are defined as follows:

<ul>
<p>
<li> 
The <code>caughtExceptions</code> field is a list of the active exceptions,
organized as a stack with the most recent first,
linked through the <code>nextException</code> field of the exception header.

<p>
<li> 
The <code>uncaughtExceptions</code> field is a count of uncaught exceptions,
for use by the C++ library <code>uncaught_exceptions()</code> routine.

</ul>

<p>
This information is maintained on a per-thread basis.
Thus, <code>caughtExceptions</code> is a list of exceptions thrown and
caught by the current thread,
and <code>uncaughtExceptions</code> is a count of exceptions thrown and
not yet caught by the current thread.
(This includes rethrown exceptions,
which may still have active handlers,
but are not considered caught.)

<p>
The <code>__cxa_eh_globals</code> for the current thread can be obtained
by using either of the APIs:

<ul>
<p>
<li> <code>__cxa_eh_globals *__cxa_get_globals(void)</code> :
<br>
Return a pointer to the <code>__cxa_eh_globals</code> structure for the
current thread, initializing it if necessary.

<p>
<li> <code>__cxa_eh_globals *__cxa_get_globals_fast(void)</code> :
<br>
Return a pointer to the <code>__cxa_eh_globals</code> structure for the
current thread, assuming that at least one prior call to
<code>__cxa_get_globals</code> has been made from the current thread.

</ul>


<p>
<a name=cxx-init></a>
<h4> 2.3  Standard Runtime Initialization </h4>


<p>
<a name=cxx-throw></a>
<h4> 2.4  Throwing an Exception </h4>

<p>
This section specifies the process by which the C++ generated code and
runtime library throw an exception,
transferring control to the unwind library for handling.

<p>
<h5> 2.4.1  Overview of Throw Processing </h5>

<i>
<p>
In broad outline,
a possible implementation of
the processing necessary to throw an exception includes the following
steps:

<ul>
<p>
<li>
Call <code>__cxa_allocate_exception</code> to create an exception object
(see Section 2.4.2).

<p>
<li>
Evaluate the thrown expression,
and copy it into the buffer returned by
<code>__cxa_allocate_exception</code>,
possibly using a copy constructor.
If evaluation of the thrown expression exits by throwing an exception,
that exception will propagate instead of the expression itself.
Cleanup code must ensure that <code>__cxa_free_exception</code>
is called on the just allocated exception object.
(If the copy constructor itself exits by throwing an exception,
<code>terminate()</code> is called.)

<p>
<li>
Call <code>__cxa_throw</code> to pass the exception
to the runtime library (see Section 2.4.3).
<code>__cxa_throw</code> never returns.
</ul>

<p>
Based on this outline, throwing an object X as in:
<code><pre>
	throw X;
</pre></code>
will produce code approximating the template:
</i>
<code><pre>
	// Allocate -- never throws:
	temp1 = __cxa_allocate_exception(sizeof(X));

	// Construct the exception object:
	#if COPY_ELISION
	  [evaluate X into temp1]
	#else
	  [evaluate X into temp2]
	  <i>copy-constructor</i>(temp1, temp2)
	  // Landing Pad L1 if this throws
	#endif

	// Pass the exception object to unwind library:
	__cxa_throw(temp1, type_info&lt;X>, destructor&lt;X>); // Never returns

	// Landing pad for copy constructor:
	L1: __cxa_free_exception(temp1) // never throws
</pre></code>

<p>
<i>
The following sections will describe
the ABI facilities available to implement
these steps,
or possible variants,
in more detail.
One possible variant is to evaluate the thrown expression
before allocating the exception object and always copy the value.
</i>

<p>
<a name=cxx-allocate></a>
<h5> 2.4.2  Allocating the Exception Object </h5>

<p>
Storage is needed for exceptions being thrown.
This storage must persist while stack is being unwound,
since it will be used by the handler,
and must be thread-safe.
Exception object storage will therefore normally be allocated in the heap,
although implementations may provide an emergency buffer to support
throwing <code>bad_alloc</code> exceptions under low memory conditions
(see <a href=#imp-emergency>Section 3.3.1</a>).

<p>
Memory will be allocated by the <code>__cxa_allocate_exception</code>
runtime library routine.
This routine is passed the size of the exception object to be thrown
(not including the size of the <code>__cxa_exception</code> header),
and returns a pointer to the temporary space for the exception object.
It will allocate the exception memory on the heap if possible.
If heap allocation fails,
an implementation may use other backup mechanisms
(see <a href=#imp-allocate>Section 3.4.1</a>).

<p>
If <code>__cxa_allocate_exception</code> cannot allocate an exception
object under these constraints, it calls <code>terminate()</code>.
<code><pre>
	void *__cxa_allocate_exception(size_t thrown_size);
</pre></code>

<p>
Once space is allocated,
a throw expression must initialize the exception object with the thrown
value as specified by the C++ Standard.

<p>
The temporary space will be freed by <code>__cxa_free_exception</code>
(see <a href=#cxx-destroy>Section 2.5.5</a>),
which is passed the address returned by the previous
<code>__cxa_allocate_exception</code>.
<code><pre>
	void __cxa_free_exception(void *thrown_exception);
</pre></code>

<p>
These routines are thread-safe (in a multi-threading environment),
and may block threads after the maximum number of threads
allowed to use the emergency buffer has been reached.


<p>
<a name=cxx-throw-rt></a>
<h5> 2.4.3  Throwing the Exception Object </h5>

<p>
After constructing the exception object with the throw argument value,
the generated code calls the <code>__cxa_throw</code> runtime library
routine.
This routine never returns.
<code><pre> 
    void __cxa_throw (void *thrown_exception, std::type_info *tinfo, void (*dest) (void *) );
</pre></code>
The arguments are:
<ul>
<p>
<li> The address of the thrown exception object
     (which points to the throw value, after the header,
     as specified above).
<p>
<li> A <code>std::type_info</code> pointer,
     giving the static type of the throw argument
     as a <code>std::type_info</code> pointer,
     used for matching potential catch sites to the thrown exception.
<p>
<li> A destructor pointer to be used eventually to destroy the object.
</ul>

<p>
The <code>__cxa_throw</code> routine will do the following:

<ul>
<p>
<li>
Obtain the <code>__cxa_exception</code> header from the
thrown exception object address,
which can be computed as follows:
<code><pre>
    __cxa_exception *header = ((__cxa_exception *) thrown_exception - 1);
</pre></code>

<p>
<li>
Save the current <code>unexpected_handler</code> and
<code>terminate_handler</code> in the <code>__cxa_exception</code> header.

<p>
<li>
Save the <code>tinfo</code> and <code>dest</code> arguments
in the <code>__cxa_exception</code> header.

<p>
<li>
Set the <code>exception_class</code> field in the unwind header.
This is a 64-bit value representing the ASCII string
"XXXXC++\0", where "XXXX" is a vendor-dependent string.
That is, for implementations conforming to this ABI,
the low-order 4 bytes of this 64-bit value will be "C++\0".

<p>
<li>
Increment the <code>uncaught_exception</code> flag.

<p>
<li>
Call <code>_Unwind_RaiseException</code> in the system unwind library,
Its argument is the pointer to the thrown exception,
which <code>__cxa_throw</code> itself received as an argument.

</ul>

<p>
<code>__Unwind_RaiseException</code> begins the process of stack unwinding,
described in <a href=#cxx-catch>Section 2.5</a>.
In special cases, such as an inability to find a handler,
<code>_Unwind_RaiseException</code> may return.
In that case, <code>__cxa_throw</code> will call terminate,
assuming that there was no handler for the exception.

</ul>


<p>
<a name=cxx-catch></a>
<h4> 2.5  Catching an Exception </h4>

<p>
<h5> 2.5.1  Overview of Catch Processing </h5>

<i>
See <a href=#imp-catch>Section 3.5</a> below for an overview of a
possible implementation of catch processing.
This section specifies the interfaces which must be supported by
ABI-compliant exception handling runtime libraries.
</i>

<p>
<a name=cxx-personality></a>
<h5> 2.5.2  The Personality Routine </h5>

<p>
The personality routine is the function in the C++ runtime library
which serves as an interface between the system unwind library
and the C++ specific semantics.
Its interface is defined by
<a href=#base-personality>Section 1.6</a>:
<code><pre>
    _Unwind_Reason_Code (*__personality_routine)
	    (int version,
	     _Unwind_Action actions,
	     uint64 exceptionClass,
	     struct _Unwind_Exception *exceptionObject,
	     struct _Unwind_Context *context);
</pre></code>

<p>
The interface between the unwind library and the personality routine is
specified as part of the Level I interface in
<a html=#base-personality>Section 1.6</a>.
Furthermore, the personality routine is tailored by the implementation
to the handlers for the frame in which it works,
and to the exception tables for that frame.
Therefore, only general behavior is specified here.

<p>
Although other approaches are possible,
this ABI requires a two-phase unwind process.
During the first phase,
i.e. with <code>actions</code> including the bit
<code>_UA_SEARCH_PHASE</code>,
the personality routine should do nothing to update state,
simply searching for a handler and returning
<code>_URC_HANDLER_FOUND</code> when it finds one.
During the second phase,
i.e. with <code>actions</code> including the bit
<code>_UA_CLEANUP_PHASE</code>,
the personality routine may perform cleanup actions at intermediate frames,
and must transfer to the handler found when <code>actions</code>
includes the bit <code>_UA_HANDLER_FRAME</code>,
which it does by setting up the context and returning
<code>_URC_INSTALL_CONTEXT</code>.

<p>
If the exception is not a C++ exception,
the C++ personality routine must not catch it,
that is it should return _URC_CONTINUE_UNWIND in both phases,
after performing any required cleanup actions in the second phase.
See the specification in Section 1.6.4.

<p>
The Level I specification requires that the personality routine
transfer control to a landing pad via the unwind library,
enabling the latter to do any final cleanup.
It does so by modifying the context record for the current frame,
and letting the unwind library transfer control:

<ul>
<p>
<li> Using <code>_Unwind_SetIP</code> to set the PC of the current
     stack frame to the address of the landing pad.

<p>
<li> Using <code>_Unwind_SetGR</code> to set parameters to the
     landing pad in the general registers of the current stack frame.
     Although this is again an unspecified implementation detail,
     it is suggested that the exception object address be passed in
     GR15, the switch value in GR16, and any other parameters in
     GR17 and GR18.

<p>
<li> Once the frame is set,
     returning <code>_URC_INSTALL_CONTEXT</code> to the unwind library,
     which does any cleanup required,
     installs the context, and transfers control to the landing pad.

</ul>

<p>
Note that any cleanup activity may be implemented as a landing pad
that performs only cleanup tasks (no handlers),
and calls <code>_Unwind_Resume</code> when done.
In such cases,
the personality routine should treat the cleanup landing pad as a handler.

<p>
The personality routine works only within the current frame;
that is, it returns control to the unwind library for any processing
required beyond this frame.


<p>
<a name=cxx-handler></a>
<h5> 2.5.3  Exception Handlers </h5>

<p>
For purposes of this ABI,
several things are considered <i>exception handlers</i>:

<ul>
<li> A normal C++ handler, i.e. a catch clause.
<li> An <code>unexpected()</code> call,
     due to a violated exception specification.
<li> A <code>terminate()</code> call due to a throw.
</ul>

Most of the behavior of a handler is implementation-defined.
However, in order to allow maintenance of the exception stack,
all handlers must make the following calls.

<p>
Upon entry, a handler must call:
<code><pre>
void *__cxa_get_exception_ptr ( void *exceptionObject );
</pre></code>
This routine returns the adjusted pointer to the exception object.
(The adjusted pointer is typically computed by the personality routine
during phase 1 and saved in the exception object.)
</div>

<p>
<strike>Upon entry,</strike>
<span class="change">Following initialization of the catch parameter,</span>
a handler must call:
<code><pre>
void <span class="change">*</span>__cxa_begin_catch ( void *exceptionObject );
</pre></code>
This routine:
<ul>
<li> Increment's the exception's handler count.
<li> Places the exception on the stack of currently-caught exceptions
    if it is not already there,
    linking the exception to the previous top of the stack.
<li> Decrements the uncaught_exception count.
<li><span class="change">Returns the adjusted pointer to the exception object.</span>
</ul>

<p>
If the initialization of the catch parameter is trivial
(e,g., there is no formal catch parameter, or the parameter has no copy constructor),
the calls to <code>__cxa_get_exception_ptr()</code> and
<code>__cxa_begin_catch()</code> may be combined into a single call to
<code>__cxa_begin_catch()</code>.
</p>

<p>
When the personality routine encounters a termination condition,
it will call <code>__cxa_begin_catch()</code> to mark the exception
as handled and then call <code>terminate()</code>,
which shall not return to its caller.

<p>
Upon exit for any reason, a handler must call:
<code><pre>
	void __cxa_end_catch ();
</pre></code>
This routine:
<ul>
<li> Locates the most recently caught exception
     and decrements its handler count.
<li> Removes the exception from the caughtÓexception stack,
     if the handler count goes to zero.
<li> Destroys the exception if the handler count goes to zero,
     and the exception was not re-thrown by <code>throw</code>.
</ul>

<p>
<img src=warning.gif>
<i>
Collaboration between <code>__cxa_rethrow()</code> and
<code>__cxa_end_catch()</code> is necessary to handle the last point.
Though implementation-defined,
one possibility
is for <code>__cxa_rethrow()</code> to set a flag in the 
<code>handlerCount</code> member of the exception header
to mark an exception being rethrown.
</i>

<p>
<a name=cxx-cleanup></a>
If a landing pad is going to resume unwinding, e.g. because
<ul>
<li> it contains no handlers, just cleanup actions;
<li> none of its catch handlers matches the exception; or
<li> the catch handler re-throws the exception,
</ul>
then it shall do any required cleanup for the current frame before
calling <code>_Unwind_Resume</code> to resume unwinding.


<p>A handler for an arbitrary exception, including a
<code>terminate_handler</code> or <code>unwind_handler</code>, has no way
in standard C++ of determining the type of the exception without resorting
to a complete enumeration, which is impractical at best.  Since we use
<code>type_info</code> for EH type matching, a user can access this
information by calling:
<code><pre>
	std::type_info *__cxa_current_exception_type ();
</pre></code>
which returns the type of the first caught exception, or null if there are
no caught exceptions.  This routine is optional; a conforming ABI 
implementation need not provide it.  However, if it is provided, it shall
have the behavior specified here.

<p>
<a name=cxx-rethrow></a>
<h5> 2.5.4  Rethrowing Exceptions </h5>

<p>
Rethrowing an exception is possible any time an exception is being handled.
Most commonly, that means within a catch clause,
but it is also possible to rethrow within an
<code>unexpected()</code> or <code>terminate()</code> handler.

<p>
A catch handler rethrows the
exception on top of the caughtExceptions stack
by calling:
<code><pre>
	void __cxa_rethrow ();
</pre></code>
This routine marks the
exception object on top of the caughtExceptions stack
(in an implementation-defined way)
as being rethrown.
If the caughtExceptions stack is empty,
it calls <code>terminate()</code> (see [C++FDIS] [except.throw], 15.1.8).
It then returns to the handler that called it,
which must call <code>__cxa_end_catch()</code>,
perform any necessary cleanup,
and finally call <code>_Unwind_Resume()</code> to continue unwinding.


<p>
<a name=cxx-destroy></a>
<h5> 2.5.5  Finishing and Destroying the Exception </h5>

<p>
An exception is considered <i>handled</i>:
<ul>
<li> Immediately after initializing the parameter of the corresponding
     catch clause (or upon entry to a <code>catch(...)</code> clause).
<li> Upon entering <code>unexpected()</code> or <code>terminate()</code>
     due to a throw.
</ul>

<p>
An exception is considered <i>finished</i>:
<ul>
<li> When the corresponding catch clause exits
     (normally, by another throw, or by rethrow).
<li> When <code>unexpected()</code> exits (by throwing),
     after being entered due to a throw.
</ul>

<p>
Because an exception can be rethrown and caught within a handler,
there can be more than one handler active for an exception.
The exception is destroyed when the last (outermost) handler exits
by any means other than rethrow.
The destruction occurs immediately after destruction of the catch
clause parameter, if any.

<p>
This lifetime management is performed by the <code>__cxa_begin_catch</code>
and <code>__cxa_end_catch</code> runtime functions,
which keep track of what handlers exist for which exceptions.
When <code>__cxa_end_catch</code> detects that an exception is
no longer being thrown or handled,
it destroys the exception and frees the memory allocated for it.

<p>
<img src=warning.gif>
<i>
Managing an exception lifetime occurs at runtime,
because it is impossible to determine statically when it ends.
For example:
<code><pre>
try { throw X(); }
catch (X x)
{
  try { throw; }
  catch(...) {
    if (case1)
      throw;
    else if (case2)
      throw Y();
  }
  if (case3) throw;
}
</pre></code>

<p>
In this example,
the lifetime of the thrown exception created in the outermost
try block depends on the conditions:
<ul>
<li> In case case1,
     the initial exception is thrown again,
     using the same temporary.
     It survives the outer catch.
<li> In case case2,
     another exception is being thrown,
     causing the initial exception to be destroyed
     as the exception propagates from the outer catch.
<li> In case case3,
     the exception lives outside both the innermost and outermost catch block.
     (The effect is the same as case1.)
<li> Otherwise,
     the exception is finished at the end of the outermost catch block.
</ul>
</i>

<p>
The complete exception object will be destroyed by calling its
destructor and <code>__cxa_free_exception</code>,
as described in <a href=#cxx-allocate>Section 2.4.2</a>.
This is not normally called directly by the generated code,
but rather by the <code>__cxa_end_catch</code> routine,
which also removes the exception from the caught-exceptions stack.


<p>
<a name=cxx-aux></a>
<h4> 2.6  Auxiliary Runtime APIs </h4>

<p>
The C++ ABI includes the APIs of a number of runtime routines to
facilitate code generation for recurring situations that need not
always produce inline code.

<dl>

<dt><code><pre>
extern "C" void __cxa_bad_cast ();
</pre></code></dt>
<dd>
Raise a bad_cast exception (lib.bad.cast, 18.5.2).
Does not return (normally),
and implementations may note this fact, e.g. with pragmas.
</dd>

<dt><code><pre>
extern "C" void __cxa_bad_typeid ();
</pre></code></dt>
<dd>
Raise a bad_typeid exception (lib.bad.typeid, 18.5.3).
Does not return (normally),
and implementations may note this fact, e.g. with pragmas.
</dd>

</dl>


<p> <hr> <p>
<a name=cxx-rt></a>
<h3> Level III. Suggested Implementation </h3>


<p>
<a name=imp-intro></a>
<h4> 3.1  Introduction </h4>

<p>
The third level is a specification sufficient to allow all compliant
C++ systems to share the relevant runtime implementation.
It includes, in addition to the Level II specification:

<ul>
<p>
<li>
Format of the C++ language-specific unwind tables.

<p>
<li>
APIs of the functions named __allocate_exception, __throw, and
__free_exception (and likely others) by HP, or their equivalents.

<p>
<li>
API of landing pad code,
and of any other entries back into the user code.

<p>
<li>
Definition of what HP calls the exception class value.

</ul>

<p>
The vocal attendees at the meeting wish to achieve the third level,
and we will attempt to do so.
What follows is a subset of the required information;
See the HP exception handling specification for elaboration at this time.


<p>
<a name=imp-data></a>
<h4> 3.2  Data Structures </h4>

<p>
&lt;To Be Supplied>


<p>
<a name=imp-init></a>
<h4> 3.3  Standard Runtime Initialization </h4>

<p>
<a name=imp-emergency></a>
<h5> 3.3.1  Exception Storage </h5>

<i>
<p>
The C++ runtime library shall allocate a static emergency buffer of at
least 4K bytes per potential task, up to 64KB.
This buffer shall be used only in cases where dynamic allocation of
exception objects fails.
It shall be allocated in 1KB chunks.
At most 16 tasks may use the emergency buffer at any time,
for at most 4 nested exceptions,
with each exception object (including header) of size at most 1KB.
Additional threads are blocked until one of the 16 de-allocates its
emergency buffer storage.

<p>
The interface to the emergency buffer is implementation-defined,
and used only by the exception library.
</i>


<p>
<a name=imp-throw></a>
<h4> 3.4  Throwing an Exception </h4>

<p>
This section specifies further implementation details of the process
by which the C++ generated code and runtime library throw an exception,
transferring control to the unwind library for handling.

<p>
<a name=imp-allocate></a>
<h5> 3.4.1  Allocating the Exception Object </h5>

<p>
Memory for an exception object will be allocated by the
<code>__cxa_allocate_exception</code> runtime library routine,
with general requirements as described in
<a href=cxx-allocate>Section 2.4.2</a>.
If normal allocation fails,
then it will attempt to allocate one of the emergency buffers,
described in <a href=imp-emergency>Section 3.3.1</a>,
under the following constraints:
<ul>
<li> The exception object size, including headers, is under 1KB.
<li> The current thread does not already hold four buffers.
<li> There are fewer than 16 other threads holding buffers,
     or this thread will wait until one of the others releases
     its buffers before acquiring one.
</ul>


<p>
<a name=imp-catch></a>
<h4> 3.5  Catching an Exception </h4>

<p>
<h5> 3.5.1  Overview of Catch Processing </h5>

<i>

<p>
<h6> 3.5.1.1  Unwinding the Stack </h6>
<p>
As specified by this ABI,
stack unwinding itself is begun by calling
<code>__Unwind_RaiseException()</code>,
and performed by the unwind library
(see <a href=#base-framework>Section 1.1</a>).
We summarize it again here.

<p>
The stack unwind library runs two passes on the stack, as follows:

<ul>
<p>
<li>
Recover the program counter (PC) in the current stack frame.

<p>
<li>
Using an unwind table,
find information on how to handle exceptions that occur at that PC,
and in particular,
get the address of the personality routine for that address range.
The unwind table is described in [SWCONV].

<p>
<li>
Call the personality routine
(see <a href=#cxx-personality>Section 2.5.2</a>).
that will determine if an appropriate
handler is found at that level of the stack (in pass 1),
and that will determine which particular handler to invoke from
the landing pad (in pass 2),
as well as the arguments to pass to the landing pad
(see <a href=#imp-personality>Section 3.5.2</a>).
The personality routine passes this information back to the unwind
library.

<p>
<li>
In the second phase,
the unwind library jumps to the landing pad corresponding to the call
(see <a href=#imp-personality>Section 3.5.2</a>)
for each level of the stack being unwound.
Landing pad parameters are set as indicated by the personality routine.
The landing pad executes compensation code
(generated by the back end)
to restore the appropriate register and stack state.

<p>
<li>
Some cleanup code generated by the front-end may then execute,
corresponding to the exit of the <b>try</b> block.
For instance, an automatic variable local to the try block
would be destroyed here.

<p>
<li>
The exception handler may select and execute user-defined code
corresponding to C++ catch clauses and other handlers.
The generated code may be similar to a switch statement,
where the switch value is determined by the runtime based on
the exception type
(see <a href=#cxx-handler>Section 2.5.3</a> and
<a href=#imp-handler>Section 3.5.3</a>),
and passed in a landing pad argument.

<p>
<li>
As soon as the runtime determines that the execution will go to a handler,
the unwinding process is considered complete for the unwind library.
A handler may still rethrow the current exception
(see <a href=#cxx-rethrow>Section 2.5.4</a>)
or a different exception,
but a new unwind process will occur in both cases.
Otherwise, after the code in a handler has executed,
execution resumes at the end of the try block which defines this handler.

<p>
<li>
If none of the possible handlers matches the exception being thrown,
the runtime selects a switch value that does not match any switch statement.
In that case, control passes through all switch statements,
and goes to additional <a href=#cxx-cleanup>cleanup code</a>,
which will call all destructors that need
to be called for the current stack frame.
For instance,
an automatic variable local to the outer block of the function
would be destroyed here.
<i>
This means that the handler must loop through any try blocks
enclosing the original one in the process of cleaning up the frame,
trying the switch value in each one.
</i>

<p>
<li>
At the end of this current cleanup code,
control is transferred back to the unwind library,
to unwind one more stack frame
(see <a href=#cxx-cleanup>Section 2.5.3</a>).

</ul>

<p>
<h6> 3.5.1.2  Generated Catch Code </h6>

<p>
For purposes of illustration,
suppose we have a call site in a try-catch block such as:
</i>
<code><pre>
	try { foo(); }
	catch (TYPE1) { ... }
	catch (TYPE2) { buz(); }
	bar();
</pre></code>

<p>
<i>
This might be translated as follows:
</i>
<code><pre>
	// In "Normal" area:
	foo(); // Call Attributes: Landing Pad L1, Action Record A1
	goto E1;
	...
	E1: // End Label
	bar();

	// In "Exception" area;
	L1: // Landing Pad label
	[Back-end generated ÒcompensationÓ code]
	goto C1;

	C1: // Cleanup label
	[Front-end generated cleanup code, destructors, etc]
	[corresponding to exit of try { } block]
	goto S1;

	S1: // Switch label
	switch(SWITCH_VALUE_PAD_ARGUMENT)
	{
	    case 1: goto H1; // For TYPE1
	    case 2: goto H2; // For TYPE2
	    //...
	    default: goto X1;
	}

	X1:
	[Cleanup code corresponding to exit of scope]
	[enclosing the try block]
	_Unwind_Resume();

	H1: // Handler label
	adjusted_exception_ptr = __cxa_get_exception_ptr(exception);
	[Initialize catch parameter]
	__cxa_begin_catch(exception);
	[User code]
	goto R1;

	H2:
	adjusted_exception_ptr = __cxa_get_exception_ptr(exception);
	[Initialize catch parameter]
	__cxa_begin_catch(exception);
	[User code]
	buz(); // Call attributes: Landing pad L2, action record A2
	goto R1;

	R1: // Resume label:
	__cxa_end_catch();
	goto E1;

	L2:
	C2:
	// Make sure we cleanup the current exception
	__cxa_end_catch();

	X2:
	[Cleanup code corresponding to exit of scope]
	[enclosing the try block]
	_Unwind_Resume();
</pre></code>

<p>
<i>
The various components of this example segment are discussed 
in <a href=#cxx-catch>Section 2.5</a> above (ABI requirements),
and below.
</i>

<p>
<a name=imp-personality></a>
<h5> 3.5.2  The Personality Routine </h5>

<p>

<p>
<a name=imp-handler></a>
<h5> 3.5.3  Exception Handlers </h5>

<p>

</font>


<p><a name=revisions></a> <hr> <p>
<h3> Appendix R:  Revisions </h3>

<p>
<font color="blue">[050504]</font>
Add __cxa_get_exception_ptr, add return value to __cxa_begin_catch.

<p>
<font color="blue">[011126]</font>
Add __cxa_current_exception_type.

<p>
<font color="blue">[010731]</font>
Clarify linkage of constants.

<p>
<font color="blue">[010315]</font>
Clarify exception object structure (2.2.1).
Rename IA-64 to Itanium throughout.

<p>
<font color=blue>[001110]</font>
Eliminate __cxa_throw_type_info in favor of storing its components
separately in the exception header and passing them separately in
__cxa_throw.

<p>
<font color=blue>[001010]</font>
Correct phase2 error behavior of _Unwind_RaiseException and
_Unwind_ForcedUnwind (1.3).
Define __cxa_throw_type_info correctly (2.2.1).
Todo: fix cross-references in moved material in Level III.

<p>
<font color=blue>[000911]</font>
Add Jason's corrections.
Remove section 2.4.3.

<p>
<font color=blue>[000810]</font>
Add C++ exception data (2.2),
begin initialization (2.3) and throwing exceptions (2.4).

<p>
<font color=blue>[000707]</font>
Add auxiliary runtime APIs (2.6).

<p>
<font color=blue>[000502]</font>
Begin integration of Level 2/3 specifications.

<p>
<font color=blue>[000131]</font>
Integrate comments from 27 January meeting.
Put literal names in reserved name space.

<p>
<font color=blue>[000126]</font>
Integrate comments from 20 January meeting.

<p>
<font color=blue>[000118]</font>
Integrate comments from 13 January meeting.

<p>
<font color=blue>[000112]</font>
Integrate comments from 6 January meeting.
See in particular <a href=#forced><code>_Unwind_ForcedUnwind</code></a>.

<p>
<font color=blue>[991230]</font>
Integrate HP specification, Chapter 8.

<p>
<font color=blue>[990909]</font>
Original version.

<p>
<hr>

</BODY>
</HTML>