Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/filesystem/doc/exception.htm @ 12

Last change on this file since 12 was 12, checked in by landauf, 18 years ago

added boost
File size: 7.2 KB
Line 
1<html>
2
3<head>
4<meta http-equiv="Content-Language" content="en-us">
5<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
6<meta name="ProgId" content="FrontPage.Editor.Document">
7<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
8<title>Boost Filesystem exception.hpp Header</title>
9</head>
10
11<body bgcolor="#FFFFFF">
12
13<h1>
14<img border="0" src="../../../boost.png" align="center" width="277" height="86"><a href="../../../boost/filesystem/exception.hpp">boost/filesystem/exception.hpp</a></h1>
15
16<p><a href="#Introduction">Introduction</a><br>
17<a href="#Synopsis">Synopsis</a><br>
18<a href="#Members">Member functions</a><br>
19<a href="#Acknowledgements">Acknowledgements</a></p>
20
21<h2><a name="Introduction">Introduction</a></h2>
22
23<p>The header provides class <i>filesystem_error</i>, publicly derived from <i>
24std::runtime_error</i>, which is used by functions in the Filesystem Library to
25report operational errors.</p>
26
27<p>The design evolved based on user requests to ease portability and
28internationalization. See the Boost <a href="../../../more/error_handling.html">
29Error and Exception Handling</a> guidelines.</p>
30
31<h2><a name="Synopsis">Synopsis</a></h2>
32<pre>namespace boost
33{
34  namespace filesystem
35  {
36    enum <a name="error_code">error_code</a>
37    {
38      no_error = 0,
39      system_error,     // system generated error; if possible, is translated
40                        // to one of the more specific errors below.
41      other_error,      // library generated error
42      security_error,   // includes access rights, permissions failures
43      read_only_error,
44      io_error,
45      path_error,
46      not_found_error,
47      not_directory_error,
48      busy_error,       // implies trying again might succeed
49      already_exists_error,
50      not_empty_error,
51      is_directory_error,
52      out_of_space_error,
53      out_of_memory_error,
54      out_of_resource_error
55    };
56
57    class filesystem_error : public std::exception
58    {
59    public:
60
61      <a href="#Constructors">filesystem_error</a>(
62        const std::string &amp; who,
63        const std::string &amp; message );
64
65      <a href="#Constructors">filesystem_error</a>(
66        const std::string &amp; who,
67        const path &amp; path1,
68        const std::string &amp; message,
69        error_code ec = other_error );
70
71      <a href="#Constructors">filesystem_error</a>(
72        const std::string &amp; who,
73        const path &amp; path1,
74        <i>sys_err</i> sys_err_code );
75
76      <a href="#Constructors">filesystem_error</a>(
77        const std::string &amp; who,
78        const path &amp; path1,
79        const path &amp; path2,
80        <i>sys_err</i> sys_err_code );
81
82      ~filesystem_error() throw();
83
84      virtual const char * what() const throw();
85
86      <i>sys_err</i> <a href="#native_error">native_error</a>() const;
87      error_code <a href="#error">error</a>() const;
88      const std::string &amp; <a href="#who">who</a>() const;
89      const path &amp; <a href="#path1">path1</a>() const;
90      const path &amp; <a href="#path2">path2</a>() const;
91    };
92  } // namespace filesystem
93} // namespace boost
94</pre>
95
96<p>For POSIX and Windows, <i><code>sys_err</code></i> is <code>int</code>. For
97other operating systems, it is implementation defined.</p>
98
99<h2><a name="Members">Member functions</a></h2>
100
101<h3><a name="Constructors">Constructors</a></h3>
102<pre>      filesystem_error(
103        const std::string &amp; who,
104        const std::string &amp; message );
105
106      filesystem_error(
107        const std::string &amp; who,
108        const path &amp; path1,
109        const std::string &amp; message,
110        error_code ec = other_error );
111
112      filesystem_error(
113        const std::string &amp; who,
114        const path &amp; path1,
115        <i>sys_err</i> sys_err_code );
116
117      filesystem_error(
118        const std::string &amp; who,
119        const path &amp; path1,
120        const path &amp; path2,
121        <i>sys_err</i> sys_err_code );
122</pre>
123<blockquote>
124  <p><b>Precondition:</b> The <code>who</code> argument is in the form, as
125  appropriate:</p>
126  <ul>
127    <li>boost::filesystem::class-name::function-name for errors from public
128    member functions.</li>
129    <li>boost::filesystem::class-name for errors not identified with a
130    particular member function.</li>
131    <li>boost::filesystem::function-name for errors from non-member functions.</li>
132  </ul>
133  <p>These forms are explicitly specified to ensure portability of user programs
134  between library implementations. </p>
135  <p><b>Effects:</b> Constructs a <i>filesystem_error</i> object, initialized
136  from the appropriate arguments.</p>
137</blockquote>
138<h3><a name="what">what</a></h3>
139<blockquote>
140<p><code>virtual const char * what() const throw();</code></p>
141<p><b>Returns:</b> A string identifying the error, including who(), path1(),
142path2(), and related messages. If an error occurs in the preparation of the
143string, particularly in low-memory situations, an implementation is permitted to
144return a simpler static string.</p>
145</blockquote>
146<h3><a name="native_error">native_error</a></h3>
147<blockquote>
148  <p><i><code>sys_err</code></i><code> native_error() const;</code></p>
149  <p><b>Returns:</b> The <code>sys_err_code</code> argument to the constructor,
150  if any. Otherwise, 0.</p>
151</blockquote>
152<h3><a name="error">error</a></h3>
153<blockquote>
154  <pre>error_code error() const;</pre>
155  <p><b>Returns:</b> <code>native_error()</code> translated to <code>
156  <a href="#error_code">error_code</a></code>. The translation is
157  implementation-defined. For the POSIX and Windows implementations, see
158  <a href="../src/exception.cpp">libs/filesystem/src/exception.cpp</a>.</p>
159</blockquote>
160
161<h3><a name="who">who</a></h3>
162<blockquote>
163  <pre>const std::string &amp; who() const;</pre>
164
165<p><b>Returns:</b> The <code>who</code> argument to the constructor. An
166implementation is permitted to return an empty string if an exception, for
167example,&nbsp; std::bad_alloc,&nbsp; occurs during processing.</p>
168</blockquote>
169
170<h3><a name="path1">path1</a></h3>
171<blockquote>
172  <pre>const path &amp; path1() const;</pre>
173
174<p><b>Returns:</b> The <code>path1</code> argument to the constructor, if any,
175otherwise <code>path()</code>. An implementation is permitted to return an empty
176path if an exception, for example, std::bad_alloc,&nbsp; occurs during
177processing.</p>
178</blockquote>
179
180<h3><a name="path2">path2</a></h3>
181<blockquote>
182  <pre>const path &amp; path2() const;</pre>
183
184<p><b>Returns:</b> The <code>path2</code> argument to the constructor, if any,
185otherwise <code>path()</code>. An implementation is permitted to return an empty
186path if an exception, for example, std::bad_alloc,&nbsp; occurs during
187processing.</p>
188</blockquote>
189
190<h2><a name="Acknowledgements">Acknowledgements</a></h2>
191
192<p>Peter Dimov patiently identified requirements for portability and
193internationalization of error messages. </p>
194<hr>
195<p>Revised
196<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->28 February, 2005<!--webbot bot="Timestamp" endspan i-checksum="40416" --></p>
197
198<p>© Copyright Beman Dawes, 2002</p>
199<p> Use, modification, and distribution are subject to the Boost Software
200License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt">
201LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
202www.boost.org/LICENSE_1_0.txt</a>)</p>
203
204</body>
205
206</html>
Note: See TracBrowser for help on using the repository browser.