boost.png (6897 bytes) System Library
Boost Home    Library Home   Tutorial   Reference
Contents
Introduction
Macros
Header <boost/system/error_code.hpp>
Class error_category
   Class error_category synopsis
   Class error_category virtual members
   Class error_category non-virtual members
   Class error_category non-member functions
   Class error_category predefined objects
Class error_code
   Class error_code synopsis
   Class error_code constructors
   Class error_code modifiers
   Class error_code observers
Class error_condition
   Class error_condition synopsis
   Class error_condition constructors
   Class error_condition modifiers
   Class error_condition observers
Non-member functions
Header <boost/system/system_error.hpp>
   Class system_error

Introduction

This reference documentation describes components that  programs may use to report error conditions originating from the operating system or other low-level application program interfaces.

Boost.System library components never change the value of errno.

Macros

Users may defined the following macros if desired. Sensible defaults are provided, so users may ignore these macros if they prefer.

Macro Name Default Effect if defined
BOOST_WINDOWS_API Defined if Windows is detected by Boost.System's automatic configuration code, otherwise not defined. Implementation uses the Microsoft Windows native application program interface (API).
BOOST_POSIX_API Defined if Windows is not detected by Boost.System's automatic configuration code. Implementation uses the POSIX native application program interface (API).
BOOST_SYSTEM_DYN_LINK Defined if BOOST_ALL_DYN_LINK is defined, otherwise not defined. Boost.System library is dynamically linked. If not defined, static linking is assumed.
BOOST_SYSTEM_NO_LIB Defined if BOOST_ALL_NO_LIB is defined, otherwise not defined. Boost.System library does not use the Boost auto-link facility.
BOOST_SYSTEM_NO_DEPRECATED Not defined. Deprecated features are excluded.

Header <boost/system/error_code.hpp>

<boost/system/error_code.hpp> synopsis

namespace boost
{
  namespace system
  {
    class error_category;
    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; };

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

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

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

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

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

    size_t hash_value( const error_code & ec );
  }
}

The value of each errc_t constant shall be 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.

[Note: Classes may be derived from error_category to support additional categories of errors. --end note]

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 the Boost System library. Such classes shall behave as specified in this subclause. [ Note: error_category objects are passed by reference, and two such objects are equal if they have the same address. This means that applications using custom error_category types should create a single object of each such type. —end note ]

Class error_category synopsis

namespace boost
{
  namespace system
  {
    class error_category : public noncopyable
    {
    public:
      virtual ~error_category();

      virtual const char *     name() const = 0;
      virtual string           message( error_code::value_type ev ) const = 0;
      virtual error_condition  default_error_condition( int ev ) const;
      virtual bool             equivalent( int code, const error_condition & condition ) const;
      virtual bool             equivalent( const error_code & code, int condition ) const;

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

    const error_category &  get_system_category();
    const error_category &  get_generic_category();

    static const error_category &  system_category = get_system_category();
    static const error_category &  generic_category = get_generic_category();
  }
}

Class error_category virtual members

Classes derived from error_category shall behave as specified in this subclause.

virtual const char * name() const=0;

Returns: a string naming the error category.

Throws: Nothing.

virtual string message( error_code::value_type ev ) const=0;

Returns: A string that describes the error denoted by ev.

Throws: Nothing.

virtual error_condition default_error_condition( int ev ) const;

Returns:  error_condition( ev, *this ).

 [--Note: Derived classes will typically convert ev to some portable error_category, such as generic_category, and return it as an error_condition for that category. --end note]

Throws: Nothing.

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

Returns: default_error_condition( code ) == condition.

Throws: Nothing.

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

Returns: *this == code.category() && code.value() == condition.

Throws: Nothing.

Class error_category non-virtual members

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

Returns: this == &rhs.

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

Returns: this != &rhs.

bool operator<( const error_category & rhs ) const;

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

[Note: std::less provides a total ordering for pointers. --end note]

Throws: Nothing.

Class error_category non-member functions

const error_category & get_system_category();

Returns: A reference to a error_category object identifying errors originating from the operating system.

Throws: Nothing.

const error_category & get_generic_category();

Returns: A reference to a error_category object identifying portable error conditions.

Throws: Nothing.

Class error_category predefined objects

Predefined objects system_category and generic_category identify operating system error codes and portable error conditions, respectively.

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. [ Note: Class error_code is an adjunct to error reporting by
exception. —end note ]

Class error_code synopsis

namespace boost
{
  namespace system
  {
    class error_code {
    public:

      // constructors:
      error_code();
      error_code( val, const error_category & cat );
      template <class ErrorCodeEnum>
        error_code( errorCodeEnum e,
         typename enable_if<is_error_code_enum<ErrorCodeEnum> >::type* = 0);

      // modifiers:
      void assign( int val, const error_category & cat );
      template<typename ErrorCodeEnum>
        typename enable_if<is_error_code_enum<ErrorCodeEnum>, error_code>::type &
          operator=( ErrorCodeEnum val );;
      void clear();

      // observers:
      int                    value() const;
      cont error_category &  category() const;
      error_condition        default_error_condition() const;
      string                 message() const;
      operator unspecified-bool-type() const;

    private:
      int val_;                     // exposition only
      const error_category & cat_;  // exposition only
    };
  }
}

Class error_code constructors

error_code();

Effects: Constructs an object of type error_code.

Postconditions: val_ == 0 && cat_ == &system_category.

Throws: Nothing.

error_code( int val, const error_category & cat );

Effects: Constructs an object of type error_code.

Postconditions: val_ == val && cat_ == &cat.

Throws: Nothing.

template <class ErrorCodeEnum>
  error_code( errorCodeEnum val,
    typename enable_if<is_error_code_enum<ErrorCodeEnum> >::type* = 0);

Effects: Constructs an object of type error_code.

Postconditions: *this == make_error_code( val ).

Throws: Nothing.

Class error_code modifiers

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

Postconditions: val_ == val && cat_ == cat.

Throws: Nothing.

template<typename ErrorCodeEnum>
  typename enable_if<is_error_code_enum<ErrorCodeEnum>, error_code>::type &
    operator=( ErrorCodeEnum val );

Postconditions: *this == make_error_code( val ).

Throws: Nothing.

void clear();

postcondition: value() == 0 && category() == generic_category

Class error_code observers

int value() const;

Returns: val_.

Throws: Nothing.

error_category category() const;

Returns: cat_.

Throws: Nothing.

error_condition default_error_condition() const;

Returns:  category().default_error_condition( value()).

Throws: Nothing.

string message() const;

Returns:  category().message( value()).

Throws: Nothing.

operator unspecified-bool-type() const;

Returns: if value() != value_type(), returns a value that will evaluate true in a boolean context; otherwise, returns a value that will evaluate false in a boolean context. The value type returned shall not be convertible to int.

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 ]

Class error_condition

The class error_condition describes an object used to hold values identifying error conditions. [ Note: error_condition values are portable abstractions, while error_code values are implementation specific. --end note ]

Class error_condition synopsis

namespace boost
{
  namespace system
  {
    class error_condition
    {
    public:

      // constructors:
      error_condition();
      error_condition( int val, const error_category & cat );
      template <class ErrorConditionEnum>
        error_condition( errorConditionEnum val,
          typename enable_if<is_error_condition_enum<ErrorConditionEnum> >::type* = 0 );

      // modifiers:
      void assign( int val, const error_category & cat );
      template<typename ErrorConditionEnum>
        typename enable_if<is_error_condition_enum<ErrorConditionEnum>, error_code>::type &
          operator=( ErrorConditionEnum val );
      void clear();

      // observers:
      int value() const;
      const error_category & category() const;
      string message() const;
      operator unspecified-bool-type () const;

    private:
      int val_;                     // exposition only
      const error_category & cat_;   // exposition only
    };
  }
}

Class error_condition constructors

error_condition(); 

Effects: Constructs an object of type error_condition.

Postconditions: val_ == 0 and cat_ == generic_category.

Throws: Nothing.

error_condition( value_type val, const error_category & cat );

Effects: Constructs an object of type error_condition.

Postconditions: val_ == val and cat_ == cat.

Throws: Nothing.

template <class ErrorConditionEnum>
  error_condition( errorConditionEnum val,
    typename enable_if<is_error_condition_enum<ErrorConditionEnum> >::type* = 0 );

Effects: Constructs an object of type error_condition.

Postconditions: *this == make_error_condition( val ).

Throws: Nothing.

Class error_condition modifiers

void assign( value_type val, const error_category & cat ); 

Postconditions: val_ == val and cat_ == cat.

Throws: Nothing.

template<typename ErrorConditionEnum>
  typename enable_if<is_error_condition_enum<ErrorConditionEnum>, error_code>::type &
    operator=( ErrorConditionEnum val );

Postconditions: *this == make_error_condition( val ).

Throws: Nothing.

void clear();

postcondition: value() == 0 && category() == generic_category

Class error_condition observers

value_type value() const;

Returns: val_.

Throws: Nothing

const error_category & category() const;

Returns: cat_.

Throws: Nothing.

string message() const;

Returns: category().message( value() ).

Throws: Nothing.

operator unspecified-bool-type () const;

Returns: If value() != 0, returns a value that will evaluate true in a boolean context; otherwise, returns a value that will evaluate false. The return type shall not be convertible to int.

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 ]

Non-member functions

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

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

Throws: Nothing.

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

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

Throws: Nothing.

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

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

Throws: Nothing.

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

Returns: !(lhs == rhs ).

Throws: Nothing.

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

Returns: !( code ==  condition ).

Throws: Nothing.

bool operator!=( const error_condition & lhs, const error_condition & rhs );

Returns: !(lhs == rhs ).

Throws: Nothing.

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

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

Throws: Nothing.

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

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

Throws: Nothing.

error_code make_error_code( errc::errc_t e );

Returns: error_code( e, generic_category).

error_condition make_error_condition( errc::errc_t e );

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.

size_t hash_value( const error_code & ec );

Returns:  A hash value representing ec.

Header <boost/system/system_error.hpp>

Class system_error

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.

namespace boost
{
  namespace system
  {
    class system_error : public std::runtime_error
    {
    public:
      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( error_code::value_type ev, const error_category & ecat,
                    const char * what_arg );
      system_error( error_code::value_type ev, const error_category & ecat,
                    const std::string & what_arg );
      system_error( error_code::value_type ev, const error_category & ecat);

      const error_code & code() const throw();
      const char *       what() const throw();
    };
  }
}
system_error( error_code ec );

Effects: Constructs an object of class system_error.

Postcondition: code() == ec
  && std::strcmp( this->runtime_error::what(), "" ) == 0

system_error( error_code ec, const char * what_arg );

Effects: Constructs an object of class system_error.

Postcondition: code() == ec
  && std::strcmp( this->runtime_error::what(), what_arg ) == 0

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

Effects: Constructs an object of class system_error.

Postcondition: code() == ec
  && std::strcmp( this->runtime_error::what(), what_arg.c_str() ) == 0

system_error( error_code::value_type ev, const error_category & ecat,
             const char * what_arg );

Effects: Constructs an object of class system_error.

Postcondition: code() == error_code( ev, ecat )
  && std::strcmp( this->runtime_error::what(), what_arg ) == 0

system_error( error_code::value_type ev, const error_category & ecat,
             const std::string & what_arg );

Effects: Constructs an object of class system_error.

Postcondition: code() == error_code( ev, ecat )
  && std::strcmp( this->runtime_error::what(), what_arg.c_str() ) == 0

system_error( error_code::value_type ev, const error_category & ecat );

Effects: Constructs an object of class system_error.

Postcondition: code() == error_code( ev, ecat )
  && std::strcmp( this->runtime_error::what(), "" ) == 0

const error_code & code() const;

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

const char * what() const;

Returns: A string incorporating this->runtime_error::what() and code.message().


© Copyright Beman Dawes, 2006, 2007
Distributed under the Boost Software License, Version 1.0. See www.boost.org/LICENSE_1_0.txt

Revised June 25, 2008