cxxabi.h

   1 #ifndef __CXXABI_H_
   2 #define __CXXABI_H_
   3 #include <stdint.h>
   4 #include "unwind.h"
   5 namespace std
   6 {
   7         class type_info;
   8 }
   9 /*
  10  * The cxxabi.h header provides a set of public definitions for types and
  11  * functions defined by the Itanium C++ ABI specification.  For reference, see
  12  * the ABI specification here:
  13  *
  14  * http://sourcery.mentor.com/public/cxx-abi/abi.html
  15  *
  16  * All deviations from this specification, unless otherwise noted, are
  17  * accidental.
  18  */
  19
  20 #ifdef __cplusplus
  21 namespace __cxxabiv1 {
  22 extern "C" {
  23 #endif
  24 /**
  25  * Function type to call when an unexpected exception is encountered.
  26  */
  27 typedef void (*unexpected_handler)();
  28 /**
  29  * Function type to call when an unrecoverable condition is encountered.
  30  */
  31 typedef void (*terminate_handler)();
  32
  33
  34 /**
  35  * Structure used as a header on thrown exceptions.  This is the same layout as
  36  * defined by the Itanium ABI spec, so should be interoperable with any other
  37  * implementation of this spec, such as GNU libsupc++.
  38  *
  39  * This structure is allocated when an exception is thrown.  Unwinding happens
  40  * in two phases, the first looks for a handler and the second installs the
  41  * context.  This structure stores a cache of the handler location between
  42  * phase 1 and phase 2.  Unfortunately, cleanup information is not cached, so
  43  * must be looked up in both phases.  This happens for two reasons.  The first
  44  * is that we don't know how many frames containing cleanups there will be, and
  45  * we should avoid dynamic allocation during unwinding (the exception may be
  46  * reporting that we've run out of memory).  The second is that finding
  47  * cleanups is much cheaper than finding handlers, because we don't have to
  48  * look at the type table at all.
  49  *
  50  * Note: Several fields of this structure have not-very-informative names.
  51  * These are taken from the ABI spec and have not been changed to make it
  52  * easier for people referring to to the spec while reading this code.
  53  */
  54 struct __cxa_exception
  55 {
  56 #if __LP64__
  57         /**
  58          * Reference count.  Used to support the C++11 exception_ptr class.  This
  59          * is prepended to the structure in 64-bit mode and squeezed in to the
  60          * padding left before the 64-bit aligned _Unwind_Exception at the end in
  61          * 32-bit mode.
  62          *
  63          * Note that it is safe to extend this structure at the beginning, rather
  64          * than the end, because the public API for creating it returns the address
  65          * of the end (where the exception object can be stored).
  66          */
  67         uintptr_t referenceCount;
  68 #endif
  69         /** Type info for the thrown object. */
  70         std::type_info *exceptionType;
  71         /** Destructor for the object, if one exists. */
  72         void (*exceptionDestructor) (void *);
  73         /** Handler called when an exception specification is violated. */
  74         unexpected_handler unexpectedHandler;
  75         /** Hander called to terminate. */
  76         terminate_handler terminateHandler;
  77         /**
  78          * Next exception in the list.  If an exception is thrown inside a catch
  79          * block and caught in a nested catch, this points to the exception that
  80          * will be handled after the inner catch block completes.
  81          */
  82         __cxa_exception *nextException;
  83         /**
  84          * The number of handlers that currently have references to this
  85          * exception.  The top (non-sign) bit of this is used as a flag to indicate
  86          * that the exception is being rethrown, so should not be deleted when its
  87          * handler count reaches 0 (which it doesn't with the top bit set).
  88          */
  89         int handlerCount;
  90 #ifdef __arm__
  91         /**
  92          * The ARM EH ABI requires the unwind library to keep track of exceptions
  93          * during cleanups.  These support nesting, so we need to keep a list of
  94          * them.
  95          */
  96         _Unwind_Exception *nextCleanup;
  97         /**
  98          * The number of cleanups that are currently being run on this exception.
  99          */
 100         int cleanupCount;
 101 #endif
 102         /**
 103          * The selector value to be returned when installing the catch handler.
 104          * Used at the call site to determine which catch() block should execute.
 105          * This is found in phase 1 of unwinding then installed in phase 2.
 106          */
 107         int handlerSwitchValue;
 108         /**
 109          * The action record for the catch.  This is cached during phase 1
 110          * unwinding.
 111          */
 112         const char *actionRecord;
 113         /**
 114          * Pointer to the language-specific data area (LSDA) for the handler
 115          * frame.  This is unused in this implementation, but set for ABI
 116          * compatibility in case we want to mix code in very weird ways.
 117          */
 118         const char *languageSpecificData;
 119         /** The cached landing pad for the catch handler.*/
 120         void *catchTemp;
 121         /**
 122          * The pointer that will be returned as the pointer to the object.  When
 123          * throwing a class and catching a virtual superclass (for example), we
 124          * need to adjust the thrown pointer to make it all work correctly.
 125          */
 126         void *adjustedPtr;
 127 #if !__LP64__
 128         /**
 129          * Reference count.  Used to support the C++11 exception_ptr class.  This
 130          * is prepended to the structure in 64-bit mode and squeezed in to the
 131          * padding left before the 64-bit aligned _Unwind_Exception at the end in
 132          * 32-bit mode.
 133          *
 134          * Note that it is safe to extend this structure at the beginning, rather
 135          * than the end, because the public API for creating it returns the address
 136          * of the end (where the exception object can be stored)
 137          */
 138         uintptr_t referenceCount;
 139 #endif
 140         /** The language-agnostic part of the exception header. */
 141         _Unwind_Exception unwindHeader;
 142 };
 143
 144 /**
 145  * ABI-specified globals structure.  Returned by the __cxa_get_globals()
 146  * function and its fast variant.  This is a per-thread structure - every
 147  * thread will have one lazily allocated.
 148  *
 149  * This structure is defined by the ABI, so may be used outside of this
 150  * library.
 151  */
 152 struct __cxa_eh_globals
 153 {
 154         /**
 155          * A linked list of exceptions that are currently caught.  There may be
 156          * several of these in nested catch() blocks.
 157          */
 158         __cxa_exception *caughtExceptions;
 159         /**
 160          * The number of uncaught exceptions.
 161          */
 162         unsigned int uncaughtExceptions;
 163 };
 164 /**
 165  * ABI function returning the __cxa_eh_globals structure.
 166  */
 167 __cxa_eh_globals *__cxa_get_globals(void);
 168 /**
 169  * Version of __cxa_get_globals() assuming that __cxa_get_globals() has already
 170  * been called at least once by this thread.
 171  */
 172 __cxa_eh_globals *__cxa_get_globals_fast(void);
 173
 174 /**
 175  * Throws an exception returned by __cxa_current_primary_exception().  This
 176  * exception may have been caught in another thread.
 177  */
 178 void __cxa_rethrow_primary_exception(void* thrown_exception);
 179 /**
 180  * Returns the current exception in a form that can be stored in an
 181  * exception_ptr object and then rethrown by a call to
 182  * __cxa_rethrow_primary_exception().
 183  */
 184 void *__cxa_current_primary_exception(void);
 185 /**
 186  * Increments the reference count of an exception.  Called when an
 187  * exception_ptr is copied.
 188  */
 189 void __cxa_increment_exception_refcount(void* thrown_exception);
 190 /**
 191  * Decrements the reference count of an exception.  Called when an
 192  * exception_ptr is deleted.
 193  */
 194 void __cxa_decrement_exception_refcount(void* thrown_exception);
 195 /**
 196  * Demangles a C++ symbol or type name.  The buffer, if non-NULL, must be
 197  * allocated with malloc() and must be *n bytes or more long.  This function
 198  * may call realloc() on the value pointed to by buf, and will return the
 199  * length of the string via *n.
 200  *
 201  * The value pointed to by status is set to one of the following:
 202  *
 203  * 0: success
 204  * -1: memory allocation failure
 205  * -2: invalid mangled name
 206  * -3: invalid arguments
 207  */
 208 char* __cxa_demangle(const char* mangled_name,
 209                      char* buf,
 210                      size_t* n,
 211                      int* status);
 212 #ifdef __cplusplus
 213 } // extern "C"
 214 } // namespace
 215
 216 namespace abi = __cxxabiv1;
 217
 218 #endif /* __cplusplus */
 219 #endif /* __CXXABI_H_ */