From f733867bb0874f9bccb6abd0570609b63536d769 Mon Sep 17 00:00:00 2001 From: Beman Dawes Date: Fri, 14 Sep 2007 15:45:36 +0000 Subject: [PATCH] Replace docs with up-to-date contents, design [SVN r39270] --- doc/error_code.html | 270 ----------------- doc/index.html | 125 ++++++++ doc/reference.html | 689 ++++++++++++++++++++++++++++++++++++++++++ doc/system_error.html | 127 -------- 4 files changed, 814 insertions(+), 397 deletions(-) delete mode 100644 doc/error_code.html create mode 100644 doc/index.html create mode 100644 doc/reference.html delete mode 100644 doc/system_error.html diff --git a/doc/error_code.html b/doc/error_code.html deleted file mode 100644 index 6770103..0000000 --- a/doc/error_code.html +++ /dev/null @@ -1,270 +0,0 @@ - - - - - - - -Boost class error_code documentation - - - - - -

Header boost/system/error_code.hpp

-

Introduction
-Synopsis
-Class error_category
-    Members
-Class error_code
-    Members
-Non-member functions
-Acknowledgments

-

Introduction

-

This header provides components used to report errors from the operating -system or other low-level application program interface (API). It is based on the Diagnostics portion of the TR2 filesystem -proposal.

-

Class error_code encapsulates an error -code, usually one returned by an API. Class -error_category encapsulates -an identifier for a -particular kind of error code. Users or -third-parties may add additional error categories.

-

Builds

-

The system library is required by default. If the preprocessor macro name -BOOST_ERROR_CODE_HEADER_ONLY is defined, no object library or shared/DLL library -is required. Only one translation unit may defined BOOST_ERROR_CODE_HEADER_ONLY, -otherwise symbols will be multiply defined.

-

Synopsis

-
namespace boost
-{
-  namespace system
-  {
-    class error_code;
-
-    typedef int         (*errno_decoder)( const error_code & );
-    typedef std::string (*message_decoder)( const error_code & );
-    typedef wstring_t   (*wmessage_decoder)( const error_code & );
-
-    class error_category : public identifier< uint_least32_t, error_category >
-    {
-    public:
-      error_category();
-      explicit error_category( value_type v );
-    };
-
-    const error_category  errno_ecat = unspecified-value;
-    const error_category  native_ecat = unspecified-value;
-
-    class error_code
-    {
-    public:
-      typedef boost::int_least32_t  value_type;
-
-      // constructors:
-      error_code();
-      error_code( value_type val, error_category cat );
-      void assign(value_type val, error_category cat);
-
-      // observers:
-      value_type      value() const;
-      error_category  category() const;
-      int             to_errno() const;  // name chosen to limit surprises
-                                         // see Kohlhoff June 28 '06 boost posting
-      std::string     message() const;
-      std::wstring    wmessage() const;
-
-      // relationals:
-      bool operator==( const error_code & rhs ) const;
-      bool operator!=( const error_code & rhs ) const;
-      bool operator< ( const error_code & rhs ) const;
-      bool operator<=( const error_code & rhs ) const;
-      bool operator> ( const error_code & rhs ) const;
-      bool operator>=( const error_code & rhs ) const;
-
-      operator unspecified-bool-type() const;
-      bool operator!() const;
-
-      // statics:
-      static error_category new_category( errno_decoder ed = 0,
-        message_decoder md = 0, wmessage_decoder wmd = 0 );
-      static bool get_decoders( error_category cat, errno_decoder & ed,
-        message_decoder & md,  wmessage_decoder & wmd );
-
-    };
-
-    std::size_t hash_value( const error_code & ec );
-    
-  } // namespace system
-} // namespace boost
-

Class error_category

-

Class error_category -encapsulates an identifier for a -particular kind of error code. Users or -third-parties may add additional error categories.

-

For inherited members, see -identifier documentation.

-

Class error_category -members

-
error_category();
-
-

Effects: Constructs an object of class error_category.

-

Postcondition: value() == value_type().

-
-
explicit error_category( value_type v );
-
-

Effects: Constructs an object of class error_category.

-

Postcondition: value() == v.

-
-

Class error_code

-

The value contained by an error_code object is the underlying -API error code itself if the API error code type can be stored in -value_type without loss of any actual values and if 0 represents no -error. Otherwise, the value is an integer that maps to the API error code, with -the exact method of mapping unspecified.

-

Class error_code members

-
error_code();
-
-

Effects: Constructs an object of class error_code.

-

Postcondition: value() == 0 && category() == errno_ecat.

-
-
error_code( value_type val, error_category cat );
-
-

Effects: Constructs an object of class error_code.

-

Postcondition: value() == val && category() == cat.

-
-
void assign(value_type val, error_category cat);
-
-

Postconditions: value() == val && category() == cat.

-
-
value_type value() const;
-
-

Returns: value() as specified by postconditions of the most -recent assign, if any, or of the constructor.

-
-
error_category category() const;
-
-

Returns: category() as specified by postconditions of the most -recent assign, if any, or of the constructor.

-
-
int to_errno() const;
-
-

Effects:  errno_decoder ed;
-       message_decoder md;
-       wmessage_decoder wmd;
-       bool ok( get_decoders( category(), ed, md, -wmd ) );

-

Returns:  If ok && ed, ed(*this), -otherwise EOTHER.

-

[Note: The intent is to return the -ISO/IEC 9945:2003, Portable Operating System Interface (POSIX) error -number that the implementation determines most closely corresponds to -value(). --end note.]

-
-
std::string message() const;
-
-

Effects:  errno_decoder ed;
-       message_decoder md;
-       wmessage_decoder wmd;
-       bool ok( get_decoders( category(), ed, md, -wmd ) );

-

Returns:  If ok && md, md(*this), -otherwise std::string().

-

Remarks: If category() == errno_ec, the string is as -returned by strerror(). Otherwise, the method used by the -implementation to determine the string is unspecified.

-

[Note: The intent is to return a locale sensitive string that describes the error -corresponding to value().  --end note.]

-
-
wstring_t wmessage() const;
-
-

Effects:  errno_decoder ed;
-       message_decoder md;
-       wmessage_decoder wmd;
-       bool ok( get_decoders( category(), ed, md, -wmd ) );

-

Returns:  If ok && wmd, wmd(*this), -otherwise std::wstring().

-

Remarks: If category() == errno_ec, the string is as -returned by strerror(). Otherwise, the method used by the -implementation to determine the string is unspecified.

-

[Note: The intent is to return a locale sensitive string that describes the error -corresponding to value().  --end note.]

-
-
bool operator==(const error_code & rhs) const;
-
-

Returns: value() == rhs.value() && category() == rhs.category().

-
-
bool operator!=(const error_code & rhs) const;
-
-

Returns: !(*this == rhs).

-
-
bool operator<(const error_code & rhs) const;
-
-

Returns: category() < rhs.category() || ( category() == - rhs.category() && value() < rhs.value() ).

-
-
bool operator<=(const error_code & rhs) const;
-
-

Returns: *this == rhs || *this < rhs.

-
-
bool operator>(const error_code & rhs) const;
-
-

Returns: !(*this <= rhs).

-
-
bool operator>=(const error_code & rhs) const;
-
-

Returns: !(*this < rhs).

-
-
operator unspecified-bool-type() const;
-
-

Returns:  value() != value_type() ? unspecified-bool-type - : 0.

-

Throws: nothing.

-

[ Note: This conversion can be used in contexts where a bool -is expected (e.g., an if condition); however, implicit conversions -(e.g., to int) that can occur with bool are not -allowed, eliminating some sources of user error. One possible implementation -choice for this type is pointer-to-member. —end note ]

-
-
bool operator!() const;
-
-

Returns:  value() == value_type().

-
-
static error_category new_category( errno_decoder ed = 0, message_decoder md = 0, wmessage_decoder wmd = 0 );
-
-

Effects: Constructs a new error_category object. - Creates an association between the object and ed,  - md, and wmd.

-

Returns: The object.

-
-
static bool get_decoders( error_category cat, errno_decoder & ed, message_decoder & md, wmessage_decoder & wmd );
-
-

Effects: If cat was created by new_category(), - sets ed,  md, and wmd - to the respective values associated with cat by - new_category(). Otherwise, no effects.

-

Returns: If cat was created by new_category(), - true, otherwise false.

-
-

Non-member functions

-
std::size_t hash_value( const error_code & ec );
-
-

Returns:  A hash value representing ec.

-
-

Acknowledgements

-

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.

-
-

Last revised: -30 August, 2007

-

© Copyright Beman Dawes, 2006

-

Distributed under the Boost Software License, Version 1.0. (See accompanying -file LICENSE_1_0.txt or copy at -www.boost.org/ LICENSE_1_0.txt)

- - - - \ No newline at end of file diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..f6eb28e --- /dev/null +++ b/doc/index.html @@ -0,0 +1,125 @@ + + + + + + + +Boost System Library + + + + + + + + + + +
+ +boost.png (6897 bytes) + System Library +
+ + + + + +
Boost Home    + Library Home   Tutorial   + Reference
+ + + + + + + + +
+ Contents
+ Introduction
+ Design Rationale
+ History
+ Acknowledgements +
+ +

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 very inefficient. The Boost System library +supports both error reporting by exception and by error code.

+

Design Rationale

+

Class error_code  and error_condition are designed as a value types so +they can be copied +without slicing and do not requiring 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.

+

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.

+

Acknowledgements

+

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 Beman Dawes, 1999
+Distributed under the Boost Software License, Version 1.0. See +www.boost.org/LICENSE_1_0.txt

+ +

Revised +September 14, 2007 +

+ + + + \ No newline at end of file diff --git a/doc/reference.html b/doc/reference.html new file mode 100644 index 0000000..9160bd6 --- /dev/null +++ b/doc/reference.html @@ -0,0 +1,689 @@ + + + + + + + +System Library Reference + + + + + + + + + + +
+ +boost.png (6897 bytes) + System Library +
+ + + + + +
Boost Home    + Library Home   Tutorial   + Reference
+ + + + + + + + +
+ Contents
+ Introduction
+ Header <boost/system/error_code.hpp>
+ Class error_category
+    Class error_category synopsis
+    Class error_category virtual members
+    Class error_category non-virtual members
+    Class error_category predefined objects
+ Class error_code
+    Class error_code synopsis
+    Class error_code constructors
+    Class error_code modifiers
+    Class error_code observers
+ Class error_condition
+    Class error_condition synopsis
+    Class error_condition constructors
+    Class error_condition modifiers
+    Class error_condition observers
+ Non-member functions
+ Header <boost/system/system_error.hpp>
+    Class system_error
+
+ +

Introduction

+ +

This reference documentation describes components that  +programs may use to report error conditions originating from the operating +system or other low-level application program interfaces.

+

System Library components do not change the value of +errno.

+

Header <boost/system/error_code.hpp>

+

<boost/system/error_code.hpp> synopsis

+
+
namespace boost
+{
+  namespace system
+  {
+    class error_category;
+    class error_code;
+    class error_condition;
+
+    //  "Concept" helpers
+    template< class T="" >
+      struct is_error_code_enum { static const bool value = false; };
+
+    template< class T="" >
+      struct is_error_condition_enum { static const bool value = false; };
+
+    //  portable error_conditions
+    namespace posix
+    {
+      enum posix_errno
+      {
+        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 posix
+
+    template<> struct is_error_condition_enum<posix::posix_errno>
+      { static const bool value = true; };
+
+    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( posix::posix_errno e );
+    error_condition make_error_condition( posix::posix_errno 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 posix_errno constant shall be the same as the +value of the <cerrno> macro shown in the above synopsis.

+

Users may specialize is_error_code_enum and +is_error_condition_enum templates to indicate that a type is eligible for +class error_code and error_condition automatic +conversions respectively.

+ +

Class error_category

+

The class error_category defines the base class for types used +to identify the source and encoding of a particular category of error code.

+

[Note: Classes may be derived from error_category +to support additional categories of errors. --end note]

+

The class error_category serves as a base class for types used +to identify the source and encoding of a particular category of error code. +Classes may be derived from error_category to support categories of +errors in addition to those defined in the Boost System library. Such classes +shall behave as specified in this subclause. [ Note: error_category +objects are passed by reference, and two such objects are equal if they have the +same address. This means that applications using custom error_category +types should create a single object of each such type. —end note ]

+

Class error_category synopsis

+
+
namespace boost
+{
+  namespace system
+  {
+    class error_category : public noncopyable
+    {
+    public:
+      virtual ~error_category();
+
+      virtual const char *     name() const = 0;
+      virtual string           message( error_code::value_type 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;
+    };
+
+    extern const error_category & posix_category;
+    extern const error_category & system_category;
+  }
+}
+
+

Class error_category virtual members

+

Classes derived from error_category shall behave as specified in +this subclause.

+
virtual const char * name() const=0;
+
+

Returns: a string naming the error category.

+

Throws: Nothing.

+
+
virtual string message( error_code::value_type ev ) const=0;
+
+

Returns: A string that describes the error denoted by + ev.

+

Throws: Nothing.

+
+

virtual error_condition default_error_condition( int ev ) const;

+
+

Returns:  error_condition( ev, *this ).

+
+

 [--Note: Derived classes will typically convert ev + to some portable error_category, such as posix_category, + and return it as an error_condition for that category. --end + note]

+
+

Throws: Nothing.

+
+

virtual bool equivalent( int code, const error_condition & +condition ) +const;

+
+

Returns: default_error_condition( code ) == condition.

+

Throws: Nothing.

+
+

virtual bool equivalent( const error_code & code, int condition ) const;

+
+

Returns: *this == code.category() && code.value() == condition.

+

Throws: Nothing.

+
+

Class error_category non-virtual members

+

bool operator==( const error_category & rhs ) const;

+
+

Returns: this == &rhs.

+
+

bool operator!=( const error_category & rhs ) const;

+
+

Returns: this != &rhs.

+
+ +
bool operator<( const error_category & rhs ) const;
+
+

Returns: std::less<const error_category*>()( this, &rhs ).

+
+

[Note: std::less provides a total ordering for + pointers. --end note]

+
+

Throws: Nothing.

+
+

Class error_category +predefined objects

+

Predefined objects posix_category +and system_category identify portable error conditions and system error +codes, respectively.

+

Class +error_code

+

The class error_code describes an object used to hold error code +values, such as those originating from the operating
+system or other low-level application program interfaces. [ Note: Class +error_code is an adjunct to error reporting by
+exception. —end note ]

+

Class +error_code synopsis

+
+
namespace boost
+{
+  namespace system
+  {
+    class error_code {
+    public:
+
+      // constructors:
+      error_code();
+      error_code( val, const error_category & cat );
+      template <class ErrorCodeEnum>
+        error_code( errorCodeEnum e,
+         typename enable_if<is_error_code_enum<ErrorCodeEnum> >::type* = 0);
+
+      // modifiers:
+      void assign( int val, const error_category & cat );
+      template<typename ErrorCodeEnum>
+        typename enable_if<is_error_code_enum<ErrorCodeEnum>, error_code>::type &
+          operator=( ErrorCodeEnum val );;
+      void clear();
+
+      // observers:
+      int                    value() const;
+      cont error_category &  category() const;
+      error_condition        default_error_condition() const;
+      string                 message() const;
+      operator unspecified-bool-type() const;
+
+    private:
+      int val_;                     // exposition only
+      const error_category & cat_;  // exposition only
+    };
+  }
+}
+
+

Class +error_code constructors

+
error_code();
+
+

Effects: Constructs an object of type error_code.

+

Postconditions: val_ == 0 && cat_ == &system_category.

+

Throws: Nothing.

+
+
error_code( int val, const error_category & cat );
+
+

Effects: Constructs an object of type error_code.

+

Postconditions: val_ == val && cat_ == &cat.

+

Throws: Nothing.

+
+
template <class ErrorCodeEnum>
+  error_code( errorCodeEnum val,
+    typename enable_if<is_error_code_enum<ErrorCodeEnum> >::type* = 0);
+
+

Effects: Constructs an object of type error_code.

+

Postconditions: *this == make_error_code( val ).

+

Throws: Nothing.

+
+

Class +error_code modifiers

+
void assign( int val, const error_category & cat );
+
+

Postconditions: val_ == val && cat_ == cat.

+

Throws: Nothing.

+
+
template<typename ErrorCodeEnum>
+  typename enable_if<is_error_code_enum<ErrorCodeEnum>, error_code>::type &
+    operator=( ErrorCodeEnum val );
+
+

Postconditions: *this == make_error_code( val ).

+

Throws: Nothing.

+
+

void clear();

+
+

postcondition: value() == 0 && category() == posix_category

+
+

Class +error_code observers

+

int value() const;

+
+

Returns: val_.

+

Throws: Nothing.

+
+

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() != value_type(), returns a value that will evaluate +true in a boolean context; otherwise, returns a value that will +evaluate false in a boolean context. The value type returned shall +not be convertible to int.

+

Throws: nothing.

+

[Note: This conversion can be used in contexts where a bool +is expected ( e.g., an if condition ); however, implicit conversions +( e.g., to int) that can occur with bool are not +allowed, eliminating some sources of user error. One possible implementation +choice for this type is pointer-to-member. --end note ]

+
+

Class error_condition

+

The class error_condition describes an object used to hold +values identifying error conditions. [ Note: error_condition +values are portable abstractions, while error_code values are +implementation specific. --end note ]

+

Class error_condition synopsis

+
+
namespace boost
+{
+  namespace system
+  {
+    class error_condition
+    {
+    public:
+
+      // constructors:
+      error_condition();
+      error_condition( int val, const error_category & cat );
+      template <class ErrorConditionEnum>
+        error_condition( errorConditionEnum val,
+          typename enable_if<is_error_condition_enum<ErrorConditionEnum> >::type* = 0 );
+
+      // modifiers:
+      void assign( int val, const error_category & cat );
+      template<typename ErrorConditionEnum>
+        typename enable_if<is_error_condition_enum<ErrorConditionEnum>, error_code>::type &
+          operator=( ErrorConditionEnum val );
+      void clear();
+
+      // observers:
+      int value() const;
+      const error_category & category() const;
+      string message() const;
+      operator unspecified-bool-type () const;
+
+    private:
+      int val_;                     // exposition only
+      const error_category & cat_;   // exposition only
+    };
+  }
+}
+
+

Class error_condition +constructors

+
error_condition();
+
+

Effects: Constructs an object of type error_condition.

+

Postconditions: val_ == 0 and cat_ == posix_category.

+

Throws: Nothing.

+
+
error_condition( value_type val, const error_category & cat );
+
+

Effects: Constructs an object of type error_condition.

+

Postconditions: val_ == val and cat_ == cat.

+

Throws: Nothing.

+
+
template <class ErrorConditionEnum>
+  error_condition( errorConditionEnum val,
+    typename enable_if<is_error_condition_enum<ErrorConditionEnum> >::type* = 0 );
+
+

Effects: Constructs an object of type error_condition.

+

Postconditions: *this == make_error_condition( val ).

+

Throws: Nothing.

+
+

Class error_condition +modifiers

+
void assign( value_type 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() == posix_category

+
+

Class error_condition +observers

+
value_type value() const;
+
+

Returns: val_.

+

Throws: Nothing

+
+
const error_category & category() const;
+
+

Returns: cat_.

+

Throws: Nothing.

+
+
string message() const;
+
+

Returns: category().message( value() ).

+

Throws: Nothing.

+
+
operator unspecified-bool-type () const;
+
+

Returns: If value() != 0, returns a value that will + evaluate true in a boolean context; otherwise, returns a value + that will evaluate false. The return type shall not be + convertible to int.

+

Throws: Nothing.

+

 [ Note: This conversion can be used in contexts where a bool + is expected ( e.g., an if condition ); however, implicit conversions ( e.g., to + int) that can occur with bool are not allowed, + eliminating some sources of user error. One possible implementation choice for + this type is pointer to member. --end note ]

+
+

Non-member functions

+ 
bool operator==( const error_code & lhs, const error_code & rhs );
+
+

Returns: lhs.category() == rhs.category() && lhs.value() == + rhs.value().

+

Throws: Nothing.

+
+
bool operator==( const error_code & code, const error_condition & condition );
+bool operator==( const error_condition & condition, const error_code & code );
+
+

Returns: code.category().equivalent( code.value(), condition )
+ || condition.category().equivalent( code, condition.value() ).

+

Throws: Nothing.

+
+
bool operator==( const error_condition & lhs, const error_condition & rhs );
+
+

Returns: lhs.category() == rhs.category() && lhs.value() == + rhs.value().

+

Throws: Nothing.

+
+
bool operator!=( const error_code & lhs, const error_code & rhs );
+
+

Returns: !(lhs == rhs ).

+

Throws: Nothing.

+
+
bool operator!=( const error_code & code, const error_condition & condition );
+bool operator!=( const error_condition & condition, const error_code & code );
+
+

Returns: !( code ==  condition ).

+

Throws: Nothing.

+
+
bool operator!=( const error_condition & lhs, const error_condition & rhs );
+
+

Returns: !(lhs == rhs ).

+

Throws: Nothing.

+
+
bool operator<( const error_code & lhs, const error_code & rhs );
+
+

Returns: lhs.category() < rhs.category()
+   || (lhs.category() == rhs.category() && lhs.value() < rhs.value()).

+

Throws: Nothing.

+
+
bool operator<( const error_condition & lhs, const error_condition & rhs );
+
+

Returns: lhs.category() < rhs.category()
+   || (lhs.category() == rhs.category() && lhs.value() < rhs.value()).

+

Throws: Nothing.

+
+
error_code make_error_code( posix::posix_errno e );
+
+

Returns: error_code( e, posix_category).

+
+
error_condition make_error_condition( posix::posix_errno e );
+
+

Returns: error_condition( e, posix_category).

+
+ +
template <class charT, class traits>
+  std::basic_ostream<charT,traits>&
+    operator<<( basic_ostream<charT,traits>& os, const error_code & ec );
+
+

Effects: os << ec.category().name() << ':' << ec.value().

+

Returns: os.

+
+
size_t hash_value( const error_code & ec );
+
+

Returns:  A hash value representing ec.

+
+ +

Header <boost/system/system_error.hpp>

+ +

Class +system_error

+

The class system_error describes an exception object used to +report error conditions that have an associated error code. Such error +conditions typically originate from the 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 std::string & what_arg );
+      system_error( error_code::value_type ev, const error_category & ecat,
+                    const std::string & what_arg );
+      system_error( error_code::value_type 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 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( error_code::value_type 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( error_code::value_type ev, const error_category & ecat );
+
+

Effects: Constructs an object of class system_error.

+

Postcondition: code() == error_code( ev, ecat )
+  && std::strcmp( this->runtime_error::what(), "" ) == 0

+
+
const error_code & code() const;
+
+

Returns: ec or error_code( ev, ecat ), from + the constructor, as appropriate.

+
+
const char * what() const;
+
+

Returns: A string incorporating + this->runtime_error::what() and + code.message().

+
+
+ +

© Copyright Beman Dawes, 2006, 2007
+Distributed under the Boost Software License, Version 1.0. See +www.boost.org/LICENSE_1_0.txt

+ +

Revised +September 14, 2007 +

+ + + + \ No newline at end of file diff --git a/doc/system_error.html b/doc/system_error.html deleted file mode 100644 index 068cbb0..0000000 --- a/doc/system_error.html +++ /dev/null @@ -1,127 +0,0 @@ - - - - - - - -Boost system/system_error.hpp documentation - - - - - -

Header boost/system/system_error.hpp

-

Introduction
-Synopsis
-Class system_error
-    Members
-Acknowledgements

-

Introduction

-

This header provides components used to report errors originating from the -operating system or other low-level application program interfaces (API's). It is based on the Diagnostics -portion of the TR2 filesystem proposal.

-

Synopsis

-
namespace boost
-{
-  namespace system
-  {
-    enum message_action { append_message, no_message };
-
-    class system_error : public std::runtime_error
-    {
-    public:
-      explicit system_error( error_code ec );
-
-      system_error( error_code ec, const std::string & what_arg,
-        message_action ma = append_message );
-
-      system_error( error_code::value_type ev, error_category ecat );
-
-      system_error( error_code::value_type ev, error_category ecat,
-        const std::string & what_arg, message_action ma = append_message );
-
-      virtual ~system_error() throw() {}
-
-      const error_code & code() const throw();
-
-      const char * what() const throw();
-
-    private:
-      error_code           m_error_code;      // for exposition only
-      bool                 m_append_message;  // for exposition only
-      mutable std::string  m_what;            // for exposition only
-    };
-  } // namespace system
-} // namespace boost
-

Class system_error

-

Class system_error defines -the type of an object that may be thrown as -an exception to report errors originating from the operating system or other -low-level API's, or used as a base class for more refined exception classes. It -encapsulates an error_code object.

-
-

[Note: A single low-level class, rather than a higher level exception -class hierarchy, is provided to allow users access to low-level error codes -originating from the operating system or other low-level API's, and to -accommodate the open-ended set of errors that may be reported by such API's. ---end note.]

-
-

Class system_error Members

-

explicit system_error( error_code ec );

-
-

Effects: Constructs an object of class system_error.

-

Postcondition: code() == ec && *runtime_error::what() == '\0' - && m_append_message.

-
-
system_error( error_code ec, const std::string & what_arg, message_action ma = append_message );
-
-

Effects: Constructs an object of class system_error.

-

Postcondition: code() == ec && std::string(runtime_error::what()) - == what_arg && m_append_message == ma.

-
-
system_error( error_code::value_type ev, error_category ecat );
-
-

Effects: Constructs an object of class system_error.

-

Postcondition: code() == error_code(ev,ecat) && *runtime_error::what() - == '\0' && m_append_message.

-
-
system_error( error_code::value_type ev, error_category ecat,
-              const std::string & what_arg, message_action ma = append_message );
-
-

Effects: Constructs an object of class system_error.

-

Postcondition: code() == error_code(ev,ecat) && std::string(runtime_error::what()) - == what_arg && m_append_message == ma.

-
-
const error_code & code() const throw();
-
-

Returns:  m_error_code

-
-
const char * what() const throw();
-
-

Returns: If !m_error_code || !m_append_message, - runtime_error::what(). Otherwise, a string as if computed by:

-
- 
m_what = runtime_error::what();
-if ( !m_what.empty() ) m_what += ": ";
-m_what += m_error_code.message();
-return m_what.c_str();
-
-
-

Acknowledgements

-

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, Jeremy Day, Bo - Persson, Oliver Kowalke, and - Oleg Abrosimov.

-
-

Last revised: -22 July, 2006

-

© Copyright Beman Dawes, 2006

-

Distributed under the Boost Software License, Version 1.0. (See accompanying -file LICENSE_1_0.txt or copy at -www.boost.org/ LICENSE_1_0.txt)

- - - - \ No newline at end of file