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