19 Diagnostics library [diagnostics]

19.5 System error support [syserr]

19.5.2 Class error_­category [syserr.errcat]

19.5.2.1 Overview [syserr.errcat.overview]

1
#
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
:
error_­category objects are passed by reference, and two such objects are equal if they have the same address.
This means that applications using custom error_­category types should create a single object of each such type.
— 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.2.2 Virtual members [syserr.errcat.virtuals]

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

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

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

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

🔗
virtual const char* name() const noexcept = 0;
1
#
Returns: A string naming the error category.
🔗
virtual error_condition default_error_condition(int ev) const noexcept;
2
#
Returns: An object of type error_­condition that corresponds to ev.
🔗
virtual bool equivalent(int code, const error_condition& condition) const noexcept;
3
#
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;
4
#
Returns: true if, for the category of error represented by *this, code is considered equivalent to condition; otherwise, false.

19.5.2.5 Error category objects [syserr.errcat.objects]

🔗
const error_category& generic_category() noexcept;
1
#
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.
2
#
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;
3
#
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.
4
#
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 corresponds to a POSIX errno value posv, the function shall return error_­condition(posv, generic_­category()).
Otherwise, the function shall return error_­condition(ev, system_­category()).
What constitutes correspondence for any given operating system is unspecified.
[ Note
:
The number of potential system error codes is large and unbounded, and some may not correspond to any POSIX errno value.
Thus implementations are given latitude in determining correspondence.
— end note
 ]