libstdc++
cxxabi.h
Go to the documentation of this file.
1 // ABI Support -*- C++ -*-
2 
3 // Copyright (C) 2000-2017 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>
53 
54 #ifdef __cplusplus
55 namespace __cxxabiv1
56 {
57  extern "C"
58  {
59 #endif
60 
61  typedef __cxa_cdtor_return_type (*__cxa_cdtor_type)(void *);
62 
63  // Allocate array.
64  void*
65  __cxa_vec_new(size_t __element_count, size_t __element_size,
66  size_t __padding_size, __cxa_cdtor_type __constructor,
67  __cxa_cdtor_type __destructor);
68 
69  void*
70  __cxa_vec_new2(size_t __element_count, size_t __element_size,
71  size_t __padding_size, __cxa_cdtor_type __constructor,
72  __cxa_cdtor_type __destructor, void *(*__alloc) (size_t),
73  void (*__dealloc) (void*));
74 
75  void*
76  __cxa_vec_new3(size_t __element_count, size_t __element_size,
77  size_t __padding_size, __cxa_cdtor_type __constructor,
78  __cxa_cdtor_type __destructor, void *(*__alloc) (size_t),
79  void (*__dealloc) (void*, size_t));
80 
81  // Construct array.
82  __cxa_vec_ctor_return_type
83  __cxa_vec_ctor(void* __array_address, size_t __element_count,
84  size_t __element_size, __cxa_cdtor_type __constructor,
85  __cxa_cdtor_type __destructor);
86 
87  __cxa_vec_ctor_return_type
88  __cxa_vec_cctor(void* __dest_array, void* __src_array,
89  size_t __element_count, size_t __element_size,
90  __cxa_cdtor_return_type (*__constructor) (void*, void*),
91  __cxa_cdtor_type __destructor);
92 
93  // Destruct array.
94  void
95  __cxa_vec_dtor(void* __array_address, size_t __element_count,
96  size_t __element_size, __cxa_cdtor_type __destructor);
97 
98  void
99  __cxa_vec_cleanup(void* __array_address, size_t __element_count, size_t __s,
100  __cxa_cdtor_type __destructor) _GLIBCXX_NOTHROW;
101 
102  // Destruct and release array.
103  void
104  __cxa_vec_delete(void* __array_address, size_t __element_size,
105  size_t __padding_size, __cxa_cdtor_type __destructor);
106 
107  void
108  __cxa_vec_delete2(void* __array_address, size_t __element_size,
109  size_t __padding_size, __cxa_cdtor_type __destructor,
110  void (*__dealloc) (void*));
111 
112  void
113  __cxa_vec_delete3(void* __array_address, size_t __element_size,
114  size_t __padding_size, __cxa_cdtor_type __destructor,
115  void (*__dealloc) (void*, size_t));
116 
117  int
118  __cxa_guard_acquire(__guard*);
119 
120  void
121  __cxa_guard_release(__guard*) _GLIBCXX_NOTHROW;
122 
123  void
124  __cxa_guard_abort(__guard*) _GLIBCXX_NOTHROW;
125 
126  // DSO destruction.
127  int
128  __cxa_atexit(void (*)(void*), void*, void*) _GLIBCXX_NOTHROW;
129 
130  int
131  __cxa_finalize(void*);
132 
133  // TLS destruction.
134  int
135  __cxa_thread_atexit(void (*)(void*), void*, void *) _GLIBCXX_NOTHROW;
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 auxiliary.
145  void
146  __cxa_bad_cast() __attribute__((__noreturn__));
147 
148  void
149  __cxa_bad_typeid() __attribute__((__noreturn__));
150 
151  void
152  __cxa_throw_bad_array_new_length() __attribute__((__noreturn__));
153 
154  /**
155  * @brief Demangling routine.
156  * ABI-mandated entry point in the C++ runtime library for demangling.
157  *
158  * @param __mangled_name A NUL-terminated character string
159  * containing the name to be demangled.
160  *
161  * @param __output_buffer A region of memory, allocated with
162  * malloc, of @a *__length bytes, into which the demangled name is
163  * stored. If @a __output_buffer is not long enough, it is
164  * expanded using realloc. @a __output_buffer may instead be NULL;
165  * in that case, the demangled name is placed in a region of memory
166  * allocated with malloc.
167  *
168  * @param __length If @a __length is non-NULL, the length of the
169  * buffer containing the demangled name is placed in @a *__length.
170  *
171  * @param __status @a *__status is set to one of the following values:
172  * 0: The demangling operation succeeded.
173  * -1: A memory allocation failure occurred.
174  * -2: @a mangled_name is not a valid name under the C++ ABI mangling rules.
175  * -3: One of the arguments is invalid.
176  *
177  * @return A pointer to the start of the NUL-terminated demangled
178  * name, or NULL if the demangling fails. The caller is
179  * responsible for deallocating this memory using @c free.
180  *
181  * The demangling is performed using the C++ ABI mangling rules,
182  * with GNU extensions. For example, this function is used in
183  * __gnu_cxx::__verbose_terminate_handler.
184  *
185  * See https://gcc.gnu.org/onlinedocs/libstdc++/manual/ext_demangling.html
186  * for other examples of use.
187  *
188  * @note The same demangling functionality is available via
189  * libiberty (@c <libiberty/demangle.h> and @c libiberty.a) in GCC
190  * 3.1 and later, but that requires explicit installation (@c
191  * --enable-install-libiberty) and uses a different API, although
192  * the ABI is unchanged.
193  */
194  char*
195  __cxa_demangle(const char* __mangled_name, char* __output_buffer,
196  size_t* __length, int* __status);
197 
198 #ifdef __cplusplus
199  }
200 } // namespace __cxxabiv1
201 #endif
202 
203 #ifdef __cplusplus
204 
205 #include <typeinfo>
206 
207 namespace __cxxabiv1
208 {
209  // Type information for int, float etc.
210  class __fundamental_type_info : public std::type_info
211  {
212  public:
213  explicit
214  __fundamental_type_info(const char* __n) : std::type_info(__n) { }
215 
216  virtual
217  ~__fundamental_type_info();
218  };
219 
220  // Type information for array objects.
221  class __array_type_info : public std::type_info
222  {
223  public:
224  explicit
225  __array_type_info(const char* __n) : std::type_info(__n) { }
226 
227  virtual
228  ~__array_type_info();
229  };
230 
231  // Type information for functions (both member and non-member).
232  class __function_type_info : public std::type_info
233  {
234  public:
235  explicit
236  __function_type_info(const char* __n) : std::type_info(__n) { }
237 
238  virtual
239  ~__function_type_info();
240 
241  protected:
242  // Implementation defined member function.
243  virtual bool
244  __is_function_p() const;
245  };
246 
247  // Type information for enumerations.
248  class __enum_type_info : public std::type_info
249  {
250  public:
251  explicit
252  __enum_type_info(const char* __n) : std::type_info(__n) { }
253 
254  virtual
255  ~__enum_type_info();
256  };
257 
258  // Common type information for simple pointers and pointers to member.
259  class __pbase_type_info : public std::type_info
260  {
261  public:
262  unsigned int __flags; // Qualification of the target object.
263  const std::type_info* __pointee; // Type of pointed to object.
264 
265  explicit
266  __pbase_type_info(const char* __n, int __quals,
267  const std::type_info* __type)
268  : std::type_info(__n), __flags(__quals), __pointee(__type)
269  { }
270 
271  virtual
272  ~__pbase_type_info();
273 
274  // Implementation defined type.
275  enum __masks
276  {
277  __const_mask = 0x1,
278  __volatile_mask = 0x2,
279  __restrict_mask = 0x4,
280  __incomplete_mask = 0x8,
281  __incomplete_class_mask = 0x10,
282  __transaction_safe_mask = 0x20,
283  __noexcept_mask = 0x40
284  };
285 
286  protected:
287  __pbase_type_info(const __pbase_type_info&);
288 
289  __pbase_type_info&
290  operator=(const __pbase_type_info&);
291 
292  // Implementation defined member functions.
293  virtual bool
294  __do_catch(const std::type_info* __thr_type, void** __thr_obj,
295  unsigned int __outer) const;
296 
297  inline virtual bool
298  __pointer_catch(const __pbase_type_info* __thr_type, void** __thr_obj,
299  unsigned __outer) const;
300  };
301 
302  inline bool __pbase_type_info::
303  __pointer_catch (const __pbase_type_info *thrown_type,
304  void **thr_obj,
305  unsigned outer) const
306  {
307  return __pointee->__do_catch (thrown_type->__pointee, thr_obj, outer + 2);
308  }
309 
310  // Type information for simple pointers.
311  class __pointer_type_info : public __pbase_type_info
312  {
313  public:
314  explicit
315  __pointer_type_info(const char* __n, int __quals,
316  const std::type_info* __type)
317  : __pbase_type_info (__n, __quals, __type) { }
318 
319 
320  virtual
321  ~__pointer_type_info();
322 
323  protected:
324  // Implementation defined member functions.
325  virtual bool
326  __is_pointer_p() const;
327 
328  virtual bool
329  __pointer_catch(const __pbase_type_info* __thr_type, void** __thr_obj,
330  unsigned __outer) const;
331  };
332 
333  class __class_type_info;
334 
335  // Type information for a pointer to member variable.
336  class __pointer_to_member_type_info : public __pbase_type_info
337  {
338  public:
339  __class_type_info* __context; // Class of the member.
340 
341  explicit
342  __pointer_to_member_type_info(const char* __n, int __quals,
343  const std::type_info* __type,
344  __class_type_info* __klass)
345  : __pbase_type_info(__n, __quals, __type), __context(__klass) { }
346 
347  virtual
348  ~__pointer_to_member_type_info();
349 
350  protected:
351  __pointer_to_member_type_info(const __pointer_to_member_type_info&);
352 
353  __pointer_to_member_type_info&
354  operator=(const __pointer_to_member_type_info&);
355 
356  // Implementation defined member function.
357  virtual bool
358  __pointer_catch(const __pbase_type_info* __thr_type, void** __thr_obj,
359  unsigned __outer) const;
360  };
361 
362  // Helper class for __vmi_class_type.
363  class __base_class_type_info
364  {
365  public:
366  const __class_type_info* __base_type; // Base class type.
367 #ifdef _GLIBCXX_LLP64
368  long long __offset_flags; // Offset and info.
369 #else
370  long __offset_flags; // Offset and info.
371 #endif
372 
373  enum __offset_flags_masks
374  {
375  __virtual_mask = 0x1,
376  __public_mask = 0x2,
377  __hwm_bit = 2,
378  __offset_shift = 8 // Bits to shift offset.
379  };
380 
381  // Implementation defined member functions.
382  bool
383  __is_virtual_p() const
384  { return __offset_flags & __virtual_mask; }
385 
386  bool
387  __is_public_p() const
388  { return __offset_flags & __public_mask; }
389 
390  ptrdiff_t
391  __offset() const
392  {
393  // This shift, being of a signed type, is implementation
394  // defined. GCC implements such shifts as arithmetic, which is
395  // what we want.
396  return static_cast<ptrdiff_t>(__offset_flags) >> __offset_shift;
397  }
398  };
399 
400  // Type information for a class.
401  class __class_type_info : public std::type_info
402  {
403  public:
404  explicit
405  __class_type_info (const char *__n) : type_info(__n) { }
406 
407  virtual
408  ~__class_type_info ();
409 
410  // Implementation defined types.
411  // The type sub_kind tells us about how a base object is contained
412  // within a derived object. We often do this lazily, hence the
413  // UNKNOWN value. At other times we may use NOT_CONTAINED to mean
414  // not publicly contained.
415  enum __sub_kind
416  {
417  // We have no idea.
418  __unknown = 0,
419 
420  // Not contained within us (in some circumstances this might
421  // mean not contained publicly)
422  __not_contained,
423 
424  // Contained ambiguously.
425  __contained_ambig,
426 
427  // Via a virtual path.
428  __contained_virtual_mask = __base_class_type_info::__virtual_mask,
429 
430  // Via a public path.
431  __contained_public_mask = __base_class_type_info::__public_mask,
432 
433  // Contained within us.
434  __contained_mask = 1 << __base_class_type_info::__hwm_bit,
435 
436  __contained_private = __contained_mask,
437  __contained_public = __contained_mask | __contained_public_mask
438  };
439 
440  struct __upcast_result;
441  struct __dyncast_result;
442 
443  protected:
444  // Implementation defined member functions.
445  virtual bool
446  __do_upcast(const __class_type_info* __dst_type, void**__obj_ptr) const;
447 
448  virtual bool
449  __do_catch(const type_info* __thr_type, void** __thr_obj,
450  unsigned __outer) const;
451 
452  public:
453  // Helper for upcast. See if DST is us, or one of our bases.
454  // Return false if not found, true if found.
455  virtual bool
456  __do_upcast(const __class_type_info* __dst, const void* __obj,
457  __upcast_result& __restrict __result) const;
458 
459  // Indicate whether SRC_PTR of type SRC_TYPE is contained publicly
460  // within OBJ_PTR. OBJ_PTR points to a base object of our type,
461  // which is the destination type. SRC2DST indicates how SRC
462  // objects might be contained within this type. If SRC_PTR is one
463  // of our SRC_TYPE bases, indicate the virtuality. Returns
464  // not_contained for non containment or private containment.
465  inline __sub_kind
466  __find_public_src(ptrdiff_t __src2dst, const void* __obj_ptr,
467  const __class_type_info* __src_type,
468  const void* __src_ptr) const;
469 
470  // Helper for dynamic cast. ACCESS_PATH gives the access from the
471  // most derived object to this base. DST_TYPE indicates the
472  // desired type we want. OBJ_PTR points to a base of our type
473  // within the complete object. SRC_TYPE indicates the static type
474  // started from and SRC_PTR points to that base within the most
475  // derived object. Fill in RESULT with what we find. Return true
476  // if we have located an ambiguous match.
477  virtual bool
478  __do_dyncast(ptrdiff_t __src2dst, __sub_kind __access_path,
479  const __class_type_info* __dst_type, const void* __obj_ptr,
480  const __class_type_info* __src_type, const void* __src_ptr,
481  __dyncast_result& __result) const;
482 
483  // Helper for find_public_subobj. SRC2DST indicates how SRC_TYPE
484  // bases are inherited by the type started from -- which is not
485  // necessarily the current type. The current type will be a base
486  // of the destination type. OBJ_PTR points to the current base.
487  virtual __sub_kind
488  __do_find_public_src(ptrdiff_t __src2dst, const void* __obj_ptr,
489  const __class_type_info* __src_type,
490  const void* __src_ptr) const;
491  };
492 
493  // Type information for a class with a single non-virtual base.
494  class __si_class_type_info : public __class_type_info
495  {
496  public:
497  const __class_type_info* __base_type;
498 
499  explicit
500  __si_class_type_info(const char *__n, const __class_type_info *__base)
501  : __class_type_info(__n), __base_type(__base) { }
502 
503  virtual
504  ~__si_class_type_info();
505 
506  protected:
507  __si_class_type_info(const __si_class_type_info&);
508 
509  __si_class_type_info&
510  operator=(const __si_class_type_info&);
511 
512  // Implementation defined member functions.
513  virtual bool
514  __do_dyncast(ptrdiff_t __src2dst, __sub_kind __access_path,
515  const __class_type_info* __dst_type, const void* __obj_ptr,
516  const __class_type_info* __src_type, const void* __src_ptr,
517  __dyncast_result& __result) const;
518 
519  virtual __sub_kind
520  __do_find_public_src(ptrdiff_t __src2dst, const void* __obj_ptr,
521  const __class_type_info* __src_type,
522  const void* __sub_ptr) const;
523 
524  virtual bool
525  __do_upcast(const __class_type_info*__dst, const void*__obj,
526  __upcast_result& __restrict __result) const;
527  };
528 
529  // Type information for a class with multiple and/or virtual bases.
530  class __vmi_class_type_info : public __class_type_info
531  {
532  public:
533  unsigned int __flags; // Details about the class hierarchy.
534  unsigned int __base_count; // Number of direct bases.
535 
536  // The array of bases uses the trailing array struct hack so this
537  // class is not constructable with a normal constructor. It is
538  // internally generated by the compiler.
539  __base_class_type_info __base_info[1]; // Array of bases.
540 
541  explicit
542  __vmi_class_type_info(const char* __n, int ___flags)
543  : __class_type_info(__n), __flags(___flags), __base_count(0) { }
544 
545  virtual
546  ~__vmi_class_type_info();
547 
548  // Implementation defined types.
549  enum __flags_masks
550  {
551  __non_diamond_repeat_mask = 0x1, // Distinct instance of repeated base.
552  __diamond_shaped_mask = 0x2, // Diamond shaped multiple inheritance.
553  __flags_unknown_mask = 0x10
554  };
555 
556  protected:
557  // Implementation defined member functions.
558  virtual bool
559  __do_dyncast(ptrdiff_t __src2dst, __sub_kind __access_path,
560  const __class_type_info* __dst_type, const void* __obj_ptr,
561  const __class_type_info* __src_type, const void* __src_ptr,
562  __dyncast_result& __result) const;
563 
564  virtual __sub_kind
565  __do_find_public_src(ptrdiff_t __src2dst, const void* __obj_ptr,
566  const __class_type_info* __src_type,
567  const void* __src_ptr) const;
568 
569  virtual bool
570  __do_upcast(const __class_type_info* __dst, const void* __obj,
571  __upcast_result& __restrict __result) const;
572  };
573 
574  // Exception handling forward declarations.
575  struct __cxa_exception;
576  struct __cxa_refcounted_exception;
577  struct __cxa_dependent_exception;
578  struct __cxa_eh_globals;
579 
580  extern "C"
581  {
582  // Dynamic cast runtime.
583 
584  // src2dst has the following possible values
585  // >-1: src_type is a unique public non-virtual base of dst_type
586  // dst_ptr + src2dst == src_ptr
587  // -1: unspecified relationship
588  // -2: src_type is not a public base of dst_type
589  // -3: src_type is a multiple public non-virtual base of dst_type
590  void*
591  __dynamic_cast(const void* __src_ptr, // Starting object.
592  const __class_type_info* __src_type, // Static type of object.
593  const __class_type_info* __dst_type, // Desired target type.
594  ptrdiff_t __src2dst); // How src and dst are related.
595 
596 
597  // Exception handling runtime.
598 
599  // The __cxa_eh_globals for the current thread can be obtained by using
600  // either of the following functions. The "fast" version assumes at least
601  // one prior call of __cxa_get_globals has been made from the current
602  // thread, so no initialization is necessary.
603  __cxa_eh_globals*
604  __cxa_get_globals() _GLIBCXX_NOTHROW __attribute__ ((__const__));
605 
606  __cxa_eh_globals*
607  __cxa_get_globals_fast() _GLIBCXX_NOTHROW __attribute__ ((__const__));
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
Exception thrown by __cxa_guard_acquire.6.7[stmt.dcl]/4: If control re-enters the declaration (recurs...
Definition: cxxabi.h:694
Base class for all library exceptions.
Definition: exception.h:60
ISO C++ entities toplevel namespace is std.
GNU extensions for public use.
Part of RTTI.
Definition: typeinfo:88