cxxabi.h

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