System Library Reference

System Library

Boost Home Library Home Tutorial Reference

Contents

Introduction
C++11
Macros
Deprecated names
Breaking changes
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
throws object
Semantics of throws object
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.

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

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_ERROR_CODE_HEADER_ONLY`	Not defined.	The implementation is header-only, and the Boost.System library is not built. Overrides other link and library macros.
`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.

Deprecated names

In the process of adding Boost.System to C++0x standard library, the C++ committee changed some names. To ease transition, Boost.System deprecates the old names, but continues to provide them unless macro BOOST_SYSTEM_NO_DEPRECATED is defined.

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

Breaking changes

Two static consts are replaced by functions. These are breaking changes best fixed by globally adding () to these names to turn them into function calls.

*Old usage, now broken*	*Replacement*
`generic_category`	`generic_category()`
`system_category`	`system_category()`

User-defined BOOST_POSIX_API and BOOST_WINDOWS_API macros are no longer supported.

Header <boost/system/error_code.hpp>

<boost/system/error_code.hpp> synopsis

namespace boost
{
  namespace system
  {
    class error_category;
    const error_category &  system_category() noexcept;
    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

    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;
    bool operator==( const error_condition & lhs, const error_condition & rhs ) noexcept;

    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;
    bool operator!=( const error_condition & lhs, const error_condition & rhs ) noexcept;

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

    error_code make_error_code( errc::errc_t e ) noexcept;
    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 );

    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.

const error_category & system_category();

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

const error_category & generic_category();

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

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 noexcept = 0;
      virtual string           message( int ev ) const = 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;

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

Class `error_category` virtual members

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

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

Returns: a string naming the error category.

virtual string message( int ev ) const noexcept =0;

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

virtual error_condition default_error_condition( int ev ) const noexcept;

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]

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

Returns: default_error_condition( code ) == condition.

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

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

Class `error_category` non-virtual members

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

Returns: this == &rhs.

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

Returns: this != &rhs.

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

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

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

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() noexcept;
      error_code( val, const error_category & cat ) noexcept;
      template <class ErrorCodeEnum>
        error_code( ErrorCodeEnum e ) noexcept;

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

      // observers:
      int                    value() const noexcept;
      cont error_category &  category() const noexcept;
      error_condition        default_error_condition() const noexcept;
      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() noexcept;

Effects: Constructs an object of type error_code.

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

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

Effects: Constructs an object of type error_code.

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

template <class ErrorCodeEnum>
  error_code( ErrorCodeEnum val ) noexcept;

Effects: Constructs an object of type error_code.

Postconditions: *this == make_error_code( val ).

Remarks: This constructor shall not participate in overload resolution unless is_error_code_enum<ErrorCodeEnum>::value is true.

Class `error_code` modifiers

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

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

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

Postconditions: *this == make_error_code( val ).

Remarks: This operator shall not participate in overload resolution unless is_error_code_enum<ErrorCodeEnum>::value is true.

void clear() noexcept;

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

Class `error_code` observers

int value() const noexcept;

Returns: val_.

const error_category & category() const noexcept;

Returns: *cat_.

error_condition default_error_condition() const noexcept;

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

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 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() noexcept;
      error_condition( int val, const error_category & cat ) noexcept;
      template <class ErrorConditionEnum>
        error_condition( errorConditionEnum val ) noexcept;

      // modifiers:
      void assign( int val, const error_category & cat ) noexcept;
      template<typename ErrorConditionEnum>
        error_condition & operator=( ErrorConditionEnum val ) noexcept;
      void clear() noexcept;

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

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

Class `error_condition` constructors

error_condition() noexcept;

Effects: Constructs an object of type error_condition.

Postconditions: val_ == 0 and cat_ == &generic_category().

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

Effects: Constructs an object of type error_condition.

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

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

Effects: Constructs an object of type error_condition.

Postconditions: *this == make_error_condition(e).

Remarks: This constructor shall not participate in overload resolution unless is_error_condition_enum<ErrorConditionEnum>::value is true.

Class `error_condition` modifiers

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

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

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

Postconditions: *this == make_error_condition( e ).

Returns: *this.

Remarks: This operator shall not participate in overload resolution unless is_error_condition_enum<ErrorConditionEnum>::value is true.

void clear() noexcept;

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

Class `error_condition` observers

int value() const noexcept;

Returns: val_.

const error_category & category() const noexcept;

Returns: *cat_.

string message() const;

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

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 ]

`throws` object

extern error_code throws;

The predefined error_code object throws is supplied for use as a "throw on error" tag.

Semantics of `throws` object

Functions that specify an argument in the form error_code& ec=throws, with appropriate namespace qualifiers, have the following error handling semantics:

Postconditions:

If &ec != &throws and an error occurred:

ec.value() returns the implementation specific error number for the particular error that occurred.

ec.category() returns the error_category for ec.value().

if &ec != &throws and an error did not occur, ec.clear().

Throws:

If an error occurs and &ec == &throws, throws an exception of type system_error or of a type derived from system_error. The exception's code() member function returns a reference to an error_code object with the behavior specified in Postconditions.

Non-member functions

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

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

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() ).

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

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

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

Returns: !(lhs == rhs ).

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

Returns: !( code == condition ).

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

Returns: !(lhs == rhs ).

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

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

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

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

error_code make_error_code( errc::errc_t e ) noexcept;

Returns: error_code( e, generic_category()).

error_condition make_error_condition( errc::errc_t e ) noexcept;

Returns: error_condition( static_cast<int>( 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 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:
      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,
                    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);

      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( int 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( int 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( int 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().

Revised January 06, 2014

Distributed under the Boost Software License, Version 1.0. See www.boost.org/LICENSE_1_0.txt

<boost/system/error_code.hpp> synopsis

Semantics of throws object

Semantics of `throws` object