-<p><i>Headings and synopsis for recently added functionality are shown with a
-<span style="background-color: #CCFFCC">green background</span>. </i></p>
-
-
-
<h2><a name="TOC">Table of Contents</a></h2>
<table border="0" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
<a href="#Error-reporting">Error reporting</a><br>
<a href="#class-path">Class <code>path</code></a><br>
<a href="#path-Conversions"><code>path</code> conversions</a><br>
- <a href="#path-Conversions-to-native-format"><code>path</code>
+ <a href="#path-Conversions-to-native-format"><code>path</code>
conversions to native format</a><br>
- <a href="#path-Conversions-to-generic-format"><code>path</code>
+ <a href="#path-Conversions-to-generic-format"><code>path</code>
conversions to generic format</a><br>
- <a href="#path-Encoding-conversions"><code>path</code>
+ <a href="#path-Encoding-conversions"><code>path</code>
encoding conversions</a><br>
<a href="#path-Requirements"><code>path</code> requirements</a><br>
<a href="#path-constructors"><code>path</code> constructors</a><br>
<a href="#path-appends"><code>path</code> appends</a><br>
<a href="#path-concatenation"><code>path</code> concatenation</a><br>
<a href="#path-modifiers"><code>path</code> modifiers</a><br>
- <a href="#path-native-format-observers"><code>path</code> native
+ <a href="#path-native-format-observers"><code>path</code> native
format observers</a><br>
- <a href="#path-generic-format-observers"><code>path</code> generic
+ <a href="#path-generic-format-observers"><code>path</code> generic
format observers</a><br>
<a href="#path-compare"><code>path</code> compare</a><br>
<a href="#path-decomposition"><code>path</code> decomposition</a><br>
<a href="#path-non-member-functions"><code>path</code> non-member functions</a><br>
<a href="#path-inserter-extractor"><code>path</code> inserters and extractors</a><br>
<a href="#Class-filesystem_error">Class <code>filesystem_error</code></a><br>
- <a href="#filesystem_error-members"><code>filesystem_error</code>
+ <a href="#filesystem_error-members"><code>filesystem_error</code>
constructors</a><br>
<a href="#filesystem_error-path1"><code>filesystem_error</code> path1</a><br>
<a href="#filesystem_error-path2"><code>filesystem_error</code> path2</a><br>
<p>
<a href="#Enum-file_type">Enum <code>file_type</code></a><br>
<a href="#Enum-perms">Enum <code>perms</code></a><br>
- <a href="#file_status">Class
+ <a href="#file_status">Class
<code>file_status</code></a><br>
- <a href="#file_status">
+ <a href="#file_status">
<code>file_status</code></a><a href="#file_status-constructors"> constructors</a><br>
<code><a href="#file_status-modifiers">file_status-modifiers</a></code><a href="#directory_entry-observers"> observers</a><br>
<code><a href="#file_status-observers">file_status-observers</a></code><a href="#directory_entry-modifiers"> modifiers</a><br>
<a href="#directory_entry-observers"><code>directory_entry</code> observers</a><br>
<a href="#directory_entry-modifiers"><code>directory_entry</code> modifiers</a><br>
<a href="#Class-directory_iterator">Class <code>directory_iterator</code></a><br>
- <a href="#directory_iterator-members"><code>directory_iterator</code>
+ <a href="#directory_iterator-members"><code>directory_iterator</code>
members</a><br>
<a href="#Class-recursive_directory_iterator">Class <code>recursive_directory_iterator</code></a><br>
<a href="#Operational-functions">
<a href="#last_write_time">last_write_time</a><br>
<a href="#permissions">permissions</a><br>
<a href="#read_symlink">read_symlink</a><br>
- <a href="#op-relative">
- <span style="background-color: #CCFFCC">relative</span></a><br>
+ <a href="#op-relative">relative</a><br>
<a href="#remove">remove</a><br>
<a href="#remove_all">remove_all</a><br>
<a href="#rename">rename</a><br>
<a href="#system_complete">system_complete</a><br>
<a href="#temp_directory_path">temp_directory_path</a><br>
<a href="#unique_path">unique_path</a><br>
- <a href="#weakly_canonical">
- <span style="background-color: #CCFFCC">weakly_canonical</span></a><br></code>
+ <a href="#weakly_canonical">weakly_canonical</a><br></code>
<a href="#File-streams">File streams</a><br>
<a href="#path-decomposition-table">Path decomposition table</a><br>
- <a href="#long-path-warning">Warning: Long paths on Windows and the
+ <a href="#long-path-warning">Warning: Long paths on Windows and the
extended-length <b>\\?\ </b>prefix</a><br>
<a href="#Acknowledgements">Acknowledgements</a><br>
<a href="#References">References</a><br>
<h2><a name="Introduction">Introduction</a></h2>
-<p>This reference documentation describes components that C++ programs may use
-to perform operations involving file systems, including paths, regular files,
+<p>This reference documentation describes components that C++ programs may use
+to perform operations involving file systems, including paths, regular files,
and directories.</p>
<blockquote>
bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
<tr>
<td width="100%" align="center" colspan="2">
- <p align="center"><b>C++11 Support</b><p align="left">This 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
+ <p align="center"><b>C++11 Support</b><p align="left">This 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="left">
<p>New character types</td>
<td width="65%" align="left">
- <p>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>
+ <p>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>
<td width="35%" align="left">
<p>Range-based for statements</td>
<td width="65%" align="left">
- <p>Supporting functions always provided; they do no harm even for C++03
+ <p>Supporting functions always provided; they do no harm even for C++03
compilers.</td>
</tr>
</table>
<h3>ISO/IEC 9945 conformance [fs.conform.9945]</h3>
<p>Some behavior in this reference documentation is specified by reference to ISO/IEC 9945. How such behavior is actually implemented is unspecified.</p>
<blockquote>
-<p>[<i>Note:</i> This constitutes an "as if" rule for implementation of
-operating system dependent behavior. In practice implementations will usually call native
+<p>[<i>Note:</i> This constitutes an "as if" rule for implementation of
+operating system dependent behavior. In practice implementations will usually call native
operating system API's. <i>—end note</i>]</p>
</blockquote>
-<p>Implementations are encouraged to provide such behavior
-
-as it is defined by ISO/IEC 9945. Implementations shall document any
-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
-reasonable behavior, the implementation shall report an error in an
+<p>Implementations are encouraged to provide such behavior
+
+as it is defined by ISO/IEC 9945. Implementations shall document any
+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
+reasonable behavior, the implementation shall report an error in an
implementation-defined manner.</p>
<blockquote>
<p>[<i>Note:</i> Such errors might be reported by an #error directive, a <code>
-static_assert</code>, a <code>filesystem_error</code> exception, a special
+static_assert</code>, a <code>filesystem_error</code> exception, a special
return value, or some other manner. <i>—end note</i>]</p>
</blockquote>
-<p>Implementations are not required to provide behavior that is not supported by
+<p>Implementations are not required to provide behavior that is not supported by
a particular file system.</p>
<blockquote>
<p>[<i>Example:</i> The <a href="http://en.wikipedia.org/wiki/FAT_filesystem">
-FAT file system</a> used by some memory cards, camera memory, and floppy discs
-does not support hard links, symlinks, and many other features of more capable
-file systems. Implementations are only required to support the FAT features
+FAT file system</a> used by some memory cards, camera memory, and floppy discs
+does not support hard links, symlinks, and many other features of more capable
+file systems. Implementations are only required to support the FAT features
supported by the host operating system. <i>—end example</i>]</p>
</blockquote>
-<p>The behavior of functions described in this
-reference
-may differ from their specification in
+<p>The behavior of functions described in this
+reference
+may differ from their specification in
the presence of <a href="#file-system-race">file system races</a>. No diagnostic is required.</p>
-<p>If the possibility of a file system race would make it unreliable for a program to
+<p>If the possibility of a file system race would make it unreliable for a program to
test for a precondition before calling a function described in this reference documentation, <i>
-Requires</i> is not specified for the condition. Instead, the condition is
+Requires</i> is not specified for the condition. Instead, the condition is
specified as a <i>Throws</i> condition.</p>
<blockquote>
-<p>[<i>Note:</i> As a design practice, preconditions are not specified when it
+<p>[<i>Note:</i> As a design practice, preconditions are not specified when it
is unreasonable for a program to detect them prior to calling the function. <i>
—end note</i>]</p>
</blockquote>
<h3>Operating system dependent conformance [fs.conform.os]</h3>
-<p>Some behavior is specified in this reference documentation as being
-operating system dependent ([fs.def.osdep]). The operation system an
+<p>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.</p>
-<p>It is permissible for an implementation to be dependent upon an operating
+<p>It is permissible for an implementation to be dependent upon an operating
system emulator rather than the actual operating system.</p>
<blockquote>
-<p>[<i>Example:</i> 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
+<p>[<i>Example:</i> 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. <i>—end example</i>]</p>
-<p><span style="background-color: #E0E0E0"><i>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
+<p><span style="background-color: #E0E0E0"><i>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.</i></span> </p>
</blockquote>
<h2><a name="Definitions">Definitions</a> [fs.definitions]</h2>
<p>The following definitions shall apply throughout this reference documentation:</p>
-<h3><a name="operating system dependent">operating system dependent</a> behavior
+<h3><a name="operating system dependent">operating system dependent</a> behavior
[fs.def.osdep]</h3>
-<p>Behavior that is dependent upon the behavior
+<p>Behavior that is dependent upon the behavior
and characteristics of an operating system. See [fs.conform.os].</p>
<h3><a name="file">file</a> [fs.def.file]</h3>
-<p>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
+<p>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.</p>
<h3><a name="file-system">file system</a> [fs.def.filesystem]</h3>
<p>A collection of files and certain of their attributes.</p>
<h3><a name="filename">filename</a> [fs.def.filename]</h3>
<p>The name of a file. Filenames <code>
- "."</code>
-and <code>".."</code> have special meaning. The follow characteristics of
+ "."</code>
+and <code>".."</code> have special meaning. The follow characteristics of
filenames are operating system dependent:</p>
<ul>
<li>
- <p>The permitted characters. See [<a href="#Operating-system-examples">fs.os.example</a>s].</p>
+ <p>The permitted characters. See [<a href="#Operating-system-examples">fs.os.examples</a>].</p>
</li>
<li>
<p>Specific filenames that are not permitted.</p>
<p>Case awareness and sensitivity during path resolution.</p>
</li>
<li>
- <p>Special rules that may apply to file types other than regular
+ <p>Special rules that may apply to file types other than regular
files, such as directories.</p>
</li>
</ul>
<h3><a name="path">path</a> [fs.def.path]</h3>
-<p>A sequence of elements that identify
+<p>A sequence of elements that identify
the location of a file within a filesystem. The elements are the <i>root-name<sub>opt</sub></i>, <i>
-root-directory<sub>opt</sub></i>, and an optional sequence of filenames. [<i>Note:</i>
+root-directory<sub>opt</sub></i>, and an optional sequence of filenames. [<i>Note:</i>
A <a href="#pathname">pathname</a> is the concrete representation of a path. <i>—end note</i>]</p>
<h3><a name="Absolute-path">absolute path</a> [fs.def.absolute-path]</h3>
-<p>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
+<p>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
operating system dependent.</p>
<h3><a name="Relative-path">relative path</a> [fs.def.relative-path]</h3>
-<p>A path that
-is not absolute, and so only
-unambiguously
-identifies the location of a file when resolved relative to
-an implied starting location. The elements of a path that determine if it is
-relative are operating system dependent. [<i>Note:</i>
+<p>A path that
+is not absolute, and so only
+unambiguously
+identifies the location of a file when resolved relative to
+an implied starting location. The elements of a path that determine if it is
+relative are operating system dependent. [<i>Note:</i>
Paths <code>"."</code> and <code>".."</code> are relative paths. <i>—end note</i>]</p>
<h3><a name="canonical-path">canonical path</a> [fs.def.canonical-path]</h3>
-<p>An absolute path that has
+<p>An absolute path that has
no elements that are symbolic links, and no <code>"."</code> or <code>".."</code> elements.</p>
<h3><a name="pathname">pathname</a> [fs.def.pathname]</h3>
-<p>A character string that represents
-the name of a
-path. Pathnames are formatted according to the generic pathname grammar or an
-operating system dependent
+<p>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.</p>
<h3><a name="native-pathname-format">native pathname format</a> [fs.def.native]</h3>
<p>The operating system dependent pathname format accepted by the host operating system.</p>
-<h3><a name="normal-form"><span style="background-color: #CCFFCC">normal form</span></a><span style="background-color: #CCFFCC"> path</span> [fs.def.normal]</h3>
-<p>A path with no redundant current directory (<i>dot</i>) or parent directory (<i>dot-dot</i>)
-elements. The normal form for an empty path is an empty path. The normal form
-for a path ending in a <i>directory-separator</i> that is not the root directory
+<h3><a name="normal-form">normal form</a> path [fs.def.normal]</h3>
+<p>A path with no redundant current directory (<i>dot</i>) or parent directory (<i>dot-dot</i>)
+elements. The normal form for an empty path is an empty path. The normal form
+for a path ending in a <i>directory-separator</i> that is not the root directory
is the same path with a current directory (<i>dot</i>) element appended.</p>
<h3><a name="link">link</a> [fs.def.link]</h3>
-<p>A directory entry object that associates a
-filename with a file. On some file systems, several directory entries can
+<p>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.</p>
<h3><a name="hard-link">hard link</a> [fs.def.hardlink]</h3>
-<p>A link to an existing file. Some
-file systems support multiple hard links to a file. If the last hard link to a
+<p>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.</p>
<blockquote>
-<p>[<i>Note:</i> A hard link can be thought of as a shared-ownership smart
+<p>[<i>Note:</i> A hard link can be thought of as a shared-ownership smart
pointer to a file.<i> —end note</i>]<i> </i></p>
</blockquote>
<h3><a name="symbolic-link">symbolic link</a> [fs.def.symlink]</h3>
-<p>A type of file with the
-property that when the file is encountered during pathname resolution, a string
+<p>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.</p>
<blockquote>
-<p>[<i>Note:</i> 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
+<p>[<i>Note:</i> 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.<i> —end note</i>]<i> </i></p>
</blockquote>
<h3><a name="file-system-race">file system race</a> [fs.def.race]</h3>
-<p>The condition that occurs
-when multiple threads, processes, or computers interleave access and
-modification of
+<p>The condition that occurs
+when multiple threads, processes, or computers interleave access and
+modification of
the same object within a file system.</p>
<h2><a name="generic-pathname-format">Generic pathname format</a> [path.generic]</h2>
<p><i>pathname:<br>
- root-name<sub>opt</sub>
+ root-name<sub>opt</sub>
root-directory<sub>opt</sub> relative-path<sub>opt</sub></i></p>
<p><i>root-name:<br>
- </i>An
-operating system dependent name that identifies the starting location for
+ </i>An
+operating system dependent name that identifies the starting location for
absolute paths. </p>
<blockquote>
<blockquote>
-<p>[<i>Note:</i> Many operating systems define a name
-beginning with two <i>directory-separator</i> characters as a <i>root-name</i>
-that identifies network or other resource locations. Some operating systems define a single letter followed by a colon as a drive
+<p>[<i>Note:</i> Many operating systems define a name
+beginning with two <i>directory-separator</i> characters as a <i>root-name</i>
+that identifies network or other resource locations. Some operating systems define a single letter followed by a colon as a drive
specifier - a <i>root-name</i> identifying a specific device such as a disc drive. <i>—end note</i>]</p>
</blockquote>
</blockquote>
<p><i>root-directory:<br>
-
+
directory-separator</i></p>
<p><i>relative-path:<br>
-
+
filename<br>
- relative-path
+ relative-path
directory-separator<br>
- relative-path
+ relative-path
directory-separator filename</i></p>
<p><i>filename:<br>
name<br>
</i><code>
".."</code></p>
<p><i>preferred-separator:<br>
- </i>An
+ </i>An
operating system dependent directory separator character. May be a synonym for <i> <code>"/"</code>.</i></p>
<p><i>directory-separator:<br>
<code>"/"<br>
"/"</code> directory-separator<br>
-
+
preferred-separator<br>
-
+
preferred-separator directory-separator</i></p>
-<p>Multiple successive <i>directory-separator</i> characters are considered to
+<p>Multiple successive <i>directory-separator</i> characters are considered to
be the same as one <i>directory-separator</i> character.</p>
<p>The <i>filename</i>
<code>"."</code> is considered to be a reference to the current directory. The
-<i>filename</i> <code>".."</code> is considered to be a reference to the
-parent
-directory. Specific <i>filenames</i> may have special meanings for a particular
+<i>filename</i> <code>".."</code> is considered to be a reference to the
+parent
+directory. Specific <i>filenames</i> may have special meanings for a particular
operating system.</p>
<h2><a name="Operating-system-examples">Operating system dependent examples</a> (Informative) [fs.os.examples]</h2>
-<p>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
+<p>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).<sup>[footnote1]</sup></p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<tr>
</tr>
<tr>
<td valign="top">
- <p><code>path</code> argument disambiguation between generic format and
+ <p><code>path</code> argument disambiguation between generic format and
native format</td>
<td valign="top">
<p>[<a href="#path-Conversions-to-native-format">path.arg</a><br>
<td valign="top">
<p>Not required</td>
<td valign="top">
- <p>There is no need to distinguish between the generic format and native
+ <p>There is no need to distinguish between the generic format and native
format for these operating systems.</td>
</tr>
<tr>
<td valign="top">
<p>[<a href="#path-Conversions-to-native-format">path.arg</a><br>
<a href="#path-Conversions-to-native-format">.fmt.cvt</a>]</td>
- <td valign="top">
+ <td valign="top">
<p> <code><br>
<br>
"/cats/jane"<br>
<br>
L"/cats/jane/"</code></td>
<td valign="top">
- <p>These operating systems accept the same native separator between
- directory names and a final file name, so no format conversion is performed.
+ <p>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 valign="top">
<p>No conversion performed</td>
<td valign="top">
- <p>For efficiency, <code>path</code> objects are required to store pathnames in the native
+ <p>For efficiency, <code>path</code> objects are required to store pathnames in the native
format regardless of operating system.</td>
</tr>
<tr>
<td valign="top">
<p>0x00, <code>'/'</code></td>
<td valign="top">
- <p>0x00-0x1F, <code>'"'</code>, <code>'*'</code>,<code> '*'</code>,
- <code>'<'</code>,
- <code>'>'</code>, <code>'?'</code>, <code>'\\'</code> (single backslash),
+ <p>0x00-0x1F, <code>'"'</code>, <code>'*'</code>,<code> '*'</code>,
+ <code>'<'</code>,
+ <code>'>'</code>, <code>'?'</code>, <code>'\\'</code> (single backslash),
<code>'/'</code>, <code>'|'</code></td>
<td valign="top">
- <p>Many operating systems prohibit the ASCII control characters (0x00-0x1F)
+ <p>Many operating systems prohibit the ASCII control characters (0x00-0x1F)
in filenames.</td>
</tr>
<tr>
<p>[<a href="#path-imbued-locale">path</a><br>
<a href="#path-imbued-locale">.imbued</a><br>
<a href="#path-imbued-locale">.locale</a>]</td>
- <td valign="top">
+ <td valign="top">
<p> <code>std::<br>
locale("")<br>
</code><sup>[footnote 2]</sup></td>
<td valign="top">
<p>Implementation supplied locale using <code>MultiByte<br>
- ToWideChar</code>
+ ToWideChar</code>
and <code>WideChar<br>
- ToMultiByte</code> with a codepage of <code>CP_ACP</code>
- if <code>AreFileApisANSI</code> is true, otherwise codepage <code>CP_OEMCP</code>.<sup>[footnote
+ ToMultiByte</code> with a codepage of <code>CP_ACP</code>
+ if <code>AreFileApisANSI</code> is true, otherwise codepage <code>CP_OEMCP</code>.<sup>[footnote
3]</sup></td>
<td valign="top">
- <p>Apple OS X®: Implementation supplied locale providing UTF-8 <code>codecvt</code>
+ <p>Apple OS X®: Implementation supplied locale providing UTF-8 <code>codecvt</code>
facet.<sup>[footnote 4]</sup></td>
</tr>
</table>
-<p><sup>[footnote1]</sup> 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
+<p><sup>[footnote1]</sup> 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.</p>
-<p><sup>[footnote 2] </sup>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
+<p><sup>[footnote 2] </sup>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."</p>
-<p><sup>[footnote 3] </sup>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
+<p><sup>[footnote 3] </sup>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.</p>
-<p><sup>[footnote 4]</sup> Rationale: Vendor's documentation states "All BSD
-system functions expect their string parameters to be in UTF-8 encoding and
+<p><sup>[footnote 4]</sup> Rationale: Vendor's documentation states "All BSD
+system functions expect their string parameters to be in UTF-8 encoding and
nothing else."</p>
-<h2><a name="Header-filesystem-synopsis">Header <code><boost/filesystem.hpp></code> synopsis</a>
+<h2><a name="Header-filesystem-synopsis">Header <code><boost/filesystem.hpp></code> synopsis</a>
[filesystem.synopsis]</h2>
namespace filesystem
{
class <a href="#class-path">path</a>;
-
+
bool lexicographical_compare(path::iterator first1, path::iterator last1,
path::iterator first2, path::iterator last2);
void swap(path& lhs, path& rhs);
bool operator>=(const path& lhs, const path& rhs);
path operator/ (const path& lhs, const path& rhs);
-
+
std::ostream& operator<<( std::ostream& os, const path& p );
std::wostream& operator<<( std::wostream& os, const path& p );
std::istream& operator>>( std::istream& is, path& p );
std::wistream& operator>>( std::wistream& is, path& p )
- class <a href="#Class-filesystem_error">filesystem_error</a>;
+ class <a href="#Class-filesystem_error">filesystem_error</a>;
class <a href="#Class-directory_entry">directory_entry</a>;
class <a href="#Class-directory_iterator">directory_iterator</a>;
struct <a name="space_info">space_info</a> // returned by <a href="#space" style="text-decoration: none">space</a> function
{
uintmax_t capacity;
- uintmax_t free;
+ uintmax_t free;
uintmax_t available; // free space available to non-privileged process
};
overwrite_if_exists
};
- enum class <a name="symlink_option">symlink_option</a>
+ enum class <a name="directory_options">directory_options</a>
{
none
+ skip_permission_denied,
+ follow_directory_symlink,
+ pop_on_error
+ };
+
+ // Deprecated, use <a href="#directory_options">directory_options</a> instead
+ enum class <a name="symlink_option">symlink_option</a>
+ {
+ none = directory_options::none
no_recurse = none,
- recurse
+ recurse = directory_options::follow_directory_symlink
};
// <a href="#Operational-functions">operational functions</a>
bool <a href="#is_other2">is_other</a>(const path& p,);
bool <a href="#is_other2">is_other</a>(const path& p, system::error_code& ec) noexcept;
- bool <a href="#is_regular_file">is_regular_file</a>(file_status s) noexcept;
- bool i<a href="#is_regular_file2">s_regular_file</a>(const path& p);
- bool i<a href="#is_regular_file2">s_regular_file</a>(const path& p,
+ bool <a href="#is_regular_file">is_regular_file</a>(file_status s) noexcept;
+ bool <a href="#is_regular_file2">is_regular_file</a>(const path& p);
+ bool <a href="#is_regular_file2">is_regular_file</a>(const path& p,
system::error_code& ec) noexcept;
bool <a href="#is_symlink">is_symlink</a>(file_status s noexcept);
path <a href="#read_symlink">read_symlink</a>(const path& p);
path <a href="#read_symlink">read_symlink</a>(const path& p, system::error_code& ec);
-
- <span style="background-color: #E8FFE8">path </span><span style="background-color: #E8FFE8">relative(const</span><span style="background-color: #E8FFE8"> path& p, </span><span style="background-color: #E8FFE8">system::error_code</span><span style="background-color: #E8FFE8">& </span><span style="background-color: #E8FFE8">ec</span><span style="background-color: #E8FFE8">);</span>
- <span style="background-color: #E8FFE8">path </span><span style="background-color: #E8FFE8">relative(const</span><span style="background-color: #E8FFE8"> path& p, const path& base=</span><span style="background-color: #E8FFE8">current_path</span><span style="background-color: #E8FFE8">());</span>
- <span style="background-color: #E8FFE8">path </span><span style="background-color: #E8FFE8">relative(const</span><span style="background-color: #E8FFE8"> path& p,</span>
- <span style="background-color: #E8FFE8">const path& base, </span><span style="background-color: #E8FFE8">system::error_code</span><span style="background-color: #E8FFE8">& </span><span style="background-color: #E8FFE8">ec</span><span style="background-color: #E8FFE8">);</span>
+
+ path <a href="#op-relative">relative</a>(const path& p, system::error_code& ec);
+ path <a href="#op-relative">relative</a>(const path& p, const path& base=current_path());
+ path <a href="#op-relative">relative</a>(const path& p,
+ const path& base, system::error_code& ec);
bool <a href="#remove">remove</a>(const path& p);
bool <a href="#remove">remove</a>(const path& p, system::error_code& ec);
path <a href="#unique_path">unique_path</a>(const path& model="%%%%-%%%%-%%%%-%%%%");
path <a href="#unique_path">unique_path</a>(const path& model, system::error_code& ec);
- <span style="background-color: #E8FFE8">path </span><span style="background-color: #E8FFE8">weakly_canonical(const</span><span style="background-color: #E8FFE8"> path& p);</span>
- <span style="background-color: #E8FFE8">path </span><span style="background-color: #E8FFE8">weakly_canonical(const</span><span style="background-color: #E8FFE8"> path& p, </span><span style="background-color: #E8FFE8">system::error_code</span><span style="background-color: #E8FFE8">& </span><span style="background-color: #E8FFE8">ec</span><span style="background-color: #E8FFE8">);</span>
+ path <a href="#weakly_canonical">weakly_canonical</a>(const path& p);
+ path <a href="#weakly_canonical">weakly_canonical</a>(const path& p, system::error_code& ec);
} // namespace filesystem
} // namespace boost</pre>
<h2><a name="Error-reporting">Error reporting</a> [fs.err.report]</h2>
-<p>Filesystem library functions often provide two overloads, one that
+<p>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>.</p>
<blockquote>
<p>[<i>Note:</i> This supports two common use cases:</p>
<ul>
<li>
- <p>Uses where file system
-errors are truly exceptional and indicate a serious failure. Throwing an
- exception is the most appropriate response. This is the preferred default for
+ <p>Uses where file system
+errors are truly exceptional and indicate a serious failure. Throwing an
+ exception is the most appropriate response. This is the preferred default for
most everyday programming.<br>
</li>
<li>
- <p>Uses where file system errors are routine and do not necessarily represent
- failure. Returning an error code is the most appropriate response. This allows
+ <p>Uses where file system errors are routine and do not necessarily represent
+ failure. Returning an error code is the most appropriate response. This allows
application specific error handling, including simply ignoring the error.</li>
</ul>
<p><i>—end note</i>]</p>
<p>Functions <b>not</b> having an argument of type <code>system::error_code&</code> report errors as follows, unless otherwise specified:</p>
<ul>
<li>
- <p>When a call by the
- implementation to an operating system or other underlying API results in an
- error that prevents the function from meeting its specifications, an exception
+ <p>When a call by the
+ implementation to an operating system or other underlying API results in an
+ error that prevents the function from meeting its specifications, an exception
of type
<code>filesystem_error</code> is thrown.<br>
</li>
<li>
- <p>Failure to allocate storage is reported by throwing an exception as described in the C++ standard,
+ <p>Failure to allocate storage is reported by throwing an exception as described in the C++ standard,
17.6.4.10 [res.on.exception.handling].<br>
</li>
<li>
<p>Destructors throw nothing.</li>
</ul>
- <p>Functions having an argument of type <code>system::error_code&</code> report errors as follows, unless otherwise
+ <p>Functions having an argument of type <code>system::error_code&</code> report errors as follows, unless otherwise
specified:</p>
<ul>
<li>
- <p>If a call by the
- implementation to an operating system or other underlying API results in an
+ <p>If a call by the
+ implementation to an operating system or other underlying API results in an
error that prevents the function from meeting its specifications, the
-<code>system::error_code&</code> argument is set as
- appropriate for the specific error. Otherwise, <code>clear()</code>
+<code>system::error_code&</code> argument is set as
+ appropriate for the specific error. Otherwise, <code>clear()</code>
is called on the
<code>system::error_code&</code> argument.<br>
</li>
<li>
- <p>Failure to allocate storage is reported by
- throwing an exception as described in the C++ standard,
+ <p>Failure to allocate storage is reported by
+ throwing an exception as described in the C++ standard,
17.6.4.10 [res.on.exception.handling].</li>
</ul>
<h2><a name="class-path">Class <code>path</code> [class.path]</a></h2>
-<p>An object of class <code>path</code> represents a <a href="#path">path</a>,
-and contains a <a href="#pathname">pathname</a> 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
-pathname is not necessarily valid for the current operating
+<p>An object of class <code>path</code> represents a <a href="#path">path</a>,
+and contains a <a href="#pathname">pathname</a> 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
+pathname is not necessarily valid for the current operating
system or for a particular file system.</p>
<div dir="ltr">
template <class InputIterator>
path& concat(InputIterator begin, InputIterator end,
const codecvt_type& cvt);
-
+
// <a href="#path-modifiers">modifiers</a>
void <a href="#path-clear">clear</a>();
path& <a href="#path-make_preferred">make_preferred</a>();
void <a href="#path-swap">swap</a>(path& rhs);
// lexical operations
- <span style="background-color: #E8FFE8">path </span><span style="background-color: #E8FFE8">lexically_normal</span><span style="background-color: #E8FFE8">() const;</span>
- <span style="background-color: #E8FFE8">path </span><span style="background-color: #E8FFE8">lexically_relative(const</span><span style="background-color: #E8FFE8"> path& base) const;</span>
+ path <a href="#lexically_normal">lexically_normal</a>() const;
+ path <a href="#lexically_relative">lexically_relative</a>(const path& base) const;
+ path <a href="#lexically_proximate">lexically_proximate</a>(const path& base) const;
// <a href="#path-native-format-observers">native format observers</a>
const string_type& <a href="#native">native</a>() const noexcept; // native format, encoding
const value_type* <a href="#c_str">c_str</a>() const noexcept; // native().c_str()
- <span style="background-color: #E8FFE8">string_type::size_type</span><span style="background-color: #E8FFE8"> </span><a href="#path-size"><span style="background-color: #E8FFE8">size</span></a><span style="background-color: #E8FFE8">() const noexcept; // </span><span style="background-color: #E8FFE8">native().size</span><span style="background-color: #E8FFE8">()</span>
+ string_type::size_type <a href="#path-size">size</a>() const noexcept; // native().size()
template <class String>
String <a href="#string-template">string</a>(const codecvt_type& cvt=codecvt()) const;
template <class String>
String <a href="#generic_string-template">generic_string</a>() const;
- string <a href="#generic_string">generic_string</a>(const codecvt_type& cvt=codecvt()) const;
+ string <a href="#generic_string">generic_string</a>(const codecvt_type& cvt=codecvt()) const;
wstring <a href="#generic_wstring">generic_wstring</a>(const codecvt_type& cvt=codecvt()) const;
u16string <a href="#generic_u16string">generic_u16string</a>()
u32string <a href="#generic_u32wstring">generic_u32string</a>()
// <a href="#path-query">query</a>
bool <a href="#path-query">empty</a>() const;
- <span style="background-color: #CCFFCC">bool <a href="#filename_is_dot">filename_is_dot</a>() const;</span>
- <span style="background-color: #CCFFCC">bool <a href="#filename_is_dot_dot">filename_is_dot_dot</a>() const;</span>
+ bool <a href="#filename_is_dot">filename_is_dot</a>() const;
+ bool <a href="#filename_is_dot_dot">filename_is_dot_dot</a>() const;
bool <a href="#path-has_root_name">has_root_name</a>() const;
bool <a href="#path-has_root_directory">has_root_directory</a>() const;
bool <a href="#path-has_root_path">has_root_path</a>() const;
iterator end() const;
reverse_iterator rbegin() const;
reverse_iterator rend() const;
-
+
// <a href="#path-imbued-locale">imbued locale</a>
static std::locale <a href="#path-imbue">imbue</a>(const std::locale& loc);
static const codecvt_type & <a href="#path-codecvt">codecvt</a>();
</div>
-<p><code><a name="value_type">value_type</a></code> is a <code>typedef</code> for the
+<p><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.</p>
<h4>Multithreading concerns</h4>
-<p>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. <i>—end
-note</i>] [<i>Note:</i> Thus the Filesystem library behaves as if it were part
-of the standard library, and C++ standard 17.6.4.10 <i>Shared objects and the
+<p>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. <i>—end
+note</i>] [<i>Note:</i> Thus the Filesystem library behaves as if it were part
+of the standard library, and C++ standard 17.6.4.10 <i>Shared objects and the
library</i> [res.on.objects] would thus apply. <i>—end note</i>]</p>
<h4>Windows concerns</h4>
-<p>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
+<p>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:</p>
<blockquote>
-<p><code>path::codecvt(); // ensure VC++ does not race during
+<p><code>path::codecvt(); // ensure VC++ does not race during
initialization.</code></p>
</blockquote>
-<p>in the main thread before launching any additional threads. [<i>Note:</i> 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
+<p>in the main thread before launching any additional threads. [<i>Note:</i> 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. <i>—end note</i>]</p>
<h4>POSIX concerns</h4>
-<p>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
+<p>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.</p>
-<p>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,
+<p>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.</p>
<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
+<h5><a name="path-Conversions-to-native-format"><code>path</code> argument
format conversions</a> [path.arg.fmt.cvt]</h5>
-<p>Member function arguments that take character sequences representing paths
-may use the <a href="#generic-pathname-format">generic pathname format</a> or
-the <a href="#native-pathname-format">native pathname format</a>. 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
+<p>Member function arguments that take character sequences representing paths
+may use the <a href="#generic-pathname-format">generic pathname format</a> or
+the <a href="#native-pathname-format">native pathname format</a>. 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 [<a href="#Operating-system-examples">fs.os.examples</a>].</p>
<blockquote>
-<p>[<i>Note:</i> 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
+<p>[<i>Note:</i> 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. <i>
—end note</i>]</p>
</blockquote>
-<p>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,
+<p>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.</p>
<h5><a name="path-Encoding-conversions"><code>
-path</code> argument encoding conversions</a>
+path</code> argument encoding conversions</a>
[path.arg.encoding.cvt]</h5>
-<p>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>
+<p>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. ([<a href="#path-imbued-locale">path.imbued.locale</a>]).</p>
-<h4><a name="path-Conversions-to-generic-format"><code>path</code> Conversions
+<h4><a name="path-Conversions-to-generic-format"><code>path</code> Conversions
to generic format</a> [fs.cvt.to.generic]</h4>
-<p><a href="#path-generic-format-observers">Generic format observer</a> functions
-shall return strings formatted according to the <a href="#generic-pathname-format">generic pathname format</a>
+<p><a href="#path-generic-format-observers">Generic format observer</a> functions
+shall return strings formatted according to the <a href="#generic-pathname-format">generic pathname format</a>
using <i>preferred-separator</i>. See [<a href="#Operating-system-examples">fs.os.examples</a>].</p>
<h3><a name="path-Requirements"><code>path</code> Requirements</a> [path.req]</h3>
-<p>Template parameters named <code><a name="InputIterator">InputIterator</a></code> are required meet the
+<p>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>.</p>
<p>Template parameters named <code><a name="Source">Source</a></code> are required to be one of:</p>
<ul>
<p>A container with a value type of <code>char</code>, <code>
wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.</li>
<li>
- <p>An iterator for a null terminated byte-string. The value type is required
+ <p>An iterator for a null terminated byte-string. The value type is required
to be <code>char</code>, <code>wchar_t</code>, <code>char16_t</code>, or <code>
char32_t</code>.</li>
<li>
path(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());</pre>
<blockquote>
- <p><i>Effects:</i> Stores the contents [<code>begin</code>,<code>end</code>)
- or <code>source</code> in <code>pathname</code>, converting format and
+ <p><i>Effects:</i> Stores the contents [<code>begin</code>,<code>end</code>)
+ or <code>source</code> in <code>pathname</code>, converting format and
encoding if required ([<a href="#path.arg.convert">path.arg.convert</a>]).</p>
</blockquote>
<h3> <a name="path-assignments"> <code>
path& assign(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());</pre>
<blockquote>
- <p><i>Effects:</i> Stores the contents [<code>begin</code>,<code>end</code>)
- or <code>source</code> in <code>pathname</code>, converting format and
+ <p><i>Effects:</i> Stores the contents [<code>begin</code>,<code>end</code>)
+ or <code>source</code> in <code>pathname</code>, converting format and
encoding if required ([<a href="#path.arg.convert">path.arg.convert</a>]). </p>
<p>
<i>Returns: </i><code>*this</code></p>
</blockquote>
-<h3><a name="path-appends"><code><font size="4"> path</font></code> appends</a>
+<h3><a name="path-appends"><code><font size="4"> path</font></code> appends</a>
[path.append]</h3>
<p>The append operations use <code>
operator/=</code> to denote their semantic effect of appending <i>
<blockquote>
<p><i>Effects:</i></p>
<blockquote>
- <p>Appends <code>path::preferred_separator</code> to <code>pathname</code>,
+ <p>Appends <code>path::preferred_separator</code> to <code>pathname</code>,
converting format and encoding if required ([<a href="#path.arg.convert">path.arg.convert</a>]), unless:</p>
<ul>
<li>
- <p>an added separator
+ <p>an added separator
would be redundant, or</li>
<li>
<p>would change a relative path to an absolute path, or</li>
<blockquote>
<p><i>Effects:</i></p>
<blockquote>
- <p>Appends <code>path::preferred_separator</code> to <code>pathname</code>, converting
+ <p>Appends <code>path::preferred_separator</code> to <code>pathname</code>, converting
format and encoding if required ([<a href="#path.arg.convert">path.arg.convert</a>]), unless:</p>
<ul>
<li>
- <p>an added separator
+ <p>an added separator
would be redundant, or</li>
<li>
<p>would change a relative path to an absolute path, or</li>
<li>
<p><code>*p.native().cbegin()</code> is a separator.</li>
</ul>
- <p>Appends the contents [<code>begin</code>,<code>end</code>)
- or <code>source</code> to <code>pathname</code>, converting format and
+ <p>Appends the contents [<code>begin</code>,<code>end</code>)
+ or <code>source</code> to <code>pathname</code>, converting format and
encoding if required ([<a href="#path.arg.convert">path.arg.convert</a>]).</p>
</blockquote>
<p><i>Returns: </i><code>*this</code></p>
</blockquote>
-
+
<h3><a name="path-concatenation"><code>path</code> concatenation</a> [path.concat]</h3>
<pre>path& operator+=(const path& x);
<pre>path& <a name="path-make_preferred">make_preferred</a>();</pre>
<blockquote>
- <p><i>Effects:</i> <i>directory-separator</i>s are converted to <i>preferred-separator</i>s.
+ <p><i>Effects:</i> <i>directory-separator</i>s are converted to <i>preferred-separator</i>s.
See [<a href="#Operating-system-examples">fs.os.examples</a>].</p>
<p><i>Returns:</i> <code>*this</code></p>
</blockquote>
<blockquote>
<p><i>Returns: </i>As if, <code>*this = parent_path();</code></p>
- <p>[<i>Note:</i> This function is needed to efficiently implement <code>directory_iterator</code>. It is exposed to allow additional uses. The actual
- implementation may be much more efficient than <code>*this = parent_path()</code> <i>—end
+ <p>[<i>Note:</i> This function is needed to efficiently implement <code>directory_iterator</code>. It is exposed to allow additional uses. The actual
+ implementation may be much more efficient than <code>*this = parent_path()</code> <i>—end
note</i>]</p>
</blockquote>
<p><i>Effects:</i></p>
<ul>
<li>
- <p>Any existing <code>extension()</code> is removed from the stored path,
+ <p>Any existing <code>extension()</code> is removed from the stored path,
then</li>
<li>
<p>iff
- <code>new_extension</code> is not empty and does not begin with a dot
+ <code>new_extension</code> is not empty and does not begin with a dot
character, a dot character is appended to the stored path, then</li>
<li>
<p>
<p><i>Complexity: </i>constant time.</p>
</blockquote>
- <h3><a name="path-lexical-operations"><code>path</code> lexical operations</a>
+ <h3><a name="path-lexical-operations"><code>path</code> lexical operations</a>
[path.lex.ops]</h3>
- <pre><span style="background-color: #E8FFE8">path </span><a name="lexically_normal"><span style="background-color: #E8FFE8">lexically_normal</span></a><span style="background-color: #E8FFE8">() const;</span></pre>
+ <pre>path <a name="lexically_normal">lexically_normal</a>() const;</pre>
<blockquote>
-<p><i>Overview:</i> Returns <code>*this</code> with redundant current directory
+<p><i>Overview:</i> Returns <code>*this</code> with redundant current directory
(<i>dot</i>), parent directory (<i>dot-dot</i>), and <i>directory-separator</i> elements removed.</p>
<p><i>Returns:</i> <code>*this</code> in <a href="#normal-form">normal form</a>.</p>
<p><i>Remarks:</i> Uses <code>operator/=</code> to compose the returned path.</p>
<p>[<i>Example:</i></p>
<p><code>assert(path("foo/./bar/..").lexically_normal() == "foo");<br>
assert(path("foo/.///bar/../").lexically_normal() == "foo/.");</code></p>
-<p>The above assertions will succeed.<i> </i>On Windows, the
-returned path's <i>directory-separator</i> characters will be backslashes rather than slashes, but that
+<p>The above assertions will succeed.<i> </i>On Windows, the
+returned path's <i>directory-separator</i> characters will be backslashes rather than slashes, but that
does not affect <code>path</code> equality.<i> —end example</i>]</p>
</blockquote>
-<pre><span style="background-color: #E8FFE8">path </span><a name="lexically-relative"><span style="background-color: #E8FFE8">lexically_relative</span></a><span style="background-color: #E8FFE8">(const</span><span style="background-color: #E8FFE8"> path& base) const;</span></pre>
+<pre>path <a name="lexically_relative">lexically_relative</a>(const path& base) const;</pre>
<blockquote>
- <p><i>Overview:</i> Returns <code>*this</code> made relative to <code>base</code>.
- Treats empty or identical paths as corner cases, not errors. Does not resolve
+ <p><i>Overview:</i> Returns <code>*this</code> made relative to <code>base</code>.
+ Treats empty or identical paths as corner cases, not errors. Does not resolve
symlinks. Does not first normalize <code>*this</code> or <code>base</code>.</p>
<p><i>Remarks:</i> Uses <code>std::mismatch(begin(), end(), base.begin(), base.end())</code>, to determine the first mismatched element of
- <code>*this</code> and <code>base</code>. Uses <code>operator==</code> to
+ <code>*this</code> and <code>base</code>. Uses <code>operator==</code> to
determine if elements match. </p>
-
+
<p><i>Returns:</i> </p>
-
+
<ul>
<li>
<code>path()</code> if the first mismatched element of <code>*this</code> is equal to <code>
- begin()</code> or the first mismatched element
+ begin()</code> or the first mismatched element
of <code>base</code> is equal to <code>base.begin()</code>, or<br>
</li>
<li>
<code>path(".")</code> if the first mismatched element of <code>
*this</code> is equal to <code>
- end()</code> and the first mismatched element
+ end()</code> and the first mismatched element
of <code>base</code> is equal to <code>base.end()</code>, or<br>
</li>
<li>An object of class <code>path</code> composed via application of <code>
- operator/= path("..")</code> for each element in the half-open
- range [first
- mismatched element of <code>base</code>, <code>base.end()</code>), and then
- application of <code>operator/=</code> for each element in the half-open
- range
+ operator/= path("..")</code> for each element in the half-open
+ range [first
+ mismatched element of <code>base</code>, <code>base.end()</code>), and then
+ application of <code>operator/=</code> for each element in the half-open
+ range
[first mismatched element of <code>*this</code>, <code>end()</code>).
</li>
</ul>
-
+
<p>[<i>Example:</i></p>
<p><code>assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");<br>
assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");<br>
assert(path("a/b/c").lexically_relative("a/b/c/x/y") == "../..");<br>
assert(path("a/b/c").lexically_relative("a/b/c") == ".");<br>
assert(path("a/b").lexically_relative("c/d") == "");</code></p>
-<p>The above assertions will succeed.<i> </i>On Windows, the
-returned path's <i>directory-separator</i>s will be backslashes rather than
-forward slashes, but that
+<p>The above assertions will succeed.<i> </i>On Windows, the
+returned path's <i>directory-separator</i>s will be backslashes rather than
+forward slashes, but that
does not affect <code>path</code> equality.<i> —end example</i>]</p>
-
- <p>[<i>Note:</i> If symlink following semantics are desired, use the operational function <code>
- <a href="#op-proximate">relative</a></code> <i>—end note</i>]</p>
-
- <p>[<i>Note:</i> If <a href="#lexically_normal">normalization</a> is needed to ensure
- consistent matching of elements, apply <code><a href="#lexically_normal">lexically_normal()</a></code>
+
+ <p>[<i>Note:</i> If symlink following semantics are desired, use the operational function <code>
+ <a href="#op-relative">relative</a></code> <i>—end note</i>]</p>
+
+ <p>[<i>Note:</i> If <a href="#lexically_normal">normalization</a> is needed to ensure
+ consistent matching of elements, apply <code><a href="#lexically_normal">lexically_normal()</a></code>
+ to <code>*this</code>, <code>base</code>, or both. <i>—end note</i>]</p>
+
+<pre>path <a name="lexically_proximate">lexically_proximate</a>(const path& base) const;</pre>
+<blockquote>
+<p><i>Returns:</i> If <code>lexically_relative(base)</code> returns a non-empty path, returns that path.
+Otherwise returns <code>*this</code>.</p>
+
+ <p>[<i>Note:</i> If symlink following semantics are desired, use the operational function <code>
+ <a href="#op-relative">relative</a></code> <i>—end note</i>]</p>
+
+ <p>[<i>Note:</i> If <a href="#lexically_normal">normalization</a> is needed to ensure
+ consistent matching of elements, apply <code><a href="#lexically_normal">lexically_normal()</a></code>
to <code>*this</code>, <code>base</code>, or both. <i>—end note</i>]</p>
-<h3> <a name="path-native-format-observers"><code><font size="4">path</font></code> native format observers</a>
+</blockquote>
+
+
+<h3> <a name="path-native-format-observers"><code><font size="4">path</font></code> native format observers</a>
[path.native.obs]</h3>
<p>The string returned by all native format observers is in the <a href="#native-pathname-format">native pathname format</a>.</p>
-<pre>const string_type&
<a name="native">native</a>() const noexcept;</pre>
+<pre>const string_type& <a name="native">native</a>() const noexcept;</pre>
<blockquote>
<p><i>Returns:</i> <code>pathname</code>.</p>
<p><i>Returns:</i> <code>pathname.c_str()</code>.</p>
</blockquote>
-<pre><span style="background-color: #CCFFCC">string_type::size_type </span><a name="path-size"><span style="background-color: #CCFFCC">size</span></a><span style="background-color: #CCFFCC">() const noexcept;</span></pre>
+<pre>string_type::size_type <a name="path-size">size</a>() const noexcept;</pre>
<blockquote>
<p><i>Returns:</i> <code>pathname.size()</code>.</p>
<blockquote>
<p><i>Returns:</i> <code>pathname</code>.</p>
-<p><i>Remarks:</i> If <code>string_type</code> is a different type than
+<p><i>Remarks:</i> If <code>string_type</code> is a different type than
function's return type, conversion is performed by <code>cvt</code>.</p>
</blockquote>
-<h3> <a name="path-generic-format-observers"><code><font size="4">path</font></code> generic format observers</a>
+<h3> <a name="path-generic-format-observers"><code><font size="4">path</font></code> generic format observers</a>
[path.generic.obs]</h3>
<p>The string returned by all generic format observers is in the <a href="#generic-pathname-format">generic pathname format</a>.</p>
<blockquote>
<p><i>Returns:</i> <code>pathname</code>.</p>
-<p><i>Remarks:</i> If <code>string_type</code> is a different type than
+<p><i>Remarks:</i> If <code>string_type</code> is a different type than
function's return type, conversion is performed by <code>cvt</code>.</p>
</blockquote>
<pre>int compare(const path& p) const noexcept;</pre>
<blockquote>
- <p><i>Returns:</i> A value less than 0 if the elements of <code>*this</code> are lexicographically less than the elements of <code>p</code>, otherwise a
- value greater than 0 if the elements of <code>*this</code> are
+ <p><i>Returns:</i> A value less than 0 if the elements of <code>*this</code> are lexicographically less than the elements of <code>p</code>, otherwise a
+ value greater than 0 if the elements of <code>*this</code> are
lexicographically greater than the elements of <code>p</code>, otherwise 0.</p>
- <p>Remark: The elements are determined as if by iteration over the half-open
+ <p>Remark: The elements are determined as if by iteration over the half-open
range [<code>begin()</code>, <code>end()</code>) for <code>*this</code> and <code>p</code>.</p>
</blockquote>
<blockquote>
<p><i>Returns:</i> <code>compare(path(s))</code>.</p>
</blockquote>
-<h3> <a name="path-decomposition"> <code><font size="4">path</font></code> decomposition</a>
+<h3> <a name="path-decomposition"> <code><font size="4">path</font></code> decomposition</a>
[path.decompose]</h3>
-<p><span style="background-color: #E0E0E0"><i>See the <a href="#path-decomposition-table">Path decomposition table</a> for examples
-for values returned by decomposition functions. The <a href="tutorial.html#Using-path-decomposition">Tutorial</a> may also be
+<p><span style="background-color: #E0E0E0"><i>See the <a href="#path-decomposition-table">Path decomposition table</a> for examples
+for values returned by decomposition functions. The <a href="tutorial.html#Using-path-decomposition">Tutorial</a> may also be
helpful.</i></span></p>
<pre>path <a name="path-root_name">root_name</a>() const;</pre>
<blockquote>
<p><i>Returns:</i> <i>root-directory</i>, if <code>pathname</code> includes <i>root-directory</i>, otherwise <code>path()</code>.</p>
-<p>If <i>root-directory</i> is composed of <i>slash name</i>, <i>slash</i> is
+<p>If <i>root-directory</i> is composed of <i>slash name</i>, <i>slash</i> is
excluded from the returned string.</p>
</blockquote>
<pre>path <a name="path-relative_path">relative_path</a>() const;</pre>
<blockquote>
-<p><i>Returns:</i> A <code>path</code> composed from <code>pathname</code>, if <code>!empty()</code>, beginning
+<p><i>Returns:</i> A <code>path</code> composed from <code>pathname</code>, if <code>!empty()</code>, beginning
with the first <i>filename</i> after <i>root-path</i>. Otherwise, <code>path()</code>.</p>
</blockquote>
<pre>path <a name="path-parent_path">parent_path</a>() const;</pre>
<blockquote>
- <p><i>Returns:</i> <code>(empty() || begin() == —end()) ? path() : <i>pp</i></code>, where <code><i>pp</i></code> is constructed as if by
+ <p><i>Returns:</i> <code>(empty() || begin() == —end()) ? path() : <i>pp</i></code>, where <code><i>pp</i></code> is constructed as if by
starting with an empty <code>path</code> and successively applying <code>operator/=</code> for each element in the range <code>begin()</code>, <code>—end()</code>.</p>
<p>[<i>Example:</i></p>
<blockquote>
-
+
<pre>std::cout << path("/foo/bar.txt").parent_path(); // outputs "/foo"
std::cout << path("/foo/bar").parent_path(); // outputs "/foo"
std::cout << path("/foo/bar/").parent_path(); // outputs "/foo/bar"
std::cout << path("/").parent_path(); // outputs ""
std::cout << path(".").parent_path(); // outputs ""
std::cout << path("..").parent_path(); // outputs ""</pre>
-
+
</blockquote>
<p> See the last bullet item in the <a href="#path-iterators">
- forward traversal order</a> list for why the <code>"/foo/bar/"</code> example
+ forward traversal order</a> list for why the <code>"/foo/bar/"</code> example
doesn't output <code>"/foo"</code>.</p>
<p> <i>—end example</i>]</p>
</blockquote>
<p><i>Returns:</i> <code>empty() ? path() : *—end()</code></p>
<p>[<i>Example:</i></p>
<blockquote>
-
+
<pre>std::cout << path("/foo/bar.txt").filename(); // outputs "bar.txt"
std::cout << path("/foo/bar").filename(); // outputs "bar"
std::cout << path("/foo/bar/").filename(); // outputs "."
std::cout << path("/").filename(); // outputs "/"
std::cout << path(".").filename(); // outputs "."
std::cout << path("..").filename(); // outputs ".."</pre>
-
+
</blockquote>
<p> See the last bullet item in the <a href="#path-iterators">
- forward traversal order</a> list for why the <code>"/foo/bar/"</code> example
+ forward traversal order</a> list for why the <code>"/foo/bar/"</code> example
doesn't output <code>"bar"</code>.</p>
<p> <i>—end example</i>]</p>
</blockquote>
<pre>path <a name="path-stem">stem</a>() const;</pre>
<blockquote>
- <p><i>Returns:</i> 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,
+ <p><i>Returns:</i> 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,
returns <code>p.filename()</code>.</p>
<p>[<i>Example:</i></p>
<blockquote>
-
+
<pre><code>std::cout << path("/foo/bar.txt").stem();</code> // outputs "<code>bar</code>"
path p = "foo.bar.baz.tar";
for (; !p.extension().empty(); p = p.stem())
// outputs: .tar
// .baz
// .bar</pre>
-
+
</blockquote>
<p> <i>—end example</i>]</p>
</blockquote>
<pre>path <a name="path-extension">extension</a>() const;</pre>
<blockquote>
- <p><i>Returns:</i> 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 the rightmost dot
+ <p><i>Returns:</i> 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 the rightmost dot
and ending at the path's end. Otherwise, returns an empty <code>path</code> object. </p>
- <p><i>Remarks:</i> Implementations are permitted but not required to define additional
- behavior for file systems which append additional elements to extensions, such
+ <p><i>Remarks:</i> Implementations are permitted but not required to define additional
+ behavior for file systems which append additional elements to extensions, such
as alternate data streams or partitioned dataset names.</p>
<p>[<i>Example:</i></p>
<blockquote>
-
+
<pre><code>std::cout << path("/foo/bar.txt").extension(); //</code> outputs "<code>.txt</code>"</pre>
-
+
</blockquote>
<p> <i>—end example</i>]</p>
- <p>[<i>Note:<b> </b></i>The dot is included in the return value so that it is
+ <p>[<i>Note:<b> </b></i>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
+ http://permalink.gmane.org/gmane.comp.lib.boost.devel/199744</a> for more
extensive rationale. <i>—end note</i>]</p>
</blockquote>
<h3> <a name="path-query"> <code><font size="4">path</font></code> query</a> [path.query]</h3>
<p><i>Returns:</i> <code>m_pathname.empty()</code>.</p>
</blockquote>
-<pre><span style="background-color: #CCFFCC">bool </span><a name="filename_is_dot"><span style="background-color: #CCFFCC">filename_is_dot</span></a><span style="background-color: #CCFFCC">() const;</span></pre>
+<pre>bool <a name="filename_is_dot">filename_is_dot</a>() const;</pre>
<blockquote>
<p><i>Returns:</i> <code>filename() == path(".")</code></p>
<p>[<i>Example:</i></p>
<blockquote>
-
+
<pre>std::cout << path(".").filename_is_dot(); // outputs 1
std::cout << path("/.").filename_is_dot(); // outputs 1
std::cout << path("foo/.").filename_is_dot(); // outputs 1
std::cout << path("/foo").filename_is_dot(); // outputs 0
std::cout << path("/foo.").filename_is_dot(); // outputs 0
std::cout << path("..").filename_is_dot(); // outputs 0</pre>
-
+
</blockquote>
- <p> See the last bullet item in the <a href="#path-iterators">forward traversal order</a>
+ <p> See the last bullet item in the <a href="#path-iterators">forward traversal order</a>
list for why <code>path("foo/").filename()</code> is a dot filename.</p>
<p> <i>—end example</i>]</p>
</blockquote>
-<pre><span style="background-color: #CCFFCC">bool </span><span style="background-color: #CCFFCC"><a name="filename_is_dot_dot">filename_is_dot_dot</a>() const;</span></pre>
+<pre>bool <a name="filename_is_dot_dot">filename_is_dot_dot</a>() const;</pre>
<blockquote>
<p><i>Returns:</i> <code>filename() == path("..")</code></p>
<font size="4">path</font></code> iterators</a> [path.itr]</h3>
<p> Path iterators <code>iterator</code>, <code>const_iterator</code>,
<code>reverse_iterator</code>, and <code>const_reverse_iterator</code> iterate over the elements of the stored pathname.</p>
-<p> Path iterators are constant iterators satisfying
-the requirements of a bidirectional iterator (C++ Std, 24.1.4 Bidirectional
-iterators [lib.bidirectional.iterators]). The <code>value_type</code> of
+<p> Path iterators are constant iterators satisfying
+the requirements of a bidirectional iterator (C++ Std, 24.1.4 Bidirectional
+iterators [lib.bidirectional.iterators]). The <code>value_type</code> of
an iterator is <code>path</code>.</p>
<blockquote>
-<p> [<i>Note:</i> Path iterators store their value objects internally
-and when dereferenced return references to those internal objects. They cannot
-be used with iterator adaptors such as <code>std::reverse_iterator</code> that
-assume references obtained by dereferencing an iterator point to objects that
+<p> [<i>Note:</i> Path iterators store their value objects internally
+and when dereferenced return references to those internal objects. They cannot
+be used with iterator adaptors such as <code>std::reverse_iterator</code> that
+assume references obtained by dereferencing an iterator point to objects that
out-live the iterator itself. <i>—end note</i>] </p>
</blockquote>
- <p>Calling any non-const member function of a <code>path</code> object
+ <p>Calling any non-const member function of a <code>path</code> object
invalidates all iterators referring to elements of that object.</p>
<p> The forward traversal order is as follows:</p>
<ul>
<li>The <i>root-name</i> element, if present.</li>
<li>The <i>root-directory</i> element, if present, in the generic format. <i>
- [note:</i> the generic format is required to ensure lexicographical
+ [note:</i> the generic format is required to ensure lexicographical
comparison works correctly. <i>—end note</i>]</li>
<li>Each successive <i>filename</i> element, if present.</li>
- <li><i>Dot</i>, if one or more trailing non-root <i>slash</i>
+ <li><i>Dot</i>, if one or more trailing non-root <i>slash</i>
characters are present.|</li>
</ul>
<blockquote>
- <p>[<i>Note:</i> Treating the last element during iteration as <i>dot</i> when
- there is a trailing directory separator enables lexical (i.e. syntactic)
- distinction between paths to directories versus paths to regular files. Such a
- distinction is usually irrelevant on POSIX and Windows based operating
+ <p>[<i>Note:</i> Treating the last element during iteration as <i>dot</i> when
+ there is a trailing directory separator enables lexical (i.e. syntactic)
+ distinction between paths to directories versus paths to regular files. Such a
+ distinction is usually irrelevant on POSIX and Windows based operating
systems, but may be a requirement on other operating systems. <i>—end note</i>]</p>
</blockquote>
<p>The backward traversal order is the reverse of forward traversal.</p>
<pre>iterator begin() const;</pre>
<blockquote>
- <p><i>Returns:</i> An iterator for the first element in forward traversal
+ <p><i>Returns:</i> An iterator for the first element in forward traversal
order. If no elements are present, the end iterator.</p>
</blockquote>
<pre>iterator end() const;</pre>
</blockquote>
<pre>reverse_iterator rbegin() const;</pre>
<blockquote>
- <p><i>Returns:</i> An iterator for the first element in backward traversal
+ <p><i>Returns:</i> An iterator for the first element in backward traversal
order. If no elements are present, the end iterator.</p>
</blockquote>
<pre>reverse_iterator rend() const;</pre>
<blockquote>
<p><i>Returns:</i> The end iterator.</p>
</blockquote>
- <h3><a name="path-imbued-locale"><code><font size="4"> path</font></code>
+ <h3><a name="path-imbued-locale"><code><font size="4"> path</font></code>
imbued locale</a> [path.imbued.locale]</h3>
<p><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
+ <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.</p>
<blockquote>
- <p><span style="background-color: #FFFF00">[</span><i><span style="background-color: #FFFF00">Example:</span></i><span style="background-color: #FFFF00">
+ <p><span style="background-color: #FFFF00">[</span><i><span style="background-color: #FFFF00">Example:</span></i><span style="background-color: #FFFF00">
... </span><i><span style="background-color: #FFFF00">—end example</span></i><span style="background-color: #FFFF00">]</span></p>
</blockquote>
<pre>static std::locale <a name="path-imbue">imbue</a>(const std::locale& loc);</pre>
<blockquote>
- <p><i>Effects:</i> Stores a copy of <code>loc</code> as the imbued <code>path</code>
+ <p><i>Effects:</i> Stores a copy of <code>loc</code> as the imbued <code>path</code>
locale.</p>
<p><i>Returns:</i> The previous imbued <code>path</code> locale.</p>
- <p><i>Remarks:</i> 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
+ <p><i>Remarks:</i> 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 ([<a href="#Operating-system-examples">fs.os.examples</a>]). </p>
</blockquote>
<pre>static const codecvt_type& <a name="path-codecvt">codecvt</a>();</pre>
<blockquote>
- <p><i>Returns:</i> The <code>codecvt</code> facet for the imbued<code> path</code>
+ <p><i>Returns:</i> The <code>codecvt</code> facet for the imbued<code> path</code>
locale .</p>
</blockquote>
<h3> <a name="path-deprecated-functions"><code><font size="4"> path</font></code> deprecated functions</a></h3>
-<p> Several member functions from previous versions of <code>class path</code> have been deprecated, either because they have been renamed or because the
+<p> Several member functions from previous versions of <code>class path</code> have been deprecated, either because they have been renamed or because the
functionality is no longer desirable or has become obsolete.</p>
<p> Deprecated functions available by default; will be suppressed if <code>BOOST_FILESYSTEM_NO_DEPRECATED</code> is defined:</p>
<blockquote>
const string_type external_directory_string() const { return native(); }</pre>
</blockquote>
-<h3> <a name="path-non-member-functions"> <code><font size="4">path</font></code> non-member functions</a>
+<h3> <a name="path-non-member-functions"> <code><font size="4">path</font></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>
<blockquote>
- <p><i>Returns:</i> <code>true</code> if the sequence of <code>native()</code> strings for the elements defined by the half-open range <code>[first1,last1)</code> is
- lexicographically less than the sequence of <code>native()</code> strings for
+ <p><i>Returns:</i> <code>true</code> if the sequence of <code>native()</code> strings for the elements defined by the half-open range <code>[first1,last1)</code> is
+ lexicographically less than the sequence of <code>native()</code> strings for
the elements defined by the half-open range <code>[first2,last2)</code>. Returns <code>false</code> otherwise.</p>
- <p><i>Remarks:</i> If two sequences have the same number of elements and their
- corresponding elements are equivalent, then neither sequence is
- lexicographically less than the other. If one sequence is a prefix of the
- other, then the shorter sequence is lexicographically less than the longer
- sequence. Otherwise, the lexicographical comparison of the sequences yields
- the same result as the comparison of the first corresponding pair of elements
+ <p><i>Remarks:</i> If two sequences have the same number of elements and their
+ corresponding elements are equivalent, then neither sequence is
+ lexicographically less than the other. If one sequence is a prefix of the
+ other, then the shorter sequence is lexicographically less than the longer
+ sequence. Otherwise, the lexicographical comparison of the sequences yields
+ the same result as the comparison of the first corresponding pair of elements
that are not equivalent.</p>
<p>[<i>Note:</i> A <code>path</code> aware <code>lexicographical_compare</code> algorithm is provided for historical reasons. <i>—end note</i>]</p>
</blockquote>
<div>
- <pre><span style="background-color: #CCFFCC">path lexically_</span><a name="lex-normal"><span style="background-color: #CCFFCC">normal</span></a><span style="background-color: #CCFFCC">(const path& p);</span></pre>
+ <pre>path <a name="lex-normal">lexically_normal</a>(const path& p);</pre>
</div>
<blockquote>
- <p><i>Overview:</i> Returns <code>p</code> with redundant current
+ <p><i>Overview:</i> Returns <code>p</code> with redundant current
directory (<i>dot</i>), parent directory (<i>dot-dot</i>), and <i>
directory-separator</i> elements removed.</p>
<p><i>Returns:</i> <code>p</code> in
<a href="#normal-form">
normal form</a>.</p>
- <p><i>Remarks:</i> Uses <code>operator/=</code> to compose the
+ <p><i>Remarks:</i> Uses <code>operator/=</code> to compose the
returned path.</p>
<p>[<i>Example:</i></p>
<p><code>assert(lexically_normal("foo/./bar/..") == "foo");<br>
assert(lexically_normal("foo/.///bar/../") == "foo/.");</code></p>
- <p>All of the above assertions will succeed.<i> </i>On Windows, the
- returned path's <i>directory-separator</i> characters will be backslashes
- rather than slashes, but that does not affect <code>path</code> equality.<i>
+ <p>All of the above assertions will succeed.<i> </i>On Windows, the
+ returned path's <i>directory-separator</i> characters will be backslashes
+ rather than slashes, but that does not affect <code>path</code> equality.<i>
—end example</i>]</p>
</blockquote>
<blockquote>
<p><i>Overview:</i> Returns <code>p</code> made relative to <code>
- base</code>. Treats empty or identical paths as corner cases, not errors. Does
+ base</code>. Treats empty or identical paths as corner cases, not errors. Does
not resolve symlinks. Does not first normalize <code>p</code> or <code>base</code>.</p>
- <p><i>Remarks:</i> Uses <code>std::mismatch(p.begin(), p.end(),
+ <p><i>Remarks:</i> Uses <code>std::mismatch(p.begin(), p.end(),
base.begin(), base.end())</code>, to determine the first mismatched element of
- <code>p</code> and <code>base</code>. Uses <code>operator==</code> to
+ <code>p</code> and <code>base</code>. Uses <code>operator==</code> to
determine if elements match. </p>
<p><i>Returns:</i> </p>
<ul>
<li>
- <p><code>path()</code> if the first mismatched element of <code>p</code>
+ <p><code>path()</code> if the first mismatched element of <code>p</code>
is equal to <code>p.begin()</code> or the first mismatched element of <code>
base</code> is equal to <code>base.begin()</code>, or<br>
</li>
<li>
<p><code>path(".")</code> if the first mismatched element of <code>
- p</code> is equal to <code>p.end()</code> and the first mismatched element
+ p</code> is equal to <code>p.end()</code> and the first mismatched element
of <code>base</code> is equal to <code>base.end()</code>, or<br>
</li>
<li>
- <p>An object of class <code>path</code> composed via application
- of <code>operator/= path("..")</code> for each element in the half-open
- range [first mismatched element of <code>base</code>, <code>base.end()</code>),
- and then application of <code>operator/=</code> for each element in the
+ <p>An object of class <code>path</code> composed via application
+ of <code>operator/= path("..")</code> for each element in the half-open
+ range [first mismatched element of <code>base</code>, <code>base.end()</code>),
+ and then application of <code>operator/=</code> for each element in the
half-open range [first mismatched element of <code>p</code>, <code>p.end()</code>).
</li>
</ul>
assert(lexically_relative("a/b/c", "a/b/c/x/y") == "../..");<br>
assert(lexically_relative("a/b/c", "a/b/c") == ".");<br>
assert(lexically_relative("a/b", "c/d") == "");</code></p>
- <p>All of the above assertions will succeed.<i> </i>On Windows, the
- returned path's <i>directory-separator</i>s will be backslashes rather than
- forward slashes, but that does not affect <code>path</code> equality.<i> —end
+ <p>All of the above assertions will succeed.<i> </i>On Windows, the
+ returned path's <i>directory-separator</i>s will be backslashes rather than
+ forward slashes, but that does not affect <code>path</code> equality.<i> —end
example</i>]</p>
- <p>[<i>Note:</i> If symlink following semantics are desired, use the
+ <p>[<i>Note:</i> If symlink following semantics are desired, use the
operational function <code>
<a href="#op-relative">
relative</a></code> <i>—end note</i>]</p>
<pre>bool operator==(const path& lhs, const path& rhs);</pre>
<blockquote>
<p><i>Returns:</i> <code>!(lhs < rhs) && !(rhs < lhs)</code>.</p>
- <p>[<i>Note:</i> <a name="Path-equality">Path equality</a> and path
+ <p>[<i>Note:</i> <a name="Path-equality">Path equality</a> and path
equivalence have different semantics.</p>
- <p>Equality is determined by the <code>path</code> non-member <code>operator==</code>, which considers the two path's lexical
+ <p>Equality is determined by the <code>path</code> non-member <code>operator==</code>, which considers the two path's lexical
representations only. Thus <code>path("foo") == "bar"</code> is never <code>true</code>.</p>
- <p>Equivalence is determined by the <a href="#equivalent"><code>equivalent()</code></a> non-member function, which determines if two paths <a href="#path">resolve</a> to the same file system entity.
+ <p>Equivalence is determined by the <a href="#equivalent"><code>equivalent()</code></a> non-member function, which determines if two paths <a href="#path">resolve</a> to the same file system entity.
Thus <code>equivalent("foo", "bar")</code> will be <code>true</code> when both paths resolve to the same file.</p>
- <p>Programmers wishing to determine if two paths are "the same" must decide if
- "the same" means "the same representation" or "resolve to the same actual
+ <p>Programmers wishing to determine if two paths are "the same" must decide if
+ "the same" means "the same representation" or "resolve to the same actual
file", and choose the appropriate function accordingly. <i>—end note</i>]</p>
</blockquote>
<pre>bool operator!=(const path& lhs, const path& rhs);</pre>
<blockquote>
<p><i>Returns:</i> <code>path(lhs) /= rhs</code>.</p>
</blockquote>
-<h3> <a name="path-non-member-operators"><code><font size="4">path</font></code></a><a name="path-inserter-extractor"> inserter
+<h3> <a name="path-non-member-operators"><code><font size="4">path</font></code></a><a name="path-inserter-extractor"> inserter
and extractor</a> [path.io]</h3>
-<p> The inserter and extractor delimit the string with double-quotes (<code>"</code>)
-so that paths with embedded spaces will round trip correctly. Ampersand (<code>&</code>)
+<p> The inserter and extractor delimit the string with double-quotes (<code>"</code>)
+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.</p>
<pre>template <class Char, class Traits>
std::basic_ostream<Char, Traits>& operator<<(std::basic_ostream<Char, Traits>& os,
<p>A double-quote.</p>
</li>
<li>
- <p>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
+ <p>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.</p>
</li>
<li>
p = str;</code></p>
<p><i>Effects: </i>Extract characters from os:</p>
<ul>
- <li>If the first character that would be extracted is equal to double-quote,
+ <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,
+ 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>
<p><i>Returns:</i> <code>is</code></p>
</blockquote>
-<h2><a name="Class-filesystem_error">Class <code>filesystem_error</code>
+<h2><a name="Class-filesystem_error">Class <code>filesystem_error</code>
[class.filesystem_error]</a></h2>
<pre>namespace boost
{
};
} // namespace filesystem
} // namespace boost</pre>
-<p>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
+<p>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.</p>
-<h3> <a name="filesystem_error-members"> <code>filesystem_error</code> members</a>
+<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>
</blockquote>
<pre>const path& <a name="filesystem_error-path1">path1</a>() const;</pre>
<blockquote>
- <p><i>Returns:</i> Reference to copy of <code>p1</code> stored by the
+ <p><i>Returns:</i> Reference to copy of <code>p1</code> stored by the
constructor, or, if none, an empty path.</p>
</blockquote>
<pre>const path& <a name="filesystem_error-path2">path2</a>() const;</pre>
<blockquote>
- <p><i>Returns:</i> Reference to copy of <code>p2</code> stored by the
+ <p><i>Returns:</i> Reference to copy of <code>p2</code> stored by the
constructor, or, if none, an empty path.</p>
</blockquote>
<pre>const char* <a name="filesystem_error-what">what</a>() const;</pre>
<blockquote>
- <p><i>Returns: </i>A string containing <code>runtime_error::what()</code>. The exact format is unspecified.
- Implementations are encouraged but not required to include <code>path1.native_string()</code>if not empty, <code>path2.native_string()</code>if
- not empty, and <code>system_error::what()</code> strings in the returned
+ <p><i>Returns: </i>A string containing <code>runtime_error::what()</code>. The exact format is unspecified.
+ Implementations are encouraged but not required to include <code>path1.native_string()</code>if not empty, <code>path2.native_string()</code>if
+ not empty, and <code>system_error::what()</code> strings in the returned
string.</p>
</blockquote>
<h2><a name="Enum-file_type">Enum file_type</a> [enum.file_type]</h2>
</tr>
<tr>
<td><code>status_error</code></td>
- <td>An error occurred while trying to obtain the status of the file. The
+ <td>An error occurred while trying to obtain the status of the file. The
file simply not being found is <b><u>not</u></b> considered a status error. </td>
</tr>
<tr>
</tr>
<tr>
<td><code>type_unknown</code></td>
- <td>The file exists, but it is of a system specific type not covered by any
+ <td>The file exists, but it is of a system specific type not covered by any
of the above cases.</td>
</tr>
</table>
<h2><a name="Enum-perms">Enum perms</a> [enum.perms]</h2>
-<p>This <code>enum</code> specifies bitmask constants uses to identify file
-permissions. <i><span style="background-color: #E0E0E0">ISO/</span><span style="background-color: #E0E0E0">IEC</span><span style="background-color: #E0E0E0"> 9945
-(POSIX) specifies actual values, and those values have been adopted here because
-they are very familiar and ingrained for many POSIX
+<p>This <code>enum</code> specifies bitmask constants uses to identify file
+permissions. <i><span style="background-color: #E0E0E0">ISO/</span><span style="background-color: #E0E0E0">IEC</span><span style="background-color: #E0E0E0"> 9945
+(POSIX) specifies actual values, and those values have been adopted here because
+they are very familiar and ingrained for many POSIX
users.</span></i></p>
<blockquote>
-<p><span style="background-color: #FFFF00">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,
+<p><span style="background-color: #FFFF00">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. </span> </p>
</blockquote>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<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> Operating system dependent. Inherently non-portable, even between ISO/IEC 9945
+ <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>
</tr>
-<tr><td><code>perms_not_known</code></td><td><code>0xFFFF</code></td><td></td><td>
- The permissions are not known, such as when a <code>file_status</code> object
+<tr><td><code>perms_not_known</code></td><td><code>0xFFFF</code></td><td></td><td>
+ The permissions are not known, such as when a <code>file_status</code> object
is created without specifying the permissions</td>
</tr>
<tr><td>
<p><code>add_perms</code></td><td><code>0x1000</code></td><td></td><td>
- <p><code>permissions()</code> adds the argument permission bits to the
+ <p><code>permissions()</code> adds the argument permission bits to the
file's current bits</td>
</tr>
<tr><td><code>remove_perms</code></td><td><code>0x2000</code></td><td></td><td>
- <code>permissions()</code> removes the argument permission bits from the
+ <code>permissions()</code> removes the argument permission bits from the
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>
<span style="background-color: #FFFF00">On ISO/</span><span style="background-color: #FFFF00">IEC</span><span style="background-color: #FFFF00"> 9945
</span> <code><span style="background-color: #FFFF00">permissions()</span></code><span style="background-color: #FFFF00"> resolves symlinks unless
- </span> <code><span style="background-color: #FFFF00">symlink_perms</span></code><span style="background-color: #FFFF00"> is specified.
+ </span> <code><span style="background-color: #FFFF00">symlink_perms</span></code><span style="background-color: #FFFF00"> is specified.
Meaningless on Windows as </span> <code>
- <span style="background-color: #FFFF00">permissions()</span></code><span style="background-color: #FFFF00"> never resolves symlinks.
+ <span style="background-color: #FFFF00">permissions()</span></code><span style="background-color: #FFFF00"> never resolves symlinks.
Meaningless on Mac OS X and some other BSD systems as </span> <code>
<span style="background-color: #FFFF00">permissions()</span></code><span style="background-color: #FFFF00"> always resolves symlinks. Get over it.</span></td>
</tr>
};
} // namespace filesystem
} // namespace boost</pre>
-<p>An object of type <code>file_status</code> stores information about the type
+<p>An object of type <code>file_status</code> stores information about the type
and permissions of a file.</p>
-<h3><a name="file_status-constructors"><code>file_status</code> constructors</a>
+<h3><a name="file_status-constructors"><code>file_status</code> constructors</a>
[file_status.cons]</h3>
<pre>explicit file_status() noexcept;</pre>
<blockquote>
directory_entry(const directory_entry&);
explicit directory_entry(const path& p, file_status st=file_status(),
file_status symlink_st=file_status());
- ~directory_entry();
+ ~directory_entry();
// <a href="#directory_entry-modifiers">modifiers</a>
directory_entry& operator=(const directory_entry&);
file_status symlink_status(system::error_code& ec) const;
bool operator< (const directory_entry& rhs);
- bool operator==(const directory_entry& rhs);
- bool operator!=(const directory_entry& rhs);
+ bool operator==(const directory_entry& rhs);
+ bool operator!=(const directory_entry& rhs);
bool operator< (const directory_entry& rhs);
bool operator<=(const directory_entry& rhs);
bool operator> (const directory_entry& rhs);
} // namespace filesystem
} // namespace boost</pre>
-<p>A <code>directory_entry</code> object stores a <code>path object</code>,
+<p>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.</p>
<blockquote>
-<p>[<i>Note:</i> 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
+<p>[<i>Note:</i> 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. <i>—end note</i>]</p>
-<p><span style="background-color: #E0E0E0"><i>Actual cold-boot timing of iteration over
-a directory with 15,047 entries was six seconds for non-cached status queries
-versus one second for cached status queries. Windows XP, 3.0 GHz processor, with
-a moderately fast hard-drive. Similar speedups are expected on Linux and BSD-derived
+<p><span style="background-color: #E0E0E0"><i>Actual cold-boot timing of iteration over
+a directory with 15,047 entries was six seconds for non-cached status queries
+versus one second for cached status queries. Windows XP, 3.0 GHz processor, with
+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.</i></span></p>
</blockquote>
-<h3> <a name="directory_entry-constructors"> <code>directory_entry </code>constructors</a>
+<h3> <a name="directory_entry-constructors"> <code>directory_entry </code>constructors</a>
[directory_entry.cons]</h3>
<pre>directory_entry();</pre>
<blockquote>
</tr>
</table>
</blockquote>
-<h3> <a name="directory_entry-modifiers"> <code>directory_entry </code>modifiers</a>
+<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>
</tr>
</table>
</blockquote>
-<h3> <a name="directory_entry-observers"> <code>directory_entry</code> observers</a>
+<h3> <a name="directory_entry-observers"> <code>directory_entry</code> observers</a>
[directory_entry.obs]</h3>
<pre>const path& path() const;</pre>
<blockquote>
}</pre>
</blockquote>
<p><i>Returns:</i> <code>m_status</code></p>
-
+
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
-
+
</blockquote>
<pre>file_status symlink_status() const;
file_status symlink_status(system::error_code& ec) const;</pre>
}</pre>
</blockquote>
<p><i>Returns:</i> <code>m_symlink_status</code></p>
-
+
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
-
+
</blockquote>
<pre>bool operator==(const directory_entry& rhs);</pre>
<blockquote>
<blockquote>
<p><i>Returns:</i> <code>m_path >= rhs.m_path</code>.</p>
</blockquote>
-<h2><a name="Class-directory_iterator">Class <code>directory_iterator</code>
+<h2><a name="Class-directory_iterator">Class <code>directory_iterator</code>
[class.directory_iterator]</a></h2>
-<p>Objects of type <code>directory_iterator</code> provide standard library
+<p>Objects of type <code>directory_iterator</code> provide standard library
compliant iteration over the contents of a directory. Also see class <code><a href="#Class-recursive_directory_iterator">recursive_directory_iterator</a></code>.</p>
<pre>namespace boost
{
directory_iterator() noexcept; // creates the "end" iterator
directory_iterator(const directory_iterator&);
- explicit directory_iterator(const path& p);
+ explicit directory_iterator(const path& p, <a href="#directory_options">directory_options</a> opts = directory_options::none);
directory_iterator(const path& p, system::error_code& ec);
+ directory_iterator(const path& p, <a href="#directory_options">directory_options</a> opts, system::error_code& ec);
~directory_iterator();
directory_iterator& operator=(const directory_iterator&);
} // namespace filesystem
} // namespace boost</pre>
-<p> <code>directory_iterator</code> satisfies the requirements of an
+<p> <code>directory_iterator</code> satisfies the requirements of an
input iterator (C++ Std, 24.2.1, Input iterators [input.iterators]).</p>
-<p>A <code>directory_iterator</code> reads successive elements from the directory for
-which it was constructed, as if by calling ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/readdir_r.html">readdir_r()</a></code>. After a <code>directory_iterator</code> is constructed, and every time <code>operator++</code> is called,
+<p>A <code>directory_iterator</code> reads successive elements from the directory for
+which it was constructed, as if by calling ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/readdir_r.html">readdir() or readdir_r()</a></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 an object of type <code><a href="#Class-directory_entry">directory_entry</a></code>. <code>operator++</code> is not equality preserving; that is, <code>i == j</code> does not imply that <code>++i == ++j</code>. </p>
<blockquote>
-<p>[<i>Note:</i> The practical consequence of not preserving equality is that directory iterators
+<p>[<i>Note:</i> The practical consequence of not preserving equality is that directory iterators
can only be used for single-pass algorithms. <i>—end note</i>]</p>
</blockquote>
-<p>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
+<p>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. </p>
-<p>Two end iterators are always equal. An end iterator shall not be equal to a non-end
+<p>Two end iterators are always equal. An end iterator shall not be equal to a non-end
iterator.</p>
<blockquote>
-<p><i><span style="background-color: #E0E0E0">The above wording is based on the
+<p><i><span style="background-color: #E0E0E0">The above wording is based on the
Standard Library's istream_iterator wording.</span></i></p>
</blockquote>
-<p>The result of calling the <code>path()</code> member of the <code>directory_entry</code> object obtained by dereferencing a <code>directory_iterator</code> is a reference to a <code>path</code> object composed of the directory argument from which the iterator was
+<p>The result of calling the <code>path()</code> member of the <code>directory_entry</code> object obtained by dereferencing a <code>directory_iterator</code> is a reference to a <code>path</code> object composed of the directory argument from which the iterator was
constructed with filename of the directory entry appended as if by <code>operator/=</code>. </p>
-<p>Directory iteration shall not yield directory entries for the current (<i>dot</i>)
+<p>Directory iteration shall not yield directory entries for the current (<i>dot</i>)
and parent (<i>dot dot</i>) directories.</p>
-<p>The order of directory entries obtained by dereferencing successive
+<p>The order of directory entries obtained by dereferencing successive
increments of a <code>directory_iterator</code> is unspecified.</p>
<blockquote>
-<p>[<i>Note:</i> Programs performing directory iteration may wish to test if the
-path obtained by dereferencing a directory iterator actually exists. It could be
+<p>[<i>Note:</i> Programs performing directory iteration may wish to test if the
+path obtained by dereferencing a directory iterator actually exists. It could be
a
-symbolic link to a non-existent file. Programs recursively
-walking directory trees for purposes of removing and renaming entries may wish
+symbolic link to a non-existent file. Programs recursively
+walking directory trees for purposes of removing and renaming entries may wish
to avoid following symbolic links.</p>
-<p>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
+<p>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><a href="http://www.opengroup.org/onlinepubs/000095399/functions/readdir_r.html">readdir_r()</a></code>. <i>—end note</i>]</p>
</blockquote>
-<h3><a name="directory_iterator-members"><code>directory_iterator</code> members</a>
+<h3><a name="directory_iterator-members"><code>directory_iterator</code> members</a>
[directory_iterator.members]</h3>
-<p><code><a name="directory_iterator-default-ctor">directory_iterator</a>()
+<p><code><a name="directory_iterator-default-ctor">directory_iterator</a>()
noexcept;</code></p>
<blockquote>
</blockquote>
-<pre><code>explicit <a name="directory_iterator-ctor-path">directory_iterator</a>(</code>const path& p<code>);
-directory_iterator(</code>const path& p, system::error_code& ec<code>);</code></pre>
+<pre><code>explicit <a name="directory_iterator-ctor-path">directory_iterator</a>(</code>const path& p, <a href="#directory_options">directory_options</a> opts = directory_options::none<code>);
+directory_iterator(</code>const path& p, system::error_code& ec<code>);
+directory_iterator(</code>const path& p, <a href="#directory_options">directory_options</a> opts, system::error_code& ec<code>);</code></pre>
<blockquote>
-<p><i>Effects:</i> Constructs an iterator representing the first
-entry in the directory <code>p</code> resolves to, if any; otherwise, the end iterator.</p>
+<p><i>Effects:</i> Constructs an iterator representing the first
+entry in the directory <code>p</code> resolves to, if any; otherwise, the end iterator.
+If opening the directory fails with a <code>permission_denied</code> error and <code>(opts & directory_options::skip_permission_denied) != 0</code>,
+constructs the end iterator and ignores the error (the operation completes successfully). If <code>opts</code> is not specified, it is assumed to be <code>directory_options::none</code>.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
directory_iterator& increment(system::error_code& ec);</pre>
<blockquote>
-<p><i>Effects:</i> As specified by the C++ Standard, 24.1.1 Input iterators [input.iterators]</p>
+<p><i>Effects:</i> As specified by the C++ Standard, 24.1.1 Input iterators [input.iterators]. In case of error the iterator is left in the end state.</p>
<p><i>Returns:</i> <code>*this</code>.</p>
<blockquote>
<p><i>Returns: </i><code>directory_iterator()</code>.</p>
</blockquote>
-<h2><a name="Class-recursive_directory_iterator">Class <code>recursive_directory_iterator</code>
+<h2><a name="Class-recursive_directory_iterator">Class <code>recursive_directory_iterator</code>
[class.rec.dir.itr]</a></h2>
-<p>Objects of type <code>recursive_directory_iterator</code> provide standard library
-compliant iteration over the contents of a directory, including recursion into
+<p>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.</p>
<pre>namespace boost
{
recursive_directory_iterator() noexcept;
recursive_directory_iterator(const recursive_directory_iterator&);
explicit recursive_directory_iterator(const path& p,
- <a href="#symlink_option">symlink_option</a> opt = symlink_option::none);
+ <a href="#directory_options">directory_options</a> opts = directory_options::none);
recursive_directory_iterator(const path& p,
- <a href="#symlink_option">symlink_option</a> opt, system::error_code& ec);
+ <a href="#directory_options">directory_options</a> opts, system::error_code& ec);
+ // deprecated constructors, use overloads accepting directory_options instead
+ explicit recursive_directory_iterator(const path& p,
+ <a href="#symlink_option">symlink_option</a> opts = symlink_option::none);
+ recursive_directory_iterator(const path& p,
+ <a href="#symlink_option">symlink_option</a> opts, system::error_code& ec);
recursive_directory_iterator(const path& p, system::error_code& ec);
~recursive_directory_iterator();
// observers
+ int depth() const noexcept;
+ bool recursion_pending() const noexcept;
+
+ // deprecated observers
int level() const noexcept;
- bool no_push<code>_pending</code>() const noexcept;
+ bool no_push_pending() const noexcept;
// modifiers
recursive_directory_iterator& operator=(const recursive_directory_iterator&);
recursive_directory_iterator& increment(system::error_code& ec);
void pop();
- void no_push(bool value=true);
+ void pop(system::error_code& ec);
+ void disable_recursion_pending(bool value = true) noexcept;
+
+ // deprecated modifiers
+ void no_push(bool value = true);
// other members as required by
// C++ Std, Input iterators [input.iterators]
private:
<i><b> // actual data members will probably be stored in a shared object,
// or some similar mechanism, to achieve the required input iterator
- // copy semantics
-</b></i> int m_level; <b><i> // for exposition only</i></b>
- bool m_no_<code>push</code>; <i><b>// for exposition only
- </b></i><a href="#symlink_option">symlink_option</a> m_options; <i><b>// for exposition only</b></i>
+ // copy semantics</b></i>
+ int m_depth; <b><i>// for exposition only</i></b>
+ bool m_recursion_pending; <i><b>// for exposition only</b></i>
+ <a href="#directory_options">directory_options</a> m_options; <i><b>// for exposition only</b></i>
};
} // namespace filesystem
} // namespace boost</pre>
-<p>The behavior of a <code>recursive_directory_iterator</code> is the same
+<p>The behavior of a <code>recursive_directory_iterator</code> is the same
as a <code>directory_iterator</code> unless otherwise specified.</p>
<ul>
- <li>Incrementing a <code>recursive_directory_iterator</code> pointing to a
- directory causes that directory itself to be iterated over, as specified by
+ <li>Incrementing a <code>recursive_directory_iterator</code> pointing to a
+ directory causes that directory itself to be iterated over, as specified by
the <code>operator++</code> and <code>increment</code> functions.<br>
</li>
- <li>When a <code>recursive_directory_iterator</code> reaches the end of the directory currently being iterated
- over, or when <code>pop()</code> is called, <code>m_level</code> is
+ <li>When a <code>recursive_directory_iterator</code> reaches the end of the directory currently being iterated
+ over, or when <code>pop()</code> is called, <code>m_depth</code> is
decremented, and iteration of the parent directory continues.</li>
</ul>
<pre>recursive_directory_iterator() noexcept;</pre>
</blockquote>
-<pre>explicit recursive_directory_iterator(const path& p, <a href="#symlink_option">symlink_option</a> opt = symlink_option::none);
-recursive_directory_iterator(const path& p, <a href="#symlink_option">symlink_option</a> opt, system::error_code& ec);
+<pre>explicit recursive_directory_iterator(const path& p, <a href="#directory_options">directory_options</a> opts = directory_options::none);
+recursive_directory_iterator(const path& p, <a href="#directory_options">directory_options</a> opts, system::error_code& ec);
+explicit recursive_directory_iterator(const path& p, <a href="#symlink_option">symlink_option</a> opts = symlink_option::none);
+recursive_directory_iterator(const path& p, <a href="#symlink_option">symlink_option</a> opts, system::error_code& ec);
recursive_<code>directory_iterator(</code>const path& p, system::error_code& ec<code>);</code></pre>
<blockquote>
-<p><i>Effects:</i> Constructs an iterator representing the first
+<p><i>Effects:</i> Constructs an iterator representing the first
entry in the directory <code>p</code> resolves to, if any; otherwise, the end iterator.</p>
-<p><i>Postcondition: </i>Unless the end iterator was constructed,<i> </i><code>level() == 0 && no_push_pending() == false && m_options == opt</code>.
-For the signature without a <code>symlink_option</code> argument, <code>opt</code> is assumed to be <code>symlink_option::none</code>.</p>
+<p><i>Postcondition: </i>Unless the end iterator was constructed,<i> </i><code>depth() == 0 && recursion_pending() == true && m_options == opts</code>.
+For the signature without the <code>opts</code> argument, <code>opts</code> is assumed to be <code>directory_options::none</code>.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
<p>[<i>Note:</i> To iterate over the current directory, use <code>recursive_directory_iterator(".")</code> rather than <code>recursive_directory_iterator("")</code>. <i>—end note</i>]</p>
-<p>[<i>Note:</i> By default, <code>recursive_directory_iterator</code> does not
-follow directory symlinks. To follow directory symlinks, specify <code>opt</code> as <code>symlink_option::recurse</code> <i>—end note</i>]</p>
+<p>[<i>Note:</i> By default, <code>recursive_directory_iterator</code> does not
+follow directory symlinks. To follow directory symlinks, specify <code>directory_options::follow_directory_symlink</code> in <code>opts</code>. <i>—end note</i>]</p>
+</blockquote>
+<pre>int depth() const noexcept;
+int level() const noexcept;</pre>
+<blockquote>
+ <p><i>Requires:</i> <code>*this != recursive_directory_iterator()</code>.</p>
+ <p><i>Returns:</i> <code>m_depth</code>.</p>
</blockquote>
-<pre>int level() const noexcept;</pre>
+<pre>bool recursion_pending() const noexcept;</pre>
<blockquote>
<p><i>Requires:</i> <code>*this != recursive_directory_iterator()</code>.</p>
- <p><i>Returns:</i> <code>m_level</code>.</p>
+ <p><i>Returns:</i> <code>m_recursion_pending</code>.</p>
</blockquote>
-<pre>bool <code>no_push_pending</code>() const noexcept;</pre>
+<pre>bool no_push_pending() const noexcept;</pre>
<blockquote>
<p><i>Requires:</i> <code>*this != recursive_directory_iterator()</code>.</p>
- <p><i>Returns:</i> <code>m_no_push</code>.</p>
+ <p><i>Returns:</i> <code>!recursion_pending()</code>.</p>
</blockquote>
<pre><code>recursive_directory_iterator</code>& <a name="recursive_directory_iterator-increment">operator++</a>();
recursive_directory_iterator& increment(system::error_code& ec);</pre>
<blockquote>
-<p><i>Effects:</i> As specified by the C++ Standard, 24.1.1 Input iterators [input.iterators],
+<p><i>Effects:</i> As specified by the C++ Standard, 24.1.1 Input iterators [input.iterators],
except:</p>
<ul>
<li>
-<p>if <code>!no_push_pending() && is_directory(this->status())
-&& (!is_symlink(this->symlink_status()) || (m_options & symlink_option::recurse) != 0)</code> then <code>m_level</code> is incremented and directory <code>(*this)->path()</code> is recursively iterated into.<br>
- </p>
+<p>if <code>recursion_pending() && is_directory(this->status())
+&& (!is_symlink(this->symlink_status()) || (m_options & directory_options::follow_directory_symlink) != 0)</code> then:
+ <ul>
+ <li>
+ <p>directory <code>(*this)->path()</code> is opened and recursively iterated into and <code>m_depth</code> is incremented;</p>
+ </li>
+ <li>
+ <p>if opening the directory fails with a <code>permission_denied</code> error and <code>(m_options & directory_options::skip_permission_denied) != 0</code>,
+ increment the iterator on the current level and ignore the error (the operation completes successfully).</p>
+ </li>
+ </ul>
+</p>
</li>
- <li>if there are no more directory entries at this level then <code>m_level</code>
+ <li>if there are no more directory entries at this level then <code>m_depth</code>
is decremented and iteration of the parent directory resumes.</li>
</ul>
-<p><i>Postcondition:</i> <code>no_push_pending() == false</code>.</p>
+<p>If the operation completes with an error, then
+ <ul>
+ <li>if <code>(m_options & directory_options::pop_on_error) != 0</code>, the iterator is left in a state as if after repeatedly calling <code>pop()</code> until it succeeds or the iterator becomes equal to an end iterator; any <code>pop()</code> failures are not reported to the caller;</li>
+ <li>otherwise, the iterator is left equal to an end iterator.</li>
+ </ul>
+</p>
+
+<p><i>Postcondition:</i> <code>recursion_pending() == true</code>.</p>
<p><i>Returns:</i> <code>*this</code>.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
</blockquote>
-<pre>void pop();</pre>
+<pre>void pop();
+void pop(system::error_code& ec);</pre>
<blockquote>
<p><i>Requires:</i> <code>*this != recursive_directory_iterator()</code>.</p>
- <p><i>Effects:</i> If <code>level() == 0</code>, set <code>*this</code> to <code>recursive_directory_iterator()</code>.
- Otherwise, <code>--m_level</code>, cease iteration of the directory currently being
+ <p><i>Effects:</i> If <code>depth() == 0</code>, set <code>*this</code> to <code>recursive_directory_iterator()</code>.
+ Otherwise, <code>--m_depth</code>, cease iteration of the directory currently being
iterated over, and continue iteration over the parent directory.</p>
+ <p>If the operation completes with an error, then
+ <ul>
+ <li>if <code>(m_options & directory_options::pop_on_error) != 0</code>, the iterator is left in a state as if after repeatedly calling <code>pop()</code> until it succeeds or the iterator becomes equal to an end iterator; any <code>pop()</code> failures are not reported to the caller;</li>
+ <li>otherwise, the iterator is left equal to an end iterator.</li>
+ </ul>
+ </p>
</blockquote>
-<pre>void no_push(bool value=true);</pre>
+<pre>void disable_recursion_pending(bool value = true) noexcept;
+void no_push(bool value = true) noexcept;</pre>
<blockquote>
<p><i>Requires:</i> <code>*this != recursive_directory_iterator()</code>.</p>
-<p><i>Postcondition:</i> <code>no_push_pending() == value</code>.</p>
- <p>[<i>Note:</i> <code>no_push()</code> is used to prevent
+ <p><i>Postcondition:</i> <code>recursion_pending() == !value</code>.</p>
+ <p>[<i>Note:</i> These functions are used to prevent
unwanted recursion into a directory. <i>—end note</i>]</p>
</blockquote>
<h3><a name="recursive_directory_iterator-non-member-functions"><code>recursive_directory_iterator</code> non-member functions</a></h3>
<p><i>Returns: </i><code>recursive_directory_iterator()</code>.</p>
</blockquote>
<h2><a name="Operational-functions">Operational functions</a> [fs.op.funcs]</h2>
-<p>Operational functions query or modify files, including directories, in external
+<p>Operational functions query or modify files, including directories, in external
storage.</p>
-<p>Operational functions access a file by resolving an
-object of class <code>path</code> to a particular file in a file hierarchy. The
+<p>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 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_11">Pathname Resolution</a> mechanism.</p>
-<p>[<i>Note: </i>Because hardware failures, network failures, <a href="#file-system-race">file system races</a>, and many
-other kinds of errors occur frequently in file system operations, users should be aware
-that any filesystem operational function, no matter how apparently innocuous, may encounter
+<p>[<i>Note: </i>Because hardware failures, network failures, <a href="#file-system-race">file system races</a>, and many
+other kinds of errors occur frequently in file system operations, users should be aware
+that any filesystem operational function, no matter how apparently innocuous, may encounter
an error. See <a href="#Error-reporting">Error reporting</a>. <i>—end note</i>]</p>
<pre>path <a name="absolute">absolute</a>(const path& p, const path& base=current_path());</pre>
<blockquote>
- <p><i>Returns:</i> A <a href="#Absolute-path">absolute path</a> composed according to the
+ <p><i>Returns:</i> A <a href="#Absolute-path">absolute path</a> composed according to the
following table</p>
<table border="1" cellpadding="5" cellspacing="0" bordercolor="#111111" style="border-collapse: collapse">
<tr>
</tr>
</table>
<p>[<i>Note:</i> For the returned path, <code>rp,</code> <code>rp.is_absolute()</code> is true. <i>—end note</i>]</p>
- <p><i>Throws:</i> If <code>base.is_absolute()</code> is true, throws only if
+ <p><i>Throws:</i> If <code>base.is_absolute()</code> is true, throws only if
memory allocation fails.</p>
</blockquote>
<pre>path <a name="canonical">canonical</a>(const path& p, const path& base = current_path());
path canonical(const path& p, system::error_code& ec);
path canonical(const path& p, const path& base, system::error_code& ec);</pre>
<blockquote>
-<p><i>Overview:</i> Converts <code>p</code>, which must exist, to an absolute
-path that has no symbolic link, <a href="#Dot">dot</a>,
+<p><i>Overview:</i> Converts <code>p</code>, which must exist, to an absolute
+path that has no symbolic link, <a href="#Dot">dot</a>,
or <a href="#Dot">dot-dot</a> elements. </p>
-<p><i>Returns:</i> A <a href="#canonical-path">canonical path</a> that refers to
-the same file system object as <code>absolute(p,base)</code>. For the overload
+<p><i>Returns:</i> A <a href="#canonical-path">canonical path</a> that refers to
+the same file system object as <code>absolute(p,base)</code>. For the overload
without a <code>base</code> argument, <code>base</code> is <code>current_path()</code>.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
-
+
<p><i>Remarks:</i> <code>!exists(p)</code> is an error.</p>
-
- <p>[<i>Note:</i> Canonical pathnames allow security checking of a path (eg.
+
+ <p>[<i>Note:</i> Canonical pathnames allow security checking of a path (eg.
does this path live in /home/goodguy or /home/badguy?) —end note]</p>
-
+
</blockquote>
<pre>void <a name="copy">copy</a>(const path& from, const path& to);
void copy(const path& from, const path& to, system::error_code& ec);</pre>
<blockquote>
<p><i>Effects:</i> As if</p>
-
+
<blockquote>
<pre>file_status s(symlink_status(from<i>[</i><code>, ec</code><i>]</i>));
if(is_symlink(s))
<i> Report error as specified in <a href="#Error-reporting">Error reporting</a>.</i></pre>
</blockquote>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
-
+
</blockquote>
<pre>void <a name="copy_directory">copy_directory</a>(const path& from, const path& to);
void copy_directory(const path& from, const path& to, system::error_code& ec);</pre>
<code>create_directory</code> with an additional argument.</i></td>
</tr>
</table>
-
- <p><i>Effects: </i>Creates directory <code>to</code>, with
- attributes copied from directory <code>from</code>. The set of attributes
+
+ <p><i>Effects: </i>Creates directory <code>to</code>, with
+ attributes copied from directory <code>from</code>. The set of attributes
copied is operating system dependent.</p>
-
+
<blockquote>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
bordercolor="#111111" width="90%" bgcolor="#E8FFE8">
<tr>
<td width="100%">
- <p>[<i>Note:</i> For ISO 9945/POSIX based operating systems the
- attributes are those copied by native API <code>stat(from.c_str(), &from_stat)</code>
- followed by <code>mkdir(to.c_str(),from_stat.st_mode)</code>. For
- Windows based operating systems the attributes are those copied by native
+ <p>[<i>Note:</i> For ISO 9945/POSIX based operating systems the
+ attributes are those copied by native API <code>stat(from.c_str(), &from_stat)</code>
+ followed by <code>mkdir(to.c_str(),from_stat.st_mode)</code>. For
+ Windows based operating systems the attributes are those copied by native
API <code>CreateDirectoryExW(from.c_str(), to.c_str(), 0)</code>. <i>
—end note</i>]</td>
</tr>
</table>
</blockquote>
-
+
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
</blockquote>
void copy_file(const path& from, const path& to, system::error_code& ec);</pre>
<blockquote>
<p><i>Effects: </i><code>copy_file(from, to, copy_option::fail_if_exists</code><i>[</i><code>, ec</code><i>]</i><code>)</code>.</p>
-
+
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
-
+
</blockquote>
<pre>void <a name="copy_file">copy_file</a>(const path& from, const path& to, <a href="#copy_option">copy_option</a> option);
void <a name="copy_file2">copy_file</a>(const path& from, const path& to, <a href="#copy_option">copy_option</a> option, system::error_code& ec);</pre>
void copy_symlink(const path& existing_symlink, const path& new_symlink, system::error_code& ec);</pre>
<blockquote>
<p><i>Effects: </i><code>create_symlink(read_symlink(existing_symlink</code><i>[</i><code>, ec</code><i>]</i><code>), new_symlink</code><i>[</i><code>, ec</code><i>]</i><code>)</code>.</p>
-
+
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
-
+
</blockquote>
<pre>bool <a name="create_directories">create_directories</a>(const path& p);
bool <a name="create_directories2">create_directories</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
<p><i>Effects:</i> Establishes the postcondition by calling <code>
- create_directory()</code> for any element of <code>p</code> that does not
+ create_directory()</code> for any element of <code>p</code> that does not
exist.</p>
<p><i>Postcondition:</i> <code>is_directory(p)</code></p>
<p><i>Returns:</i> <code>true</code> if a new directory was created, otherwise <code>
false</code>.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
- <p><i>Complexity:</i> <i>O(n+1)</i> where <i>n</i> is the number of elements
+ <p><i>Complexity:</i> <i>O(n+1)</i> where <i>n</i> is the number of elements
of <code>p</code> that do not exist.</p>
</blockquote>
<pre>bool <a name="create_directory">create_directory</a>(const path& p);
bool <a name="create_directory2">create_directory</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
- <p><i>Effects:</i> Establishes the postcondition by attempting to create the
+ <p><i>Effects:</i> 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">
- 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
+ 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. </p>
<p><i>Postcondition:</i> <code>is_directory(p)</code></p>
<p><i>Returns:</i> <code>true</code> if a new directory was created, otherwise <code>false</code>.</p>
<blockquote>
<p><i>Effects:</i> Establishes the postcondition, as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/symlink.html">symlink()</a></code>.</p>
<p><i>
- Postcondition:</i> <code>new_symlink</code> resolves to a symbolic link file that
+ Postcondition:</i> <code>new_symlink</code> resolves to a symbolic link file that
contains an unspecified representation of <code>to</code>.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
- <p>[<i>Note:</i> Some operating systems, such as Windows, require symlink creation to
+ <p>[<i>Note:</i> Some operating systems, such as Windows, require symlink creation to
identify that the link is to a directory. Portable code should use <code>create_directory_symlink()</code> to create directory symlinks rather than <code>create_symlink()</code> <i>—end note</i>]</p>
- <p>[<i>Note:</i> Some operating systems do not support symbolic links at all or support
- them only for regular files.
- Some file systems do not
- support
- symbolic links regardless of the operating system - the FAT file system used on
+ <p>[<i>Note:</i> Some operating systems do not support symbolic links at all or support
+ them only for regular files.
+ Some file systems do not
+ support
+ symbolic links regardless of the operating system - the FAT file system used on
memory cards and flash drives, for example. <i>—end note</i>]</p>
</blockquote>
<pre>void <a name="create_hard_link">create_hard_link</a>(const path& to, const path& new_hard_link);
<p><i>Effects:</i> Establishes the postcondition, as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/link.html">link()</a></code>.</p>
<p><i>Postcondition:</i></p>
<ul>
- <li> <code>exists(to) &&
- exists(</code><code>new_hard_link</code><code>) && equivalent(to,
-
+ <li> <code>exists(to) &&
+ exists(</code><code>new_hard_link</code><code>) && equivalent(to,
+
</code><code>new_hard_link</code><code>)</code></li>
<li>The contents of the file or directory
<code>to</code> resolves to are unchanged.</li>
</ul>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
- <p>[<i>Note:</i> Some operating systems do not support hard links at all or support
- them only for regular files. Some file systems do not support hard
- links regardless of the operating system - the FAT file system used on memory
- cards and flash drives, for example. Some file systems limit the number of
+ <p>[<i>Note:</i> Some operating systems do not support hard links at all or support
+ them only for regular files. Some file systems do not support hard
+ links regardless of the operating system - the FAT file system used on memory
+ cards and flash drives, for example. Some file systems limit the number of
links per file. <i>—end note</i>]</p>
</blockquote>
<pre>void <a name="create_symlink">create_symlink</a>(const path& to, const path& new_symlink);
<blockquote>
<p><i>Effects:</i> Establishes the postcondition, as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/symlink.html">symlink()</a></code>.</p>
<p><i>
- Postcondition:</i> <code>new_symlink</code> resolves to a symbolic link file that
+ Postcondition:</i> <code>new_symlink</code> resolves to a symbolic link file that
contains an unspecified representation of <code>to</code>.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
- <p>[<i>Note:</i> Some operating systems do not support symbolic links at all or support
- them only for regular files.
- Some file systems do not
- support
- symbolic links regardless of the operating system - the FAT system used on
+ <p>[<i>Note:</i> Some operating systems do not support symbolic links at all or support
+ them only for regular files.
+ Some file systems do not
+ support
+ symbolic links regardless of the operating system - the FAT system used on
memory cards and flash drives, for example. <i>—end note</i>]</p>
</blockquote>
<pre>path <a name="current_path">current_path</a>();
path <a name="current_path2">current_path</a>(system::error_code& ec);</pre>
<blockquote>
- <p><i>Returns:</i> The current working directory path, as if by ISO/IEC
+ <p><i>Returns:</i> The current working directory path, as if by ISO/IEC
9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/getcwd.html">getcwd()</a></code>. <code>is_absolute()</code> is true for the returned path.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
- <p>[<i>Note: </i>The <code>current_path()</code> name was chosen to emphasize that the return is a
+ <p>[<i>Note: </i>The <code>current_path()</code> name was chosen to emphasize that the return is a
path, not just a single directory name.</p>
- <p>The current path as returned by many operating systems is a dangerous
- global variable. It may be changed unexpectedly by a third-party or system
+ <p>The current path as returned by many operating systems is a dangerous
+ global variable. It may be changed unexpectedly by a third-party or system
library functions, or by another thread. <i>—end note</i>]</p>
</blockquote>
<pre>void current_path(const path& p);
<p><i>Effects:</i> Establishes the postcondition, as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/chdir.html">chdir()</a></code>.</p>
<p><i>Postcondition:</i> <code>equivalent(p, current_path())</code>.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
- <p>[<i>Note: </i>The current path for many operating systems is a dangerous
- global state. It may be changed unexpectedly by a third-party or system
+ <p>[<i>Note: </i>The current path for many operating systems is a dangerous
+ global state. It may be changed unexpectedly by a third-party or system
library functions, or by another thread. <i>—end note</i>]</p>
</blockquote>
<pre>bool <a name="exists">exists</a>(file_status s) noexcept;</pre>
<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>
- <p><i>Returns:</i> <code>exists(status(p))</code> or <code>exists(status(p, ec))</code>,
+ <p><i>Returns:</i> <code>exists(status(p))</code> or <code>exists(status(p, ec))</code>,
respectively. If ec != 0 and an error</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
</blockquote>
<pre><code>bool <a name="equivalent">equivalent</a>(const path& p1, const path& p2);
bool <a name="equivalent2">equivalent</a>(const path& p1, const path& p2, system::error_code& ec);</code></pre>
<blockquote>
- <p><i>Effects:</i> Determines <code>file_status s1</code> and <code>s2</code>, as if by <code>status(p1)</code> and <code>status(p2)</code>,
+ <p><i>Effects:</i> Determines <code>file_status s1</code> and <code>s2</code>, as if by <code>status(p1)</code> and <code>status(p2)</code>,
respectively.</p>
- <p><i>Returns:</i> <code>true</code>, if <code>sf1 ==
- sf2</code> and <code>p1</code> and <code>p2</code> resolve to the same file
+ <p><i>Returns:</i> <code>true</code>, if <code>sf1 ==
+ sf2</code> and <code>p1</code> and <code>p2</code> resolve to the same file
system entity, else <code>false</code>.</p>
<blockquote>
- <p>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><a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">stat</a></code> structure<code>,</code> obtained as if by <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code> for the two paths, having equal <code>st_dev</code> values
+ <p>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><a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">stat</a></code> structure<code>,</code> obtained as if by <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code> for the two paths, having equal <code>st_dev</code> values
and equal <code>st_ino</code> values.</p>
<p>[<i>Note:</i> ISO/IEC 9945 requires that <i>"st_dev</i> 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. <i>Windows</i> implementations may use <code>GetFileInformationByHandle()</code> as a surrogate for <code>stat()</code>,
+ ISO/IEC 9945 implementations may also wish to check for equal <code>st_size</code> and <code>st_mtime</code> values. <i>Windows</i> 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>. <i>—end note</i>]</p>
</blockquote>
- <p><i>Throws:</i> <code>filesystem_error</code> if <code>(!exists(s1) && !exists(s2)) || (is_other(s1) && is_other(s2))</code>,
+ <p><i>Throws:</i> <code>filesystem_error</code> if <code>(!exists(s1) && !exists(s2)) || (is_other(s1) && is_other(s2))</code>,
otherwise as specified in <a href="#Error-reporting">Error reporting</a>.</p>
</blockquote>
uintmax_t <a name="file_size2">file_size</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
- <p><i>Returns:</i> 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
+ <p><i>Returns:</i> 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><a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">stat</a></code> structure member <code>st_size</code> obtained as if by
- ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>.
+ ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>.
Otherwise, <code>static_cast<uintmax_t>(-1)</code>.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
</blockquote>
const path& <a name="initial_path2">initial_path</a>(<code>system::error_code& ec</code>);</pre>
<blockquote>
<p><i>Returns:</i> <code>current_path()</code> as of the first call to <code>initial_path()</code>.</p>
- <p>[<i>Note:</i> <code>initial_path()</code> is not thread safe, and may return an undesirable result
- if called subsequent to a change to the current directory. These problems can
- be avoided by calling <code>initial_path()</code> immediately on entry to
+ <p>[<i>Note:</i> <code>initial_path()</code> is not thread safe, and may return an undesirable result
+ if called subsequent to a change to the current directory. These problems can
+ be avoided by calling <code>initial_path()</code> immediately on entry to
main(). <i>—end note</i>]</p>
<p><i>Throws:</i> For the first call, as specified in <a href="#Error-reporting">Error reporting</a>. Subsequent calls throw nothing.</p>
</blockquote>
<pre><code>bool <a name="is_directory2">is_directory</a>(const path& p);
bool <a name="is_directory3">is_directory</a>(const path& p, system::error_code& ec) noexcept;</code></pre>
<blockquote>
- <p><i>Returns:</i> <code>is_directory(status(p))</code> or <code>is_directory(status(p, ec))</code>,
+ <p><i>Returns:</i> <code>is_directory(status(p))</code> or <code>is_directory(status(p, ec))</code>,
respectively.</p>
-<p><i>Throws:</i> <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+<p><i>Throws:</i> <code>filesystem_error</code>; overload with <code>error_code&</code> throws
nothing.</p>
</blockquote>
<pre><code>bool <a name="is_empty">is_empty</a>(const path& p);
</blockquote>
<pre><code>bool <a name="is_regular_file3">is_regular_file</a>(const path& p, system::error_code& ec) noexcept;</code></pre>
<blockquote>
- <p><i>Effects:</i> Sets <code>ec</code> as if by <code>status(p, ec)</code>. [<i>Note:</i> <code>status_error</code>, <code>file_not_found</code> and <code>type_unknown</code> cases set <code>ec</code> to error values. To distinguish between cases, call the <code>status</code> function directly. <i>—end
+ <p><i>Effects:</i> Sets <code>ec</code> as if by <code>status(p, ec)</code>. [<i>Note:</i> <code>status_error</code>, <code>file_not_found</code> and <code>type_unknown</code> cases set <code>ec</code> to error values. To distinguish between cases, call the <code>status</code> function directly. <i>—end
note</i>] </p>
<p><i>Returns:</i> <code>is_regular_file(status(p, ec))</code>.</p>
</blockquote>
<pre><code>bool <a name="is_other2">is_other</a>(const path& p);
bool <a name="is_other3">is_other</a>(const path& p, system::error_code& ec) noexcept;</code></pre>
<blockquote>
- <p><i>Returns:</i> <code>is_other(status(p))</code> or <code>is_other(status(p, ec))</code>,
+ <p><i>Returns:</i> <code>is_other(status(p))</code> or <code>is_other(status(p, ec))</code>,
respectively.</p>
- <p><i>Throws:</i> <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+ <p><i>Throws:</i> <code>filesystem_error</code>; overload with <code>error_code&</code> throws
nothing.</p>
</blockquote>
<pre>bool <a name="is_symlink">is_symlink</a>(file_status s) noexcept;</pre>
<pre><code>bool <a name="is_symlink2">is_symlink</a>(const path& p);
bool <a name="is_symlink3">is_symlink</a>(const path& p, system::error_code& ec) noexcept;</code></pre>
<blockquote>
- <p><i>Returns:</i> <code>is_symlink(symlink_status(p))</code> or <code>is_symlink(symlink_status(p, ec))</code>,
+ <p><i>Returns:</i> <code>is_symlink(symlink_status(p))</code> or <code>is_symlink(symlink_status(p, ec))</code>,
respectively.</p>
- <p><i>Throws:</i> <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+ <p><i>Throws:</i> <code>filesystem_error</code>; overload with <code>error_code&</code> throws
nothing.</p>
</blockquote>
<pre>std::time_t <a name="last_write_time">last_write_time</a>(const path& p);
std::time_t <a name="last_write_time2">last_write_time</a>(const path& p<code>, system::error_code& ec</code>);</pre>
<blockquote>
- <p><i>Returns:</i> The time of last data modification of <code>p</code>, determined as if by the
- value of the ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">stat</a></code> structure member <code>st_mtime</code> obtained
+ <p><i>Returns:</i> The time of last data modification of <code>p</code>, determined as if by the
+ value of the ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">stat</a></code> structure member <code>st_mtime</code> obtained
as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
</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>
- <p><i>Effects:</i> 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
+ <p><i>Effects:</i> 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><a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code> followed by
ISO/IEC 9945 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/utime.html"><code>utime()</code></a>.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
- <p>[<i>Note:</i> A postcondition of <code>last_write_time(p) == new_time</code> is not specified since it might not hold for file systems
+ <p>[<i>Note:</i> 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. <i>—end note</i>]</p>
</blockquote>
<pre>void <a name="permissions">permissions</a>(const path& p, <a href="#symlink_perms">perms</a> prms);
<p>
<i>Requires:</i> <code>!((prms & add_perms) && (prms & remove_perms))</code>.</p>
<p><i>Effects:</i> Applies the effective permissions bits from <code>prms</code> to the file <code>p</code> resolves to, as if by
- ISO/IEC 9945 <code><a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/fchmodat.html">fchmodat()</a></code>. The effective permission bits are determined as
+ ISO/IEC 9945 <code><a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/fchmodat.html">fchmodat()</a></code>. The effective permission bits are determined as
specified by the following table. </p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<tr>
<td><code>status(p)</code><code>.permissions() & ~(prms & <a href="#perms_mask">perms_mask</a>) </code></td>
</tr>
</table>
- <p>[<i>Note:</i> Conceptually permissions are viewed as bits, but the actual
+ <p>[<i>Note:</i> Conceptually permissions are viewed as bits, but the actual
implementation may use some other mechanism. -- <i>end note</i>]</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
</blockquote>
<pre>path <a name="read_symlink">read_symlink</a>(const path& p);
path read_symlink(const path& p, system::error_code& ec);</pre>
<blockquote>
- <p><i>Returns:</i> If <code>p</code> resolves to a symbolic
- link, a <code>path</code> object containing the contents of that symbolic
+ <p><i>Returns:</i> If <code>p</code> resolves to a symbolic
+ link, a <code>path</code> object containing the contents of that symbolic
link. Otherwise an empty <code>path</code> object.</p>
- <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>. [<i>Note:</i> It is an error if <code>p</code> does not
+ <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>. [<i>Note:</i> It is an error if <code>p</code> does not
resolve to a symbolic link. <i>—end note</i>]</p>
</blockquote>
-<pre><span style="background-color: #E8FFE8">path </span><a name="op-relative"><span style="background-color: #E8FFE8">relative</span></a><span style="background-color: #E8FFE8">(const</span><span style="background-color: #E8FFE8"> path& p, </span><span style="background-color: #E8FFE8">system::error_code</span><span style="background-color: #E8FFE8">& </span><span style="background-color: #E8FFE8">ec</span><span style="background-color: #E8FFE8">);</span></pre>
+<pre>path <a name="op-relative">relative</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
<p><i>Returns:</i> <code>relative(p, current_path(), ec)</code>.</p>
<p><i>Throws:</i> As specified in Error reporting.</p>
</blockquote>
-<pre><span style="background-color: #E8FFE8">path </span><span style="background-color: #E8FFE8">relative(const</span><span style="background-color: #E8FFE8"> path& p, const path& base=</span><span style="background-color: #E8FFE8">current_path</span><span style="background-color: #E8FFE8">());</span>
-<span style="background-color: #E8FFE8">path </span><span style="background-color: #E8FFE8">relative(const</span><span style="background-color: #E8FFE8"> path& p, const path& base, </span><span style="background-color: #E8FFE8">system::error_code</span><span style="background-color: #E8FFE8">& </span><span style="background-color: #E8FFE8">ec</span><span style="background-color: #E8FFE8">);</span></pre>
+<pre>path relative(const path& p, const path& base=current_path());
+path relative(const path& p, const path& base, system::error_code& ec);</pre>
<blockquote>
- <p><i>Overview:</i> Returns <code>p</code> made relative to <code>base</code>.
- Treats empty or identical paths as corner cases, not errors. Resolves symlinks
- and normalizes both <code>p</code> and <code>base</code> before other
+ <p><i>Overview:</i> Returns <code>p</code> made relative to <code>base</code>.
+ Treats empty or identical paths as corner cases, not errors. Resolves symlinks
+ and normalizes both <code>p</code> and <code>base</code> before other
processing.</p>
- <p><i>Returns:</i> <code><a href="#weakly_canonical">weakly_canonical</a>(p).<a href="#lex-relative">lexically_relative</a>(<a href="#weakly_canonical">weakly_canonical</a>(base))</code>. The second form returns <code>path()</code>
+ <p><i>Returns:</i> <code><a href="#weakly_canonical">weakly_canonical</a>(p).<a href="#lex-relative">lexically_relative</a>(<a href="#weakly_canonical">weakly_canonical</a>(base))</code>. The second form returns <code>path()</code>
if an error occurs.</p>
<p><i>Throws:</i> As specified in Error reporting.</p>
</blockquote>
<pre>bool <a name="remove">remove</a>(const path& p);
bool <a name="remove2">remove</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
- <p><i>Effects:</i> If <code>exists(symlink_status(p,ec))</code>, it is
- removed
+ <p><i>Effects:</i> If <code>exists(symlink_status(p,ec))</code>, it is
+ removed
as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/remove.html">remove()</a></code>.</p>
<blockquote>
- <p>[<i>Note:</i> A symbolic link is itself removed, rather than the file it
+ <p>[<i>Note:</i> A symbolic link is itself removed, rather than the file it
resolves to being removed. <i>—end note</i>]</p>
</blockquote>
<p><i>Postcondition:</i> <code>!exists(symlink_status(p))</code>.</p>
- <p><i>Returns:</i> <code>false</code> if p did not exist in the first
+ <p><i>Returns:</i> <code>false</code> if p did not exist in the first
place, otherwise <code>true</code>.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
</blockquote>
<pre>uintmax_t <a name="remove_all">remove_all</a>(const path& p);
uintmax_t <a name="remove_all2">remove_all</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
- <p><i>Effects:</i> Recursively deletes the contents of p if it exists,
- then deletes file <code>p</code> itself,
+ <p><i>Effects:</i> Recursively deletes the contents of p if it exists,
+ then deletes file <code>p</code> itself,
as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/remove.html">remove()</a></code>.</p>
<blockquote>
- <p>[<i>Note:</i> A symbolic link is itself removed, rather than the file it
+ <p>[<i>Note:</i> A symbolic link is itself removed, rather than the file it
resolves to being removed. <i>—end note</i>]</p>
</blockquote>
<p><i>Postcondition:</i> <code>!exists(p)</code></p>
<p><i>Effects:</i> Renames <code>old_p</code> to <code>new_p</code>, as if by
ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/rename.html">rename()</a></code>.</p>
<blockquote>
- <p>[<i>Note:</i> 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
- existing non-directory file, it is removed, while if <code>new_p</code> resolves to an
- existing directory, it is removed if empty on ISO/IEC 9945 but is an error on Windows. A symbolic link is itself renamed, rather than
+ <p>[<i>Note:</i> 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
+ existing non-directory file, it is removed, while if <code>new_p</code> resolves to an
+ existing directory, it is removed if empty on ISO/IEC 9945 but is an error on Windows. A symbolic link is itself renamed, rather than
the file it resolves to being renamed. <i>—end note</i>]</p>
</blockquote>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
<pre>space_info <a name="space">space</a>(const path& p);
space_info <a name="space2">space</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
- <p><i>Returns:</i> An object of type <code><a href="#space_info">space_info</a></code>. The value of the <code>space_info</code> object is determined as if by
+ <p><i>Returns:</i> An object of type <code><a href="#space_info">space_info</a></code>. The value of the <code>space_info</code> object is determined as if by
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 an ISO/IEC 9945 struct
<code><a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/statvfs.h.html" style="text-decoration: none">statvfs</a></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
+ 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.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
</blockquote>
return result;</pre>
</blockquote>
<p><i>Returns:</i> See above.</p>
- <p><i>Throws:</i> <code>filesystem_error</code>.
-[<i>Note:</i> <code>result</code> values of <code>file_status(file_not_found)</code>and <code>file_status(type_unknown)</code> are not considered failures and do not
- cause an exception to be
+ <p><i>Throws:</i> <code>filesystem_error</code>.
+[<i>Note:</i> <code>result</code> values of <code>file_status(file_not_found)</code>and <code>file_status(type_unknown)</code> are not considered failures and do not
+ cause an exception to be
thrown.<i> —end note</i>] </p>
</blockquote>
<pre><a href="#file_status">file_status</a> <a name="status2">status</a>(const path& p, system::error_code& ec) noexcept;</pre>
<blockquote>
<p><i>Effects: </i></p>
<blockquote>
- <p>If possible, determines the attributes
+ <p>If possible, determines the attributes
of the file <code>p</code> resolves to, as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>.</p>
- If, during attribute determination, the underlying file system API reports
- an error, sets <code>ec</code> to indicate the specific error reported.
+ 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>
- <p>[<i>Note:</i> This allows users to inspect the specifics of underlying
+ <p>[<i>Note:</i> This allows users to inspect the specifics of underlying
API errors even when the value returned by <code>status()</code> is not <code>file_status(status_error)</code>. <i>—end note</i>]</p>
</blockquote>
</blockquote>
<blockquote>
<p>If <code>ec != error_code()</code>:</p>
<ul>
- <li>If the specific error indicates that <code>p</code> cannot be resolved
+ <li>If the specific error indicates that <code>p</code> cannot be resolved
because some element of the path does not exist, return <code>
- file_status(file_not_found)</code>. [<i>Note:</i> ISO/IEC 9945 errors that
- indicate this are ENOENT or ENOTDIR. Windows equivalents
- include ERROR_FILE_NOT_FOUND, ERROR_PATH_NOT_FOUND, ERROR_INVALID_NAME,
- ERROR_INVALID_PARAMETER, ERROR_BAD_PATHNAME, and ERROR_BAD_NETPATH. <i>--
+ file_status(file_not_found)</code>. [<i>Note:</i> ISO/IEC 9945 errors that
+ indicate this are ENOENT or ENOTDIR. Windows equivalents
+ include ERROR_FILE_NOT_FOUND, ERROR_PATH_NOT_FOUND, ERROR_INVALID_NAME,
+ ERROR_INVALID_PARAMETER, ERROR_BAD_PATHNAME, and ERROR_BAD_NETPATH. <i>--
end note</i>]<br>
</li>
- <li>Otherwise, if the specific error indicates that <code>p</code> can be resolved
+ <li>Otherwise, if the specific error indicates that <code>p</code> can be resolved
but the attributes cannot be determined, return <code>
- file_status(type_unknown)</code>. [<i>Note: </i>For example, Windows
- ERROR_SHARING_VIOLATION errors. For ISO/IEC 9945, the case never arises. <i>—end
+ file_status(type_unknown)</code>. [<i>Note: </i>For example, Windows
+ ERROR_SHARING_VIOLATION errors. For ISO/IEC 9945, the case never arises. <i>—end
note</i>]<br>
</li>
<li>Otherwise, return <code>
file_status(status_error)</code>.</li>
</ul>
<blockquote>
- <p>[<i>Note:</i> These semantics distinguish between <code>p</code> being known not to exist, <code>p</code> existing but not being able to determine its attributes,
- and there being an error that prevents even knowing if <code>p</code> exists. These
+ <p>[<i>Note:</i> These semantics distinguish between <code>p</code> being known not to exist, <code>p</code> existing but not being able to determine its attributes,
+ and there being an error that prevents even knowing if <code>p</code> exists. These
distinctions are important to some use cases. <i>—end note</i>]</p>
</blockquote>
<p>Otherwise,</p>
<ul>
- <li>If the attributes indicate a regular file, as if by ISO/IEC 9945 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISREG()</a>,
+ <li>If the attributes indicate a regular file, as if by ISO/IEC 9945 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISREG()</a>,
return <code>
file_status(regular_file)</code>. [<i>Note:</i> <code>
-regular_file</code> implies appropriate <code><fstream></code> operations
- would succeed, assuming no hardware, permission, access, or file system
- race
+regular_file</code> implies appropriate <code><fstream></code> operations
+ would succeed, assuming no hardware, permission, access, or file system
+ race
errors. Lack of
-<code>regular_file</code> does not necessarily imply <code><fstream></code> operations would
+<code>regular_file</code> does not necessarily imply <code><fstream></code> operations would
fail on a directory.
<i>—end note</i>]<br>
</li>
<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>,
+ <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISDIR()</a>,
return <code>
file_status(directory_file)</code>. [<i>Note:</i> <code>directory_file</code> implies <code>
directory_iterator(p)</code>would succeed.
<i>—end note</i>]<br>
</li>
<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>,
+ <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISBLK()</a>,
return <code>
file_status(block_file)</code>.<br>
</li>
<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>,
+ <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISCHR()</a>,
return <code>
file_status(character_file)</code>.<br>
</li>
<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>,
+ <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISFIFO()</a>,
return <code>
file_status(fifo_file)</code>.<br>
</li>
- <li>Otherwise, if the attributes indicate a socket, as if by ISO/IEC
+ <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>,
+ <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISSOCK()</a>,
return <code>
file_status(socket_file)</code>.<br>
</li>
file_status(type_unknown)</code>.</li>
</ul>
</blockquote>
- <p><i>Remarks:</i> If a symbolic link is encountered during pathname
- resolution,
+ <p><i>Remarks:</i> If a symbolic link is encountered during pathname
+ resolution,
pathname resolution continues using the contents of the symbolic link.</p>
</blockquote>
<pre>bool <a name="status_known">status_known</a>(file_status s) noexcept;</pre>
<pre>file_status <a name="symlink_status">symlink_status</a>(const path& p);
file_status <a name="symlink_status2">symlink_status</a>(const path& p, system::error_code& ec) noexcept;</pre>
<blockquote>
- <p><i>Effects:</i> Same as <a href="#status">status()</a>, above,
- except that the attributes
+ <p><i>Effects:</i> Same as <a href="#status">status()</a>, above,
+ except that the attributes
of <code>p</code> are determined as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/lstat.html">lstat()</a></code>.</p>
</blockquote>
<blockquote>
- <p><i>Returns:</i> Same as <a href="#status">status()</a>, above, except
+ <p><i>Returns:</i> Same as <a href="#status">status()</a>, 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>.</p>
<p><i>Remarks:</i> Pathname resolution terminates if <code>p</code> names a symbolic link.</p>
- <p><i>Throws:</i> <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+ <p><i>Throws:</i> <code>filesystem_error</code>; overload with <code>error_code&</code> throws
nothing.</p>
</blockquote>
<pre>path <a name="system_complete">system_complete</a>(const path& p);
path <a name="system_complete2">system_complete</a>(const path& p, system::error_code& ec);</pre>
<blockquote>
- <p><i>Effects:</i> Composes an absolute path from <code>p</code>, using the
- same rules used by the operating system to resolve a path passed as the
+ <p><i>Effects:</i> Composes an absolute path from <code>p</code>, using the
+ same rules used by the operating system to resolve a path passed as the
filename argument to standard library open functions.</p>
<p><i>Returns:</i> The composed path.</p>
<p><i>Postcondition:</i> For the returned path, <code>rp,</code> <code>rp.is_absolute()</code> is true.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
<p>[<i>Note:</i> For ISO/IEC 9945, <code>system_complete(p)</code> has the same semantics as <code>complete(p, current_path())</code>.</p>
- <p><a name="windows_effects">For <i>Windows</i></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
- be the current directory of that drive the last time it was set, and thus may
- be <b>residue left over from a prior program</b> run by the command
- processor! Although these semantics are often useful, they are also very
+ <p><a name="windows_effects">For <i>Windows</i></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
+ be the current directory of that drive the last time it was set, and thus may
+ be <b>residue left over from a prior program</b> run by the command
+ processor! Although these semantics are often useful, they are also very
error-prone.</p>
<p>See <a href="#complete_note"><i>complete()</i> note</a> for usage suggestions. <i>—end note</i>]</p>
</blockquote>
<pre>path <a name="temp_directory_path">temp_directory_path</a>();
path temp_directory_path(system::error_code& ec);</pre>
<blockquote>
- <p><i>Returns:</i> A directory path suitable for temporary files under the
- 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)
+ <p><i>Returns:</i> A directory path suitable for temporary files under the
+ 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.</p>
- <p>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>,
+ <p>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>,
or, if macro <code>__ANDROID__ </code>is defined, <code>"/data/local/tmp"</code>.</p>
<p><i>Windows:</i> The path reported by the <i>Windows</i> <code>GetTempPath</code> API function.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
- <p>[<i>Note: </i>The <code>temp_directory_path()</code> name was chosen to emphasize that the return is a
+ <p>[<i>Note: </i>The <code>temp_directory_path()</code> name was chosen to emphasize that the return is a
path, not just a single directory name. <i>—end note</i>]</p>
</blockquote>
<pre>path <a name="unique_path">unique_path</a>(const path& model="%%%%-%%%%-%%%%-%%%%");
path unique_path(const path& model, system::error_code& ec);</pre>
<blockquote>
- <p>The <code>unique_path</code> function generates a path name suitable for
- creating temporary files, including directories. The name is based
- on a model that uses the percent sign character to specify replacement by a
- random hexadecimal digit. [<i>Note:</i> The more bits of randomness in the
- generated path name, the less likelihood of prior existence or being guessed.
- Each replacement hexadecimal digit in the model adds four bits of randomness.
- The default model thus provides 64 bits of randomness. This is sufficient for
+ <p>The <code>unique_path</code> function generates a path name suitable for
+ creating temporary files, including directories. The name is based
+ on a model that uses the percent sign character to specify replacement by a
+ random hexadecimal digit. [<i>Note:</i> The more bits of randomness in the
+ generated path name, the less likelihood of prior existence or being guessed.
+ Each replacement hexadecimal digit in the model adds four bits of randomness.
+ The default model thus provides 64 bits of randomness. This is sufficient for
most applications. <i>—end note</i>]</p>
- <p><i>Returns:</i> A path identical to <code>model</code>, except that each
- occurrence of a percent sign character is replaced by a random hexadecimal
+ <p><i>Returns:</i> A path identical to <code>model</code>, except that each
+ occurrence of a percent sign character is replaced by a random hexadecimal
digit character in the range 0-9, a-f.</p>
<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p>
- <p><i>Remarks:</i> Implementations are encouraged to obtain the required
- randomness via a <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator">cryptographically secure pseudo-random number generator</a>, such as one
- provided by the operating system. [<i>Note</i>: Such generators may block
+ <p><i>Remarks:</i> Implementations are encouraged to obtain the required
+ randomness via a <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator">cryptographically secure pseudo-random number generator</a>, such as one
+ provided by the operating system. [<i>Note</i>: Such generators may block
until sufficient entropy develops. <i>—end note</i>]</p>
</blockquote>
-<pre><span style="background-color: #E8FFE8">path </span><a name="weakly_canonical"><span style="background-color: #E8FFE8">weakly_canonical</span></a><span style="background-color: #E8FFE8">(const</span><span style="background-color: #E8FFE8"> path& p);</span>
-<span style="background-color: #E8FFE8">path </span><span style="background-color: #E8FFE8">weakly_canonical(const</span><span style="background-color: #E8FFE8"> path& p, </span><span style="background-color: #E8FFE8">system::error_code</span><span style="background-color: #E8FFE8">& </span><span style="background-color: #E8FFE8">ec</span><span style="background-color: #E8FFE8">);</span></pre>
+<pre>path <a name="weakly_canonical">weakly_canonical</a>(const path& p);
+path weakly_canonical(const path& p, system::error_code& ec);</pre>
<blockquote>
- <p><i>Overview:</i> Returns <code>p</code> with symlinks resolved and the
+ <p><i>Overview:</i> Returns <code>p</code> with symlinks resolved and the
result normalized.</p>
<p><i>Returns: </i>A path composed of the result of calling the <code>
canonical</code> function on a path composed of the leading elements of <code>
- p</code> that exist, if any, followed by the elements of <code>p</code> that
+ p</code> that exist, if any, followed by the elements of <code>p</code> that
do not exist, if any.</p>
<p><i>Postcondition:</i> The returned path is in
<a href="#normal-form">
normal form</a>.</p>
- <p><i>Remarks:</i> Uses <code>operator/=</code> to compose the returned path.
+ <p><i>Remarks:</i> Uses <code>operator/=</code> to compose the returned path.
Uses the <code>status</code> function to determine existence.</p>
- <p><i>Remarks:</i> Implementations are encouraged to avoid unnecessary
- normalization such as when <code>canonical</code> has already been called on
+ <p><i>Remarks:</i> Implementations are encouraged to avoid unnecessary
+ normalization such as when <code>canonical</code> has already been called on
the entirety of <code>p</code>.</p>
<p><i>Throws:</i> As specified in Error reporting.</p>
</blockquote>
-<pre> </pre>
- <p> </p>
<hr>
<!-- generate-section-numbers=false -->
<h3><a name="File-streams">File streams</a> -
<a href="../../../boost/filesystem/fstream.hpp"><boost/filesystem/fstream.hpp></a></h3>
-<p>Replacements are provided for the file stream classes from the C++ standard
-library's <code><fstream></code> header. These replacement classes
-publicly inherit from the standard library classes. In the Boost.Filesystem
-version, constructors and open functions take <code>const path&</code> arguments
+<p>Replacements are provided for the file stream classes from the C++ standard
+library's <code><fstream></code> header. These replacement classes
+publicly inherit from the standard library classes. In the Boost.Filesystem
+version, constructors and open functions take <code>const path&</code> arguments
instead of <code>
-const char*</code> arguments. There are no other differences in syntax or
+const char*</code> arguments. There are no other differences in syntax or
semantics.</p>
<pre>namespace boost
{
typedef basic_ifstream<wchar_t> wifstream;
typedef basic_fstream<wchar_t> wfstream;
typedef basic_ofstream<wchar_t> wofstream;
-
+
} // namespace filesystem
} // namespace boost</pre>
<td><code>c:</code></td>
<td><code>c:</code></td>
<td><code>c:</code></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
<td><font size="-1"><i>empty</i></font></td>
-<td><span style="background-color: #CCFFCC"><code>c:</code><br><font size="-1"><i>empty</i></font></span></td>
+<td><code>c:</code><br><font size="-1"><i>empty</i></font></td>
<td><font size="-1"><i>empty</i></font></td>
<td><code>c:</code></td>
</tr>
<tr>
<td><code>c:/</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:,.</code><br><code>c:,/</code></span></td>
+<td><code>c:,.</code><br><code>c:,/</code></td>
<td><code>c:/</code></td>
<td><code>c:/</code></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:/</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>/</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:/</code><br><font size="-1"><i>empty</i></font></span></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:/</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>/</code></td>
+<td><code>c:/</code><br><font size="-1"><i>empty</i></font></td>
<td><code>c:</code></td>
-<td><span style="background-color: #CCFFCC"><code>.</code><br><code>/</code></span></td>
+<td><code>.</code><br><code>/</code></td>
</tr>
<tr>
<td><code>c:foo</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:foo</code><br><code>c:,foo</code></span></td>
+<td><code>c:foo</code><br><code>c:,foo</code></td>
<td><code>c:foo</code></td>
<td><code>c:foo</code></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
<td><font size="-1"><i>empty</i></font></td>
-<td><span style="background-color: #CCFFCC"><code>c:foo</code><br><code>foo</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:foo</code><br><code>foo</code></span></td>
+<td><code>c:foo</code><br><code>foo</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><code>c:foo</code><br><code>foo</code></td>
</tr>
<tr>
<td><code>c:/foo</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:,foo</code><br><code>c:,/,foo</code></span></td>
+<td><code>c:,foo</code><br><code>c:,/,foo</code></td>
<td><code>c:/foo</code></td>
<td><code>c:/foo</code></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:/</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>/</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:/foo</code><br><code>foo</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:</code><br><code>c:/</code></span></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:/</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>/</code></td>
+<td><code>c:/foo</code><br><code>foo</code></td>
+<td><code>c:</code><br><code>c:/</code></td>
<td><code>foo</code></td>
</tr>
<tr>
<td><code>c:foo/</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:foo,.</code><br><code>c:,foo,.</code></span></td>
+<td><code>c:foo,.</code><br><code>c:,foo,.</code></td>
<td><code>c:foo/</code></td>
<td><code>c:foo/</code></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
<td><font size="-1"><i>empty</i></font></td>
-<td><span style="background-color: #CCFFCC"><code>c:foo/</code><br><code>foo/</code></span></td>
+<td><code>c:foo/</code><br><code>foo/</code></td>
<td><code>c:foo</code></td>
<td><code>.</code></td>
</tr>
<tr>
<td><code>c:/foo/</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:,foo,.</code><br><code>c:,/,foo,.</code></span></td>
+<td><code>c:,foo,.</code><br><code>c:,/,foo,.</code></td>
<td><code>c:/foo/</code></td>
<td><code>c:/foo/</code></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:/</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>/</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:/foo/</code><br><code>foo/</code></span></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:/</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>/</code></td>
+<td><code>c:/foo/</code><br><code>foo/</code></td>
<td><code>c:/foo</code></td>
<td><code>.</code></td>
</tr>
<tr>
<td><code>c:/foo/bar</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:,foo,bar</code><br><code>c:,/,foo,bar</code></span></td>
+<td><code>c:,foo,bar</code><br><code>c:,/,foo,bar</code></td>
<td><code>c:/foo/bar</code></td>
<td><code>c:/foo/bar</code></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:/</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>/</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:/foo/bar</code><br><code>foo/bar</code></span></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:/</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>/</code></td>
+<td><code>c:/foo/bar</code><br><code>foo/bar</code></td>
<td><code>c:/foo</code></td>
<td><code>bar</code></td>
</tr>
<td><code>prn:</code></td>
<td><code>prn:</code></td>
<td><code>prn:</code></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>prn:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>prn:</code></span></td>
+<td><font size="-1"><i>empty</i></font><br><code>prn:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>prn:</code></td>
<td><font size="-1"><i>empty</i></font></td>
-<td><span style="background-color: #CCFFCC"><code>prn:</code><br><font size="-1"><i>empty</i></font></span></td>
+<td><code>prn:</code><br><font size="-1"><i>empty</i></font></td>
<td><font size="-1"><i>empty</i></font></td>
<td><code>prn:</code></td>
</tr>
<tr>
<td><code>c:\</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:\</code><br><code>c:,/</code></span></td>
+<td><code>c:\</code><br><code>c:,/</code></td>
<td><code>c:\</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:\</code><br><code>c:/</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:\</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>\</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:\</code><br><font size="-1"><i>empty</i></font></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:\</code><br><code>\</code></span></td>
+<td><code>c:\</code><br><code>c:/</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:\</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>\</code></td>
+<td><code>c:\</code><br><font size="-1"><i>empty</i></font></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><code>c:\</code><br><code>\</code></td>
</tr>
<tr>
<td><code>c:foo</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:foo</code><br><code>c:,foo</code></span></td>
+<td><code>c:foo</code><br><code>c:,foo</code></td>
<td><code>c:foo</code></td>
<td><code>c:foo</code></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
<td><font size="-1"><i>empty</i></font></td>
-<td><span style="background-color: #CCFFCC"><code>c:foo</code><br><code>foo</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:foo</code><br><code>foo</code></span></td>
+<td><code>c:foo</code><br><code>foo</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><code>c:foo</code><br><code>foo</code></td>
</tr>
<tr>
<td><code>c:\foo</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:\foo</code><br><code>c:,/,foo</code></span></td>
+<td><code>c:\foo</code><br><code>c:,/,foo</code></td>
<td><code>c:\foo</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:\foo</code><br><code>c:/foo</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:\</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>\</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:\foo</code><br><code>foo</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:\</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:\foo</code><br><code>foo</code></span></td>
+<td><code>c:\foo</code><br><code>c:/foo</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:\</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>\</code></td>
+<td><code>c:\foo</code><br><code>foo</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:\</code></td>
+<td><code>c:\foo</code><br><code>foo</code></td>
</tr>
<tr>
<td><code>c:foo\</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:foo\</code><br><code>c:,foo,.</code></span></td>
+<td><code>c:foo\</code><br><code>c:,foo,.</code></td>
<td><code>c:foo\</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:foo\</code><br><code>c:foo/</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
+<td><code>c:foo\</code><br><code>c:foo/</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
<td><font size="-1"><i>empty</i></font></td>
-<td><span style="background-color: #CCFFCC"><code>c:foo\</code><br><code>foo\</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:foo</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:foo\</code><br><code>.</code></span></td>
+<td><code>c:foo\</code><br><code>foo\</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:foo</code></td>
+<td><code>c:foo\</code><br><code>.</code></td>
</tr>
<tr>
<td><code>c:\foo\</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:\foo\</code><br><code>c:,/,foo,.</code></span></td>
+<td><code>c:\foo\</code><br><code>c:,/,foo,.</code></td>
<td><code>c:\foo\</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:\foo\</code><br><code>c:/foo/</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:\</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>\</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:\foo\</code><br><code>foo\</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:\foo</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:\foo\</code><br><code>.</code></span></td>
+<td><code>c:\foo\</code><br><code>c:/foo/</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:\</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>\</code></td>
+<td><code>c:\foo\</code><br><code>foo\</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:\foo</code></td>
+<td><code>c:\foo\</code><br><code>.</code></td>
</tr>
<tr>
<td><code>c:\foo/</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:\foo,.</code><br><code>c:,/,foo,.</code></span></td>
+<td><code>c:\foo,.</code><br><code>c:,/,foo,.</code></td>
<td><code>c:\foo/</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:\foo/</code><br><code>c:/foo/</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:\</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>\</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:\foo/</code><br><code>foo/</code></span></td>
+<td><code>c:\foo/</code><br><code>c:/foo/</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:\</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>\</code></td>
+<td><code>c:\foo/</code><br><code>foo/</code></td>
<td><code>c:\foo</code></td>
<td><code>.</code></td>
</tr>
<tr>
<td><code>c:/foo\bar</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:,foo\bar</code><br><code>c:,/,foo,bar</code></span></td>
+<td><code>c:,foo\bar</code><br><code>c:,/,foo,bar</code></td>
<td><code>c:/foo\bar</code></td>
-<td><span style="background-color: #CCFFCC"><code>c:/foo\bar</code><br><code>c:/foo/bar</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:/</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>c:</code></span></td>
-<td><span style="background-color: #CCFFCC"><font size="-1"><i>empty</i></font><br><code>/</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:/foo\bar</code><br><code>foo\bar</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>c:</code><br><code>c:/foo</code></span></td>
-<td><span style="background-color: #CCFFCC"><code>foo\bar</code><br><code>bar</code></span></td>
+<td><code>c:/foo\bar</code><br><code>c:/foo/bar</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:/</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>c:</code></td>
+<td><font size="-1"><i>empty</i></font><br><code>/</code></td>
+<td><code>c:/foo\bar</code><br><code>foo\bar</code></td>
+<td><code>c:</code><br><code>c:/foo</code></td>
+<td><code>foo\bar</code><br><code>bar</code></td>
</tr>
</table>
-<h2><a name="long-path-warning"></a>Warning: Long paths on Windows and the
+<h2><a name="long-path-warning"></a>Warning: Long paths on Windows and the
extended-length <b>\\?\ </b>prefix</h2>
<p>The Microsoft Windows "Maximum Path Length Limitation" specifies:</p>
<blockquote>
-<p>In the Windows API (with some exceptions ...), the maximum length for a path
+<p>In the Windows API (with some exceptions ...), the maximum length for a path
is MAX_PATH, which is defined as 260 characters.</p>
-<p>The Windows API has many functions that also have Unicode versions to permit
-an extended-length path for a maximum total path length of 32,767 characters.
-... To specify an extended-length path, use the <b>"\\?\" prefix</b>. For
+<p>The Windows API has many functions that also have Unicode versions to permit
+an extended-length path for a maximum total path length of 32,767 characters.
+... To specify an extended-length path, use the <b>"\\?\" prefix</b>. For
example, "\\?\D:\<em>very long path</em>". <i>[C++ string literals require backslashes be doubled, of course.]</i></p>
</blockquote>
-<p>Because most Boost.Filesystem operational functions just pass the contents of
-a class path object to the Windows API, they do work with the extended-length
-prefixes. But some won't work, because to the limitations imposed by Windows.
+<p>Because most Boost.Filesystem operational functions just pass the contents of
+a class path object to the Windows API, they do work with the extended-length
+prefixes. But some won't work, because to the limitations imposed by Windows.
Read the following cautions carefully!</p>
<h3>Cautions for paths with extended-length prefixes</h3>
<ul>
- <li>Individual components of a path are still are limited to whatever is
+ <li>Individual components of a path are still are limited to whatever is
supported for the particular filesystem, commonly 255 characters.</li>
- <li>Only backslashes only are acceptable as directory separators. Slashes are
+ <li>Only backslashes are acceptable as directory separators. Slashes are
not treated as separators.</li>
<li>All paths must be absolute - relative paths are not allowed.</li>
- <li>Once an absolute path grows beyond 260 characters, it is essentially
- poisoned and all operations must use extended-length prefixes. So even a
- simple operation like <code>create_directory("a")</code> will fail if the
+ <li>Once an absolute path grows beyond 260 characters, it is essentially
+ poisoned and all operations must use extended-length prefixes. So even a
+ simple operation like <code>create_directory("a")</code> will fail if the
absolute path of the resulting directory would exceed 260 characters.</li>
- <li>Certain Boost.Filesystem functions that decompose their argument path and
- then work on individual relative directories or files will not work properly
+ <li>Certain Boost.Filesystem functions that decompose their argument path and
+ then work on individual relative directories or files will not work properly
with extended-length prefix paths.</li>
</ul>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
-<p>This Filesystem Library is dedicated to my wife, Sonda, who provided the
-support necessary to see both a trial implementation and the proposal itself
-through to completion. She gave me the strength to continue after a difficult
+<p>This Filesystem Library is dedicated to my wife, Sonda, who provided the
+support necessary to see both a trial implementation and the proposal itself
+through to completion. She gave me the strength to continue after a difficult
year of cancer treatment in the middle of it all.</p>
-<p>Many people contributed technical comments, ideas, and suggestions to the
+<p>Many people contributed technical comments, ideas, and suggestions to the
Boost Filesystem Library. See <a href="http://www.boost.org/libs/filesystem/doc/index.htm#Acknowledgements">http://www.boost.org/libs/filesystem/doc/index.htm#Acknowledgements</a>.</p>
-<p>Dietmar Kuehl contributed the original Boost Filesystem Library directory_iterator design. Peter Dimov, Walter Landry, Rob Stewart, and Thomas
+<p>Dietmar Kuehl contributed the original Boost Filesystem Library directory_iterator design. Peter Dimov, Walter Landry, Rob Stewart, and Thomas
Witt were particularly helpful in refining the library.</p>
-<p>The create_directories, extension, basename, and replace_extension functions
-were developed by Vladimir Prus. The temp_directory_path function was
-contributed by Jeff Flinn. David Svoboda suggested the canonical function and
+<p>The create_directories, extension, basename, and replace_extension functions
+were developed by Vladimir Prus. The temp_directory_path function was
+contributed by Jeff Flinn. David Svoboda suggested the canonical function and
provided pseudo-code.</p>
-<p>Howard Hinnant and John Maddock reviewed a draft of the version 2 proposal, and
-identified a number of mistakes or weaknesses, resulting in a more polished
+<p>Howard Hinnant and John Maddock reviewed a draft of the version 2 proposal, and
+identified a number of mistakes or weaknesses, resulting in a more polished
final document.</p>
-<p>Peter Dimov suggested a single class path, with member templates to adapt to
+<p>Peter Dimov suggested a single class path, with member templates to adapt to
multiple string types. His idea became the basis for the version 3 path design.</p>
<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/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<font face="Times New Roman">®
- Specification, Version 3. Available from each of the organizations involved
- in its creation. For example, read online or download from <a href="http://www.unix.org/single_unix_specification/">www.unix.org/single_unix_specification/</a>.</font> The ISO JTC1/SC22/WG15 -
+ <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<font face="Times New Roman">®
+ Specification, Version 3. Available from each of the organizations involved
+ in its creation. For example, read online or download from <a href="http://www.unix.org/single_unix_specification/">www.unix.org/single_unix_specification/</a>.</font> The ISO JTC1/SC22/WG15 -
POSIX homepage is <a href="http://www.open-std.org/jtc1/sc22/WG15/">www.open-std.org/jtc1/sc22/WG15/</a></td>
</tr>
<tr>
<a href="http://www.boost.org/LICENSE_1_0.txt"><font size="2">www.boost.org/LICENSE_1_0.txt</font></a></p>
<p><font size="2">Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->01 December 2015<!--webbot bot="Timestamp" endspan i-checksum="39286" --></font></p>
-
-
-</body></html>
+</body>
+</html>
projects / platform / upstream / boost.git / blobdiff