Introduction
Error conditions originating from the operating system or other low-level
application program interfaces (API’s) are typically reported via an integer
representing an error code. When these low-level API calls are wrapped in
portable code, such as in a portable library, some users want to deal with the
error codes in portable ways. Other users need to get at the system specific
error codes, so they can deal with system specific needs. The Boost System
library provides simple, light-weight error_code objects that encapsulate
system-specific error code values, yet also provide access to more abstract
and portable error conditions via error_condition objects.
Because error_code objects can represent errors from sources other than the
operating system, including user-defined sources, each error_code and
error_condition has an associated error_category.
An exception class, system_error, is provided. Derived from
std::runtime_error, it captures the underlying error_code for the problem
causing the exception so that this important information is not lost.
While exceptions are the preferred C++ default error code reporting mechanism, users of libraries dependent on low-level API’s often need overloads reporting error conditions via error code arguments and/or return values rather than via throwing exceptions. Otherwise, when errors are not exceptional occurrences and must be dealt with as they arise, programs become littered with try/catch blocks, unreadable, and inefficient. The Boost System library supports both error reporting by exception and by error code.
In addition to portable errors codes and conditions supported by the
error_code.hpp header, system-specific headers support the Cygwin, Linux,
and Windows platforms. These headers are effectively no-ops if included for
platforms other than their intended target.
Boost.System is part of the C++11 Standard Library. A number of changes, particularly to names, were made by the C++ committee during standardization. The Boost implementation has been tracking those changes. See Deprecated Names for synonyms provided to prevent breakage of existing user code.
Revision History
Changes in Boost 1.77
-
The conversion operator from
error_categorytostd::error_categoryhas been improved and no longer requires<map>or<mutex>. -
The comparison operators of
error_categoryare now inline friends instead of member functions (a side effect of the previous change.) -
error_conditionnow defers callinggeneric_category()to avoid instantiating the object until it’s actually needed. -
error_condition::failedanderror_condition::messagehave been undeprecated, andoperator bool()now once again returnsfailed(). -
The system category now doesn’t call
generic_category(), to avoid instantiating the object. -
The return value of
default_error_conditionchanges in some cases into anerror_conditionfrom the generic category, instead of from the system category. This happens on POSIX when the inputerror_codeis from the system category and does not correspond to anyerrc_tvalue. -
The interoperability of
error_codeandstd::error_codehas been improved substantially. It is now possible to constructboost::system::error_codefromstd::error_code, and it’s possible to passboost::system::error_codeto functions takingstd::error_code&. -
A stream insertion operator for
error_conditionhas been added.
Changes in Boost 1.76
-
windows_error.hppis no longer deprecated.
Changes in Boost 1.75
-
The platform-specific headers
windows_error.hpp,linux_error.hpp, andcygwin_error.hppemit deprecation messages and are slated for removal. -
The old names for
generic_category()andsystem_category()emit deprecation messages and are slated for removal. -
error_condition::failedis deprecated and is slated for removal.operator bool()forerror_conditionhas been reverted to its old meaning ofvalue() != 0. This is done for compatibility withstd::error_conditionas the next release is expected to improve interoperability with<system_error>even further. Note that this does not affecterror_code::failed, which is still alive and well. -
The overload of
error_condition::messagethat takes a buffer is deprecated and is slated for removal, for the same reasons. Note that this does not affecterror_code::message.
Changes in Boost 1.74
-
operator bool()now returnsfailed()instead ofvalue() != 0.
Changes in Boost 1.69
-
Boost.System is now header-only. A stub library is still built for compatibility, but linking to it is no longer necessary.
-
Even more functions have been marked
constexpr. -
The destructor of
error_categoryis now protected and no longer virtual. This is a potentially breaking change but its impact is expected to be limited. -
error_categorynow has a constructor that accepts a 64 bit identifier, enabling distinct category objects to compare equal. -
The constructors of
error_categoryare now protected. -
A non-allocating, nonthrowing overload of
messagehas been added. -
A virtual function
failedhas been added, allowing categories for which success is not synonymous with 0. -
The deprecated
boost::system::throwsobject has been removed. -
boost::throws()is now deprecated and its use is discouraged. -
The constructor of
system_errortaking a singleerror_codeargument is now explicit. -
system_error::code()now returns by value.
Changes in Boost 1.68
On a C++14 compiler, many Boost.System functions and member functions
are now constexpr, and error_code and error_condition are literal
classes.
In addition to enabling use in constant expressions (and constexpr
functions), this significantly improves the quality of the generated code.
As a result of this change, however, now using Boost.System from C++14
or C++17 code requires that the library be also built with C++14 or
above. This is the default on GCC 6 and newer, but not on GCC 5 or Clang.
One can build Boost for C++14 by passing the cxxstd=14 option to b2.
(Previous versions allowed code built against any C++ standard to link with Boost.System built against any C++ standard. In 1.68, code using any C++ standard can link with Boost.System built with C++14 or above, but if Boost.System is built with C++11 or below, only code also built with C++11 and below can link to it successfully.)
Changes in Boost 1.65
On a C++11 compiler, Boost.System now provides implicit conversions
from boost::system::error_category, error_code, and error_condition
to their standard equivalents from <system_error>.
This allows libraries to expose a C++11 interface and report errors
via std::error_code even when using Boost.System, directly or through a
dependency such as Boost.ASIO.
Design Rationale
error_code and error_condition are designed as value types so
they can be copied without slicing and do not require heap allocation, but
still have polymorphic behavior based on the error category. This is achieved
by abstract base class error_category supplying the polymorphic behavior,
and error_code and error_condition containing a pointer to an object of a
type derived from error_category.
Many of the detailed design decisions were driven by the requirements that users to be able to add additional error categories, and that it be no more difficult to write portable code than system-specific code.
The operator<< overload for error_code eliminates a misleading conversion to
bool in code like cout << ec, where ec is of type error_code. It is also
useful in its own right.
Reference
Use of C++11 and C++14 Features
The library is documented to use several C++11 and C++14 features,
including noexcept, explicit conversion operators and constexpr. The
actual implementation uses C++11 and C++14 features only when they are
available, and otherwise falls back on C++03 features.
Macros
When BOOST_SYSTEM_ENABLE_DEPRECATED is defined, the library provides
deprecated features for compatibility. These features are bound to eventually
disappear.
When BOOST_SYSTEM_USE_UTF8 is defined, on Windows the library returns
UTF-8 messages using code page CP_UTF8 instead of the default CP_ACP.
This macro has no effect on POSIX.
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<boost/system/is_error_code_enum.hpp>
is_error_code_enum
namespace boost {
namespace system {
template<class T>
struct is_error_code_enum { static const bool value = false; };
} // namespace system
} // namespace boost
Users may specialize is_error_code_enum for their error enumeration
types to indicate that they should be eligible for automatic conversions
to error_code. This conversion calls make_error_code(e), which should
be provided in the same namespace as the enumeration type.
<boost/system/is_error_condition_enum.hpp>
is_error_condition_enum
namespace boost {
namespace system {
template<class T>
struct is_error_condition_enum { static const bool value = false; };
} // namespace system
} // namespace boost
Users may specialize is_error_condition_enum for their error enumeration
types to indicate that they should be eligible for automatic conversions
to error_condition. This conversion calls make_error_condition(e), which
should be provided in the same namespace as the enumeration type.
<boost/system/errc.hpp>
errc
namespace boost {
namespace system {
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; };
constexpr error_code make_error_code( errc::errc_t e ) noexcept;
constexpr error_condition make_error_condition( errc::errc_t e ) noexcept;
} // namespace system
} // namespace boost
The predefined enumeration type errc::errc_t provides named constants
corresponding to the values of the <cerrno> macros.
constexpr error_condition make_error_condition( errc::errc_t e ) noexcept;
-
- Returns:
-
error_condition( e, generic_category() ).
Since errc::errc_t provides a specialization of is_error_condition_enum
and an overload of make_error_condition, it can be converted implicitly to
an error_condition. This is typically useful when comparing error_code
values returned from APIs to a portable condition, as in the below example:
*
+
void api_function( boost::system::error_code& ec );
void my_function()
{
boost::system::error_code ec;
api_function( ec );
if( ec == boost::system::errc::no_such_file_or_directory )
{
// an entity wasn't found (ENOENT)
// handle this condition
}
}
constexpr error_code make_error_code( errc::errc_t e ) noexcept;
-
- Returns:
-
error_code( e, generic_category() ).
In addition to make_error_condition, errc::errc_t provides an overload of
make_error_code. This allows the creation of generic error codes, an
operation typically useful when a function needs to signal a generic failure
that does not come from an underlying API, such as for instance an out of
memory condition:
*
+
void my_api_function( boost::system::error_code& ec )
{
void* p = std::malloc( 16 );
if( p == 0 )
{
// return ENOMEM
ec = make_error_code( boost::system::errc::out_of_memory );
return;
}
// use p
}
<boost/system/error_category.hpp>
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.
Classes may be derived from error_category to support categories of
errors in addition to those defined in Boost.System.
namespace boost {
namespace system {
class error_category
{
public: // noncopyable
error_category( error_category const & ) = delete;
error_category& operator=( error_category const & ) = delete;
protected:
~error_category() = default;
constexpr error_category() noexcept;
explicit constexpr error_category( unsigned long long id ) noexcept;
public:
virtual const char * name() const noexcept = 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;
virtual std::string message( int ev ) const = 0;
virtual char const * message( int ev, char * buffer, std::size_t len )
const noexcept;
virtual bool failed( int ev ) const noexcept;
friend constexpr bool operator==( const error_category & lhs,
const error_category & rhs ) noexcept;
friend constexpr bool operator!=( const error_category & lhs,
const error_category & rhs ) noexcept;
friend constexpr bool operator< ( const error_category & lhs,
const error_category & rhs ) noexcept;
operator std::error_category const & () const;
private:
unsigned long long id_; // exposition only
};
}
}
Constructors
constexpr error_category() noexcept;
-
- Effects:
-
Initializes
id_to 0. - Remarks:
-
Since equivalence for categories that do not have an identifier is based on comparing object addresses, a user-defined derived category of type
Cthat uses this constructor should ensure that only one object of typeCexists in the program.
explicit constexpr error_category( unsigned long long id ) noexcept;
-
- Effects:
-
Initializes
id_toid. - Remarks:
-
User-defined derived categories that use this constructor are considered equivalent when their identifiers match. Therefore, those categories may have more than one instance existing in a program, but to minimize the possibility of collision, their identifiers must be randomly chosen (at the time the category is implemented, not at runtime). One way of generating a 64 bit random identifier is https://www.random.org/cgi-bin/randbyte?nbytes=8&format=h.
Virtuals
virtual const char * name() const noexcept = 0;
-
- Returns:
-
In derived classes, a character literal naming the error category.
virtual error_condition default_error_condition( int ev ) const noexcept;
-
- Returns:
-
-
In derived classes, an error condition corresponding to
ev. The returned error condition will typically come from the generic category. -
In the default implementation,
error_condition( ev, *this ).
-
virtual bool equivalent( int code, const error_condition & condition )
const noexcept;
-
- Returns:
-
-
In derived classes,
truewhenerror_code( code, *this )is equivalent tocondition. -
In the default implementation,
default_error_condition( code ) == condition.
-
virtual bool equivalent( const error_code & code, int condition )
const noexcept;
-
- Returns:
-
-
In derived classes,
truewhencodeis equivalent toerror_condition( condition, *this ). -
In the default implementation,
*this == code.category() && code.value() == condition.
-
virtual std::string message( int ev ) const = 0;
-
- Returns:
-
In derived classes, a string that describes the error denoted by
ev.
virtual char const * message( int ev, char * buffer, std::size_t len )
const noexcept;
-
- Effects:
-
-
Derived classes should either
-
return a pointer to a character literal describing the error denoted by
ev, or -
copy a string describing the error into
buffer, truncating it tolen-1characters and storing a null terminator, and returnbuffer. Iflenis 0, nothing is copied, but the function still returnsbuffer. Note that whenlenis 0,buffermay benullptr.
-
-
The default implementation calls
message(ev)and copies the result intobuffer, truncating it tolen-1characters and storing a null terminator. Iflenis 0, copies nothing. Returnsbuffer. Ifmessage(ev)throws an exception, the string"Message text unavailable"is used.
-
- Example:
-
const char* my_category::message(int ev, char* buffer, size_t len) const noexcept { switch(ev) { case 0: return "no error"; case 1: return "voltage out of range"; case 2: return "impedance mismatch"; case 31: case 32: case 33: std::snprintf(buffer, len, "component %d failure", ev-30); return buffer; default: std::snprintf(buffer, len, "unknown error %d", ev); return buffer; } }
virtual bool failed( int ev ) const noexcept;
-
- Returns:
-
-
In derived classes,
truewhenevrepresents a failure. -
In the default implementation,
ev != 0.
-
- Remarks:
-
All calls to this function with the same
evmust return the same value.
Comparisons
friend constexpr bool operator==( const error_category & lhs,
const error_category & rhs ) noexcept;
-
- Returns:
-
rhs.id_ == 0? &lhs == &rhs: lhs.id_ == rhs.id_. - Remarks:
-
Two category objects are considered equivalent when they have matching nonzero identifiers, or are the same object.
friend constexpr bool operator!=( const error_category & lhs,
const error_category & rhs ) noexcept;
-
- Returns:
-
!( lhs == rhs ).
constexpr bool operator< ( const error_category & lhs,
const error_category & rhs ) const noexcept;
-
- Returns:
-
-
If
lhs.id_ < rhs.id_,true; -
Otherwise, if
lhs.id_ > rhs.id_,false; -
Otherwise, if
rhs.id_ != 0,false; -
Otherwise,
std::less<error_category const *>()( &lhs, &rhs ).
-
Conversions
operator std::error_category const & () const;
-
- Returns:
-
A reference to an
std::error_categoryobject corresponding to*this.
<boost/system/system_category.hpp>
system_category
namespace boost {
namespace system {
constexpr const error_category & system_category() noexcept;
} // namespace system
} // namespace boost
constexpr const error_category & system_category() noexcept;
-
- Returns:
-
A reference to a predefined
error_categoryobject identifying errors originating from the operating system.
<boost/system/generic_category.hpp>
generic_category
namespace boost {
namespace system {
constexpr const error_category & generic_category() noexcept;
} // namespace system
} // namespace boost
constexpr const error_category & generic_category() noexcept;
-
- Returns:
-
A reference to a predefined
error_categoryobject identifying portable error codes and conditions.
<boost/system/error_code.hpp>
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. It’s an adjunct to error reporting
by exception.
namespace boost {
namespace system {
class error_code {
public:
// constructors:
constexpr error_code() noexcept;
constexpr error_code( int val, const error_category & cat ) noexcept;
template <class ErrorCodeEnum>
constexpr error_code( ErrorCodeEnum e ) noexcept;
error_code( std::error_code const& ec ) noexcept;
// modifiers:
constexpr void assign( int val, const error_category & cat ) noexcept;
template<typename ErrorCodeEnum>
constexpr error_code & operator=( ErrorCodeEnum e ) noexcept;
constexpr void clear() noexcept;
// observers:
constexpr int value() const noexcept;
constexpr const error_category & category() const noexcept;
error_condition default_error_condition() const noexcept;
std::string message() const;
char const * message( char * buffer, std::size_t len ) const noexcept;
constexpr bool failed() const noexcept;
constexpr explicit operator bool() const noexcept;
// comparisons:
friend constexpr bool operator==( const error_code & lhs,
const error_code & rhs ) noexcept;
friend constexpr bool operator!=( const error_code & lhs,
const error_code & rhs ) noexcept;
friend constexpr bool operator<( const error_code & lhs,
const error_code & rhs ) noexcept;
friend bool operator==( const error_code & code,
const error_condition & condition ) noexcept;
friend bool operator==( const error_condition & condition,
const error_code & code ) noexcept;
friend bool operator!=( const error_code & code,
const error_condition & condition ) noexcept;
friend bool operator!=( const error_condition & condition,
const error_code & code ) noexcept;
friend bool operator==( const error_code & lhs,
const std::error_code & rhs ) noexcept;
friend bool operator==( const std::error_code & lhs,
const error_code & rhs ) noexcept;
friend bool operator!=( const error_code & lhs,
const std::error_code & rhs ) noexcept;
friend bool operator!=( const std::error_code & lhs,
const error_code & rhs ) noexcept;
template<class E>
friend constexpr bool operator==( const error_code & lhs, E rhs ) noexcept;
template<class E>
friend constexpr bool operator==( E lhs, const error_code & rhs ) noexcept;
template<class E>
friend constexpr bool operator!=( const error_code & lhs, E rhs ) noexcept;
template<class E>
friend constexpr bool operator!=( E lhs, const error_code & rhs ) noexcept;
// conversions:
operator std::error_code() const;
operator std::error_code();
template<class T> operator T& (); // only when T=std::error_code
// stream insertion:
template <class charT, class traits>
std::basic_ostream<charT, traits>&
operator<<( basic_ostream<charT, traits>& os, const error_code & ec );
};
// non-member functions
std::size_t hash_value( const error_code & ec );
}
}
Constructors
constexpr error_code() noexcept;
-
- Ensures:
-
value() == 0;category() == system_category().
constexpr error_code( int val, const error_category & cat ) noexcept;
-
- Ensures:
-
value() == val;category() == cat.
template <class ErrorCodeEnum>
constexpr error_code( ErrorCodeEnum e ) noexcept;
-
- Ensures:
-
*this == make_error_code( e ). - Remarks:
-
This constructor is only enabled when
is_error_code_enum<ErrorCodeEnum>::valueistrue.
error_code( std::error_code const & ec ) noexcept;
-
- Effects:
-
Construct an
error_codethat wrapsec. - Remarks:
-
value()andcategory()are unspecified.
Modifiers
constexpr void assign( int val, const error_category & cat ) noexcept;
-
- Ensures:
-
value() == val;category() == cat.
template<typename ErrorCodeEnum>
constexpr error_code & operator=( ErrorCodeEnum e ) noexcept;
-
- Ensures:
-
*this == make_error_code( e ). - Remarks:
-
This operator is only enabled when
is_error_code_enum<ErrorCodeEnum>::valueistrue.
constexpr void clear() noexcept;
-
- Ensures:
-
value() == 0;category() == system_category().
Observers
constexpr int value() const noexcept;
-
- Returns:
-
the error value.
constexpr const error_category & category() const noexcept;
-
- Returns:
-
the error category.
error_condition default_error_condition() const noexcept;
-
- Returns:
-
category().default_error_condition( value() ).
std::string message() const;
-
- Returns:
-
If
*thiswraps astd::error_codeobjectec,ec.message(). Otherwise,category().message( value() ).
char const * message( char * buffer, std::size_t len ) const noexcept;
-
- Effects:
-
If
*thiswraps astd::error_codeobjectec, copies the string returned fromec.message()intobufferand returnsbuffer. Otherwise, returnscategory().message( value(), buffer, len ).
constexpr bool failed() const noexcept;
-
- Returns:
-
If
*thiswraps astd::error_codeobjectec,ec.value() != 0. Otherwise,category().failed( value() ).
constexpr explicit operator bool() const noexcept;
-
- Returns:
-
failed().
Comparisons
friend constexpr bool operator==( const error_code & lhs,
const error_code & rhs ) noexcept;
-
- Returns:
-
If both
lhsandrhswrapstd::error_codeobjectse1ande2,e1 == e2. Otherwise,lhs.value() == rhs.value() && lhs.category() == rhs.category().
friend constexpr bool operator!=( const error_code & lhs,
const error_code & rhs ) noexcept;
-
- Returns:
-
!( lhs == rhs ).
friend constexpr bool operator<( const error_code & lhs,
const error_code & rhs ) noexcept;
-
- Returns:
-
If both
lhsandrhswrapstd::error_codeobjectse1ande2,e1 < e2. Otherwise,lhs.category() < rhs.category() || (lhs.category() == rhs.category() && lhs.value() < rhs.value()).
friend bool operator==( const error_code & code,
const error_condition & condition ) noexcept;
friend bool operator==( const error_condition & condition,
const error_code & code ) noexcept;
-
- Returns:
-
If
codewraps astd::error_codeobjectec,ec == static_cast<std::error_condition>( condition ). Otherwise,code.category().equivalent( code.value(), condition ) || condition.category().equivalent( code, condition.value() ).
friend bool operator!=( const error_code & lhs,
const error_condition & rhs ) noexcept;
friend bool operator!=( const error_condition & lhs,
const error_code & rhs ) noexcept;
-
- Returns:
-
!( lhs == rhs ).
friend bool operator==( const error_code & lhs,
const std::error_code & rhs ) noexcept;
-
- Returns:
-
static_cast<std::error_code>(lhs) == rhs.
friend bool operator==( const std::error_code & lhs,
const error_code & rhs ) noexcept;
-
- Returns:
-
lhs == static_cast<std::error_code>(rhs).
friend bool operator!=( const error_code & lhs,
const std::error_code & rhs ) noexcept;
friend bool operator!=( const std::error_code & lhs,
const error_code & rhs ) noexcept;
-
- Returns:
-
!( lhs == rhs ).
template<class E>
friend constexpr bool operator==( const error_code & lhs, E rhs ) noexcept;
-
- Effects:
-
When
is_error_code_enum<E>::valueistrue, returnslhs == make_error_code(rhs); -
When
is_error_condition_enum<E>::valueistrue, returnslhs == make_error_condition(rhs); -
Otherwise, this overload is disabled.
template<class E>
friend constexpr bool operator==( E lhs, const error_code & rhs ) noexcept;
-
- Effects:
-
When
is_error_code_enum<E>::valueistrue, returnsmake_error_code(lhs) == rhs; -
When
is_error_condition_enum<E>::valueistrue, returnsmake_error_condition(lhs) == rhs; -
Otherwise, this overload is disabled.
template<class E>
friend constexpr bool operator!=( const error_code & lhs, E rhs ) noexcept;
template<class E>
friend constexpr bool operator!=( E lhs, const error_code & rhs ) noexcept;
-
- Returns:
-
!( lhs == rhs ). - Remarks:
-
These overloads are only enabled when
is_error_code_enum<E>::valueistrueoris_error_condition_enum<E>::valueistrue.
Conversions
operator std::error_code() const;
operator std::error_code();
-
- Returns:
-
If
*thiswraps astd::error_codeobjectec,ec. Otherwise,std::error_code( value(), category() ).
template<class T> operator T&();
-
- Effects:
-
If
*thiswraps astd::error_codeobjectec, returns a reference toec. Otherwise, makes*thiswrapstd::error_code( *this ), then returns a reference to it. - Remarks:
-
This operator is only enabled when
Tisstd::error_code.
Stream Insertion
template <class charT, class traits>
std::basic_ostream<charT, traits>&
operator<<( basic_ostream<charT, traits>& os, const error_code & ec );
-
- Effects:
-
If
ecwraps astd::error_codeobjecte2,os << "std:" << e2. Otherwise,os << ec.category().name() << ':' << ec.value(). - Returns:
-
os.
Nonmembers
std::size_t hash_value( const error_code & ec );
-
- Returns:
-
If
ecwraps astd::error_codeobjecte2,std::hash<std::error_code>()(e2). Otherwise, a hash value representingec.
<boost/system/error_condition.hpp>
error_condition
namespace boost {
namespace system {
class error_condition {
public:
// constructors:
constexpr error_condition() noexcept;
constexpr error_condition( int val, const error_category & cat ) noexcept;
template <class ErrorConditionEnum>
constexpr error_condition( ErrorConditionEnum e ) noexcept;
// modifiers:
constexpr void assign( int val, const error_category & cat ) noexcept;
template<typename ErrorConditionEnum>
constexpr error_condition & operator=( ErrorConditionEnum e ) noexcept;
constexpr void clear() noexcept;
// observers:
constexpr int value() const noexcept;
constexpr const error_category & category() const noexcept;
std::string message() const;
char const * message( char * buffer, std::size_t len ) const noexcept;
constexpr bool failed() const noexcept;
constexpr explicit operator bool() const noexcept;
// comparisons:
friend constexpr bool operator==( const error_condition & lhs,
const error_condition & rhs ) noexcept;
friend constexpr bool operator!=( const error_condition & lhs,
const error_condition & rhs ) noexcept;
friend constexpr bool operator<( const error_condition & lhs,
const error_condition & rhs ) noexcept;
friend bool operator==( const std::error_code & code,
const error_condition & condition ) noexcept;
friend bool operator==( const error_condition & condition,
const std::error_code & code ) noexcept;
friend bool operator!=( const std::error_code & code,
const error_condition & condition ) noexcept;
friend bool operator!=( const error_condition & condition,
const std::error_code & code ) noexcept;
// conversions:
operator std::error_condition() const;
// stream insertion:
template <class charT, class traits>
std::basic_ostream<charT, traits>&
operator<<( basic_ostream<charT, traits>& os, const error_condition & en );
};
}
}
Constructors
constexpr error_condition() noexcept;
-
- Ensures:
-
value() == 0;category() == generic_category().
constexpr error_condition( int val, const error_category & cat ) noexcept;
-
- Ensures:
-
value() == val;category() == cat.
template <class ErrorConditionEnum>
constexpr error_condition( ErrorConditionEnum e ) noexcept;
-
- Ensures:
-
*this == make_error_condition( e ). - Remarks:
-
This constructor is only enabled when
is_error_condition_enum<ErrorConditionEnum>::valueistrue.
Modifiers
constexpr void assign( int val, const error_category & cat ) noexcept;
-
- Ensures:
-
value() == val;category() == cat.
template <class ErrorConditionEnum>
constexpr error_condition & operator=( ErrorConditionEnum e ) noexcept;
-
- Ensures:
-
*this == make_error_condition( e ). - Remarks:
-
This operator is only enabled when
is_error_condition_enum<ErrorConditionEnum>::valueistrue.
constexpr void clear() noexcept;
-
- Ensures:
-
value() == 0;category() == generic_category().
Observers
constexpr int value() const noexcept;
-
- Returns:
-
the error value.
constexpr const error_category & category() const noexcept;
-
- Returns:
-
the error category.
std::string message() const;
-
- Returns:
-
category().message( value() ).
char const * message( char * buffer, std::size_t len ) const noexcept;
-
- Returns:
-
category().message( value(), buffer, len ).
constexpr bool failed() const noexcept;
-
- Returns:
-
category().failed( value() ).
constexpr explicit operator bool() const noexcept;
-
- Returns:
-
failed().
Comparisons
friend constexpr bool operator==( const error_condition & lhs,
const error_condition & rhs ) noexcept;
-
- Returns:
-
lhs.value() == rhs.value() && lhs.category() == rhs.category().
friend constexpr bool operator!=( const error_condition & lhs,
const error_condition & rhs ) noexcept;
-
- Returns:
-
!( lhs == rhs ).
friend constexpr bool operator<( const error_condition & lhs,
const error_condition & rhs ) noexcept;
-
- Returns:
-
lhs.category() < rhs.category() || (lhs.category() == rhs.category() && lhs.value() < rhs.value()).
friend bool operator==( const std::error_code & code,
const error_condition & condition ) noexcept;
friend bool operator==( const error_condition & condition,
const std::error_code & code ) noexcept;
-
- Returns:
-
code == static_cast<std::error_condition>( rhs ).
friend constexpr bool operator!=( const std::error_code & lhs,
const error_condition & rhs ) noexcept;
friend constexpr bool operator!=( const error_condition & lhs,
const std::error_code & rhs ) noexcept;
-
- Returns:
-
!( lhs == rhs ).
Conversions
operator std::error_condition() const;
-
- Returns:
-
std::error_condition( value(), category() ).
Stream Insertion
template <class charT, class traits>
std::basic_ostream<charT, traits>&
operator<<( basic_ostream<charT, traits>& os, const error_condition & en );
-
- Effects:
-
os << "cond:" << en.category().name() << ':' << en.value(). - Returns:
-
os.
<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:
explicit 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 );
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 );
error_code code() const noexcept;
const char * what() const noexcept;
};
}
}
Constructors
explicit system_error( error_code ec );
system_error( error_code ec, const char * what_arg );
system_error( error_code ec, const std::string & what_arg );
-
- Ensures:
-
code() == ec.
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 );
-
- Ensures:
-
code() == error_code( ev, ecat ).
Observers
error_code code() const noexcept;
-
- Returns:
-
ecorerror_code( ev, ecat ), from the constructor, as appropriate.
const char * what() const noexcept;
-
- Returns:
-
A null-terminated character string incorporating the arguments supplied in the constructor, typically of the form
what_arg + ": " + code().message().
<boost/system.hpp>
This convenience header includes all the headers previously described.
History
N1975, Filesystem Library Proposal for TR2, accepted for Library Technical Report 2 (TR2) at the Berlin meeting, included additional components to supplement the Standard Library’s Diagnostics clause. Since then, these error reporting components have received wider public scrutiny and enhancements have been made to the design. The enhanced version has been used by N2054, Networking Library Proposal for TR2, demonstrating that these error reporting components are useful beyond the original Filesystem Library.
The original proposal viewed error categories as a binary choice between
errno (i.e. POSIX-style) and the native operating system’s error
codes. The proposed components now allow as many additional error categories as
are needed by either implementations or by users. The need to support additional
error categories, for example, occurs in some networking library implementations
because they are built on top of the POSIX getaddrinfo API that
uses error codes not based on errno.
Acknowledgments
Christopher Kohlhoff and Peter Dimov made important contributions to the design. Comments and suggestions were also received from Pavel Vozenilek, Gennaro Prota, Dave Abrahams, Jeff Garland, Iain Hanson, Oliver Kowalke, and Oleg Abrosimov. Christopher Kohlhoff suggested several improvements to the N2066 paper. Johan Nilsson’s comments led to several of the refinements in N2066.
Copyright and License
This documentation is
-
Copyright 2003-2017 Beman Dawes
-
Copyright 2018-2021 Peter Dimov
and is distributed under the Boost Software License, Version 1.0.