19 Diagnostics library [diagnostics]

19.5 System error support [syserr]

19.5.3 Class error_­category [syserr.errcat]

19.5.3.1 Overview [syserr.errcat.overview]

The class error_­category serves as a base class for types used to identify the source and encoding of a particular category of error code.
Classes may be derived from error_­category to support categories of errors in addition to those defined in this document.
Such classes shall behave as specified in subclause [syserr.errcat].
[Note 1:
error_­category objects are passed by reference, and two such objects are equal if they have the same address.
If there is more than a single object of a custom error_­category type, such equality comparisons can evaluate to false even for objects holding the same value.
— end note]
namespace std { class error_category { public: constexpr error_category() noexcept; virtual ~error_category(); error_category(const error_category&) = delete; error_category& operator=(const error_category&) = delete; virtual const char* name() const noexcept = 0; virtual error_condition default_error_condition(int ev) const noexcept; virtual bool equivalent(int code, const error_condition& condition) const noexcept; virtual bool equivalent(const error_code& code, int condition) const noexcept; virtual string message(int ev) const = 0; bool operator==(const error_category& rhs) const noexcept; strong_ordering operator<=>(const error_category& rhs) const noexcept; }; const error_category& generic_category() noexcept; const error_category& system_category() noexcept; }

19.5.3.2 Virtual members [syserr.errcat.virtuals]

virtual const char* name() const noexcept = 0;
Returns: A string naming the error category.
virtual error_condition default_error_condition(int ev) const noexcept;
Returns: error_­condition(ev, *this).
virtual bool equivalent(int code, const error_condition& condition) const noexcept;
Returns: default_­error_­condition(code) == condition.
virtual bool equivalent(const error_code& code, int condition) const noexcept;
Returns: *this == code.category() && code.value() == condition.
virtual string message(int ev) const = 0;
Returns: A string that describes the error condition denoted by ev.

19.5.3.3 Non-virtual members [syserr.errcat.nonvirtuals]

bool operator==(const error_category& rhs) const noexcept;
Returns: this == &rhs.
strong_ordering operator<=>(const error_category& rhs) const noexcept;
Returns: compare_­three_­way()(this, &rhs).
[Note 1:
compare_­three_­way ([comparisons.three.way]) provides a total ordering for pointers.
— end note]

19.5.3.4 Program-defined classes derived from error_­category [syserr.errcat.derived]

virtual const char* name() const noexcept = 0;
Returns: A string naming the error category.
virtual error_condition default_error_condition(int ev) const noexcept;
Returns: An object of type error_­condition that corresponds to ev.
virtual bool equivalent(int code, const error_condition& condition) const noexcept;
Returns: true if, for the category of error represented by *this, code is considered equivalent to condition; otherwise, false.
virtual bool equivalent(const error_code& code, int condition) const noexcept;
Returns: true if, for the category of error represented by *this, code is considered equivalent to condition; otherwise, false.

19.5.3.5 Error category objects [syserr.errcat.objects]

const error_category& generic_category() noexcept;
Returns: A reference to an object of a type derived from class error_­category.
All calls to this function shall return references to the same object.
Remarks: The object's default_­error_­condition and equivalent virtual functions shall behave as specified for the class error_­category.
The object's name virtual function shall return a pointer to the string "generic".
const error_category& system_category() noexcept;
Returns: A reference to an object of a type derived from class error_­category.
All calls to this function shall return references to the same object.
Remarks: The object's equivalent virtual functions shall behave as specified for class error_­category.
The object's name virtual function shall return a pointer to the string "system".
The object's default_­error_­condition virtual function shall behave as follows:
If the argument ev is equal to 0, the function returns error_­condition(0, generic_­category()).
Otherwise, if ev corresponds to a POSIX errno value pxv, the function returns error_­condition(pxv, generic_­category()).
Otherwise, the function returns error_­condition(ev, system_­category()).
What constitutes correspondence for any given operating system is unspecified.
[Note 1:
The number of potential system error codes is large and unbounded, and some might not correspond to any POSIX errno value.
Thus implementations are given latitude in determining correspondence.
— end note]