Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r57255 - sandbox/filesystem-v3/libs/filesystem/doc
From: bdawes_at_[hidden]
Date: 2009-10-30 17:28:14

Author: bemandawes
Date: 2009-10-30 17:28:14 EDT (Fri, 30 Oct 2009)
New Revision: 57255
URL: http://svn.boost.org/trac/boost/changeset/57255

Log:
filesystem-v3: work-in-progress
Text files modified:
sandbox/filesystem-v3/libs/filesystem/doc/reference.html | 369 ++++++++++++++++++++++++---------------
1 files changed, 223 insertions(+), 146 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-10-30 17:28:14 EDT (Fri, 30 Oct 2009)
@@ -257,73 +257,111 @@

 // operational functions

- path complete(const path& p, const path& base, system::error_code& ec=throws());
- path complete(const path& p, system::error_code& ec=throws());
- void copy_file(const path& from, const path& to,
- BOOST_SCOPED_ENUM(copy_option) option, system::error_code& ec=throws());
- void copy_file(const path& from, const path& to, system::error_code& ec=throws());
- bool create_directories(const path& p, system::error_code& ec=throws());
- bool create_directory(const path& p, system::error_code& ec=throws());
- void create_hard_link(const path& p, const path& new_link, system::error_code& ec=throws());
- void create_symlink(const path& p, const path& new_link, system::error_code& ec=throws());
- path current_path(system::error_code& ec=throws());
- void current_path(const path& p, system::error_code& ec=throws());
+ path complete(const path& p, const path& base, system::error_code& ec);
+ path complete(const path& p, system::error_code& ec);
+
+ void copy_file(const path& from, const path& to);
+ void copy_file(const path& from, const path& to, system::error_code& ec);
+ void copy_file(const path& from, const path& to, BOOST_SCOPED_ENUM(copy_option) option);
+ void copy_file(const path& from, const path& to, BOOST_SCOPED_ENUM(copy_option) option,
+ system::error_code& ec);
+
+ bool create_directories(const path& p);
+ bool create_directories(const path& p, system::error_code& ec);
+
+ bool create_directory(const path& p);
+ bool create_directory(const path& p, system::error_code& ec);
+
+ void create_hard_link(const path& p, const path& new_link);
+ void create_hard_link(const path& p, const path& new_link, system::error_code& ec);
+
+ void create_symlink(const path& p, const path& new_link);
+ void create_symlink(const path& p, const path& new_link, system::error_code& ec);
+
+ path current_path();
+ path current_path(system::error_code& ec);
+ void current_path(const path& p);
+ void current_path(const path& p, system::error_code& ec);
+
 bool exists(file_status s);
- bool exists(const path& p, system::error_code& ec=throws());
- bool equivalent(const path& p1, const path& p2, system::error_code& ec=throws());
- uintmax_t file_size(const path& p, system::error_code& ec=throws());
- const path& initial_path(system::error_code& ec=throws());
+ bool exists(const path& p);
+ bool exists(const path& p, system::error_code& ec);
+
+ bool equivalent(const path& p1, const path& p2);
+ bool equivalent(const path& p1, const path& p2, system::error_code& ec);
+
+ uintmax_t file_size(const path& p);
+ uintmax_t file_size(const path& p, system::error_code& ec);
+
+ const path& initial_path();
+ const path& initial_path(system::error_code& ec);
+
 bool is_directory(file_status s);
- bool is_directory(const path& p, system::error_code& ec=throws());
- bool is_empty(const path& p, system::error_code& ec=throws());
+ bool is_directory(const path& p);
+ bool is_directory(const path& p, system::error_code& ec);
+
+ bool is_empty(const path& p);
+ bool is_empty(const path& p, system::error_code& ec);
+
 bool is_other(file_status s);
- bool is_other(const path& p, system::error_code& ec=throws());
+ bool is_other(const path& p,);
+ bool is_other(const path& p, system::error_code& ec);
+
 bool is_regular_file(file_status s);
- bool is_regular_file(const path& p, system::error_code& ec=throws());
+ bool is_regular_file(const path& p);
+ bool is_regular_file(const path& p, system::error_code& ec);
+
 bool is_symlink(file_status s);
- bool is_symlink(const path& p, system::error_code& ec=throws());
- std::time_t last_write_time(const path& p, system::error_code& ec=throws());
- void last_write_time(const path& p, const std::time_t new_time, system::error_code& ec=throws());
- bool remove(const path& p, system::error_code& ec=throws());
- uintmax_t remove_all(const path& p, system::error_code& ec=throws());
- void rename(const path& from, const path& to, system::error_code& ec=throws());
- space_info space(const path& p, system::error_code& ec=throws());
- file_status status(const path& p, system::error_code& ec=throws());
+ bool is_symlink(const path& p);
+ bool is_symlink(const path& p, system::error_code& ec);
+
+ std::time_t last_write_time(const path& p);
+ std::time_t last_write_time(const path& p, system::error_code& ec);
+ void last_write_time(const path& p, const std::time_t new_time);
+ void last_write_time(const path& p, const std::time_t new_time, system::error_code& ec);
+
+ bool remove(const path& p);
+ bool remove(const path& p, system::error_code& ec);
+
+ uintmax_t remove_all(const path& p);
+ uintmax_t remove_all(const path& p, system::error_code& ec);
+
+ void rename(const path& from, const path& to);
+ void rename(const path& from, const path& to, system::error_code& ec);
+
+ space_info space(const path& p);
+ space_info space(const path& p, system::error_code& ec);
+
+ file_status status(const path& p);
+ file_status status(const path& p, system::error_code& ec);
+
 bool status_known(file_status s);
- file_status symlink_status(const path& p, system::error_code& ec=throws());
- path system_complete(const path& p, system::error_code& ec=throws());
+
+ file_status symlink_status(const path& p);
+ file_status symlink_status(const path& p, system::error_code& ec);
+
+ path system_complete(const path& p);
+ path system_complete(const path& p, system::error_code& ec);

 } // namespace filesystem
 } // namespace boost</pre>
-<h3><a name="Error-handling">Error reporting</a></h3>
-Functions in this library may throw exceptions as described in this section.
-Such exceptions are not explicitly described in each function's Throws
-element.
-Certain functions in this library are specified as having an argument of type
-<code>system::error_code& ec</code>. This argument determines how errors are
-reported by the implementation when a call to an operating system or other
-underlying API results in an error that prevents the library function from
-meeting its specifications:
-<ul>
- <li>If <code>&ec == &throws()</code>, the function throws an exception of type
- <code>filesystem_error.</code></li>
- <li>Otherwise, the function sets <code>ec</code> to an error_code representing
- the error that occurred.</li>
-</ul>
-If an error does not occur and <code>&ec != &throws()</code>, <code>ec.clear()</code>
-is called.
-Certain failures are reported by throwing an exception, regardless of the
-value of the <code>ec</code> argument:
-<ul>
+<h4><a name="Error-handling">Error reporting</a></h4>
+Filesystem functions report errors in one of two ways:
+<blockquote>
+Functions not having an argument of type
+<code>system::error_code& ec</code> report errors by throwing exceptions:
+ <ul>
+ <li>Exceptions of type <code>system_error</code> are thrown 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,
 17.6.4.10 [res.on.exception.handling].</li>
- <li>Class <code>path</code> failures are reported by throwing an exception of
- type <code>system_error</code>.</li>
-</ul>
-[Note: Because hardware failures, network failures, race conditions, and a plethora of
-other errors occur frequently in file system operations, users should be aware
-that any filesystem operational function, no matter how innocuous, may encounter
-an error.  -- end note]
+ </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>
<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
@@ -421,7 +459,7 @@
 iterator end() const;

 // encoding conversion
- static std::locale imbue( const std::locale & loc );
+ static std::locale imbue( const std::locale& loc );
 static const codecvt_type & codecvt()
 };

@@ -1362,8 +1400,8 @@

 // observers
 const path& path() const;
- file_status status(system::error_code& ec=throws()) const;
- file_status symlink_status(system::error_code& ec=throws()) const;
+ file_status status(system::error_code& ec) const;
+ file_status symlink_status(system::error_code& ec) const;

 private:
 path_type m_path; // for exposition only
@@ -1483,7 +1521,7 @@
<blockquote>
 Returns: <code>m_path</code>
</blockquote>
-<pre>file_status status(system::error_code& ec=throws()) const;</pre>
+<pre>file_status status(system::error_code& ec) const;</pre>
<blockquote>
Effects:
As if,
@@ -1498,7 +1536,7 @@
 </blockquote>
 Returns: <code>m_status</code>
</blockquote>
-<pre>file_status symlink_status(system::error_code& ec=throws()) const;</pre>
+<pre>file_status symlink_status(system::error_code& ec) const;</pre>
<blockquote>
Effects:
As if,
@@ -1527,7 +1565,7 @@

 // constructors
 directory_iterator(); // creates the "end" iterator
- explicit directory_iterator(const path& p, system::error_code& ec=throws());
+ explicit directory_iterator(const path& p, system::error_code& ec);

 ~directory_iterator();

@@ -1604,7 +1642,7 @@

</blockquote>

-<pre><code>explicit directory_iterator(</code>const path& p, system::error_code& ec=throws()<code>);</code></pre>
+<pre><code>explicit directory_iterator(</code>const path& p, system::error_code& ec<code>);</code></pre>
<blockquote>

Effects: Constructs a iterator representing the first
@@ -1712,11 +1750,13 @@
path is resolved as if by the POSIX
<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_11">
Pathname Resolution</a> mechanism.
-[Note: Because operational functions are subject to
-race conditions and I/O errors,
-error handling is of particular concern. -- end
-note] 
-<pre>path <a name="complete">complete</a>(const path& p, const path& base, system::error_code& ec=throws());</pre>
+[Note: Because hardware failures, network failures,
+race conditions, 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>
+<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>,
 using the following rules:
@@ -1755,27 +1795,31 @@
 is expected by program users. --
 end note]
</blockquote>
-<pre>path complete(const path& p, system::error_code& ec=throws());</pre>
+<pre>path complete(const path& p, system::error_code& ec);</pre>
<blockquote>
Returns: <code>path(p, initial_path(), ec)</code>.
</blockquote>
-<pre>void <a name="copy_file">copy_file</a>(const path& from, const path& to,
- BOOST_SCOPED_ENUM(copy_option) option, system::error_code& ec=throws());</pre>
+<pre>void copy_file(const path& from, const path& to);</pre>
<blockquote>
- Effects: The contents and attributes of the file <code>from</code>
- resolves to are copied to the file <code>to</code> resolves to.
- Throws: <code>filesystem_error</code> if <code>
- from.empty() || to.empty() ||!exists(from) || !is_regular_file(from) ||
- (option==copy_option::fail_if_exists
- && exists(to))</code>
+ Effects: <code>copy_file(from, to,
+ copy_option::fail_if_exists)</code>.
+
</blockquote>
-<pre>void copy_file(const path& from, const path& to, system::error_code& ec=throws());</pre>
+<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>.

</blockquote>
-<pre>bool <a name="create_directories">create_directories</a>(const path& p, system::error_code& ec=throws());</pre>
+<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>
+<blockquote>
+ 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.
+</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>
<blockquote>
 Requires: <code>p.empty() || 
 forall px: px == p || is_parent(px, p): is_directory(px) || !exists( px )</code>
@@ -1786,7 +1830,8 @@
 Throws:  <code>filesystem_error</code> if<code>
 exists(p) && !is_directory(p)</code>
</blockquote>
-<pre>bool <a name="create_directory">create_directory</a>(const path& p, system::error_code& ec=throws());</pre>
+<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>
<blockquote>
 Effects: Attempts to create the directory <code>p</code> resolves to,
 as if by POSIX <code>
@@ -1796,7 +1841,8 @@
 Returns: True if a new directory was created, otherwise false.
 Postcondition: <code>is_directory(dp)</code>
</blockquote>
-<pre>void <a name="create_hard_link">create_hard_link</a>(const path& p, const path& new_link, system::error_code& ec=throws());</pre>
+<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>
<blockquote>
 Effects: Establishes the postcondition, as if by
 POSIX
@@ -1813,16 +1859,14 @@
 </ul>
 [Note:
 Some operating systems do not support hard links at all or support
- them only for regular files. Some file systems limit the number of links per
- file.
- Some file systems do not
- support
- hard links regardless of the operating system - the FAT system used on floppy discs, memory cards and flash
- drives,
- for example. Thus hard links should only be used if these situations are not
- concerns, or if workarounds are provided. -- end note]
+ them only for regular files. Some file systems do not support hard
+ links regardless of the operating system - the FAT system used on floppy
+ discs, memory cards and flash drives, for example. Some file systems limit the
+ number of links per file. Thus hard links should only be used if these
+ situations are not concerns, or if workarounds are provided. -- end note]
 </blockquote>
-<pre>void <a name="create_symlink">create_symlink</a>(const path& p, const path& new_link, system::error_code& ec=throws());</pre>
+<pre>void <a name="create_symlink">create_symlink</a>(const path& p, const path& new_link);
+void <a name="create_symlink">create_symlink</a>(const path& p, const path& new_link, system::error_code& ec);</pre>
<blockquote style="font-size: 10pt">
 Effects:
 Establishes the postcondition, as if by 
@@ -1843,12 +1887,13 @@
 for example. Thus symbolic links should only be used if these situations are
 not concerns, or if workarounds are provided. -- end note]
 </blockquote>
-<pre>path <a name="current_path">current_path</a>(system::error_code& ec=throws());</pre>
+<pre>path <a name="current_path">current_path</a>();
+path <a name="current_path">current_path</a>(system::error_code& ec);</pre>
<blockquote>
 Returns: The current working directory path, as if by POSIX
+ <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/getcwd.html">
- <code>getcwd()</code></a>.
- Postcondition: <code>current_path().is_complete()</code>
+ getcwd()</a></code>. <code>is_complete()</code> is true for the returned path.
 [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,
@@ -1856,7 +1901,8 @@
 current_path()</code> name was chosen to emphasize that the return is a
 complete path, not just a single directory name. -- end note]
</blockquote>
-<pre>void current_path(const path& p, system::error_code& ec=throws());</pre>
+<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>.
</blockquote>
@@ -1865,11 +1911,13 @@
 Returns:
 <code>status_known(s) && s.type() != file_not_found</code>
</blockquote>
-<pre>bool <a name="exists2">exists</a>(const path& p, system::error_code& ec=throws());</pre>
+<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>
</blockquote>
-<pre><code>bool <a name="equivalent">equivalent</a>(const path& p1, const path& p2, system::error_code& ec=throws());</code></pre>
+<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>
<blockquote style="font-size: 10pt">
 Effects: Determines <code>file_status s1</code>
 and <code>s2</code>, as if by <code>status(p1)</code> and  <code>status(p2)</code>,
@@ -1898,7 +1946,8 @@
 <code>nFileSizeLow</code>, <code>ftLastWriteTime.dwLowDateTime</code>, and
 <code>ftLastWriteTime.dwHighDateTime</code>. -- end note]
</blockquote>
-<pre>uintmax_t <a name="file_size">file_size</a>(const path& p, system::error_code& ec=throws());</pre>
+<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>
<blockquote>
 Returns: The size
 in bytes
@@ -1910,7 +1959,8 @@
 Throws: <code>filesystem_error</code>
 if <code>!exists(p) || !is_regular_file(p)</code>.
</blockquote>
-<pre>const path& <a name="initial_path">initial_path</a>(system::error_code& ec=throws());</pre>
+<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>.
@@ -1930,11 +1980,13 @@
 Returns: 
 <code>s.type() == directory_file</code>
</blockquote>
-<pre><code>bool <a name="is_directory2">is_directory</a>(const path& p, system::error_code& ec=throws());</code></pre>
+<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>
</blockquote>
-<pre><code>bool <a name="is_empty">is_</a><a name="is_empty">empty</a>(const path& p, system::error_code& ec=throws());</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>.
@@ -1942,8 +1994,6 @@
         ?
 directory_iterator(p) == directory_iterator() 
         : file_size(p) == 0;</code>
- Throws: <code>filesystem_error</code> if <code>!exist(s) ||
- is_other(s)</code>.
</blockquote>
<pre>bool <a name="is_other">is_other</a>(file_status s);</pre>
<blockquote>
@@ -1953,29 +2003,41 @@
 <code>is_other()</code> will remain unchanged even if additional <code>is_xxx()</code>
 functions are added in the future. -- end note]
</blockquote>
-<pre><code>bool <a name="is_other2">is_other</a>(const path& p, system::error_code& ec=throws());</code></pre>
+<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>
+<pre>bool <code><a name="is_regular_file">is_regular_file</a></code>(file_status s);</pre>
<blockquote>
- Returns:
+ 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, system::error_code& ec=throws());</code></pre>
+<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, ec) )</code>
+ 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.
</blockquote>
<pre>bool <a name="is_symlink">is_symlink</a>(file_status s);</pre>
<blockquote>
 Returns: 
 <code>s.type() == symlink_file</code>
</blockquote>
-<pre><code>bool <a name="is_symlink2">is_symlink</a>(const path& p, system::error_code& ec=throws());</code></pre>
+<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>
</blockquote>
-<pre>std::time_t <a name="last_write_time">last_write_time</a>(const path& p<code>, system::error_code& ec=throws()</code>);</pre>
+<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>
<blockquote>
 Returns: The time of last data modification of <code>p</code>, determined as if by the
 value of the POSIX <code>
@@ -1983,7 +2045,8 @@
 as if by POSIX <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>.
</blockquote>
-<pre>void <a name="last_write_time2">last_write_time</a>(const path& p, const std::time_t new_time<code>, system::error_code& ec=throws()</code>);</pre>
+<pre>void <a name="last_write_time2">last_write_time</a>(const path& p, const std::time_t new_time);
+void <a name="last_write_time2">last_write_time</a>(const path& p, const std::time_t new_time<code>, system::error_code& ec</code>);</pre>
<blockquote>
 Effects: Sets the time of last data modification of the file
 resolved to by <code>p</code>
@@ -1996,7 +2059,8 @@
 new_time</code> is not specified since it would not hold for file systems
 with coarse time mechanism granularity. -- end note]
</blockquote>
-<pre>bool <a name="remove">remove</a>(const path& p, system::error_code& ec=throws());</pre>
+<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
 removed
@@ -2008,7 +2072,8 @@
 [Note: A symbolic link is itself removed, rather than the file it
 resolves to being removed. -- end note]
</blockquote>
-<pre>uintmax_t <a name="remove_all">remove_all</a>(const path& p, system::error_code& ec=throws());</pre>
+<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>
<blockquote>
 Effects:  Recursively deletes the contents of p if it exists,
 then deletes file <code>p</code> itself,
@@ -2019,31 +2084,32 @@
 [Note: A symbolic link is itself removed, rather than the file it
 resolves to being removed. -- end note]
</blockquote>
-<pre>void <a name="rename">rename</a>(const path& from, const path& to, system::error_code& ec=throws());</pre>
+<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>
<blockquote>
- Effects: Renames <code>from_p</code> to <code>to_p</code>, as if by
+ Effects: Renames <code>from</code> to <code>to</code>, as if by
 POSIX <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/rename.html">
 rename()</a></code>.
- Postconditions: <code>!exists(from_p) && exists(to_p)</code>, and
- the contents and attributes of the file originally named <code>from_p</code>
+ Postconditions: <code>!exists(from) && exists(to)</code>, and
+ the contents and attributes of the file originally named <code>from</code>
 are otherwise unchanged.
- [Note: If <code>from_p</code> and <code>to_p</code> resolve to the
- same file, no action is taken. Otherwise, if <code>to_p</code> resolves to an
+ [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>
-<pre>void <a name="resize_file">resize_file</a>(const path& p, uintmax_t new_size, system::error_code& ec=throws());</pre>
+<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>.
- Throws: <code>filesystem_error</code>
- if <code>!exists(p) || !is_regular_file(p)</code>.
 Remarks: Achieves its postcondition as if by
 POSIX <code>
 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/truncate.html">
 truncate()</a></code>.
</blockquote>
-<pre>space_info <a name="space">space</a>(const path& p, system::error_code& ec=throws());</pre>
+<pre>space_info <a name="space">space</a>(const path& p);
+space_info <a name="space">space</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
 Returns: An object of type <code>
 <a href="#space_info">space_info</a></code>. The value of the <code>space_info</code> object is determined as if by
@@ -2057,46 +2123,42 @@
 and <code>available</code> members respectively. Any members for which the
 value cannot be determined shall be set to -1.
</blockquote>
-<pre>file_status <a name="status">status</a>(const path& p, system::error_code& ec=throws());
-file_status symlink_status(const path& p, system::error_code& ec=throws());</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>
- Returns:
+ Effects: 
 <blockquote>
- For <code>status</code>, determine the attributes
+ Determines the attributes
 of
 <code>p</code> as if by POSIX <code>
- stat()</code>;
- for <code>symlink_status</code>, determine the attributes as if by POSIX <code>
- <a href="http://www.opengroup.org/onlinepubs/000095399/functions/lstat.html">
- lstat()</a></code>.
- <blockquote>
+ stat()</code>.
 [Note: For symbolic links, <code>stat()</code> continues
- pathname resolution using the contents of the symbolic link, <code>lstat()</code>
- does not. --
+ pathname resolution using the contents of the symbolic link. --
 end note]
 </blockquote>
- If the underlying file system reports an error during attribute determination:
+ Returns:
+ <blockquote>
+ If the underlying file system API reports an error during attribute determination:
 <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> and return <code>
+ 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>
 </ul>
 <blockquote>
 <blockquote>
 [Note: The effect of this behavior is to distinguish between
- knowing that p
- does not exist, and not being able to determine the status of p. This
+ 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>
 </blockquote>
 <ul>
- <li>Otherwise, set ec to the error number reported by the underlying
- implementation API
+ <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>
 </ul>
- Under what conditions do
- these functions throw? It isn't at all clear.
 Otherwise:
 <ul>
 <li>If the attributes indicate a regular file, as if by POSIX S_ISREG(),
@@ -2126,24 +2188,39 @@
 </ul>
 </blockquote>
[Note: <code>directory_file</code> implies <code>
-directory_iterator</code> on the file would succeed, and <code>
+directory_iterator(p)</code>would succeed, and <code>
regular_file</code> implies appropriate <code><fstream></code> operations would succeed,
assuming no hardware, permission, access, or race
condition errors. For <code>regular_file,</code> the converse is not true; lack of
<code>regular_file</code> does not necessarily imply <code><fstream></code> operations would
fail on a directory.
-- end note]
+Throws: Nothing.
</blockquote>
<pre>bool <a name="status_known">status_known</a>(file_status s);</pre>
<blockquote>
 Returns:
 <code>s.type() != status_unknown</code>
</blockquote>
-<pre>file_status <a name="symlink_status">symlink_status</a>(const path& p, system::error_code& ec=throws());</pre>
+<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>
-<pre>See status() above.</pre>
+ Effects: 
+ <blockquote>
+ Determines the attributes
+ of
+ <code>p</code> 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. --
+ end note]
+ </blockquote>
+Returns: As specified for status(),
+above.
+Throws: Nothing.
</blockquote>
-<pre>path <a name="system_complete">system_complete</a>(const path& p, system::error_code& ec=throws());</pre>
+<pre>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
@@ -2929,7 +3006,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
-18 October 2009
+28 October 2009

</body>

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