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