The header <exception> defines several types and functions related to the handling of exceptions in a C++ program.
namespace std {
class exception;
class bad_exception;
class nested_exception;
using terminate_handler = void (*)();
terminate_handler get_terminate() noexcept;
terminate_handler set_terminate(terminate_handler f) noexcept;
[[noreturn]] void terminate() noexcept;
int uncaught_exceptions() noexcept;
using exception_ptr = unspecified;
exception_ptr current_exception() noexcept;
[[noreturn]] void rethrow_exception(exception_ptr p);
template<class E> exception_ptr make_exception_ptr(E e) noexcept;
template <class T> [[noreturn]] void throw_with_nested(T&& t);
template <class E> void rethrow_if_nested(const E& e);
}See also: [except.special].
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;
exception(const exception& rhs) noexcept;
exception& operator=(const exception& rhs) noexcept;
Postconditions: If *this and rhs both have dynamic type exception then the value of the expression strcmp(what(), rhs.what()) shall equal 0.
virtual ~exception();
virtual const char* what() const noexcept;
Remarks: The message may be a null-terminated multibyte string, 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.
namespace std {
class bad_exception : public exception {
public:
bad_exception() noexcept;
bad_exception(const bad_exception&) noexcept;
bad_exception& operator=(const bad_exception&) noexcept;
const char* what() const noexcept override;
};
}The class bad_exception defines the type of the object referenced by the exception_ptr returned from a call to current_exception ([propagation]) when the currently active exception object fails to copy.
bad_exception() noexcept;
bad_exception(const bad_exception&) noexcept;
bad_exception& operator=(const bad_exception&) noexcept;
const char* what() const noexcept override;
Remarks: The message may be a null-terminated multibyte string, suitable for conversion and display as a wstring ([string.classes], [locale.codecvt]).
using terminate_handler = void (*)();
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.
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.
terminate_handler get_terminate() noexcept;
[[noreturn]] void terminate() noexcept;
Remarks: Called by the implementation when exception handling must be abandoned for any of several reasons ([except.terminate]). May also be called directly by the program.
Effects: Calls a terminate_handler function. It is unspecified which terminate_handler function will be called if an exception is active during a call to set_terminate. Otherwise calls the current terminate_handler function. [ Note: A default terminate_handler is always considered a callable handler in this context. — end note ]
int uncaught_exceptions() noexcept;
Returns: The number of uncaught exceptions.
Remarks: When uncaught_exceptions() > 0, throwing an exception can result in a call of std::terminate().
using exception_ptr = unspecified;
exception_ptr shall satisfy the requirements of NullablePointer.
Two non-null values of type exception_ptr are equivalent and compare equal if and only if they refer to the same exception.
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 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);
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();
}
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;
};
template<class T> [[noreturn]] 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;
[[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;
template <class T> [[noreturn]] void throw_with_nested(T&& t);
Throws: If is_class_v<U> && !is_final_v<U> && !is_base_of_v<nested_exception, U> is true, 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);