Boost.System: Extensible Error Reporting

Introduction

Error conditions originating from the operating system or other low-level application program interfaces (API’s) are typically reported via an integer representing an error code. When these low-level API calls are wrapped in portable code, such as in a portable library, some users want to deal with the error codes in portable ways. Other users need to get at the system specific error codes, so they can deal with system specific needs. The Boost System library provides simple, light-weight error_code objects that encapsulate system-specific error code values, yet also provide access to more abstract and portable error conditions via error_condition objects.

Because error_code objects can represent errors from sources other than the operating system, including user-defined sources, each error_code and error_condition has an associated error_category.

An exception class, system_error, is provided. Derived from std::runtime_error, it captures the underlying error_code for the problem causing the exception so that this important information is not lost.

While exceptions are the preferred C++ default error code reporting mechanism, users of libraries dependent on low-level API’s often need overloads reporting error conditions via error code arguments and/or return values rather than via throwing exceptions. Otherwise, when errors are not exceptional occurrences and must be dealt with as they arise, programs become littered with try/catch blocks, unreadable, and inefficient. The Boost System library supports both error reporting by exception and by error code.

In addition to portable errors codes and conditions supported by the error_code.hpp header, system-specific headers support the Cygwin, Linux, and Windows platforms. These headers are effectively no-ops if included for platforms other than their intended target.

Boost.System is part of the C++11 Standard Library. A number of changes, particularly to names, were made by the C++ committee during standardization. The Boost implementation has been tracking those changes. See Deprecated Names for synonyms provided to prevent breakage of existing user code.

Revision History

Changes in Boost 1.75

The platform-specific headers windows_error.hpp, linux_error.hpp, and cygwin_error.hpp emit deprecation messages and are slated for removal.
The old names for generic_category() and system_category() emit deprecation messages and are slated for removal.
error_condition::failed is deprecated and is slated for removal. operator bool() for error_condition has been reverted to its old meaning of value() != 0. This is done for compatibility with std::error_condition as the next release is expected to improve interoperability with <system_error> even further. Note that this does not affect error_code::failed, which is still alive and well.
The overload of error_condition::message that takes a buffer is deprecated and is slated for removal, for the same reasons. Note that this does not affect error_code::message.

Changes in Boost 1.74

operator bool() now returns failed() instead of value() != 0.

Changes in Boost 1.69

Boost.System is now header-only. A stub library is still built for compatibility, but linking to it is no longer necessary.
Even more functions have been marked constexpr.
The destructor of error_category is now protected and no longer virtual. This is a potentially breaking change but its impact is expected to be limited.
error_category now has a constructor that accepts a 64 bit identifier, enabling distinct category objects to compare equal.
The constructors of error_category are now protected.
A non-allocating, nonthrowing overload of message has been added.
A virtual function failed has been added, allowing categories for which success is not synonymous with 0.
The deprecated boost::system::throws object has been removed.
boost::throws() is now deprecated and its use is discouraged.
The constructor of system_error taking a single error_code argument is now explicit.
system_error::code() now returns by value.

Changes in Boost 1.68

On a C++14 compiler, many Boost.System functions and member functions are now constexpr, and error_code and error_condition are literal classes.

In addition to enabling use in constant expressions (and constexpr functions), this significantly improves the quality of the generated code.

As a result of this change, however, now using Boost.System from C++14 or C++17 code requires that the library be also built with C++14 or above. This is the default on GCC 6 and newer, but not on GCC 5 or Clang. One can build Boost for C++14 by passing the cxxstd=14 option to b2.

(Previous versions allowed code built against any C++ standard to link with Boost.System built against any C++ standard. In 1.68, code using any C++ standard can link with Boost.System built with C++14 or above, but if Boost.System is built with C++11 or below, only code also built with C++11 and below can link to it successfully.)

Changes in Boost 1.65

On a C++11 compiler, Boost.System now provides implicit conversions from boost::system::error_category, error_code, and error_condition to their standard equivalents from <system_error>.

This allows libraries to expose a C++11 interface and report errors via std::error_code even when using Boost.System, directly or through a dependency such as Boost.ASIO.

Design Rationale

error_code and error_condition are designed as value types so they can be copied without slicing and do not require heap allocation, but still have polymorphic behavior based on the error category. This is achieved by abstract base class error_category supplying the polymorphic behavior, and error_code and error_condition containing a pointer to an object of a type derived from error_category.

Many of the detailed design decisions were driven by the requirements that users to be able to add additional error categories, and that it be no more difficult to write portable code than system-specific code.

The operator<< overload for error_code eliminates a misleading conversion to bool in code like cout << ec, where ec is of type error_code. It is also useful in its own right.

Reference

Use of C++11 and C++14 Features

The library is documented to use several C++11 and C++14 features, including noexcept, explicit conversion operators and constexpr. The actual implementation uses C++11 and C++14 features only when they are available, and otherwise falls back on C++03 features.

Macros

When BOOST_SYSTEM_ENABLE_DEPRECATED is defined, the library provides deprecated features for compatibility. These features are bound to eventually disappear.

When BOOST_SYSTEM_USE_UTF8 is defined, on Windows the library returns UTF-8 messages using code page CP_UTF8 instead of the default CP_ACP. This macro has no effect on POSIX.

Deprecated Names

In the process of adding Boost.System to the C++11 standard library, the C++ committee changed some names. To ease transition, Boost.System deprecates the old names, but will provide them when the macro BOOST_SYSTEM_ENABLE_DEPRECATED is defined.

Old usage, now deprecated Replacement

Old usage, now deprecated	Replacement
`get_generic_category()`	`generic_category()`
`get_system_category()`	`system_category()`
`namespace posix`	`namespace errc`
`namespace posix_error`	`namespace errc`
`get_posix_category()`	`generic_category()`
`posix_category`	`generic_category()`
`errno_ecat`	`generic_category()`
`native_ecat`	`system_category()`

get_generic_category()

generic_category()

get_system_category()

system_category()

namespace posix

namespace errc

namespace posix_error

namespace errc

get_posix_category()

generic_category()

posix_category

generic_category()

errno_ecat

generic_category()

native_ecat

system_category()

<boost/system/error_code.hpp>

Synopsis

namespace boost {
  namespace system {

    class error_category;

    constexpr const error_category & system_category() noexcept;
    constexpr const error_category & generic_category() noexcept;

    class error_code;
    class error_condition;

    // "Concept" helpers

    template<class T>
      struct is_error_code_enum { static const bool value = false; };

    template<class T>
      struct is_error_condition_enum { static const bool value = false; };

    // generic error conditions

    namespace errc {
      enum errc_t
      {
        success = 0,
        address_family_not_supported,   //EAFNOSUPPORT
        address_in_use,                 //EADDRINUSE
        address_not_available,          //EADDRNOTAVAIL
        already_connected,              //EISCONN
        argument_list_too_long,         //E2BIG
        argument_out_of_domain,         //EDOM
        bad_address,                    //EFAULT
        bad_file_descriptor,            //EBADF
        bad_message,                    //EBADMSG
        broken_pipe,                    //EPIPE
        connection_aborted,             //ECONNABORTED
        connection_already_in_progress, //EALREADY
        connection_refused,             //ECONNREFUSED
        connection_reset,               //ECONNRESET
        cross_device_link,              //EXDEV
        destination_address_required,   //EDESTADDRREQ
        device_or_resource_busy,        //EBUSY
        directory_not_empty,            //ENOTEMPTY
        executable_format_error,        //ENOEXEC
        file_exists,                    //EEXIST
        file_too_large,                 //EFBIG
        filename_too_long,              //ENAMETOOLONG
        function_not_supported,         //ENOSYS
        host_unreachable,               //EHOSTUNREACH
        identifier_removed,             //EIDRM
        illegal_byte_sequence,          //EILSEQ
        inappropriate_io_control_operation, //ENOTTY
        interrupted,                    //EINTR
        invalid_argument,               //EINVAL
        invalid_seek,                   //ESPIPE
        io_error,                       //EIO
        is_a_directory,                 //EISDIR
        message_size,                   //EMSGSIZE
        network_down,                   //ENETDOWN
        network_reset,                  //ENETRESET
        network_unreachable,            //ENETUNREACH
        no_buffer_space,                //ENOBUFS
        no_child_process,               //ECHILD
        no_link,                        //ENOLINK
        no_lock_available,              //ENOLCK
        no_message_available,           //ENODATA
        no_message,                     //ENOMSG
        no_protocol_option,             //ENOPROTOOPT
        no_space_on_device,             //ENOSPC
        no_stream_resources,            //ENOSR
        no_such_device_or_address,      //ENXIO
        no_such_device,                 //ENODEV
        no_such_file_or_directory,      //ENOENT
        no_such_process,                //ESRCH
        not_a_directory,                //ENOTDIR
        not_a_socket,                   //ENOTSOCK
        not_a_stream,                   //ENOSTR
        not_connected,                  //ENOTCONN
        not_enough_memory,              //ENOMEM
        not_supported,                  //ENOTSUP
        operation_canceled,             //ECANCELED
        operation_in_progress,          //EINPROGRESS
        operation_not_permitted,        //EPERM
        operation_not_supported,        //EOPNOTSUPP
        operation_would_block,          //EWOULDBLOCK
        owner_dead,                     //EOWNERDEAD
        permission_denied,              //EACCES
        protocol_error,                 //EPROTO
        protocol_not_supported,         //EPROTONOSUPPORT
        read_only_file_system,          //EROFS
        resource_deadlock_would_occur,  //EDEADLK
        resource_unavailable_try_again, //EAGAIN
        result_out_of_range,            //ERANGE
        state_not_recoverable,          //ENOTRECOVERABLE
        stream_timeout,                 //ETIME
        text_file_busy,                 //ETXTBSY
        timed_out,                      //ETIMEDOUT
        too_many_files_open_in_system,  //ENFILE
        too_many_files_open,            //EMFILE
        too_many_links,                 //EMLINK
        too_many_synbolic_link_levels,  //ELOOP
        value_too_large,                //EOVERFLOW
        wrong_protocol_type             //EPROTOTYPE
      };

    } // namespace errc

    template<> struct is_error_condition_enum<errc::errc_t>
      { static const bool value = true; };

    // non-member functions

    constexpr bool operator==( const error_code & lhs,
      const error_code & rhs ) noexcept;
    bool operator==( const error_code & code,
      const error_condition & condition ) noexcept;
    bool operator==( const error_condition & condition,
      const error_code & code ) noexcept;
    constexpr bool operator==( const error_condition & lhs,
      const error_condition & rhs ) noexcept;

    constexpr bool operator!=( const error_code & lhs,
      const error_code & rhs ) noexcept;
    bool operator!=( const error_code & code,
      const error_condition & condition ) noexcept;
    bool operator!=( const error_condition & condition,
      const error_code & code ) noexcept;
    constexpr bool operator!=( const error_condition & lhs,
      const error_condition & rhs ) noexcept;

    constexpr bool operator<( const error_code & lhs,
      const error_code & rhs ) noexcept;
    constexpr bool operator<( const error_condition & lhs,
      const error_condition & rhs ) noexcept;

    constexpr error_code make_error_code( errc::errc_t e ) noexcept;
    constexpr error_condition make_error_condition( errc::errc_t e ) noexcept;

    template <class charT, class traits>
      std::basic_ostream<charT, traits>&
        operator<<( basic_ostream<charT, traits>& os, const error_code & ec );

    std::size_t hash_value( const error_code & ec );

  } // namespace system
} // namespace boost

The value of each errc_t constant is the same as the value of the <cerrno> macro shown in the above synopsis.

Users may specialize is_error_code_enum and is_error_condition_enum templates to indicate that a type is eligible for class error_code and error_condition automatic conversions respectively.

Class error_category

The class error_category defines the 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 Boost.System.

namespace boost {
  namespace system {

    class error_category
    {
    public: // noncopyable

      error_category( error_category const & ) = delete;
      error_category& operator=( error_category const & ) = delete;

    protected:

      ~error_category() = default;

      constexpr error_category() noexcept;
      explicit constexpr error_category( unsigned long long id ) noexcept;

    public:

      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 std::string message( int ev ) const = 0;
      virtual char const * message( int ev, char * buffer, std::size_t len )
        const noexcept;

      virtual bool failed( int ev ) const noexcept;

      constexpr bool operator==( const error_category & rhs ) const noexcept;
      constexpr bool operator!=( const error_category & rhs ) const noexcept;
      constexpr bool operator< ( const error_category & rhs ) const noexcept;

      operator std::error_category const & () const;

    private:

      unsigned long long id_; // exposition only

    };
  }
}

Constructors

constexpr error_category() noexcept;

Effects:

Initializes id_ to 0.

Remarks:

Since equivalence for categories that do not have an identifier is based on comparing object addresses, a user-defined derived category of type C that uses this constructor should ensure that only one object of type C exists in the program.

explicit constexpr error_category( unsigned long long id ) noexcept;

Effects:

Initializes id_ to id.

Remarks:

User-defined derived categories that use this constructor are considered equivalent when their identifiers match. Therefore, those categories may have more than one instance existing in a program, but to minimize the possibility of collision, their identifiers must be randomly chosen (at the time the category is implemented, not at runtime). One way of generating a 64 bit random identifier is https://www.random.org/cgi-bin/randbyte?nbytes=8&format=h.

Virtuals

virtual const char * name() const noexcept = 0;

Returns:

In derived classes, a character literal naming the error category.

virtual error_condition default_error_condition( int ev ) const noexcept;

Returns:
In derived classes, an error condition corresponding to ev. The returned error condition will typically come from the generic category.

In the default implementation, error_condition( ev, *this ).

virtual bool equivalent( int code, const error_condition & condition )
  const noexcept;

Returns:
In derived classes, true when error_code( code, *this ) is equivalent to condition.

In the default implementation, default_error_condition( code ) == condition.

virtual bool equivalent( const error_code & code, int condition )
  const noexcept;

Returns:
In derived classes, true when code is equivalent to error_condition( condition, *this ).

In the default implementation, *this == code.category() && code.value() == condition.

virtual std::string message( int ev ) const = 0;

Returns:

In derived classes, a string that describes the error denoted by ev.

virtual char const * message( int ev, char * buffer, std::size_t len )
  const noexcept;

Effects:
Derived classes should either

return a pointer to a character literal describing the error denoted by ev, or

copy a string describing the error into buffer, truncating it to len-1 characters and storing a null terminator, and return buffer. If len is 0, nothing is copied, but the function still returns buffer. Note that when len is 0, buffer may be nullptr.

The default implementation calls message(ev) and copies the result into buffer, truncating it to len-1 characters and storing a null terminator. If len is 0, copies nothing. Returns buffer. If message(ev) throws an exception, the string "Message text unavailable" is used.
Example:
const char* my_category::message(int ev, char* buffer, size_t len) const noexcept { switch(ev) { case 0: return "no error"; case 1: return "voltage out of range"; case 2: return "impedance mismatch"; case 31: case 32: case 33: std::snprintf(buffer, len, "component %d failure", ev-30); return buffer; default: std::snprintf(buffer, len, "unknown error %d", ev); return buffer; } }

virtual bool failed( int ev ) const noexcept;

Returns:
In derived classes, true when ev represents a failure.

In the default implementation, ev != 0.
Remarks:

All calls to this function with the same ev must return the same value.

Nonvirtuals

constexpr bool operator==( const error_category & rhs ) const noexcept;

Returns:

rhs.id_ == 0? this == &rhs: id_ == rhs.id_.

Remarks:

Two category objects are considered equivalent when they have matching nonzero identifiers, or are the same object.

constexpr bool operator!=( const error_category & rhs ) const noexcept;

Returns:

!( *this == rhs ).

constexpr bool operator< ( const error_category & rhs ) const noexcept;

Returns:
If id_ < rhs.id_, true;

Otherwise, if id_ > rhs.id_, false;

Otherwise, if rhs.id_ != 0, false;

Otherwise, std::less<error_category const *>()( this, &rhs ).

operator std::error_category const & () const;

Returns:

A reference to an std::error_category object corresponding to *this.

Predefined Categories

constexpr const error_category & system_category() noexcept;

Returns:

A reference to an error_category object identifying errors originating from the operating system.

constexpr const error_category & generic_category() noexcept;

Returns:

A reference to an error_category object identifying portable error conditions.

Class error_code

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. It’s an adjunct to error reporting by exception.

namespace boost {
  namespace system {

    class error_code {
    public:

      // constructors:

      constexpr error_code() noexcept;
      constexpr error_code( int val, const error_category & cat ) noexcept;

      template <class ErrorCodeEnum>
        constexpr error_code( ErrorCodeEnum e ) noexcept;

      // modifiers:

      constexpr void assign( int val, const error_category & cat ) noexcept;

      template<typename ErrorCodeEnum>
        constexpr error_code & operator=( ErrorCodeEnum e ) noexcept;

      constexpr void clear() noexcept;

      // observers:

      constexpr int value() const noexcept;
      constexpr const error_category & category() const noexcept;

      error_condition default_error_condition() const noexcept;

      std::string message() const;
      char const * message( char * buffer, std::size_t len ) const noexcept;

      constexpr bool failed() const noexcept;
      constexpr explicit operator bool() const noexcept;

      operator std::error_code() const;

    private: // exposition only

      int val_;
      const error_category * cat_;

    };
  }
}

Constructors

constexpr error_code() noexcept;

Ensures:

val_ == 0; *cat_ == system_category().

constexpr error_code( int val, const error_category & cat ) noexcept;

Ensures:

val_ == val; cat_ == &cat.

template <class ErrorCodeEnum>
  constexpr error_code( ErrorCodeEnum e ) noexcept;

Ensures:

*this == make_error_code( e ).

Remarks:

This constructor is only enabled when is_error_code_enum<ErrorCodeEnum>::value is true.

Modifiers

constexpr void assign( int val, const error_category & cat ) noexcept;

Ensures:

val_ == val; cat_ == &cat.

template<typename ErrorCodeEnum>
  constexpr error_code & operator=( ErrorCodeEnum e ) noexcept;

Ensures:

*this == make_error_code( e ).

Remarks:

This operator is only enabled when is_error_code_enum<ErrorCodeEnum>::value is true.

constexpr void clear() noexcept;

Ensures:

val_ == 0; *cat_ == system_category().

Observers

constexpr int value() const noexcept;

Returns:

val_.

constexpr const error_category & category() const noexcept;

Returns:

*cat_.

error_condition default_error_condition() const noexcept;

Returns:

cat_->default_error_condition( val_ ).

std::string message() const;

Returns:

cat_->message( val_ ).

char const * message( char * buffer, std::size_t len ) const noexcept;

Returns:

cat_->message( val_, buffer, len ).

constexpr bool failed() const noexcept;

Returns:

cat_->failed( val_ ).

constexpr explicit operator bool() const noexcept;

Returns:

failed().

operator std::error_code() const;

Returns:

std::error_code( val_, *cat_ ).

Class error_condition

namespace boost {
  namespace system {

    class error_condition {
    public:

      // constructors:

      constexpr error_condition() noexcept;
      constexpr error_condition( int val, const error_category & cat ) noexcept;

      template <class ErrorConditionEnum>
        constexpr error_condition( ErrorConditionEnum e ) noexcept;

      // modifiers:

      constexpr void assign( int val, const error_category & cat ) noexcept;

      template<typename ErrorConditionEnum>
        constexpr error_condition & operator=( ErrorConditionEnum e ) noexcept;

      constexpr void clear() noexcept;

      // observers:

      constexpr int value() const noexcept;
      constexpr const error_category & category() const noexcept;

      std::string message() const;

      constexpr explicit operator bool() const noexcept;

      operator std::error_condition() const;

      // deprecated members; do not use

      char const * message( char * buffer, std::size_t len ) const noexcept;
      constexpr bool failed() const noexcept;

    private: // exposition only

      int val_;
      const error_category * cat_;

    };
  }
}

Constructors

constexpr error_condition() noexcept;

Ensures:

val_ == 0; *cat_ == generic_category().

constexpr error_condition( int val, const error_category & cat ) noexcept;

Ensures:

val_ == val; cat_ == &cat.

template <class ErrorConditionEnum>
  constexpr error_condition( ErrorConditionEnum e ) noexcept;

Ensures:

*this == make_error_condition( e ).

Remarks:

This constructor is only enabled when is_error_condition_enum<ErrorConditionEnum>::value is true.

Modifiers

constexpr void assign( int val, const error_category & cat ) noexcept;

Ensures:

val_ == val; cat_ == &cat.

template <class ErrorConditionEnum>
  constexpr error_condition & operator=( ErrorConditionEnum e ) noexcept;

Ensures:

*this == make_error_condition( e ).

Remarks:

This operator is only enabled when is_error_condition_enum<ErrorConditionEnum>::value is true.

constexpr void clear() noexcept;

Ensures:

val_ == 0; *cat_ == generic_category().

Observers

constexpr int value() const noexcept;

Returns:

val_.

constexpr const error_category & category() const noexcept;

Returns:

*cat_.

std::string message() const;

Returns:

cat_->message( val_ ).

constexpr explicit operator bool() const noexcept;

Returns:

value() != 0.

operator std::error_condition() const;

Returns:

std::error_condition( val_, *cat_ ).

Deprecated members

char const * message( char * buffer, std::size_t len ) const noexcept;

Returns:

cat_->message( val_, buffer, len ).

Warning

This member function is deprecated and will be removed. This is done for compatibility with std::error_condition as the next release is expected to improve interoperability with <system_error> even further. Note that this does not affect error_code::message.

constexpr bool failed() const noexcept;

Returns:

cat_->failed( val_ ).

Warning

Nonmember functions

constexpr bool operator==( const error_code & lhs,
  const error_code & rhs ) noexcept;
constexpr bool operator==( const error_condition & lhs,
  const error_condition & rhs ) noexcept;

Returns:

lhs.value() == rhs.value() && lhs.category() == rhs.category().

bool operator==( const error_code & code,
  const error_condition & condition ) noexcept;
bool operator==( const error_condition & condition,
  const error_code & code ) noexcept;

Returns:

code.category().equivalent( code.value(), condition ) || condition.category().equivalent( code, condition.value() ).

constexpr bool operator!=( const error_code & lhs,
  const error_code & rhs ) noexcept;
constexpr bool operator!=( const error_condition & lhs,
  const error_condition & rhs ) noexcept;
bool operator!=( const error_code & code,
  const error_condition & condition ) noexcept;
bool operator!=( const error_condition & condition,
  const error_code & code ) noexcept;

Returns:

!( lhs == rhs ).

constexpr bool operator<( const error_code & lhs,
  const error_code & rhs ) noexcept;
constexpr bool operator<( const error_condition & lhs,
  const error_condition & rhs ) noexcept;

Returns:

lhs.category() < rhs.category() || ( lhs.category() == rhs.category() && lhs.value() < rhs.value() ).

constexpr error_code make_error_code( errc::errc_t e ) noexcept;

Returns:

error_code( e, generic_category() ).

constexpr error_condition make_error_condition( errc::errc_t e ) noexcept;

Returns:

error_condition( e, generic_category() ).

template <class charT, class traits>
  std::basic_ostream<charT, traits>&
    operator<<( basic_ostream<charT, traits>& os, const error_code & ec );

Effects:

os << ec.category().name() << ':' << ec.value().

Returns:

os.

std::size_t hash_value( const error_code & ec );

Returns:

A hash value representing ec.

<boost/system/system_error.hpp>

Class system_error

The class system_error describes an exception object used to report errors that have an associated error_code. Such errors typically originate from operating system or other low-level application program interfaces.

namespace boost
{
  namespace system
  {
    class system_error: public std::runtime_error
    {
    public:

      explicit system_error( error_code ec );
      system_error( error_code ec, const char * what_arg );
      system_error( error_code ec, const std::string & what_arg );

      system_error( int ev, const error_category & ecat );
      system_error( int ev, const error_category & ecat,
        const char * what_arg );
      system_error( int ev, const error_category & ecat,
        const std::string & what_arg );

      error_code code() const noexcept;
      const char * what() const noexcept;
    };
  }
}

Constructors

explicit system_error( error_code ec );
system_error( error_code ec, const char * what_arg );
system_error( error_code ec, const std::string & what_arg );

Ensures:

code() == ec.

system_error( int ev, const error_category & ecat,
  const char * what_arg );
system_error( int ev, const error_category & ecat,
  const std::string & what_arg );
system_error( int ev, const error_category & ecat );

Ensures:

code() == error_code( ev, ecat ).

Observers

error_code code() const noexcept;

Returns:

ec or error_code( ev, ecat ), from the constructor, as appropriate.

const char * what() const noexcept;

Returns:

A null-terminated character string incorporating the arguments supplied in the constructor, typically of the form what_arg + ": " + code.message().

History

N1975, Filesystem Library Proposal for TR2, accepted for Library Technical Report 2 (TR2) at the Berlin meeting, included additional components to supplement the Standard Library’s Diagnostics clause. Since then, these error reporting components have received wider public scrutiny and enhancements have been made to the design. The enhanced version has been used by N2054, Networking Library Proposal for TR2, demonstrating that these error reporting components are useful beyond the original Filesystem Library.

The original proposal viewed error categories as a binary choice between errno (i.e. POSIX-style) and the native operating system’s error codes. The proposed components now allow as many additional error categories as are needed by either implementations or by users. The need to support additional error categories, for example, occurs in some networking library implementations because they are built on top of the POSIX getaddrinfo API that uses error codes not based on errno.

Acknowledgments

Christopher Kohlhoff and Peter Dimov made important contributions to the design. Comments and suggestions were also received from Pavel Vozenilek, Gennaro Prota, Dave Abrahams, Jeff Garland, Iain Hanson, Oliver Kowalke, and Oleg Abrosimov. Christopher Kohlhoff suggested several improvements to the N2066 paper. Johan Nilsson’s comments led to several of the refinements in N2066.

Copyright and License

This documentation is

and is distributed under the Boost Software License, Version 1.0.