Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r83062 - in trunk/libs/filesystem/doc: . src
From: bdawes_at_[hidden]
Date: 2013-02-21 09:27:11

Next message: marshall_at_[hidden]: "[Boost-commit] svn:boost r83063 - trunk/libs/algorithm/test"
Previous message: adam.wulkiewicz_at_[hidden]: "[Boost-commit] svn:boost r83061 - sandbox/tuple-move/detail"

Author: bemandawes
Date: 2013-02-21 09:27:10 EST (Thu, 21 Feb 2013)
New Revision: 83062
URL: http://svn.boost.org/trac/boost/changeset/83062

Log:
Document the reimplementation of path::codecvt() and path::imbue(), adding a section on path usage concerns.
Text files modified:
   trunk/libs/filesystem/doc/reference.html | 1078 ++++++++++++++++++++++++---------------
   trunk/libs/filesystem/doc/release_history.html | 11
   trunk/libs/filesystem/doc/src/build.bat | 2
   trunk/libs/filesystem/doc/src/source.html | 52 +
   4 files changed, 724 insertions(+), 419 deletions(-)

Modified: trunk/libs/filesystem/doc/reference.html
==============================================================================
--- trunk/libs/filesystem/doc/reference.html (original)
+++ trunk/libs/filesystem/doc/reference.html 2013-02-21 09:27:10 EST (Thu, 21 Feb 2013)
@@ -2,6 +2,9 @@



+
+
+
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
@@ -41,6 +44,7 @@
<body>

+
<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
 <tr>
 <td width="277">
@@ -53,7 +57,8 @@
 </tr>
</table>

-<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
+<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
+ bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
 <tr>
 <td>Filesystem Home   
 <a href="release_history.html">Releases</a>   
@@ -134,12 +139,7 @@
<a href="#Class-directory_iterator">Class <code>directory_iterator</code></a> 
    <a href="#directory_iterator-members"><code>directory_iterator</code>
 members</a> 
-  <code> directory_iterator</code><a href="#directory_iterator-members">
- non-member functions</a> 
<a href="#Class-recursive_directory_iterator">Class <code>recursive_directory_iterator</code></a> 
- <code>  <a href="#recursive_directory_iterator-non-member-functions">
- recursive_directory_iterator</a></code> 
-       non-member functions 
 <a href="#Operational-functions">
 Operational functions</a> 
 <code>   &nbsp absolute 
@@ -157,11 +157,11 @@
   &nbsp equivalent 
   &nbsp file_size 
     hard_link_count 
-      initial_path</code></td>
+      initial_path 
+   &nbsp is_directory 
+   &nbsp is_empty</code></td>
 <td width="34%" valign="top">
- <code>     is_directory 
-   &nbsp is_empty 
-   &nbsp is_other 
+ <code>   &nbsp is_other 
   &nbsp is_regular_file 
   &nbsp is_symlink 
   &nbsp last_write_time 
@@ -195,21 +195,94 @@
to perform operations involving file systems, including paths, regular files,
and directories.

+<blockquote>
+<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
+ bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
+ <tr>
+ <td width="100%" align="center" colspan="2">
+ C++11 SupportThis reference
+ documentation is written as if all compilers supported C++11. Where
+ possible, the implementation falls back to C++03 if a C++11 feature is not
+ available.</td>
+ </tr>
+ <tr>
+ <td width="35%" align="center">
+ C++11 Feature</td>
+ <td width="65%" align="center">
+ Action if not supported by compiler</td>
+ </tr>
+ <tr>
+ <td width="35%" align="left">
+ <code>noexcept</code></td>
+ <td width="65%" align="left">
+ Keyword omitted.</td>
+ </tr>
+ <tr>
+ <td width="35%" align="left">
+ <code>constexpr</code></td>
+ <td width="65%" align="left">
+ Keyword omitted.</td>
+ </tr>
+ <tr>
+ <td width="35%" align="left">
+ R-value references</td>
+ <td width="65%" align="left">
+ Function signature omitted.</td>
+ </tr>
+ <tr>
+ <td width="35%" align="left">
+ New character types</td>
+ <td width="65%" align="left">
+ The <code>boost::filesystem</code> interface doesn't use the
+ new types directly. It does use <code>u16string</code> and <code>u32string</code>
+ in namespace <code>boost</code>. These are typedefs to <code>std::u16string</code>
+ and <code>std::u32string</code> for C++11, or to <code>
+ std::basic_string<boost::u16_t></code> and <code>
+ std::basic_string<boost::u32_t></code> for C++03.</td>
+ </tr>
+ <tr>
+ <td width="35%" align="left">
+ Defaulted and deleted functions</td>
+ <td width="65%" align="left">
+ Workaround replacement functions provided.</td>
+ </tr>
+ <tr>
+ <td width="35%" align="left">
+ Initializer lists</td>
+ <td width="65%" align="left">
+ Not currently used.</td>
+ </tr>
+ <tr>
+ <td width="35%" align="left">
+ Variadic templates</td>
+ <td width="65%" align="left">
+ Not currently used.</td>
+ </tr>
+ <tr>
+ <td width="35%" align="left">
+ Range-based for statements</td>
+ <td width="65%" align="left">
+ Supporting functions always provided; they do no harm even for C++03
+ compilers.</td>
+ </tr>
+</table>
+</blockquote>
+

-This reference documentation describes components that perform operations on file systems and
-their components, such as paths, regular files, and directories.

-<h2><a name="Conformance">Conformance</a></h2>
-Behavior is sometimes specified by reference to ISO/IEC 9945. How such behavior is actually implemented is unspecified.
+<h2><a name="Conformance">Conformance</a> [fs.conformance]</h2>
+
+<h3>ISO/IEC 9945 conformance [fs.conform.9945]</h3>
+Some behavior in this reference documentation is specified by reference to ISO/IEC 9945. How such behavior is actually implemented is unspecified.
<blockquote>
[Note: This constitutes an "as if" rule for implementation of
operating system dependent behavior. In practice implementations will usually call native
operating system API's. --end note]
</blockquote>
-Implementations are encouraged, but not required, to prove such behavior
+Implementations are encouraged to provide such behavior

as it is defined by ISO/IEC 9945. Implementations shall document any
-behavior that differs from the ISO/IEC 9945 defined behavior. Implementations that do not support exact
+behavior that differs from the behavior defined by ISO/IEC 9945. Implementations that do not support exact
ISO/IEC 9945 behavior are
encouraged to provide behavior as close to ISO/IEC 9945 behavior as is reasonable given the
limitations of actual operating systems and file systems. If an implementation cannot provide any
@@ -242,72 +315,132 @@
is unreasonable for a program to detect them prior to calling the function. 
-- end note]
</blockquote>
-<h2><a name="Definitions">Definitions</a></h2>
+<h3>Operating system dependent conformance [fs.conform.os]</h3>
+Some behavior is specified in this reference documentation as being
+operating system dependent ([fs.def.osdep]). The operation system an
+implementation is dependent upon is implementation defined.
+It is permissible for an implementation to be dependent upon an operating
+system emulator rather than the actual operating system.
+<blockquote>
+[Example: An implementation uses Cygwin, a Linux® API emulator for
+some Windows® operating system versions. The implementation would define Cygwin
+as its operating system. Users could refer to the Cygwin documentation to find
+details of the operating system dependent behavior.  --end example]
+It is user and conformance test
+detectable that such an implementation is running on Cygwin. Users would be
+misled and conformance tests would fail if the implementation defined Linux or
+Windows rather than Cygwin as the operating system, since real behavior is a
+blend of the two. 
+</blockquote>
+<h2><a name="Definitions">Definitions</a> [fs.definitions]</h2>
The following definitions shall apply throughout this reference documentation:
-<a name="File">File</a>: An object that can be written to, or read from, or both. A file
+<h3><a name="operating system dependent">operating system dependent</a> behavior
+[fs.def.osdep]</h3>
+Behavior that is dependent upon the behavior
+and characteristics of an operating system. See [fs.conform.os].
+<h3><a name="file">file</a> [fs.def.file]</h3>
+An object that can be written to, or read from, or both. A file
has certain attributes, including type. File types include regular files
and directories. Other types of files, such as symbolic links, may be supported by the
implementation.
-<a name="File-system">File system</a>: A collection of files and certain of their attributes.
-<a name="Filename">Filename</a>: The name of a file. Slash and
-0x00
-characters are not permitted. Implementations may define additional
-characters or specific names that are not permitted. Filenames <code>.</code> 
-and <code>..</code>  have special meaning. Implementations may define
-additional filenames that have special meaning.
-<blockquote>
- [Note: Many operating systems prohibit the ASCII control characters
- (0x00-0x1F) in filenames.
- One widely used operating system prohibits the characters 0x00-0x1F, <code>"</code>,<code>
- *</code>,<code> :</code>,<code> <</code>,<code> ></code>,<code> ?</code>,<code>
- \</code>,<code> /</code>, and<code> |</code> --end note]
-</blockquote>
-<a name="Path">Path</a>: A sequence of elements that identify
+<h3><a name="file-system">file system</a> [fs.def.filesystem]</h3>
+A collection of files and certain of their attributes.
+<h3><a name="filename">filename</a> [fs.def.filename]</h3>
+ The name of a file. Filenames <code>
+ "."</code> 
+and <code>".."</code>  have special meaning. The follow characteristics of
+ filenames are operating system dependent:
+<ul>
+ <li>
+ The permitted characters. See [fs.os.examples].
+ </li>
+ <li>
+ Specific filenames that are not permitted.
+ </li>
+ <li>
+ Additional filenames that have special meaning.
+ </li>
+ <li>
+ Case awareness and sensitivity during path resolution.
+ </li>
+ <li>
+ Special rules that may apply to file types other than regular
+ files, such as directories.
+ </li>
+</ul>
+<h3><a name="path">path</a> [fs.def.path]</h3>
+A sequence of elements that identify
the location of a file within a filesystem. The elements are the root-nameopt, 
root-directoryopt, and an optional sequence of filenames. [Note:
A pathname is the concrete representation of a path. --end note]
-POSIX API systems: Operating systems that use the ISO/IEC 9945
-API as their native application program interface.
-Windows API systems: Operating systems that use the Windows API
-as their native application program interface.
-<a name="Absolute-path">Absolute path</a>: A path that
+
+<h3><a name="Absolute-path">absolute path</a> [fs.def.absolute-path]</h3>
+A path that
unambiguously
identifies the location of a file without reference to an additional starting
location. The elements of a path that determine if it is absolute are
-implementation defined.
-<blockquote>
- [Note: For POSIX API systems, paths that begin with one or
- more directory-specifier characters are absolute paths.
- For Windows API systems, paths that begin with a drive specifier (i.e. a
- single letter followed by a colon) followed by one or more directory-specifier
- characters, or begin with two directory-specifier characters, are absolute paths. --end
- note]
-</blockquote>
-<a name="Relative-path">Relative path</a>: A path that only
+operating system dependent.
+
+<h3><a name="Relative-path">relative path</a> [fs.def.relative-path]</h3>
+A path that
+is not absolute, and so only
unambiguously
identifies the location of a file when resolved relative to
-a starting location. The format is implementation defined. [Note:
-Paths "." and ".." are considered to be relative paths. --end note]
-<a name="Canonical-path">Canonical path</a>: An absolute path that has
-no elements which are symbolic links, and no dot or dot dot elements.
-<a name="Pathname">Pathname</a>: A character string that represents a
-path. Pathnames are formatted according to the generic pathname format or an implementation defined
+an implied starting location. The elements of a path that determine if it is
+relative are operating system dependent.  [Note:
+Paths <code>"."</code> and <code>".."</code> are relative paths. --end note]
+<h3><a name="canonical-path">canonical path</a> [fs.def.cannonical-path]</h3>
+An absolute path that has
+no elements that are symbolic links, and no <code>"."</code> or <code>".."</code> elements.
+<h3>pathname [fs.def.pathname]</h3>
+A character string that represents
+the name of a
+path. Pathnames are formatted according to the generic pathname grammar or an
+operating system dependent
native pathname format.
-<a name="generic-pathname-format">Generic pathname format:</a>
+
+<h3>native pathname format [fs.def.native]</h3>
+The operating system dependent pathname format accepted by the host operating system.
+<h3><a name="link">link</a> [fs.def.link]</h3>
+A directory entry object that associates a
+filename with a file. On some file systems, several directory entries can
+associate names with the same file.
+<h3><a name="hard-link">hard link</a> [fs.def.hardlink]</h3>
+A link to an existing file. Some
+file systems support multiple hard links to a file. If the last hard link to a
+file is removed, the file itself is removed.
<blockquote>
+[Note: A hard link can be thought of as a shared-ownership smart
+pointer to a file. -- end note] 
+</blockquote>
+<h3><a name="symbolic-link">symbolic link</a> [fs.def.symlink]</h3>
+A type of file with the
+property that when the file is encountered during pathname resolution, a string
+stored by the file is used to modify the pathname resolution.
+<blockquote>
+[Note: A symbolic link can be thought of as a raw pointer to a file.
+If the file pointed to does not exist, the symbolic link is said to be a
+"dangling" symbolic link. -- end note] 
+</blockquote>
+<h3><a name="file-system-race">file system race</a> [fs.def.race]</h3>
+The condition that occurs
+when multiple threads, processes, or computers interleave access and
+modification of
+the same object within a file system.
+<h2><a name="Generic-pathname-grammar">Generic pathname format</a> [path.generic]</h2>
pathname: 
            root-nameopt
root-directoryopt relative-pathopt
root-name: 
-           
-implementation-defined
+            An
+operating system dependent name that identifies the starting location for
+absolute paths. 
<blockquote>
 <blockquote>
[Note: Many operating systems define a name
beginning with two directory-separator characters as a root-name
-that identifies network locations. Some
-operating systems defines a single letter followed by a colon as a drive
-specifier; a root-name identifying a specific device such as a disc drive. --end note]
+that identifies network or other resource locations. Some operating systems define a single letter followed by a colon as a drive
+specifier - a root-name identifying a specific device such as a disc drive. --end note]
 </blockquote>
</blockquote>
root-directory: 
@@ -325,9 +458,9 @@
            <code>"."</code> 
            <code>
".."</code>
-preferred-separator:opt 
-           
-implementation-defined
+preferred-separator: 
+            An
+operating system dependent directory separator character. May be a synonym for <code>"/"</code>.
directory-separator: 
            <code>"/" 
      "/"</code> directory-separator 
@@ -342,50 +475,145 @@
filename <code>".."</code> is considered to be a reference to the
parent
directory. Specific filenames may have special meanings for a particular
-operating system. 
-</blockquote>
-<a name="native-pathname-format">Native pathname format:</a> 
-An implementation defined format. [Note: For ISO/IEC 9945 compliant operating
-systems, the native format is the same as the generic format. For one widely
-used non-ISO/IEC 9945 compliant operating system, the
-native format is similar to the generic format, but the directory-separator
-characters can be either slashes or backslashes. --end note]
-<a name="Link">Link</a>: A directory entry object that associates a
-filename with a file. On some file systems, several directory entries can
-associate names with the same file.
-<a name="Hard-link">Hard link</a>: A link to an existing file. Some
-file systems support multiple hard links to a file. If the last hard link to a
-file is removed, the file itself is removed.
-<blockquote>
-[Note: A hard link can be thought of as a shared-ownership smart
-pointer to a file. -- end note] 
-</blockquote>
-<a name="Symbolic-link">Symbolic link</a>: A type of file with the
-property that when the file is encountered during pathname resolution, a string
-stored by the file is used to modify the pathname resolution.
-<blockquote>
-[Note: A symbolic link can be thought of as a raw pointer to a file.
-If the file pointed to does not exist, the symbolic link is said to be a
-"dangling" symbolic link. -- end note] 
-</blockquote>
-<a name="Race-condition">File system race</a>: The condition that occurs
-when multiple threads, processes, or computers interleave access and
-modification of
-the same object within a file system.
-<a name="Dot">Dot</a>, Dot Dot: Synonyms for the filenames <code>"."</code>
-and <code>".."</code>, respectively. The dot filename names the current
-directory. The dot dot filename names the parent directory.
-<h2><a name="Header-filesystem-synopsis">Header <code><boost/filesystem.hpp></code> synopsis</a></h2>
+operating system.
+<h2><a name="Operating-system-examples">Operating system dependent examples</a> (Informative) [fs.os.examples]</h2>
+Certain features are specified in this reference documentation as being operating system dependent. The following table shows the application of those
+specifications for operating systems that use the ISO/IEC 9945 or Windows® application program interfaces
+(APIs).[footnote1]
+<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
+ <tr>
+ <td>Feature</td>
+ <td>Section</td>
+ <td>ISO/IEC 9945 API</td>
+ <td>Windows® API</td>
+ <td>Notes</td>
+ </tr>
+ <tr>
+ <td><code>path::value_type</code></td>
+ <td>[class.path]</td>
+ <td><code>char</code></td>
+ <td><code>wchar_t</code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code>path::preferred_separator</code></td>
+ <td>[class.path]</td>
+ <td><code>'/'</code></td>
+ <td><code>L'\\'</code> (single backslash)</td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code>path("/").is_absolute() 
+ path("c:/").is_absolute()</code></td>
+ <td>[path.query]</td>
+ <td><code>true 
+ false</code></td>
+ <td><code>false 
+ true</code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code>path</code> argument disambiguation between generic format and
+ native format</td>
+ <td>[path.arg.fmt.cvt]</td>
+ <td>Not required</td>
+ <td>Not required</td>
+ <td>There is no need to distinguish between the generic format and native
+ format for these operating systems.</td>
+ </tr>
+ <tr>
+ <td><code>path</code> argument format conversion</td>
+ <td>[path.arg.fmt.cvt]</td>
+ <td>No conversion performed</td>
+ <td>No conversion performed</td>
+ <td>The generic format is already acceptable to the native API of these operating systems.</td>
+ </tr>
+ <tr>
+ <td valign="top">
+ <code>path("/cats/jane").c_str() 
+ path("/cats/jane/").c_str()</code></td>
+ <td>[path.arg.fmt.cvt]</td>
+ <td valign="top"> <code>"/cats/jane" 
+ "/cats/jane/"</code></td>
+ <td valign="top">
+ <code>L"/cats/jane" 
+ L"/cats/jane/"</code></td>
+ <td>These operating systems accept the same native separator between
+ directory names and a final file name, so no format conversion is performed.
+ Other operating systems might require conversion.</td>
+ </tr>
+ <tr>
+ <td>Format conversion by <code>path</code> native format observers</td>
+ <td>[path.native.obs]</td>
+ <td>No conversion performed</td>
+ <td>No conversion performed</td>
+ <td>For efficiency, <code>path</code> objects are required to store pathnames in the native
+ format regardless of operating system.</td>
+ </tr>
+ <tr>
+ <td>
+ Format conversion by <code>path</code> generic format observers</td>
+ <td>[path.generic.obs]</td>
+ <td>No conversion performed</td>
+ <td>Backslashes converted to slashes</td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code>p.make_preferred()</code></td>
+ <td>[fs.path.modifiers]</td>
+ <td>No change</td>
+ <td>Slashes converted to backslashes</td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td>Characters prohibited in filenames</td>
+ <td>[fs.def.filename]</td>
+ <td>0x00, <code>'/'</code></td>
+ <td>0x00-0x1F, <code>'"'</code>, <code>'*'</code>,<code> '*'</code>,
+ <code>'<'</code>,
+ <code>'>'</code>, <code>'?'</code>, <code>'\\'</code> (single backslash),
+ <code>'/'</code>, <code>'|'</code></td>
+ <td>Many operating systems prohibit the ASCII control characters (0x00-0x1F)
+ in filenames.</td>
+ </tr>
+ <tr>
+ <td>Initial imbued <code>path</code> locale</td>
+ <td>[path.imbued.locale]</td>
+ <td> <code>std::locale("") 
+ </code>[footnote 2]</td>
+ <td>Implementation supplied locale using <code>MultiByteToWideChar</code>
+ and <code>WideCharToMultiByte</code> with a codepage of <code>CP_ACP</code>
+ if <code>AreFileApisANSI()</code>is true, otherwise codepage <code>CP_OEMCP</code>.[footnote
+ 3]</td>
+ <td>Apple OS X®:  Implementation supplied locale providing UTF-8 <code>codecvt</code>
+ facet.[footnote 4]</td>
+ </tr>
+</table>
+[footnote1] OS X® and Windows® are examples of commercially
+available operating systems. This information is given for the convenience of
+users of this document and does not constitute an endorsement by ISO or IEC of
+these products.
+[footnote 2] Rationale: ISO C specifies <code>std::locale("")</code> as "the locale-specific native
+environment", while ISO/IEC 9945 says it "Specifies an implementation-defined native
+environment."
+[footnote 3] Rationale: This is the current behavior of C and C++
+standard library functions that perform file operations using narrow character
+strings to identify paths. Changing this behavior would be surprising and at
+variance with existing code, particularly where user input is involved.
+[footnote 4] Rationale: Vendor's documentation states "All BSD
+system functions expect their string parameters to be in UTF-8 encoding and
+nothing else."
+<h2><a name="Header-filesystem-synopsis">Header <code><boost/filesystem.hpp></code> synopsis</a>
+[filesystem.synopsis]</h2>
<pre>namespace boost
{
 namespace filesystem
 {
- class path;
-
+ class path;
+
 bool lexicographical_compare(path::iterator first1, path::iterator last1,
 path::iterator first2, path::iterator last2);
-
-void swap(path& lhs, path& rhs);
+ void swap(path& lhs, path& rhs);
 std::size_t hash_value(const path& p);

 bool operator==(const path& lhs, const path& rhs);
@@ -411,23 +639,25 @@
 const directory_iterator& begin(const directory_iterator& iter);
 directory_iterator end(const directory_iterator&);

+
 // enable BOOST_FOREACH
 directory_iterator& range_begin(directory_iterator& iter);
 directory_iterator range_begin(const directory_iterator& iter);
 directory_iterator range_end(const directory_iterator&);

- class recursive_directory_iterator;
+class recursive_directory_iterator;

 // enable c++11 range-based for statements
 const recursive_directory_iterator& begin(const recursive_directory_iterator& iter);
 recursive_directory_iterator end(const recursive_directory_iterator&);

-    // enable BOOST_FOREACH
-    recursive_directory_iterator& range_begin(recursive_directory_iterator& iter);
-    recursive_directory_iterator range_begin(const recursive_directory_iterator& iter);
-    recursive_directory_iterator range_end(const recursive_directory_iterator&);
- 
- enum <a name="file_type" href="#Enum-file_type">file_type</a>
+
+ // enable BOOST_FOREACH
+ recursive_directory_iterator& range_begin(recursive_directory_iterator& iter);
+ recursive_directory_iterator range_begin(const recursive_directory_iterator& iter);
+ recursive_directory_iterator range_end(const recursive_directory_iterator&);
+
+enum <a name="file_type" href="#Enum-file_type">file_type</a>
 {
 status_error, file_not_found, regular_file, directory_file,
 symlink_file, block_file, character_file, fifo_file, socket_file,
@@ -489,7 +719,8 @@
 system::error_code& ec);

 void copy_symlink(const path& existing_symlink, const path& new_symlink);
- void copy_symlink(const path& existing_symlink, const path& new_symlink, system::error_code& ec);
+ void copy_symlink(const path& existing_symlink, const path& new_symlink,
+ system::error_code& ec);

 bool create_directories(const path& p);
 bool create_directories(const path& p, system::error_code& ec);
@@ -498,13 +729,16 @@
 bool create_directory(const path& p, system::error_code& ec);

 void create_directory_symlink(const path& to, const path& new_symlink);
- void create_directory_symlink(const path& to, const path& new_symlink, system::error_code& ec);
+ void create_directory_symlink(const path& to, const path& new_symlink,
+ system::error_code& ec);

 void create_hard_link(const path& to, const path& new_hard_link);
- void create_hard_link(const path& to, const path& new_hard_link, system::error_code& ec);
+ void create_hard_link(const path& to, const path& new_hard_link,
+ system::error_code& ec);

 void create_symlink(const path& to, const path& new_symlink);
- void create_symlink(const path& to, const path& new_symlink, system::error_code& ec);
+ void create_symlink(const path& to, const path& new_symlink,
+ system::error_code& ec);

 path current_path();
 path current_path(system::error_code& ec);
@@ -549,7 +783,8 @@
 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);
+ void last_write_time(const path& p, const std::time_t new_time,
+ system::error_code& ec);

 path read_symlink(const path& p);
 path read_symlink(const path& p, system::error_code& ec);
@@ -588,7 +823,7 @@

 } // namespace filesystem
} // namespace boost</pre>
-<h2><a name="Error-reporting">Error reporting</a></h2>
+<h2><a name="Error-reporting">Error reporting</a> [fs.err.report]</h2>
Filesystem library functions often provide two overloads, one that
throws an exception to report file system errors, and another that sets an <code>error_code</code>.
<blockquote>
@@ -633,7 +868,7 @@
 throwing an exception as described in the C++ standard,
 17.6.4.10 [res.on.exception.handling].</li>
</ul>
-<h2><a name="class-path">Class <code>path</code></a></h2>
+<h2><a name="class-path">Class <code>path</code> [class.path]</a></h2>
An object of class <code>path</code> represents a path,
and contains a pathname Such an object is concerned only with the lexical and syntactic aspects
of a path. The path does not necessarily exist in external storage, and the
@@ -646,7 +881,7 @@
 class path
 {
 public:
- typedef see below value_type; // char for ISO/IEC 9945, wchar_t for Windows
+ typedef see below value_type;
 typedef std::basic_string<value_type> string_type;
 typedef std::codecvt<wchar_t, char, std::mbstate_t> codecvt_type;
 constexpr value_type preferred_separator;
@@ -707,7 +942,7 @@

 // modifiers
 void clear();
- path& make_preferred(); // ISO/IEC 9945: no effect. Windows: convert slashes to backslashes
+ path& make_preferred();
 path& remove_filename();
 path& replace_extension(const path& new_extension = path());
 void swap(path& rhs);
@@ -717,21 +952,21 @@
 const value_type* c_str() const noexcept; // native().c_str()

 template <class String>
- String string(const codecvt_type& cvt=codecvt()) const; // native format
+ String string(const codecvt_type& cvt=codecvt()) const; // native format

- const string string(const codecvt_type& cvt=codecvt()) const; // native format
- const wstring wstring(const codecvt_type& cvt=codecvt()) const; // ditto
- const u16string u16string() const; // ditto
- const u32string u32string() const; // ditto
+ string string(const codecvt_type& cvt=codecvt()) const; // native format
+ wstring wstring(const codecvt_type& cvt=codecvt()) const; // native format
+ u16string u16string() const; // native format
+ u32string u32string() const; // native format

 // generic format observers
 template <class String>
- String generic_string() const;
+ String generic_string() const;

- const string generic_string(const codecvt_type& cvt=codecvt()) const; // generic format
- const wstring generic_wstring(const codecvt_type& cvt=codecvt()) const; // ditto
- const u16string generic_u16string() const; // ditto
- const u32string generic_u32string() const; // ditto
+ string generic_string(const codecvt_type& cvt=codecvt()) const; // generic format
+ wstring generic_wstring(const codecvt_type& cvt=codecvt()) const; // generic format
+ u16string generic_u16string() const; // generic format
+ u32string generic_u32string() const; // generic format

 // compare
 int compare(const path& p) const noexcept;
@@ -768,8 +1003,8 @@
 iterator begin() const;
 iterator end() const;

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

 private:
@@ -778,111 +1013,95 @@

 } // namespace filesystem
} // namespace boost</pre>
-<code><a name="value_type">value_type</a></code> is an implementation-defined <code>typedef</code> for the
+<code><a name="value_type">value_type</a></code> is a <code>typedef</code> for the
character type used by the operating system to represent pathnames.
-Member functions described as returning <code>const string</code>, <code>const wstring</code>, <code>const u16string</code>, or <code>const u32string</code> are permitted to return <code>const string&</code>, <code>const
-wstring&</code>, <code>const u16string&</code>, or <code>const u32string&</code>,
-respectively.
-<blockquote>
-[Note: This allows implementations to avoid unnecessary copies when no
-conversion is required.
-Return-by-value is specified as <code>const</code> to ensure programs won't break if moved to a return-by-reference
-implementation. --
-end note]
-</blockquote>
-<h3><a name="path-Conversions"><code>path</code> Conversions</a></h3>
-<h4><a name="path-Conversions-to-native-format"><code>path</code> Conversions to
-native format</a></h4>
-Member function arguments that take character sequences representing paths
-may use the generic pathname format or
-the native pathname format. If such an
-argument uses the generic format, an implementation defined conversion to native format is performed
-during the processing of the argument. 
-<blockquote>
-[Note: No conversion occurs on ISO/IEC 9945 and Windows since they have
-native formats that conform to the generic format. --end note]
-[Rationale: There is no unambiguous way for an implementation to
-always be able distinguish between native format and generic format arguments.
-This is by design as it simplifies use. Should an implementation encounter an
-operating system where disambiguation is required, an implementation defined
-native format prefix can be introduced to identify the native format. -- end
-rationale]
-</blockquote>

-<div align="center">
- <center>

-<table border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#E0E0E0" width="90%">
- <tr>
- <td>
- Class <code>path</code> does not currently map invalid characters in
- filenames to valid characters. In the future we might add something like
- this:<blockquote>
-When converting filenames to the native operating system format,
-implementations are encouraged, but not required, to convert otherwise invalid
-characters or character sequences to valid characters or character sequences.
-Such conversions are implementation-defined.
-<blockquote>
-[Note: Filename conversion allows much wider portability of both
-programs and filenames that would otherwise be possible.
-Implementations are encouraged to base conversion on existing standards or
-practice. Examples include the Uniform Resource Locator escape syntax of a percent sign (<code>'%'</code>)
-followed by two hex digits representing the character value. On OpenVMS, which does not allow percent signs in filenames, a dollar sign (<code>'$'</code>)
-followed by two hex digits is the existing practice, as is converting lowercase
-letters to uppercase. -- end note.]
-</blockquote>
- </blockquote>
- </td>
- </tr>
-</table>
+<h3><a name="path-Usage"><code>path</code> Usage concerns</a> [path.usage]</h3>

- </center>
-</div>
+<h4>Multithreading concerns</h4>
+
+Filesystem library functions are not protected against data races. [Modifying
+an object of a Filesystem library type that is shared between threads risks
+undefined behavior unless objects of that type are explicitly specified as being
+sharable without data races or the user supplies a locking mechanism. —end
+note] [Note: Thus the Filesystem library behaves as if it were part
+of the standard library, and C++ standard 17.6.4.10 Shared objects and the
+library [res.on.objects] would thus apply.  —end note]
+
+<h4>Windows concerns</h4>
+
+Visual C++ at least through version 2012 does not employ C++11-style static
+initialization locks, so the initialization of <code>path::codecvt()</code> can
+race, either with itself or <code>path::imbue::()</code> if they are called from
+a different thread. A workaround is to call:
+
+<blockquote>
+<code>path::codecvt();  // ensure VC++ does not race during
+initialization.</code>
+
+</blockquote>
+in the main thread before launching any additional threads. [Note: The
+obvious fix of the Filesystem implementation doing the locking doesn't work
+because of unrelated problems with the Microsoft compiler; for static linking
+the runtime tries to do the initialization before main() starts, but doesn't
+permit operating system lock calls at that time.  —end note]
+
+<h4 dir="ltr">POSIX concerns</h4>
+
+Filesystem library initialization may throw an exception on POSIX
+systems (e.g. Linux, but not Mac OS X) that use environmental variables to
+determine the encoding of paths. This happens when <code>std::locale("")</code>
+throws because an environmental variable such as LANG is set to an invalid
+value, so it can affect any use of  <code>std::locale("")</code>, not just
+the Filesystem library. Filesystem uses lazy initialization so the exception is
+only thrown if a valid <code>std::locale("")</code> is actually needed, and also
+so that the exception is thrown after <code>main()</code> starts.
+
+Rather than waiting until a call to some Filesystem library function
+unexpectedly triggers the exception when it calls <code>path::codecvt()</code>,
+a program that needs be highly robust against environmental variable problems
+may want to preemptively call <code>std::locale("")</code> within a try block,
+catch the exception, and diagnose or repair the invalid environmental variable.
+
+<h3><a name="path-Conversions"><code>path</code> Conversions</a> [path.cvt]</h3>
+<h4><code>path</code> argument conversions [<a name="path.arg.convert">path.arg.cvt</a>]</h4>
+<h5><a name="path-Conversions-to-native-format"><code>path</code> argument
+format conversions</a> [path.arg.fmt.cvt]</h5>
+Member function arguments that take character sequences representing paths
+may use the generic pathname format or
+the native pathname format. Iff such arguments
+are in the generic format and the generic format is not acceptable to the
+operating system as a native path, conversion to native format shall be performed
+during the processing of the argument. See [fs.os.examples].
+<blockquote>
+[Note: Depending on the operating system, there may be no unambiguous way for an implementation to
+always be able to distinguish between native format and generic format arguments.
+This is by design as it simplifies use for operating systems that do not require
+disambiguation. Should an implementation encounter an
+operating system where disambiguation is required, an implementation can defined
+an extension to distinguish between the formats. 
+-- end note]
+</blockquote>

If the native format requires
paths for regular files to be formatted differently from paths for directories, the
path shall be treated as a directory path if last element is a separator,
otherwise it shall be treated as a regular file path.

-<blockquote>
-
-[Note: The above paragraph does not apply to ISO/IEC 9945 and Windows since
-they use the same format
-for both regular file and directory pathnames. --end note]
-
-[Example: On OpenVMS, a path
-constructed from <code>"/cats/jane"</code> would considered a regular file
-path, and have a native format of <code>"[CATS]JANE"</code>, while a
-path constructed from <code>"/cats/jane/"</code> would be considered a
-directory path, and have a native format of <code>"[CATS.JANE]"</code>. --end example]
-
-</blockquote>
+<h5><a name="path-Encoding-conversions"><code>
+path</code> argument encoding conversions</a>
+[path.arg.encoding.cvt]</h5>
+For member function arguments that take character sequences representing
+paths, if the value type of the argument is not <code>value_type and </code>one
+of the value types is <code>char</code> and the other is <code>wchar_t</code>, conversion to <code>value_type</code>
+shall be performed by the <code>path::codecvt()</code> facet. ([path.imbued.locale]).
<h4><a name="path-Conversions-to-generic-format"><code>path</code> Conversions
-to generic format</a></h4>
-Generic format observer functions return strings formatted according to the generic pathname format. The conversion
-from generic to native formats is implementation defined.
-<blockquote>
-[Note: For ISO/IEC 9945, no conversion is performed. For Windows, backslashes are converted to
-forward slashes. -- end note]
-</blockquote>
-<h4><a name="path-Encoding-conversions"><code>path</code> Encoding conversions</a></h4>
-If the value type of member function arguments that are character sequences
-representing paths is not <code>value_type</code>,
-and no <code>cvt</code> argument is supplied, conversion to <code>value_type</code> occurs using an imbued locale. This imbued locale is initialized with a <code>codecvt</code> facet appropriate for the operating system.
-<blockquote>
-For Apple OS X implementations, <code>path::value_type</code> is <code>char</code>. The default imbued locale provides a UTF-8 <code>codecvt</code> facet. [Rationale: "All BSD system functions expect their string
-parameters to be in UTF-8 encoding and nothing else." See Apple docs. -- end rationale]
-For Windows-like implementations, including MinGW, <code>path::value_type</code> is <code>wchar_t</code>. The default imbued locale provides a <code>codecvt</code> facet
-that invokes Windows <code>MultiByteToWideChar</code> or <code>WideCharToMultiByte</code> API with a codepage of <code>CP_THREAD_ACP</code> if Windows <code>AreFileApisANSI()</code>is true, otherwise codepage <code>CP_OEMCP</code>. [Rationale: this is the current behavior of C and C++
-programs that perform file operations using narrow character string to identify
-paths. Changing this in the Filesystem library would be too surprising,
-particularly where user input is involved. -- end rationale]
-For all other implementations, including Linux, <code>path::value_type</code> is <code>char</code>. The default imbued locale is <code>std::locale("")</code>.
-[Rationale: ISO C specifies this as "the locale-specific native
-environment", while ISO/IEC 9945 says it "Specifies an implementation-defined native
-environment." -- end rationale]
-</blockquote>
-<h3><a name="path-Requirements"><code>path</code> Requirements</a></h3>
+to generic format</a> [fs.cvt.to.generic]</h4>
+Generic format observer functions
+shall return strings formatted according to the generic pathname format
+using preferred-separator. See [fs.os.examples].
+<h3><a name="path-Requirements"><code>path</code> Requirements</a> [path.req]</h3>
Template parameters named <code><a name="InputIterator">InputIterator</a></code> are required meet the
requirements for a C++ standard library <code>RandomIterator</code> compliant iterator. The iterator's value type is required to be <code>char</code>, <code>wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.
Template parameters named <code><a name="Source">Source</a></code> are required to be one of:
@@ -898,107 +1117,78 @@
</ul>

<h3> <a name="path-constructors"> <code>
-path</code> constructors</a></h3>
-<pre>path();</pre>
-<blockquote>
- Postcondition: <code>empty()</code>.
- </blockquote>
+path</code> constructors</a> [path.construct]</h3>
<pre>template <class Source>
 path(Source const& source, const codecvt_type& cvt=codecvt());</pre>
<pre>template <class InputIterator>
 path(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());</pre>
<blockquote>
 Effects: Stores the contents [<code>begin</code>,<code>end</code>)
- or <code>source</code> in <code>pathname</code>. If the contents are in the
- generic format and the generic format is unacceptable to the operating
- system's API, they are converted to the native format. [Note: For
- ISO/IEC 9945 and Windows implementations, the generic format is already
- acceptable as a native format, so no generic to native conversion is
- performed. --end note]
- 
- Remarks: If the value type of  [<code>begin</code>,<code>end</code>)
- or <code>source</code> is not <code>value_type</code>, conversion is performed
- by <code>cvt</code>.
+ or <code>source</code> in <code>pathname</code>, converting format and
+ encoding if required ([path.arg.convert]).
</blockquote>
<h3> <a name="path-assignments"> <code>
-path</code> assignments</a></h3>
-<pre>template <class Source>
- path& operator=(Source const& source);</pre>
+path</code> assignments</a> [path.assign]</h3>
<pre>template <class Source>
- path& assign(Source const& source, const codecvt_type& cvt);</pre>
-<pre>template <class InputIterator>
+ path& operator=(Source const& source);
+ template <class Source>
+ path& assign(Source const& source, const codecvt_type& cvt);
+ template <class InputIterator>
 path& assign(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());</pre>
<blockquote>
 Effects: Stores the contents [<code>begin</code>,<code>end</code>)
- or <code>source</code> in <code>pathname</code>. If the contents are in the
- generic format, they are converted to the native format. [Note: For
- ISO/IEC 9945 and Windows based implementations, the generic format is already
- acceptable as a native format, so no generic to native conversion is
- performed. --end note]
+ or <code>source</code> in <code>pathname</code>, converting format and
+ encoding if required ([path.arg.convert]). 
 
 Returns: <code>*this</code>
- 
- Remarks: If the value type of  [<code>begin</code>,<code>end</code>)
- or <code>source</code> is not <code>value_type</code>, conversion is performed
- by <code>cvt</code>.
- </blockquote>
-<h3><a name="path-appends"><code> path</code> appends</a></h3>
- The append operations use <code>operator/=</code> to denote their semantic
- effect of appending the platform's preferred directory separator when needed. The
- preferred
- directory separator is implementation-defined.
-<blockquote>
- [Note: For ISO/IEC 9945-like implementations, including Unix variants, Linux, and Mac OS X, the preferred directory separator is a
- single forward slash.
- For Windows-like implementations, including Cygwin and MinGW, the preferred directory
- separator is a single backslash.--end note]
- </blockquote>
+ </blockquote>
+<h3><a name="path-appends"><code> path</code> appends</a>
+[path.append]</h3>
+ The append operations use <code>
+ operator/=</code> to denote their semantic effect of appending 
+ preferred-separator when needed. 
<pre>path& operator/=(const path& p);</pre>
<blockquote>
 Effects:
 <blockquote>
- Appends the preferred directory separator to the contained pathname, unless:<ul>
+ Appends <code>path::preferred_separator</code> to <code>pathname</code>,
+ converting format and encoding if required ([path.arg.convert]), unless:<ul>
 <li>an added separator
 would be redundant, or</li>
 <li>would change an relative path to an absolute path, or</li>
 <li><code>p.empty()</code>, or</li>
 <li><code>*p.native().cbegin()</code> is a directory separator.</li>
 </ul>
- Appends <code>p.native()</code> to <code>pathname</code>.
+ Then appends <code>p.native()</code> to <code>pathname</code>.
 </blockquote>
 Returns: <code>*this</code>
</blockquote>
<pre>template <class Source>
- path& operator/=(Source const & source);</pre>
-<pre>template <class Source>
- path& append(Source const & source, const codecvt_type& cvt);</pre>
-<pre>template <class InputIterator>
+ path& operator/=(Source const & source);
+ template <class Source>
+ path& append(Source const & source, const codecvt_type& cvt);
+ template <class InputIterator>
 path& append(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());</pre>
<blockquote>
 Effects:
 <blockquote>
- Appends a native directory separator to the contained pathname, unless:
+ Appends <code>path::preferred_separator</code> to <code>pathname</code>, converting
+ format and encoding if required ([path.arg.convert]), unless:
 <ul>
 <li>an added separator
 would be redundant, or</li>
- <li>would change an relative path to an absoute path, or</li>
+ <li>would change an relative path to an absolute path, or</li>
 <li><code>p.empty()</code>, or</li>
 <li><code>*p.native().cbegin()</code> is a separator.</li>
 </ul>
 Appends the contents [<code>begin</code>,<code>end</code>)
- or <code>source</code> to <code>pathname</code>. If the contents are in the
- generic format, they are converted to the native format. [Note: For
- ISO/IEC 9945 and Windows based implementations, the generic format is already
- acceptable as a native format, so no generic to native conversion is
- performed. --end note]
- </blockquote>
- Remarks: If the value type of  [<code>begin</code>,<code>end</code>)
- or <code>source</code> is not <code>value_type</code>, conversion is performed
- by <code>cvt</code>.
+ or <code>source</code> to <code>pathname</code>, converting format and
+ encoding if required ([path.arg.convert]).
+ </blockquote>
 Returns: <code>*this</code>
 </blockquote>

-<h3><a name="path-concatenation"><code>path</code> concatenation</a></h3>
+<h3><a name="path-concatenation"><code>path</code> concatenation</a> [path.concat]</h3>
<pre>path& operator+=(const path& x);
path& operator+=(const string_type& x);
path& operator+=(const value_type* x);
@@ -1007,8 +1197,6 @@
 path& operator+=(Source const& x);
template <class CharT>
 path& operator+=(CharT x);
-template <class Source>
- path& concat(Source const& x, const codecvt_type& cvt);
template <class InputIterator>
 path& concat(InputIterator begin, InputIterator end);
template <class InputIterator>
@@ -1025,15 +1213,14 @@
 Returns: <code>*this</code>
 </blockquote>
<h3><a name="path-modifiers"> <code>
-path</code> modifiers</a></h3><pre>void <a name="path-clear">clear</a>();</pre>
+path</code> modifiers</a> [path.modifiers]</h3><pre>void <a name="path-clear">clear</a>();</pre>
<blockquote>
Postcondition: <code>this->empty()</code> is true.
</blockquote>
<pre>path& <a name="path-make_preferred">make_preferred</a>();</pre>
<blockquote>
- Effects: The contained pathname is converted to the preferred native
- format. [Note: On Windows, the effect is to replace slashes with
- backslashes. On ISO/IEC 9945, there is no effect. -- end note]
+ Effects: directory-separators are converted to prefered-separators.
+ See [fs.os.examples].
 Returns: <code>*this</code>
</blockquote>

@@ -1064,7 +1251,8 @@
 Complexity: constant time.
</blockquote>

-<h3> <a name="path-native-format-observers"><code>path</code> native format observers</a></h3>
+<h3> <a name="path-native-format-observers"><code>path</code> native format observers</a>
+[path.native.obs]</h3>
The string returned by all native format observers is in the native pathname format.
<pre>const string_type& <a name="native">native</a>() const noexcept;</pre>
<blockquote>
@@ -1080,45 +1268,36 @@
 Returns: <code>pathname</code>.
Remarks: If <code>string_type</code> is a different type than <code>String</code>, conversion is performed by <code>cvt</code>.
</blockquote>
-<pre>const string <a name="string">string</a>(const codecvt_type& cvt=codecvt()) const;
-const wstring <a name="wstring">wstring</a>(const codecvt_type& cvt=codecvt()) const;
-const u16string <a name="u16string">u16string</a>() const;
-const u32wstring <a name="u32wstring">u32wstring</a>() const; </pre>
+<pre>string <a name="string">string</a>(const codecvt_type& cvt=codecvt()) const;
+wstring <a name="wstring">wstring</a>(const codecvt_type& cvt=codecvt()) const;
+u16string <a name="u16string">u16string</a>() const;
+u32wstring <a name="u32wstring">u32wstring</a>() const; </pre>
<blockquote>
Returns: <code>pathname</code>.
Remarks: If <code>string_type</code> is a different type than
function's return type, conversion is performed by <code>cvt</code>.
-If <code>string_type</code> is the same type as the
-function's return type, the function is permitted to return by <code>const&</code> rather than <code>const</code> value. [Note: For
-ISO/IEC 9945, this occurs for <code>string()</code>, for Windows, <code>wstring()</code>. --end note]
</blockquote>

-<h3> <a name="path-generic-format-observers"><code>path</code> generic format observers</a></h3>
+<h3> <a name="path-generic-format-observers"><code>path</code> generic format observers</a>
+[path.generic.obs]</h3>
The string returned by all generic format observers is in the generic pathname format.
-[Note: For ISO/IEC 9945, no conversion occurs, since the native format and
-generic format are the same. For Windows, backslashes are converted to slashes --end note]
<pre>template <class String>
String <a name="generic_string-template">generic_string</a>(const codecvt_type& cvt=codecvt()) const;</pre>
<blockquote>
 Returns: <code>pathname</code>.
Remarks: If <code>string_type</code> is a different type than <code>String</code>, conversion is performed by <code>cvt</code>.
</blockquote>
-<pre>const string <a name="generic_string">generic_string</a>(const codecvt_type& cvt=codecvt()) const;
-const wstring <a name="generic_wstring">generic_wstring</a>(const codecvt_type& cvt=codecvt()) const;
-const u16string <a name="generic_u16string">generic_u16string</a>() const;
-const u32wstring <a name="generic_u32wstring">generic_u32wstring</a>() const; </pre>
+<pre>string <a name="generic_string">generic_string</a>(const codecvt_type& cvt=codecvt()) const;
+wstring <a name="generic_wstring">generic_wstring</a>(const codecvt_type& cvt=codecvt()) const;
+u16string <a name="generic_u16string">generic_u16string</a>() const;
+u32wstring <a name="generic_u32wstring">generic_u32wstring</a>() const; </pre>
<blockquote>
Returns: <code>pathname</code>.
Remarks:  If <code>string_type</code> is a different type than
function's return type, conversion is performed by <code>cvt</code>.
-If <code>string_type</code> is of the same type as the
-function's return type, and the generic format is the same as the native format,
-the function is permitted to return by <code>const&</code> rather than <code>const</code> value. [Note: For
-ISO/IEC 9945, this occurs for <code>string()</code>.
-It never occurs for Windows, because backslashes must be converted to slashes. --end note]
</blockquote>

-<h3> <a name="path-compare"><code>path</code> compare</a></h3>
+<h3> <a name="path-compare"><code>path</code> compare</a> [path.compare]</h3>
<pre>int compare(const path& p) const noexcept;</pre>
<blockquote>
 Returns: A value less than 0 if the elements of <code>*this</code> are lexicographically less than the elements of <code>p</code>, otherwise a
@@ -1135,7 +1314,8 @@
<blockquote>
 Returns: <code>compare(path(s))</code>.
</blockquote>
-<h3> <a name="path-decomposition"> <code>path</code> decomposition</a></h3>
+<h3> <a name="path-decomposition"> <code>path</code> decomposition</a>
+[path.decompose]</h3>
See the Path decomposition table for examples
for values returned by decomposition functions. The Tutorial may also be
helpful.
@@ -1174,7 +1354,7 @@
</blockquote>
<pre>path <a name="path-stem">stem</a>(const path& p) const;</pre>
<blockquote>
- Returns: if <code>p.filename()</code>contains a dot but does not
+ Returns: if <code>p.filename()</code> contains a dot but does not
 consist solely of one or to two dots, returns
 the substring of <code>p.filename()</code> starting at its beginning and
 ending at the last dot (the dot is not included). Otherwise,
@@ -1205,11 +1385,14 @@
 <pre><code>std::cout << path("/foo/bar.txt").extension(); //</code> outputs "<code>.txt</code>"</pre>
 </blockquote>
 --end example]
- [Note: The dot is included in the return value so that
- it is possible to distinguish between no extension and an empty extension. See http://permalink.gmane.org/gmane.comp.lib.boost.devel/199744 for more
- extensive rationale.  -- end note]
+ [Note: The dot is included in the return value so that it is
+ possible to distinguish between no extension and an empty extension. 
+ See
+ <a href="http://permalink.gmane.org/gmane.comp.lib.boost.devel/199744">
+ http://permalink.gmane.org/gmane.comp.lib.boost.devel/199744></a> for more
+ extensive rationale.  -- end note]
</blockquote>
-<h3> <a name="path-query"> <code>path</code> query</a></h3>
+<h3> <a name="path-query"> <code>path</code> query</a> [path.query]</h3>
<pre>bool <a name="path-empty">empty</a>() const;</pre>
<blockquote>
 Returns: <code>m_pathname.empty()</code>.
@@ -1249,14 +1432,13 @@
<pre>bool <a name="path-is_absolute">is_absolute</a>() const;</pre>
<blockquote>
 Returns: <code>true</code> if the elements of <code>root_path()</code> uniquely identify a directory, else <code>false</code>.
- [Note: On ISO/IEC 9945,<code> path("/foo").is_absolute()</code> returns <code>true</code>. On Windows, <code>path("/foo").is_absolute()</code> returns <code>false</code>. --end note]
</blockquote>
<pre>bool <a name="path-is_relative">is_relative</a>() const;</pre>
<blockquote>
 Returns: <code>!is_absolute()</code>.
</blockquote>
<h3> <a name="path-iterators"> <code>
-path</code> iterators</a></h3>
+path</code> iterators</a> [path.itr]</h3>
 Path iterators iterate over the elements of the stored pathname.
 A <code>path::iterator</code> is a constant iterator satisfying all
the requirements of a bidirectional iterator (C++ Std, 24.1.4 Bidirectional
@@ -1283,17 +1465,30 @@
<blockquote>
 Returns: The end iterator.
</blockquote>
- <h3><a name="path_encoding"><code> path</code> encoding</a> conversion</h3>
+ <h3><a name="path-imbued-locale"><code> path</code>
+ imbued locale</a> [path.imbued.locale]</h3>
+ <code>path</code> operations sometimes require encoding conversions between
+ <code>pathname</code> and some other string object where one of the value types
+ is <code>char</code> and the other is <code>wchar_t</code>. Such conversions
+ shall be performed by the <code>path::codecvt()</code> facet.
+ <blockquote>
+ [Example:
+ ... --end example]
+ </blockquote>
 <pre>static std::locale <a name="path-imbue">imbue</a>(const std::locale& loc);</pre>
<blockquote>
- Effects: Stores <code>loc</code> as the default locale for all
- objects of type <code>path</code>.
- Returns: The previous default locale for all objects of type <code>path</code>.
+ Effects: Stores a copy of <code>loc</code> as the imbued <code>path</code>
+ locale.
+ Returns: The previous imbued <code>path</code> locale.
+ Remarks: The initial value of the imbued <code>path</code> locale is
+ operating system dependent. It shall be a locale with a <code>codecvt</code>
+ facet for a <code>char</code> string encoding appropriate for the operating
+ system. See ([fs.os.examples]).  
</blockquote>
<pre>static const codecvt_type& <a name="path-codecvt">codecvt</a>();</pre>
<blockquote>
- Returns: The <code>codecvt</code> facet for the default locale for
- all objects of type <code>path</code>.
+ Returns: The <code>codecvt</code> facet for the imbued<code> path</code>
+ locale .
</blockquote>

@@ -1318,7 +1513,8 @@
const string_type external_directory_string() const { return native(); }</pre>
</blockquote>

-<h3> <a name="path-non-member-functions"> <code>path</code> non-member functions</a></h3>
+<h3> <a name="path-non-member-functions"> <code>path</code> non-member functions</a>
+[path.non-member]</h3>

 <pre>bool lexicographical_compare(path::iterator first1, path::iterator last1,
 path::iterator first2, path::iterator last2);</pre>
@@ -1383,16 +1579,30 @@
 Returns: <code>path(lhs) /= rhs</code>.
</blockquote>
<h3> <a name="path-non-member-operators"><code>path</code></a><a name="path-inserter-extractor"> inserter
- and extractor</a></h3>
+ and extractor</a> [path.io]</h3>
 The inserter and extractor delimit the string with double-quotes (<code>"</code>)
-to ensure that paths with embedded spaces will round trip correctly. Ampersand (<code>&</code>)
-is used as an escape character, so the path can itself contain double quotes.
+so that paths with embedded spaces will round trip correctly. Ampersand (<code>&</code>)
+is as an escape character, so the path can itself contain double quotes.
<pre>template <class Char, class Traits>
std::basic_ostream<Char, Traits>& operator<<(std::basic_ostream<Char, Traits>& os,
 const path& p)
</pre>
<blockquote>
- Effects:  <code>os << boost::io::quoted(p.string<std::basic_string<Char>>(), static_cast<Char>('&'));</code>
+ Effects: Insert characters into <code>os</code>:
+ <ul>
+ <li>
+ A double-quote.
+ </li>
+ <li>
+ Each character in <code>p.string<std::basic_string<Char>>()</code>.
+ If the character to be inserted is equal to the escape character or a
+ double-quote, as determined by <code>operator==</code>, first insert the
+ escape character.
+ </li>
+ <li>
+ A double-quote.
+ </li>
+ </ul>
 Returns: <code>os</code>
</blockquote>
<pre>template <class Char, class Traits>
@@ -1403,9 +1613,27 @@
 Effects:  <code> std::basic_string<Char> str; 
        is >> boost::io::quoted(str, static_cast<Char>('&')); 
        p = str;</code>
+ Effects:  Extract characters from os:
+ <ul>
+ <li>If the first character that would be extracted is equal to double-quote,
+ as determined by <code>operator==</code>, then:<ul>
+ <li>Discard the initial double-quote.</li>
+ <li>Save the value and then turn off the <code>skipws</code> flag.</li>
+ <li><code>p.clear()</code></li>
+ <li>Until an unescaped double-quote character is reached or <code>
+ is.not_good()</code>, extract characters from <code>os</code> and append
+ them to <code>p</code>, except that if an escape character is reached,
+ ignore it and append the next character to <code>p</code>.</li>
+ <li>Discard the final double-quote character.</li>
+ <li>Restore the <code>skipws</code> flag to its original value.</li>
+ </ul>
+ </li>
+ <li>Otherwise, <code>os >> p</code>.</li>
+ </ul>
 Returns: <code>is</code>
 </blockquote>
-<h3><a name="Class-filesystem_error">Class <code>filesystem_error</code></a></h3>
+<h2><a name="Class-filesystem_error">Class <code>filesystem_error</code>
+[class.filesystem_error]</a></h2>
<pre>namespace boost
{
 namespace filesystem
@@ -1437,7 +1665,8 @@
The class template <code>filesystem_error</code> defines the type of
objects thrown as exceptions to report file system errors from functions described in this
reference documentation.
-<h4> <a name="filesystem_error-members"> <code>filesystem_error</code> members</a></h4>
+<h3> <a name="filesystem_error-members"> <code>filesystem_error</code> members</a>
+[filesystem_error.members]</h3>
<pre><a name="filesystem_error-2-arg">filesystem_error</a>(const std::string& what_arg, error_code ec);</pre>
<blockquote>
 Postcondition:
@@ -1540,7 +1769,7 @@
 not empty, and <code>system_error::what()</code> strings in the returned
 string.
</blockquote>
-<h3><a name="Enum-file_type">Enum file_type</a></h3>
+<h2><a name="Enum-file_type">Enum file_type</a> [enum.file_type]</h2>
This enum specifies constants uses to identify file types.
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
 <tr>
@@ -1590,22 +1819,17 @@
 of the above cases.</td>
 </tr>
</table>
-<h3><a name="Enum-perms">Enum perms</a></h3>
-This enum specifies bitmask constants uses to identify file
-permissions. The ISO/IEC 9945 standard specifies actual values, and those values have
-been adopted here because they are very familiar and ingrained for many ISO/IEC
-9945
-users.
-<blockquote>
-Caution: Operating systems do not always support permissions as described in
-the table.
-There is much variation in the meaning of <code>sticky_bit</code>; do not use it unless you understand what it means for
-your operating system.
-There is much variation in how operating systems treat symlinks. See <code>symlink_perms</code>.
-Windows: All permissions except write are currently ignored. There is only a
+<h2><a name="Enum-perms">Enum perms</a> [enum.perms]</h2>
+This <code>enum</code> specifies bitmask constants uses to identify file
+permissions. ISO/IEC 9945
+(POSIX) specifies actual values, and those values have been adopted here because
+they are very familiar and ingrained for many POSIX
+users.
+<blockquote>
+Windows: All permissions except write are currently ignored. There is only a
single write permission; setting write permission for owner, group, or others
sets write permission for all, and removing write permission for owner, group,
-or others removes write permission for all. 
+or others removes write permission for all. 
</blockquote>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
 <tr>
@@ -1666,7 +1890,8 @@
 <td> Set-group-ID on execution</td>
</tr>
<tr><td><code><a name="sticky_bit">sticky_bit</a> </code></td><td><code>01000</code></td><td> <code>S_ISVTX</code></td>
- <td> Meaning varies; see http:en.wikipedia.org/wiki/Sticky_bit</td>
+ <td> Operating system dependent. Inherently non-portable, even between ISO/IEC 9945
+ operating systems.</td>
</tr>
<tr><td><code><a name="perms_mask">perms_mask</a></code></td><td><code>07777</code></td><td>  </td>
 <td><code>all_all | set_uid_on_exe | set_gid_on_exe | sticky_bit</code></td>
@@ -1685,13 +1910,17 @@
 file's current bits</td>
</tr>
<tr><td><code><a name="symlink_perms">symlink_perms</a></code></td><td><code>0x4000</code></td><td></td><td>
- On ISO/IEC 9945 <code>permissions()</code> resolves symlinks unless <code>symlink_perms</code> is specified.
- Meaningless on Windows as <code>permissions()</code> never resolves symlinks.
- Meaningless on Mac OS X and some other BSD systems as <code>permissions()</code> always resolves symlinks. Get over it.</td>
+ On ISO/IEC 9945
+ <code>permissions()</code> resolves symlinks unless
+ <code>symlink_perms</code> is specified.
+ Meaningless on Windows as <code>
+ permissions()</code> never resolves symlinks.
+ Meaningless on Mac OS X and some other BSD systems as <code>
+ permissions()</code> always resolves symlinks. Get over it.</td>
</tr>

</table>
-<h3><a name="file_status">Class file_status</a></h3>
+<h2><a name="file_status">Class file_status</a> [class.file_status]</h2>
<pre>namespace boost
{
 namespace filesystem
@@ -1721,7 +1950,8 @@
} // namespace boost</pre>
An object of type <code>file_status</code> stores information about the type
and permissions of a file.
-<h4><a name="file_status-constructors"><code>file_status</code> constructors</a></h4>
+<h3><a name="file_status-constructors"><code>file_status</code> constructors</a>
+[file_status.cons]</h3>
<pre>explicit file_status() noexcept;</pre>
<blockquote>
 Postconditions: <code>type() == status_error</code>, <code>permissions() == perms_not_known</code>.
@@ -1730,7 +1960,7 @@
<blockquote>
 Postconditions: <code>type() == ft</code>, <code>permissions() == prms</code>.
</blockquote>
- <h4><a name="file_status-observers"><code>file_status</code> observers</a></h4>
+ <h3><a name="file_status-observers"><code>file_status</code> observers</a> [file_status.obs]</h3>
<pre>file_type type() const noexcept;</pre>
<blockquote>
 Returns: The value of <code>type()</code> specified by the postconditions of the most recent call to a constructor, operator=, or <code>type(file_type)</code> function.
@@ -1739,7 +1969,7 @@
<blockquote>
 Returns: The value of <code>permissions()</code> specified by the postconditions of the most recent call to a constructor, operator=, or <code>permissions(perms)</code> function.
</blockquote>
-<h4><a name="file_status-modifiers"><code>file_status</code> modifiers</a></h4>
+<h3><a name="file_status-modifiers"><code>file_status</code> modifiers</a> [file_status.mods]</h3>
<pre>void type(file_type ft) noexcept;</pre>
<blockquote>
 Postconditions: <code>type() == ft</code>.
@@ -1748,7 +1978,7 @@
<blockquote>
 Postconditions: <code>permissions() == prms</code>.
</blockquote>
-<h3><a name="Class-directory_entry">Class <code>directory_entry</code></a></h3>
+<h2><a name="Class-directory_entry">Class <code>directory_entry</code></a> [class.directory_entry]</h2>
<div>
<pre>namespace boost
{
@@ -1798,7 +2028,7 @@
A <code>directory_entry</code> object stores a <code>path object</code>,
a <code>file_status</code> object for non-symbolic link status, and a <code>file_status</code> object for symbolic link status. The <code>file_status</code> objects act as value caches.
<blockquote>
-[Note: Because <code>status()</code>on a pathname may be a very expensive operation,
+[Note: Because <code>status()</code>on a pathname may be a relatively expensive operation,
some operating systems provide status information as a byproduct of directory
iteration. Caching such status information can result is significant time savings. Cached and
non-cached results may differ in the presence of file system races. -- end note]
@@ -1808,7 +2038,8 @@
a moderately fast hard-drive. Similar speedups are expected on Linux and BSD-derived
systems that provide status as a by-product of directory iteration.
</blockquote>
-<h4> <a name="directory_entry-constructors"> <code>directory_entry </code>constructors</a></h4>
+<h3> <a name="directory_entry-constructors"> <code>directory_entry </code>constructors</a>
+[directory_entry.cons]</h3>
<pre>directory_entry();</pre>
<blockquote>
 Postcondition:
@@ -1853,7 +2084,8 @@
 </tr>
 </table>
</blockquote>
-<h4> <a name="directory_entry-modifiers"> <code>directory_entry </code>modifiers</a></h4>
+<h3> <a name="directory_entry-modifiers"> <code>directory_entry </code>modifiers</a>
+[directory_entry.mods]</h3>
<pre>void assign(const path& p, file_status st=file_status(), file_status symlink_st=file_status());</pre>
<blockquote>
 Postcondition:
@@ -1898,7 +2130,8 @@
 </tr>
 </table>
</blockquote>
-<h4> <a name="directory_entry-observers"> <code>directory_entry</code> observers</a></h4>
+<h3> <a name="directory_entry-observers"> <code>directory_entry</code> observers</a>
+[directory_entry.obs]</h3>
<pre>const path& path() const;</pre>
<blockquote>
 Returns: <code>m_path</code>
@@ -1960,7 +2193,8 @@
<blockquote>
 Returns: <code>m_path >= rhs.m_path</code>.
</blockquote>
-<h3><a name="Class-directory_iterator">Class <code>directory_iterator</code></a></h3>
+<h2><a name="Class-directory_iterator">Class <code>directory_iterator</code>
+[class.directory_iterator]</a></h2>
Objects of type <code>directory_iterator</code> provide standard library
compliant iteration over the contents of a directory. Also see class <code>recursive_directory_iterator</code>.
<pre>namespace boost
@@ -1992,18 +2226,19 @@
 <code>directory_iterator</code> satisfies the requirements of an
input iterator (C++ Std, 24.2.1, Input iterators [input.iterators]).
A <code>directory_iterator</code> reads successive elements from the directory for
-which it was constructed, as if by calling ISO/IEC 9945 <code>readdir_r()</code>. After a <code>directory_iterator</code> is constructed, and every time <code>operator++</code> is called,
+which it was constructed, as if by calling ISO/IEC 9945 <code>readdir_r()</code>. After a <code>directory_iterator</code> is constructed, and every time <code>operator++</code> is called,
it reads a directory element and stores information about it in a object of type <code>directory_entry</code>. <code>operator++</code> is not equality preserving; that is, <code>i == j</code> does not imply that <code>++i == ++j</code>. 
<blockquote>
[Note: The practical consequence of not preserving equality is that directory iterators
can only be used for single-pass algorithms. --end note]
</blockquote>
-If the end of the directory elements is reached, the iterator becomes equal to
-the end iterator value. The constructor <code>directory_iterator()</code> with no arguments always constructs an end iterator object, which is the only
-legitimate iterator to be used for the end condition. The result of <code>operator*</code> on an end iterator is not defined. For any other iterator value
-a <code>const directory_entry&</code> is returned. The result of <code>operator-></code> on an end iterator is not defined. For any other iterator value a <code>const directory_entry*</code> is
+If the end of the directory elements is reached, the iterator shall become equal to
+the end iterator value. The constructor <code>directory_iterator()</code> with no arguments always constructs an end iterator object, which
+shall be the only valid iterator for the end condition. The result of <code>operator*</code> on an end iterator is not defined. For any other iterator value
+a <code>const directory_entry&</code> is returned. The result of <code>operator-></code> on an end iterator is
+undefined behavior. For any other iterator value a <code>const directory_entry*</code> is
returned. 
-Two end iterators are always equal. An end iterator is not equal to a non-end
+Two end iterators are always equal. An end iterator shall not be equal to a non-end
iterator.
<blockquote>
The above wording is based on the
@@ -2025,10 +2260,11 @@
If a file is removed from or added to a directory after the
construction of a <code>directory_iterator</code> for the directory, it is
unspecified whether or not subsequent incrementing of the iterator will ever
-result in an iterator whose value is the removed or added directory entry. See 
-ISO/IEC 9945 <code>readdir_r()</code>. --end note]
+result in an iterator whose value is the removed or added directory entry. See
+ISO/IEC 9945 <code>readdir_r()</code>. --end note]
</blockquote>
-<h4><a name="directory_iterator-members"><code>directory_iterator</code> members</a></h4>
+<h3><a name="directory_iterator-members"><code>directory_iterator</code> members</a>
+[directory_iterator.members]</h3>

<code><a name="directory_iterator-default-ctor">directory_iterator</a>()
noexcept;</code>
@@ -2070,7 +2306,8 @@
<blockquote>
 Returns: <code>directory_iterator()</code>.
</blockquote>
-<h3><a name="Class-recursive_directory_iterator">Class <code>recursive_directory_iterator</code></a></h3>
+<h2><a name="Class-recursive_directory_iterator">Class <code>recursive_directory_iterator</code>
+[class.rec.dir.itr]</a></h2>
Objects of type <code>recursive_directory_iterator</code> provide standard library
compliant iteration over the contents of a directory, including recursion into
its sub-directories.
@@ -2216,17 +2453,16 @@
<blockquote>
 Returns: <code>recursive_directory_iterator()</code>.
</blockquote>
-<h3><a name="Operational-functions">Operational functions</a></h3>
+<h2><a name="Operational-functions">Operational functions</a> [fs.op.funcs]</h2>
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
-path is resolved as if by the ISO/IEC 9945 Pathname Resolution mechanism.
+path is resolved as if by the ISO/IEC 9945 Pathname Resolution mechanism.
[Note: Because hardware failures, network failures, file system races, 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">Operational function specifications</a></h4>
<pre>path <a name="absolute">absolute</a>(const path& p, const path& base=current_path());</pre>
 <blockquote>
 Returns: A absolute path composed according to the
@@ -2325,6 +2561,7 @@
 Throws: As specified in Error reporting.

</blockquote>
+
<pre>void copy_file(const path& from, const path& to);
void copy_file(const path& from, const path& to, system::error_code& ec);</pre>
<blockquote>
@@ -2364,7 +2601,7 @@
bool <a name="create_directory2">create_directory</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
 Effects: Establishes the postcondition by attempting to create the
- directory <code>p</code> resolves to, as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/mkdir.html">
+ directory <code>p</code> resolves to, as if by ISO/IEC 9945 <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. Creation
 failure because <code>p</code> resolves to an existing directory shall not be
 treated as an error. 
@@ -2375,7 +2612,7 @@
<pre>void <a name="create_directory_symlink">create_directory_symlink</a>(const path& to, const path& new_symlink);
void create_directory_symlink(const path& to, const path& new_symlink, system::error_code& ec);</pre>
<blockquote>
- Effects: Establishes the postcondition, as if by ISO/IEC 9945 <code>symlink()</code>.
+ Effects: Establishes the postcondition, as if by ISO/IEC 9945 <code>symlink()</code>.
 
 Postcondition: <code>new_symlink</code> resolves to a symbolic link file that
 contains an unspecified representation of <code>to</code>.
@@ -2392,7 +2629,7 @@
<pre>void <a name="create_hard_link">create_hard_link</a>(const path& to, const path& new_hard_link);
void <a name="create_hard_link2">create_hard_link</a>(const path& to, const path& new_hard_link, system::error_code& ec);</pre>
<blockquote>
- Effects: Establishes the postcondition, as if by ISO/IEC 9945 <code>link()</code>.
+ Effects: Establishes the postcondition, as if by ISO/IEC 9945 <code>link()</code>.
 Postcondition:
 <ul>
 <li> <code>exists(to) &&
@@ -2412,7 +2649,7 @@
<pre>void <a name="create_symlink">create_symlink</a>(const path& to, const path& new_symlink);
void <a name="create_symlink2">create_symlink</a>(const path& to, const path& new_symlink, system::error_code& ec);</pre>
<blockquote>
- Effects: Establishes the postcondition, as if by ISO/IEC 9945 <code>symlink()</code>.
+ Effects: Establishes the postcondition, as if by ISO/IEC 9945 <code>symlink()</code>.
 
 Postcondition: <code>new_symlink</code> resolves to a symbolic link file that
 contains an unspecified representation of <code>to</code>.
@@ -2427,8 +2664,8 @@
<pre>path <a name="current_path">current_path</a>();
path <a name="current_path2">current_path</a>(system::error_code& ec);</pre>
<blockquote>
- Returns: The current working directory path, as if by ISO/IEC
- 9945 <code>getcwd()</code>. <code>is_absolute()</code> is true for the returned path.
+ Returns: The current working directory path, as if by ISO/IEC
+ 9945 <code>getcwd()</code>. <code>is_absolute()</code> is true for the returned path.
 Throws: As specified in Error reporting.
 [Note: The <code>current_path()</code> name was chosen to emphasize that the return is a
 path, not just a single directory name.
@@ -2439,7 +2676,7 @@
<pre>void current_path(const path& p);
void current_path(const path& p, system::error_code& ec);</pre>
<blockquote>
- Effects: Establishes the postcondition, as if by ISO/IEC 9945 <code>chdir()</code>.
+ Effects: Establishes the postcondition, as if by ISO/IEC 9945 <code>chdir()</code>.
Postcondition: <code>equivalent(p, current_path())</code>.
Throws: As specified in Error reporting.
 [Note: The current path for many operating systems is a dangerous
@@ -2453,7 +2690,7 @@
<pre>bool <a name="exists2">exists</a>(const path& p);
bool <a name="exists3">exists</a>(const path& p, system::error_code& ec) noexcept;</pre>
<blockquote>
- Returns: <code>exists(status(p))</code> or <code>exists(status(p, ec))</code>,
+ Returns: <code>exists(status(p))</code> or <code>exists(status(p, ec))</code>,
 respectively. If ec != 0 and an error
Throws: As specified in Error reporting.
</blockquote>
@@ -2468,10 +2705,10 @@
 <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 ISO/IEC 9945 <code>stat</code> structure<code>,</code> obtained as if by <code>stat()</code> for the two paths, having equal <code>st_dev</code> values
+ same location. This is determined as if by the values of the ISO/IEC 9945 <code>stat</code> structure<code>,</code> obtained as if by <code>stat()</code> for the two paths, having equal <code>st_dev</code> values
 and equal <code>st_ino</code> values.
- [Note: ISO/IEC 9945 requires that "st_dev must be unique within a Local Area Network". Conservative 
- ISO/IEC 9945 implementations may also wish to check for equal <code>st_size</code> and <code>st_mtime</code> values. Windows implementations may use <code>GetFileInformationByHandle()</code> as a surrogate for <code>stat()</code>,
+ [Note: ISO/IEC 9945 requires that "st_dev must be unique within a Local Area Network". Conservative
+ ISO/IEC 9945 implementations may also wish to check for equal <code>st_size</code> and <code>st_mtime</code> values. Windows implementations may use <code>GetFileInformationByHandle()</code> as a surrogate for <code>stat()</code>,
 and consider "same" to be equal values for <code>dwVolumeSerialNumber</code>, <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>,
@@ -2485,8 +2722,8 @@
 Returns: If <code>exists(p) && is_regular_file(p)</code>, the size
 in bytes
 of the file <code>p</code> resolves to, determined as if by the value of
- the ISO/IEC 9945 <code>stat</code> structure member <code>st_size</code> obtained as if by 
- ISO/IEC 9945 <code>stat()</code>.
+ the ISO/IEC 9945 <code>stat</code> structure member <code>st_size</code> obtained as if by
+ ISO/IEC 9945 <code>stat()</code>.
 Otherwise, <code>static_cast<uintmax_t>(-1)</code>.
 Throws: As specified in Error reporting.
</blockquote>
@@ -2572,17 +2809,17 @@
std::time_t <a name="last_write_time2">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 ISO/IEC 9945 <code>stat</code> structure member <code>st_mtime</code>  obtained
- as if by ISO/IEC 9945 <code>stat()</code>.
+ value of the ISO/IEC 9945 <code>stat</code> structure member <code>st_mtime</code>  obtained
+ as if by ISO/IEC 9945 <code>stat()</code>.
 Throws: As specified in Error reporting.
</blockquote>
<pre>void <a name="last_write_time3">last_write_time</a>(const path& p, const std::time_t new_time);
void <a name="last_write_time4">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> to <code>new_time</code>, as if by ISO/IEC
- 9945 <code>stat()</code> followed by 
- ISO/IEC 9945 utime().
+ resolved to by <code>p</code> to <code>new_time</code>, as if by ISO/IEC
+ 9945 <code>stat()</code> followed by
+ ISO/IEC 9945 utime().
 Throws: As specified in Error reporting.
 [Note: A postcondition of <code>last_write_time(p) == new_time</code> is not specified since it might not hold for file systems
 with coarse time granularity. -- end note]
@@ -2592,8 +2829,8 @@
<blockquote>
 
 Requires: <code>!((prms & add_perms) && (prms & remove_perms))</code>.
- Effects: Applies the effective permissions bits from <code>prms</code> to the file <code>p</code> resolves to, as if by 
- ISO/IEC 9945 <code>fchmodat()</code>. The effective permission bits are determined as
+ Effects: Applies the effective permissions bits from <code>prms</code> to the file <code>p</code> resolves to, as if by
+ ISO/IEC 9945 <code>fchmodat()</code>. The effective permission bits are determined as
 specified by the following table. 
 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
 <tr>
@@ -2632,7 +2869,7 @@
<blockquote>
 Effects:  If <code>exists(symlink_status(p,ec))</code>, it is
 removed
- as if by ISO/IEC 9945 <code>remove()</code>.
+ as if by ISO/IEC 9945 <code>remove()</code>.
 <blockquote>
 [Note: A symbolic link is itself removed, rather than the file it
 resolves to being removed. -- end note]
@@ -2647,7 +2884,7 @@
<blockquote>
 Effects:  Recursively deletes the contents of p if it exists,
 then deletes file <code>p</code> itself,
- as if by ISO/IEC 9945 <code>remove()</code>.
+ as if by ISO/IEC 9945 <code>remove()</code>.
 <blockquote>
 [Note: A symbolic link is itself removed, rather than the file it
 resolves to being removed. -- end note]
@@ -2659,8 +2896,8 @@
<pre>void <a name="rename">rename</a>(const path& old_p, const path& new_p);
void <a name="rename2">rename</a>(const path& old_p, const path& new_p, system::error_code& ec);</pre>
<blockquote>
- Effects: Renames <code>old_p</code> to <code>new_p</code>, as if by 
- ISO/IEC 9945 <code>rename()</code>.
+ Effects: Renames <code>old_p</code> to <code>new_p</code>, as if by
+ ISO/IEC 9945 <code>rename()</code>.
 <blockquote>
 [Note: If <code>old_p</code> and <code>new_p</code> resolve to the
 same existing file, no action is taken. Otherwise, if <code>new_p</code> resolves to an
@@ -2681,8 +2918,12 @@
space_info <a name="space2">space</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
 Returns: An object of type <code>space_info</code>. The value of the <code>space_info</code> object is determined as if by
- using ISO/IEC 9945 <code>statvfs()</code> to obtain a 
- ISO/IEC 9945 struct <code>statvfs</code>, and then multiplying its <code>f_blocks</code>, <code>f_bfree</code>, and <code>f_bavail</code> members by its <code>f_frsize</code> member, and assigning the results to the <code>capacity</code>, <code>free</code>,
+ using ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/statvfs.html"
+ style="text-decoration: none">statvfs()</a></code> to obtain a ISO/IEC 9945 struct
+ <code>statvfs</code>,
+ and then multiplying its <code>f_blocks</code>, <code>f_bfree</code>,
+ and <code>f_bavail</code> members by its <code>f_frsize</code> 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 Error reporting.
@@ -2708,7 +2949,7 @@
 Effects: 
 <blockquote>
 If possible, determines the attributes
- of the file <code>p</code> resolves to, as if by ISO/IEC 9945 <code>stat()</code>.
+ of the file <code>p</code> resolves to, as if by ISO/IEC 9945 <code>stat()</code>.
 If, during attribute determination, the underlying file system API reports
 an error, sets <code>ec</code> to indicate the specific error reported.
 Otherwise, <code>ec.clear()</code>.<blockquote>
@@ -2744,7 +2985,7 @@
 </blockquote>
 Otherwise,
 <ul>
- <li>If the attributes indicate a regular file, as if by ISO/IEC 9945 S_ISREG(),
+ <li>If the attributes indicate a regular file, as if by ISO/IEC 9945 S_ISREG(),
 return <code>
 file_status(regular_file)</code>. [Note: <code>
regular_file</code> implies appropriate <code><fstream></code> operations
@@ -2755,34 +2996,31 @@
fail on a directory.
-- end note] 
 </li>
- <li>Otherwise, if the attributes indicate a directory, as if by ISO/IEC
- 9945
+ <li>Otherwise, if the attributes indicate a directory, as if by ISO/IEC 9945
 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISDIR()</a>,
 return <code>
 file_status(directory_file)</code>. [Note: <code>directory_file</code> implies <code>
directory_iterator(p)</code>would succeed.
-- end note] 
 </li>
- <li>Otherwise, if the attributes indicate a block special file, as if by 
- ISO/IEC 9945
+ <li>Otherwise, if the attributes indicate a block special file, as if by ISO/IEC 9945
 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISBLK()</a>,
 return <code>
 file_status(block_file)</code>. 
 </li>
- <li>Otherwise, if the attributes indicate a character special file, as if by 
- ISO/IEC 9945
+ <li>Otherwise, if the attributes indicate a character special file, as if by ISO/IEC 9945
 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISCHR()</a>,
 return <code>
 file_status(character_file)</code>. 
 </li>
- <li>Otherwise, if the attributes indicate a fifo or pipe file, as if by 
- ISO/IEC 9945
+ <li>Otherwise, if the attributes indicate a fifo or pipe file, as if by
+ ISO/IEC 9945
 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISFIFO()</a>,
 return <code>
 file_status(fifo_file)</code>. 
 </li>
- <li>Otherwise, if the attributes indicate a socket, as if by ISO/IEC
- 9945
+ <li>Otherwise, if the attributes indicate a socket, as if by ISO/IEC
+ 9945
 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISSOCK()</a>,
 return <code>
 file_status(socket_file)</code>. 
@@ -2804,11 +3042,11 @@
<blockquote>
 Effects:  Same as status(), above,
 except that the attributes
- of <code>p</code> are determined as if by ISO/IEC 9945 <code>lstat()</code>.
+ of <code>p</code> are determined as if by ISO/IEC 9945 <code>lstat()</code>.
</blockquote>
<blockquote>
 Returns: Same as status(), above, except
- that if the attributes indicate a symbolic link, as if by ISO/IEC 9945 <a class="external" href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISLNK()</a>, return <code>file_status(symlink_file)</code>.
+ that if the attributes indicate a symbolic link, as if by ISO/IEC 9945 <a class="external" href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISLNK()</a>, return <code>file_status(symlink_file)</code>.
 Remarks: Pathname resolution terminates if <code>p</code> names a symbolic link.
 Throws: <code>filesystem_error</code>; overload with <code>error_code&</code> throws
 nothing.
@@ -2822,7 +3060,7 @@
 Returns: The composed path.
 Postcondition: For the returned path, <code>rp,</code> <code>rp.is_absolute()</code> is true.
 Throws: As specified in Error reporting.
- [Note: For ISO/IEC 9945, <code>system_complete(p)</code> has the same semantics as <code>complete(p, current_path())</code>.
+ [Note: For ISO/IEC 9945, <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
 same semantics as <code>complete(ph, current_path())</code> if <code>p.is_absolute() || !p.has_root_name()</code> or <code>p</code> and <code>base</code> have the same <code>root_name()</code>.
 Otherwise it acts like <code>complete(p, kinky)</code>, where <code>kinky</code> is the current directory for the <code>p.root_name()</code> drive. This will
@@ -2839,7 +3077,7 @@
 conventions of the operating system. The specifics of how this path is
 determined are implementation defined. An error shall be reported if<code> !exists(p)
 || !is_directory(p)</code>, where <code>p</code> is the path to be returned.
- ISO/IEC 9945: The path supplied by the first environment variable found in the
+ ISO/IEC 9945: The path supplied by the first environment variable found in the
 list TMPDIR, TMP, TEMP, TEMPDIR. If none of these are found, <code>"/tmp"</code>.
 Windows: The path reported by the Windows <code>GetTempPath</code> API function.
 Throws: As specified in Error reporting.
@@ -2866,6 +3104,10 @@
 provided by the operating system. [Note: Such generators may block
 until sufficient entropy develops. --end note]
</blockquote>
+<hr>
+
+
+

<h3><a name="File-streams">File streams</a> -
<a href="../../../boost/filesystem/fstream.hpp"><boost/filesystem/fstream.hpp></a></h3>
@@ -2931,8 +3173,8 @@

<h2><a name="Path-decomposition-table">Path decomposition table</a></h2>
The table is generated by a program compiled with the Boost implementation.
-Shaded entries indicate cases where ISO/IEC 9945 and Windows implementations yield different results. The top value is the 
-ISO/IEC 9945 result and the bottom value is the Windows result. 
+Shaded entries indicate cases where ISO/IEC 9945 (POSIX) and Windows implementations yield different results. The top value is the
+ISO/IEC 9945 result and the bottom value is the Windows result. 
<table border="1" cellspacing="0" cellpadding="5">

<tr><td>Constructor argument</td>
@@ -3478,7 +3720,7 @@
<h2><a name="References">References</a></h2>
<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
 <tr>
- <td width="16%" valign="top">[<a name="ISO_POSIX">ISO-ISO/IEC 9945</a>]</td>
+ <td width="16%" valign="top">[<a name="ISO_POSIX">ISO/IEC 9945</a>]</td>
 <td width="84%">ISO/IEC 9945:2003, IEEE Std 1003.1-2001, and The Open Group
 Base Specifications, Issue 6. Also known as The Single Unix®
 Specification, Version 3. Available from each of the organizations involved
@@ -3497,7 +3739,7 @@

<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>
Revised
-21 September 2012
+16 July 2012

</body></html>
\ No newline at end of file

Modified: trunk/libs/filesystem/doc/release_history.html
==============================================================================
--- trunk/libs/filesystem/doc/release_history.html (original)
+++ trunk/libs/filesystem/doc/release_history.html 2013-02-21 09:27:10 EST (Thu, 21 Feb 2013)
@@ -36,6 +36,15 @@
</tr>
</table>

+<h2>1.54.0</h2>
+<ul>
+ <li>Reimplement <code>path::codecvt()</code> and <code>path::imbue()</code>
+ with portable code that is intended to be much more robust and maintainable. A
+ section on path usage concerns has
+ been added to the reference documentation describing several concerns that
+ arise in the context of multithreading and <code>path::codecvt()</code>.</li>
+</ul>
+
<h2>1.52.0</h2>
<ul>
<li>Fix #7239, Stack
@@ -191,7 +200,7 @@
</ul>
<hr>
Revised
-28 August, 2012
+20 February, 2013
© Copyright Beman Dawes, 2011
 Use, modification, and distribution are subject to the Boost Software
License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt">

Modified: trunk/libs/filesystem/doc/src/build.bat
==============================================================================
--- trunk/libs/filesystem/doc/src/build.bat (original)
+++ trunk/libs/filesystem/doc/src/build.bat 2013-02-21 09:27:10 EST (Thu, 21 Feb 2013)
@@ -2,7 +2,9 @@
rem Copyright Beman Dawes 2012
rem Distributed under the Boost Software License, Version 1.0.
del tr2.html 2>nul
+echo building tr2.html
mmp TARGET=TR2 source.html tr2.html
del reference.html 2>nul
+echo building reference.html
mmp TARGET=BOOST source.html reference.html
echo run "hoist" to hoist reference.html to doc directory

Modified: trunk/libs/filesystem/doc/src/source.html
==============================================================================
--- trunk/libs/filesystem/doc/src/source.html (original)
+++ trunk/libs/filesystem/doc/src/source.html 2013-02-21 09:27:10 EST (Thu, 21 Feb 2013)
@@ -903,6 +903,58 @@
$NAMESPACE_END;</pre>
<code><a name="value_type">value_type</a></code> is a <code>typedef</code> for the
character type used by the operating system to represent pathnames.
+
+$if $TARGET; == BOOST
+<h3><a name="path-Usage"><code>path</code> Usage concerns</a> [path.usage]</h3>
+
+<h4>Multithreading concerns</h4>
+
+Filesystem library functions are not protected against data races. [Modifying
+an object of a Filesystem library type that is shared between threads risks
+undefined behavior unless objects of that type are explicitly specified as being
+sharable without data races or the user supplies a locking mechanism. —end
+note] [Note: Thus the Filesystem library behaves as if it were part
+of the standard library, and C++ standard 17.6.4.10 Shared objects and the
+library [res.on.objects] would thus apply.  —end note]
+
+<h4>Windows concerns</h4>
+
+Visual C++ at least through version 2012 does not employ C++11-style static
+initialization locks, so the initialization of <code>path::codecvt()</code> can
+race, either with itself or <code>path::imbue::()</code> if they are called from
+a different thread. A workaround is to call:
+
+<blockquote>
+<code>path::codecvt();  // ensure VC++ does not race during
+initialization.</code>
+
+</blockquote>
+in the main thread before launching any additional threads. [Note: The
+obvious fix of the Filesystem implementation doing the locking doesn't work
+because of unrelated problems with the Microsoft compiler; for static linking
+the runtime tries to do the initialization before main() starts, but doesn't
+permit operating system lock calls at that time.  —end note]
+
+<h4 dir="ltr">POSIX concerns</h4>
+
+Filesystem library initialization may throw an exception on POSIX
+systems (e.g. Linux, but not Mac OS X) that use environmental variables to
+determine the encoding of paths. This happens when <code>std::locale("")</code>
+throws because an environmental variable such as LANG is set to an invalid
+value, so it can affect any use of  <code>std::locale("")</code>, not just
+the Filesystem library. Filesystem uses lazy initialization so the exception is
+only thrown if a valid <code>std::locale("")</code> is actually needed, and also
+so that the exception is thrown after <code>main()</code> starts.
+
+Rather than waiting until a call to some Filesystem library function
+unexpectedly triggers the exception when it calls <code>path::codecvt()</code>,
+a program that needs be highly robust against environmental variable problems
+may want to preemptively call <code>std::locale("")</code> within a try block,
+catch the exception, and diagnose or repair the invalid environmental variable.
+
+$endif
+
+
<h3><a name="path-Conversions"><code>path</code> Conversions</a> [path.cvt]</h3>
<h4><code>path</code> argument conversions [<a name="path.arg.convert">path.arg.cvt</a>]</h4>
<h5><a name="path-Conversions-to-native-format"><code>path</code> argument

Next message: marshall_at_[hidden]: "[Boost-commit] svn:boost r83063 - trunk/libs/algorithm/test"
Previous message: adam.wulkiewicz_at_[hidden]: "[Boost-commit] svn:boost r83061 - sandbox/tuple-move/detail"

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