forked from boostorg/system
Replace docs with up-to-date contents, design
[SVN r39270]
This commit is contained in:
Beman Dawes
@@ -1,270 +0,0 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<title>Boost class error_code documentation
|
||||
</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF">
|
||||
|
||||
<h1>Header <a href="../../../boost/system/error_code.hpp">boost/system/error_code.hpp</a></h1>
|
||||
<p><a href="#Introduction">Introduction</a><br>
|
||||
<a href="#Synopsis">Synopsis</a><br>
|
||||
<a href="#Class-error_category">Class <code>error_category</code></a><br>
|
||||
<a href="#Class-error_category-members">Members</a><br>
|
||||
<a href="#Class-error_code">Class <code>error_code</code></a><br>
|
||||
<a href="#Class-error_code-members">Members</a><br>
|
||||
<a href="#Non-member">Non-member functions</a><br>
|
||||
<a href="#Acknowledgements">Acknowledgments</a></p>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>This header provides components used to report errors from the operating
|
||||
system or other low-level application program interface (API). It is based on the <i>Diagnostics</i> portion of the TR2 filesystem
|
||||
proposal.</p>
|
||||
<p>Class <code><a href="#Class-error_code">error_code</a></code> encapsulates an error
|
||||
code, usually one returned by an API. Class <code>
|
||||
<a href="#Class-error_category-members">error_category</a></code> encapsulates
|
||||
an identifier for a
|
||||
particular kind of error code. Users or
|
||||
third-parties may add additional error categories.</p>
|
||||
<h2>Builds</h2>
|
||||
<p>The system library is required by default. If the preprocessor macro name
|
||||
BOOST_ERROR_CODE_HEADER_ONLY is defined, no object library or shared/DLL library
|
||||
is required. Only one translation unit may defined BOOST_ERROR_CODE_HEADER_ONLY,
|
||||
otherwise symbols will be multiply defined.</p>
|
||||
<h2><a name="Synopsis">Synopsis</a></h2>
|
||||
<pre>namespace boost
|
||||
{
|
||||
namespace system
|
||||
{
|
||||
class error_code;
|
||||
|
||||
typedef int (*errno_decoder)( const error_code & );
|
||||
typedef std::string (*message_decoder)( const error_code & );
|
||||
typedef wstring_t (*wmessage_decoder)( const error_code & );
|
||||
|
||||
class error_category : public <a href="../../utility/doc/identifier.html">identifier</a>< uint_least32_t, error_category >
|
||||
{
|
||||
public:
|
||||
error_category();
|
||||
explicit error_category( value_type v );
|
||||
};
|
||||
|
||||
const error_category errno_ecat = <i>unspecified-value</i>;
|
||||
const error_category native_ecat = <i>unspecified-value</i>;
|
||||
|
||||
class error_code
|
||||
{
|
||||
public:
|
||||
typedef boost::int_least32_t value_type;
|
||||
|
||||
// constructors:
|
||||
<a href="#error_code">error_code</a>();
|
||||
<a href="#error_code-2">error_code</a>( value_type val, error_category cat );
|
||||
void <a href="#error_code-assign">assign</a>(value_type val, error_category cat);
|
||||
|
||||
// observers:
|
||||
value_type <a href="#value">value</a>() const;
|
||||
error_category <a href="#category">category</a>() const;
|
||||
int <a href="#to_errno">to_errno</a>() const; // name chosen to limit surprises
|
||||
// see Kohlhoff June 28 '06 boost posting
|
||||
std::string <a href="#message">message</a>() const;
|
||||
std::wstring <a href="#wmessage">wmessage</a>() const;
|
||||
|
||||
// relationals:
|
||||
bool <a href="#operator-eq">operator==</a>( const error_code & rhs ) const;
|
||||
bool <a href="#operator-ne">operator!=</a>( const error_code & rhs ) const;
|
||||
bool <a href="#operator-lt">operator<</a> ( const error_code & rhs ) const;
|
||||
bool <a href="#operator-le">operator<=</a>( const error_code & rhs ) const;
|
||||
bool <a href="#operator-gt">operator></a> ( const error_code & rhs ) const;
|
||||
bool <a href="#operator-ge">operator>=</a>( const error_code & rhs ) const;
|
||||
|
||||
<a href="#operator-unspecified-bool-type">operator <i>unspecified-bool-type</i></a>() const;
|
||||
bool <a href="#operator-bang">operator!</a>() const;
|
||||
|
||||
// statics:
|
||||
static error_category <a href="#new_category">new_category</a>( errno_decoder ed = 0,
|
||||
message_decoder md = 0, wmessage_decoder wmd = 0 );
|
||||
static bool <a href="#get_decoders">get_decoders</a>( error_category cat, errno_decoder & ed,
|
||||
message_decoder & md, wmessage_decoder & wmd );
|
||||
|
||||
};
|
||||
|
||||
std::size_t <a href="#hash_value">hash_value</a>( const error_code & ec );
|
||||
|
||||
} // namespace system
|
||||
} // namespace boost</pre>
|
||||
<h2><a name="Class-error_category">Class <code>error_category</code></a></h2>
|
||||
<p>Class <code><a href="#Class-error_category-members">error_category</a></code>
|
||||
encapsulates an identifier for a
|
||||
particular kind of error code. Users or
|
||||
third-parties may add additional error categories.</p>
|
||||
<p>For inherited members, see <a href="../../utility/doc/identifier.html">
|
||||
identifier documentation</a>.</p>
|
||||
<h3><a name="Class-error_category-members">Class <code>error_category</code>
|
||||
members</a></h3>
|
||||
<pre>error_category();</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of class <code>error_category</code>.</p>
|
||||
<p><i>Postcondition:</i> <code>value() == value_type()</code>.</p>
|
||||
</blockquote>
|
||||
<pre>explicit error_category( value_type v );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of class <code>error_category</code>.</p>
|
||||
<p><i>Postcondition:</i> <code>value() == v</code>.</p>
|
||||
</blockquote>
|
||||
<h2><a name="Class-error_code">Class <code>error_code</code></a></h2>
|
||||
<p>The value contained by an <code>error_code</code> object is the underlying
|
||||
API error code itself if the API error code type can be stored in <code>
|
||||
value_type</code> without loss of any actual values and if 0 represents no
|
||||
error. Otherwise, the value is an integer that maps to the API error code, with
|
||||
the exact method of mapping unspecified.</p>
|
||||
<h3><a name="Class-error_code-members">Class <code>error_code</code> members</a></h3>
|
||||
<pre><a name="error_code">error_code</a>();</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of class <code>error_code</code>.</p>
|
||||
<p><i>Postcondition:</i> <code>value() == 0 && category() == errno_ecat</code>.</p>
|
||||
</blockquote>
|
||||
<pre><a name="error_code-2">error_code</a>( value_type val, error_category cat );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of class <code>error_code</code>.</p>
|
||||
<p><i>Postcondition:</i> <code>value() == val && category() == cat</code>.</p>
|
||||
</blockquote>
|
||||
<pre>void <a name="error_code-assign">assign</a>(value_type val, error_category cat);</pre>
|
||||
<blockquote>
|
||||
<p><i>Postconditions:</i> <code>value() == val && category() == cat</code>.</p>
|
||||
</blockquote>
|
||||
<pre>value_type <a name="value">value</a>() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>value()</code> as specified by <i>postconditions</i> of the most
|
||||
recent <code>assign</code>, if any, or of the constructor.</p>
|
||||
</blockquote>
|
||||
<pre>error_category <a name="category">category</a>() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>category()</code> as specified by <i>postconditions</i> of the most
|
||||
recent <code>assign</code>, if any, or of the constructor.</p>
|
||||
</blockquote>
|
||||
<pre>int <a name="to_errno">to_errno</a>() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects: </i> <code>errno_decoder ed;<br>
|
||||
message_decoder md;<br>
|
||||
wmessage_decoder wmd;<br>
|
||||
bool ok( get_decoders( category(), ed, md,
|
||||
wmd ) );</code></p>
|
||||
<p><i>Returns:</i> If <code>ok && ed</code>, <code>ed(*this)</code>,
|
||||
otherwise <code>EOTHER</code>.</p>
|
||||
<p><i>[Note:</i> The intent is to return the <a href="http://www.unix.org/single_unix_specification/">
|
||||
ISO/IEC 9945:2003, <i>Portable Operating System Interface (POSIX)</i></a> error
|
||||
number that the implementation determines most closely corresponds to <code>
|
||||
value()</code>. <i>--end note.]</i></p>
|
||||
</blockquote>
|
||||
<pre>std::string <a name="message">message</a>() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects: </i> <code>errno_decoder ed;<br>
|
||||
message_decoder md;<br>
|
||||
wmessage_decoder wmd;<br>
|
||||
bool ok( get_decoders( category(), ed, md,
|
||||
wmd ) );</code></p>
|
||||
<p><i>Returns:</i> If <code>ok && md</code>, <code>md(*this)</code>,
|
||||
otherwise <code>std::string()</code>.</p>
|
||||
<p><i>Remarks:</i> If <code>category() == errno_ec</code>, the string is as
|
||||
returned by <code>strerror()</code>. Otherwise, the method used by the
|
||||
implementation to determine the string is unspecified.</p>
|
||||
<p><i>[Note:</i> The intent is to return a locale sensitive string that describes the error
|
||||
corresponding to <code>value()</code>. <i>--end note.]</i></p>
|
||||
</blockquote>
|
||||
<pre>wstring_t <a name="wmessage">wmessage</a>() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects: </i> <code>errno_decoder ed;<br>
|
||||
message_decoder md;<br>
|
||||
wmessage_decoder wmd;<br>
|
||||
bool ok( get_decoders( category(), ed, md,
|
||||
wmd ) );</code></p>
|
||||
<p><i>Returns:</i> If <code>ok && wmd</code>, <code>wmd(*this)</code>,
|
||||
otherwise <code>std::wstring()</code>.</p>
|
||||
<p><i>Remarks:</i> If <code>category() == errno_ec</code>, the string is as
|
||||
returned by <code>strerror()</code>. Otherwise, the method used by the
|
||||
implementation to determine the string is unspecified.</p>
|
||||
<p><i>[Note:</i> The intent is to return a locale sensitive string that describes the error
|
||||
corresponding to <code>value()</code>. <i>--end note.]</i></p>
|
||||
</blockquote>
|
||||
<pre>bool <a name="operator-eq">operator</a>==(const error_code & rhs) const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>value() == rhs.value() && category() == rhs.category()</code>.</p>
|
||||
</blockquote>
|
||||
<pre>bool <a name="operator-ne">operator!</a>=(const error_code & rhs) const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>!(*this == rhs)</code>.</p>
|
||||
</blockquote>
|
||||
<pre>bool <a name="operator-lt">operator</a><(const error_code & rhs) const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>category() < rhs.category() || ( category() ==
|
||||
rhs.category() && value() < rhs.value() )</code>.</p>
|
||||
</blockquote>
|
||||
<pre>bool <a name="operator-le">operator</a><=(const error_code & rhs) const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>*this == rhs || *this < rhs</code>.</p>
|
||||
</blockquote>
|
||||
<pre>bool <a name="operator-gt">operator</a>>(const error_code & rhs) const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>!(*this <= rhs)</code>.</p>
|
||||
</blockquote>
|
||||
<pre>bool <a name="operator-ge">operator</a>>=(const error_code & rhs) const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>!(*this < rhs)</code>.</p>
|
||||
</blockquote>
|
||||
<pre><a name="operator-unspecified-bool-type">operator <i>unspecified-bool-type</i></a>() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code> value() != value_type() ? <i>unspecified-bool-type</i>
|
||||
: 0</code>.</p>
|
||||
<p><i>Throws:</i> nothing.</p>
|
||||
<p>[ <i>Note: </i>This conversion can be used in contexts where a <code>bool</code>
|
||||
is expected (e.g., an <code>if</code> condition); however, implicit conversions
|
||||
(e.g., to <code>int</code>) that can occur with <code>bool</code> are not
|
||||
allowed, eliminating some sources of user error. One possible implementation
|
||||
choice for this type is pointer-to-member. <i><EFBFBD>end note </i>]</p>
|
||||
</blockquote>
|
||||
<pre>bool <a name="operator-bang">operator!</a>() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code> value() == value_type()</code>.</p>
|
||||
</blockquote>
|
||||
<pre>static error_category <a name="new_category">new_category</a>( errno_decoder ed = 0, message_decoder md = 0, wmessage_decoder wmd = 0 );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs a new <code>error_category</code> object.<code>
|
||||
</code>Creates an association between the object and <code>ed</code>,
|
||||
<code>md</code>, and <code>wmd</code>.</p>
|
||||
<p><i>Returns:</i> The object.</p>
|
||||
</blockquote>
|
||||
<pre>static bool <a name="get_decoders">get_decoders</a>( error_category cat, errno_decoder & ed, message_decoder & md, wmessage_decoder & wmd );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> If <code>cat</code> was created by <code>new_category()</code>,
|
||||
sets <code>ed</code>, <code>md</code>, and <code>wmd</code>
|
||||
to the respective values associated with <code>cat</code> by <code>
|
||||
new_category()</code>. Otherwise, no effects.</p>
|
||||
<p><i>Returns:</i> If <code>cat</code> was created by <code>new_category()</code>,
|
||||
<code>true</code>, otherwise <code>false</code>.</p>
|
||||
</blockquote>
|
||||
<h2><a name="Non-member">Non-member</a> functions</h2>
|
||||
<pre>std::size_t <a name="hash_value">hash_value</a>( const error_code & ec );</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns: </i> A hash value representing <code>ec</code>.</p>
|
||||
</blockquote>
|
||||
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
|
||||
<p>Christopher Kohlhoff and Peter Dimov made important contributions to the
|
||||
design. Comments and suggestions were also received from Pavel Vozenilek,
|
||||
Gennaro Prota, Dave Abrahams, Jeff Garland, Iain Hanson, Oliver Kowalke, and
|
||||
Oleg Abrosimov.</p>
|
||||
<hr>
|
||||
<p>Last revised:
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->30 August, 2007<!--webbot bot="Timestamp" endspan i-checksum="34727" --></p>
|
||||
<p><EFBFBD> Copyright Beman Dawes, 2006</p>
|
||||
<p>Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at
|
||||
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a>)</p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
125
doc/index.html
Normal file
125
doc/index.html
Normal file
@@ -0,0 +1,125 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<title>Boost System Library</title>
|
||||
<link rel="stylesheet" type="text/css" href="../../../doc/html/minimal.css">
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="637">
|
||||
<tr>
|
||||
<td width="277">
|
||||
<a href="../../../index.htm">
|
||||
<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td>
|
||||
<td width="337" align="middle">
|
||||
<font size="7">System Library</font>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
|
||||
<tr>
|
||||
<td><a href="../../../index.htm">Boost Home</a> <a href="index.html">
|
||||
Library Home</a> Tutorial <a href="reference.html">
|
||||
Reference</a></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
|
||||
<tr>
|
||||
<td width="100%" bgcolor="#D7EEFF" align="center">
|
||||
<i><b>Contents</b></i></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="100%" bgcolor="#E8F5FF">
|
||||
<a href="#Introduction">Introduction</a><br>
|
||||
<a href="#Design_Rationale">Design Rationale</a><br>
|
||||
<a href="#History">History</a><br>
|
||||
<a href="#Acknowledgements">Acknowledgements</a>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
|
||||
<p>Error conditions originating from the operating system or other low-level
|
||||
application program interfaces (API's) are typically reported via an integer
|
||||
representing an error code. When these low-level API calls are wrapped in
|
||||
portable code, such as in a portable library, some users want to deal with the
|
||||
error codes in portable ways. Other users need to get at the system specific
|
||||
error codes, so they can deal with system specific needs. The Boost System
|
||||
library provides simple, light-weight <a href="reference.html#Class-error_code">
|
||||
error_code</a> objects that encapsulate system-specific error code values, yet
|
||||
also provide access to more abstract and portable error conditions via
|
||||
<a href="reference.html#Class-error_condition">error_condition</a> objects.
|
||||
Because error_code objects can represent errors from sources other than the
|
||||
operating system, including user-defined sources, each error_code and
|
||||
error_condition has an associated <a href="reference.html#Class-error_category">
|
||||
error_category</a>.</p>
|
||||
|
||||
<p>An exception class, <a href="reference.html#Class-system_error">
|
||||
system_error</a>, is provided. Derived from std::runtime_error, it captures the
|
||||
underlying error_code for the problem causing the exception so that this
|
||||
important information is not lost.</p>
|
||||
<p>While exceptions are the preferred C++ default error code reporting
|
||||
mechanism, users of libraries dependent on low-level API's often need overloads
|
||||
reporting error conditions via error code arguments and/or return values rather
|
||||
than via throwing exceptions. Otherwise, when errors are not exceptional
|
||||
occurrences and must be dealt with as they arise, programs become littered with
|
||||
try/catch blocks, unreadable, and very inefficient. The Boost System library
|
||||
supports both error reporting by exception and by error code.</p>
|
||||
<h2><a name="Design_Rationale">Design Rationale</a></h2>
|
||||
<p>Class <code>error_code</code> and <code>error_condition</code> are designed as a value types so
|
||||
they can be copied
|
||||
without slicing and do not requiring heap allocation, but still have polymorphic
|
||||
behavior based on the error category. This is achieved by abstract base class
|
||||
<code>error_category</code> supplying the polymorphic behavior, and <code>
|
||||
error_code</code> and <code>error_condition</code> containing a pointer to an object of a type derived from <code>
|
||||
error_category</code>.</p>
|
||||
<p>Many of the detailed design decisions were driven by the requirements that
|
||||
users to be able to add additional error categories, and that it be no more
|
||||
difficult to write portable code than system-specific code.</p>
|
||||
<p>The <code>operator<<</code> overload for <code>error_code</code> eliminates a
|
||||
misleading conversion to bool in code like <code>cout << ec</code>, where <code>
|
||||
ec</code> is of type <code>error_code</code>. It is also useful in its own
|
||||
right.</p>
|
||||
<h2><a name="History">History</a></h2>
|
||||
<p><a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1975.html">
|
||||
N1975</a>, Filesystem Library Proposal for TR2, accepted for Library Technical
|
||||
Report 2 (TR2) at the Berlin meeting, included additional components to
|
||||
supplement the Standard Library's Diagnostics clause. Since then, these error
|
||||
reporting components have received wider public scrutiny and enhancements have
|
||||
been made to the design. The enhanced version has been used by N2054, Networking
|
||||
Library Proposal for TR2, demonstrating that these error reporting components
|
||||
are useful beyond the original Filesystem Library.</p>
|
||||
<p>The original proposal viewed error categories as a binary choice between
|
||||
<code>errno</code> (i.e. POSIX-style) and the native operating system's error
|
||||
codes. The proposed components now allow as many additional error categories as
|
||||
are needed by either implementations or by users. The need to support additional
|
||||
error categories, for example, occurs in some networking library implementations
|
||||
because they are built on top of the POSIX <code>getaddrinfo</code> API that
|
||||
uses error codes not based on <code>errno</code>.</p>
|
||||
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
|
||||
<p>Christopher Kohlhoff and Peter Dimov made important contributions to the
|
||||
design. Comments and suggestions were also received from Pavel Vozenilek,
|
||||
Gennaro Prota, Dave Abrahams, Jeff Garland, Iain Hanson, Oliver Kowalke, and
|
||||
Oleg Abrosimov. Christopher Kohlhoff suggested several improvements to the N2066
|
||||
paper. Johan Nilsson's comments led to several of the refinements in N2066 .</p>
|
||||
<hr>
|
||||
|
||||
<p><EFBFBD> Copyright Beman Dawes, 1999<br>
|
||||
Distributed under the Boost Software License, Version 1.0. See
|
||||
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
|
||||
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%B %d, %Y" startspan -->September 14, 2007<!--webbot bot="Timestamp" endspan i-checksum="37985" --> </font>
|
||||
</p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
689
doc/reference.html
Normal file
689
doc/reference.html
Normal file
@@ -0,0 +1,689 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<title>System Library Reference</title>
|
||||
<link rel="stylesheet" type="text/css" href="../../../doc/html/minimal.css">
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="637">
|
||||
<tr>
|
||||
<td width="277">
|
||||
<a href="../../../index.htm">
|
||||
<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td>
|
||||
<td width="337" align="middle">
|
||||
<font size="7">System Library</font>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
|
||||
<tr>
|
||||
<td><a href="../../../index.htm">Boost Home</a> <a href="index.html">
|
||||
Library Home</a> Tutorial <a href="reference.html">
|
||||
Reference</a></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
|
||||
<tr>
|
||||
<td width="100%" bgcolor="#D7EEFF" align="center">
|
||||
<i><b>Contents</b></i></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="100%" bgcolor="#E8F5FF">
|
||||
<a href="#Introduction">Introduction</a><br>
|
||||
<a href="#Header-error_code">Header <boost/system/error_code.hpp></a><br>
|
||||
<a href="#Class-error_category">Class <code>error_category</code></a><br>
|
||||
<a href="#Class-error_category-synopsis">Class <code>error_category</code> synopsis</a><br>
|
||||
<a href="#Class-error_category-virtual-members">Class <code>error_category</code> virtual members</a><br>
|
||||
<a href="#Class-error_category-non-virtual-members">Class <code>error_category</code> non-virtual members</a><br>
|
||||
<a href="#Class-error_category-predefined-objects">Class <code>error_category</code> predefined objects</a><br>
|
||||
<a href="#Class-error_code">Class <code>error_code</code></a><br>
|
||||
<a href="#Class-error_code-synopsis">Class <code>error_code</code> synopsis</a><br>
|
||||
<a href="#Class-error_code-constructors">Class <code>error_code</code> constructors</a><br>
|
||||
<a href="#Class-error_code-modifiers">Class <code>error_code</code> modifiers</a><br>
|
||||
<a href="#Class-error_code-observers">Class <code>error_code</code> observers</a><br>
|
||||
<a href="#Class-error_condition</code>">Class <code>error_condition</code></a><br>
|
||||
<a href="#Class-error_condition-synopsis">Class <code>error_condition</code> synopsis</a><br>
|
||||
<a href="#Class-error_condition-constructors">Class <code>error_condition</code> constructors</a><br>
|
||||
<a href="#Class-error_condition-modifiers">Class <code>error_condition</code> modifiers</a><br>
|
||||
<a href="#Class-error_condition-observers">Class <code>error_condition</code> observers</a><br>
|
||||
<a href="#Non-member-functions">Non-member functions</a><br>
|
||||
<a href="#Header-system_error">Header <boost/system/system_error.hpp></a><br>
|
||||
<a href="#Class-system_error">Class <code>system_error</code></a><br>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
|
||||
<p>This reference documentation describes components that
|
||||
programs may use to report error conditions originating from the operating
|
||||
system or other low-level application program interfaces.</p>
|
||||
<p>System Library components do not change the value of <code>
|
||||
errno</code>.</p>
|
||||
<h2><a name="Header-error_code">Header <boost/system/error_code.hpp></a></h2>
|
||||
<h3><boost/system/error_code.hpp> synopsis</h3>
|
||||
<blockquote>
|
||||
<pre>namespace boost
|
||||
{
|
||||
namespace system
|
||||
{
|
||||
class <a href="#Class-error_category">error_category</a>;
|
||||
class <a href="#Class-error_code">error_code</a>;
|
||||
class <a href="#Class-error_condition">error_condition</a>;
|
||||
|
||||
// "Concept" helpers
|
||||
template< class T="" >
|
||||
struct is_error_code_enum { static const bool value = false; };
|
||||
|
||||
template< class T="" >
|
||||
struct is_error_condition_enum { static const bool value = false; };
|
||||
|
||||
// portable error_conditions
|
||||
namespace posix
|
||||
{
|
||||
enum posix_errno
|
||||
{
|
||||
success = 0,
|
||||
address_family_not_supported, //EAFNOSUPPORT
|
||||
address_in_use, //EADDRINUSE
|
||||
address_not_available, //EADDRNOTAVAIL
|
||||
already_connected, //EISCONN
|
||||
argument_list_too_long, //E2BIG
|
||||
argument_out_of_domain, //EDOM
|
||||
bad_address, //EFAULT
|
||||
bad_file_descriptor, //EBADF
|
||||
bad_message, //EBADMSG
|
||||
broken_pipe, //EPIPE
|
||||
connection_aborted, //ECONNABORTED
|
||||
connection_already_in_progress, //EALREADY
|
||||
connection_refused, //ECONNREFUSED
|
||||
connection_reset, //ECONNRESET
|
||||
cross_device_link, //EXDEV
|
||||
destination_address_required, //EDESTADDRREQ
|
||||
device_or_resource_busy, //EBUSY
|
||||
directory_not_empty, //ENOTEMPTY
|
||||
executable_format_error, //ENOEXEC
|
||||
file_exists, //EEXIST
|
||||
file_too_large, //EFBIG
|
||||
filename_too_long, //ENAMETOOLONG
|
||||
function_not_supported, //ENOSYS
|
||||
host_unreachable, //EHOSTUNREACH
|
||||
identifier_removed, //EIDRM
|
||||
illegal_byte_sequence, //EILSEQ
|
||||
inappropriate_io_control_operation,//ENOTTY
|
||||
interrupted, //EINTR
|
||||
invalid_argument, //EINVAL
|
||||
invalid_seek, //ESPIPE
|
||||
io_error, //EIO
|
||||
is_a_directory, //EISDIR
|
||||
message_size, //EMSGSIZE
|
||||
network_down, //ENETDOWN
|
||||
network_reset, //ENETRESET
|
||||
network_unreachable, //ENETUNREACH
|
||||
no_buffer_space, //ENOBUFS
|
||||
no_child_process, //ECHILD
|
||||
no_link, //ENOLINK
|
||||
no_lock_available, //ENOLCK
|
||||
no_message_available, //ENODATA
|
||||
no_message, //ENOMSG
|
||||
no_protocol_option, //ENOPROTOOPT
|
||||
no_space_on_device, //ENOSPC
|
||||
no_stream_resources, //ENOSR
|
||||
no_such_device_or_address, //ENXIO
|
||||
no_such_device, //ENODEV
|
||||
no_such_file_or_directory, //ENOENT
|
||||
no_such_process, //ESRCH
|
||||
not_a_directory, //ENOTDIR
|
||||
not_a_socket, //ENOTSOCK
|
||||
not_a_stream, //ENOSTR
|
||||
not_connected, //ENOTCONN
|
||||
not_enough_memory, //ENOMEM
|
||||
not_supported, //ENOTSUP
|
||||
operation_canceled, //ECANCELED
|
||||
operation_in_progress, //EINPROGRESS
|
||||
operation_not_permitted, //EPERM
|
||||
operation_not_supported, //EOPNOTSUPP
|
||||
operation_would_block, //EWOULDBLOCK
|
||||
owner_dead, //EOWNERDEAD
|
||||
permission_denied, //EACCES
|
||||
protocol_error, //EPROTO
|
||||
protocol_not_supported, //EPROTONOSUPPORT
|
||||
read_only_file_system, //EROFS
|
||||
resource_deadlock_would_occur, //EDEADLK
|
||||
resource_unavailable_try_again, //EAGAIN
|
||||
result_out_of_range, //ERANGE
|
||||
state_not_recoverable, //ENOTRECOVERABLE
|
||||
stream_timeout, //ETIME
|
||||
text_file_busy, //ETXTBSY
|
||||
timed_out, //ETIMEDOUT
|
||||
too_many_files_open_in_system, //ENFILE
|
||||
too_many_files_open, //EMFILE
|
||||
too_many_links, //EMLINK
|
||||
too_many_synbolic_link_levels, //ELOOP
|
||||
value_too_large, //EOVERFLOW
|
||||
wrong_protocol_type //EPROTOTYPE
|
||||
};
|
||||
|
||||
} // namespace posix
|
||||
|
||||
template<> struct is_error_condition_enum<posix::posix_errno><posix::posix_errno>
|
||||
{ static const bool value = true; };
|
||||
|
||||
bool operator==( const error_code & lhs, const error_code & rhs );
|
||||
bool operator==( const error_code & code, const error_condition & condition );
|
||||
bool operator==( const error_condition & condition, const error_code & code );
|
||||
bool operator==( const error_condition & lhs, const error_condition & rhs );
|
||||
|
||||
bool operator!=( const error_code & lhs, const error_code & rhs );
|
||||
bool operator!=( const error_code & code, const error_condition & condition );
|
||||
bool operator!=( const error_condition & condition, const error_code & code );
|
||||
bool operator!=( const error_condition & lhs, const error_condition & rhs );
|
||||
|
||||
bool operator<( const error_code & lhs, const error_code & rhs );
|
||||
bool operator<( const error_condition & lhs, const error_condition & rhs );
|
||||
|
||||
error_code make_error_code( posix::posix_errno e );
|
||||
error_condition make_error_condition( posix::posix_errno e );
|
||||
|
||||
template <class charT, class traits>
|
||||
std::basic_ostream<charT,traits>&
|
||||
operator<<( basic_ostream<charT,traits>& os, const error_code & ec );
|
||||
|
||||
size_t hash_value( const error_code & ec );
|
||||
}
|
||||
}</pre>
|
||||
</blockquote>
|
||||
<p>The value of each<code> posix_errno</code> constant shall be the same as the
|
||||
value of the <code><cerrno></code> macro shown in the above synopsis.</p>
|
||||
<p>Users may specialize <code>is_error_code_enum</code> and <code>
|
||||
is_error_condition_enum</code> templates to indicate that a type is eligible for
|
||||
class <code>error_code</code> and <code>error_condition</code> automatic
|
||||
conversions respectively.</p>
|
||||
|
||||
<h2><a name="Class-error_category">Class <code>error_category</code></a></h2>
|
||||
<p>The class <code>error_category</code> defines the base class for types used
|
||||
to identify the source and encoding of a particular category of error code.</p>
|
||||
<p><i>[Note:</i> Classes may be derived from <code>error_category</code>
|
||||
to support additional categories of errors. <i>--end note]</i></p>
|
||||
<p>The class <code>error_category</code> serves as a base class for types used
|
||||
to identify the source and encoding of a particular category of error code.
|
||||
Classes may be derived from <code>error_category</code> to support categories of
|
||||
errors in addition to those defined in the Boost System library. Such classes
|
||||
shall behave as specified in this subclause. [<i> Note:</i> <code>error_category</code>
|
||||
objects are passed by reference, and two such objects are equal if they have the
|
||||
same address. This means that applications using custom <code>error_category</code>
|
||||
types should create a single object of each such type. <i><EFBFBD>end note</i> ]</p>
|
||||
<h3><a name="Class-error_category-synopsis">Class <code>error_category</code> synopsis</a></h3>
|
||||
<blockquote>
|
||||
<pre>namespace boost
|
||||
{
|
||||
namespace system
|
||||
{
|
||||
class error_category : public noncopyable
|
||||
{
|
||||
public:
|
||||
virtual ~error_category();
|
||||
|
||||
virtual const char * name() const = 0;
|
||||
virtual string message( error_code::value_type ev ) const = 0;
|
||||
virtual error_condition default_error_condition( int ev ) const;
|
||||
virtual bool equivalent( int code, const error_condition & condition ) const;
|
||||
virtual bool equivalent( const error_code & code, int condition ) const;
|
||||
|
||||
bool operator==( const error_category & rhs ) const;
|
||||
bool operator!=( const error_category & rhs ) const;
|
||||
bool operator< ( const error_category & rhs ) const;
|
||||
};
|
||||
|
||||
extern const error_category & posix_category;
|
||||
extern const error_category & system_category;
|
||||
}
|
||||
}</pre>
|
||||
</blockquote>
|
||||
<h3><a name="Class-error_category-virtual-members">Class <code>error_category</code> virtual members</a></h3>
|
||||
<p>Classes derived from <code>error_category</code> shall behave as specified in
|
||||
this subclause.</p>
|
||||
<pre>virtual const char * name() const=0;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns: </i>a string naming the error category.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>virtual string message( error_code::value_type ev ) const=0;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> A string that describes the error denoted by
|
||||
<code>ev</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<p><code>virtual error_condition default_error_condition( int ev ) const;</code></p>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>error_condition( ev, *this )</code>.</p>
|
||||
<blockquote>
|
||||
<p> [<i>--Note:</i> Derived classes will typically convert <code>ev</code>
|
||||
to some portable <code>error_category</code>, such as <code>posix_category</code>,
|
||||
and return it as an <code>error_condition</code> for that category. <i>--end
|
||||
note</i>]</p>
|
||||
</blockquote>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<p><code>virtual bool equivalent( int code, const error_condition &
|
||||
condition )
|
||||
const;</code></p>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>default_error_condition( code ) == condition</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<p><code>virtual bool equivalent( const error_code & code, int condition ) const;</code></p>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>*this == code.category() && code.value() == condition</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="Class-error_category-non-virtual-members">Class <code>error_category</code> non-virtual members</a></h3>
|
||||
<p><code>bool operator==( const error_category & rhs ) const;</code></p>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>this == &rhs</code>.</p>
|
||||
</blockquote>
|
||||
<p><code>bool operator!=( const error_category & rhs ) const;</code></p>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>this != &rhs</code>.</p>
|
||||
</blockquote>
|
||||
|
||||
<pre>bool operator<( const error_category & rhs ) const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>std::less<const error_category*>()( this, &rhs )</code>.</p>
|
||||
<blockquote>
|
||||
<p><i>[Note:</i> <code>std::less</code> provides a total ordering for
|
||||
pointers. <i>--end note]</i></p>
|
||||
</blockquote>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="Class-error_category-predefined-objects">Class <code>error_category</code>
|
||||
predefined objects</a></h3>
|
||||
<p>Predefined objects <code>posix_category</code>
|
||||
and <code>system_category</code> identify portable error conditions and system error
|
||||
codes, respectively.</p>
|
||||
<h2><a name="Class-error_code">Class <code>
|
||||
error_code</code></a></h2>
|
||||
<p>The class <code>error_code</code> describes an object used to hold error code
|
||||
values, such as those originating from the operating<br>
|
||||
system or other low-level application program interfaces. <i>[ Note: </i>Class
|
||||
<code>error_code</code> is an adjunct to error reporting by<br>
|
||||
exception. <i><EFBFBD>end note ]</i></p>
|
||||
<h3><a name="Class-error_code-synopsis">Class <code>
|
||||
error_code</code> synopsis</a></h3>
|
||||
<blockquote>
|
||||
<pre>namespace boost
|
||||
{
|
||||
namespace system
|
||||
{
|
||||
class error_code {
|
||||
public:
|
||||
|
||||
// constructors:
|
||||
error_code();
|
||||
error_code( val, const error_category & cat );
|
||||
template <class <code>ErrorCodeEnum</code>>
|
||||
error_code(<code> errorCodeEnum</code> e,
|
||||
typename enable_if<is_error_code_enum<<code>ErrorCodeEnum</code>> >::type* = 0);
|
||||
|
||||
// modifiers:
|
||||
void assign( int val, const error_category & cat );
|
||||
template<typename <code>ErrorCodeEnum</code>>
|
||||
typename enable_if<is_error_code_enum<<code>ErrorCodeEnum</code>>, error_code>::type &
|
||||
operator=( <code>ErrorCodeEnum</code> val );;
|
||||
void clear();
|
||||
|
||||
// observers:
|
||||
int value() const;
|
||||
cont error_category & category() const;
|
||||
error_condition default_error_condition() const;
|
||||
string message() const;
|
||||
operator unspecified-bool-type() const;
|
||||
|
||||
private:
|
||||
int val_; // <i>exposition only</i>
|
||||
const error_category & cat_; // <i>exposition only</i>
|
||||
};
|
||||
}
|
||||
}</pre>
|
||||
</blockquote>
|
||||
<h3><a name="Class-error_code-constructors">Class <code>
|
||||
error_code</code> constructors</a></h3>
|
||||
<pre>error_code();</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects: </i>Constructs an object of type <code>error_code</code>.</p>
|
||||
<p><i>Postconditions:</i> <code>val_ == 0 && cat_ == &system_category</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>error_code( int val, const error_category & cat );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects: </i>Constructs an object of type <code>error_code</code>.</p>
|
||||
<p><i>Postconditions:</i> <code>val_ == val && cat_ == &cat</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template <class <code>ErrorCodeEnum</code>>
|
||||
error_code(<code> errorCodeEnum</code> val,
|
||||
typename enable_if<is_error_code_enum<<code>ErrorCodeEnum</code>> >::type* = 0);</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects: </i>Constructs an object of type <code>error_code</code>.</p>
|
||||
<p><i>Postconditions:</i> <code>*this == make_error_code( val )</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="Class-error_code-modifiers">Class <code>
|
||||
error_code</code> modifiers</a></h3>
|
||||
<pre>void assign( int val, const error_category & cat );</pre>
|
||||
<blockquote>
|
||||
<p><i>Postconditions:</i> <code>val_ == val && cat_ == cat</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<typename <code>ErrorCodeEnum</code>>
|
||||
typename enable_if<is_error_code_enum<<code>ErrorCodeEnum</code>>, error_code>::type &
|
||||
operator=( <code>ErrorCodeEnum</code> val );</pre>
|
||||
<blockquote>
|
||||
<p><i>Postconditions:</i> <code>*this == make_error_code( val )</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<p><code>void clear();</code></p>
|
||||
<blockquote>
|
||||
<p><i>postcondition:</i> <code>value() == 0 && category() == posix_category</code></p>
|
||||
</blockquote>
|
||||
<h3><a name="Class-error_code-observers">Class <code>
|
||||
error_code</code> observers</a></h3>
|
||||
<p><code>int value() const;</code></p>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>val_</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<p><code>error_category category() const;</code></p>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>cat_</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>error_condition default_error_condition() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>category().default_error_condition( value())</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<p><code>string message() const;</code></p>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>category().message( value())</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<p><code>operator <i>unspecified-bool-type</i>() const;</code></p>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> if <code>value() != value_type()</code>, returns a value that will evaluate
|
||||
<code>true</code> in a boolean context; otherwise, returns a value that will
|
||||
evaluate <code>false</code> in a boolean context. The value type returned shall
|
||||
not be convertible to <code>int</code>.</p>
|
||||
<p><i>Throws:</i> nothing.</p>
|
||||
<p><i>[Note: </i>This conversion can be used in contexts where a <code>bool</code>
|
||||
is expected ( e.g., an <code>if</code> condition ); however, implicit conversions
|
||||
( e.g., to <code>int</code>) that can occur with <code>bool</code> are not
|
||||
allowed, eliminating some sources of user error. One possible implementation
|
||||
choice for this type is pointer-to-member. <i>--end note ]</i></p>
|
||||
</blockquote>
|
||||
<h2><a name="Class-error_condition">Class <code>error_condition</code></a></h2>
|
||||
<p>The class <code>error_condition</code> describes an object used to hold
|
||||
values identifying error conditions. <i>[ Note: </i><code>error_condition</code>
|
||||
values are portable abstractions, while <code>error_code</code> values are
|
||||
implementation specific. <i>--end note ]</i></p>
|
||||
<h3><a name="Class-error_condition-synopsis">Class <code>error_condition</code> synopsis</a></h3>
|
||||
<blockquote>
|
||||
<pre>namespace boost
|
||||
{
|
||||
namespace system
|
||||
{
|
||||
class error_condition
|
||||
{
|
||||
public:
|
||||
|
||||
// constructors:
|
||||
error_condition();
|
||||
error_condition( int val, const error_category & cat );
|
||||
template <class ErrorConditionEnum>
|
||||
error_condition( errorConditionEnum val,
|
||||
typename enable_if<is_error_condition_enum<ErrorConditionEnum> >::type* = 0 );
|
||||
|
||||
// modifiers:
|
||||
void assign( int val, const error_category & cat );
|
||||
template<typename ErrorConditionEnum>
|
||||
typename enable_if<is_error_condition_enum<ErrorConditionEnum>, error_code>::type &
|
||||
operator=( ErrorConditionEnum val );
|
||||
void clear();
|
||||
|
||||
// observers:
|
||||
int value() const;
|
||||
const error_category & category() const;
|
||||
string message() const;
|
||||
operator unspecified-bool-type () const;
|
||||
|
||||
private:
|
||||
int val_; // <i>exposition only</i>
|
||||
const error_category & cat_; // <i>exposition only</i>
|
||||
};
|
||||
}
|
||||
}</pre>
|
||||
</blockquote>
|
||||
<h3><a name="Class-error_condition-constructors">Class <code>error_condition</code>
|
||||
constructors</a></h3>
|
||||
<pre>error_condition(); </pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of type <code>error_condition</code>.</p>
|
||||
<p><i>Postconditions:</i> <code>val_ == 0 and cat_ == posix_category</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>error_condition( value_type val, const error_category & cat );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects: </i>Constructs an object of type error_condition.</p>
|
||||
<p><i>Postconditions:</i> <code>val_ == val and cat_ == cat</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template <class ErrorConditionEnum>
|
||||
error_condition( errorConditionEnum val,
|
||||
typename enable_if<is_error_condition_enum<ErrorConditionEnum> >::type* = 0 );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of type <code>error_condition</code>.</p>
|
||||
<p><i>Postconditions:</i> <code>*this == make_error_condition( val )</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<h3><a name="Class-error_condition-modifiers">Class <code>error_condition</code>
|
||||
modifiers</a></h3>
|
||||
<pre>void assign( value_type val, const error_category & cat ); </pre>
|
||||
<blockquote>
|
||||
<p><i>Postconditions:</i> <code>val_ == val and cat_ == cat</code>. </p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>template<typename ErrorConditionEnum>
|
||||
typename enable_if<is_error_condition_enum<ErrorConditionEnum>, error_code>::type &
|
||||
operator=( ErrorConditionEnum val );</pre>
|
||||
<blockquote>
|
||||
<p><i>Postconditions:</i> <code>*this == make_error_condition( val )</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<p><code>void clear();</code></p>
|
||||
<blockquote>
|
||||
<p><i>postcondition:</i> <code>value() == 0 && category() == posix_category</code></p>
|
||||
</blockquote>
|
||||
<h3><a name="Class-error_condition-observers">Class <code>error_condition</code>
|
||||
observers</a></h3>
|
||||
<pre>value_type value() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>val_</code>.</p>
|
||||
<p><i>Throws:</i> Nothing</p>
|
||||
</blockquote>
|
||||
<pre>const error_category & category() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>cat_</code>.</p>
|
||||
<p>Throws: Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>string message() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>category().message( value() )</code>.</p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>operator unspecified-bool-type () const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns: </i>If <code>value() != 0</code>, returns a value that will
|
||||
evaluate <code>true</code> in a boolean context; otherwise, returns a value
|
||||
that will evaluate <code>false</code>. The return type shall not be
|
||||
convertible to <code>int</code>. </p>
|
||||
<p><i>Throws:</i> Nothing.</p>
|
||||
<p><i> [ Note:</i> This conversion can be used in contexts where a <code>bool</code>
|
||||
is expected ( e.g., an if condition ); however, implicit conversions ( e.g., to
|
||||
<code>int</code>) that can occur with <code>bool</code> are not allowed,
|
||||
eliminating some sources of user error. One possible implementation choice for
|
||||
this type is pointer to member. <i>--end note</i> <i>]</i></p>
|
||||
</blockquote>
|
||||
<h2><a name="Non-member-functions">Non-member functions</a></h2>
|
||||
<pre>bool operator==( const error_code & lhs, const error_code & rhs );</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>lhs.category() == rhs.category() && lhs.value() ==
|
||||
rhs.value()</code>.</p>
|
||||
<p><i>Throws: </i>Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>bool operator==( const error_code & code, const error_condition & condition );
|
||||
bool operator==( const error_condition & condition, const error_code & code );</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>code.category().equivalent( code.value(), condition )<br>
|
||||
|| condition.category().equivalent( code, condition.value() )</code>.</p>
|
||||
<p><i>Throws: </i>Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>bool operator==( const error_condition & lhs, const error_condition & rhs );</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>lhs.category() == rhs.category() && lhs.value() ==
|
||||
rhs.value()</code>.</p>
|
||||
<p><i>Throws: </i>Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>bool operator!=( const error_code & lhs, const error_code & rhs );</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>!(lhs == rhs )</code>.</p>
|
||||
<p><i>Throws: </i>Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>bool operator!=( const error_code & code, const error_condition & condition );
|
||||
bool operator!=( const error_condition & condition, const error_code & code );</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i><code> !( code == condition )</code>.</p>
|
||||
<p><i>Throws: </i>Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>bool operator!=( const error_condition & lhs, const error_condition & rhs );</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>!(lhs == rhs )</code>.</p>
|
||||
<p><i>Throws: </i>Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>bool operator<( const error_code & lhs, const error_code & rhs );</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>lhs.category() < rhs.category()<br>
|
||||
|| (lhs.category() == rhs.category() && lhs.value() < rhs.value())</code>.</p>
|
||||
<p><i>Throws: </i>Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>bool operator<( const error_condition & lhs, const error_condition & rhs );</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>lhs.category() < rhs.category()<br>
|
||||
|| (lhs.category() == rhs.category() && lhs.value() < rhs.value())</code>.</p>
|
||||
<p><i>Throws: </i>Nothing.</p>
|
||||
</blockquote>
|
||||
<pre>error_code make_error_code( posix::posix_errno e );</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>error_code( e, posix_category)</code>.</p>
|
||||
</blockquote>
|
||||
<pre>error_condition make_error_condition( posix::posix_errno e );</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>error_condition( e, posix_category)</code>.</p>
|
||||
</blockquote>
|
||||
|
||||
<pre>template <class charT, class traits>
|
||||
std::basic_ostream<charT,traits>&
|
||||
operator<<( basic_ostream<charT,traits>& os, const error_code & ec );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> <code>os << ec.category().name() << ':' << ec.value()</code>.</p>
|
||||
<p><i>Returns:</i> <code>os</code>.</p>
|
||||
</blockquote>
|
||||
<pre>size_t <a name="hash_value">hash_value</a>( const error_code & ec );</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns: </i> A hash value representing <code>ec</code>.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2><a name="Header-system_error">Header <boost/system/system_error.hpp></a></h2>
|
||||
|
||||
<h3><a name="Class-system_error">Class <code>
|
||||
system_error</code></a></h3>
|
||||
<p>The class <code>system_error</code> describes an exception object used to
|
||||
report error conditions that have an associated error code. Such error
|
||||
conditions typically originate from the operating system or other low-level
|
||||
application program interfaces.</p>
|
||||
<blockquote>
|
||||
<pre>namespace boost
|
||||
{
|
||||
namespace system
|
||||
{
|
||||
class system_error : public std::runtime_error
|
||||
{
|
||||
public:
|
||||
system_error( error_code ec );
|
||||
system_error( error_code ec, const std::string & what_arg );
|
||||
system_error( error_code::value_type ev, const error_category & ecat,
|
||||
const std::string & what_arg );
|
||||
system_error( error_code::value_type ev, const error_category & ecat);
|
||||
|
||||
const error_code & code() const throw();
|
||||
const char * what() const throw();
|
||||
};
|
||||
}
|
||||
}</pre>
|
||||
</blockquote>
|
||||
<pre>system_error( error_code ec );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
|
||||
<p><i>Postcondition:</i> <code>code() == ec <br>
|
||||
&& std::strcmp( this->runtime_error::what(), "" ) == 0</code></p>
|
||||
</blockquote>
|
||||
<pre>system_error( error_code ec, const std::string & what_arg );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
|
||||
<p><i>Postcondition:</i> <code>code() == ec <br>
|
||||
&& std::strcmp( this->runtime_error::what(), what_arg.c_str() ) == 0</code></p>
|
||||
</blockquote>
|
||||
<pre>system_error( error_code::value_type ev, const error_category & ecat,
|
||||
const std::string & what_arg );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
|
||||
<p><i>Postcondition:</i> <code>code() == error_code( ev, ecat )<br>
|
||||
&& std::strcmp( this->runtime_error::what(), what_arg.c_str() ) == 0</code></p>
|
||||
</blockquote>
|
||||
<pre>system_error( error_code::value_type ev, const error_category & ecat );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
|
||||
<p><i>Postcondition:</i> <code>code() == error_code( ev, ecat )<br>
|
||||
&& std::strcmp( this->runtime_error::what(), "" ) == 0</code></p>
|
||||
</blockquote>
|
||||
<pre>const error_code & code() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>ec</code> or <code>error_code( ev, ecat )</code>, from
|
||||
the constructor, as appropriate.</p>
|
||||
</blockquote>
|
||||
<pre>const char * what() const;</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns: </i>A string incorporating <code>
|
||||
this->runtime_error::what()</code> and <code>
|
||||
code.message()</code>.</p>
|
||||
</blockquote>
|
||||
<hr>
|
||||
|
||||
<p><EFBFBD> Copyright Beman Dawes, 2006, 2007<br>
|
||||
Distributed under the Boost Software License, Version 1.0. See
|
||||
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
|
||||
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%B %d, %Y" startspan -->September 14, 2007<!--webbot bot="Timestamp" endspan i-checksum="37985" --> </font>
|
||||
</p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@@ -1,127 +0,0 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<title>Boost system/system_error.hpp documentation
|
||||
</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF">
|
||||
|
||||
<h1>Header <a href="../../../boost/system/system_error.hpp">boost/system/system_error.hpp</a></h1>
|
||||
<p><a href="#Introduction">Introduction</a><br>
|
||||
<a href="#Synopsis">Synopsis</a><br>
|
||||
<a href="#Class-system_error">Class <code>system_error</code></a><br>
|
||||
<a href="#Class-system_error-members">Members</a><br>
|
||||
<a href="#Acknowledgements">Acknowledgements</a></p>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>This header provides components used to report errors originating from the
|
||||
operating system or other low-level application program interfaces (API's). It is based on the <i>Diagnostics</i>
|
||||
portion of the TR2 filesystem proposal.</p>
|
||||
<h2><a name="Synopsis">Synopsis</a></h2>
|
||||
<pre>namespace boost
|
||||
{
|
||||
namespace system
|
||||
{
|
||||
enum message_action { append_message, no_message };
|
||||
|
||||
class system_error : public std::runtime_error
|
||||
{
|
||||
public:
|
||||
explicit <a href="#system_error-1">system_error</a>( error_code ec );
|
||||
|
||||
<a href="#system_error-2">system_error</a>( error_code ec, const std::string & what_arg,
|
||||
message_action ma = append_message );
|
||||
|
||||
<a href="#system_error-3">system_error</a>( error_code::value_type ev, error_category ecat );
|
||||
|
||||
<a href="#system_error-4">system_error</a>( error_code::value_type ev, error_category ecat,
|
||||
const std::string & what_arg, message_action ma = append_message );
|
||||
|
||||
virtual ~system_error() throw() {}
|
||||
|
||||
const error_code & <a href="#code">code</a>() const throw();
|
||||
|
||||
const char * <a href="#what">what</a>() const throw();
|
||||
|
||||
private:
|
||||
error_code m_error_code; // for exposition only
|
||||
bool m_append_message; // for exposition only
|
||||
mutable std::string m_what; // for exposition only
|
||||
};
|
||||
} // namespace system
|
||||
} // namespace boost</pre>
|
||||
<h2><a name="Class-system_error">Class <code>system_error</code></a></h2>
|
||||
<p>Class <code><a href="#Class-system_error-members">system_error</a></code> defines
|
||||
the type of an object that may be thrown as
|
||||
an exception to report errors originating from the operating system or other
|
||||
low-level API's, or used as a base class for more refined exception classes. It
|
||||
encapsulates an <code><a href="error_code.html">error_code</a></code> object.</p>
|
||||
<blockquote>
|
||||
<p><i>[Note:</i> A single low-level class, rather than a higher level exception
|
||||
class hierarchy, is provided to allow users access to low-level error codes
|
||||
originating from the operating system or other low-level API's, and to
|
||||
accommodate the open-ended set of errors that may be reported by such API's. <i>
|
||||
--end note.]</i></p>
|
||||
</blockquote>
|
||||
<h2><a name="Class-system_error-members">Class <code>system_error</code> Members</a></h2>
|
||||
<p><code>explicit <a name="system_error-1">system_error</a>( error_code ec );</code></p>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
|
||||
<p><i>Postcondition:</i> <code>code() == ec && *runtime_error::what() == '\0'
|
||||
&& </code><code>m_append_message</code>.</p>
|
||||
</blockquote>
|
||||
<pre><a name="system_error-2">system_error</a>( error_code ec, const std::string & what_arg, message_action ma = append_message );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
|
||||
<p><i>Postcondition:</i> <code>code() == ec && std::string(runtime_error::what())
|
||||
== </code><code>what_arg</code><code> && m_append_message == ma</code>.</p>
|
||||
</blockquote>
|
||||
<pre><a name="system_error-3">system_error</a>( error_code::value_type ev, error_category ecat );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
|
||||
<p><i>Postcondition:</i> <code>code() == error_code(ev,ecat) && *runtime_error::what()
|
||||
== '\0' && m_append_message</code>.</p>
|
||||
</blockquote>
|
||||
<pre><a name="system_error-4">system_error</a>( error_code::value_type ev, error_category ecat,
|
||||
const std::string & what_arg, message_action ma = append_message );</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of class <code>system_error</code>.</p>
|
||||
<p><i>Postcondition:</i> <code>code() == error_code(ev,ecat) && std::string(runtime_error::what())
|
||||
== </code><code>what_arg</code><code> && m_append_message == ma</code>.</p>
|
||||
</blockquote>
|
||||
<pre>const error_code & <a name="code">code</a>() const throw();</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns: </i> <code>m_error_code</code></p>
|
||||
</blockquote>
|
||||
<pre>const char * <a name="what">what</a>() const throw();</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns: </i>If <code>!m_error_code || !m_append_message</code>, <code>
|
||||
runtime_error::what()</code>. Otherwise, a string as if computed by:</p>
|
||||
<blockquote>
|
||||
<pre>m_what = runtime_error::what();
|
||||
if ( !m_what.empty() ) m_what += ": ";
|
||||
m_what += m_error_code.message();
|
||||
return m_what.c_str();</pre>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
|
||||
<p>Christopher Kohlhoff and Peter Dimov made important contributions to the
|
||||
design. Comments and suggestions were also received from Pavel Vozenilek,
|
||||
Gennaro Prota, Dave Abrahams, Jeff Garland, Iain Hanson, Jeremy Day, Bo
|
||||
Persson, Oliver Kowalke, and
|
||||
Oleg Abrosimov.</p>
|
||||
<hr>
|
||||
<p>Last revised:
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->22 July, 2006<!--webbot bot="Timestamp" endspan i-checksum="21146" --></p>
|
||||
<p><EFBFBD> Copyright Beman Dawes, 2006</p>
|
||||
<p>Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at
|
||||
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a>)</p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
Reference in New Issue
Block a user