[syserr] (original) (raw)
19 Diagnostics library [diagnostics]
19.5 System error support [syserr]
19.5.1 General [syserr.general]
Subclause [syserr] describes components that the standard library and C++ programs may use to report error conditions originating from the operating system or other low-level application program interfaces.
Components described in [syserr] do not change the value oferrno ([errno]).
Recommended practice: Implementations should leave the error states provided by other libraries unchanged.
19.5.2 Header <system_error> synopsis [system.error.syn]
The value of each enum errc enumerator is the same as the value of the macro shown in the above synopsis.
Whether or not the implementation exposes the macros is unspecified.
The is_error_code_enum and is_error_condition_enum templates may be specialized for program-defined types to indicate that such types are eligible for class error_code and class error_condition implicit conversions, respectively.
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 falseeven 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;
strong_ordering operator<=>(const error_category& rhs) const noexcept;
Returns: compare_three_way()(this, &rhs).
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_conditionvirtual 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_]
19.5.4 Class error_code [syserr.errcode]
19.5.4.1 Overview [syserr.errcode.overview]
The class error_code describes an object used to hold error code values, such as those originating from the operating system or other low-level application program interfaces.
[Note 1:
Class error_code is an adjunct to error reporting by exception.
— _end note_]
namespace std { class error_code { public: error_code() noexcept; error_code(int val, const error_category& cat) noexcept;template<class ErrorCodeEnum> error_code(ErrorCodeEnum e) noexcept;void assign(int val, const error_category& cat) noexcept;template<class ErrorCodeEnum> error_code& operator=(ErrorCodeEnum e) noexcept;void clear() noexcept;int value() const noexcept;const error_category& category() const noexcept; error_condition default_error_condition() const noexcept; string message() const;explicit operator bool() const noexcept;private: int val_; const error_category* cat_; }; error_code make_error_code(errc e) noexcept;template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const error_code& ec);}
19.5.4.2 Constructors [syserr.errcode.constructors]
Effects: Initializes val_ with 0and cat_ with &system_category().
error_code(int val, const error_category& cat) noexcept;
Effects: Initializes val_ with valand cat_ with &cat.
template<class ErrorCodeEnum> error_code(ErrorCodeEnum e) noexcept;
Constraints: is_error_code_enum_v<ErrorCodeEnum> is true.
Effects: Equivalent to:error_code ec = make_error_code(e); assign(ec.value(), ec.category());
19.5.4.3 Modifiers [syserr.errcode.modifiers]
void assign(int val, const error_category& cat) noexcept;
Postconditions: val_ == val and cat_ == &cat.
template<class ErrorCodeEnum> error_code& operator=(ErrorCodeEnum e) noexcept;
Constraints: is_error_code_enum_v<ErrorCodeEnum> is true.
Effects: Equivalent to:error_code ec = make_error_code(e); assign(ec.value(), ec.category());
Postconditions: value() == 0 and category() == system_category().
19.5.4.4 Observers [syserr.errcode.observers]
int value() const noexcept;
const error_category& category() const noexcept;
error_condition default_error_condition() const noexcept;
Returns: category().default_error_condition(value()).
Returns: category().message(value()).
explicit operator bool() const noexcept;
19.5.4.5 Non-member functions [syserr.errcode.nonmembers]
error_code make_error_code(errc e) noexcept;
Returns: error_code(static_cast<int>(e), generic_category()).
template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const error_code& ec);
Effects: Equivalent to: return os << ec.category().name() << ':' << ec.value();
19.5.5 Class error_condition [syserr.errcondition]
19.5.5.1 Overview [syserr.errcondition.overview]
The class error_condition describes an object used to hold values identifying error conditions.
[Note 1:
error_condition values are portable abstractions, while error_code values ([syserr.errcode]) are implementation specific.
— _end note_]
namespace std { class error_condition { public: error_condition() noexcept; error_condition(int val, const error_category& cat) noexcept;template<class ErrorConditionEnum> error_condition(ErrorConditionEnum e) noexcept;void assign(int val, const error_category& cat) noexcept;template<class ErrorConditionEnum> error_condition& operator=(ErrorConditionEnum e) noexcept;void clear() noexcept;int value() const noexcept;const error_category& category() const noexcept; string message() const;explicit operator bool() const noexcept;private: int val_; const error_category* cat_; };}
19.5.5.2 Constructors [syserr.errcondition.constructors]
error_condition() noexcept;
Effects: Initializes val_ with 0and cat_ with &generic_category().
error_condition(int val, const error_category& cat) noexcept;
Effects: Initializes val_ with valand cat_ with &cat.
template<class ErrorConditionEnum> error_condition(ErrorConditionEnum e) noexcept;
Constraints: is_error_condition_enum_v<ErrorConditionEnum> is true.
Effects: Equivalent to:error_condition ec = make_error_condition(e); assign(ec.value(), ec.category());
19.5.5.3 Modifiers [syserr.errcondition.modifiers]
void assign(int val, const error_category& cat) noexcept;
Postconditions: val_ == val and cat_ == &cat.
template<class ErrorConditionEnum> error_condition& operator=(ErrorConditionEnum e) noexcept;
Constraints: is_error_condition_enum_v<ErrorConditionEnum> is true.
Effects: Equivalent to:error_condition ec = make_error_condition(e); assign(ec.value(), ec.category());
Postconditions: value() == 0 and category() == generic_category().
19.5.5.4 Observers [syserr.errcondition.observers]
int value() const noexcept;
const error_category& category() const noexcept;
Returns: category().message(value()).
explicit operator bool() const noexcept;
19.5.5.5 Non-member functions [syserr.errcondition.nonmembers]
error_condition make_error_condition(errc e) noexcept;
Returns: error_condition(static_cast<int>(e), generic_category()).
19.5.6 Comparison operator functions [syserr.compare]
bool operator==(const error_code& lhs, const error_code& rhs) noexcept;
Returns: lhs.category() == rhs.category() && lhs.value() == rhs.value()
bool operator==(const error_code& lhs, const error_condition& rhs) noexcept;
Returns: lhs.category().equivalent(lhs.value(), rhs) || rhs.category().equivalent(lhs, rhs.value())
bool operator==(const error_condition& lhs, const error_condition& rhs) noexcept;
Returns: lhs.category() == rhs.category() && lhs.value() == rhs.value()
strong_ordering operator<=>(const error_code& lhs, const error_code& rhs) noexcept;
Effects: Equivalent to:if (auto c = lhs.category() <=> rhs.category(); c != 0) return c;return lhs.value() <=> rhs.value();
strong_ordering operator<=>(const error_condition& lhs, const error_condition& rhs) noexcept;
Returns: if (auto c = lhs.category() <=> rhs.category(); c != 0) return c;return lhs.value() <=> rhs.value();
19.5.7 System error hash support [syserr.hash]
template<> struct hash<error_code>;template<> struct hash<error_condition>;
19.5.8 Class system_error [syserr.syserr]
19.5.8.1 Overview [syserr.syserr.overview]
The class system_error describes an exception object used to report error conditions that have an associated error code.
Such error conditions typically originate from the operating system or other low-level application program interfaces.
[Note 1:
If an error represents an out-of-memory condition, implementations are encouraged to throw an exception object of type bad_alloc rather than system_error.
— _end note_]
namespace std { class system_error : public runtime_error { public: system_error(error_code ec, const string& what_arg); system_error(error_code ec, const char* what_arg); system_error(error_code ec); system_error(int ev, const error_category& ecat, const string& what_arg); system_error(int ev, const error_category& ecat, const char* what_arg); system_error(int ev, const error_category& ecat);const error_code& code() const noexcept;const char* what() const noexcept override;};}
19.5.8.2 Members [syserr.syserr.members]
system_error(error_code ec, const string& what_arg);
Postconditions: code() == ec and
string_view(what()).find(what_arg.c_str()) != string_view::npos.
system_error(error_code ec, const char* what_arg);
Postconditions: code() == ec andstring_view(what()).find(what_arg) != string_view::npos.
system_error(error_code ec);
Postconditions: code() == ec.
system_error(int ev, const error_category& ecat, const string& what_arg);
Postconditions: code() == error_code(ev, ecat) and
string_view(what()).find(what_arg.c_str()) != string_view::npos.
system_error(int ev, const error_category& ecat, const char* what_arg);
Postconditions: code() == error_code(ev, ecat) and
string_view(what()).find(what_arg) != string_view::npos.
system_error(int ev, const error_category& ecat);
Postconditions: code() == error_code(ev, ecat).
const error_code& code() const noexcept;
Returns: ec or error_code(ev, ecat), from the constructor, as appropriate.
const char* what() const noexcept override;
Returns: An ntbs incorporating the arguments supplied in the constructor.
[Note 1:
The returned ntbs might be the contents of what_arg + ": " +code.message().
— _end note_]