System Library

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.

System Library components do not change the value of errno.

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; };

    //  portable error_conditions
    namespace posix
    {
      enum posix_errno
      {
        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 posix

    template<> struct is_error_condition_enum<posix::posix_errno>
      { 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( posix::posix_errno e );
    error_condition make_error_condition( posix::posix_errno 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 posix_errno 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;
    };

    extern const error_category & posix_category;
    extern const error_category & system_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 posix_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 predefined objects

Predefined objects posix_category and system_category identify portable error conditions and system error codes, 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() == posix_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_ == posix_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() == posix_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( posix::posix_errno e );

Returns: error_code( e, posix_category).

error_condition make_error_condition( posix::posix_errno e );

Returns: error_condition( e, posix_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 std::string & 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 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 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 September 14, 2007