| System Library

Boost Home Library Home Tutorial Reference

Contents

Introduction
Macros
Deprecated names
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`.

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

## Deprecated names

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

Old name, now deprecated | New name
`namespace posix` | `namespace errc`
`namespace posix_error` | `namespace errc`
`enum posix_errno` | `enum errc_t`
`get_posix_category()` | `get_generic_category()`
`posix_category` | `generic_category`
`errno_ecat` | `generic_category`
`native_ecat` | `system_category`

## 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<posix::posix_errno><errc::errc_t>
>           { static const bool value = true; };

>         // predefined error_code object used as "throw on error" tag
>         extern error_code throws;

>         //  non-member functions

>         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( int 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( int 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 system specific 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.

`const 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() != 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();
>           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( int 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( int 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

    int 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 ]

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

> 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( 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 October 11, 2008

© Copyright Beman Dawes, 2006, 2007, 2008

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