C++ Reference ยท Memory and Utilities
C++ std::error_code and std::error_condition
Reference for std::error_code, error_condition, error_category and std::errc: report failures without exceptions and compare them portably.
std::error_code (header <system_error>) is a small value that holds an integer error number together with an error category, the object that knows what the number means and how to turn it into text. It lets functions report failure without throwing, which suits expected failures such as "file not found". The standard filesystem and std::from_chars-style APIs use it, and you can define categories for your own libraries.
std::error_condition is the portable side. It names a failure in platform-independent terms, with the values of std::errc (such as no_such_file_or_directory), and an error_code can be compared to it with ==. std::system_error is the exception that carries an error_code.
std::error_code ec = std::make_error_code(std::errc::invalid_argument); if (ec) { /* a non-zero code means failure */ }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
class error_code { public: error_code() noexcept; // value 0, system_category error_code(int value, const error_category& cat) noexcept; template<class E> error_code(E e) noexcept; // when is_error_code_enum<E> int value() const noexcept; const error_category& category() const noexcept; std::string message() const; explicit operator bool() const noexcept; // value != 0 };
| Name | Description |
|---|---|
value() |
The raw number. Only meaningful together with the category. |
category() |
generic_category(), system_category(), iostream_category(), future_category() or your own. |
message() |
Text from the category; wording is implementation-specific. |
std::errc |
Enum of portable POSIX-style conditions such as invalid_argument, permission_denied, timed_out. |
std::error_condition |
Portable counterpart. ec == std::errc::x compares through the category. |
make_error_code(e) |
Found by argument-dependent lookup; defines how an enum becomes an error_code. |
Errors: std::system_error wraps an error_code for the throwing style: throw std::system_error(ec, "while opening file").
Usage notes
- Zero means success in every category. Test with
if (ec). - Compare with
std::errc, not raw numbers. A WindowsERROR_FILE_NOT_FOUNDand a LinuxENOENTboth compare equal toerrc::no_such_file_or_directory. - Return the code, pass output by reference (or use
std::expected) for non-throwing APIs. The filesystem functions have overloads that takestd::error_code&for this reason. - Category objects are singletons. Two codes are equal only when both the value and the category object match, so return a reference to a function-local static.
- Enable implicit conversion from your enum by specializing
std::is_error_code_enumand providingmake_error_codein the enum's namespace. message()allocates and may throwstd::bad_alloc; do not call it on a hot path.- Not an exception. If a function takes an
error_code&and you ignore it, nothing stops execution.