![]() |
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_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. |
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