18 Language support library [language.support]

18.8 Exception handling [support.exception]

The header <exception> defines several types and functions related to the handling of exceptions in a C++ program.

Header <exception> synopsis

namespace std {
  class exception;
  class bad_exception;
  class nested_exception;

  typedef void (*unexpected_handler)();
  unexpected_handler get_unexpected() noexcept;
  unexpected_handler set_unexpected(unexpected_handler f) noexcept;
  [[noreturn]] void unexpected();

  typedef void (*terminate_handler)();
  terminate_handler get_terminate() noexcept;
  terminate_handler set_terminate(terminate_handler f) noexcept;
  [[noreturn]] void terminate() noexcept;

  bool uncaught_exception() noexcept;

  typedef unspecified exception_ptr;

  exception_ptr current_exception() noexcept;
  [[noreturn]] void rethrow_exception(exception_ptr p);
  template<class E> exception_ptr make_exception_ptr(E e) noexcept;

  [[noreturn]] template <class T> void throw_with_nested(T&& t);
  template <class E> void rethrow_if_nested(const E& e);
}

See also: [except.special].

18.8.1 Class exception [exception]

namespace std {
  class exception {
  public:
    exception() noexcept;
    exception(const exception&) noexcept;
    exception& operator=(const exception&) noexcept;
    virtual ~exception();
    virtual const char* what() const noexcept;
  };
}

The class exception defines the base class for the types of objects thrown as exceptions by C++ standard library components, and certain expressions, to report errors detected during program execution.

Each standard library class T that derives from class exception shall have a publicly accessible copy constructor and a publicly accessible copy assignment operator that do not exit with an exception. These member functions shall meet the following postcondition: If two objects lhs and rhs both have dynamic type T and lhs is a copy of rhs, then strcmp(lhs.what(), rhs.what()) shall equal 0.

exception() noexcept;

Effects: Constructs an object of class exception.

Remarks: Does not throw any exceptions.

exception(const exception& rhs) noexcept; exception& operator=(const exception& rhs) noexcept;

Effects: Copies an exception object.

Postcondition: If *this and rhs both have dynamic type exception then strcmp(what(), rhs.what()) shall equal 0.

virtual ~exception();

Effects: Destroys an object of class exception.

Remarks: Does not throw any exceptions.

virtual const char* what() const noexcept;

Returns: An implementation-defined ntbs.

Remarks: The message may be a null-terminated multibyte string ([multibyte.strings]), suitable for conversion and display as a wstring ([string.classes], [locale.codecvt]). The return value remains valid until the exception object from which it is obtained is destroyed or a non-const member function of the exception object is called.

18.8.2 Class bad_exception [bad.exception]

namespace std {
  class bad_exception : public exception {
  public:
    bad_exception() noexcept;
    bad_exception(const bad_exception&) noexcept;
    bad_exception& operator=(const bad_exception&) noexcept;
    virtual const char* what() const noexcept;
  };
}

The class bad_exception defines the type of objects thrown as described in ([except.unexpected]).

bad_exception() noexcept;

Effects: Constructs an object of class bad_exception.

Remarks: The result of calling what() on the newly constructed object is implementation-defined.

bad_exception(const bad_exception&) noexcept; bad_exception& operator=(const bad_exception&) noexcept;

Effects: Copies an object of class bad_exception.

virtual const char* what() const noexcept;

Returns: An implementation-defined ntbs.

Remarks: The message may be a null-terminated multibyte string ([multibyte.strings]), suitable for conversion and display as a wstring ([string.classes], [locale.codecvt]).

18.8.3 Abnormal termination [exception.terminate]

18.8.3.1 Type terminate_handler [terminate.handler]

typedef void (*terminate_handler)();

The type of a handler function to be called by std::terminate() when terminating exception processing.

Required behavior: A terminate_handler shall terminate execution of the program without returning to the caller.

Default behavior: The implementation's default terminate_handler calls abort().

18.8.3.2 set_terminate [set.terminate]

terminate_handler set_terminate(terminate_handler f) noexcept;

Effects: Establishes the function designated by f as the current handler function for terminating exception processing.

Remarks: It is unspecified whether a null pointer value designates the default terminate_handler.

Returns: The previous terminate_handler.

18.8.3.3 get_terminate [get.terminate]

terminate_handler get_terminate() noexcept;

Returns: The current terminate_handler. [ Note: This may be a null pointer value.  — end note ]

18.8.3.4 terminate [terminate]

[[noreturn]] void terminate() noexcept;

Remarks: Called by the implementation when exception handling must be abandoned for any of several reasons ([except.terminate]), in effect immediately after evaluating the throw-expression ([terminate.handler]). May also be called directly by the program.

Effects: Calls the current terminate_handler function. [ Note: A default terminate_handler is always considered a callable handler in this context.  — end note ]

18.8.4 uncaught_exception [uncaught]

bool uncaught_exception() noexcept;

Returns: true after the current thread has initialized an exception object ([except.throw]) until a handler for the exception (including std::unexpected() or std::terminate()) is activated ([except.handle]). [ Note: This includes stack unwinding ([except.ctor]).  — end note ]

Remarks: When uncaught_exception() returns true, throwing an exception can result in a call of std::terminate() ([except.terminate]).

18.8.5 Exception propagation [propagation]

typedef unspecified exception_ptr;

The type exception_ptr can be used to refer to an exception object.

exception_ptr shall satisfy the requirements of NullablePointer ([nullablepointer.requirements]).

Two non-null values of type exception_ptr are equivalent and compare equal if and only if they refer to the same exception.

The default constructor of exception_ptr produces the null value of the type.

exception_ptr shall not be implicitly convertible to any arithmetic, enumeration, or pointer type.

Note: An implementation might use a reference-counted smart pointer as exception_ptr.  — end note ]

For purposes of determining the presence of a data race, operations on exception_ptr objects shall access and modify only the exception_ptr objects themselves and not the exceptions they refer to. Use of rethrow_exception on exception_ptr objects that refer to the same exception object shall not introduce a data race. [ Note: if rethrow_exception rethrows the same exception object (rather than a copy), concurrent access to that rethrown exception object may introduce a data race. Changes in the number of exception_ptr objects that refer to a particular exception do not introduce a data race.  — end note ]

exception_ptr current_exception() noexcept;

Returns: An exception_ptr object that refers to the currently handled exception ([except.handle]) or a copy of the currently handled exception, or a null exception_ptr object if no exception is being handled. The referenced object shall remain valid at least as long as there is an exception_ptr object that refers to it. If the function needs to allocate memory and the attempt fails, it returns an exception_ptr object that refers to an instance of bad_alloc. It is unspecified whether the return values of two successive calls to current_exception refer to the same exception object. [ Note: That is, it is unspecified whether current_exception creates a new copy each time it is called.  — end note ] If the attempt to copy the current exception object throws an exception, the function returns an exception_ptr object that refers to the thrown exception or, if this is not possible, to an instance of bad_exception. [ Note: The copy constructor of the thrown exception may also fail, so the implementation is allowed to substitute a bad_exception object to avoid infinite recursion. — end note ]

[[noreturn]] void rethrow_exception(exception_ptr p);

Requires: p shall not be a null pointer.

Throws: the exception object to which p refers.

template<class E> exception_ptr make_exception_ptr(E e) noexcept;

Effects: Creates an exception_ptr object that refers to a copy of e, as if

try {
  throw e;
} catch(...) {
  return current_exception();
}

Note: This function is provided for convenience and efficiency reasons.  — end note ]

18.8.6 nested_exception [except.nested]

namespace std {
  class nested_exception {
  public:
    nested_exception() noexcept;
    nested_exception(const nested_exception&) noexcept = default;
    nested_exception& operator=(const nested_exception&) noexcept = default;
    virtual ~nested_exception() = default;

    // access functions
    [[noreturn]] void rethrow_nested() const;
    exception_ptr nested_ptr() const noexcept;
  };

  [[noreturn]] template<class T> void throw_with_nested(T&& t);
  template <class E> void rethrow_if_nested(const E& e);
}

The class nested_exception is designed for use as a mixin through multiple inheritance. It captures the currently handled exception and stores it for later use.

Note: nested_exception has a virtual destructor to make it a polymorphic class. Its presence can be tested for with dynamic_cast.  — end note ]

nested_exception() noexcept;

Effects: The constructor calls current_exception() and stores the returned value.

[[noreturn]] void rethrow_nested() const;

Effects: If nested_ptr() returns a null pointer, the function calls std::terminate(). Otherwise, it throws the stored exception captured by *this.

exception_ptr nested_ptr() const noexcept;

Returns: The stored exception captured by this nested_exception object.

[[noreturn]] template <class T> void throw_with_nested(T&& t);

Let U be remove_reference<T>::type.

Requires: U shall be CopyConstructible.

Throws: if U is a non-union class type not derived from nested_exception, an exception of unspecified type that is publicly derived from both U and nested_exception and constructed from std::forward<T>(t), otherwise std::forward<T>(t).

template <class E> void rethrow_if_nested(const E& e);

Effects: If the dynamic type of e is publicly and unambiguously derived from nested_exception, calls dynamic_cast<const nested_exception&>(e).rethrow_nested().