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