21 Language support library [language.support]

21.8 Exception handling [support.exception]

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

21.8.1 Header <exception> synopsis [exception.syn]

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].

21.8.2 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;
  };
}
1
#
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.
2
#
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;
3
#
Effects: Constructs an object of class exception.
exception(const exception& rhs) noexcept; exception& operator=(const exception& rhs) noexcept;
4
#
Effects: Copies an exception object.
5
#
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();
6
#
Effects: Destroys an object of class exception.
virtual const char* what() const noexcept;
7
#
Returns: An implementation-defined ntbs.
8
#
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.

21.8.3 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;
    const char* what() const noexcept override;
  };
}
1
#
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;
2
#
Effects: Constructs an object of class bad_­exception.
bad_exception(const bad_exception&) noexcept; bad_exception& operator=(const bad_exception&) noexcept;
3
#
Effects: Copies an object of class bad_­exception.
const char* what() const noexcept override;
4
#
Returns: An implementation-defined ntbs.
5
#
Remarks: The message may be a null-terminated multibyte string ([multibyte.strings]), suitable for conversion and display as a wstring ([string.classes], [locale.codecvt]).

21.8.4 Abnormal termination [exception.terminate]

21.8.4.1 Type terminate_­handler [terminate.handler]

using terminate_handler = void (*)();
1
#
The type of a handler function to be called by std​::​terminate() when terminating exception processing.
2
#
Required behavior: A terminate_­handler shall terminate execution of the program without returning to the caller.
3
#
Default behavior: The implementation's default terminate_­handler calls abort().

21.8.4.2 set_­terminate [set.terminate]

terminate_handler set_terminate(terminate_handler f) noexcept;
1
#
Effects: Establishes the function designated by f as the current handler function for terminating exception processing.
2
#
Remarks: It is unspecified whether a null pointer value designates the default terminate_­handler.
3
#
Returns: The previous terminate_­handler.

21.8.4.3 get_­terminate [get.terminate]

terminate_handler get_terminate() noexcept;
1
#
Returns: The current terminate_­handler.
[ Note
:
This may be a null pointer value.
— end note
 ]

21.8.4.4 terminate [terminate]

[[noreturn]] void terminate() noexcept;
1
#
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.
2
#
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
 ]

21.8.5 uncaught_­exceptions [uncaught.exceptions]

int uncaught_exceptions() noexcept;
1
#
Returns: The number of uncaught exceptions ([except.uncaught]).
2
#
Remarks: When uncaught_­exceptions() > 0, throwing an exception can result in a call of
std​::​terminate() ([except.terminate]).

21.8.6 Exception propagation [propagation]

using exception_ptr = unspecified;
1
#
The type exception_­ptr can be used to refer to an exception object.
2
#
exception_­ptr shall satisfy the requirements of NullablePointer ([nullablepointer.requirements]).
3
#
Two non-null values of type exception_­ptr are equivalent and compare equal if and only if they refer to the same exception.
4
#
The default constructor of exception_­ptr produces the null value of the type.
5
#
exception_­ptr shall not be implicitly convertible to any arithmetic, enumeration, or pointer type.
6
#
[ Note
:
An implementation might use a reference-counted smart pointer as exception_­ptr.
— end note
 ]
7
#
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;
8
#
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);
9
#
Requires: p shall not be a null pointer.
10
#
Throws: The exception object to which p refers.
template<class E> exception_ptr make_exception_ptr(E e) noexcept;
11
#
Effects: Creates an exception_­ptr object that refers to a copy of e, as if: 
try {
  throw e;
} catch(...) {
  return current_exception();
}
12
#
[ Note
:
This function is provided for convenience and efficiency reasons.
— end note
 ]

21.8.7 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;
  };

  template<class T> [[noreturn]] void throw_with_nested(T&& t);
  template <class E> void rethrow_if_nested(const E& e);
}
1
#
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.
2
#
[ 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;
3
#
Effects: The constructor calls current_­exception() and stores the returned value.
[[noreturn]] void rethrow_nested() const;
4
#
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;
5
#
Returns: The stored exception captured by this nested_­exception object.
template <class T> [[noreturn]] void throw_with_nested(T&& t);
6
#
Let U be decay_­t<T>.
7
#
Requires: U shall be CopyConstructible.
8
#
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);
9
#
Effects: If E is not a polymorphic class type, or if nested_­exception is an inaccessible or ambiguous base class of E, there is no effect.
Otherwise, performs: 
if (auto p = dynamic_cast<const nested_exception*>(addressof(e)))
  p->rethrow_nested();