libstdc++

cxxabi.h
Go to the documentation of this file.
1 // ABI Support -*- C++ -*-
2
3 // Copyright (C) 2000-2013 Free Software Foundation, Inc.
4 //
5 // This file is part of GCC.
6 //
7 // GCC is free software; you can redistribute it and/or modify
8 // it under the terms of the GNU General Public License as published by
9 // the Free Software Foundation; either version 3, or (at your option)
10 // any later version.
11 //
12 // GCC is distributed in the hope that it will be useful,
13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 // GNU General Public License for more details.
16 //
17 // Under Section 7 of GPL version 3, you are granted additional
18 // permissions described in the GCC Runtime Library Exception, version
19 // 3.1, as published by the Free Software Foundation.
20
21 // You should have received a copy of the GNU General Public License and
22 // a copy of the GCC Runtime Library Exception along with this program;
23 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
24 // <http://www.gnu.org/licenses/>.
25
26 // Written by Nathan Sidwell, Codesourcery LLC, <nathan@codesourcery.com>
27
28 /* This file declares the new abi entry points into the runtime. It is not
29 normally necessary for user programs to include this header, or use the
30 entry points directly. However, this header is available should that be
31 needed.
32
33 Some of the entry points are intended for both C and C++, thus this header
34 is includable from both C and C++. Though the C++ specific parts are not
35 available in C, naturally enough. */
36
37 /** @file cxxabi.h
38 * The header provides an interface to the C++ ABI.
39 */
40
41 #ifndef _CXXABI_H
42 #define _CXXABI_H 1
43
44 #pragma GCC system_header
45
46 #pragma GCC visibility push(default)
47
48 #include <stddef.h>
49 #include <bits/c++config.h>
50 #include <bits/cxxabi_tweaks.h>
51 #include <bits/cxxabi_forced.h>
52
53 #ifndef _GLIBCXX_CDTOR_CALLABI
54 #define _GLIBCXX_CDTOR_CALLABI
55 #endif
56
57 #ifdef __cplusplus
58 namespace __cxxabiv1
59 {
60 extern "C"
61 {
62 #endif
63
64 typedef __cxa_cdtor_return_type (*__cxa_cdtor_type)(void *);
65
66 // Allocate array.
67 void*
68 __cxa_vec_new(size_t __element_count, size_t __element_size,
69 size_t __padding_size, __cxa_cdtor_type __constructor,
70 __cxa_cdtor_type __destructor);
71
72 void*
73 __cxa_vec_new2(size_t __element_count, size_t __element_size,
74 size_t __padding_size, __cxa_cdtor_type __constructor,
75 __cxa_cdtor_type __destructor, void *(*__alloc) (size_t),
76 void (*__dealloc) (void*));
77
78 void*
79 __cxa_vec_new3(size_t __element_count, size_t __element_size,
80 size_t __padding_size, __cxa_cdtor_type __constructor,
81 __cxa_cdtor_type __destructor, void *(*__alloc) (size_t),
82 void (*__dealloc) (void*, size_t));
83
84 // Construct array.
85 __cxa_vec_ctor_return_type
86 __cxa_vec_ctor(void* __array_address, size_t __element_count,
87 size_t __element_size, __cxa_cdtor_type __constructor,
88 __cxa_cdtor_type __destructor);
89
90 __cxa_vec_ctor_return_type
91 __cxa_vec_cctor(void* __dest_array, void* __src_array,
92 size_t __element_count, size_t __element_size,
93 __cxa_cdtor_return_type (*__constructor) (void*, void*),
94 __cxa_cdtor_type __destructor);
95
96 // Destruct array.
97 void
98 __cxa_vec_dtor(void* __array_address, size_t __element_count,
99 size_t __element_size, __cxa_cdtor_type __destructor);
100
101 void
102 __cxa_vec_cleanup(void* __array_address, size_t __element_count, size_t __s,
103 __cxa_cdtor_type __destructor) _GLIBCXX_NOTHROW;
104
105 // Destruct and release array.
106 void
107 __cxa_vec_delete(void* __array_address, size_t __element_size,
108 size_t __padding_size, __cxa_cdtor_type __destructor);
109
110 void
111 __cxa_vec_delete2(void* __array_address, size_t __element_size,
112 size_t __padding_size, __cxa_cdtor_type __destructor,
113 void (*__dealloc) (void*));
114
115 void
116 __cxa_vec_delete3(void* __array_address, size_t __element_size,
117 size_t __padding_size, __cxa_cdtor_type __destructor,
118 void (*__dealloc) (void*, size_t));
119
120 int
121 __cxa_guard_acquire(__guard*);
122
123 void
124 __cxa_guard_release(__guard*) _GLIBCXX_NOTHROW;
125
126 void
127 __cxa_guard_abort(__guard*) _GLIBCXX_NOTHROW;
128
129 // DSO destruction.
130 int
131 __cxa_atexit(void (*)(void*), void*, void*) _GLIBCXX_NOTHROW;
132
133 int
134 __cxa_finalize(void*);
135
136 // TLS destruction.
137 int
138 __cxa_thread_atexit(void (*)(void*), void*, void *) _GLIBCXX_NOTHROW;
139
140 // Pure virtual functions.
141 void
142 __cxa_pure_virtual(void) __attribute__ ((__noreturn__));
143
144 void
145 __cxa_deleted_virtual(void) __attribute__ ((__noreturn__));
146
147 // Exception handling auxillary.
148 void
149 __cxa_bad_cast() __attribute__((__noreturn__));
150
151 void
152 __cxa_bad_typeid() __attribute__((__noreturn__));
153
154
155 /**
156 * @brief Demangling routine.
157 * ABI-mandated entry point in the C++ runtime library for demangling.
158 *
159 * @param __mangled_name A NUL-terminated character string
160 * containing the name to be demangled.
161 *
162 * @param __output_buffer A region of memory, allocated with
163 * malloc, of @a *__length bytes, into which the demangled name is
164 * stored. If @a __output_buffer is not long enough, it is
165 * expanded using realloc. @a __output_buffer may instead be NULL;
166 * in that case, the demangled name is placed in a region of memory
167 * allocated with malloc.
168 *
169 * @param __length If @a __length is non-NULL, the length of the
170 * buffer containing the demangled name is placed in @a *__length.
171 *
172 * @param __status @a *__status is set to one of the following values:
173 * 0: The demangling operation succeeded.
174 * -1: A memory allocation failure occurred.
175 * -2: @a mangled_name is not a valid name under the C++ ABI mangling rules.
176 * -3: One of the arguments is invalid.
177 *
178 * @return A pointer to the start of the NUL-terminated demangled
179 * name, or NULL if the demangling fails. The caller is
180 * responsible for deallocating this memory using @c free.
181 *
182 * The demangling is performed using the C++ ABI mangling rules,
183 * with GNU extensions. For example, this function is used in
184 * __gnu_cxx::__verbose_terminate_handler.
185 *
186 * See http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt12ch39.html
187 * for other examples of use.
188 *
189 * @note The same demangling functionality is available via
190 * libiberty (@c <libiberty/demangle.h> and @c libiberty.a) in GCC
191 * 3.1 and later, but that requires explicit installation (@c
192 * --enable-install-libiberty) and uses a different API, although
193 * the ABI is unchanged.
194 */
195 char*
196 __cxa_demangle(const char* __mangled_name, char* __output_buffer,
197 size_t* __length, int* __status);
198
199 #ifdef __cplusplus
200 }
201 } // namespace __cxxabiv1
202 #endif
203
204 #ifdef __cplusplus
205
206 #include <typeinfo>
207
208 namespace __cxxabiv1
209 {
210 // Type information for int, float etc.
211 class __fundamental_type_info : public std::type_info
212 {
213 public:
214 explicit
215 __fundamental_type_info(const char* __n) : std::type_info(__n) { }
216
217 virtual
218 ~__fundamental_type_info();
219 };
220
221 // Type information for array objects.
222 class __array_type_info : public std::type_info
223 {
224 public:
225 explicit
226 __array_type_info(const char* __n) : std::type_info(__n) { }
227
228 virtual
229 ~__array_type_info();
230 };
231
232 // Type information for functions (both member and non-member).
233 class __function_type_info : public std::type_info
234 {
235 public:
236 explicit
237 __function_type_info(const char* __n) : std::type_info(__n) { }
238
239 virtual
240 ~__function_type_info();
241
242 protected:
243 // Implementation defined member function.
244 virtual bool
245 __is_function_p() const;
246 };
247
248 // Type information for enumerations.
249 class __enum_type_info : public std::type_info
250 {
251 public:
252 explicit
253 __enum_type_info(const char* __n) : std::type_info(__n) { }
254
255 virtual
256 ~__enum_type_info();
257 };
258
259 // Common type information for simple pointers and pointers to member.
260 class __pbase_type_info : public std::type_info
261 {
262 public:
263 unsigned int __flags; // Qualification of the target object.
264 const std::type_info* __pointee; // Type of pointed to object.
265
266 explicit
267 __pbase_type_info(const char* __n, int __quals,
268 const std::type_info* __type)
269 : std::type_info(__n), __flags(__quals), __pointee(__type)
270 { }
271
272 virtual
273 ~__pbase_type_info();
274
275 // Implementation defined type.
276 enum __masks
277 {
278 __const_mask = 0x1,
279 __volatile_mask = 0x2,
280 __restrict_mask = 0x4,
281 __incomplete_mask = 0x8,
282 __incomplete_class_mask = 0x10
283 };
284
285 protected:
286 __pbase_type_info(const __pbase_type_info&);
287
288 __pbase_type_info&
289 operator=(const __pbase_type_info&);
290
291 // Implementation defined member functions.
292 virtual bool
293 __do_catch(const std::type_info* __thr_type, void** __thr_obj,
294 unsigned int __outer) const;
295
296 inline virtual bool
297 __pointer_catch(const __pbase_type_info* __thr_type, void** __thr_obj,
298 unsigned __outer) const;
299 };
300
301 // Type information for simple pointers.
302 class __pointer_type_info : public __pbase_type_info
303 {
304 public:
305 explicit
306 __pointer_type_info(const char* __n, int __quals,
307 const std::type_info* __type)
308 : __pbase_type_info (__n, __quals, __type) { }
309
310
311 virtual
312 ~__pointer_type_info();
313
314 protected:
315 // Implementation defined member functions.
316 virtual bool
317 __is_pointer_p() const;
318
319 virtual bool
320 __pointer_catch(const __pbase_type_info* __thr_type, void** __thr_obj,
321 unsigned __outer) const;
322 };
323
324 class __class_type_info;
325
326 // Type information for a pointer to member variable.
327 class __pointer_to_member_type_info : public __pbase_type_info
328 {
329 public:
330 __class_type_info* __context; // Class of the member.
331
332 explicit
333 __pointer_to_member_type_info(const char* __n, int __quals,
334 const std::type_info* __type,
335 __class_type_info* __klass)
336 : __pbase_type_info(__n, __quals, __type), __context(__klass) { }
337
338 virtual
339 ~__pointer_to_member_type_info();
340
341 protected:
342 __pointer_to_member_type_info(const __pointer_to_member_type_info&);
343
344 __pointer_to_member_type_info&
345 operator=(const __pointer_to_member_type_info&);
346
347 // Implementation defined member function.
348 virtual bool
349 __pointer_catch(const __pbase_type_info* __thr_type, void** __thr_obj,
350 unsigned __outer) const;
351 };
352
353 // Helper class for __vmi_class_type.
354 class __base_class_type_info
355 {
356 public:
357 const __class_type_info* __base_type; // Base class type.
358 #ifdef _GLIBCXX_LLP64
359 long long __offset_flags; // Offset and info.
360 #else
361 long __offset_flags; // Offset and info.
362 #endif
363
364 enum __offset_flags_masks
365 {
366 __virtual_mask = 0x1,
367 __public_mask = 0x2,
368 __hwm_bit = 2,
369 __offset_shift = 8 // Bits to shift offset.
370 };
371
372 // Implementation defined member functions.
373 bool
374 __is_virtual_p() const
375 { return __offset_flags & __virtual_mask; }
376
377 bool
378 __is_public_p() const
379 { return __offset_flags & __public_mask; }
380
381 ptrdiff_t
382 __offset() const
383 {
384 // This shift, being of a signed type, is implementation
385 // defined. GCC implements such shifts as arithmetic, which is
386 // what we want.
387 return static_cast<ptrdiff_t>(__offset_flags) >> __offset_shift;
388 }
389 };
390
391 // Type information for a class.
392 class __class_type_info : public std::type_info
393 {
394 public:
395 explicit
396 __class_type_info (const char *__n) : type_info(__n) { }
397
398 virtual
399 ~__class_type_info ();
400
401 // Implementation defined types.
402 // The type sub_kind tells us about how a base object is contained
403 // within a derived object. We often do this lazily, hence the
404 // UNKNOWN value. At other times we may use NOT_CONTAINED to mean
405 // not publicly contained.
406 enum __sub_kind
407 {
408 // We have no idea.
409 __unknown = 0,
410
411 // Not contained within us (in some circumstances this might
412 // mean not contained publicly)
413 __not_contained,
414
415 // Contained ambiguously.
416 __contained_ambig,
417
418 // Via a virtual path.
419 __contained_virtual_mask = __base_class_type_info::__virtual_mask,
420
421 // Via a public path.
422 __contained_public_mask = __base_class_type_info::__public_mask,
423
424 // Contained within us.
425 __contained_mask = 1 << __base_class_type_info::__hwm_bit,
426
427 __contained_private = __contained_mask,
428 __contained_public = __contained_mask | __contained_public_mask
429 };
430
431 struct __upcast_result;
432 struct __dyncast_result;
433
434 protected:
435 // Implementation defined member functions.
436 virtual bool
437 __do_upcast(const __class_type_info* __dst_type, void**__obj_ptr) const;
438
439 virtual bool
440 __do_catch(const type_info* __thr_type, void** __thr_obj,
441 unsigned __outer) const;
442
443 public:
444 // Helper for upcast. See if DST is us, or one of our bases.
445 // Return false if not found, true if found.
446 virtual bool
447 __do_upcast(const __class_type_info* __dst, const void* __obj,
448 __upcast_result& __restrict __result) const;
449
450 // Indicate whether SRC_PTR of type SRC_TYPE is contained publicly
451 // within OBJ_PTR. OBJ_PTR points to a base object of our type,
452 // which is the destination type. SRC2DST indicates how SRC
453 // objects might be contained within this type. If SRC_PTR is one
454 // of our SRC_TYPE bases, indicate the virtuality. Returns
455 // not_contained for non containment or private containment.
456 inline __sub_kind
457 __find_public_src(ptrdiff_t __src2dst, const void* __obj_ptr,
458 const __class_type_info* __src_type,
459 const void* __src_ptr) const;
460
461 // Helper for dynamic cast. ACCESS_PATH gives the access from the
462 // most derived object to this base. DST_TYPE indicates the
463 // desired type we want. OBJ_PTR points to a base of our type
464 // within the complete object. SRC_TYPE indicates the static type
465 // started from and SRC_PTR points to that base within the most
466 // derived object. Fill in RESULT with what we find. Return true
467 // if we have located an ambiguous match.
468 virtual bool
469 __do_dyncast(ptrdiff_t __src2dst, __sub_kind __access_path,
470 const __class_type_info* __dst_type, const void* __obj_ptr,
471 const __class_type_info* __src_type, const void* __src_ptr,
472 __dyncast_result& __result) const;
473
474 // Helper for find_public_subobj. SRC2DST indicates how SRC_TYPE
475 // bases are inherited by the type started from -- which is not
476 // necessarily the current type. The current type will be a base
477 // of the destination type. OBJ_PTR points to the current base.
478 virtual __sub_kind
479 __do_find_public_src(ptrdiff_t __src2dst, const void* __obj_ptr,
480 const __class_type_info* __src_type,
481 const void* __src_ptr) const;
482 };
483
484 // Type information for a class with a single non-virtual base.
485 class __si_class_type_info : public __class_type_info
486 {
487 public:
488 const __class_type_info* __base_type;
489
490 explicit
491 __si_class_type_info(const char *__n, const __class_type_info *__base)
492 : __class_type_info(__n), __base_type(__base) { }
493
494 virtual
495 ~__si_class_type_info();
496
497 protected:
498 __si_class_type_info(const __si_class_type_info&);
499
500 __si_class_type_info&
501 operator=(const __si_class_type_info&);
502
503 // Implementation defined member functions.
504 virtual bool
505 __do_dyncast(ptrdiff_t __src2dst, __sub_kind __access_path,
506 const __class_type_info* __dst_type, const void* __obj_ptr,
507 const __class_type_info* __src_type, const void* __src_ptr,
508 __dyncast_result& __result) const;
509
510 virtual __sub_kind
511 __do_find_public_src(ptrdiff_t __src2dst, const void* __obj_ptr,
512 const __class_type_info* __src_type,
513 const void* __sub_ptr) const;
514
515 virtual bool
516 __do_upcast(const __class_type_info*__dst, const void*__obj,
517 __upcast_result& __restrict __result) const;
518 };
519
520 // Type information for a class with multiple and/or virtual bases.
521 class __vmi_class_type_info : public __class_type_info
522 {
523 public:
524 unsigned int __flags; // Details about the class hierarchy.
525 unsigned int __base_count; // Number of direct bases.
526
527 // The array of bases uses the trailing array struct hack so this
528 // class is not constructable with a normal constructor. It is
529 // internally generated by the compiler.
530 __base_class_type_info __base_info[1]; // Array of bases.
531
532 explicit
533 __vmi_class_type_info(const char* __n, int ___flags)
534 : __class_type_info(__n), __flags(___flags), __base_count(0) { }
535
536 virtual
537 ~__vmi_class_type_info();
538
539 // Implementation defined types.
540 enum __flags_masks
541 {
542 __non_diamond_repeat_mask = 0x1, // Distinct instance of repeated base.
543 __diamond_shaped_mask = 0x2, // Diamond shaped multiple inheritance.
544 __flags_unknown_mask = 0x10
545 };
546
547 protected:
548 // Implementation defined member functions.
549 virtual bool
550 __do_dyncast(ptrdiff_t __src2dst, __sub_kind __access_path,
551 const __class_type_info* __dst_type, const void* __obj_ptr,
552 const __class_type_info* __src_type, const void* __src_ptr,
553 __dyncast_result& __result) const;
554
555 virtual __sub_kind
556 __do_find_public_src(ptrdiff_t __src2dst, const void* __obj_ptr,
557 const __class_type_info* __src_type,
558 const void* __src_ptr) const;
559
560 virtual bool
561 __do_upcast(const __class_type_info* __dst, const void* __obj,
562 __upcast_result& __restrict __result) const;
563 };
564
565 // Exception handling forward declarations.
566 struct __cxa_exception;
567 struct __cxa_refcounted_exception;
568 struct __cxa_dependent_exception;
569 struct __cxa_eh_globals;
570
571 extern "C"
572 {
573 // Dynamic cast runtime.
574
575 // src2dst has the following possible values
576 // >-1: src_type is a unique public non-virtual base of dst_type
577 // dst_ptr + src2dst == src_ptr
578 // -1: unspecified relationship
579 // -2: src_type is not a public base of dst_type
580 // -3: src_type is a multiple public non-virtual base of dst_type
581 void*
582 __dynamic_cast(const void* __src_ptr, // Starting object.
583 const __class_type_info* __src_type, // Static type of object.
584 const __class_type_info* __dst_type, // Desired target type.
585 ptrdiff_t __src2dst); // How src and dst are related.
586
587
588 // Exception handling runtime.
589
590 // The __cxa_eh_globals for the current thread can be obtained by using
591 // either of the following functions. The "fast" version assumes at least
592 // one prior call of __cxa_get_globals has been made from the current
593 // thread, so no initialization is necessary.
594 __cxa_eh_globals*
595 __cxa_get_globals() _GLIBCXX_NOTHROW __attribute__ ((__const__));
596
597 __cxa_eh_globals*
598 __cxa_get_globals_fast() _GLIBCXX_NOTHROW __attribute__ ((__const__));
599
600 // Allocate memory for the primary exception plus the thrown object.
601 void*
602 __cxa_allocate_exception(size_t) _GLIBCXX_NOTHROW;
603
604 // Free the space allocated for the primary exception.
605 void
606 __cxa_free_exception(void*) _GLIBCXX_NOTHROW;
607
608 // Throw the exception.
609 void
610 __cxa_throw(void*, std::type_info*, void (_GLIBCXX_CDTOR_CALLABI *) (void *))
611 __attribute__((__noreturn__));
612
613 // Used to implement exception handlers.
614 void*
615 __cxa_get_exception_ptr(void*) _GLIBCXX_NOTHROW __attribute__ ((__pure__));
616
617 void*
618 __cxa_begin_catch(void*) _GLIBCXX_NOTHROW;
619
620 void
621 __cxa_end_catch();
622
623 void
624 __cxa_rethrow() __attribute__((__noreturn__));
625
626 // Returns the type_info for the currently handled exception [15.3/8], or
627 // null if there is none.
628 std::type_info*
629 __cxa_current_exception_type() _GLIBCXX_NOTHROW __attribute__ ((__pure__));
630
631 // GNU Extensions.
632
633 // Allocate memory for a dependent exception.
634 __cxa_dependent_exception*
635 __cxa_allocate_dependent_exception() _GLIBCXX_NOTHROW;
636
637 // Free the space allocated for the dependent exception.
638 void
639 __cxa_free_dependent_exception(__cxa_dependent_exception*) _GLIBCXX_NOTHROW;
640
641 } // extern "C"
642
643 // A magic placeholder class that can be caught by reference
644 // to recognize foreign exceptions.
645 class __foreign_exception
646 {
647 virtual ~__foreign_exception() throw();
648 virtual void __pure_dummy() = 0; // prevent catch by value
649 };
650
651 } // namespace __cxxabiv1
652
653 /** @namespace abi
654 * @brief The cross-vendor C++ Application Binary Interface. A
655 * namespace alias to __cxxabiv1, but user programs should use the
656 * alias 'abi'.
657 *
658 * A brief overview of an ABI is given in the libstdc++ FAQ, question
659 * 5.8 (you may have a copy of the FAQ locally, or you can view the online
660 * version at http://gcc.gnu.org/onlinedocs/libstdc++/faq.html#5_8 ).
661 *
662 * GCC subscribes to a cross-vendor ABI for C++, sometimes
663 * called the IA64 ABI because it happens to be the native ABI for that
664 * platform. It is summarized at http://www.codesourcery.com/cxx-abi/
665 * along with the current specification.
666 *
667 * For users of GCC greater than or equal to 3.x, entry points are
668 * available in <cxxabi.h>, which notes, <em>'It is not normally
669 * necessary for user programs to include this header, or use the
670 * entry points directly. However, this header is available should
671 * that be needed.'</em>
672 */
673 namespace abi = __cxxabiv1;
674
675 namespace __gnu_cxx
676 {
677 /**
678 * @brief Exception thrown by __cxa_guard_acquire.
679 * @ingroup exceptions
680 *
681 * 6.7[stmt.dcl]/4: If control re-enters the declaration (recursively)
682 * while the object is being initialized, the behavior is undefined.
683 *
684 * Since we already have a library function to handle locking, we might
685 * as well check for this situation and throw an exception.
686 * We use the second byte of the guard variable to remember that we're
687 * in the middle of an initialization.
688 */
689 class recursive_init_error: public std::exception
690 {
691 public:
692 recursive_init_error() throw() { }
693 virtual ~recursive_init_error() throw ();
694 };
695 }
696 #endif // __cplusplus
697
698 #pragma GCC visibility pop
699
700 #endif // __CXXABI_H