libstdc++-v3/libsupc++/cxxabi.h

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