![]() |
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.
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. |
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 |
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<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.
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 = 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();
}
}
error_category virtual membersClasses 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
evto some portableerror_category, such asgeneric_category, and return it as anerror_conditionfor 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.
error_category non-virtual membersbool 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::lessprovides a total ordering for pointers. --end note]Throws: Nothing.
error_category
non-member functionsconst error_category & get_system_category();
Returns: A reference to a
error_categoryobject identifying errors originating from the operating system.Throws: Nothing.
const error_category & get_generic_category();
Returns: A reference to a
error_categoryobject identifying portable error conditions.Throws: Nothing.
error_category
predefined objectsPredefined objects system_category
and generic_category identify system specific error codes and portable error conditions, respectively.
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();
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
};
}
}
error_code constructorserror_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 <classErrorCodeEnum> error_code(errorCodeEnumval, 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.
error_code modifiersvoid assign( int val, const error_category & cat );
Postconditions:
val_ == val && cat_ == &cat.Throws: Nothing.
template<typenameErrorCodeEnum> typename enable_if<is_error_code_enum<ErrorCodeEnum>, error_code>::type & operator=(ErrorCodeEnumval );
Postconditions:
*this == make_error_code( val ).Throws: Nothing.
void clear();
postcondition:
value() == 0 && category() == generic_category
error_code observersint 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 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();
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
};
}
}
error_condition
constructorserror_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.
error_condition
modifiersvoid 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
error_condition
observersint 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 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 );
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.
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 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