cxxabi.h revision 227972 
1#ifndef __CXXABI_H_
2#define __CXXABI_H_
3#include <stdint.h>
4#include "unwind.h"
5namespace 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
21namespace __cxxabiv1 {
22extern "C" {
23#endif
24/**
25 * Function type to call when an unexpected exception is encountered.
26 */
27typedef void (*unexpected_handler)();
28/**
29 * Function type to call when an unrecoverable condition is encountered.
30 */
31typedef 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 */
54struct __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 */
152struct __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 */
178void __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 */
184void *__cxa_current_primary_exception(void);
185/**
186 * Increments the reference count of an exception.  Called when an
187 * exception_ptr is copied.
188 */
189void __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 */
194void __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 */
208char* __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
216namespace abi = __cxxabiv1;
217
218#endif /* __cplusplus */
219#endif /* __CXXABI_H_ */
220