Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r57434 - sandbox/filesystem-v3/libs/filesystem/doc
From: bdawes_at_[hidden]
Date: 2009-11-06 09:17:58

Next message: hartmut.kaiser_at_[hidden]: "[Boost-commit] svn:boost r57435 - in trunk: boost/spirit/home/karma/operator libs/spirit/test/karma"
Previous message: jewillco_at_[hidden]: "[Boost-commit] svn:boost r57433 - trunk/libs/graph/build"

Author: bemandawes
Date: 2009-11-06 09:17:57 EST (Fri, 06 Nov 2009)
New Revision: 57434
URL: http://svn.boost.org/trac/boost/changeset/57434

Log:
Improve "Error reporting" wording. Refine error reporting spec for status(). Apply Throws clauses more uniformly.
Text files modified:
sandbox/filesystem-v3/libs/filesystem/doc/reference.html | 401 ++++++++++++++++++++++++++-------------
1 files changed, 267 insertions(+), 134 deletions(-)

Modified: sandbox/filesystem-v3/libs/filesystem/doc/reference.html
==============================================================================
--- sandbox/filesystem-v3/libs/filesystem/doc/reference.html (original)
+++ sandbox/filesystem-v3/libs/filesystem/doc/reference.html 2009-11-06 09:17:57 EST (Fri, 06 Nov 2009)
@@ -43,7 +43,7 @@
 <a href="#Definitions">Definitions</a> 
 <a href="#Header-filesystem-synopsis">
 Header <filesystem> synopsis</a> 
- Error reporting 
+ Error reporting 
 <a href="#Class-template-path">
 Class path</a> 
    
@@ -234,7 +234,7 @@

 class recursive_directory_iterator;

- enum <a name="file_type">file_type</a> { status_unknown, file_not_found, regular_file, directory_file,
+ enum <a name="file_type">file_type</a> { status_error, file_not_found, regular_file, directory_file,
 symlink_file, block_file, character_file, fifo_file, socket_file,
 type_unknown
 };
@@ -345,23 +345,47 @@

 } // namespace filesystem
 } // namespace boost</pre>
-<h4><a name="Error-handling">Error reporting</a></h4>
-Filesystem functions report errors in one of two ways:
-<blockquote>
+<h4><a name="Error-reporting">Error reporting</a></h4>
+Use cases for the Filesystem library include situations where:
+<ul>
+ <li>File system
+errors are truly exceptional and indicate a serious failure. Throwing an
+ exception is the most appropriate response. 
+ </li>
+ <li>File system system errors are routine and do not necessarily represent
+ failure. Returning an error code is the most appropriate response.</li>
+</ul>
+To support both uses cases, many filesystem library functions provide two overloads, one that
+throws an exception to report file system errors, and another that sets an
+<code>error_code</code>.
Functions not having an argument of type
-<code>system::error_code& ec</code> report errors by throwing exceptions:
+<code>system::error_code&</code>, unless otherwise specified,
+report errors as follows:
 <ul>
- <li>Exceptions of type <code>system_error</code> are thrown when a call by the
+ <li>When a call by the
 implementation to an operating system or other underlying API results in an
- error that prevents the function from meeting its specifications.</li>
- <li>Failure to allocate storage is reported as described in the C++ standard,
+ error that prevents the function from meeting its specifications, an exception
+ of type
+<code>filesystem_error</code> is thrown. 
+ </li>
+ <li>Failure to allocate storage is reported by throwing an exception as described in the C++ standard,
 17.6.4.10 [res.on.exception.handling].</li>
 </ul>
 Functions having an argument of type
-<code>system::error_code& ec</code> report errors by setting ec as appropriate
- for the specific error encountered. If no error is encountered, <code>ec.clear()</code>
- is called.
-</blockquote>
+<code>system::error_code&</code>, unless otherwise specified, report errors as follows:
+<ul>
+ <li>If a call by the
+ implementation to an operating system or other underlying API results in an
+ error that prevents the function from meeting its specifications, the
+<code>system::error_code&</code> argument is set as
+ appropriate appropriate for the specific error. Otherwise, <code>clear()</code>
+ is called on the
+<code>system::error_code&</code> argument. 
+ </li>
+ <li>Failure to allocate storage is reported by
+ throwing an exception as described in the C++ standard,
+ 17.6.4.10 [res.on.exception.handling].</li>
+</ul>
<h3><a name="Class-template-path">Class <code>path</code></a></h3>
An object of class <code>path</code> represents a path,
and contains a pathname in the
@@ -533,9 +557,9 @@
 </li>
</ul>
<div align="left">
- <table border="1" cellpadding="10" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="90%">
+ <table border="1" cellpadding="10" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
 <tr>
- <td width="90%" bgcolor="#D7EEFF">
+ <td bgcolor="#D7EEFF">
 [Note:
 POSIX-like implementations, including Cygwin:
 The portable format and the native format are the same, and the encoding
@@ -1715,7 +1739,7 @@
 class file_status
 {
 public:
- explicit file_status( file_type v = status_unknown );
+ explicit file_status( file_type v = status_error );

 <a href="#file_type">file_type</a> type() const;
 void type( file_type v );
@@ -1729,7 +1753,7 @@
 additional status information. --end note]
</blockquote>
<h4>Members</h4>
-<pre>explicit file_status( file_type v = status_unknown );</pre>
+<pre>explicit file_status( file_type v = status_error );</pre>
<blockquote>
 Effects: Stores <code>v</code>.
</blockquote>
@@ -1743,7 +1767,7 @@
 value.
</blockquote>
<h3><a name="Operational-functions">Operational functions</a></h3>
-Operational functions query or modify files, including directories of files, in external
+Operational functions query or modify files, including directories, in external
storage.
Operational functions access a file by resolving an
object of class <code>path</code> to a particular file in a file hierarchy. The
@@ -1754,8 +1778,8 @@
<a href="#Race-condition">race conditions</a>, and many
other kinds of errors occur frequently in file system operations, users should be aware
that any filesystem operational function, no matter how apparently innocuous, may encounter
-an error. See Error reporting. -- end note]
-<h4><a name="Function-specifications">Function specifications</a></h4>
+an error. See Error reporting. -- end note]
+<h4><a name="Function-specifications">Operational function specifications</a></h4>
<pre>path <a name="complete">complete</a>(const path& p, const path& base, system::error_code& ec);</pre>
<blockquote>
 Effects: Composes a complete path from <code>p</code> and <code>base</code>,
@@ -1778,12 +1802,13 @@
 <td align="center"><code>base / p</code></td>
 </tr>
 </table>
- Returns: The composed path.
- Postcondition: For the returned path, <code>rp,</code> <code>
+ Postconditions: For the returned path, <code>rp,</code> <code>
 rp.is_complete()</code> is true.
- Throws: <code>filesystem_error</code>
- if <code>
- !(base.is_complete() && (p.is_complete() || !p.has_root_name()))</code>
+ Returns: The composed path.
+ Throws: <code>
+ filesystem_error</code> if
+ <code>
+ !(base.is_complete() && (p.is_complete() || !p.has_root_name()))</code>
 [<a name="complete_note">Note</a>: When portable behavior is
 required, use complete(). When operating system dependent behavior is
 required, use system_complete().
@@ -1798,18 +1823,27 @@
<pre>path complete(const path& p, system::error_code& ec);</pre>
<blockquote>
Returns: <code>path(p, initial_path(), ec)</code>.
+Throws: 
</blockquote>
<pre>void copy_file(const path& from, const path& to);</pre>
<blockquote>
 Effects: <code>copy_file(from, to,
 copy_option::fail_if_exists)</code>.

+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
+
</blockquote>
<pre>void copy_file(const path& from, const path& to, system::error_code& ec);</pre>
<blockquote>
 Effects: <code>copy_file(from, to,
 copy_option::fail_if_exists, ec)</code>.

+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
+
</blockquote>
<pre>void <a name="copy_file">copy_file</a>(const path& from, const path& to, BOOST_SCOPED_ENUM(copy_option) option);
void <a name="copy_file">copy_file</a>(const path& from, const path& to, BOOST_SCOPED_ENUM(copy_option) option, system::error_code& ec);</pre>
@@ -1817,6 +1851,9 @@
 Effects: If <code>option == copy_option::</code><code>fail_if_exists
 && exists(to)</code>, an error is reported. Otherwise, the contents and attributes of the file <code>from</code>
 resolves to are copied to the file <code>to</code> resolves to.
+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
</blockquote>
<pre>bool <a name="create_directories">create_directories</a>(const path& p);
bool <a name="create_directories">create_directories</a>(const path& p, system::error_code& ec);</pre>
@@ -1824,11 +1861,12 @@
 Requires: <code>p.empty() || 
 forall px: px == p || is_parent(px, p): is_directory(px) || !exists( px )</code>
 
+ Postconditions: <code>is_directory(p)</code>
 Returns: The value of <code>!exists(p)</code> prior to the
 establishment of the postcondition.
- Postcondition: <code>is_directory(p)</code>
- Throws:  <code>filesystem_error</code> if<code>
- exists(p) && !is_directory(p)</code>
+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
</blockquote>
<pre>bool <a name="create_directory">create_directory</a>(const path& p);
bool <a name="create_directory">create_directory</a>(const path& p, system::error_code& ec);</pre>
@@ -1836,10 +1874,12 @@
 Effects: Attempts to create the directory <code>p</code> resolves to,
 as if by POSIX <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mkdir.html">mkdir()</a></code> with a second argument of S_IRWXU|S_IRWXG|S_IRWXO. 
- Throws: <code>filesystem_error</code> if 
- Effects fails for any reason other than because the directory already exists.
- Returns: True if a new directory was created, otherwise false.
- Postcondition: <code>is_directory(dp)</code>
+ Postcondition: <code>is_directory(p)</code>
+ Returns: <code>true</code> if a new directory was created, otherwise
+ <code>false</code>.
+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
</blockquote>
<pre>void <a name="create_hard_link">create_hard_link</a>(const path& p, const path& new_link);
void <a name="create_hard_link">create_hard_link</a>(const path& p, const path& new_link, system::error_code& ec);</pre>
@@ -1857,6 +1897,9 @@
 <li>The contents of the file or directory
 <code>p</code> resolves to are unchanged.</li>
 </ul>
+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
 [Note:
 Some operating systems do not support hard links at all or support
 them only for regular files. Some file systems do not support hard
@@ -1875,8 +1918,11 @@
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/symlink.html">
 symlink()</a></code>.
 
- Postcondition: <code>new_link</code> resolves to a symbolic link file that
+ Postconditions: <code>new_link</code> resolves to a symbolic link file that
 contains an unspecified representation of <code>p</code>.
+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
 [Note:
 Some operating systems do not support symbolic links at all or support
 them only for regular files.
@@ -1894,6 +1940,9 @@
 <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/getcwd.html">
 getcwd()</a></code>. <code>is_complete()</code> is true for the returned path.
+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
 [Note: The current path as returned by many operating systems is a
 dangerous global variable. It may be changed unexpectedly by a third-party or
 system library functions, or by another thread. For a safer alternative,
@@ -1904,17 +1953,30 @@
<pre>void current_path(const path& p);
void current_path(const path& p, system::error_code& ec);</pre>
<blockquote>
-Postcondition: <code>equivalent(p, current_path())</code>.
+ Effects:
+ Establishes the postcondition, as if by 
+ POSIX
+ <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/chdir.html">
+ chdir()</a></code>.
+Postconditions: <code>equivalent(p, current_path())</code>.
+Throws: As specified in
+<a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+Error reporting</a>.
</blockquote>
<pre>bool <a name="exists">exists</a>(file_status s);</pre>
<blockquote>
 Returns:
 <code>status_known(s) && s.type() != file_not_found</code>
+ Throws: Nothing.
</blockquote>
<pre>bool <a name="exists2">exists</a>(const path& p);
bool <a name="exists2">exists</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
- Returns: <code>exists( status(p, ec) )</code>
+ Returns: <code>exists(status(p))</code> or <code>exists(status(p, ec))</code>,
+ respectively.
+Throws: <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+nothing.
</blockquote>
<pre><code>bool <a name="equivalent">equivalent</a>(const path& p1, const path& p2);
bool <a name="equivalent">equivalent</a>(const path& p1, const path& p2, system::error_code& ec);</code></pre>
@@ -1922,11 +1984,10 @@
 Effects: Determines <code>file_status s1</code>
 and <code>s2</code>, as if by <code>status(p1)</code> and  <code>status(p2)</code>,
 respectively.
- Throws: <code>filesystem_error</code>
- if <code>(!exists(s1) && !exists(s2)) || (is_other(s1) && is_other(s2))</code>.
 Returns: <code>true</code>, if <code>sf1 ==
 sf2</code> and <code>p1</code> and <code>p2</code> resolve to the same file
 system entity, else <code>false</code>.
+ <blockquote>
 Two paths are considered to resolve to the same
 file system entity if two candidate entities reside on the same device at the
 same location. This is determined as if by the values of the POSIX
@@ -1945,6 +2006,12 @@
 <code>nFileIndexHigh</code>, <code>nFileIndexLow</code>, <code>nFileSizeHigh</code>,
 <code>nFileSizeLow</code>, <code>ftLastWriteTime.dwLowDateTime</code>, and
 <code>ftLastWriteTime.dwHighDateTime</code>. -- end note]
+ </blockquote>
+ Throws: <code>filesystem_error</code>
+ if <code>(!exists(s1) && !exists(s2)) || (is_other(s1) && is_other(s2))</code>,
+ otherwise as specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
</blockquote>
<pre>uintmax_t <a name="file_size">file_size</a>(const path& p);
uintmax_t <a name="file_size">file_size</a>(const path& p, system::error_code& ec);</pre>
@@ -1957,13 +2024,17 @@
 obtained as if by POSIX <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>.
 Throws: <code>filesystem_error</code>
- if <code>!exists(p) || !is_regular_file(p)</code>.
+ if <code>!exists(p) || !is_regular_file(p)</code>,
+ otherwise as specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
</blockquote>
<pre>const path& <a name="initial_path">initial_path</a>();
const path& <a name="initial_path">initial_path</a>(system::error_code& ec);</pre>
<blockquote>
 Returns: <code>current_path()</code> at the time of entry to <code>
 main()</code>.
+ Throws: Nothing.
 [Note: These semantics turn a dangerous global variable into a safer
 global constant. --end note]
 [Note: Full implementation requires runtime library support.
@@ -1979,62 +2050,70 @@
<blockquote>
 Returns: 
 <code>s.type() == directory_file</code>
+ Throws: Nothing.
</blockquote>
<pre><code>bool <a name="is_directory2">is_directory</a>(const path& p);
bool <a name="is_directory2">is_directory</a>(const path& p, system::error_code& ec);</code></pre>
<blockquote>
- Returns: <code>is_directory( status(p, ec) )</code>
+ Returns: <code>is_<a name="is_directory2">directory</a>(status(p))</code> or <code>is_directory(status(p, ec))</code>,
+ respectively.
+Throws: <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+nothing.
</blockquote>
-<pre><code>bool <a name="is_empty">is_</a><a name="is_empty">empty</a>(const path& p);
-bool <a name="is_empty">is_</a><a name="is_empty">empty</a>(const path& p, system::error_code& ec);</code></pre>
+<pre><code>bool <a name="is_empty">is_</a><a name="is_empty">empty</a>(const path& p);
+bool <a name="is_empty">is_</a><a name="is_empty">empty</a>(const path& p, system::error_code& ec);</code></pre>
<blockquote>
- Effects: Determines <code>file_status s</code>, as if by <code>
- status(p, ec)</code>.
- Returns: <code>is_directory(s) 
+ Effects: Determines
+ <code>file_status s</code>, as if by
+ <code>
+ status(p, ec)</code>.
+ Returns:
+ <code>is_directory(s) 
         ?
 directory_iterator(p) == directory_iterator() 
-         : file_size(p) == 0;</code>
+         : file_size(p) == 0;</code>
+</blockquote>
+<pre>bool <code><a name="is_regular_file">is_regular_file</a></code>(file_status s);</pre>
+<blockquote>
+ Returns:
+ <code>s.type() == regular_file</code>
+ Throws: Nothing.
+</blockquote>
+<pre><code>bool <a name="is_regular_file2">is_regular_file</a>(const path& p);
+bool <a name="is_regular_file2">is_regular_file</a>(const path& p, system::error_code& ec);</code></pre>
+<blockquote>
+ Returns: <code>is_regular_file(status(p))</code> or <code>is_regular_file(status(p, ec))</code>,
+ respectively.
+ Throws: <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+ nothing.
</blockquote>
<pre>bool <a name="is_other">is_other</a>(file_status s);</pre>
<blockquote>
 Returns:
 <code>return exists(s) && !is_regular_file(s) && !is_directory(s) && !is_symlink(s)</code>
- [Note: The specification of
- <code>is_other()</code> will remain unchanged even if additional <code>is_xxx()</code>
- functions are added in the future. -- end note]
+ Throws: Nothing.
</blockquote>
<pre><code>bool <a name="is_other2">is_other</a>(const path& p);
bool <a name="is_other2">is_other</a>(const path& p, system::error_code& ec);</code></pre>
<blockquote>
- Returns: <code>is_other( status(p, ec) )</code>
-</blockquote>
-<pre>bool <code><a name="is_regular_file">is_regular_file</a></code>(file_status s);</pre>
-<blockquote>
- Returns:
- <code>s.type() == regular_file</code>
- Throws: Nothing.
-</blockquote>
-<pre><code>bool <a name="is_regular_file2">is_regular_file</a>(const path& p);</code></pre>
-<blockquote>
- Returns:
- <code>is_regular_file( status(p) )</code>
- Throws: Nothing.
-</blockquote>
-<pre><code>bool <a name="is_regular_file2">is_regular_file</a>(const path& p, system::error_code& ec);</code></pre>
-<blockquote>
- Returns:
- <code>is_regular_file( status(p, ec) )</code>
- Throws: Nothing.
+ Returns: <code>is_other(status(p))</code> or <code>is_other(status(p, ec))</code>,
+ respectively.
+ Throws: <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+ nothing.
</blockquote>
<pre>bool <a name="is_symlink">is_symlink</a>(file_status s);</pre>
<blockquote>
 Returns: 
 <code>s.type() == symlink_file</code>
+ Throws: Nothing.
</blockquote>
<pre><code>bool <a name="is_symlink2">is_symlink</a>(const path& p);
bool <a name="is_symlink2">is_symlink</a>(const path& p, system::error_code& ec);</code></pre>
<blockquote>
- Returns: <code>is_symlink( symlink_status(p, ec) )</code>
+ Returns: <code>is_symlink(symlink_status(p))</code> or <code>is_symlink(symlink_status(p, ec))</code>,
+ respectively.
+ Throws: <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+ nothing.
</blockquote>
<pre>std::time_t <a name="last_write_time">last_write_time</a>(const path& p);
std::time_t <a name="last_write_time">last_write_time</a>(const path& p<code>, system::error_code& ec</code>);</pre>
@@ -2055,22 +2134,30 @@
 followed by POSIX
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/utime.html">
 <code>utime()</code></a>.
+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
 [Note: A postcondition of <code>last_write_time(p) ==
- new_time</code> is not specified since it would not hold for file systems
- with coarse time mechanism granularity. -- end note]
+ new_time</code> is not specified since it might not hold for file systems
+ with coarse time granularity. -- end note]
</blockquote>
<pre>bool <a name="remove">remove</a>(const path& p);
bool <a name="remove">remove</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
- Remarks:  If <code>exists(symlink_status(p,ec))</code>, it is
+ Effects:  If <code>exists(symlink_status(p,ec))</code>, it is
 removed
 as if by POSIX <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/remove.html">remove()</a></code>.
+ <blockquote>
+ [Note: A symbolic link is itself removed, rather than the file it
+ resolves to being removed. -- end note]
+ </blockquote>
 Postcondition: <code>!exists(symlink_status(p))</code>.
 Returns:  <code>false</code> if p did not exist in the first
 place, otherwise <code>true</code>.
- [Note: A symbolic link is itself removed, rather than the file it
- resolves to being removed. -- end note]
+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
</blockquote>
<pre>uintmax_t <a name="remove_all">remove_all</a>(const path& p);
uintmax_t <a name="remove_all">remove_all</a>(const path& p, system::error_code& ec);</pre>
@@ -2079,10 +2166,15 @@
 then deletes file <code>p</code> itself,
 as if by POSIX <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/remove.html">remove()</a></code>.
- Returns: The number of files removed.
- Postcondition: <code>!exists(p)</code>
+ <blockquote>
 [Note: A symbolic link is itself removed, rather than the file it
 resolves to being removed. -- end note]
+ </blockquote>
+ Postcondition: <code>!exists(p)</code>
+ Returns: The number of files removed.
+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
</blockquote>
<pre>void <a name="rename">rename</a>(const path& from, const path& to);
void <a name="rename">rename</a>(const path& from, const path& to, system::error_code& ec);</pre>
@@ -2091,19 +2183,27 @@
 POSIX <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/rename.html">
 rename()</a></code>.
- Postconditions: <code>!exists(from) && exists(to)</code>, and
- the contents and attributes of the file originally named <code>from</code>
- are otherwise unchanged.
+ <blockquote>
 [Note: If <code>from</code> and <code>to</code> resolve to the
 same file, no action is taken. Otherwise, if <code>to</code> resolves to an
 existing file, it is removed. A symbolic link is itself renamed, rather than
 the file it resolves to being renamed. -- end note]
+ </blockquote>
+ Postconditions: <code>!exists(from) && exists(to)</code>, and
+ the contents and attributes of the file originally named <code>from</code>
+ are otherwise unchanged.
+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
</blockquote>
<pre>void <a name="resize_file">resize_file</a>(const path& p, uintmax_t new_size);
void <a name="resize_file">resize_file</a>(const path& p, uintmax_t new_size, system::error_code& ec);</pre>
<blockquote>
-Postcondition: <code>file_size() == new_size</code>.
- Remarks: Achieves its postcondition as if by
+Postconditions: <code>file_size() == new_size</code>.
+Throws: As specified in
+<a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+Error reporting</a>.
+ Remarks: Achieves its postconditions as if by
 POSIX <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/truncate.html">
 truncate()</a></code>.
@@ -2122,9 +2222,12 @@
 member, and assigning the results to the <code>capacity</code>, <code>free</code>,
 and <code>available</code> members respectively. Any members for which the
 value cannot be determined shall be set to -1.
+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
</blockquote>
-<pre>file_status <a name="status">status</a>(const path& p);
-file_status <a name="status">status</a>(const path& p, system::error_code& ec);</pre>
+<pre>file_status <a name="status">status</a>(const path& p);
+file_status <a name="status">status</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
 Effects: 
 <blockquote>
@@ -2132,58 +2235,82 @@
 of
 <code>p</code> as if by POSIX <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>.
- [Note: For symbolic links, <code>stat()</code> continues
- pathname resolution using the contents of the symbolic link. --
+ [Note: If a symbolic link is encountered during pathname
+ resolution,
+ pathname resolution continues using the contents of the symbolic link. --
 end note]
- </blockquote>
- Returns:
- <blockquote>
- If the underlying file system API reports an error during attribute determination:
+ For the <code>error_code&</code> overload:
 <ul>
- <li>If the error indicates that <code>p</code> could not be resolved, as
- if by POSIX errors ENOENT or ENOTDIR, call <code>ec.clear()</code>if ec is
- present and return <code>
- file_status(not_found_flag)</code>.</li>
+ <li>If the underlying file system API reports no error during attribute
+ determination, <code>ec.clear()</code>. 
+ </li>
+ <li>Otherwise, <code>ec</code> is set according to the error reported by
+ the underlying file system API.</li>
 </ul>
 <blockquote>
- <blockquote>
- [Note: The effect of this behavior is to distinguish between
- knowing that <code>p</code>
- does not exist, and not being able to determine the status of <code>p</code>. This
- distinction is important to users.  --end note]
- </blockquote>
+ [Note: This allows users to inspect the specifics of underlying
+ API errors even when the value returned by <code>status()</code> is <code>
+ file_status(file_not_found)</code>.  --end note]
+ </blockquote>
 </blockquote>
+ Returns:
+ <blockquote>
+ If the underlying file system API reported an error during attribute determination:
 <ul>
- <li>Otherwise, set <code>ec</code> if present to represent the error
- reported by the underlying file system API,
- and return <code>
- file_status(status_unknown)</code>.</li>
+ <li>If the error indicated that <code>p</code> could not be resolved, as
+ if by POSIX errors ENOENT or ENOTDIR, return <code>
+ file_status(file_not_found)</code>. [Note: Windows equivalents
+ include ERROR_FILE_NOT_FOUND, ERROR_PATH_NOT_FOUND, ERROR_INVALID_NAME,
+ ERROR_INVALID_PARAMETER, ERROR_BAD_PATHNAME, and ERROR_BAD_NETPATH. --
+ end note] 
+ </li>
+ <li>Otherwise, if the error indicates that <code>p</code> can be resolved
+ but the attributes cannot be determined, return <code>
+ file_status(type_unknown)</code>. [Note: For example, Windows
+ ERROR_SHARING_VIOLATION errors. The case never arises on POSIX. -- end
+ note] 
+ </li>
+ <li>Otherwise, for the overload without <code>error_code&</code>,
+ throw an exception of type <code>filesystem_error</code>. 
+ </li>
+ <li>Otherwise, return <code>
+ file_status(status_error)</code>.</li>
 </ul>
- Otherwise:
+ [Note: These semantics distinguish between
+ <code>p</code> being known not to exist and not being able to determine the status of <code>p</code>. The
+ distinction is important to some users.  --end note]
+ Otherwise,
 <ul>
 <li>If the attributes indicate a regular file, as if by POSIX S_ISREG(),
 return <code>
- file_status(regular_file)</code>.</li>
- <li>Else if the attributes indicate a directory, as if by POSIX S_ISDIR(),
+ file_status(regular_file)</code>. 
+ </li>
+ <li>Otherwise, if the attributes indicate a directory, as if by POSIX S_ISDIR(),
 return <code>
- file_status(directory_file)</code>.</li>
- <li>Else if the attributes indicate a symbolic link, as if by POSIX S_ISLNK(),
+ file_status(directory_file)</code>. 
+ </li>
+ <li>Otherwise, if the attributes indicate a symbolic link, as if by POSIX S_ISLNK(),
 return <code>
 file_status(symlink_file)</code>. [Note: Only possible for <code>
- symlink_status</code>. --end note]</li>
- <li>Else if the attributes indicate a block special file, as if by POSIX S_ISBLK(),
+ symlink_status</code>. --end note] 
+ </li>
+ <li>Otherwise, if the attributes indicate a block special file, as if by POSIX S_ISBLK(),
 return <code>
- file_status(block_file)</code>.</li>
- <li>Else if the attributes indicate a character special file, as if by POSIX S_ISCHR(),
+ file_status(block_file)</code>. 
+ </li>
+ <li>Otherwise, if the attributes indicate a character special file, as if by POSIX S_ISCHR(),
 return <code>
- file_status(character_file)</code>.</li>
- <li>Else if the attributes indicate a fifo or pipe file, as if by POSIX S_ISFIFO(),
+ file_status(character_file)</code>. 
+ </li>
+ <li>Otherwise, if the attributes indicate a fifo or pipe file, as if by POSIX S_ISFIFO(),
 return <code>
- file_status(fifo_file)</code>.</li>
- <li>Else if the attributes indicate a socket, as if by POSIX S_ISSOCK(),
+ file_status(fifo_file)</code>. 
+ </li>
+ <li>Otherwise, if the attributes indicate a socket, as if by POSIX S_ISSOCK(),
 return <code>
- file_status(socket_file)</code>.</li>
- <li>Else return <code>
+ file_status(socket_file)</code>. 
+ </li>
+ <li>Otherwise, return <code>
 file_status(type_unknown)</code>.</li>
 </ul>
 </blockquote>
@@ -2195,40 +2322,46 @@
<code>regular_file</code> does not necessarily imply <code><fstream></code> operations would
fail on a directory.
-- end note]
-Throws: Nothing.
+Throws: <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+nothing.
</blockquote>
<pre>bool <a name="status_known">status_known</a>(file_status s);</pre>
<blockquote>
 Returns:
- <code>s.type() != status_unknown</code>
+ <code>s.type() != status_error</code>
+ Throws: Nothing.
</blockquote>
<pre>file_status <a name="symlink_status">symlink_status</a>(const path& p);
file_status <a name="symlink_status">symlink_status</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
- Effects: 
- <blockquote>
- Determines the attributes
+ Effects:  Same as status(), above,
+ except that the attributes
 of
- <code>p</code> as if by POSIX <code>
+ <code>p</code> are determined as if by POSIX <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/lstat.html">
- lstat()</a></code>..
- [Note: For symbolic links, <code>lstat()</code> does not
- continue pathname resolution when a symbolic link is encountered. --
+ lstat()</a></code>.
+</blockquote>
+<blockquote>
+ <blockquote>
+ [Note: Pathname resolution is complete if <code>p</code> names a symbolic link. --
 end note]
- </blockquote>
-Returns: As specified for status(),
-above.
-Throws: Nothing.
+ </blockquote>
+ Returns: Same as status(), above.
+Throws: <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+nothing.
</blockquote>
-<pre>path <a name="system_complete">system_complete</a>(const path& p, system::error_code& ec);</pre>
+<pre>path <a name="system_complete">system_complete</a>(const path& p);
+path <a name="system_complete">system_complete</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
 Effects: Composes a complete path from <code>p</code>, using the
 same rules used by the operating system to resolve a path passed as the
 filename argument to standard library open functions.
 Returns: The composed path.
- Postcondition: For the returned path, <code>rp,</code> <code>
+ Postconditions: For the returned path, <code>rp,</code> <code>
 rp.is_complete()</code> is true.
- Throws: If <code>p.empty()</code>.
+ Throws: As specified in
+ <a href="file:///C:/boost/filesystem-v3-sandbox/libs/filesystem/doc/reference.html#Error-reporting">
+ Error reporting</a>.
 [Note: For POSIX, <code>system_complete(p)</code> has the same semantics as
 <code>complete(p, current_path())</code>.
 <a name="windows_effects">For Windows</a>, <code>system_complete(p)</code> has the
@@ -3006,7 +3139,7 @@
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>
Revised
-28 October 2009
+04 November 2009

</body>

Next message: hartmut.kaiser_at_[hidden]: "[Boost-commit] svn:boost r57435 - in trunk: boost/spirit/home/karma/operator libs/spirit/test/karma"
Previous message: jewillco_at_[hidden]: "[Boost-commit] svn:boost r57433 - trunk/libs/graph/build"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk