libstdc++
cxxabi.h
Go to the documentation of this file.
00001 // ABI Support -*- C++ -*-
00002 
00003 // Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2009, 2010, 2011
00004 // Free Software Foundation, Inc.
00005 //
00006 // This file is part of GCC.
00007 //
00008 // GCC is free software; you can redistribute it and/or modify
00009 // it under the terms of the GNU General Public License as published by
00010 // the Free Software Foundation; either version 3, or (at your option)
00011 // any later version.
00012 //
00013 // GCC is distributed in the hope that it will be useful,
00014 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00015 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00016 // GNU General Public License for more details.
00017 //
00018 // Under Section 7 of GPL version 3, you are granted additional
00019 // permissions described in the GCC Runtime Library Exception, version
00020 // 3.1, as published by the Free Software Foundation.
00021 
00022 // You should have received a copy of the GNU General Public License and
00023 // a copy of the GCC Runtime Library Exception along with this program;
00024 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
00025 // <http://www.gnu.org/licenses/>.
00026 
00027 // Written by Nathan Sidwell, Codesourcery LLC, <nathan@codesourcery.com>
00028 
00029 /* This file declares the new abi entry points into the runtime. It is not
00030    normally necessary for user programs to include this header, or use the
00031    entry points directly. However, this header is available should that be
00032    needed.
00033 
00034    Some of the entry points are intended for both C and C++, thus this header
00035    is includable from both C and C++. Though the C++ specific parts are not
00036    available in C, naturally enough.  */
00037 
00038 /** @file cxxabi.h
00039  *  The header provides an interface to the C++ ABI.
00040  */
00041 
00042 #ifndef _CXXABI_H
00043 #define _CXXABI_H 1
00044 
00045 #pragma GCC system_header
00046 
00047 #pragma GCC visibility push(default)
00048 
00049 #include <stddef.h>
00050 #include <bits/c++config.h>
00051 #include <bits/cxxabi_tweaks.h>
00052 #include <bits/cxxabi_forced.h>
00053 
00054 #ifdef __cplusplus
00055 namespace __cxxabiv1
00056 {
00057   extern "C"
00058   {
00059 #endif
00060 
00061   typedef __cxa_cdtor_return_type (*__cxa_cdtor_type)(void *);
00062 
00063   // Allocate array.
00064   void*
00065   __cxa_vec_new(size_t __element_count, size_t __element_size,
00066         size_t __padding_size, __cxa_cdtor_type __constructor,
00067         __cxa_cdtor_type __destructor);
00068 
00069   void*
00070   __cxa_vec_new2(size_t __element_count, size_t __element_size,
00071          size_t __padding_size, __cxa_cdtor_type __constructor,
00072          __cxa_cdtor_type __destructor, void *(*__alloc) (size_t),
00073          void (*__dealloc) (void*));
00074 
00075   void*
00076   __cxa_vec_new3(size_t __element_count, size_t __element_size,
00077          size_t __padding_size, __cxa_cdtor_type __constructor,
00078          __cxa_cdtor_type __destructor, void *(*__alloc) (size_t),
00079          void (*__dealloc) (void*, size_t));
00080 
00081   // Construct array.
00082   __cxa_vec_ctor_return_type
00083   __cxa_vec_ctor(void* __array_address, size_t __element_count,
00084          size_t __element_size, __cxa_cdtor_type __constructor,
00085          __cxa_cdtor_type __destructor);
00086 
00087   __cxa_vec_ctor_return_type
00088   __cxa_vec_cctor(void* __dest_array, void* __src_array,
00089           size_t __element_count, size_t __element_size,
00090           __cxa_cdtor_return_type (*__constructor) (void*, void*),
00091           __cxa_cdtor_type __destructor);
00092 
00093   // Destruct array.
00094   void
00095   __cxa_vec_dtor(void* __array_address, size_t __element_count,
00096          size_t __element_size, __cxa_cdtor_type __destructor);
00097 
00098   void
00099   __cxa_vec_cleanup(void* __array_address, size_t __element_count, size_t __s,
00100             __cxa_cdtor_type __destructor) _GLIBCXX_NOTHROW;
00101 
00102   // Destruct and release array.
00103   void
00104   __cxa_vec_delete(void* __array_address, size_t __element_size,
00105            size_t __padding_size, __cxa_cdtor_type __destructor);
00106 
00107   void
00108   __cxa_vec_delete2(void* __array_address, size_t __element_size,
00109             size_t __padding_size, __cxa_cdtor_type __destructor,
00110             void (*__dealloc) (void*));
00111 
00112   void
00113   __cxa_vec_delete3(void* __array_address, size_t __element_size,
00114             size_t __padding_size, __cxa_cdtor_type __destructor,
00115             void (*__dealloc) (void*, size_t));
00116 
00117   int
00118   __cxa_guard_acquire(__guard*);
00119 
00120   void
00121   __cxa_guard_release(__guard*) _GLIBCXX_NOTHROW;
00122 
00123   void
00124   __cxa_guard_abort(__guard*) _GLIBCXX_NOTHROW;
00125 
00126   // Pure virtual functions.
00127   void
00128   __cxa_pure_virtual(void) __attribute__ ((__noreturn__));
00129 
00130   // Exception handling.
00131   void
00132   __cxa_bad_cast();
00133 
00134   void
00135   __cxa_bad_typeid();
00136 
00137   // DSO destruction.
00138   int
00139   __cxa_atexit(void (*)(void*), void*, void*) _GLIBCXX_NOTHROW;
00140 
00141   int
00142   __cxa_finalize(void*);
00143 
00144 
00145   /**
00146    *  @brief Demangling routine.
00147    *  ABI-mandated entry point in the C++ runtime library for demangling.
00148    *
00149    *  @param __mangled_name A NUL-terminated character string
00150    *  containing the name to be demangled.
00151    *
00152    *  @param __output_buffer A region of memory, allocated with
00153    *  malloc, of @a *__length bytes, into which the demangled name is
00154    *  stored.  If @a __output_buffer is not long enough, it is
00155    *  expanded using realloc.  @a __output_buffer may instead be NULL;
00156    *  in that case, the demangled name is placed in a region of memory
00157    *  allocated with malloc.
00158    *
00159    *  @param __length If @a __length is non-NULL, the length of the
00160    *  buffer containing the demangled name is placed in @a *__length.
00161    *
00162    *  @param __status @a *__status is set to one of the following values:
00163    *   0: The demangling operation succeeded.
00164    *  -1: A memory allocation failure occurred.
00165    *  -2: @a mangled_name is not a valid name under the C++ ABI mangling rules.
00166    *  -3: One of the arguments is invalid.
00167    *
00168    *  @return A pointer to the start of the NUL-terminated demangled
00169    *  name, or NULL if the demangling fails.  The caller is
00170    *  responsible for deallocating this memory using @c free.
00171    *
00172    *  The demangling is performed using the C++ ABI mangling rules,
00173    *  with GNU extensions. For example, this function is used in
00174    *  __gnu_cxx::__verbose_terminate_handler.
00175    *
00176    *  See http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt12ch39.html
00177    *  for other examples of use.
00178    *
00179    *  @note The same demangling functionality is available via
00180    *  libiberty (@c <libiberty/demangle.h> and @c libiberty.a) in GCC
00181    *  3.1 and later, but that requires explicit installation (@c
00182    *  --enable-install-libiberty) and uses a different API, although
00183    *  the ABI is unchanged.
00184    */
00185   char*
00186   __cxa_demangle(const char* __mangled_name, char* __output_buffer,
00187          size_t* __length, int* __status);
00188 #ifdef __cplusplus
00189   }
00190 } // namespace __cxxabiv1
00191 #endif
00192 
00193 #ifdef __cplusplus
00194 
00195 #include <typeinfo>
00196 
00197 namespace __cxxabiv1
00198 {
00199   // Type information for int, float etc.
00200   class __fundamental_type_info : public std::type_info
00201   {
00202   public:
00203     explicit
00204     __fundamental_type_info(const char* __n) : std::type_info(__n) { }
00205 
00206     virtual
00207     ~__fundamental_type_info();
00208   };
00209 
00210   // Type information for array objects.
00211   class __array_type_info : public std::type_info
00212   {
00213   public:
00214     explicit
00215     __array_type_info(const char* __n) : std::type_info(__n) { }
00216 
00217     virtual
00218     ~__array_type_info();
00219   };
00220 
00221   // Type information for functions (both member and non-member).
00222   class __function_type_info : public std::type_info
00223   {
00224   public:
00225     explicit
00226     __function_type_info(const char* __n) : std::type_info(__n) { }
00227 
00228     virtual
00229     ~__function_type_info();
00230 
00231   protected:
00232     // Implementation defined member function.
00233     virtual bool
00234     __is_function_p() const;
00235   };
00236 
00237   // Type information for enumerations.
00238   class __enum_type_info : public std::type_info
00239   {
00240   public:
00241     explicit
00242     __enum_type_info(const char* __n) : std::type_info(__n) { }
00243 
00244     virtual
00245     ~__enum_type_info();
00246   };
00247 
00248   // Common type information for simple pointers and pointers to member.
00249   class __pbase_type_info : public std::type_info
00250   {
00251   public:
00252     unsigned int        __flags; // Qualification of the target object.
00253     const std::type_info*   __pointee; // Type of pointed to object.
00254 
00255     explicit
00256     __pbase_type_info(const char* __n, int __quals,
00257               const std::type_info* __type)
00258     : std::type_info(__n), __flags(__quals), __pointee(__type)
00259     { }
00260 
00261     virtual
00262     ~__pbase_type_info();
00263 
00264     // Implementation defined type.
00265     enum __masks
00266       {
00267     __const_mask = 0x1,
00268     __volatile_mask = 0x2,
00269     __restrict_mask = 0x4,
00270     __incomplete_mask = 0x8,
00271     __incomplete_class_mask = 0x10
00272       };
00273 
00274   protected:
00275     __pbase_type_info(const __pbase_type_info&);
00276 
00277     __pbase_type_info&
00278     operator=(const __pbase_type_info&);
00279 
00280     // Implementation defined member functions.
00281     virtual bool
00282     __do_catch(const std::type_info* __thr_type, void** __thr_obj,
00283            unsigned int __outer) const;
00284 
00285     inline virtual bool
00286     __pointer_catch(const __pbase_type_info* __thr_type, void** __thr_obj,
00287             unsigned __outer) const;
00288   };
00289 
00290   // Type information for simple pointers.
00291   class __pointer_type_info : public __pbase_type_info
00292   {
00293   public:
00294     explicit
00295     __pointer_type_info(const char* __n, int __quals,
00296             const std::type_info* __type)
00297     : __pbase_type_info (__n, __quals, __type) { }
00298 
00299 
00300     virtual
00301     ~__pointer_type_info();
00302 
00303   protected:
00304     // Implementation defined member functions.
00305     virtual bool
00306     __is_pointer_p() const;
00307 
00308     virtual bool
00309     __pointer_catch(const __pbase_type_info* __thr_type, void** __thr_obj,
00310             unsigned __outer) const;
00311   };
00312 
00313   class __class_type_info;
00314 
00315   // Type information for a pointer to member variable.
00316   class __pointer_to_member_type_info : public __pbase_type_info
00317   {
00318   public:
00319     __class_type_info* __context;   // Class of the member.
00320 
00321     explicit
00322     __pointer_to_member_type_info(const char* __n, int __quals,
00323                   const std::type_info* __type,
00324                   __class_type_info* __klass)
00325     : __pbase_type_info(__n, __quals, __type), __context(__klass) { }
00326 
00327     virtual
00328     ~__pointer_to_member_type_info();
00329 
00330   protected:
00331     __pointer_to_member_type_info(const __pointer_to_member_type_info&);
00332 
00333     __pointer_to_member_type_info&
00334     operator=(const __pointer_to_member_type_info&);
00335 
00336     // Implementation defined member function.
00337     virtual bool
00338     __pointer_catch(const __pbase_type_info* __thr_type, void** __thr_obj,
00339             unsigned __outer) const;
00340   };
00341 
00342   // Helper class for __vmi_class_type.
00343   class __base_class_type_info
00344   {
00345   public:
00346     const __class_type_info*    __base_type;  // Base class type.
00347     long            __offset_flags;  // Offset and info.
00348 
00349     enum __offset_flags_masks
00350       {
00351     __virtual_mask = 0x1,
00352     __public_mask = 0x2,
00353     __hwm_bit = 2,
00354     __offset_shift = 8          // Bits to shift offset.
00355       };
00356 
00357     // Implementation defined member functions.
00358     bool
00359     __is_virtual_p() const
00360     { return __offset_flags & __virtual_mask; }
00361 
00362     bool
00363     __is_public_p() const
00364     { return __offset_flags & __public_mask; }
00365 
00366     ptrdiff_t
00367     __offset() const
00368     {
00369       // This shift, being of a signed type, is implementation
00370       // defined. GCC implements such shifts as arithmetic, which is
00371       // what we want.
00372       return static_cast<ptrdiff_t>(__offset_flags) >> __offset_shift;
00373     }
00374   };
00375 
00376   // Type information for a class.
00377   class __class_type_info : public std::type_info
00378   {
00379   public:
00380     explicit
00381     __class_type_info (const char *__n) : type_info(__n) { }
00382 
00383     virtual
00384     ~__class_type_info ();
00385 
00386     // Implementation defined types.
00387     // The type sub_kind tells us about how a base object is contained
00388     // within a derived object. We often do this lazily, hence the
00389     // UNKNOWN value. At other times we may use NOT_CONTAINED to mean
00390     // not publicly contained.
00391     enum __sub_kind
00392       {
00393     // We have no idea.
00394     __unknown = 0,
00395 
00396     // Not contained within us (in some circumstances this might
00397     // mean not contained publicly)
00398     __not_contained,
00399 
00400     // Contained ambiguously.
00401     __contained_ambig,
00402 
00403     // Via a virtual path.
00404     __contained_virtual_mask = __base_class_type_info::__virtual_mask,
00405 
00406     // Via a public path.
00407     __contained_public_mask = __base_class_type_info::__public_mask,
00408 
00409     // Contained within us.
00410     __contained_mask = 1 << __base_class_type_info::__hwm_bit,
00411 
00412     __contained_private = __contained_mask,
00413     __contained_public = __contained_mask | __contained_public_mask
00414       };
00415 
00416     struct __upcast_result;
00417     struct __dyncast_result;
00418 
00419   protected:
00420     // Implementation defined member functions.
00421     virtual bool
00422     __do_upcast(const __class_type_info* __dst_type, void**__obj_ptr) const;
00423 
00424     virtual bool
00425     __do_catch(const type_info* __thr_type, void** __thr_obj,
00426            unsigned __outer) const;
00427 
00428   public:
00429     // Helper for upcast. See if DST is us, or one of our bases.
00430     // Return false if not found, true if found.
00431     virtual bool
00432     __do_upcast(const __class_type_info* __dst, const void* __obj,
00433         __upcast_result& __restrict __result) const;
00434 
00435     // Indicate whether SRC_PTR of type SRC_TYPE is contained publicly
00436     // within OBJ_PTR. OBJ_PTR points to a base object of our type,
00437     // which is the destination type. SRC2DST indicates how SRC
00438     // objects might be contained within this type.  If SRC_PTR is one
00439     // of our SRC_TYPE bases, indicate the virtuality. Returns
00440     // not_contained for non containment or private containment.
00441     inline __sub_kind
00442     __find_public_src(ptrdiff_t __src2dst, const void* __obj_ptr,
00443               const __class_type_info* __src_type,
00444               const void* __src_ptr) const;
00445 
00446     // Helper for dynamic cast. ACCESS_PATH gives the access from the
00447     // most derived object to this base. DST_TYPE indicates the
00448     // desired type we want. OBJ_PTR points to a base of our type
00449     // within the complete object. SRC_TYPE indicates the static type
00450     // started from and SRC_PTR points to that base within the most
00451     // derived object. Fill in RESULT with what we find. Return true
00452     // if we have located an ambiguous match.
00453     virtual bool
00454     __do_dyncast(ptrdiff_t __src2dst, __sub_kind __access_path,
00455          const __class_type_info* __dst_type, const void* __obj_ptr,
00456          const __class_type_info* __src_type, const void* __src_ptr,
00457          __dyncast_result& __result) const;
00458 
00459     // Helper for find_public_subobj. SRC2DST indicates how SRC_TYPE
00460     // bases are inherited by the type started from -- which is not
00461     // necessarily the current type. The current type will be a base
00462     // of the destination type.  OBJ_PTR points to the current base.
00463     virtual __sub_kind
00464     __do_find_public_src(ptrdiff_t __src2dst, const void* __obj_ptr,
00465              const __class_type_info* __src_type,
00466              const void* __src_ptr) const;
00467   };
00468 
00469   // Type information for a class with a single non-virtual base.
00470   class __si_class_type_info : public __class_type_info
00471   {
00472   public:
00473     const __class_type_info* __base_type;
00474 
00475     explicit
00476     __si_class_type_info(const char *__n, const __class_type_info *__base)
00477     : __class_type_info(__n), __base_type(__base) { }
00478 
00479     virtual
00480     ~__si_class_type_info();
00481 
00482   protected:
00483     __si_class_type_info(const __si_class_type_info&);
00484 
00485     __si_class_type_info&
00486     operator=(const __si_class_type_info&);
00487 
00488     // Implementation defined member functions.
00489     virtual bool
00490     __do_dyncast(ptrdiff_t __src2dst, __sub_kind __access_path,
00491          const __class_type_info* __dst_type, const void* __obj_ptr,
00492          const __class_type_info* __src_type, const void* __src_ptr,
00493          __dyncast_result& __result) const;
00494 
00495     virtual __sub_kind
00496     __do_find_public_src(ptrdiff_t __src2dst, const void* __obj_ptr,
00497              const __class_type_info* __src_type,
00498              const void* __sub_ptr) const;
00499 
00500     virtual bool
00501     __do_upcast(const __class_type_info*__dst, const void*__obj,
00502         __upcast_result& __restrict __result) const;
00503   };
00504 
00505   // Type information for a class with multiple and/or virtual bases.
00506   class __vmi_class_type_info : public __class_type_info
00507   {
00508   public:
00509     unsigned int        __flags;  // Details about the class hierarchy.
00510     unsigned int        __base_count;  // Number of direct bases.
00511 
00512     // The array of bases uses the trailing array struct hack so this
00513     // class is not constructable with a normal constructor. It is
00514     // internally generated by the compiler.
00515     __base_class_type_info  __base_info[1];  // Array of bases.
00516 
00517     explicit
00518     __vmi_class_type_info(const char* __n, int ___flags)
00519     : __class_type_info(__n), __flags(___flags), __base_count(0) { }
00520 
00521     virtual
00522     ~__vmi_class_type_info();
00523 
00524     // Implementation defined types.
00525     enum __flags_masks
00526       {
00527     __non_diamond_repeat_mask = 0x1, // Distinct instance of repeated base.
00528     __diamond_shaped_mask = 0x2, // Diamond shaped multiple inheritance.
00529     __flags_unknown_mask = 0x10
00530       };
00531 
00532   protected:
00533     // Implementation defined member functions.
00534     virtual bool
00535     __do_dyncast(ptrdiff_t __src2dst, __sub_kind __access_path,
00536          const __class_type_info* __dst_type, const void* __obj_ptr,
00537          const __class_type_info* __src_type, const void* __src_ptr,
00538          __dyncast_result& __result) const;
00539 
00540     virtual __sub_kind
00541     __do_find_public_src(ptrdiff_t __src2dst, const void* __obj_ptr,
00542              const __class_type_info* __src_type,
00543              const void* __src_ptr) const;
00544 
00545     virtual bool
00546     __do_upcast(const __class_type_info* __dst, const void* __obj,
00547         __upcast_result& __restrict __result) const;
00548   };
00549 
00550   // Dynamic cast runtime.
00551   // src2dst has the following possible values
00552   //  >-1: src_type is a unique public non-virtual base of dst_type
00553   //       dst_ptr + src2dst == src_ptr
00554   //   -1: unspecified relationship
00555   //   -2: src_type is not a public base of dst_type
00556   //   -3: src_type is a multiple public non-virtual base of dst_type
00557   extern "C" void*
00558   __dynamic_cast(const void* __src_ptr, // Starting object.
00559          const __class_type_info* __src_type, // Static type of object.
00560          const __class_type_info* __dst_type, // Desired target type.
00561          ptrdiff_t __src2dst); // How src and dst are related.
00562 
00563 
00564   // Returns the type_info for the currently handled exception [15.3/8], or
00565   // null if there is none.
00566   extern "C" std::type_info*
00567   __cxa_current_exception_type() _GLIBCXX_NOTHROW __attribute__ ((__pure__));
00568 
00569   // A magic placeholder class that can be caught by reference
00570   // to recognize foreign exceptions.
00571   class __foreign_exception
00572   {
00573     virtual ~__foreign_exception() _GLIBCXX_NOTHROW;
00574     virtual void __pure_dummy() = 0; // prevent catch by value
00575   };
00576 
00577 } // namespace __cxxabiv1
00578 
00579 /** @namespace abi
00580  *  @brief The cross-vendor C++ Application Binary Interface. A
00581  *  namespace alias to __cxxabiv1, but user programs should use the
00582  *  alias 'abi'.
00583  *
00584  *  A brief overview of an ABI is given in the libstdc++ FAQ, question
00585  *  5.8 (you may have a copy of the FAQ locally, or you can view the online
00586  *  version at http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#5_8).
00587  *
00588  *  GCC subscribes to a cross-vendor ABI for C++, sometimes
00589  *  called the IA64 ABI because it happens to be the native ABI for that
00590  *  platform.  It is summarized at http://www.codesourcery.com/cxx-abi/
00591  *  along with the current specification.
00592  *
00593  *  For users of GCC greater than or equal to 3.x, entry points are
00594  *  available in <cxxabi.h>, which notes, <em>'It is not normally
00595  *  necessary for user programs to include this header, or use the
00596  *  entry points directly.  However, this header is available should
00597  *  that be needed.'</em>
00598 */
00599 namespace abi = __cxxabiv1;
00600 
00601 namespace __gnu_cxx
00602 {
00603   /**
00604    *  @brief Exception thrown by __cxa_guard_acquire.
00605    *  @ingroup exceptions
00606    *
00607    *  6.7[stmt.dcl]/4: If control re-enters the declaration (recursively)
00608    *  while the object is being initialized, the behavior is undefined.
00609    *
00610    *  Since we already have a library function to handle locking, we might
00611    *  as well check for this situation and throw an exception.
00612    *  We use the second byte of the guard variable to remember that we're
00613    *  in the middle of an initialization.
00614    */
00615   class recursive_init_error: public std::exception
00616   {
00617   public:
00618     recursive_init_error() throw() { }
00619     virtual ~recursive_init_error() throw ();
00620   };
00621 }
00622 #endif // __cplusplus
00623 
00624 #pragma GCC visibility pop
00625 
00626 #endif // __CXXABI_H