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