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