libs/system/doc/reference.html

   1 <html>
   2
   3 <head>
   4 <meta http-equiv="Content-Language" content="en-us">
   5 <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
   6 <meta name="ProgId" content="FrontPage.Editor.Document">
   7 <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
   8 <title>System Library Reference</title>
   9 <link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css">
  10 </head>
  11
  12 <body>
  13
  14 <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="637">
  15   <tr>
  16     <td width="277">
  17 <a href="../../../index.htm">
  18 <img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td>
  19     <td width="337" align="middle">
  20     <font size="7">System Library</font>
  21     </td>
  22   </tr>
  23 </table>
  24
  25 <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
  26   <tr>
  27     <td><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp; <a href="index.html">
  28     Library Home</a>&nbsp;&nbsp; Tutorial&nbsp;&nbsp; <a href="reference.html">
  29     Reference</a></td>
  30   </tr>
  31 </table>
  32
  33 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
  34   <tr>
  35     <td width="100%" bgcolor="#D7EEFF" align="center">
  36       <i><b>Contents</b></i></td>
  37   </tr>
  38   <tr>
  39     <td width="100%" bgcolor="#E8F5FF">
  40       <a href="#Introduction">Introduction</a><br>
  41       <a href="#C++11">C++11</a><br>
  42       <a href="#Macros">Macros</a><br>
  43       <a href="#Deprecated-names">Deprecated names</a><br>
  44       <a href="#Breaking-changes">Breaking changes</a><br>
  45       <a href="#Header-error_code">Header &lt;boost/system/error_code.hpp&gt;</a><br>
  46       <a href="#Class-error_category">Class <code>error_category</code></a><br>
  47       &nbsp;&nbsp;&nbsp;<a href="#Class-error_category-synopsis">Class <code>error_category</code> synopsis</a><br>
  48       &nbsp;&nbsp;&nbsp;<a href="#Class-error_category-virtual-members">Class <code>error_category</code> virtual members</a><br>
  49       &nbsp;&nbsp;&nbsp;<a href="#Class-error_category-non-virtual-members">Class <code>error_category</code> non-virtual members</a><br>
  50 &nbsp;&nbsp; <a href="#Class-error_category-non-member-functions">Class <code>error_category</code>
  51       non-member functions</a><br>
  52       &nbsp;&nbsp;&nbsp;<a href="#Class-error_category-predefined-objects">Class <code>error_category</code> predefined objects</a><br>
  53       <a href="#Class-error_code">Class <code>error_code</code></a><br>
  54       &nbsp;&nbsp;&nbsp;<a href="#Class-error_code-synopsis">Class <code>error_code</code> synopsis</a><br>
  55       &nbsp;&nbsp;&nbsp;<a href="#Class-error_code-constructors">Class <code>error_code</code> constructors</a><br>
  56       &nbsp;&nbsp;&nbsp;<a href="#Class-error_code-modifiers">Class <code>error_code</code> modifiers</a><br>
  57       &nbsp;&nbsp;&nbsp;<a href="#Class-error_code-observers">Class <code>error_code</code> observers</a><br>
  58       <a href="#Class-error_condition">Class <code>error_condition</code></a><br>
  59       &nbsp;&nbsp;&nbsp;<a href="#Class-error_condition-synopsis">Class <code>error_condition</code> synopsis</a><br>
  60       &nbsp;&nbsp;&nbsp;<a href="#Class-error_condition-constructors">Class <code>error_condition</code> constructors</a><br>
  61       &nbsp;&nbsp;&nbsp;<a href="#Class-error_condition-modifiers">Class <code>error_condition</code> modifiers</a><br>
  62       &nbsp;&nbsp;&nbsp;<a href="#Class-error_condition-observers">Class <code>error_condition</code> observers</a><br>
  63       <a href="#throws-object"><code>throws</code> object</a><br>
  64       <a href="#Semantics-of-throws">Semantics of <code>throws</code> object</a><br>
  65       <a href="#Non-member-functions">Non-member functions</a><br>
  66       <a href="#Header-system_error">Header &lt;boost/system/system_error.hpp&gt;</a><br>
  67       &nbsp;&nbsp;&nbsp;<a href="#Class-system_error">Class <code>system_error</code></a><br>
  68     </td>
  69   </tr>
  70 </table>
  71
  72 <h2><a name="Introduction">Introduction</a></h2>
  73
  74 <p>This reference documentation describes components that&nbsp;programs may use to report error conditions originating from the operating
  75 system or other low-level application program interfaces.</p>
  76 <p>Boost.System library components never change the value of <code>
  77 errno</code>.</p>
  78 <h2><a name="C++11">C++11</a></h2>
  79 <p>The library is documented to use several C++11 features, including <code>
  80 noexcept</code> and explicit conversion operators. The actual implementation
  81 uses C++11 features only when they are available, and otherwise falls back on
  82 C++03 features.</p>
  83 <h2><a name="Macros">Macros</a></h2>
  84 <p>Users may defined the following macros if desired. Sensible defaults are
  85 provided, so users may ignore these macros if they prefer.</p>
  86 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" height="368">
  87   <tr>
  88     <td height="16"><b><i>Macro Name</i></b></td>
  89     <td height="16"><b><i>Default</i></b></td>
  90     <td height="16"><b><i>Effect if defined</i></b></td>
  91   </tr>
  92   <tr>
  93     <td valign="top" height="64"><code>BOOST_ERROR_CODE_HEADER_ONLY</code></td>
  94     <td valign="top" height="64">Not defined.</td>
  95     <td valign="top" height="64">The implementation is header-only, and the
  96     Boost.System library is not built. Overrides other link and library macros.</td>
  97   </tr>
  98   <tr>
  99     <td valign="top" height="64"><code>BOOST_SYSTEM_DYN_LINK</code></td>
 100     <td valign="top" height="64">Defined if <code>BOOST_ALL_DYN_LINK</code> is defined,
 101     otherwise not defined.</td>
 102     <td valign="top" height="64">Boost.System library is dynamically linked. If not defined,
 103     static linking is assumed.</td>
 104   </tr>
 105   <tr>
 106     <td valign="top" height="47"><code>BOOST_SYSTEM_NO_LIB</code></td>
 107     <td valign="top" height="47">Defined if <code>BOOST_ALL_NO_LIB</code> is defined,
 108     otherwise not defined.</td>
 109     <td valign="top" height="47">Boost.System library does not use the Boost auto-link
 110     facility.</td>
 111   </tr>
 112   <tr>
 113     <td valign="top" height="32"><code>BOOST_SYSTEM_NO_DEPRECATED</code></td>
 114     <td valign="top" height="32">Not defined.</td>
 115     <td valign="top" height="32">Deprecated features are excluded.</td>
 116   </tr>
 117   </table>
 118 <h2><a name="Deprecated-names">Deprecated names</a></h2>
 119 <p>In the process of adding Boost.System to C++0x standard library, the C++
 120 committee changed some
 121 names. To ease transition, Boost.System deprecates the old
 122 names, but continues to provide them unless macro <code>BOOST_SYSTEM_NO_DEPRECATED</code>
 123 is defined.</p>
 124 <table border="1" cellpadding="5" cellspacing="1" style="border-collapse: collapse" bordercolor="#111111">
 125   <tr>
 126     <td><b><i>Old usage, now deprecated</i></b></td>
 127     <td><b><i>Replacement</i></b></td>
 128   </tr>
 129   <tr>
 130     <td><code>get_generic_category()</code></td>
 131     <td><code>generic_category()</code></td>
 132   </tr>
 133   <tr>
 134     <td><code>get_system_category()</code></td>
 135     <td><code>system_category()</code></td>
 136   </tr>
 137   <tr>
 138     <td><code>namespace posix</code></td>
 139     <td><code>namespace errc</code></td>
 140   </tr>
 141   <tr>
 142     <td><code>namespace posix_error</code></td>
 143     <td><code>namespace errc</code></td>
 144   </tr>
 145   <tr>
 146     <td><code>enum posix_errno</code></td>
 147     <td><code>enum errc_t</code></td>
 148   </tr>
 149   <tr>
 150     <td><code>get_posix_category()</code></td>
 151     <td><code>generic_category()</code></td>
 152   </tr>
 153   <tr>
 154     <td><code>posix_category</code></td>
 155     <td><code>generic_category()</code></td>
 156   </tr>
 157   <tr>
 158     <td><code>errno_ecat</code></td>
 159     <td><code>generic_category()</code></td>
 160   </tr>
 161   <tr>
 162     <td><code>native_ecat</code></td>
 163     <td><code>system_category()</code></td>
 164   </tr>
 165 </table>
 166 <h2><a name="Breaking-changes">Breaking changes</a></h2>
 167 <p>Two static consts are replaced by functions. These are breaking changes best
 168 fixed by globally adding () to these names to turn them into function calls.</p>
 169 <table border="1" cellpadding="5" cellspacing="1" style="border-collapse: collapse" bordercolor="#111111">
 170   <tr>
 171     <td><b><i>Old usage, now broken</i></b></td>
 172     <td><b><i>Replacement</i></b></td>
 173   </tr>
 174   <tr>
 175     <td><code>generic_category</code></td>
 176     <td><code>generic_category()</code></td>
 177   </tr>
 178   <tr>
 179     <td><code>system_category</code></td>
 180     <td><code>system_category()</code></td>
 181   </tr>
 182   </table>
 183 <p>User-defined BOOST_POSIX_API and BOOST_WINDOWS_API macros are no longer supported.</p>
 184 <h2><a name="Header-error_code">Header &lt;boost/system/error_code.hpp&gt;</a></h2>
 185 <h3>&lt;boost/system/error_code.hpp&gt; synopsis</h3>
 186 <blockquote>
 187 <pre>namespace boost
 188 {
 189   namespace system
 190   {
 191     class <a href="#Class-error_category">error_category</a>;
 192     const error_category &amp;  <a href="#system_category">system_category</a>() noexcept;
 193     const error_category &amp;  <a href="#generic_category">generic_category</a>() noexcept;
 194
 195     class <a href="#Class-error_code">error_code</a>;
 196     class <a href="#Class-error_condition">error_condition</a>;
 197
 198     //  "Concept" helpers
 199     template< class T="" >
 200       struct is_error_code_enum { static const bool value = false; };
 201
 202     template< class T="" >
 203       struct is_error_condition_enum { static const bool value = false; };
 204
 205     //  generic error_conditions
 206     namespace errc
 207     {
 208       enum errc_t
 209       {
 210         success = 0,
 211         address_family_not_supported,   //EAFNOSUPPORT
 212         address_in_use,                 //EADDRINUSE
 213         address_not_available,          //EADDRNOTAVAIL
 214         already_connected,              //EISCONN
 215         argument_list_too_long,         //E2BIG
 216         argument_out_of_domain,         //EDOM
 217         bad_address,                    //EFAULT
 218         bad_file_descriptor,            //EBADF
 219         bad_message,                    //EBADMSG
 220         broken_pipe,                    //EPIPE
 221         connection_aborted,             //ECONNABORTED
 222         connection_already_in_progress, //EALREADY
 223         connection_refused,             //ECONNREFUSED
 224         connection_reset,               //ECONNRESET
 225         cross_device_link,              //EXDEV
 226         destination_address_required,   //EDESTADDRREQ
 227         device_or_resource_busy,        //EBUSY
 228         directory_not_empty,            //ENOTEMPTY
 229         executable_format_error,        //ENOEXEC
 230         file_exists,                    //EEXIST
 231         file_too_large,                 //EFBIG
 232         filename_too_long,              //ENAMETOOLONG
 233         function_not_supported,         //ENOSYS
 234         host_unreachable,               //EHOSTUNREACH
 235         identifier_removed,             //EIDRM
 236         illegal_byte_sequence,          //EILSEQ
 237         inappropriate_io_control_operation,//ENOTTY
 238         interrupted,                    //EINTR
 239         invalid_argument,               //EINVAL
 240         invalid_seek,                   //ESPIPE
 241         io_error,                       //EIO
 242         is_a_directory,                 //EISDIR
 243         message_size,                   //EMSGSIZE
 244         network_down,                   //ENETDOWN
 245         network_reset,                  //ENETRESET
 246         network_unreachable,            //ENETUNREACH
 247         no_buffer_space,                //ENOBUFS
 248         no_child_process,               //ECHILD
 249         no_link,                        //ENOLINK
 250         no_lock_available,              //ENOLCK
 251         no_message_available,           //ENODATA
 252         no_message,                     //ENOMSG
 253         no_protocol_option,             //ENOPROTOOPT
 254         no_space_on_device,             //ENOSPC
 255         no_stream_resources,            //ENOSR
 256         no_such_device_or_address,      //ENXIO
 257         no_such_device,                 //ENODEV
 258         no_such_file_or_directory,      //ENOENT
 259         no_such_process,                //ESRCH
 260         not_a_directory,                //ENOTDIR
 261         not_a_socket,                   //ENOTSOCK
 262         not_a_stream,                   //ENOSTR
 263         not_connected,                  //ENOTCONN
 264         not_enough_memory,              //ENOMEM
 265         not_supported,                  //ENOTSUP
 266         operation_canceled,             //ECANCELED
 267         operation_in_progress,          //EINPROGRESS
 268         operation_not_permitted,        //EPERM
 269         operation_not_supported,        //EOPNOTSUPP
 270         operation_would_block,          //EWOULDBLOCK
 271         owner_dead,                     //EOWNERDEAD
 272         permission_denied,              //EACCES
 273         protocol_error,                 //EPROTO
 274         protocol_not_supported,         //EPROTONOSUPPORT
 275         read_only_file_system,          //EROFS
 276         resource_deadlock_would_occur,  //EDEADLK
 277         resource_unavailable_try_again, //EAGAIN
 278         result_out_of_range,            //ERANGE
 279         state_not_recoverable,          //ENOTRECOVERABLE
 280         stream_timeout,                 //ETIME
 281         text_file_busy,                 //ETXTBSY
 282         timed_out,                      //ETIMEDOUT
 283         too_many_files_open_in_system,  //ENFILE
 284         too_many_files_open,            //EMFILE
 285         too_many_links,                 //EMLINK
 286         too_many_synbolic_link_levels,  //ELOOP
 287         value_too_large,                //EOVERFLOW
 288         wrong_protocol_type             //EPROTOTYPE
 289       };
 290
 291     } // namespace errc
 292
 293     template<> struct is_error_condition_enum<posix::posix_errno>&lt;errc::errc_t&gt;
 294       { static const bool value = true; };
 295
 296     //  <a href="#Non-member-functions">non-member functions</a>
 297
 298     bool operator==( const error_code &amp; lhs, const error_code &amp; rhs ) noexcept;
 299     bool operator==( const error_code &amp; code, const error_condition &amp; condition ) noexcept;
 300     bool operator==( const error_condition &amp; condition, const error_code &amp; code ) noexcept;
 301     bool operator==( const error_condition &amp; lhs, const error_condition &amp; rhs ) noexcept;
 302
 303     bool operator!=( const error_code &amp; lhs, const error_code &amp; rhs ) noexcept;
 304     bool operator!=( const error_code &amp; code, const error_condition &amp; condition ) noexcept;
 305     bool operator!=( const error_condition &amp; condition, const error_code &amp; code ) noexcept;
 306     bool operator!=( const error_condition &amp; lhs, const error_condition &amp; rhs ) noexcept;
 307
 308     bool operator&lt;( const error_code &amp; lhs, const error_code &amp; rhs ) noexcept;
 309     bool operator&lt;( const error_condition &amp; lhs, const error_condition &amp; rhs ) noexcept;
 310
 311     error_code make_error_code( errc::errc_t e ) noexcept;
 312     error_condition make_error_condition( errc::errc_t e ) noexcept;
 313
 314     template &lt;class charT, class traits&gt;
 315       std::basic_ostream&lt;charT,traits&gt;&amp;
 316         operator&lt;&lt;( basic_ostream&lt;charT,traits&gt;&amp; os, const error_code &amp; ec );
 317
 318     size_t hash_value( const error_code &amp; ec );
 319   }
 320 }</pre>
 321 </blockquote>
 322 <p>The value of each<code> errc_t</code> constant shall be the same as the
 323 value of the <code>&lt;cerrno&gt;</code> macro shown in the above synopsis.</p>
 324 <p>Users may specialize <code>is_error_code_enum</code> and <code>
 325 is_error_condition_enum</code> templates to indicate that a type is eligible for
 326 class <code>error_code</code> and <code>error_condition</code> automatic
 327 conversions respectively.</p>
 328
 329 <pre>const error_category &amp; <a name="system_category">system_category</a>();</pre>
 330 <blockquote>
 331   <p><i>Returns:</i> A reference to a <code>error_category</code> object
 332   identifying errors originating from the operating system.</p>
 333 </blockquote>
 334 <pre>const error_category &amp; <a name="generic_category">generic_category</a>();</pre>
 335 <blockquote>
 336   <p><i>Returns:</i> A reference to a <code>error_category</code> object
 337   identifying portable error conditions.</p>
 338 </blockquote>
 339
 340 <h2><a name="Class-error_category">Class <code>error_category</code></a></h2>
 341 <p>The class <code>error_category</code> defines the base class for types used
 342 to identify the source and encoding of a particular category of error code.</p>
 343 <p><i>[Note:</i> Classes may be derived from <code>error_category</code>
 344 to support additional categories of errors. <i>--end note]</i></p>
 345 <p>The class <code>error_category</code> serves as a base class for types used
 346 to identify the source and encoding of a particular category of error code.
 347 Classes may be derived from <code>error_category</code> to support categories of
 348 errors in addition to those defined in the Boost System library. Such classes
 349 shall behave as specified in this subclause. [<i> Note:</i> <code>error_category</code>
 350 objects are passed by reference, and two such objects are equal if they have the
 351 same address. This means that applications using custom <code>error_category</code>
 352 types should create a single object of each such type. <i>\97end note</i> ]</p>
 353 <h3><a name="Class-error_category-synopsis">Class <code>error_category</code> synopsis</a></h3>
 354 <blockquote>
 355 <pre>namespace boost
 356 {
 357   namespace system
 358   {
 359     class error_category : public noncopyable
 360     {
 361     public:
 362       virtual ~error_category();
 363
 364       virtual const char *     name() const noexcept = 0;
 365       virtual string           message( int ev ) const = 0;
 366       virtual error_condition  default_error_condition( int ev ) const noexcept;
 367       virtual bool             equivalent( int code, const error_condition &amp; condition )
 368                                  const noexcept;
 369       virtual bool             equivalent( const error_code &amp; code, int condition ) const noexcept;
 370
 371       bool operator==( const error_category &amp; rhs ) const noexcept;
 372       bool operator!=( const error_category &amp; rhs ) const noexcept;
 373       bool operator&lt; ( const error_category &amp; rhs ) const noexcept;
 374     };
 375   }
 376 }</pre>
 377 </blockquote>
 378 <h3><a name="Class-error_category-virtual-members">Class <code>error_category</code> virtual members</a></h3>
 379 <p>Classes derived from <code>error_category</code> shall behave as specified in
 380 this subclause.</p>
 381 <pre>virtual const char * name() const noexcept =0;</pre>
 382 <blockquote>
 383   <p><i>Returns: </i>a string naming the error category.</p>
 384 </blockquote>
 385 <pre>virtual string message( int ev ) const noexcept =0;</pre>
 386 <blockquote>
 387   <p><i>Returns:</i> A string that describes the error denoted by
 388   <code>ev</code>.</p>
 389 </blockquote>
 390 <pre>virtual error_condition default_error_condition( int ev ) const noexcept;</pre>
 391 <blockquote>
 392   <p><i>Returns:</i>&nbsp; <code>error_condition( ev, *this )</code>.</p>
 393   <blockquote>
 394     <p dir="ltr">&nbsp;[<i>--Note:</i> Derived classes will typically convert <code>ev</code>
 395     to some portable <code>error_category</code>, such as <code>generic_category()</code>,
 396     and return it as an <code>error_condition</code> for that category. <i>--end
 397     note</i>]</p>
 398   </blockquote>
 399   </blockquote>
 400 <pre>virtual bool equivalent( int code, const error_condition &amp; condition ) const noexcept;</pre>
 401 <blockquote>
 402   <p><i>Returns:</i> <code>default_error_condition( code ) == condition</code>.</p>
 403   </blockquote>
 404 <pre>virtual bool equivalent( const error_code &amp; code, int condition ) const noexcept;</pre>
 405 <blockquote>
 406   <p><i>Returns:</i> <code>*this == code.category() &amp;&amp; code.value() == condition</code>.</p>
 407   </blockquote>
 408 <h3><a name="Class-error_category-non-virtual-members">Class <code>error_category</code> non-virtual members</a></h3>
 409 <pre>bool operator==( const error_category &amp; rhs ) const noexcept;</pre>
 410 <blockquote>
 411 <p><i>Returns:</i> <code>this == &amp;rhs</code>.</p>
 412 </blockquote>
 413 <pre>bool operator!=( const error_category &amp; rhs ) const noexcept;</pre>
 414 <blockquote>
 415 <p><i>Returns:</i> <code>this != &amp;rhs</code>.</p>
 416 </blockquote>
 417
 418 <pre>bool operator&lt;( const error_category &amp; rhs ) const noexcept;</pre>
 419 <blockquote>
 420   <p><i>Returns:</i> <code>std::less&lt;const error_category*&gt;()( this, &amp;rhs&nbsp;
 421   noexcept)</code>.</p>
 422   <blockquote>
 423     <p><i>[Note:</i> <code>std::less</code> provides a total ordering for
 424     pointers. <i>--end note]</i></p>
 425   </blockquote>
 426 </blockquote>
 427 <h2><a name="Class-error_code">Class <code>
 428 error_code</code></a></h2>
 429 <p>The class <code>error_code</code> describes an object used to hold error code
 430 values, such as those originating from the operating<br>
 431 system or other low-level application program interfaces. <i>[ Note: </i>Class
 432 <code>error_code</code> is an adjunct to error reporting by<br>
 433 exception. <i>\97end note ]</i></p>
 434 <h3><a name="Class-error_code-synopsis">Class <code>
 435 error_code</code> synopsis</a></h3>
 436 <blockquote>
 437 <pre>namespace boost
 438 {
 439   namespace system
 440   {
 441     class error_code {
 442     public:
 443
 444       // constructors:
 445       error_code() noexcept;
 446       error_code( val, const error_category &amp; cat ) noexcept;
 447       template &lt;class <code>ErrorCodeEnum</code>&gt;
 448         error_code(<code> ErrorCodeEnum</code> e ) noexcept;
 449
 450       // modifiers:
 451       void assign( int val, const error_category &amp; cat ) noexcept;
 452       template&lt;typename <code>ErrorCodeEnum</code>&gt;
 453         error_code &amp; operator=( <code>ErrorCodeEnum</code> val ) noexcept;
 454       void clear() noexcept;
 455
 456       // observers:
 457       int                    value() const noexcept;
 458       cont error_category &amp;  category() const noexcept;
 459       error_condition        default_error_condition() const noexcept;
 460       string                 message() const;
 461       operator unspecified-bool-type() const;
 462
 463     private:
 464       int val_;                     // <i>exposition only</i>
 465       const error_category * cat_;  // <i>exposition only</i>
 466     };
 467   }
 468 }</pre>
 469 </blockquote>
 470 <h3><a name="Class-error_code-constructors">Class <code>
 471 error_code</code> constructors</a></h3>
 472 <pre>error_code() noexcept;</pre>
 473 <blockquote>
 474   <p><i>Effects: </i>Constructs an object of type <code>error_code</code>.</p>
 475   <p><i>Postconditions:</i> <code>val_ == 0 &amp;&amp; cat_ == &amp;system_category()</code>.</p>
 476 </blockquote>
 477 <pre>error_code( int val, const error_category &amp; cat ) noexcept;</pre>
 478 <blockquote>
 479   <p><i>Effects: </i>Constructs an object of type <code>error_code</code>.</p>
 480   <p><i>Postconditions:</i> <code>val_ == val &amp;&amp; cat_ == &amp;cat</code>.</p>
 481 </blockquote>
 482 <pre>template &lt;class <code>ErrorCodeEnum</code>&gt;
 483   error_code(<code> ErrorCodeEnum</code> val ) noexcept;</pre>
 484 <blockquote>
 485   <p><i>Effects: </i>Constructs an object of type <code>error_code</code>.</p>
 486   <p><i>Postconditions:</i> <code>*this == make_error_code( val )</code>.</p>
 487   <p><i>Remarks:</i> This constructor shall not participate in overload
 488   resolution unless <code>is_error_code_enum&lt;ErrorCodeEnum&gt;::value</code> is
 489   <code>true</code>.</p>
 490 </blockquote>
 491 <h3><a name="Class-error_code-modifiers">Class <code>
 492 error_code</code> modifiers</a></h3>
 493 <pre>void assign( int val, const error_category &amp; cat ) noexcept;</pre>
 494 <blockquote>
 495   <p><i>Postconditions:</i> <code>val_ == val &amp;&amp; cat_ == &amp;cat</code>.</p>
 496 </blockquote>
 497 <pre>template&lt;typename <code>ErrorCodeEnum</code>&gt;
 498   error_code &amp; operator=( <code>ErrorCodeEnum</code> val ) noexcept;</pre>
 499 <blockquote>
 500   <p><i>Postconditions:</i> <code>*this == make_error_code( val )</code>.</p>
 501   <p><i>Remarks:</i> This operator shall not participate in overload resolution
 502   unless <code>is_error_code_enum&lt;ErrorCodeEnum&gt;::value</code> is <code>true</code>.</p>
 503 </blockquote>
 504 <pre><code>void clear() noexcept;</code></pre>
 505 <blockquote>
 506   <p><i>postcondition:</i> <code>value() == 0 &amp;&amp; category() ==
 507   system_category()</code></p>
 508 </blockquote>
 509   <h3><a name="Class-error_code-observers">Class <code>
 510 error_code</code> observers</a></h3>
 511   <pre><code>int value() const noexcept;</code></pre>
 512 <blockquote>
 513 <p><i>Returns:</i> <code>val_</code>.</p>
 514   </blockquote>
 515 <pre><code>const error_category &amp; category() const noexcept;</code></pre>
 516 <blockquote>
 517 <p><i>Returns:</i> <code>*cat_</code>.</p>
 518   </blockquote>
 519   <pre>error_condition default_error_condition() const noexcept;</pre>
 520 <blockquote>
 521 <p><i>Returns:</i>&nbsp; <code>category().default_error_condition( value())</code>.</p>
 522 </blockquote>
 523   <pre><code>string message() const;</code></pre>
 524 <blockquote>
 525 <p><i>Returns:</i>&nbsp; <code>category().message( value())</code>.</p>
 526   <p><i>Throws:</i> Nothing.</p>
 527 </blockquote>
 528 <pre>operator unspecified-bool-type() const;</pre>
 529 <blockquote>
 530 <p><i>Returns:</i> if <code>value() != 0</code>, returns a value that will evaluate
 531 <code>true</code> in a boolean context; otherwise, returns a value that will
 532 evaluate <code>false</code> in a boolean context. The value type returned shall
 533 not be convertible to <code>int</code>.</p>
 534 <p><i>Throws:</i> nothing.</p>
 535 <p><i>[Note: </i>This conversion can be used in contexts where a <code>bool</code>
 536 is expected ( e.g., an <code>if</code> condition ); however, implicit conversions
 537 ( e.g., to <code>int</code>) that can occur with <code>bool</code> are not
 538 allowed, eliminating some sources of user error. One possible implementation
 539 choice for this type is pointer-to-member. <i>--end note ]</i></p>
 540 </blockquote>
 541 <h2><a name="Class-error_condition">Class <code>error_condition</code></a></h2>
 542 <p>The class <code>error_condition</code> describes an object used to hold
 543 values identifying error conditions. <i>[ Note: </i><code>error_condition</code>
 544 values are portable abstractions, while <code>error_code</code> values are
 545 implementation specific. <i>--end note ]</i></p>
 546 <h3><a name="Class-error_condition-synopsis">Class <code>error_condition</code> synopsis</a></h3>
 547 <blockquote>
 548 <pre>namespace boost
 549 {
 550   namespace system
 551   {
 552     class error_condition
 553     {
 554     public:
 555
 556       // constructors:
 557       error_condition() noexcept;
 558       error_condition( int val, const error_category &amp; cat ) noexcept;
 559       template &lt;class ErrorConditionEnum&gt;
 560         error_condition( errorConditionEnum val ) noexcept;
 561
 562       // modifiers:
 563       void assign( int val, const error_category &amp; cat ) noexcept;
 564       template&lt;typename ErrorConditionEnum&gt;
 565         error_condition &amp; operator=( ErrorConditionEnum val ) noexcept;
 566       void clear() noexcept;
 567
 568       // observers:
 569       int value() const noexcept;
 570       const error_category &amp; category() const noexcept;
 571       string message() const;
 572       operator unspecified-bool-type () const noexcept;
 573
 574     private:
 575       int val_;                      // <i>exposition only</i>
 576       const error_category * cat_;   // <i>exposition only</i>
 577     };
 578   }
 579 }</pre>
 580 </blockquote>
 581 <h3><a name="Class-error_condition-constructors">Class <code>error_condition</code>
 582 constructors</a></h3>
 583 <pre>error_condition() noexcept; </pre>
 584 <blockquote>
 585   <p><i>Effects:</i> Constructs an object of type <code>error_condition</code>.</p>
 586   <p><i>Postconditions:</i> <code>val_ == 0 and cat_ == &amp;generic_category()</code>.</p>
 587 </blockquote>
 588 <pre>error_condition( int val, const error_category &amp; cat ) noexcept;</pre>
 589 <blockquote>
 590   <p><i>Effects: </i>Constructs an object of type error_condition.</p>
 591   <p><i>Postconditions:</i> <code>val_ == val and cat_ == &amp;cat</code>.</p>
 592 </blockquote>
 593 <pre>template &lt;class ErrorConditionEnum&gt;
 594   error_condition( ErrorConditionEnum e ) noexcept;</pre>
 595 <blockquote>
 596   <p><i>Effects:</i> Constructs an object of type <code>error_condition</code>.</p>
 597   <p><i>Postconditions:</i> <code>*this == make_error_condition(e)</code>.</p>
 598   <p><i>Remarks:</i> This constructor shall not participate in overload
 599   resolution unless <code>is_error_condition_enum&lt;ErrorConditionEnum&gt;::value</code>
 600   is <code>true</code>.</p>
 601 </blockquote>
 602 <h3><a name="Class-error_condition-modifiers">Class <code>error_condition</code>
 603 modifiers</a></h3>
 604 <pre>void assign( int val, const error_category &amp; cat ) noexcept; </pre>
 605 <blockquote>
 606   <p><i>Postconditions:</i> <code>val_ == val and cat_ == &amp;cat</code>. </p>
 607 </blockquote>
 608 <pre>template&lt;typename ErrorConditionEnum&gt;
 609   error_condition &amp; operator=( ErrorConditionEnum e ) noexcept;</pre>
 610 <blockquote>
 611   <p><i>Postconditions:</i> <code>*this == make_error_condition( e )</code>.</p>
 612   <p><i>Returns:</i> <code>*this</code>.</p>
 613   <p><i>Remarks:</i> This operator shall not participate in overload resolution
 614   unless <code>is_error_condition_enum&lt;ErrorConditionEnum&gt;::value</code> is
 615   <code>true</code>.</p>
 616 </blockquote>
 617 <pre>void clear() noexcept;</pre>
 618 <blockquote>
 619   <p><i>Postcondition:</i> <code>value() == 0 &amp;&amp; category() == generic_category()</code></p>
 620 </blockquote>
 621 <h3><a name="Class-error_condition-observers">Class <code>error_condition</code>
 622 observers</a></h3>
 623 <pre>int value() const noexcept;</pre>
 624 <blockquote>
 625   <p><i>Returns:</i> <code>val_</code>.</p>
 626 </blockquote>
 627 <pre>const error_category &amp; category() const noexcept;</pre>
 628 <blockquote>
 629   <p><i>Returns:</i> <code>*cat_</code>.</p>
 630 </blockquote>
 631 <pre>string message() const;</pre>
 632 <blockquote>
 633   <p><i>Returns:</i> <code>category().message( value() )</code>.</p>
 634 </blockquote>
 635 <pre>operator unspecified-bool-type () const;</pre>
 636 <blockquote>
 637   <p><i>Returns: </i>If <code>value() != 0</code>, returns a value that will
 638   evaluate <code>true</code> in a boolean context; otherwise, returns a value
 639   that will evaluate <code>false</code>. The return type shall not be
 640   convertible to <code>int</code>. </p>
 641   <p><i>Throws:</i> Nothing.</p>
 642   <p><i>&nbsp;[ Note:</i> This conversion can be used in contexts where a <code>bool</code>
 643   is expected ( e.g., an if condition ); however, implicit conversions ( e.g., to
 644   <code>int</code>) that can occur with <code>bool</code> are not allowed,
 645   eliminating some sources of user error. One possible implementation choice for
 646   this type is pointer to member. <i>--end note</i> <i>]</i></p>
 647 </blockquote>
 648   <h2><a name="throws-object"><code>throws</code> object</a></h2>
 649   <pre>extern error_code throws;</pre>
 650 <p>The predefined <code>error_code</code> object <code>throws</code> is supplied
 651 for use as a &quot;throw on error&quot; tag.</p>
 652 <h2><a name="Semantics-of-throws">Semantics of <code>throws</code></a> object</h2>
 653 <p>Functions that specify an argument in the form <code>error_code&amp; ec=throws</code>,
 654 with appropriate namespace qualifiers, have the following error handling
 655 semantics:</p>
 656 <blockquote>
 657   <p><i>Postconditions:</i></p>
 658   <blockquote>
 659     <p>If <code>&amp;ec != &amp;throws</code> and an error occurred:</p>
 660     <ul>
 661       <li> <code>ec.value()</code> returns the implementation specific error
 662       number for the particular error that occurred.</li>
 663       <li><code>ec.category()</code> returns the <code>
 664     <a href="#Class-error_category">error_category</a></code> for <code>ec.value()</code>.</li>
 665     </ul>
 666     <p>if <code>&amp;ec != &amp;throws</code> and an error did not occur, <code>ec.clear()</code>.</p>
 667   </blockquote>
 668   <p><i>Throws:</i></p>
 669   <blockquote>
 670   <p>If an error occurs and <code>&amp;ec == &amp;throws</code>, throws an exception of type
 671   <code><a href="#Class-system_error">system_error</a></code> or of a type
 672   derived from <code><a href="#Class-system_error">system_error</a></code>. The
 673   exception's <code>code()</code> member function returns a reference to an
 674   <code>error_code</code> object with the behavior specified in <i>
 675   Postconditions</i>.</p>
 676   </blockquote>
 677 </blockquote>
 678 <h2><a name="Non-member-functions">Non-member functions</a></h2>
 679   <pre>bool operator==( const error_code &amp; lhs, const error_code &amp; rhs ) noexcept;</pre>
 680 <blockquote>
 681   <p><i>Returns:</i> <code>lhs.category() == rhs.category() &amp;&amp; lhs.value() ==
 682   rhs.value()</code>.</p>
 683 </blockquote>
 684 <pre>bool operator==( const error_code &amp; code, const error_condition &amp; condition ) noexcept;
 685 bool operator==( const error_condition &amp; condition, const error_code &amp; code ) noexcept;</pre>
 686 <blockquote>
 687   <p><i>Returns:</i> <code>code.category().equivalent( code.value(), condition )<br>
 688   || condition.category().equivalent( code, condition.value() )</code>.</p>
 689 </blockquote>
 690 <pre>bool operator==( const error_condition &amp; lhs, const error_condition &amp; rhs ) noexcept;</pre>
 691 <blockquote>
 692   <p><i>Returns:</i> <code>lhs.category() == rhs.category() &amp;&amp; lhs.value() ==
 693   rhs.value()</code>.</p>
 694 </blockquote>
 695 <pre>bool operator!=( const error_code &amp; lhs, const error_code &amp; rhs ) noexcept;</pre>
 696 <blockquote>
 697   <p><i>Returns:</i> <code>!(lhs == rhs )</code>.</p>
 698 </blockquote>
 699 <pre>bool operator!=( const error_code &amp; code, const error_condition &amp; condition ) noexcept;
 700 bool operator!=( const error_condition &amp; condition, const error_code &amp; code ) noexcept;</pre>
 701 <blockquote>
 702   <p><i>Returns:</i><code> !( code ==&nbsp; condition )</code>.</p>
 703 </blockquote>
 704 <pre>bool operator!=( const error_condition &amp; lhs, const error_condition &amp; rhs ) noexcept;</pre>
 705 <blockquote>
 706   <p><i>Returns:</i> <code>!(lhs == rhs )</code>.</p>
 707 </blockquote>
 708 <pre>bool operator&lt;( const error_code &amp; lhs, const error_code &amp; rhs ) noexcept;</pre>
 709 <blockquote>
 710   <p><i>Returns:</i> <code>lhs.category() &lt; rhs.category()<br>
 711   &nbsp; || (lhs.category() == rhs.category() &amp;&amp; lhs.value() &lt; rhs.value())</code>.</p>
 712 </blockquote>
 713 <pre>bool operator&lt;( const error_condition &amp; lhs, const error_condition &amp; rhs ) noexcept;</pre>
 714 <blockquote>
 715   <p><i>Returns:</i> <code>lhs.category() &lt; rhs.category()<br>
 716   &nbsp; || (lhs.category() == rhs.category() &amp;&amp; lhs.value() &lt; rhs.value())</code>.</p>
 717 </blockquote>
 718 <pre>error_code make_error_code( errc::errc_t e ) noexcept;</pre>
 719 <blockquote>
 720   <p><i>Returns:</i> <code>error_code( e, generic_category())</code>.</p>
 721 </blockquote>
 722 <pre>error_condition make_error_condition( errc::errc_t e ) noexcept;</pre>
 723 <blockquote>
 724   <p><i>Returns:</i> <code>error_condition( static_cast&lt;int&gt;( e ), generic_category())</code>.</p>
 725 </blockquote>
 726
 727 <pre>template &lt;class charT, class traits&gt;
 728   std::basic_ostream&lt;charT,traits&gt;&amp;
 729     operator&lt;&lt;( basic_ostream&lt;charT,traits&gt;&amp; os, const error_code &amp; ec );</pre>
 730 <blockquote>
 731 <p><i>Effects:</i> <code>os &lt;&lt; ec.category().name() &lt;&lt; ':' &lt;&lt; ec.value()</code>.</p>
 732 <p><i>Returns:</i> <code>os</code>.</p>
 733 </blockquote>
 734 <pre>size_t <a name="hash_value">hash_value</a>( const error_code &amp; ec );</pre>
 735 <blockquote>
 736   <p><i>Returns: </i>&nbsp;A hash value representing <code>ec</code>.</p>
 737 </blockquote>
 738
 739 <h2><a name="Header-system_error">Header &lt;boost/system/system_error.hpp&gt;</a></h2>
 740
 741 <h3><a name="Class-system_error">Class <code>
 742 system_error</code></a></h3>
 743 <p>The class <code>system_error</code> describes an exception object used to
 744 report errors that have an associated <code><a href="#Class-error_code">error_code</a></code>. Such errors typically originate from operating system or other low-level
 745 application program interfaces.</p>
 746 <blockquote>
 747 <pre>namespace boost
 748 {
 749   namespace system
 750   {
 751     class system_error : public std::runtime_error
 752     {
 753     public:
 754       system_error( error_code ec );
 755       system_error( error_code ec, const char * what_arg );
 756       system_error( error_code ec, const std::string &amp; what_arg );
 757       system_error( int ev, const error_category &amp; ecat,
 758                     const char * what_arg );
 759       system_error( int ev, const error_category &amp; ecat,
 760                     const std::string &amp; what_arg );
 761       system_error( int ev, const error_category &amp; ecat);
 762
 763       const error_code &amp; code() const throw();
 764       const char *       what() const throw();
 765     };
 766   }
 767 }</pre>
 768 </blockquote>
 769 <pre>system_error( error_code ec );</pre>
 770 <blockquote>
 771   <p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
 772   <p><i>Postcondition:</i> <code>code() == ec <br>
 773 &nbsp; &amp;&amp; std::strcmp( this-&gt;runtime_error::what(), &quot;&quot; ) == 0</code></p>
 774 </blockquote>
 775 <pre>system_error( error_code ec, const char * what_arg );</pre>
 776 <blockquote>
 777   <p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
 778   <p><i>Postcondition:</i> <code>code() == ec <br>
 779 &nbsp; &amp;&amp; std::strcmp( this-&gt;runtime_error::what(), what_arg ) == 0</code></p>
 780 </blockquote>
 781 <pre>system_error( error_code ec, const std::string &amp; what_arg );</pre>
 782 <blockquote>
 783   <p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
 784   <p><i>Postcondition:</i> <code>code() == ec <br>
 785 &nbsp; &amp;&amp; std::strcmp( this-&gt;runtime_error::what(), what_arg.c_str() ) == 0</code></p>
 786 </blockquote>
 787 <pre>system_error( int ev, const error_category &amp; ecat,
 788              const char * what_arg );</pre>
 789 <blockquote>
 790   <p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
 791   <p><i>Postcondition:</i> <code>code() == error_code( ev, ecat )<br>
 792 &nbsp; &amp;&amp; std::strcmp( this-&gt;runtime_error::what(), what_arg ) == 0</code></p>
 793 </blockquote>
 794 <pre>system_error( int ev, const error_category &amp; ecat,
 795              const std::string &amp; what_arg );</pre>
 796 <blockquote>
 797   <p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
 798   <p><i>Postcondition:</i> <code>code() == error_code( ev, ecat )<br>
 799 &nbsp; &amp;&amp; std::strcmp( this-&gt;runtime_error::what(), what_arg.c_str() ) == 0</code></p>
 800 </blockquote>
 801 <pre>system_error( int ev, const error_category &amp; ecat );</pre>
 802 <blockquote>
 803   <p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
 804   <p><i>Postcondition:</i> <code>code() == error_code( ev, ecat )<br>
 805 &nbsp; &amp;&amp; std::strcmp( this-&gt;runtime_error::what(), &quot;&quot; ) == 0</code></p>
 806 </blockquote>
 807 <pre>const error_code &amp; code() const;</pre>
 808 <blockquote>
 809   <p><i>Returns:</i> <code>ec</code> or <code>error_code( ev, ecat )</code>, from
 810   the constructor, as appropriate.</p>
 811 </blockquote>
 812 <pre>const char * what() const;</pre>
 813 <blockquote>
 814   <p><i>Returns: </i>A string incorporating <code>
 815   this-&gt;runtime_error::what()</code> and <code>
 816   code.message()</code>.</p>
 817 </blockquote>
 818 <hr>
 819
 820 <p>Revised
 821 <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%B %d, %Y" startspan -->January 06, 2014<!--webbot bot="Timestamp" endspan i-checksum="31400" --> </font>
 822 </p>
 823
 824 <p>© Copyright Beman Dawes, 2006, 2007, 2008, 2013</p>
 825
 826 <p>Distributed under the Boost Software License, Version 1.0. See
 827 <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
 828
 829 </body>
 830
 831 </html>