Boost-Commit mailing page: [Boost-commit] svn:boost r76404

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r76404 - trunk/libs/filesystem/v3/doc/src
From: bdawes_at_[hidden]
Date: 2012-01-10 20:34:39

Next message: atompkins_at_[hidden]: "[Boost-commit] svn:boost r76405 - branches/release/boost/uuid"
Previous message: emil_at_[hidden]: "[Boost-commit] svn:boost r76403 - in trunk: boost/exception libs/exception/test"

Author: bemandawes
Date: 2012-01-10 20:34:38 EST (Tue, 10 Jan 2012)
New Revision: 76404
URL: http://svn.boost.org/trac/boost/changeset/76404

Log:
Initial commit of files enabling build of filesystem reference.html and the filesystem TR2 proposal from the same source file. This commit represents work-in-progress, and is not yet ready for prime time. See README for more information.
Added:
   trunk/libs/filesystem/v3/doc/src/
   trunk/libs/filesystem/v3/doc/src/README (contents, props changed)
   trunk/libs/filesystem/v3/doc/src/boost_snippets.html (contents, props changed)
   trunk/libs/filesystem/v3/doc/src/build.bat (contents, props changed)
   trunk/libs/filesystem/v3/doc/src/source.html (contents, props changed)
   trunk/libs/filesystem/v3/doc/src/tr2_snippets.html (contents, props changed)

Added: trunk/libs/filesystem/v3/doc/src/README
==============================================================================
--- (empty file)
+++ trunk/libs/filesystem/v3/doc/src/README 2012-01-10 20:34:38 EST (Tue, 10 Jan 2012)
@@ -0,0 +1,14 @@
+This directory contains the source files used to generate the Filesystem library
+reference documentation and the TR2 filesystem proposal. The generated HTML files
+contain much common material that would be difficult to keep in sync if maintained
+as separate files.
+
+Generation is performed by the Minimal Macro Processor, available from
+https://github.com/Beman/mmp
+
+------------
+
+Copyright Beman Dawes 2012
+
+Distributed under the Boost Software Licence Version 1.0.
+See http://www.boost.org/LICENSE_1_0.txt

Added: trunk/libs/filesystem/v3/doc/src/boost_snippets.html
==============================================================================
--- (empty file)
+++ trunk/libs/filesystem/v3/doc/src/boost_snippets.html 2012-01-10 20:34:38 EST (Tue, 10 Jan 2012)
@@ -0,0 +1,46 @@
+<html>
+
+<head>
+<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
+<meta name="ProgId" content="FrontPage.Editor.Document">
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+<title>New Page 1</title>
+</head>
+
+<body>
+$id frontmatter=
+
+<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
+ <tr>
+ <td width="277">
+<a href="../../../../index.htm">
+<img src="../../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="300" height="86" border="0"></a></td>
+ <td align="middle">
+ Filesystem Library 
+ 
+ Version 3</td>
+ </tr>
+</table>
+
+<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
+ <tr>
+ <td>Filesystem Home   
+ Releases   
+ Reference   
+ Tutorial   
+ FAQ   
+ Portability   
+ V3 Intro   
+ V3 Design   
+ Deprecated   
+ </td>
+ </td>
+ </tr>
+</table>
+
+<h1>Reference Documentation</h1>
+
+$endid
+</body>
+
+</html>
\ No newline at end of file

Added: trunk/libs/filesystem/v3/doc/src/build.bat
==============================================================================
--- (empty file)
+++ trunk/libs/filesystem/v3/doc/src/build.bat 2012-01-10 20:34:38 EST (Tue, 10 Jan 2012)
@@ -0,0 +1,5 @@
+@echo off
+del tr2.html >nul
+mmp TARGET=TR2 source.html tr2.html
+del reference.html >nul
+mmp TARGET=BOOST source.html reference.html

Added: trunk/libs/filesystem/v3/doc/src/source.html
==============================================================================
--- (empty file)
+++ trunk/libs/filesystem/v3/doc/src/source.html 2012-01-10 20:34:38 EST (Tue, 10 Jan 2012)
@@ -0,0 +1,3628 @@
+<html>
+
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
+<meta name="ProgId" content="FrontPage.Editor.Document">
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+<title>
+$if $TARGET; == BOOST
+ Filesystem V3 Reference
+ $def HEADER "boost/filesystem.hpp"
+ $def NAMESPACE boost
+ $def SUBNAMESPACE filesystem
+ $def NAMESPACE_BEGIN "namespace boost
+{
+ namespace filesystem
+ {"
+ $def NAMESPACE_END " } // namespace filesystem
+} // namespace boost"
+$else
+ Filesystem TR2 Proposal
+ $def HEADER "files"
+ $def NAMESPACE std
+ $def SUBNAMESPACE files
+ $def NAMESPACE_BEGIN "namespace std { namespace tr2 { namespace files {
+"
+ $def NAMESPACE_END "} } } // namespaces std::tr2::files"
+$endif
+</title>
+<style type="text/css">
+$include "../../../../../doc/src/minimal.css"
+</style>
+</head>
+
+<body>
+$if $TARGET; == BOOST
+$snippet frontmatter "boost_snippets.html"
+$elif $TARGET; == TR2
+$snippet frontmatter "tr2_snippets.html"
+$endif
+
+<h2><a name="TOC">Table of Contents</a></h2>
+
+<table border="0" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
+ <tr>
+ <td width="33%" valign="top">Introduction 
+ Definitions 
+ Conformance 
+ <a href="#Header-filesystem-synopsis">
+ Header <code><boost/filesystem.hpp></code> synopsis</a> 
+ Error reporting 
+ Class path 
+    path conversions 
+    <a href="#path-Conversions-to-native-format"><code>path</code>
+ conversions to native format</a> 
+    <a href="#path-Conversions-to-generic-format"><code>path</code>
+ conversions to generic format</a> 
+    <a href="#path-Encoding-conversions"><code>path</code>
+ encoding conversions</a> 
+    path requirements 
+     path constructors 
+    path assignments 
+    path appends 
+    path modifiers 
+    <a href="#path-native-format-observers"><code>path</code> native
+ format observers</a> 
+    <a href="#path-generic-format-observers"><code>path</code> generic
+ format observers</a> 
+    path decomposition 
+    path query 
+    path iterators 
+    path deprecated functions 
+    path non-member functions 
+    path inserters and extractors 
+  Class filesystem_error 
+    <a href="#filesystem_error-members"><code>filesystem_error</code>
+ constructors</a> 
+    <code>f</code>ilesystem_error path1 
+    filesystem_error path2 
+    <a href="#filesystem_error-what"><code>filesystem_error</code><code>
+ </code>what</a></td>
+ <td width="33%" valign="top">
+ Enum file_type 
+ Enum perms 
+ <a href="#file_status">Class
+ <code>file_status</code></a> 
+   
+ <a href="#file_status">
+ <code>file_status</code></a> constructors 
+    <code>file_status-modifiers</code> observers 
+    <code>file_status-observers</code> modifiers 
+Class directory_entry 
+   
+directory_entry constructors 
+    directory_entry observers 
+    directory_entry modifiers 
+Class directory_iterator 
+    <a href="#directory_iterator-members"><code>directory_iterator</code>
+ members</a> 
+Class recursive_directory_iterator 
+ <a href="#Operational-functions">
+ Operational functions</a> 
+ <code>   &nbsp absolute 
+     canonical 
+     copy 
+     copy_directory 
+     copy_file 
+     copy_symlink 
+   &nbsp create_directories 
+   &nbsp create_directory 
+   &nbsp create_hard_link 
+   &nbsp create_symlink 
+   &nbsp current_path 
+   &nbsp exists 
+   &nbsp equivalent 
+   &nbsp file_size 
+     hard_link_count 
+      initial_path 
+   &nbsp is_directory 
+   &nbsp is_empty</code></td>
+ <td width="34%" valign="top">
+ <code>   &nbsp is_other 
+   &nbsp is_regular_file 
+   &nbsp is_symlink 
+   &nbsp last_write_time 
+     permissions 
+     read_symlink 
+   &nbsp remove 
+   &nbsp remove_all 
+   &nbsp rename 
+     resize_file 
+   &nbsp space 
+   &nbsp status 
+   &nbsp status_known 
+   &nbsp symlink_status 
+   &nbsp system_complete 
+   &nbsp temp_directory_path 
+     </code> <code> unique_path</code> 
+ File streams 
+Path decomposition table 
+ <a href="#long-path-warning">Warning: Long paths on Windows and the
+ extended-length \\?\ prefix</a> 
+Acknowledgements 
+References 
+ </td>
+ </tr>
+</table>
+
+<h2><a name="Introduction">Introduction</a></h2>
+
+This reference documentation describes components that C++ programs may use
+to perform operations involving file systems, including paths, regular files,
+and directories.
+<h2><a name="Definitions">Definitions</a></h2>
+The following definitions shall apply throughout this reference documentation:
+<a name="File">File</a>: An object that can be written to, or read from, or both. A file
+has certain attributes, including type. Common types of files include regular files
+and directories. Other types of files, such as symbolic links, may be supported by the
+implementation.
+<a name="File-system">File system</a>: A collection of files and certain of their attributes.
+<a name="Filename">Filename</a>: The name of a file. Slash and
+0x00
+characters are not permitted. Implementations may define additional
+characters or specific names that are not permitted. Filenames <code>.</code> 
+and <code>..</code>  have special meaning. Implementations may define
+additional filenames that have special meaning.
+<blockquote>
+ [Note: Most operating systems prohibit the ASCII control characters
+ (0x00-0x1F) in filenames.
+ Windows prohibits the characters 0x00-0x1F, <code>"</code>,<code>
+ *</code>,<code> :</code>,<code> <</code>,<code> ></code>,<code> ?</code>,<code>
+ \</code>,<code> /</code>, and<code> |</code> --end note]
+</blockquote>
+<a name="Path">Path</a>: A sequence of elements that identify
+the location of a file within a filesystem. The elements are the root-nameopt, 
+root-directoryopt, and an optional sequence of filenames. [Note:
+A pathname is the concrete representation of a path. --end note]
+<a name="Absolute-path">Absolute path</a>: A path that
+unambiguously
+identifies the location of a file within a filesystem without reference to an
+additional starting location. The format is implementation defined. 
+<blockquote>
+ [Note: For POSIX-like implementations, including Unix
+ variants, Linux, and Mac OS X, only paths
+ that begin with a slash are absolute paths.
+ For Windows-like implementations, including <a href="http://www.cygwin.com/">
+ Cygwin</a> and
+ MinGW, only paths that begin with a drive
+ specifier followed by a slash, or begin with two slashes, are absolute paths. --end
+ note]
+</blockquote>
+<a name="Relative-path">Relative path</a>: A path that only
+unambiguously
+identifies the location of a file within a filesystem when resolved relative to
+a starting location. The format is implementation defined. [Note:
+Paths "." and ".." are considered to be relative paths. --end note]
+<a name="Canonical-path">Canonical path</a>: An absolute path that has
+no elements which are symbolic links, and no dot or dot dot elements.
+<a name="Pathname">Pathname</a>: A character string that represents a
+path. Pathnames are formatted according to the generic pathname format or the
+implementation defined
+native pathname format.
+<a name="generic-pathname-format">Generic pathname format:</a>
+<blockquote>
+pathname: 
+            root-nameopt
+root-directoryopt relative-pathopt
+root-name: 
+           
+implementation-defined
+<blockquote>
+ <blockquote>
+[Note: Most POSIX and Windows based operating system define a name
+beginning with two slashes (or backslashes, for Windows) as a root-name
+identifying network locations. Windows defines a single letter followed by a
+<code>":"</code> as a root-name identifying a disc drive. --end note]
+ </blockquote>
+</blockquote>
+root-directory: 
+           
+directory-separator
+relative-path: 
+           
+filename 
+            relative-path
+directory-separator 
+            relative-path
+directory-separator filename
+filename: 
+            name 
+            <code>"."</code> 
+            <code>
+".."</code>
+directory-separator: 
+            <code>"/" 
+      "/"</code> directory-separator
+Multiple successive directory-separator characters are considered to
+be the same as one directory-separator character. The filename
+<code>"."</code> is considered to be a reference to the current directory. The
+filename <code>".."</code> is considered to be a reference to the current
+directory. Specific filenames may have special meaning for a particular
+operating system.
+</blockquote>
+<a name="native-pathname-format">Native pathname format:</a> 
+An implementation defined format. [Note: For POSIX-like operating
+systems, the native format is the same as the generic format. For Windows, the
+native format is similar to the generic format, but the directory-separator
+characters can be either slashes or backslashes. --end note]
+<a name="Link">Link</a>: A directory entry object that associates a
+filename with a file. On some file systems, several directory entries can
+associate names with the same file.
+<a name="Hard-link">Hard link</a>: A link to an existing file. Some
+file systems support multiple hard links to a file. If the last hard link to a
+file is removed, the file itself is removed.
+<blockquote>
+[Note: A hard link can be thought of as a shared-ownership smart
+pointer to a file. -- end note] 
+</blockquote>
+<a name="Symbolic-link">Symbolic link</a>: A type of file with the
+property that when the file is encountered during pathname resolution, a string
+stored by the file is used to modify the pathname resolution.
+<blockquote>
+[Note: A symbolic link can be thought of as a raw pointer to a file.
+If the file pointed to does not exist, the symbolic link is said to be a
+"dangling" symbolic link. -- end note] 
+</blockquote>
+<a name="Race-condition">Race condition</a>: The condition that occurs
+when multiple threads, processes, or computers interleave access and
+modification of
+the same object within a file system.
+<a name="Dot">Dot</a>, Dot Dot: Synonyms for the filenames <code>"."</code>
+and <code>".."</code>, respectively. The dot filename names the current
+directory. The dot dot filename names the parent directory.
+<h2><a name="Conformance">Conformance</a></h2>
+Behavior is sometimes specified by reference to ISO/IEC 9945:2003, 
+POSIX. How such behavior is actually implemented is unspecified.
+<blockquote>
+[Note: This constitutes an "as if" rule for implementation of
+operating system dependent behavior. Presumably implementations will usually call native
+operating system API's. --end note]
+</blockquote>
+Implementations are encouraged, but not required, to support such behavior
+
+as it is defined by POSIX. Implementations shall document any
+behavior that differs from the POSIX defined behavior. Implementations that do not support exact POSIX behavior are
+encouraged to provide behavior as close to POSIX 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.
+<blockquote>
+[Note: Such errors might be reported by an #error directive, a <code>
+static_assert</code>, a <code>filesystem_error</code> exception, a special
+return value, or some other manner. --end note]
+</blockquote>
+Implementations are not required to provide behavior that is not supported by
+a particular file system.
+<blockquote>
+[Example: 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
+supported by the host operating system. -- end example]
+</blockquote>
+Specific operating systems such as OpenMVS,
+UNIX, and Windows are mentioned only for purposes of illustration or to
+give guidance to users and implementers. No slight to other operating systems is implied
+or intended. When unlikely to cause confusion, the term POSIX is
+sometimes used to refer to "POSIX-compliant operating systems".
+The behavior of functions described in this
+reference
+may not be achieved in
+the presence of race conditions. No diagnostic is required.
+If the possibility of race conditions would make it unreliable for a program to
+test for a precondition before calling a function described in this clause, 
+Requires is not specified for the condition. Instead, the condition is
+specified as a Throws condition.
+<blockquote>
+[Note: As a design practice, preconditions are not specified when it
+is unreasonable for a program to detect them prior to calling the function. 
+-- end note]
+</blockquote>
+<h2><a name="Header-filesystem-synopsis">Header <code><$HEADER;></code> synopsis</a></h2>
+<pre>$NAMESPACE_BEGIN;
+ class path;
+
+ void swap(path& lhs, path& rhs);
+ bool lexicographical_compare(path::iterator first1, path::iterator last1,
+ path::iterator first2, path::iterator last2);
+ std::size_t hash_value(const path& p);
+
+ bool operator==(const path& lhs, const path& rhs);
+ bool operator!=(const path& lhs, const path& rhs);
+ bool operator< (const path& lhs, const path& rhs);
+ bool operator<=(const path& lhs, const path& rhs);
+ bool operator> (const path& lhs, const 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 filesystem_error;
+ class directory_entry;
+
+ class directory_iterator;
+
+ class recursive_directory_iterator;
+
+ enum <a name="file_type" href="#Enum-file_type">file_type</a>
+ {
+ status_error, file_not_found, regular_file, directory_file,
+ symlink_file, block_file, character_file, fifo_file, socket_file,
+ type_unknown
+ };
+
+ enum perms
+ {
+ no_perms,
+ owner_read, owner_write, owner_exe, owner_all,
+ group_read, group_write, group_exe, group_all,
+ others_read, others_write, others_exe, others_all, all_all,
+ set_uid_on_exe, set_gid_on_exe, sticky_bit,
+ perms_mask, perms_not_known,
+ add_perms, remove_perms, symlink_perms
+ };
+
+ class file_status;
+
+ struct <a name="space_info">space_info</a> // returned by space function
+ {
+ uintmax_t capacity;
+ uintmax_t free;
+ uintmax_t available; // free space available to a non-privileged process
+ };
+
+ BOOST_SCOPED_ENUM_START(<a name="copy_option">copy_option</a>)
+ {
+ none
+ fail_if_exists = none,
+ overwrite_if_exists
+ };
+ BOOST_SCOPED_ENUM_END
+
+ BOOST_SCOPED_ENUM_START(<a name="symlink_option">symlink_option</a>)
+ {
+ none
+ no_recurse = none,
+ recurse
+ };
+ BOOST_SCOPED_ENUM_END
+
+ // operational functions
+
+ path absolute(const path& p, const path& base=current_path());
+
+ path canonical(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);
+
+ void copy(const path& from, const path& to);
+ void copy(const path& from, const path& to, system::error_code& ec);
+
+ void copy_directory(const path& from, const path& to);
+ void copy_directory(const path& from, const path& to, system::error_code& ec);
+
+ void copy_file(const path& from, const path& to);
+ void copy_file(const path& from, const path& to, system::error_code& ec);
+ void copy_file(const path& from, const path& to, BOOST_SCOPED_ENUM(copy_option) option);
+ void copy_file(const path& from, const path& to, BOOST_SCOPED_ENUM(copy_option) option,
+ system::error_code& ec);
+
+ void copy_symlink(const path& existing_symlink, const path& new_symlink);
+ void copy_symlink(const path& existing_symlink, const path& new_symlink, system::error_code& ec);
+
+ bool create_directories(const path& p);
+ bool create_directories(const path& p, system::error_code& ec);
+
+ bool create_directory(const path& p);
+ bool create_directory(const path& p, system::error_code& ec);
+
+ void create_directory_symlink(const path& to, const path& new_symlink);
+ void create_directory_symlink(const path& to, const path& new_symlink, system::error_code& ec);
+
+ void create_hard_link(const path& to, const path& new_hard_link);
+ void create_hard_link(const path& to, const path& new_hard_link, system::error_code& ec);
+
+ void create_symlink(const path& to, const path& new_symlink);
+ void create_symlink(const path& to, const path& new_symlink, system::error_code& ec);
+
+ path current_path();
+ path current_path(system::error_code& ec);
+ void current_path(const path& p);
+ void current_path(const path& p, system::error_code& ec);
+
+ bool exists(file_status s);
+ bool exists(const path& p);
+ bool exists(const path& p, system::error_code& ec);
+
+ bool equivalent(const path& p1, const path& p2);
+ bool equivalent(const path& p1, const path& p2, system::error_code& ec);
+
+ uintmax_t file_size(const path& p);
+ uintmax_t file_size(const path& p, system::error_code& ec);
+ uintmax_t hard_link_count(const path& p);
+ uintmax_t hard_link_count(const path& p, system::error_code& ec);
+
+ const path& initial_path();
+ const path& initial_path(<code>system::error_code& ec</code>);
+
+ bool is_directory(file_status s);
+ bool is_directory(const path& p);
+ bool is_directory(const path& p, system::error_code& ec);
+
+ bool is_empty(const path& p);
+ bool is_empty(const path& p, system::error_code& ec);
+
+ bool is_other(file_status s);
+ bool is_other(const path& p,);
+ bool is_other(const path& p, system::error_code& ec);
+
+ bool is_regular_file(file_status s);
+ bool is_regular_file(const path& p);
+ bool is_regular_file(const path& p, system::error_code& ec);
+
+ bool is_symlink(file_status s);
+ bool is_symlink(const path& p);
+ bool is_symlink(const path& p, system::error_code& ec);
+
+ std::time_t last_write_time(const path& p);
+ std::time_t last_write_time(const path& p, system::error_code& ec);
+ void last_write_time(const path& p, const std::time_t new_time);
+ void last_write_time(const path& p, const std::time_t new_time, system::error_code& ec);
+
+ path read_symlink(const path& p);
+ path read_symlink(const path& p, system::error_code& ec);
+
+ bool remove(const path& p);
+ bool remove(const path& p, system::error_code& ec);
+
+ uintmax_t remove_all(const path& p);
+ uintmax_t remove_all(const path& p, system::error_code& ec);
+
+ void rename(const path& from, const path& to);
+ void rename(const path& from, const path& to, system::error_code& ec);
+
+ void resize_file(const path& p, uintmax_t size);
+ void resize_file(const path& p, uintmax_t size, system::error_code& ec);
+
+ space_info space(const path& p);
+ space_info space(const path& p, system::error_code& ec);
+ file_status status(const path& p);
+ file_status status(const path& p, system::error_code& ec);
+
+ bool status_known(file_status s);
+
+ file_status symlink_status(const path& p);
+ file_status symlink_status(const path& p, system::error_code& ec);
+
+ path system_complete(const path& p);
+ path system_complete(const path& p, system::error_code& ec);
+
+ path temp_directory_path();
+ path temp_directory_path(system::error_code& ec);
+
+ path unique_path(const path& model="%%%%-%%%%-%%%%-%%%%");
+ path unique_path(const path& model, system::error_code& ec);
+
+$NAMESPACE_END;</pre>
+<h2><a name="Error-reporting">Error reporting</a></h2>
+Filesystem library functions often provide two overloads, one that
+throws an exception to report file system errors, and another that sets an
+<code>error_code</code>.
+<blockquote>
+[Note: This supports two common use cases:
+<ul>
+ <li>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. 
+ </li>
+ <li>Uses where file system 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>
+ --end note]
+</blockquote>
+Functions not having an argument of type
+<code>system::error_code&</code>
+report errors as follows, unless otherwise specified:
+ <ul>
+ <li>When a call by the
+ implementation to an operating system or other underlying API results in an
+ error that prevents the function from meeting its specifications, an exception
+ of type
+<code>filesystem_error</code> is thrown. 
+ </li>
+ <li>Failure to allocate storage is reported by throwing an exception as described in the C++ standard,
+ 17.6.4.10 [res.on.exception.handling]. 
+ </li>
+ <li>Destructors throw nothing.</li>
+ </ul>
+ Functions having an argument of type
+<code>system::error_code&</code> report errors as follows, unless otherwise
+ specified:
+<ul>
+ <li>If a call by the
+ implementation to an operating system or other underlying API results in an
+ error that prevents the function from meeting its specifications, the
+<code>system::error_code&</code> argument is set as
+ appropriate appropriate for the specific error. Otherwise, <code>clear()</code>
+ is called on the
+<code>system::error_code&</code> argument. 
+ </li>
+ <li>Failure to allocate storage is reported by
+ throwing an exception as described in the C++ standard,
+ 17.6.4.10 [res.on.exception.handling].</li>
+</ul>
+<h2><a name="class-path">Class <code>path</code></a></h2>
+An object of class <code>path</code> represents a path,
+and contains a pathname Such an object is concerned only with the lexical and syntactic aspects
+of a path. The path does not necessarily exist in external storage, and the
+pathname is not necessarily valid for the current operating
+system or for a particular file system.
+<blockquote>
+[Example: A long path name on Windows
+is an example of an innocuous appearing path that is not actually valid. --
+end example]
+</blockquote>
+<pre>$NAMESPACE_BEGIN;
+ class path
+ {
+ public:
+ typedef see below value_type; // char for POSIX, wchar_t for Windows
+ typedef std::basic_string<value_type> string_type;
+ typedef std::codecvt<wchar_t, char, std::mbstate_t> codecvt_type;
+
+ // constructors and destructor
+ path();
+ path(const path& p);
+
+ template <class Source>
+ path(Source const& source, const codecvt_type& cvt=codecvt());
+
+ template <class InputIterator>
+ path(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());
+
+ ~path();
+
+ // assignments
+ path& operator=(const path& p);
+
+ template <class Source>
+ path& operator=(Source const& source);
+
+ template <class Source>
+ path& assign(Source const& source, const codecvt_type& cvt)
+
+ template <class InputIterator>
+ path& assign(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());
+
+ // appends
+ path& operator/=(const path& p);
+
+ template <class Source>
+ path& operator/=(Source const& source);
+
+ template <class Source>
+ path& append(Source const& source, const codecvt_type& cvt);
+
+ template <class InputIterator>
+ path& append(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());
+
+ // modifiers
+ void clear();
+ path& make_absolute(const path& base);
+ path& make_preferred(); // POSIX: no effect. Windows: convert slashes to backslashes
+ path& remove_filename();
+ path& replace_extension(const path& new_extension = path());
+ void swap(path& rhs);
+
+ // native format observers
+ const string_type& native() const; // native format, encoding
+ const value_type* c_str() const; // native().c_str()
+
+ template <class String>
+ String string(const codecvt_type& cvt=codecvt()) const; // native format
+
+ const string string(const codecvt_type& cvt=codecvt()) const; // native format
+ const wstring wstring(const codecvt_type& cvt=codecvt()) const; // ditto
+ const u16string u16string() const; // ditto
+ const u32string u32string() const; // ditto
+
+ // generic format observers
+ template <class String>
+ String generic_string() const;
+
+ const string generic_string(const codecvt_type& cvt=codecvt()) const; // generic format
+ const wstring generic_wstring(const codecvt_type& cvt=codecvt()) const; // ditto
+ const u16string generic_u16string() const; // ditto
+ const u32string generic_u32string() const; // ditto
+
+ // decomposition
+ path root_name() const;
+ path root_directory() const;
+ path root_path() const;
+ path relative_path() const;
+ path parent_path() const;
+ path filename() const;
+ path stem() const;
+ path extension() const;
+
+ // query
+ bool empty() const;
+ bool has_root_name() const;
+ bool has_root_directory() const;
+ bool has_root_path() const;
+ bool has_relative_path() const;
+ bool has_parent_path() const;
+ bool has_filename() const;
+ bool has_stem() const;
+ bool has_extension() const;
+ bool is_absolute() const;
+ bool is_relative() const;
+
+ // iterators
+ class iterator;
+ typedef iterator const_iterator;
+
+ iterator begin() const;
+ iterator end() const;
+
+ // encoding conversion
+ static std::locale imbue( const std::locale& loc );
+ static const codecvt_type & codecvt();
+
+ private:
+ string_type pathname; // exposition only
+ };
+
+$NAMESPACE_END;</pre>
+<code><a name="value_type">value_type</a></code> is an implementation-defined
+<code>typedef</code> for the
+character type used by the operating system to represent pathnames.
+Member functions described as returning <code>const string</code>, <code>
+const wstring</code>, <code>const u16string</code>, or <code>const u32string</code> are permitted to return <code>const string&</code>, <code>const
+wstring&</code>, <code>const u16string&</code>, or <code>const u32string&</code>,
+respectively.
+<blockquote>
+[Note: This allows implementations to avoid unnecessary copies when no
+conversion is required.
+Return-by-value is specified as
+<code>const</code> to ensure programs won't break if moved to a return-by-reference
+implementation. --
+end note]
+</blockquote>
+<h3><a name="path-Conversions"><code>path</code> Conversions</a></h3>
+<h4><a name="path-Conversions-to-native-format"><code>path</code> Conversions to
+native format</a></h4>
+Member function arguments that take character sequences representing paths
+may use the generic pathname format or
+the native pathname format. If such an
+argument uses the generic format, an implementation defined conversion to native format is performed
+during the processing of the argument. 
+<blockquote>
+[Note: No conversion occurs on POSIX and Windows since they have
+native formats that conform to the generic format. --end note]
+[Rationale: There is no unambiguous way for an implementation to
+always be able distinguish between native format and generic format arguments.
+This is by design as it simplifies use. Should an implementation encounter an
+operating system where disambiguation is required, an implementation defined
+native format prefix can be introduced to identify the native format. -- end
+rationale]
+</blockquote>
+
+<table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
+ <tr>
+ <td style="font-size: 10pt">
+ Class <code>path</code> does not currently map invalid characters in
+ filenames to valid characters. In the future we might add something like
+ this:<blockquote>
+When converting filenames to the native operating system format,
+implementations are encouraged, but not required, to convert otherwise invalid
+characters or character sequences to valid characters or character sequences.
+Such conversions are implementation-defined.
+<blockquote>
+[Note: Filename conversion allows much wider portability of both
+programs and filenames that would otherwise be possible.
+Implementations are encouraged to base conversion on existing standards or
+practice. Examples include the Uniform Resource Locator escape syntax of a percent sign (<code>'%'</code>)
+followed by two hex digits representing the character value. On
+OpenVMS, which does not allow percent signs in filenames, a dollar sign (<code>'$'</code>)
+followed by two hex digits is the existing practice, as is converting lowercase
+letters to uppercase. -- end note.]
+</blockquote>
+ </blockquote>
+ </td>
+ </tr>
+</table>
+
+If the native format requires
+paths for regular files to be formatted differently from paths for directories, the
+path shall be treated as a directory path if last element is a separator,
+otherwise it shall be treated as a regular file path.
+
+<blockquote>
+
+[Note: The above paragraph does not apply to POSIX and Windows since
+they use the same format
+for both regular file and directory pathnames. --end note]
+
+[Example:
+On OpenVMS, a path
+constructed from <code>"/cats/jane"</code> would considered a regular file
+path, and have a native format of <code>"[CATS]JANE"</code>, while a
+path constructed from <code>"/cats/jane/"</code> would be considered a
+directory path, and have a native format of <code>"[CATS.JANE]"</code>.
+--end example]
+
+</blockquote>
+<h4><a name="path-Conversions-to-generic-format"><code>path</code> Conversions
+to generic format</a></h4>
+Generic format observer
+functions return strings formatted according to the
+generic pathname format. The conversion
+from generic to native formats is implementation defined.
+<blockquote>
+[Note: For POSIX, no conversion is performed. For Windows, backslashes are converted to
+forward slashes. -- end note]
+</blockquote>
+<h4><a name="path-Encoding-conversions"><code>path</code> Encoding conversions</a></h4>
+If the value type of member function arguments that are character sequences
+representing paths is not <code>value_type</code>,
+and no <code>cvt</code> argument is supplied, conversion to <code>value_type</code>
+occurs using an imbued locale. This imbued locale is initialized with a <code>
+codecvt</code> facet appropriate for the operating system.
+<blockquote>
+For Apple OS X implementations, <code>path::value_type</code>
+is <code>char</code>. The default imbued locale provides a UTF-8 <code>codecvt</code>
+facet. [Rationale: "All BSD system functions expect their string
+parameters to be in UTF-8 encoding and nothing else." See
+<a href="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPInternational/Articles/FileEncodings.html">
+Apple docs</a>. -- end rationale]
+For Windows-like implementations, including
+MinGW, <code>path::value_type</code> is <code>
+wchar_t</code>. The default imbued locale provides a <code>codecvt</code> facet
+that invokes Windows <code>MultiByteToWideChar</code> or <code>
+WideCharToMultiByte</code> API with a codepage of <code>CP_THREAD_ACP</code>
+if Windows <code>AreFileApisANSI()</code>is true, otherwise codepage <code>
+CP_OEMCP</code>. [Rationale: this is the current behavior of C and C++
+programs that perform file operations using narrow character string to identify
+paths. Changing this in the Filesystem library would be too surprising,
+particularly where user input is involved. -- end rationale]
+For all other implementations, including Linux, <code>path::value_type</code>
+is <code>char</code>. The default imbued locale is <code>std::locale("")</code>.
+[Rationale: ISO C specifies this as "the locale-specific native
+environment", while POSIX says it "Specifies an implementation-defined native
+environment." -- end rationale]
+</blockquote>
+<h3><a name="path-Requirements"><code>path</code> Requirements</a></h3>
+Template parameters named <code><a name="InputIterator">InputIterator</a></code>
+are required meet the
+requirements for a C++ standard library <code>RandomIterator</code>
+compliant iterator. The iterator's value type is required to be <code>char</code>, <code>
+ wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.
+Template parameters named <code><a name="Source">Source</a></code> are required to be one of:
+<ul>
+ <li>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>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>A C-array. 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>A <code>boost::filesystem::directory_entry</code>.</li>
+</ul>
+
+<h3> <a name="path-constructors"> <code>
+path</code> constructors</a></h3>
+<pre>path();</pre>
+<blockquote>
+ Postcondition: <code>empty()</code>.
+ </blockquote>
+<pre>template <class Source>
+ path(Source const& source, const codecvt_type& cvt=codecvt());</pre>
+<pre>template <class InputIterator>
+ path(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());</pre>
+<blockquote>
+ Effects: Stores the contents [<code>begin</code>,<code>end</code>)
+ or <code>source</code> in <code>pathname</code>. If the contents are in the
+ generic format and the generic format is unacceptable to the operating
+ system's API, they are converted to the native format. [Note: For
+ POSIX and Windows implementations, the generic format is already
+ acceptable as a native format, so no generic to native conversion is
+ performed. --end note]
+ 
+ Remarks: If the value type of  [<code>begin</code>,<code>end</code>)
+ or <code>source</code> is not <code>value_type</code>, conversion is performed
+ by <code>cvt</code>.
+</blockquote>
+<h3> <a name="path-assignments"> <code>
+path</code> assignments</a></h3>
+<pre>template <class Source>
+ path& operator=(Source const& source);</pre>
+<pre>template <class Source>
+ path& assign(Source const& source, const codecvt_type& cvt);</pre>
+<pre>template <class InputIterator>
+ path& assign(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());</pre>
+<blockquote>
+ Effects: Stores the contents [<code>begin</code>,<code>end</code>)
+ or <code>source</code> in <code>pathname</code>. If the contents are in the
+ generic format, they are converted to the native format. [Note: For
+ POSIX and Windows based implementations, the generic format is already
+ acceptable as a native format, so no generic to native conversion is
+ performed. --end note]
+ 
+ Returns: <code>*this</code>
+ 
+ Remarks: If the value type of  [<code>begin</code>,<code>end</code>)
+ or <code>source</code> is not <code>value_type</code>, conversion is performed
+ by <code>cvt</code>.
+ </blockquote>
+<h3> <a name="path-appends"><code> path</code> appends</a></h3>
+ The append operations use <code>operator/=</code> to denote their semantic
+ effect of appending the platform's preferred directory separator when needed. The
+ preferred
+ directory separator is implementation-defined.
+<blockquote>
+ [Note: For POSIX-like implementations, including 
+ Unix variants, Linux, and Mac OS X, the preferred directory separator is a
+ single forward slash.
+ For Windows-like implementations, including
+ Cygwin and
+ MinGW, the preferred directory
+ separator is a single backslash.--end note]
+ </blockquote>
+<pre>path& operator/=(const path& p);</pre>
+<blockquote>
+ Effects:
+ <blockquote>
+ Appends the preferred directory separator to the contained pathname, unless:<ul>
+ <li>an added separator
+ would be redundant, or</li>
+ <li>would change an relative path to an absolute path, or</li>
+ <li><code>p.empty()</code>, or</li>
+ <li><code>*p.native().cbegin()</code> is a directory separator.</li>
+ </ul>
+ Appends <code>p.native()</code> to <code>pathname</code>.
+ </blockquote>
+ Returns: <code>*this</code>
+</blockquote>
+<pre>template <class Source>
+ path& operator/=(Source const & source);</pre>
+<pre>template <class Source>
+ path& append(Source const & source, const codecvt_type& cvt);</pre>
+<pre>template <class InputIterator>
+ path& append(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());</pre>
+<blockquote>
+ Effects:
+ <blockquote>
+ Appends a native directory separator to the contained pathname, unless:
+ <ul>
+ <li>an added separator
+ would be redundant, or</li>
+ <li>would change an relative path to an absoute path, or</li>
+ <li><code>p.empty()</code>, or</li>
+ <li><code>*p.native().cbegin()</code> is a separator.</li>
+ </ul>
+ Appends the contents [<code>begin</code>,<code>end</code>)
+ or <code>source</code> to <code>pathname</code>. If the contents are in the
+ generic format, they are converted to the native format. [Note: For
+ POSIX and Windows based implementations, the generic format is already
+ acceptable as a native format, so no generic to native conversion is
+ performed. --end note]
+ </blockquote>
+ Remarks: If the value type of  [<code>begin</code>,<code>end</code>)
+ or <code>source</code> is not <code>value_type</code>, conversion is performed
+ by <code>cvt</code>.
+ Returns: <code>*this</code>
+ </blockquote>
+
+<h3> <a name="path-modifiers"> <code>
+path</code> modifiers</a></h3>
+<pre>void <a name="path-clear">clear</a>();</pre>
+<blockquote>
+Postcondition: <code>this->empty()</code> is true.
+</blockquote>
+<pre>path& <a name="path-make_preferred">make_preferred</a>();</pre>
+<blockquote>
+ Effects: The contained pathname is converted to the preferred native
+ format. [Note: On Windows, the effect is to replace slashes with
+ backslashes. On POSIX, there is no effect. -- end note]
+ Returns: <code>*this</code>
+</blockquote>
+
+<pre>path& <a name="path-remove_filename">remove_filename</a>();</pre>
+<blockquote>
+ Returns: As if, <code>*this = parent_path();</code>
+ [Note: 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>  -- end
+ note]
+</blockquote>
+<pre>path& <a name="path-replace_extension">replace_extension</a>(const path& new_extension = path());</pre>
+<blockquote>
+ Postcondition: <code>extension() == replacement</code>,
+ where <code>replacement</code> is <code>new_extension</code> if <code>
+ new_extension.empty() || new_extension[0] ==</code> the dot character,
+ otherwise <code>replacement</code> is the dot character followed by
+ <code>new_extension</code>.
+ Returns: <code>*this</code>
+</blockquote>
+<pre><code>void <a name="path-swap">swap</a>(path& rhs);</code></pre>
+<blockquote>
+ Effects:
+ Swaps the contents of the two paths.
+ Throws: 
+ nothing.
+ Complexity: 
+ constant time.
+</blockquote>
+
+<h3> <a name="path-native-format-observers"><code>path</code>
+native format observers</a></h3>
+The string returned by all native format observers is in the
+native pathname format.
+<pre>const string_type& <a name="native">native</a>() const;</pre>
+<blockquote>
+Returns: <code>pathname</code>.
+Throws: nothing.
+</blockquote>
+<pre>const value_type* <a name="c_str">c_str</a>() const;</pre>
+<blockquote>
+Returns: <code>pathname.c_str()</code>.
+Throws: nothing.
+</blockquote>
+<pre>template <class String>
+String <a name="string-template">string</a>(const codecvt_type& cvt=codecvt()) const;</pre>
+<blockquote>
+ Returns: <code>pathname</code>.
+Remarks: If <code>string_type</code> is a different type than <code>
+String</code>, conversion is performed by <code>cvt</code>.
+</blockquote>
+<pre>const string <a name="string">string</a>(const codecvt_type& cvt=codecvt()) const;
+const wstring <a name="wstring">wstring</a>(const codecvt_type& cvt=codecvt()) const;
+const u16string <a name="u16string">u16string</a>() const;
+const u32wstring <a name="u32wstring">u32wstring</a>() const; </pre>
+<blockquote>
+Returns: <code>pathname</code>.
+Remarks: If <code>string_type</code> is a different type than
+function's return type, conversion is performed by <code>cvt</code>.
+If <code>string_type</code> is the same type as the
+function's return type, the function is permitted to return by <code>const&</code>
+rather than <code>const</code> value. [Note: For POSIX, this occurs for
+<code>string()</code>, for Windows, <code>wstring()</code>. --end note]
+</blockquote>
+
+<h3> <a name="path-generic-format-observers"><code>path</code>
+generic format observers</a></h3>
+The string returned by all generic format observers is in the
+generic pathname format.
+[Note: For POSIX, no conversion occurs, since the native format and
+generic format are the same. For Windows, backslashes are converted to slashes
+--end note]
+<pre>template <class String>
+String <a name="generic_string-template">generic_string</a>(const codecvt_type& cvt=codecvt()) const;</pre>
+<blockquote>
+ Returns: <code>pathname</code>.
+Remarks: If <code>string_type</code> is a different type than <code>
+String</code>, conversion is performed by
+<code>cvt</code>.
+</blockquote>
+<pre>const string <a name="generic_string">generic_string</a>(const codecvt_type& cvt=codecvt()) const;
+const wstring <a name="generic_wstring">generic_wstring</a>(const codecvt_type& cvt=codecvt()) const;
+const u16string <a name="generic_u16string">generic_u16string</a>() const;
+const u32wstring <a name="generic_u32wstring">generic_u32wstring</a>() const; </pre>
+<blockquote>
+Returns: <code>pathname</code>.
+Remarks:  If <code>string_type</code> is a different type than
+function's return type, conversion is performed by <code>cvt</code>.
+If <code>string_type</code> is of the same type as the
+function's return type, and the generic format is the same as the native format,
+the function is permitted to return by <code>const&</code> rather than <code>
+const</code> value. [Note: For POSIX, this occurs for <code>string()</code>.
+It never occurs for Windows, because backslashes must be converted to slashes.
+--end note]
+</blockquote>
+
+<h3> <a name="path-decomposition"> <code>path</code>
+decomposition</a></h3>
+See the
+Path decomposition table for examples
+for values returned by decomposition functions. The
+Tutorial may also be
+helpful.
+<pre>path <a name="path-root_name">root_name</a>() const;</pre>
+<blockquote>
+Returns: root-name, if <code>pathname</code> includes 
+root-name, otherwise <code>path()</code>. 
+</blockquote>
+<pre>path <a name="path-root_directory">root_directory</a>() const;</pre>
+<blockquote>
+Returns: root-directory, if <code>pathname</code> includes 
+root-directory, otherwise <code>path()</code>.
+If root-directory is composed of slash name, slash is
+excluded from the returned string.
+</blockquote>
+<pre>path <a name="path-root_path">root_path</a>() const;</pre>
+<blockquote>
+ Returns: <code>root_name() / root_directory()</code>
+</blockquote>
+<pre>path <a name="path-relative_path">relative_path</a>() const;</pre>
+<blockquote>
+Returns: A <code>path</code> composed from <code>pathname</code>, if <code>
+!empty()</code>, beginning
+with the first filename after root-path. Otherwise, <code>path()</code>.
+</blockquote>
+<pre>path <a name="path-parent_path">parent_path</a>() const;</pre>
+<blockquote>
+ Returns: <code>(empty() || begin() == --end()) ? path() : pp</code>, where
+ <code>pp</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>.
+</blockquote>
+<pre>path <a name="path-filename">filename</a>() const;</pre>
+<blockquote>
+ Returns: <code>empty() ? path() : *--end()</code>
+ [Example:
+ <blockquote>
+ <pre><code>std::cout << path("/foo/bar.txt").filename();</code> // outputs "<code>bar.txt</code>"</pre>
+ </blockquote>
+ --end example]
+</blockquote>
+<pre>path <a name="path-stem">stem</a>(const path& p) const;</pre>
+<blockquote>
+ Returns: if <code>p.filename()</code>contains a dot but does not
+ 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>.
+ [Example:
+ <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())
+ std::cout << p.extension() << '\n';
+ // outputs: .tar
+ // .baz
+ // .bar</pre>
+ </blockquote>
+ --end example]
+</blockquote>
+<pre>path <a name="path-extension">extension</a>(const path& p) const;</pre>
+<blockquote>
+ Returns: if <code>p.filename()</code> contains a dot but does not
+ consist solely of one or to two dots, returns
+ the substring of <code>p.filename()</code> starting at the rightmost dot
+ and ending at the path's end. Otherwise, returns an empty <code>path</code>
+ object. 
+ Remarks: 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.
+ [Example:
+ <blockquote>
+ <pre><code>std::cout << path("/foo/bar.txt").extension(); //</code> outputs "<code>.txt</code>"</pre>
+ </blockquote>
+ --end example]
+ [Note: The dot is included in the return value so that
+ it is possible to distinguish between no extension and an empty extension. See
+ <a href="http://permalink.gmane.org/gmane.comp.lib.boost.devel/199744">
+ http://permalink.gmane.org/gmane.comp.lib.boost.devel/199744> for more
+ extensive rationale.  -- end note]
+</blockquote>
+<h3> <a name="path-query"> <code>path</code> query</a></h3>
+<pre>bool <a name="path-empty">empty</a>() const;</pre>
+<blockquote>
+ Returns: <code>m_pathname.empty()</code>.
+</blockquote>
+<pre>bool <a name="path-has_root_path">has_root_path</a>() const;</pre>
+<blockquote>
+ Returns: <code>!root_path().empty()</code>
+</blockquote>
+<pre>bool <a name="path-has_root_name">has_root_name</a>() const;</pre>
+<blockquote>
+ Returns: <code>!root_name().empty()</code>
+</blockquote>
+<pre>bool <a name="path-has_root_directory">has_root_directory</a>() const;</pre>
+<blockquote>
+ Returns: <code>!root_directory().empty()</code>
+</blockquote>
+<pre>bool <a name="path-has_relative_path">has_relative_path</a>() const;</pre>
+<blockquote>
+ Returns: <code>!relative_path().empty()</code>
+</blockquote>
+<pre>bool <a name="path-has_parent_path">has_parent_path</a>() const;</pre>
+<blockquote>
+ Returns: <code>!parent_path().empty()</code>
+</blockquote>
+<pre>bool <a name="path-has_filename">has_filename</a>() const;</pre>
+<blockquote>
+ Returns: <code>!filename().empty()</code>
+</blockquote>
+<pre>bool <a name="path-has_stem">has_stem</a>() const;</pre>
+<blockquote>
+ Returns: <code>!stem().empty()</code>
+</blockquote>
+<pre>bool <a name="path-has_extension">has_extension</a>() const;</pre>
+<blockquote>
+ Returns: <code>!extension().empty()</code>
+</blockquote>
+<pre>bool <a name="path-is_absolute">is_absolute</a>() const;</pre>
+<blockquote>
+ Returns: <code>true</code>
+ if the elements of <code>root_path()</code> uniquely identify a directory, else <code>false</code>.
+ [Note: On POSIX,<code>
+ path("/foo").is_absolute()</code> returns <code>true</code>. On Windows, <code>
+ path("/foo").is_absolute()</code> returns <code>false</code>. --end note]
+</blockquote>
+<pre>bool <a name="path-is_relative">is_relative</a>() const;</pre>
+<blockquote>
+ Returns: <code>!is_absolute()</code>.
+</blockquote>
+<h3> <a name="path-iterators"> <code>
+path</code> iterators</a></h3>
+ A <code>path::iterator</code> is a constant iterator satisfying all
+the requirements of a bidirectional iterator (C++ Std, 24.1.4 Bidirectional
+iterators [lib.bidirectional.iterators]). Its <code>value_type</code> is <code>
+path</code>.
+ Calling any non-const member function of a <code>path</code> object
+ invalidates all iterators referring to elements of that object.
+ The forward traversal order is as follows:
+<ul>
+ <li>The root-name element, if present.</li>
+ <li>The root-directory element, if present.</li>
+ <li>Each successive filename element, if present.</li>
+ <li>Dot, if one or more trailing non-root slash
+ characters are present.</li>
+</ul>
+ The backward traversal order is the reverse of forward traversal.
+ <pre>iterator begin() const;</pre>
+<blockquote>
+ Returns: An iterator for the first present element in the traversal
+ list above. If no elements are present, the end iterator.
+</blockquote>
+<pre>iterator end() const;</pre>
+<blockquote>
+ Returns: The end iterator.
+</blockquote>
+ <h3><a name="path_encoding"><code> path</code> encoding</a> conversion</h3>
+ <pre>static std::locale <a name="path-imbue">imbue</a>(const std::locale& loc);</pre>
+<blockquote>
+ Effects: Stores <code>loc</code> as the default locale for all
+ objects of type <code>path</code>.
+ Returns: The previous default locale for all objects of type <code>
+ path</code>.
+</blockquote>
+<pre>static const codecvt_type& <a name="path-codecvt">codecvt</a>();</pre>
+<blockquote>
+ Returns: The <code>codecvt</code> facet for the default locale for
+ all objects of type <code>path</code>.
+</blockquote>
+<h3> <a name="path-deprecated-functions"><code> path</code> deprecated functions</a></h3>
+ 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.
+ Deprecated functions available by default; will be suppressed if <code>
+BOOST_FILESYSTEM_NO_DEPRECATED</code> is defined:
+<blockquote>
+ <pre>path& remove_leaf() { return remove_filename(); }
+path leaf() const { return filename(); }
+path branch_path() const { return parent_path(); }
+bool has_leaf() const { return !m_path.empty(); }
+bool has_branch_path() const { return !parent_path().empty(); }</pre>
+</blockquote>
+ Deprecated functions not available by default; will be supplied if <code>
+BOOST_FILESYSTEM_DEPRECATED</code> is defined:
+<blockquote>
+ <pre>const std::string file_string() const { return native_string(); }
+const std::string directory_string() const { return native_string(); }
+const std::string native_file_string() const { return native_string(); }
+const std::string native_directory_string() const { return native_string(); }
+const string_type external_file_string() const { return native(); }
+const string_type external_directory_string() const { return native(); }</pre>
+</blockquote>
+<h3> <a name="path-non-member-functions"> <code>path</code>
+non-member functions</a></h3>
+<pre>void swap( path& lhs, path& rhs )</pre>
+<blockquote>
+ Effects: <code>
+ lhs.swap(rhs)</code>.
+</blockquote>
+ <pre>bool lexicographical_compare(path::iterator first1, path::iterator last1,
+ path::iterator first2, path::iterator last2)</pre>
+<blockquote>
+ Returns: <code>true</code> if the sequence of <code>native()</code>
+ strings for the elements defined by the range <code>[first1,last1)</code> is
+ lexicographically less than the sequence of <code>native()</code> strings for
+ the elements defined by the range <code>[first2,last2)</code>. Returns <code>
+ false</code> otherwise.
+ Remarks: 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.
+ <pre> for ( ; first1 != last1 && first2 != last2 ; ++first1, ++first2) {
+ if (first1->native() < first2->native()) return true;
+ if (first2->native() < first1->native()) return false;
+ }
+ return first1 == last1 && first2 != last2;</pre>
+ [Note: A <code>path</code> aware<code> lexicographical_compare</code>
+ is provided to avoid infinite recursion in <code>std::lexicographical_compare</code>
+ due to the <code>path</code> iterator's value type itself being <code>path</code>.
+ --end note]
+</blockquote>
+<pre>std::size_t <a name="hash_value">hash_value</a> (const path& p);</pre>
+<blockquote>
+ Returns: A hash value for the path <code>p</code>. If
+ for two paths, <code>p1 == p2</code> then
+ <code>hash_value(p1) == hash_value(p2)</code>.
+ This allows paths to be used with
+ Boost.Hash.
+</blockquote>
+<pre>bool operator< (const path& lhs, const path& rhs);</pre>
+<blockquote>
+ Returns: <code>return lexicographical_compare(lhs.begin(), lhs.end(),
+ rhs.begin(), rhs.end())</code>.
+</blockquote>
+<pre>bool operator<=(const path& lhs, const path& rhs);</pre>
+<blockquote>
+ Returns: <code>!(rhs < lhs)</code>.
+</blockquote>
+<pre>bool operator> (const path& lhs, const path& rhs);</pre>
+<blockquote>
+ Returns: <code>rhs < lhs</code>.
+</blockquote>
+<pre>bool operator>=(const path& lhs, const path& rhs);</pre>
+<blockquote>
+ Returns: <code>!(lhs < rhs)</code>.
+</blockquote>
+<pre>bool operator==(const path& lhs, const path& rhs);</pre>
+<blockquote>
+ Returns: <code>!(lhs < rhs) && !(rhs < lhs)</code>.
+ [Note: Actual implementations may use an equivalent, but more
+ efficient, algorithm. --end note]
+ [Note: <a name="Path-equality">Path equality</a> and path
+ equivalence have different semantics.
+ 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>.
+ Equivalence is determined by the equivalent()
+ non-member function, which determines if two paths resolve 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.
+ 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. 
+ -- end note]
+</blockquote>
+<pre>bool operator!=(const path& lhs, const path& rhs);</pre>
+<blockquote>
+ Returns: <code>!(lhs == rhs)</code>.
+</blockquote>
+<pre>path operator/ (const path& lhs, const path& rhs);</pre>
+<blockquote>
+ Returns: <code>path(lhs) /= rhs</code>.
+</blockquote>
+<h3> <a name="path-non-member-operators"><code>path</code></a><a name="path-inserter-extractor"> inserter
+ and extractor</a></h3>
+ The inserter and extractor delimit the string with double-quotes (<code>"</code>)
+to ensure that paths with embedded spaces will round trip correctly. Ampersand (<code>&</code>)
+is used as an escape character, so the path can itself contain double quotes.
+<pre>template <class Char, class Traits>
+std::basic_ostream<Char, Traits>& operator<<(std::basic_ostream<Char, Traits>& os,
+ const path& p)
+</pre>
+<blockquote>
+ Effects: 
+ <code>os << <a href="../../../io/doc/quoted_manip.html">
+ boost::io::quoted</a>(p.string<std::basic_string<Char>>(), static_cast<Char>('&'));</code>
+ Returns:
+ <code>os</code>
+</blockquote>
+<pre>template <class Char, class Traits>
+inline std::basic_istream<Char, Traits>& operator>>(std::basic_istream<Char, Traits>& is,
+ path& p)
+</pre>
+<blockquote>
+ Effects:  
+ <code> std::basic_string<Char> str; 
+        is >>
+ boost::io::quoted(str,
+ static_cast<Char>('&')); 
+        p = str;</code>
+ Returns:
+ <code>is</code>
+ </blockquote>
+<h3><a name="Class-filesystem_error">Class <code>filesystem_error</code></a></h3>
+<pre>$NAMESPACE_BEGIN;
+ class basic_filesystem_error : public system_error
+ {
+ public:
+ filesystem_error();
+ filesystem_error(const filesystem_error&);
+ filesystem_error(const std::string& what_arg,
+ system::error_code ec);
+ filesystem_error(const std::string& what_arg,
+ const path& p1, system::error_code ec);
+ filesystem_error(const std::string& what_arg,
+ const path& p1, const path& p2, system::error_code ec);
+
+ filesystem_error& filesystem_error(const filesystem_error&);
+ ~filesystem_error();
+
+ filesystem_error& operator=(const filesystem_error&);
+
+ const path& path1() const;
+ const path& path2() const;
+
+ const char * what() const;
+ };
+$NAMESPACE_END;</pre>
+The class template <code>basic_filesystem_error</code> defines the type of
+objects thrown as exceptions to report file system errors from functions described in this
+clause.
+<h4> <a name="filesystem_error-members"> <code>filesystem_error</code> members</a></h4>
+<pre><a name="filesystem_error-2-arg">filesystem_error</a>(const std::string& what_arg, error_code ec);</pre>
+<blockquote>
+ Postcondition:
+ <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="46%">
+ <tr>
+ <td width="18%">Expression</td>
+ <td width="82%">Value</td>
+ </tr>
+ <tr>
+ <td width="18%" bgcolor="#FFFFFF"><code>
+ runtime_error::what()</code></td>
+ <td width="82%" bgcolor="#FFFFFF">
+ <code>what_arg.c_str()</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>code()</code></td>
+ <td width="82%"><code>ec</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>path1().empty()</code></td>
+ <td width="82%"><code>true</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>path2().empty()</code></td>
+ <td width="82%"><code>true</code></td>
+ </tr>
+ </table>
+</blockquote>
+<pre><a name="filesystem_error-3-arg">filesystem_error</a>(const std::string& what_arg, const path_type& p1, error_code ec);</pre>
+<blockquote>
+ Postcondition:
+ <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="46%">
+ <tr>
+ <td width="18%">Expression</td>
+ <td width="82%">Value</td>
+ </tr>
+ <tr>
+ <td width="18%" valign="top"><code>
+ runtime_error::what()</code></td>
+ <td width="82%">
+ <code>what_arg.c_str()</code></td>
+ </tr>
+ <tr>
+ <td width="18%" valign="top"><code>code()</code></td>
+ <td width="82%"><code>ec</code></td>
+ </tr>
+ <tr>
+ <td width="18%" valign="top"><code>path1()</code></td>
+ <td width="82%">Reference to stored copy of
+ <code>p1</code></td>
+ </tr>
+ <tr>
+ <td width="18%" valign="top"><code>path2().empty()</code></td>
+ <td width="82%"><code>true</code></td>
+ </tr>
+ </table>
+</blockquote>
+<pre><a name="filesystem_error-4-arg">filesystem_error</a>(const std::string& what_arg, const path_type& p1, const path_type& p2, error_code ec);</pre>
+<blockquote>
+ Postcondition:
+ <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="46%">
+ <tr>
+ <td width="18%">Expression</td>
+ <td width="82%">Value</td>
+ </tr>
+ <tr>
+ <td width="18%"><code>
+ runtime_error::what()</code></td>
+ <td width="82%">
+ 
+ <code>w</code><code>hat_arg.c_str()</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>code()</code></td>
+ <td width="82%"><code>ec</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>path1()</code></td>
+ <td width="82%">Reference to stored copy of
+ <code>p1</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>path2()</code></td>
+ <td width="82%">Reference to stored copy of
+ <code>p2</code></td>
+ </tr>
+ </table>
+</blockquote>
+<pre>const path& <a name="filesystem_error-path1">path1</a>() const;</pre>
+<blockquote>
+ Returns: Reference to copy of <code>p1</code> stored by the
+ constructor, or, if none, an empty path.
+</blockquote>
+<pre>const path& <a name="filesystem_error-path2">path2</a>() const;</pre>
+<blockquote>
+ Returns: Reference to copy of <code>p2</code> stored by the
+ constructor, or, if none, an empty path.
+</blockquote>
+<pre>const char* <a name="filesystem_error-what">what</a>() const;</pre>
+<blockquote>
+ Returns: 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.
+</blockquote>
+<h3><a name="Enum-file_type">Enum file_type</a></h3>
+This enum specifies constants uses to identify file types.
+<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
+ <tr>
+ <td>Constant Name</td>
+ <td>Meaning</td>
+ </tr>
+ <tr>
+ <td><code>status_error</code></td>
+ <td>An error occurred while trying to obtain the status of the file. The
+ file simply not being found is not considered a status error.
+ </td>
+ </tr>
+ <tr>
+ <td><code>file_not_found</code></td>
+ <td>The file could not be found</td>
+ </tr>
+ <tr>
+ <td><code>regular_file</code></td>
+ <td>Regular file</td>
+ </tr>
+ <tr>
+ <td><code>directory_file</code></td>
+ <td>Directory file</td>
+ </tr>
+ <tr>
+ <td><code>symlink_file</code></td>
+ <td>Symbolic link file</td>
+ </tr>
+ <tr>
+ <td><code>block_file</code></td>
+ <td>Block special file</td>
+ </tr>
+ <tr>
+ <td><code>character_file</code></td>
+ <td>Character special file</td>
+ </tr>
+ <tr>
+ <td><code>fifo_file</code></td>
+ <td>FIFO or pipe file</td>
+ </tr>
+ <tr>
+ <td><code>socket_file</code></td>
+ <td>Socket file</td>
+ </tr>
+ <tr>
+ <td><code>type_unknown</code></td>
+ <td>The file exists, but it is of a system specific type not covered by any
+ of the above cases.</td>
+ </tr>
+</table>
+<h3><a name="Enum-perms">Enum perms</a></h3>
+This enum specifies bitmask constants uses to identify file
+permissions. The POSIX standard specifies actual values, and those values have
+been adopted here because they are very familiar and ingrained for many POSIX
+users.
+<blockquote>
+Caution: Operating systems do not always support permissions as described in
+the table.
+There is much variation in the meaning of <code><a href="#sticky_bit">
+sticky_bit</a></code>; do not use it unless you understand what it means for
+your operating system.
+There is much variation in how operating systems treat symlinks. See <code>
+symlink_perms</code>.
+Windows: All permissions except write are currently ignored. There is only a
+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. 
+</blockquote>
+<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
+ <tr>
+ <td>Name</td>
+ <td align="center">Value 
+ (octal)</td>
+ <td align="center">POSIX 
+ macro</td>
+ <td>Definition or notes</td>
+ </tr>
+
+<tr><td>
+ <code>no_perms</code></td><td><code>0</code></td><td></td>
+ <td>There are no permissions set for the file. Note: <code>file_not_found</code> is
+ <code>no_perms</code> rather than <code>perms_not_known</code></td>
+</tr>
+<tr><td><code>owner_read</code></td><td><code>0400</code></td><td> <code>S_IRUSR</code></td>
+ <td> Read permission, owner</td>
+</tr>
+<tr><td><code>owner_write</code></td><td><code>0200</code></td><td> <code>S_IWUSR</code></td>
+ <td> Write permission, owner</td>
+</tr>
+<tr><td><code>owner_exe</code></td><td><code>0100</code></td><td> <code>S_IXUSR</code></td>
+ <td> Execute/search permission, owner</td>
+</tr>
+<tr><td><code>owner_all</code></td><td><code>0700</code></td><td> <code>S_IRWXU</code></td>
+ <td> Read, write, execute/search by owner; <code>owner_read | owner_write | owner_exe</code></td>
+</tr>
+<tr><td><code>group_read</code></td><td><code>040</code></td><td> <code>S_IRGRP</code></td>
+ <td> Read permission, group</td>
+</tr>
+<tr><td><code>group_write</code></td><td><code>020</code></td><td> <code>S_IWGRP</code></td>
+ <td> Write permission, group</td>
+</tr>
+<tr><td><code>group_exe</code></td><td><code>010</code></td><td> <code>S_IXGRP</code></td>
+ <td> Execute/search permission, group</td>
+</tr>
+<tr><td><code>group_all</code></td><td><code>070</code></td><td> <code>S_IRWXG</code></td>
+ <td> Read, write, execute/search by group; <code>group_read | group_write |
+ group_exe</code></td>
+</tr>
+<tr><td><code>others_read</code></td><td><code>04</code></td><td> <code>S_IROTH</code></td>
+ <td> Read permission, others</td>
+</tr>
+<tr><td><code>others_write</code></td><td><code>02</code></td><td> <code>S_IWOTH</code></td>
+ <td> Write permission, others</td>
+</tr>
+<tr><td><code>others_exe</code></td><td><code>01</code></td><td> <code>S_IXOTH</code></td>
+ <td> Execute/search permission, others</td>
+</tr>
+<tr><td><code>others_all</code></td><td><code>07</code></td><td> <code>S_IRWXO</code></td>
+ <td>Read, write, execute/search by others; <code>others_read | others_write | others_exe</code></td>
+</tr>
+<tr><td><code>all_all</code></td><td><code>0777</code></td><td> </td><td><code>owner_all | group_all | others_all</code></td>
+</tr>
+<tr><td><code>set_uid_on_exe</code></td><td><code>04000</code></td><td> <code>S_ISUID</code></td>
+ <td> Set-user-ID on execution</td>
+</tr>
+<tr><td><code>set_gid_on_exe</code></td><td><code>02000</code></td><td> <code>S_ISGID</code></td>
+ <td> Set-group-ID on execution</td>
+</tr>
+<tr><td><code><a name="sticky_bit">sticky_bit</a> </code> </td><td><code>01000</code></td><td> <code>S_ISVTX</code></td>
+ <td> Meaning varies; see http:en.wikipedia.org/wiki/Sticky_bit</td>
+</tr>
+<tr><td><code>perms_mask</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
+ is created without specifying the permissions</td>
+</tr>
+<tr><td>
+ <code>add_perms</code></td><td><code>0x1000</code></td><td></td><td>
+ <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
+ file's current bits</td>
+</tr>
+<tr><td><code><a name="symlink_perms">symlink_perms</a></code></td><td><code>0x4000</code></td><td></td><td>
+ On POSIX <code>permissions()</code> resolves symlinks unless <code>symlink_perms</code>
+ is specified.
+ Meaningless on Windows as <code>permissions()</code> never resolves symlinks.
+ Meaningless on Mac OS X and some other BSD systems as <code>permissions()</code>
+ always resolves symlinks. Get over it.</td>
+</tr>
+
+</table>
+<h3><a name="file_status">Class file_status</a></h3>
+<pre>$NAMESPACE_BEGIN;
+ class file_status
+ {
+ public:
+
+ // constructors
+ file_status() noexcept;
+ explicit file_status(file_type ft, perms prms = perms_not_known) noexcept;
+
+ // compiler generated
+ file_status(const file_status&) noexcept;
+ file_status& operator=(const file_status&) noexcept;
+ ~file_status() noexcept;
+
+ // observers
+ file_type type() const noexcept;
+ perms permissions() const noexcept;
+
+ // modifiers
+ void type(file_type ft) noexcept;
+ void permissions(perms prms) noexcept;
+ };
+$NAMESPACE_END;</pre>
+An object of type <code>file_status</code> stores information about the type
+and permissions of a file.
+<h4 dir="ltr"><a name="file_status-constructors"><code>file_status</code>
+constructors</a></h4>
+<pre>explicit file_status() noexcept;</pre>
+<blockquote>
+ Postconditions: <code>type() == status_error</code>, <code>
+ permissions() == perms_not_known</code>.
+</blockquote>
+<pre>explicit file_status(file_type ft, perms prms = perms_not_known) noexcept;</pre>
+<blockquote>
+ Postconditions: <code>type() == ft</code>, <code>permissions() ==
+ prms</code>.
+</blockquote>
+ <h4 dir="ltr"><a name="file_status-observers"><code>file_status</code>
+ observers</a></h4>
+<pre>file_type type() const noexcept;</pre>
+<blockquote>
+ Returns: The value of <code>type()</code> specified by the 
+ postconditions of the most recent call to a constructor, operator=, or
+ <code>type(file_type)</code> function.
+</blockquote>
+<pre>perms permissions() const noexcept;</pre>
+<blockquote>
+ Returns: The value of <code>permissions()</code> specified by the 
+ postconditions of the most recent call to a constructor, operator=, or
+ <code>permissions(perms)</code> function.
+</blockquote>
+<h4 dir="ltr"><a name="file_status-modifiers"><code>file_status</code> modifiers</a></h4>
+<pre>void type(file_type ft) noexcept;</pre>
+<blockquote>
+ Postconditions: <code>type() == ft</code>.
+</blockquote>
+<pre>void permissions(perms prms) noexcept;</pre>
+<blockquote>
+ Postconditions: <code>permissions() == prms</code>.
+</blockquote>
+<h3><a name="Class-directory_entry">Class <code>directory_entry</code></a></h3>
+<div dir="ltr">
+<pre>$NAMESPACE_BEGIN;
+ class directory_entry
+ {
+ public:
+
+ // constructors and destructor
+ directory_entry();
+ directory_entry(const directory_entry&);
+ explicit directory_entry(const path_type& p, file_status st=file_status(),
+ file_status symlink_st=file_status());
+ ~directory_entry();
+
+ // modifiers
+ directory_entry& operator=(const directory_entry&);
+ void assign(const path_type& p, file_status st=file_status(),
+ file_status symlink_st=file_status());
+ void replace_filename(const path& p, file_status st=file_status(),
+ file_status symlink_st=file_status());
+
+ // observers
+ const path& path() const;
+ file_status status() const;
+ file_status status(system::error_code& ec) const;
+ file_status symlink_status() const;
+ 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);
+ private:
+ path_type m_path; // for exposition only
+ mutable file_status m_status; // for exposition only; stat()-like
+ mutable file_status m_symlink_status; // for exposition only; lstat()-like
+ };
+
+$NAMESPACE_END;</pre>
+</div>
+A <code>directory_entry</code> object stores a <code>path object</code>,
+a <code>file_status</code> object for non-symbolic link status, and a <code>
+file_status</code> object for symbolic link status. The <code>file_status</code>
+objects act as value caches.
+<blockquote>
+[Note: Because <code>status()</code>on a pathname may be a very expensive operation,
+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 race conditions. -- end note]
+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.
+</blockquote>
+<h4> <a name="directory_entry-constructors"> <code>directory_entry </code>constructors</a></h4>
+<pre>directory_entry();</pre>
+<blockquote>
+ Postcondition:
+ <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="36%">
+ <tr>
+ <td width="18%">Expression</td>
+ <td width="82%">Value</td>
+ </tr>
+ <tr>
+ <td width="18%"><code>path().empty()</code></td>
+ <td width="82%"><code>true</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>status()</code></td>
+ <td width="82%"><code>file_status()</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>symlink_status()</code></td>
+ <td width="82%"><code>file_status()</code></td>
+ </tr>
+ </table>
+</blockquote>
+<pre>explicit directory_entry(const path_type& p, file_status st=file_status(), file_status symlink_st=file_status());</pre>
+<blockquote>
+ Postcondition:
+ <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="36%">
+ <tr>
+ <td width="18%">Expression</td>
+ <td width="82%">Value</td>
+ </tr>
+ <tr>
+ <td width="18%"><code>path()</code></td>
+ <td width="82%"><code>p</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>status()</code></td>
+ <td width="82%"><code>st</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>symlink_status()</code></td>
+ <td width="82%"><code>symlink_st</code></td>
+ </tr>
+ </table>
+</blockquote>
+<h4> <a name="directory_entry-modifiers"> <code>directory_entry </code>modifiers</a></h4>
+<pre>void assign(const path_type& p, file_status st=file_status(), file_status symlink_st=file_status());</pre>
+<blockquote>
+ Postcondition:
+ <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="36%">
+ <tr>
+ <td width="18%">Expression</td>
+ <td width="82%">Value</td>
+ </tr>
+ <tr>
+ <td width="18%"><code>path()</code></td>
+ <td width="82%"><code>p</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>status()</code></td>
+ <td width="82%"><code>st</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>symlink_status()</code></td>
+ <td width="82%"><code>symlink_st</code></td>
+ </tr>
+ </table>
+</blockquote>
+<pre>void replace_filename(const path& p, file_status st=file_status(), file_status symlink_st=file_status());</pre>
+<blockquote>
+ Postcondition:
+ <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="43%">
+ <tr>
+ <td width="18%">Expression</td>
+ <td width="82%">Value</td>
+ </tr>
+ <tr>
+ <td width="18%"><code>path()</code></td>
+ <td width="82%"><code>path().branch() / s</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>status()</code></td>
+ <td width="82%"><code>st</code></td>
+ </tr>
+ <tr>
+ <td width="18%"><code>symlink_status()</code></td>
+ <td width="82%"><code>symlink_st</code></td>
+ </tr>
+ </table>
+</blockquote>
+<h4> <a name="directory_entry-observers"> <code>directory_entry</code> observers</a></h4>
+<pre>const path& path() const;</pre>
+<blockquote>
+ Returns: <code>m_path</code>
+</blockquote>
+<pre>file_status status() const;
+file_status status(system::error_code& ec) const;</pre>
+<blockquote>
+Effects:
+As if,
+ <blockquote>
+ <pre>if ( !status_known( m_status ) )
+{
+ if ( status_known(m_symlink_status) && !is_symlink(m_symlink_status) )
+ { m_status = m_symlink_status; }
+ else { m_status = status(m_path[, ec]); }
+}</pre>
+ </blockquote>
+ Returns: <code>m_status</code>
+
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+
+</blockquote>
+<pre>file_status symlink_status() const;
+file_status symlink_status(system::error_code& ec) const;</pre>
+<blockquote>
+
+ Effects:
+As if,
+ <blockquote>
+ <pre>if ( !status_known( m_symlink_status ) )
+{
+ m_symlink_status = symlink_status(m_path[, ec]);
+}</pre>
+ </blockquote>
+ Returns: <code>
+ m_symlink_status</code>
+
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+
+</blockquote>
+<pre>bool operator==(const directory_entry& rhs);</pre>
+<blockquote>
+ Returns: <code>m_path ==
+ rhs.m_path</code>.
+</blockquote>
+<pre>bool operator!=(const directory_entry& rhs);</pre>
+<blockquote>
+ Returns: <code>m_path !=
+ rhs.m_path</code>.
+</blockquote>
+<pre>bool operator< (const directory_entry& rhs);</pre>
+<blockquote>
+ Returns: <code>m_path <
+ rhs.m_path</code>.
+</blockquote>
+<pre>bool operator<=(const directory_entry& rhs);</pre>
+<blockquote>
+ Returns: <code>m_path <=
+ rhs.m_path</code>.
+</blockquote>
+<pre>bool operator> (const directory_entry& rhs);</pre>
+<blockquote>
+ Returns: <code>m_path >
+ rhs.m_path</code>.
+</blockquote>
+<pre>bool operator>=(const directory_entry& rhs);</pre>
+<blockquote>
+ Returns: <code>m_path >=
+ rhs.m_path</code>.
+</blockquote>
+<h3><a name="Class-directory_iterator">Class <code>directory_iterator</code></a></h3>
+Objects of type <code>directory_iterator</code> provide standard library
+compliant iteration over the contents of a directory. Also see class <code>
+recursive_directory_iterator</code>.
+<pre>$NAMESPACE_BEGIN;
+ class directory_iterator
+ : public boost::iterator_facade< directory_iterator,
+ directory_entry,
+ boost::single_pass_traversal_tag >
+ {
+ public:
+ // member functions
+
+ directory_iterator(); // creates the "end" iterator
+ directory_iterator(const directory_iterator&);
+ explicit directory_iterator(const path& p);
+ directory_iterator(const path& p, system::error_code& ec);
+ ~directory_iterator();
+
+ directory_iterator& operator=(const directory_iterator&);
+
+ directory_iterator& operator++();
+ directory_iterator& increment(system::error_code& ec);
+
+ // other members as required by
+ // C++ Std, 24.1.1 Input iterators [input.iterators]
+ };
+
+$NAMESPACE_END;</pre>
+ <code>directory_iterator</code> satisfies the requirements of an
+input iterator (C++ Std, 24.2.1, Input iterators [input.iterators]).
+A <code>directory_iterator</code> reads successive elements from the directory for
+which it was constructed, as if by calling POSIX
+<code>
+readdir_r()</code>. After a <code>directory_iterator</code> is constructed, and every time
+<code>operator++</code> is called,
+it reads a directory element and stores information about it in a object of type <code>
+directory_entry</code>.
+<code>operator++</code> is not equality preserving; that is, <code>i == j</code> does not imply that
+<code>++i == ++j</code>. 
+<blockquote>
+[Note: The practical consequence of not preserving equality is that directory iterators
+can only be used for single-pass algorithms. --end note]
+</blockquote>
+If the end of the directory elements is reached, the iterator becomes equal to
+the end iterator value. The constructor <code>directory_iterator()</code>
+with no arguments always constructs an end iterator object, which is the only
+legitimate iterator to be used for the end condition. The result of <code>
+operator*</code> on an end iterator is not defined. For any other iterator value
+a <code>const directory_entry&</code> is returned. The result of
+<code>operator-></code> on an end iterator is not defined. For any other iterator value a <code>const directory_entry*</code> is
+returned. 
+Two end iterators are always equal. An end iterator is not equal to a non-end
+iterator.
+<blockquote>
+The above wording is based on the
+Standard Library's istream_iterator wording.
+</blockquote>
+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>. 
+Directory iteration shall not yield directory entries for the current (dot)
+and parent (dot dot) directories.
+The order of directory entries obtained by dereferencing successive
+increments of a <code>directory_iterator</code> is unspecified.
+<blockquote>
+[Note: 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
+to avoid following symbolic links.
+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
+POSIX
+<code>
+readdir_r()</code>. 
+--end note]
+</blockquote>
+<h4><a name="directory_iterator-members"><code>directory_iterator</code> members</a></h4>
+
+<code><a name="directory_iterator-default-ctor">directory_iterator</a>();</code>
+
+<blockquote>
+
+Effects: Constructs the end iterator.
+
+Throws: Nothing.
+
+</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>
+<blockquote>
+
+Effects: Constructs a iterator representing the first
+entry in the directory <code>p</code> resolves to, if any; otherwise, the end iterator.
+
+Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+
+[Note: To iterate over the current directory, use <code>
+directory_iterator(".")</code> rather than <code>directory_iterator("")</code>.
+-- end note]
+</blockquote>
+<pre>directory_iterator& <a name="directory_iterator-increment">operator++</a>();
+directory_iterator& increment(system::error_code& ec);</pre>
+<blockquote>
+
+Effects: As specified by the C++ Standard, 24.1.1 Input iterators [input.iterators]
+
+Returns: <code>*this</code>.
+
+Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+
+</blockquote>
+<h3><a name="Class-recursive_directory_iterator">Class <code>recursive_directory_iterator</code></a></h3>
+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.
+<pre>$NAMESPACE_BEGIN;
+ class recursive_directory_iterator :
+ public iterator<input_iterator_tag, directory_entry>
+ {
+ public:
+
+ // constructors and destructor
+ recursive_directory_iterator();
+ recursive_directory_iterator(const recursive_directory_iterator&);
+ explicit recursive_directory_iterator(const path& p,
+ BOOST_SCOPED_ENUM(symlink_option) opt = symlink_option::none);
+ recursive_directory_iterator(const path& p,
+ BOOST_SCOPED_ENUM(symlink_option) opt, system::error_code& ec);
+ recursive_directory_iterator(const path& p, system::error_code& ec);
+ ~recursive_directory_iterator();
+
+ // observers
+ int level() const;
+ bool no_push<code>_pending</code>() const;
+
+ // modifiers
+ recursive_directory_iterator& operator=(const recursive_directory_iterator&);
+
+ recursive_directory_iterator& operator++();
+ recursive_directory_iterator& increment(system::error_code& ec);
+
+ void pop();
+ void no_push(bool value=true);
+
+ // other members as required by
+ // C++ Std, 24.1.2 Input iterators [input.iterators]
+
+ private:
+ // actual data members will probably be stored in a shared pimpl object,
+ // or some similar mechanism, to achieve the required input iterator copy semantics
+ int m_level; // for exposition only
+ bool m_no_<code>push</code>; // for exposition only
+ BOOST_SCOPED_ENUM(symlink_option) m_options; // for exposition only
+ };
+
+$NAMESPACE_END;</pre>
+
+The behavior of a <code>recursive_directory_iterator</code> is the same
+as a <code>directory_iterator</code> unless otherwise specified.
+<ul>
+ <li>Incrementing a <code>recursive_directory_iterator</code> pointing to a
+ directory causes that directory itself to be iterated ovee, as specified by
+ the <code>operator++</code> and <code>increment</code> functions. 
+ </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
+ decremented, and iteration of the parent directory continues.</li>
+</ul>
+<pre>recursive_directory_iterator();</pre>
+<blockquote>
+
+Effects: Constructs the end iterator.
+
+Throws: Nothing.
+
+</blockquote>
+
+<pre>explicit recursive_directory_iterator(const path& p, BOOST_SCOPED_ENUM(symlink_option) opt = symlink_option::none);
+recursive_directory_iterator(const path& p, BOOST_SCOPED_ENUM(symlink_option) opt, system::error_code& ec);
+recursive_<code>directory_iterator(</code>const path& p, system::error_code& ec<code>);</code></pre>
+<blockquote>
+
+Effects:  Constructs a iterator representing the first
+entry in the directory <code>p</code> resolves to, if any; otherwise, the end iterator.
+
+Postcondition: Unless the end iterator was constructed, 
+<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>.
+
+Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+
+[Note: To iterate over the current directory, use <code>recursive_directory_iterator(".")</code> rather than
+<code>recursive_directory_iterator("")</code>.
+-- end note]
+
+[Note: 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>
+-- end note]
+</blockquote>
+<pre>int level() const;</pre>
+<blockquote>
+ Requires: <code>*this != recursive_directory_iterator()</code>.
+ Returns: <code>m_level</code>.
+ Throws: Nothing.
+</blockquote>
+<pre>bool <code>no_push_pending</code>() const;</pre>
+<blockquote>
+ Requires: <code>*this != recursive_directory_iterator()</code>.
+ Returns: <code>m_no_push</code>.
+ Throws: Nothing.
+</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>
+
+Effects: As specified by the C++ Standard, 24.1.1 Input iterators [input.iterators],
+except:
+
+<ul>
+ <li dir="ltr">
+
+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. 
+ 
+
+ </li>
+ <li>if there are no more directory entries at this level then <code>m_level</code>
+is decremented and iteration of the parent directory resumes.</li>
+</ul>
+
+Postcondition: <code>no_push_pending() == false</code>.
+
+Returns: <code>*this</code>.
+
+Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+
+</blockquote>
+<pre>void pop();</pre>
+<blockquote>
+ Requires: <code>*this != recursive_directory_iterator()</code>.
+ Effects: 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
+ iterated over, and continue iteration over the parent directory.
+ Throws: Nothing.
+</blockquote>
+<pre>void no_push(bool value=true);</pre>
+<blockquote>
+ Requires: <code>*this != recursive_directory_iterator()</code>.
+Postcondition: <code>no_push_pending() == value</code>.
+ Throws: Nothing.
+ [Note: <code>no_push()</code> is used to prevent
+ unwanted recursion into a directory. --end note]
+</blockquote>
+<h3><a name="Operational-functions">Operational functions</a></h3>
+Operational functions query or modify files, including directories, in external
+storage.
+Operational functions access a file by resolving an
+object of class <code>path</code> to a particular file in a file hierarchy. The
+path is resolved as if by the POSIX
+<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_11">
+Pathname Resolution</a> mechanism.
+[Note: Because hardware failures, network failures,
+race conditions, and many
+other kinds of errors occur frequently in file system operations, users should be aware
+that any filesystem operational function, no matter how apparently innocuous, may encounter
+an error. See Error reporting. -- end note]
+<h4><a name="Function-specifications">Operational function specifications</a></h4>
+<pre>path <a name="absolute">absolute</a>(const path& p, const path& base=current_path());</pre>
+ <blockquote>
+ Returns: A absolute path composed according to the
+ following table
+ <table border="1" cellpadding="5" cellspacing="0" bordercolor="#111111" style="border-collapse: collapse">
+ <tr>
+ <td align="center"> </td>
+ <td align="center"><code>p.has_root_directory()</code></td>
+ <td align="center"><code>!p.has_root_directory()</code></td>
+ </tr>
+ <tr>
+ <td align="center"><code>p.has_root_name()</code></td>
+ <td align="center"><code>return p</code></td>
+ <td align="center"><code>return p.root_name() /
+ absolute(base).root_directory() 
+ / absolute(base).relative_path() / p.relative_path()</code></td>
+ </tr>
+ <tr>
+ <td align="center"><code>!p.has_root_name()</code></td>
+ <td align="center"><code>return absolute(base).root_name() 
+ / p</code></td>
+ <td align="center"><code>return absolute(base) / p</code></td>
+ </tr>
+ </table>
+ [Note: For the returned path, <code>rp,</code> <code>
+ rp.is_absolute()</code> is true. -- end note]
+ Throws: If <code>base.is_absolute()</code> is true, throws only if
+ memory allocation fails.
+</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>
+Overview: Converts <code>p</code>, which must exist, to an absolute
+path that has no symbolic link, dot,
+or dot-dot elements. 
+Returns: A canonical path 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>.
+ Throws:  As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+
+ Remarks: <code>!exists(p)</code> is an error.
+
+ [Note: Canonical pathnames allow security checking of a path (eg.
+ does this path live in /home/goodguy or /home/badguy?)  -- end note]
+
+</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>
+ Effects: As if
+
+ <blockquote>
+ <pre>file_status s(symlink_status(from[<code>, ec</code>]));
+if(is_symlink(s))
+ copy_symlink(from, to[<code>, ec</code>]);
+else if(is_directory(s))
+ copy_directory(from, to[<code>, ec</code>]);
+else if(is_regular_file(s))
+ copy_file(from, to, copy_option::fail_if_exists[<code>, ec</code>]);
+else
+ Report error as specified in Error reporting.</pre>
+ </blockquote>
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+
+</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>
+<blockquote>
+ Effects: 
+
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+
+</blockquote>
+<pre>void copy_file(const path& from, const path& to);
+void copy_file(const path& from, const path& to, system::error_code& ec);</pre>
+<blockquote>
+ Effects: <code>copy_file(from, to,
+ copy_option::fail_if_exists</code>[<code>, ec</code>]<code>)</code>.
+
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+
+</blockquote>
+<pre>void <a name="copy_file">copy_file</a>(const path& from, const path& to, BOOST_SCOPED_ENUM(copy_option) option);
+void <a name="copy_file2">copy_file</a>(const path& from, const path& to, BOOST_SCOPED_ENUM(copy_option) option, system::error_code& ec);</pre>
+<blockquote>
+ Effects: If <code>option == copy_option::</code><code>fail_if_exists
+ && exists(to)</code>, an error is reported. Otherwise, the contents and attributes of the file <code>from</code>
+ resolves to are copied to the file <code>to</code> resolves to.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+</blockquote>
+<pre>void <a name="copy_symlink">copy_symlink</a>(const path& existing_symlink, const path& new_symlink);
+void copy_symlink(const path& existing_symlink, const path& new_symlink, system::error_code& ec);</pre>
+<blockquote>
+ Effects: <code>create_symlink(read_symlink(existing_symlink</code>[<code>, ec</code>]<code>),
+ new_symlink</code>[<code>, ec</code>]<code>)</code>.
+
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+
+</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>
+ Requires: <code>p.empty() || 
+ forall px: px == p || is_parent(px, p): is_directory(px) || !exists( px )</code>
+ 
+ Postcondition: <code>is_directory(p)</code>
+ Returns: The value of <code>!exists(p)</code> prior to the
+ establishment of the postcondition.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+</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>
+ Effects: Attempts to create the directory <code>p</code> resolves to,
+ as if by POSIX <code>
+ mkdir()</code> with a second argument of S_IRWXU|S_IRWXG|S_IRWXO. 
+ Postcondition: <code>is_directory(p)</code>
+ Returns: <code>true</code> if a new directory was created, otherwise
+ <code>false</code>.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+</blockquote>
+<pre>void <a name="create_directory_symlink">create_directory_symlink</a>(const path& to, const path& new_symlink);
+void create_directory_symlink(const path& to, const path& new_symlink, system::error_code& ec);</pre>
+<blockquote style="font-size: 10pt">
+ Effects:
+ Establishes the postcondition, as if by 
+ POSIX
+ <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/symlink.html">
+ symlink()</a></code>.
+ 
+ Postcondition: <code>new_symlink</code> resolves to a symbolic link file that
+ contains an unspecified representation of <code>to</code>.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+ [Note:
+ 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> -- end note]
+ [Note:
+ Some operating systems do not support symbolic links at all or support
+ them only for regular files. Windows prior to Vista, for example, did not
+ support symbolic links.
+ Some file systems do not
+ support
+ symbolic links regardless of the operating system - the FAT system used on floppy discs, memory cards and flash
+ drives,
+ for example. Thus symbolic links should only be used if these situations are
+ not concerns, or if workarounds are provided. -- end note]
+ </blockquote>
+<pre>void <a name="create_hard_link">create_hard_link</a>(const path& to, const path& new_hard_link);
+void <a name="create_hard_link2">create_hard_link</a>(const path& to, const path& new_hard_link, system::error_code& ec);</pre>
+<blockquote>
+ Effects: Establishes the postcondition, as if by
+ POSIX
+ <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/link.html">
+ link()</a></code>.
+ Postcondition:
+ <ul>
+ <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>
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+ [Note:
+ Some operating systems do not support hard links at all or support
+ them only for regular files. Some file systems do not support hard
+ links regardless of the operating system - the FAT system used on floppy
+ discs, memory cards and flash drives, for example. Some file systems limit the
+ number of links per file. Thus hard links should only be used if these
+ situations are not concerns, or if workarounds are provided. -- end note]
+ </blockquote>
+<pre>void <a name="create_symlink">create_symlink</a>(const path& to, const path& new_symlink);
+void <a name="create_symlink2">create_symlink</a>(const path& to, const path& new_symlink, system::error_code& ec);</pre>
+<blockquote style="font-size: 10pt">
+ Effects:
+ Establishes the postcondition, as if by 
+ POSIX
+ <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/symlink.html">
+ symlink()</a></code>.
+ 
+ Postcondition: <code>new_symlink</code> resolves to a symbolic link file that
+ contains an unspecified representation of <code>to</code>.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+ [Note:
+ Some operating systems do not support symbolic links at all or support
+ them only for regular files. Windows prior to Vista, for example, did not
+ support symbolic links.
+ Some file systems do not
+ support
+ symbolic links regardless of the operating system - the FAT system used on floppy discs, memory cards and flash
+ drives,
+ for example. Thus symbolic links should only be used if these situations are
+ not concerns, or if workarounds are provided. -- end note]
+ </blockquote>
+<pre>path <a name="current_path">current_path</a>();
+path <a name="current_path2">current_path</a>(system::error_code& ec);</pre>
+<blockquote>
+ Returns: The current working directory path, as if by POSIX
+ <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/getcwd.html">
+ getcwd()</a></code>. <code>is_absolute()</code> is true for the returned path.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+ [Note: The <code>
+ current_path()</code> name was chosen to emphasize that the return is a
+ path, not just a single directory name.
+ 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.  -- end note]
+</blockquote>
+<pre>void current_path(const path& p);
+void current_path(const path& p, system::error_code& ec);</pre>
+<blockquote>
+ Effects:
+ Establishes the postcondition, as if by 
+ POSIX
+ <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/chdir.html">
+ chdir()</a></code>.
+Postcondition: <code>equivalent(p, current_path())</code>.
+Throws: As specified in
+<a href="#Error-reporting">
+Error reporting</a>.
+ [Note: 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.  -- end note]
+</blockquote>
+<pre>bool <a name="exists">exists</a>(file_status s);</pre>
+<blockquote>
+ Returns:
+ <code>status_known(s) && s.type() != file_not_found</code>
+ Throws: Nothing.
+</blockquote>
+<pre>bool <a name="exists2">exists</a>(const path& p);
+bool <a name="exists3">exists</a>(const path& p, system::error_code& ec);</pre>
+<blockquote>
+ Returns: <code>exists(status(p))</code> or <code>exists(status(p, ec))</code>,
+ respectively.
+Throws: <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+nothing.
+</blockquote>
+<pre><code>bool <a name="equivalent">equivalent</a>(const path& p1, const path& p2);
+bool <a name="equivalent2">equivalent</a>(const path& p1, const path& p2, system::error_code& ec);</code></pre>
+<blockquote style="font-size: 10pt">
+ Effects: Determines <code>file_status s1</code>
+ and <code>s2</code>, as if by <code>status(p1)</code> and  <code>status(p2)</code>,
+ respectively.
+ Returns: <code>true</code>, if <code>sf1 ==
+ sf2</code> and <code>p1</code> and <code>p2</code> resolve to the same file
+ system entity, else <code>false</code>.
+ <blockquote>
+ Two paths are considered to resolve to the same
+ file system entity if two candidate entities reside on the same device at the
+ same location. This is determined as if by the values of the POSIX
+ <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.
+ [Note: POSIX requires that "st_dev
+ must be unique within a Local Area Network". Conservative POSIX
+ implementations may also wish to check for equal <code>st_size</code> and
+ <code>st_mtime</code> values. Windows implementations may use <code>
+ GetFileInformationByHandle()</code> as a surrogate for <code>stat()</code>,
+ and consider "same" to be equal values for <code>dwVolumeSerialNumber</code>,
+ <code>nFileIndexHigh</code>, <code>nFileIndexLow</code>, <code>nFileSizeHigh</code>,
+ <code>nFileSizeLow</code>, <code>ftLastWriteTime.dwLowDateTime</code>, and
+ <code>ftLastWriteTime.dwHighDateTime</code>. -- end note]
+ </blockquote>
+ Throws: <code>filesystem_error</code>
+ if <code>(!exists(s1) && !exists(s2)) || (is_other(s1) && is_other(s2))</code>,
+ otherwise as specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+</blockquote>
+<div dir="ltr">
+<pre>uintmax_t <a name="file_size">file_size</a>(const path& p);
+uintmax_t <a name="file_size2">file_size</a>(const path& p, system::error_code& ec);</pre>
+</div>
+<blockquote>
+ 
+ Remarks: 
+ 
+ Returns: If <code>exists(p) && is_regular_file(p)</code>, the size
+ in bytes
+ of the file <code>p</code> resolves to, determined as if by the value of
+ the POSIX <code>
+ stat</code> structure member <code>st_size</code>
+ obtained as if by POSIX <code>
+ stat()</code>.
+ Otherwise, <code>static_cast<uintmax_t>(-1)</code>.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+</blockquote>
+<pre>uintmax_t <a name="hard_link_count">hard_link_count</a>(const path& p);
+uintmax_t hard_link_count(const path& p, system::error_code& ec);</pre>
+<blockquote>
+
+ Returns: The number of hard links for <code>p</code>.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+
+</blockquote>
+
+<pre>const path& <a name="initial_path">initial_path</a>();
+const path& <a name="initial_path">initial_path</a>(<code>system::error_code& ec</code>);</pre>
+<blockquote>
+ Returns:
+ <code>current_path()</code> as of the first call to <code>initial_path()</code>.
+ [Note: <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().  --end note]
+ Throws: For the first call, as specified in
+ <a href="#Error-reporting">
+ Error reporting</a>. Subsequent calls throw nothing.
+</blockquote>
+<pre>bool <code><a name="is_directory">is_directory</a></code>(file_status s);</pre>
+<blockquote>
+ Returns:
+ <code>s.type() == directory_file</code>
+ Throws: Nothing.
+</blockquote>
+<pre><code>bool <a name="is_directory2">is_directory</a>(const path& p);
+bool <a name="is_directory3">is_directory</a>(const path& p, system::error_code& ec);</code></pre>
+<blockquote>
+ Returns: <code>is_directory(status(p))</code> or <code>is_directory(status(p, ec))</code>,
+ respectively.
+Throws: <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+nothing.
+</blockquote>
+<pre><code>bool <a name="is_empty">is_empty</a>(const path& p);
+bool <a name="is_empty2">is_empty</a></a>(const path& p, system::error_code& ec);</code></pre>
+<blockquote>
+ Effects: Determines <code>file_status s</code>, as if by <code>
+ status(p, ec)</code>.
+ Returns: <code>is_directory(s) 
+         ?
+ directory_iterator(p) == directory_iterator() 
+         : file_size(p) == 0;</code>
+</blockquote>
+<pre>bool <code><a name="is_regular_file">is_regular_file</a></code>(file_status s);</pre>
+<blockquote>
+ Returns:
+ <code>s.type() == regular_file</code>
+ Throws: Nothing.
+</blockquote>
+<pre><code>bool <a name="is_regular_file2">is_regular_file</a>(const path& p);</code></pre>
+<blockquote>
+ Returns: <code>is_regular_file(status(p))</code>.
+ Throws: <code>filesystem_error</code>
+ if <code>status(p)</code> would throw <code>filesystem_error.</code>
+ </blockquote>
+<pre><code>bool <a name="is_regular_file3">is_regular_file</a>(const path& p, system::error_code& ec);</code></pre>
+<blockquote>
+ Effects: Sets <code>ec</code> as if by <code>status(p, ec)</code>. [Note:
+ <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. -- end
+ note] 
+ Returns: <code>is_regular_file(status(p, ec))</code>.
+ Throws: Nothing.
+</blockquote>
+<pre>bool <a name="is_other">is_other</a>(file_status s);</pre>
+<blockquote>
+ Returns:
+ <code>return exists(s) && !is_regular_file(s) && !is_directory(s) && !is_symlink(s)</code>
+ Throws: Nothing.
+</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);</code></pre>
+<blockquote>
+ Returns: <code>is_other(status(p))</code> or <code>is_other(status(p, ec))</code>,
+ respectively.
+ Throws: <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+ nothing.
+</blockquote>
+<pre>bool <a name="is_symlink">is_symlink</a>(file_status s);</pre>
+<blockquote>
+ Returns:
+ <code>s.type() == symlink_file</code>
+ Throws: Nothing.
+</blockquote>
+<pre><code>bool <a name="is_symlink2">is_symlink</a>(const path& p);
+bool <a name="is_symlink3">is_symlink</a>(const path& p, system::error_code& ec);</code></pre>
+<blockquote>
+ Returns: <code>is_symlink(symlink_status(p))</code> or <code>is_symlink(symlink_status(p, ec))</code>,
+ respectively.
+ Throws: <code>filesystem_error</code>; overload with <code>error_code&</code> throws
+ nothing.
+</blockquote>
+<pre>std::time_t <a name="last_write_time">last_write_time</a>(const path& p);
+std::time_t <a name="last_write_time2">last_write_time</a>(const path& p<code>, system::error_code& ec</code>);</pre>
+<blockquote>
+ Returns: The time of last data modification of <code>p</code>, determined as if by the
+ value of the POSIX <code>
+ stat</code> structure member <code>st_mtime</code>  obtained
+ as if by POSIX <code>
+ stat()</code>.
+</blockquote>
+<pre>void <a name="last_write_time3">last_write_time</a>(const path& p, const std::time_t new_time);
+void <a name="last_write_time4">last_write_time</a>(const path& p, const std::time_t new_time<code>, system::error_code& ec</code>);</pre>
+<blockquote>
+ Effects: Sets the time of last data modification of the file
+ resolved to by <code>p</code>
+ to <code>new_time</code>, as if by POSIX <code>
+ stat()</code>
+ followed by POSIX
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/utime.html">
+ <code>utime()</code></a>.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+ [Note: A postcondition of <code>last_write_time(p) ==
+ new_time</code> is not specified since it might not hold for file systems
+ with coarse time granularity. -- end note]
+</blockquote>
+<pre>void permissions(const path& p, perms prms);
+void permissions(const path& p, perms prms, system::error_code& ec);</pre>
+<blockquote>
+ Applies an operating system set of permissions to a file. See
+ perms for specifics. 
+ 
+ Requires: <code>!((prms & add_perms) && (prms & remove_perms))</code>.
+ Effects: Applies the effective permissions bits from <code>
+ prms</code> to the file <code>p</code> resolves to, as if by POSIX
+ <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. 
+ <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
+ <tr>
+ <td>bits present in <code>prms</code></td>
+ <td>Effective bits applied</td>
+ </tr>
+ <tr>
+ <td>Neither <code>add_perms</code> nor <code>remove_perms</code></td>
+ <td><code>prms & perms_mask</code></td>
+ </tr>
+ <tr>
+ <td><code>add_perms</code></td>
+ <td>
+ current_status.permissions() | (<code>prms & perms_mask</code>)
+ </td>
+ </tr>
+ <tr>
+ <td><code>remove_perms</code></td>
+ <td>current_status.permissions() & ~(<code>prms & perms_mask</code>) </td>
+ </tr>
+ </table>
+ [Note: Conceptually permissions are viewed as bits, but the actual
+ implementation by a file system may use some other mechanism. -- end note]
+</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>
+ Returns:  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.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>. [Note: It is an error if <code>p</code> does not
+ resolve to a symbolic link. -- end note]
+</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>
+ Effects:  If <code>exists(symlink_status(p,ec))</code>, it is
+ removed
+ as if by POSIX <code>
+ remove()</code>.
+ <blockquote>
+ [Note: A symbolic link is itself removed, rather than the file it
+ resolves to being removed. -- end note]
+ </blockquote>
+ Postcondition: <code>!exists(symlink_status(p))</code>.
+ Returns:  <code>false</code> if p did not exist in the first
+ place, otherwise <code>true</code>.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+</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>
+ Effects:  Recursively deletes the contents of p if it exists,
+ then deletes file <code>p</code> itself,
+ as if by POSIX <code>
+ remove()</code>.
+ <blockquote>
+ [Note: A symbolic link is itself removed, rather than the file it
+ resolves to being removed. -- end note]
+ </blockquote>
+ Postcondition: <code>!exists(p)</code>
+ Returns: The number of files removed.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+</blockquote>
+<pre>void <a name="rename">rename</a>(const path& old_p, const path& new_p);
+void <a name="rename2">rename</a>(const path& old_p, const path& new_p, system::error_code& ec);</pre>
+<blockquote>
+ Effects: Renames <code>old_p</code> to <code>new_p</code>, as if by
+ POSIX <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/rename.html">
+ rename()</a></code>.
+ <blockquote>
+ [Note: If <code>old_p</code> and <code>new_p</code> resolve to the
+ same existing file, no action is taken. Otherwise, if <code>new_p</code> resolves to an
+ existing non-directory file, it is removed, while if <code>new_p</code> resolves to an
+ existing directory, it is removed if empty on POSIX but is an error on Windows. A symbolic link is itself renamed, rather than
+ the file it resolves to being renamed. -- end note]
+ </blockquote>
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+</blockquote>
+<pre>void <a name="resize_file">resize_file</a>(const path& p, uintmax_t new_size);
+void <a name="resize_file2">resize_file</a>(const path& p, uintmax_t new_size, system::error_code& ec);</pre>
+<blockquote>
+Postcondition: <code>file_size() == new_size</code>.
+Throws: As specified in
+<a href="#Error-reporting">
+Error reporting</a>.
+ Remarks: Achieves its postconditions as if by
+ POSIX <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/truncate.html">
+ truncate()</a></code>.
+</blockquote>
+<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>
+ Returns: An object of type <code>
+ space_info</code>. The value of the <code>space_info</code> object is determined as if by
+ using POSIX <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/statvfs.html" style="text-decoration: none">
+ statvfs()</a></code> to obtain a POSIX 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
+ value cannot be determined shall be set to -1.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+</blockquote>
+<pre>file_status <a name="status">status</a>(const path& p);</pre>
+<blockquote>
+ Effects: As if:
+ <blockquote>
+ <pre>system::error_code ec;
+file_status result = status(p, ec);
+if (result == status_error)
+ throw filesystem_error(implementation-supplied-message, p, ec);
+return result;</pre>
+ </blockquote>
+ Returns: See above.
+ Throws: <code>filesystem_error</code>.
+[Note: <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. -- end note] 
+ </blockquote>
+<pre>file_status <a name="status2">status</a>(const path& p, system::error_code& ec);</pre>
+<blockquote>
+ Effects: 
+ <blockquote>
+ If possible, determines the attributes
+ of the file
+ <code>p</code> resolves to, as if by POSIX <code>
+ stat()</code>.
+ If, during attribute determination, the underlying file system API reports
+ an error, sets <code>ec</code> to indicate the specific error reported.
+ Otherwise, <code>ec.clear()</code>.<blockquote>
+ [Note: 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>.  --end note]
+ </blockquote>
+ </blockquote>
+ Returns:
+ <blockquote>
+ If <code>ec != error_code()</code>:
+ <ul>
+ <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>. [Note: POSIX 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. --
+ end note] 
+ </li>
+ <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>. [Note: For example, Windows
+ ERROR_SHARING_VIOLATION errors. For POSIX, the case never arises. -- end
+ note] 
+ </li>
+ <li>Otherwise, return <code>
+ file_status(status_error)</code>.</li>
+ </ul>
+ <blockquote>
+ [Note: 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. --end note]
+ </blockquote>
+ Otherwise,
+ <ul>
+ <li>If the attributes indicate a regular file, as if by POSIX S_ISREG(),
+ return <code>
+ file_status(regular_file)</code>. [Note: <code>
+regular_file</code> implies appropriate <code><fstream></code> operations
+ would succeed, assuming no hardware, permission, access, or race condition
+ errors. Lack of
+<code>regular_file</code> does not necessarily imply <code><fstream></code> operations would
+fail on a directory.
+-- end note] 
+ </li>
+ <li>Otherwise, if the attributes indicate a directory, as if by POSIX
+ S_ISDIR(),
+ return <code>
+ file_status(directory_file)</code>. [Note: <code>directory_file</code> implies <code>
+directory_iterator(p)</code>would succeed.
+-- end note] 
+ </li>
+ <li>Otherwise, if the attributes indicate a block special file, as if by POSIX
+ S_ISBLK(),
+ return <code>
+ file_status(block_file)</code>. 
+ </li>
+ <li>Otherwise, if the attributes indicate a character special file, as if by POSIX
+ S_ISCHR(),
+ return <code>
+ file_status(character_file)</code>. 
+ </li>
+ <li>Otherwise, if the attributes indicate a fifo or pipe file, as if by POSIX
+ S_ISFIFO(),
+ return <code>
+ file_status(fifo_file)</code>. 
+ </li>
+ <li>Otherwise, if the attributes indicate a socket, as if by POSIX
+ S_ISSOCK(),
+ return <code>
+ file_status(socket_file)</code>. 
+ </li>
+ <li>Otherwise, return <code>
+ file_status(type_unknown)</code>.</li>
+ </ul>
+ </blockquote>
+Throws: Nothing.
+ Remarks: If a symbolic link is encountered during pathname
+ resolution,
+ pathname resolution continues using the contents of the symbolic link.
+</blockquote>
+<pre>bool <a name="status_known">status_known</a>(file_status s);</pre>
+<blockquote>
+ Returns:
+ <code>s.type() != status_error</code>
+ Throws: Nothing.
+</blockquote>
+<pre>file_status <a name="symlink_status">symlink_status</a>(const path& p);
+file_status <a name="symlink_status2">symlink_status</a>(const path& p, system::error_code& ec);</pre>
+<blockquote>
+ Effects:  Same as status(), above,
+ except that the attributes
+ of
+ <code>p</code> are determined as if by POSIX <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/lstat.html">
+ lstat()</a></code>.
+</blockquote>
+<blockquote>
+ Returns: Same as status(), above, except
+ that if the attributes indicate a symbolic link, as if by POSIX
+ <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>.
+Throws: Nothing.
+ Remarks: Pathname resolution terminates if <code>p</code> names a symbolic link.
+</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>
+ Effects: 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.
+ Returns: The composed path.
+ Postcondition: For the returned path, <code>rp,</code> <code>
+ rp.is_absolute()</code> is true.
+ [Note: For POSIX, <code>system_complete(p)</code> has the same semantics as
+ <code>complete(p, current_path())</code>.
+ <a name="windows_effects">For Windows</a>, <code>system_complete(p)</code> has the
+ 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 residue left over from a prior program run by the command
+ processor! Although these semantics are often useful, they are also very
+ error-prone.
+ See <a href="#complete_note">
+ complete() note</a> for usage suggestions. -- end note]
+</blockquote>
+<pre>path <a name="temp_directory_path">temp_directory_path</a>();
+path temp_directory_path(system::error_code& ec);</pre>
+<blockquote>
+ Returns: 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.
+ POSIX: The path supplied by the first environment variable found in the
+ list TMPDIR, TMP, TEMP, TEMPDIR. If none of these are found, <code>"/tmp"</code>.
+ Windows: The path reported by the Windows <code>GetTempPath</code> API function.
+ Throws: As specified in <a href="#Error-reporting">
+ Error reporting</a>.
+ [Note: The <code>temp_directory_path()</code> name was chosen to emphasize that the return is a
+ path, not just a single directory name.  -- end note]
+</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>
+ 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. [Note: 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. --end note]
+ Returns: 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.
+ Throws: As specified in
+ <a href="#Error-reporting">
+ Error reporting</a>.
+ Remarks: 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. [Note: Such generators may block
+ until sufficient entropy develops. --end note]
+</blockquote>
+<h3><a name="File-streams">File streams</a> -
+<boost/filesystem/fstream.hpp></h3>
+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
+semantics.
+<pre>$NAMESPACE_BEGIN;
+ template < class charT, class traits = std::char_traits<charT> >
+ class basic_filebuf : public std::basic_filebuf<charT,traits>
+ {
+ public:
+ basic_filebuf<charT,traits>*
+ open(const path& p, std::ios_base::openmode mode);
+ };
+
+ template < class charT, class traits = std::char_traits<charT> >
+ class basic_ifstream : public std::basic_ifstream<charT,traits>
+ {
+ public:
+ explicit basic_ifstream(const path& p, std::ios_base::openmode mode=std::ios_base::in)
+ void open(const path& p, std::ios_base::openmode mode=std::ios_base::in);
+ };
+
+ template < class charT, class traits = std::char_traits<charT> >
+ class basic_ofstream : public std::basic_ofstream<charT,traits>
+ {
+ public:
+ explicit basic_ofstream(const path& p, std::ios_base::openmode mode=std::ios_base::out);
+ void open(const path& p, std::ios_base::openmode mode=std::ios_base::out);
+ };
+
+ template < class charT, class traits = std::char_traits<charT> >
+ class basic_fstream : public std::basic_fstream<charT,traits>
+ {
+ public:
+ explicit basic_fstream(const path& p,
+ std::ios_base::openmode mode=std::ios_base::in | std::ios_base::out);
+ void open(const path& p,
+ std::ios_base::openmode mode=std::ios_base::in | std::ios_base::out);
+ };
+
+ typedef basic_filebuf<char> filebuf;
+ typedef basic_ifstream<char> ifstream;
+ typedef basic_ofstream<char> ofstream;
+ typedef basic_fstream<char> fstream;
+
+ typedef basic_filebuf<wchar_t> wfilebuf;
+ typedef basic_ifstream<wchar_t> wifstream;
+ typedef basic_fstream<wchar_t> wfstream;
+ typedef basic_ofstream<wchar_t> wofstream;
+
+$NAMESPACE_END;</pre>
+<h2><a name="Path-decomposition-table">Path decomposition table</a></h2>
+The table is generated by a program compiled with the Boost implementation.
+Shaded entries indicate cases where POSIX and Windows
+implementations yield different results. The top value is the
+POSIX result and the bottom value is the Windows result. 
+<table border="1" cellspacing="0" cellpadding="5">
+
+<tr><td>Constructor argument</td>
+<td>Iteration over Elements</td>
+<td><code>string()</code></td>
+<td><code>generic_ string()</code></td>
+<td><code>root_ path()</code></td>
+<td><code>root_ name()</code></td>
+<td><code>root_ directory()</code></td>
+<td><code>relative_ path()</code></td>
+<td><code>parent_ path()</code></td>
+<td><code>filename()</code></td>
+</tr>
+<tr>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+</tr>
+<tr>
+<td><code>.</code></td>
+<td><code>.</code></td>
+<td><code>.</code></td>
+<td><code>.</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>.</code></td>
+<td>empty</td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>..</code></td>
+<td><code>..</code></td>
+<td><code>..</code></td>
+<td><code>..</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>..</code></td>
+<td>empty</td>
+<td><code>..</code></td>
+</tr>
+<tr>
+<td><code>foo</code></td>
+<td><code>foo</code></td>
+<td><code>foo</code></td>
+<td><code>foo</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>foo</code></td>
+<td>empty</td>
+<td><code>foo</code></td>
+</tr>
+<tr>
+<td><code>/</code></td>
+<td><code>/</code></td>
+<td><code>/</code></td>
+<td><code>/</code></td>
+<td><code>/</code></td>
+<td>empty</td>
+<td><code>/</code></td>
+<td>empty</td>
+<td>empty</td>
+<td><code>/</code></td>
+</tr>
+<tr>
+<td><code>/foo</code></td>
+<td><code>/,foo</code></td>
+<td><code>/foo</code></td>
+<td><code>/foo</code></td>
+<td><code>/</code></td>
+<td>empty</td>
+<td><code>/</code></td>
+<td><code>foo</code></td>
+<td><code>/</code></td>
+<td><code>foo</code></td>
+</tr>
+<tr>
+<td><code>foo/</code></td>
+<td><code>foo,.</code></td>
+<td><code>foo/</code></td>
+<td><code>foo/</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>foo/</code></td>
+<td><code>foo</code></td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>/foo/</code></td>
+<td><code>/,foo,.</code></td>
+<td><code>/foo/</code></td>
+<td><code>/foo/</code></td>
+<td><code>/</code></td>
+<td>empty</td>
+<td><code>/</code></td>
+<td><code>foo/</code></td>
+<td><code>/foo</code></td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>foo/bar</code></td>
+<td><code>foo,bar</code></td>
+<td><code>foo/bar</code></td>
+<td><code>foo/bar</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>foo/bar</code></td>
+<td><code>foo</code></td>
+<td><code>bar</code></td>
+</tr>
+<tr>
+<td><code>/foo/bar</code></td>
+<td><code>/,foo,bar</code></td>
+<td><code>/foo/bar</code></td>
+<td><code>/foo/bar</code></td>
+<td><code>/</code></td>
+<td>empty</td>
+<td><code>/</code></td>
+<td><code>foo/bar</code></td>
+<td><code>/foo</code></td>
+<td><code>bar</code></td>
+</tr>
+<tr>
+<td><code>//net</code></td>
+<td><code>//net</code></td>
+<td><code>//net</code></td>
+<td><code>//net</code></td>
+<td><code>//net</code></td>
+<td><code>//net</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>//net</code></td>
+</tr>
+<tr>
+<td><code>//net/foo</code></td>
+<td><code>//net,/,foo</code></td>
+<td><code>//net/foo</code></td>
+<td><code>//net/foo</code></td>
+<td><code>//net/</code></td>
+<td><code>//net</code></td>
+<td><code>/</code></td>
+<td><code>foo</code></td>
+<td><code>//net/</code></td>
+<td><code>foo</code></td>
+</tr>
+<tr>
+<td><code>///foo///</code></td>
+<td><code>/,foo,.</code></td>
+<td><code>///foo///</code></td>
+<td><code>///foo///</code></td>
+<td><code>/</code></td>
+<td>empty</td>
+<td><code>/</code></td>
+<td><code>foo///</code></td>
+<td><code>///foo</code></td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>///foo///bar</code></td>
+<td><code>/,foo,bar</code></td>
+<td><code>///foo///bar</code></td>
+<td><code>///foo///bar</code></td>
+<td><code>/</code></td>
+<td>empty</td>
+<td><code>/</code></td>
+<td><code>foo///bar</code></td>
+<td><code>///foo</code></td>
+<td><code>bar</code></td>
+</tr>
+<tr>
+<td><code>/.</code></td>
+<td><code>/,.</code></td>
+<td><code>/.</code></td>
+<td><code>/.</code></td>
+<td><code>/</code></td>
+<td>empty</td>
+<td><code>/</code></td>
+<td><code>.</code></td>
+<td><code>/</code></td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>./</code></td>
+<td><code>.,.</code></td>
+<td><code>./</code></td>
+<td><code>./</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>./</code></td>
+<td><code>.</code></td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>/..</code></td>
+<td><code>/,..</code></td>
+<td><code>/..</code></td>
+<td><code>/..</code></td>
+<td><code>/</code></td>
+<td>empty</td>
+<td><code>/</code></td>
+<td><code>..</code></td>
+<td><code>/</code></td>
+<td><code>..</code></td>
+</tr>
+<tr>
+<td><code>../</code></td>
+<td><code>..,.</code></td>
+<td><code>../</code></td>
+<td><code>../</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>../</code></td>
+<td><code>..</code></td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>foo/.</code></td>
+<td><code>foo,.</code></td>
+<td><code>foo/.</code></td>
+<td><code>foo/.</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>foo/.</code></td>
+<td><code>foo</code></td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>foo/..</code></td>
+<td><code>foo,..</code></td>
+<td><code>foo/..</code></td>
+<td><code>foo/..</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>foo/..</code></td>
+<td><code>foo</code></td>
+<td><code>..</code></td>
+</tr>
+<tr>
+<td><code>foo/./</code></td>
+<td><code>foo,.,.</code></td>
+<td><code>foo/./</code></td>
+<td><code>foo/./</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>foo/./</code></td>
+<td><code>foo/.</code></td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>foo/./bar</code></td>
+<td><code>foo,.,bar</code></td>
+<td><code>foo/./bar</code></td>
+<td><code>foo/./bar</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>foo/./bar</code></td>
+<td><code>foo/.</code></td>
+<td><code>bar</code></td>
+</tr>
+<tr>
+<td><code>foo/..</code></td>
+<td><code>foo,..</code></td>
+<td><code>foo/..</code></td>
+<td><code>foo/..</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>foo/..</code></td>
+<td><code>foo</code></td>
+<td><code>..</code></td>
+</tr>
+<tr>
+<td><code>foo/../</code></td>
+<td><code>foo,..,.</code></td>
+<td><code>foo/../</code></td>
+<td><code>foo/../</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>foo/../</code></td>
+<td><code>foo/..</code></td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>foo/../bar</code></td>
+<td><code>foo,..,bar</code></td>
+<td><code>foo/../bar</code></td>
+<td><code>foo/../bar</code></td>
+<td>empty</td>
+<td>empty</td>
+<td>empty</td>
+<td><code>foo/../bar</code></td>
+<td><code>foo/..</code></td>
+<td><code>bar</code></td>
+</tr>
+<tr>
+<td><code>c:</code></td>
+<td><code>c:</code></td>
+<td><code>c:</code></td>
+<td><code>c:</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>c:</code></td>
+<td>empty</td>
+<td><code>c:</code> empty</td>
+<td>empty</td>
+<td><code>c:</code></td>
+</tr>
+<tr>
+<td><code>c:/</code></td>
+<td><code>c:,.</code> <code>c:,/</code></td>
+<td><code>c:/</code></td>
+<td><code>c:/</code></td>
+<td>empty <code>c:/</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>/</code></td>
+<td><code>c:/</code> empty</td>
+<td><code>c:</code></td>
+<td><code>.</code> <code>/</code></td>
+</tr>
+<tr>
+<td><code>c:foo</code></td>
+<td><code>c:foo</code> <code>c:,foo</code></td>
+<td><code>c:foo</code></td>
+<td><code>c:foo</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>c:</code></td>
+<td>empty</td>
+<td><code>c:foo</code> <code>foo</code></td>
+<td>empty <code>c:</code></td>
+<td><code>c:foo</code> <code>foo</code></td>
+</tr>
+<tr>
+<td><code>c:/foo</code></td>
+<td><code>c:,foo</code> <code>c:,/,foo</code></td>
+<td><code>c:/foo</code></td>
+<td><code>c:/foo</code></td>
+<td>empty <code>c:/</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>/</code></td>
+<td><code>c:/foo</code> <code>foo</code></td>
+<td><code>c:</code> <code>c:/</code></td>
+<td><code>foo</code></td>
+</tr>
+<tr>
+<td><code>c:foo/</code></td>
+<td><code>c:foo,.</code> <code>c:,foo,.</code></td>
+<td><code>c:foo/</code></td>
+<td><code>c:foo/</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>c:</code></td>
+<td>empty</td>
+<td><code>c:foo/</code> <code>foo/</code></td>
+<td><code>c:foo</code></td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>c:/foo/</code></td>
+<td><code>c:,foo,.</code> <code>c:,/,foo,.</code></td>
+<td><code>c:/foo/</code></td>
+<td><code>c:/foo/</code></td>
+<td>empty <code>c:/</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>/</code></td>
+<td><code>c:/foo/</code> <code>foo/</code></td>
+<td><code>c:/foo</code></td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>c:/foo/bar</code></td>
+<td><code>c:,foo,bar</code> <code>c:,/,foo,bar</code></td>
+<td><code>c:/foo/bar</code></td>
+<td><code>c:/foo/bar</code></td>
+<td>empty <code>c:/</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>/</code></td>
+<td><code>c:/foo/bar</code> <code>foo/bar</code></td>
+<td><code>c:/foo</code></td>
+<td><code>bar</code></td>
+</tr>
+<tr>
+<td><code>prn:</code></td>
+<td><code>prn:</code></td>
+<td><code>prn:</code></td>
+<td><code>prn:</code></td>
+<td>empty <code>prn:</code></td>
+<td>empty <code>prn:</code></td>
+<td>empty</td>
+<td><code>prn:</code> empty</td>
+<td>empty</td>
+<td><code>prn:</code></td>
+</tr>
+<tr>
+<td><code>c:\</code></td>
+<td><code>c:\</code> <code>c:,/</code></td>
+<td><code>c:\</code></td>
+<td><code>c:\</code> <code>c:/</code></td>
+<td>empty <code>c:\</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>\</code></td>
+<td><code>c:\</code> empty</td>
+<td>empty <code>c:</code></td>
+<td><code>c:\</code> <code>\</code></td>
+</tr>
+<tr>
+<td><code>c:foo</code></td>
+<td><code>c:foo</code> <code>c:,foo</code></td>
+<td><code>c:foo</code></td>
+<td><code>c:foo</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>c:</code></td>
+<td>empty</td>
+<td><code>c:foo</code> <code>foo</code></td>
+<td>empty <code>c:</code></td>
+<td><code>c:foo</code> <code>foo</code></td>
+</tr>
+<tr>
+<td><code>c:\foo</code></td>
+<td><code>c:\foo</code> <code>c:,/,foo</code></td>
+<td><code>c:\foo</code></td>
+<td><code>c:\foo</code> <code>c:/foo</code></td>
+<td>empty <code>c:\</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>\</code></td>
+<td><code>c:\foo</code> <code>foo</code></td>
+<td>empty <code>c:\</code></td>
+<td><code>c:\foo</code> <code>foo</code></td>
+</tr>
+<tr>
+<td><code>c:foo\</code></td>
+<td><code>c:foo\</code> <code>c:,foo,.</code></td>
+<td><code>c:foo\</code></td>
+<td><code>c:foo\</code> <code>c:foo/</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>c:</code></td>
+<td>empty</td>
+<td><code>c:foo\</code> <code>foo\</code></td>
+<td>empty <code>c:foo</code></td>
+<td><code>c:foo\</code> <code>.</code></td>
+</tr>
+<tr>
+<td><code>c:\foo\</code></td>
+<td><code>c:\foo\</code> <code>c:,/,foo,.</code></td>
+<td><code>c:\foo\</code></td>
+<td><code>c:\foo\</code> <code>c:/foo/</code></td>
+<td>empty <code>c:\</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>\</code></td>
+<td><code>c:\foo\</code> <code>foo\</code></td>
+<td>empty <code>c:\foo</code></td>
+<td><code>c:\foo\</code> <code>.</code></td>
+</tr>
+<tr>
+<td><code>c:\foo/</code></td>
+<td><code>c:\foo,.</code> <code>c:,/,foo,.</code></td>
+<td><code>c:\foo/</code></td>
+<td><code>c:\foo/</code> <code>c:/foo/</code></td>
+<td>empty <code>c:\</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>\</code></td>
+<td><code>c:\foo/</code> <code>foo/</code></td>
+<td><code>c:\foo</code></td>
+<td><code>.</code></td>
+</tr>
+<tr>
+<td><code>c:/foo\bar</code></td>
+<td><code>c:,foo\bar</code> <code>c:,/,foo,bar</code></td>
+<td><code>c:/foo\bar</code></td>
+<td><code>c:/foo\bar</code> <code>c:/foo/bar</code></td>
+<td>empty <code>c:/</code></td>
+<td>empty <code>c:</code></td>
+<td>empty <code>/</code></td>
+<td><code>c:/foo\bar</code> <code>foo\bar</code></td>
+<td><code>c:</code> <code>c:/foo</code></td>
+<td><code>foo\bar</code> <code>bar</code></td>
+</tr>
+</table>
+<h2><a name="long-path-warning"></a>Warning: Long paths on Windows and the
+extended-length \\?\ prefix</h2>
+The Microsoft Windows "Maximum Path Length Limitation" specifies:
+<blockquote>
+In the Windows API (with some exceptions ...), the maximum length for a path
+is MAX_PATH, which is defined as 260 characters.
+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 "\\?\" prefix. For
+example, "\\?\D:\very long path". 
+[C++ string literals require backslashes be doubled, of course.]
+</blockquote>
+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!
+<h3>Cautions for paths with extended-length prefixes</h3>
+<ul>
+ <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
+ 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
+ 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
+ with extended-length prefix paths.</li>
+</ul>
+<h2><a name="Acknowledgements">Acknowledgements</a></h2>
+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.
+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>.
+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.
+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 psuedo-code.
+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.
+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.
+ 
+<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-POSIX</a>]</td>
+ <td width="84%">ISO/IEC 9945:2003, IEEE Std 1003.1-2001, and The Open Group
+ Base Specifications, Issue 6. Also known as The Single UnixÂ®
+ Specification, Version 3. Available from each of the organizations involved
+ 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>. 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>
+ <td width="16%" valign="top">[Abrahams]</td>
+ <td width="84%">Dave Abrahams, Error and Exception Handling,
+ <a href="http://www.boost.org/more/error_handling.html">
+ www.boost.org/more/error_handling.html</a></td>
+ </tr>
+</table>
+<hr>
+Â© Copyright Beman Dawes, 2002, 2006, 2007, 2009, 2010, 2011
+Distributed under the Boost Software License, Version 1.0. See
+
+www.boost.org/LICENSE_1_0.txt
+Revised
+10 January 2012
+
+</body>
+
+</html>
\ No newline at end of file

Added: trunk/libs/filesystem/v3/doc/src/tr2_snippets.html
==============================================================================
--- (empty file)
+++ trunk/libs/filesystem/v3/doc/src/tr2_snippets.html 2012-01-10 20:34:38 EST (Tue, 10 Jan 2012)
@@ -0,0 +1,126 @@
+<html>
+
+<head>
+<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
+<meta name="ProgId" content="FrontPage.Editor.Document">
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+<title>New Page 1</title>
+</head>
+
+<body>
+
+$id frontmatter=
+ <table border="0" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="579">
+ <tr>
+ <td width="153" align="left" valign="top">Document number:</td>
+ <td width="426">N3239 = 11-0009</td>
+ </tr>
+ <tr>
+ <td width="153" align="left" valign="top">Date:</td>
+ <td width="426">
+ 2012-01-10</td>
+ </tr>
+ <tr>
+ <td width="153" align="left" valign="top">Project:</td>
+ <td width="426">Programming Language C++, Library Working Group</td>
+ </tr>
+ <tr>
+ <td width="153" align="left" valign="top">Reply-to:</td>
+ <td width="426">Beman Dawes <bdawes at acm dot org></td>
+ </tr>
+ </table>
+
+
+<h1>Filesystem Library Update for TR2 (Preliminary)</h1>
+
+
+This paper proposes that the filesystem library component of C++ Standard
+Library Technical Report 2 be based on Version 3 of the Boost Filesystem
+Library (see <a href="http://www.boost.org/libs/filesystem">
+www.boost.org/libs/filesystem</a>). Preliminary wording is provided. A
+TODO list identifies remaining work to be done.
+
+
+<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1975.html">
+J16/06-0045 = WG21/N1975</a>, Filesystem Library Proposal for TR2 (Revision 3),
+was adopted by the committee in April, 2006, at the Berlin meeting. Shortly
+afterward the Library Working Group set aside work on TR2 to concentrate on
+C++0x. In the meantime, work on the Boost version of the Filesystem Library has
+continued, and Version 3 of the library has been released. Changes include:
+
+
+ <ul>
+ <li>A single class <code>path</code> handles all aspects of
+ internationalization, replacing the previous template and its <code>path</code>
+ and <code>wpath</code> instantiations. Character types <code>char</code>,
+ <code>wchar_t</code>, <code>char16_t</code>, and <code>char32_t</code> are
+ supported. This is a major simplification of the path abstraction,
+ particularly for functions that take path arguments. This change was based
+ on a suggestion by Peter Dimov. 
+ </li>
+ <li>Several operational functions have been added, including much better
+ symlink support, the ability to resize a file, and the ability to generate a
+ unique path. 
+ </li>
+ <li>Support for error reporting via <code>error_code</code> is now uniform
+ throughout the operations functions.| 
+ </li>
+ <li>Several functions have been renamed, based on feedback from users.</li>
+ </ul>
+
+
+<h2>Motivation and Scope</h2>
+
+
+The motivation and scope for a filesystem library were described in <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1975.html">
+N1975</a>, and are not repeated here. A minor scope reduction is that an
+addition to the current C++ runtime library is no longer needed.
+
+
+Boost Filesystem Version 3 introduced a single path type that interoperates well with both <code>
+basic_string</code> and user defined string types. Thus the following Design
+alternatives paragraph is no long applicable:
+
+
+ <blockquote>
+
+
+<strike>Single path type which can at runtime accept narrow or wide character
+pathnames. Although certainly interesting, and possibly superior, such a
+design would not interoperate well with the current Standard Library's
+compile-time typed <code>basic_string</code>. A new runtime polymorphic string
+class would be the best place to experiment with this concept, not a path class.</strike>
+
+
+ </blockquote>
+
+
+ <h2><a name="TODO">TODO</a></h2>
+ <ul>
+ <li>Apply C++0X features. Boost.Filesystem needs to implement these to verify their
+ application is correct.</li>
+ <li>Boost.Filesystem needs to implement <code>char16_t</code> and <code>char32_t</code> support to verify the
+ specification for these is correct.</li>
+ <li>Class <code>file_status</code> is overdesigned. It holds just a single <code>file_type</code> variable, and that's unlikely to change
+ because of performance considerations. It would be simpler to eliminate class <code>
+ file_status</code>, and just use <code>file_type</code> in its stead. Perhaps
+ rename to <code>file_status</code>. This hasn't been done in the Boost
+ because it would break existing code, albeit noisily.</li>
+ <li>Replace path inserter and extractor Effects with prose, since the
+ current wording relies on
+ <code>boost::io::quoted</code>.</li>
+ <li>Replace uses of <code>boost::iterator_facade</code>.</li>
+ <li><code>Source</code> is not specified as actually
+ implemented. Expose <code>path_traits</code>?</li>
+ <li>Effects for <code>copy</code> and <code>copy_directory</code>
+ need to be reviewed, revised, tested.</li>
+ <li>Review changes to header <fstream></li>
+ </ul>
+
+ <h2>Revisions</h2>
+ TBS
+
+ $endid
+</body>
+
+</html>
\ No newline at end of file

Next message: atompkins_at_[hidden]: "[Boost-commit] svn:boost r76405 - branches/release/boost/uuid"
Previous message: emil_at_[hidden]: "[Boost-commit] svn:boost r76403 - in trunk: boost/exception libs/exception/test"

Date view	Thread view	Subject view	Author view