Skip to content
Tutorials Center
My learning

Topics

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.

C++
std::error_code ec = std::make_error_code(std::errc::invalid_argument);
if (ec) { /* a non-zero code means failure */ }

Try it

C++ Codes, categories and conditions

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.

C++ A custom error category

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

C++
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 Windows ERROR_FILE_NOT_FOUND and a Linux ENOENT both compare equal to errc::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 take std::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_enum and providing make_error_code in the enum's namespace.
  • message() allocates and may throw std::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.