|  | System Library | 
| Boost Home Library Home Tutorial Reference | 
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.
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_LINKis 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_LIBis 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. | 
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() | 
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.
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_categoryobject identifying errors originating from the operating system.
const error_category & generic_category();
Returns: A reference to a
error_categoryobject identifying portable error conditions.
error_categoryThe 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 ]
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;
    };
  }
}
error_category virtual membersClasses 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
evto some portableerror_category, such asgeneric_category(), and return it as anerror_conditionfor 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.
error_category non-virtual membersbool 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::lessprovides a total ordering for pointers. --end note]
error_codeThe 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 ]
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
    };
  }
}
error_code constructorserror_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 <classErrorCodeEnum> error_code(ErrorCodeEnumval ) 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>::valueistrue.
error_code modifiersvoid assign( int val, const error_category & cat ) noexcept;
Postconditions:
val_ == val && cat_ == &cat.
template<typenameErrorCodeEnum> error_code & operator=(ErrorCodeEnumval ) noexcept;
Postconditions:
*this == make_error_code( val ).Remarks: This operator shall not participate in overload resolution unless
is_error_code_enum<ErrorCodeEnum>::valueistrue.
void clear() noexcept;postcondition:
value() == 0 && category() == system_category()
error_code observersint 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 evaluatetruein a boolean context; otherwise, returns a value that will evaluatefalsein a boolean context. The value type returned shall not be convertible toint.Throws: nothing.
[Note: This conversion can be used in contexts where a
boolis expected ( e.g., anifcondition ); however, implicit conversions ( e.g., toint) that can occur withboolare not allowed, eliminating some sources of user error. One possible implementation choice for this type is pointer-to-member. --end note ]
error_conditionThe 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 ]
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
    };
  }
}
error_condition 
constructorserror_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>::valueistrue.
error_condition 
modifiersvoid 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>::valueistrue.
void clear() noexcept;
Postcondition:
value() == 0 && category() == generic_category()
error_condition 
observersint 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 evaluatetruein a boolean context; otherwise, returns a value that will evaluatefalse. The return type shall not be convertible toint.Throws: Nothing.
[ Note: This conversion can be used in contexts where a
boolis expected ( e.g., an if condition ); however, implicit conversions ( e.g., toint) that can occur withboolare not allowed, eliminating some sources of user error. One possible implementation choice for this type is pointer to member. --end note ]
throws objectextern error_code throws;
The predefined error_code object throws is supplied 
for use as a "throw on error" tag.
throws objectFunctions that specify an argument in the form error_code& ec=throws, 
with appropriate namespace qualifiers, have the following error handling 
semantics:
Postconditions:
If
&ec != &throwsand an error occurred:
ec.value()returns the implementation specific error number for the particular error that occurred.
ec.category()returns theerror_categoryforec.value().if
&ec != &throwsand an error did not occur,ec.clear().Throws:
If an error occurs and
&ec == &throws, throws an exception of typesystem_erroror of a type derived fromsystem_error. The exception'scode()member function returns a reference to anerror_codeobject with the behavior specified in Postconditions.
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.
system_errorThe 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:
ecorerror_code( ev, ecat ), from the constructor, as appropriate.
const char * what() const;
Returns: A string incorporating
this->runtime_error::what()andcode.message().
Revised January 06, 2014
© Copyright Beman Dawes, 2006, 2007, 2008, 2013
Distributed under the Boost Software License, Version 1.0. See www.boost.org/LICENSE_1_0.txt