/Src/Dependencies/Boost/libs/system/doc/reference.html

http://hadesmem.googlecode.com/ · HTML · 853 lines · 812 code · 41 blank · 0 comment · 0 complexity · d4562ea592c2afe1758955d732537dc4 MD5 · raw file

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