Home | History | Annotate | Download | only in include
      1 // Exception Handling support header for -*- C++ -*-
      2 
      3 // Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
      4 // 2004, 2005, 2006, 2007, 2008, 2009
      5 // Free Software Foundation
      6 //
      7 // This file is part of GCC.
      8 //
      9 // GCC is free software; you can redistribute it and/or modify
     10 // it under the terms of the GNU General Public License as published by
     11 // the Free Software Foundation; either version 3, or (at your option)
     12 // any later version.
     13 // 
     14 // GCC is distributed in the hope that it will be useful,
     15 // but WITHOUT ANY WARRANTY; without even the implied warranty of
     16 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     17 // GNU General Public License for more details.
     18 // 
     19 // Under Section 7 of GPL version 3, you are granted additional
     20 // permissions described in the GCC Runtime Library Exception, version
     21 // 3.1, as published by the Free Software Foundation.
     22 
     23 // You should have received a copy of the GNU General Public License and
     24 // a copy of the GCC Runtime Library Exception along with this program;
     25 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
     26 // <http://www.gnu.org/licenses/>.
     27 
     28 /** @file exception
     29  *  This is a Standard C++ Library header.
     30  */
     31 
     32 #ifndef __EXCEPTION__
     33 #define __EXCEPTION__
     34 
     35 #pragma GCC visibility push(default)
     36 
     37 #include <bits/c++config.h>
     38 
     39 extern "C++" {
     40 
     41 namespace std 
     42 {
     43   /**
     44    * @defgroup exceptions Exceptions
     45    * @ingroup diagnostics
     46    *
     47    * Classes and functions for reporting errors via exception classes.
     48    * @{
     49    */
     50 
     51   /**
     52    *  @brief Base class for all library exceptions.
     53    *
     54    *  This is the base class for all exceptions thrown by the standard
     55    *  library, and by certain language expressions.  You are free to derive
     56    *  your own %exception classes, or use a different hierarchy, or to
     57    *  throw non-class data (e.g., fundamental types).
     58    */
     59   class exception 
     60   {
     61   public:
     62     exception() throw() { }
     63     virtual ~exception() throw();
     64 
     65     /** Returns a C-style character string describing the general cause
     66      *  of the current error.  */
     67     virtual const char* what() const throw();
     68   };
     69 
     70   /** If an %exception is thrown which is not listed in a function's
     71    *  %exception specification, one of these may be thrown.  */
     72   class bad_exception : public exception 
     73   {
     74   public:
     75     bad_exception() throw() { }
     76 
     77     // This declaration is not useless:
     78     // http://gcc.gnu.org/onlinedocs/gcc-3.0.2/gcc_6.html#SEC118
     79     virtual ~bad_exception() throw();
     80 
     81     // See comment in eh_exception.cc.
     82     virtual const char* what() const throw();
     83   };
     84 
     85   /// If you write a replacement %terminate handler, it must be of this type.
     86   typedef void (*terminate_handler) ();
     87 
     88   /// If you write a replacement %unexpected handler, it must be of this type.
     89   typedef void (*unexpected_handler) ();
     90 
     91   /// Takes a new handler function as an argument, returns the old function.
     92   terminate_handler set_terminate(terminate_handler) throw();
     93 
     94   /** The runtime will call this function if %exception handling must be
     95    *  abandoned for any reason.  It can also be called by the user.  */
     96   void terminate() __attribute__ ((__noreturn__));
     97 
     98   /// Takes a new handler function as an argument, returns the old function.
     99   unexpected_handler set_unexpected(unexpected_handler) throw();
    100 
    101   /** The runtime will call this function if an %exception is thrown which
    102    *  violates the function's %exception specification.  */
    103   void unexpected() __attribute__ ((__noreturn__));
    104 
    105   /** [18.6.4]/1:  "Returns true after completing evaluation of a
    106    *  throw-expression until either completing initialization of the
    107    *  exception-declaration in the matching handler or entering @c unexpected()
    108    *  due to the throw; or after entering @c terminate() for any reason
    109    *  other than an explicit call to @c terminate().  [Note: This includes
    110    *  stack unwinding [15.2].  end note]"
    111    *
    112    *  2:  "When @c uncaught_exception() is true, throwing an %exception can
    113    *  result in a call of @c terminate() (15.5.1)."
    114    */
    115   bool uncaught_exception() throw();
    116 
    117   // @} group exceptions
    118 } // namespace std
    119 
    120 _GLIBCXX_BEGIN_NAMESPACE(__gnu_cxx)
    121 
    122   /** 
    123    *  @brief A replacement for the standard terminate_handler which
    124    *  prints more information about the terminating exception (if any)
    125    *  on stderr.  
    126    *
    127    *  @ingroup exceptions
    128    *
    129    *  Call
    130    *   @code
    131    *     std::set_terminate(__gnu_cxx::__verbose_terminate_handler)
    132    *   @endcode
    133    *  to use.  For more info, see
    134    *  http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt02ch06s02.html
    135    *
    136    *  In 3.4 and later, this is on by default.
    137    */
    138   void __verbose_terminate_handler();
    139 
    140 _GLIBCXX_END_NAMESPACE
    141   
    142 } // extern "C++"
    143 
    144 #pragma GCC visibility pop
    145 
    146 #if (defined(__GXX_EXPERIMENTAL_CXX0X__) \
    147      && defined(_GLIBCXX_ATOMIC_BUILTINS_4))
    148 #include <exception_ptr.h>
    149 #endif
    150 
    151 #endif
    152