error_code.hpp

Introduction
Synopsis
Class error_category
Members
Class error_code
Members
Non-member functions
Acknowledgments

Introduction

This header provides components used to report errors from the operating system or other low-level application program interface (API). It is based on the Diagnostics portion of the TR2 filesystem proposal.

Class error_code encapsulates an error code, usually one returned by an API. Class error_category encapsulates an identifier for a particular kind of error code. Users or third-parties may add additional error categories.

Builds

The system library is required by default. If the preprocessor macro name BOOST_ERROR_CODE_HEADER_ONLY is defined, no object library or shared/DLL library is required. Only one translation unit may defined BOOST_ERROR_CODE_HEADER_ONLY, otherwise symbols will be multiply defined.

Synopsis

namespace boost
{
  namespace system
  {
    class error_code;

    typedef int         (*errno_decoder)( const error_code & );
    typedef std::string (*message_decoder)( const error_code & );
    typedef wstring_t   (*wmessage_decoder)( const error_code & );

    class error_category : public identifier< uint_least32_t, error_category >
    {
    public:
      error_category();
      explicit error_category( value_type v );
    };

    const error_category  errno_ecat = unspecified-value;
    const error_category  native_ecat = unspecified-value;

    class error_code
    {
    public:
      typedef boost::int_least32_t  value_type;

      // constructors:
      error_code();
      error_code( value_type val, error_category cat );
      void assign(value_type val, error_category cat);

      // observers:
      value_type      value() const;
      error_category  category() const;
      int             to_errno() const;  // name chosen to limit surprises
                                         // see Kohlhoff June 28 '06 boost posting
      std::string     message() const;
      std::wstring    wmessage() const;

      // relationals:
      bool operator==( const error_code & rhs ) const;
      bool operator!=( const error_code & rhs ) const;
      bool operator< ( const error_code & rhs ) const;
      bool operator<=( const error_code & rhs ) const;
      bool operator> ( const error_code & rhs ) const;
      bool operator>=( const error_code & rhs ) const;

      operator unspecified-bool-type() const;
      bool operator!() const;

      // statics:
      static error_category new_category( errno_decoder ed = 0,
        message_decoder md = 0, wmessage_decoder wmd = 0 );
      static bool get_decoders( error_category cat, errno_decoder & ed,
        message_decoder & md,  wmessage_decoder & wmd );

    };

    std::size_t hash_value( const error_code & ec );
    
  } // namespace system
} // namespace boost

Class `error_category`

Class error_category encapsulates an identifier for a particular kind of error code. Users or third-parties may add additional error categories.

For inherited members, see identifier documentation.

Class `error_category` members

error_category();

Effects: Constructs an object of class error_category.

Postcondition: value() == value_type().

explicit error_category( value_type v );

Effects: Constructs an object of class error_category.

Postcondition: value() == v.

Class `error_code`

The value contained by an error_code object is the underlying API error code itself if the API error code type can be stored in value_type without loss of any actual values and if 0 represents no error. Otherwise, the value is an integer that maps to the API error code, with the exact method of mapping unspecified.

Class `error_code` members

error_code();

Effects: Constructs an object of class error_code.

Postcondition: value() == 0 && category() == errno_ecat.

error_code( value_type val, error_category cat );

Effects: Constructs an object of class error_code.

Postcondition: value() == val && category() == cat.

void assign(value_type val, error_category cat);

Postconditions: value() == val && category() == cat.

value_type value() const;

Returns: value() as specified by postconditions of the most recent assign, if any, or of the constructor.

error_category category() const;

Returns: category() as specified by postconditions of the most recent assign, if any, or of the constructor.

int to_errno() const;

Effects: errno_decoder ed; message_decoder md; wmessage_decoder wmd; bool ok( get_decoders( category(), ed, md, wmd ) );

Returns: If ok && ed, ed(*this), otherwise EOTHER.

[Note: The intent is to return the ISO/IEC 9945:2003, Portable Operating System Interface (POSIX) error number that the implementation determines most closely corresponds to value(). --end note.]

std::string message() const;

Effects: errno_decoder ed; message_decoder md; wmessage_decoder wmd; bool ok( get_decoders( category(), ed, md, wmd ) );

Returns: If ok && md, md(*this), otherwise std::string().

Remarks: If category() == errno_ec, the string is as returned by strerror(). Otherwise, the method used by the implementation to determine the string is unspecified.

[Note: The intent is to return a locale sensitive string that describes the error corresponding to value(). --end note.]

wstring_t wmessage() const;

Effects: errno_decoder ed; message_decoder md; wmessage_decoder wmd; bool ok( get_decoders( category(), ed, md, wmd ) );

Returns: If ok && wmd, wmd(*this), otherwise std::wstring().

Remarks: If category() == errno_ec, the string is as returned by strerror(). Otherwise, the method used by the implementation to determine the string is unspecified.

[Note: The intent is to return a locale sensitive string that describes the error corresponding to value(). --end note.]

bool operator==(const error_code & rhs) const;

Returns: value() == rhs.value() && category() == rhs.category().

bool operator!=(const error_code & rhs) const;

Returns: !(*this == rhs).

bool operator<(const error_code & rhs) const;

Returns: category() < rhs.category() || ( category() == rhs.category() && value() < rhs.value() ).

bool operator<=(const error_code & rhs) const;

Returns: *this == rhs || *this < rhs.

bool operator>(const error_code & rhs) const;

Returns: !(*this <= rhs).

bool operator>=(const error_code & rhs) const;

Returns: !(*this < rhs).

operator unspecified-bool-type() const;

Returns: value() != value_type() ? unspecified-bool-type : 0.

Throws: nothing.

[ Note: This conversion can be used in contexts where a bool is expected (e.g., an if condition); however, implicit conversions (e.g., to int) that can occur with bool are not allowed, eliminating some sources of user error. One possible implementation choice for this type is pointer-to-member. —end note ]

bool operator!() const;

Returns: value() == value_type().

static error_category new_category( errno_decoder ed = 0, message_decoder md = 0, wmessage_decoder wmd = 0 );

Effects: Constructs a new error_category object.Creates an association between the object and ed, md, and wmd.

Returns: The object.

static bool get_decoders( error_category cat, errno_decoder & ed, message_decoder & md, wmessage_decoder & wmd );

Effects: If cat was created by new_category(), sets ed, md, and wmd to the respective values associated with cat by new_category(). Otherwise, no effects.

Returns: If cat was created by new_category(), true, otherwise false.

Non-member functions

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

Returns: A hash value representing ec.

Acknowledgements

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.

Last revised: 30 August, 2007

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/ LICENSE_1_0.txt)