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 Function `boost::throws()` 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`.

## C++11

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 define 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_ENABLE_DEPRECATED` | Not defined. | Deprecated features are provided for compatibility.

## 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
`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 );

>       } // namespace system

>       system::error_code & throws();

>     } // namespace boost

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 ]

## 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`.

## Function `boost::throws()`

    system::error_code& throws();

> Returns: A `system::error_code` reference for use in some user-defined function signature as a "throw on error" tag.

> Remark: The only valid use for the returned reference is to test its address for equality or inequality to the address of the reference returned by another call to throws(). The returned reference itself has been poisoned so that an attempt to dereference it will fail.

> [Example: Example of a function that uses the `throws()` idiom:

> >     int divide(int dividend, int divisor,
> >                boost::system::error_code& ec = boost::throws())
> >     {
> >       if (divisor == 0)                             // is there an error?
> >       {
> >         if (&ec == &boost::throws())                // throw on error
> >           throw "oops!";                            // whatever exception you prefer
> >         ec = error_code(EDOM, generic_category());  // report error via error_code
> >         return 0;
> >       }

> >       if (&ec != &boost::throws())                  // error reporting via error_code
> >         ec.clear();
> >       return dividend / divisor;
> >     }

> — end Example]

## 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 September 07, 2017

© Copyright Beman Dawes, 2006, 2007, 2008, 2013

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