Boost-Commit :

Date view	Thread view	Subject view	Author view

From: bdawes_at_[hidden]
Date: 2007-11-07 16:54:48

Author: bemandawes
Date: 2007-11-07 16:54:48 EST (Wed, 07 Nov 2007)
New Revision: 40912
URL: http://svn.boost.org/trac/boost/changeset/40912

Log:
Initial commit. The starting point for the reference documentation is N1975, Filesystem Library Proposal for TR2 (Revision 3).
Added:
trunk/libs/filesystem/doc/reference.html (contents, props changed)

Added: trunk/libs/filesystem/doc/reference.html
==============================================================================
--- (empty file)
+++ trunk/libs/filesystem/doc/reference.html 2007-11-07 16:54:48 EST (Wed, 07 Nov 2007)
@@ -0,0 +1,3588 @@
+<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>Filesystem Library Proposal
+</title>
+</head>
+
+<body bgcolor="#FFFFFF">
+
+Doc. no.   WG21/N1975=06-0045 
+Date:       
+2006-04-04 
+Project:     Programming Language C++ 
+Reply to:   Beman Dawes <<a href="mailto:bdawes_at_[hidden]">bdawes_at_[hidden]</a>>
+
+<h1>Filesystem Library Proposal for TR2 (Revision 3)</h1>
+
+<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="26%" valign="top">Introduction 
+Motivation and Scope 
+Impact on the Standard 
+Important Design Decisions 
+Proposed Text for TR2 
+    Introductory chapter 
+    Diagnostics library chapter 
+    Filesystem library chapter 
+        Definitions 
+        Requirements 
+           
+Requirements on programs 
+           
+Requirements 
+              
+on implementations 
+        <a href="#Header-filesystem-synopsis">
+ Header <filesystem> synopsis</a> 
+        Path traits 
+        <a href="#Class-template-basic_path">
+ Class template basic_path</a> 
+           
+Pathname formats 
+           
+Pathname grammar 
+           
+Filename conversion 
+           
+Requirements </td>
+ <td width="35%" valign="top"> Class template basic_path (continued) 
+           
+basic_path constructors 
+           
+basic_path assignments 
+           
+basic_path modifiers 
+           
+basic_path operators 
+           
+basic_path observers 
+           
+basic_path iterators 
+           
+basic_path non-member functions 
+           
+basic_path inserter and extractor 
+        
+<a href="#Class-template-basic_filesystem_error">Class template
+ basic_filesystem_error</a> 
+           
+<a href="#basic_filesystem_error-constructors">basic_filesystem_error
+ constructors</a> 
+           
+basic_filesystem_error observers 
+       
+<a href="#Class-template-basic_directory_entry">Class template
+ basic_directory_entry</a> 
+           
+basic_directory_entry constructors 
+           
+basic_directory_entry modifiers 
+           
+basic_directory_entry observers 
+           
+basic_directory_entry comparisons</td>
+ <td width="89%" valign="top">Filesystem library chapter (continued) 
+       
+<a href="#Class-template-basic_directory_iterator">Class template
+ basic_directory_iterator</a> 
+           
+<a href="#basic_directory_iterator-constructors">basic_directory_iterator
+ constructors</a> 
+       
+<a href="#Class-template-basic_recursive_directory_iterator">Class template
+ basic_recursive_directory_iterator</a> 
+        <a href="#file_status">Class
+ file_status</a> 
+        <a href="#Non-member-functions">
+ Non-member operational functions</a> 
+           
+Status functions 
+           
+Predicate functions 
+           
+Attribute functions 
+           
+Other operations functions 
+           
+Convenience functions 
+        <a href="#header-cerrno">Additions to
+ header <cerrno></a> 
+        <a href="#header-fstream">Additions
+ to header <fstream></a> 
+Suggestions for <fstream><code> 
+  </code>
+ implementations 
+Path decomposition table 
+Issues 
+Acknowledgements 
+References 
+<a href="#Revision-History">Revision
+History</a></td>
+ </tr>
+</table>
+
+<h2><a name="Introduction">Introduction</a></h2>
+This paper proposes addition of a filesystem library component
+to the C++ Standard Library Technical Report 2. The proposal is based on the Boost Filesystem Library (see www.boost.org/libs/filesystem).
+The library provides portable facilities to query and
+manipulate paths, files, and directories. The Boost version of the library is widely used. It would
+be a pure addition to the C++ standard, leaving in place existing
+standard library functionality in the relatively few areas where there is overlap.
+Users say they prefer the Boost Filesystem Library interface to native
+operating system or
+POSIX API's, even in code without portability requirements, because the design
+follows modern C++ practice.
+The proposed text includes an example of a
+program using the library.
+<h2><a name="Motivation">Motivation</a> and Scope</h2>
+Why is this important? 
+The motivation for the library is the desire to perform safe, portable, script-like filesystem operations from within C++ programs. Because the
+C++ Standard Library currently contains no facilities for such filesystem tasks
+as directory iteration or directory creation, programmers currently must rely on
+operating system specific interfaces, making it difficult to write
+portable programs.
+The intent is not to compete
+with Python, Perl, or shell scripting languages, but rather to provide
+file system operations where C++ is already the language of choice. The design
+encourages, but does not require, safe and portable usage.
+What kinds of problems does it address, and what kinds of programmers is
+it intended to support?
+The library addresses everyday needs, for both application programs and
+libraries. It is useful across every application domain that uses files. It is
+intended to be useful to all levels of programmers, from rank beginners to
+seasoned experts.
+Is it based on existing practice?
+Yes, very much so. The proposal is based on the Boost Filesystem Library,
+which has been in use since 2002 and by now is in very wide use.
+Note, however, that until recently all the Boost experience was with a
+narrow-character only version of the library. The internationalized version as
+described in this proposal is just starting to be used, and will not be fully
+released until Boost release 1.34.
+The underlying mechanisms have been in use for decades on the world's most
+wide-spread operating systems, such as POSIX, Windows, and various
+mainframe operating systems. What this proposal brings to the table is an
+approach that is C++
+Standard Library friendly and fully internationalized.
+Is there a reference implementation?
+Yes. The Boost Filesystem Library is freely and publicly available. The Boost library will track the TR2 proposed
+library as the proposal evolves.
+<h2><a name="Impact">Impact</a> on the Standard</h2>
+What does it depend on, and what depends on it?
+It depends on
+some standard library components, such as basic_string. No other proposals
+depend on it.
+If a revision to the Code Conversion Proposal (See
+<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1683.html">
+http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1683.html>) is
+accepted, it may be advantageous for the Filesystem Library
+to use that library rather than the current code conversion facilities proposed
+below.
+Is it a pure extension, or does it require changes to standard
+components?
+Most of the proposed library is a pure extension.
+There are additions to header <cerrno>. Since
+the critical portions that might require change to C headers (always a sore
+point) are already mandated for POSIX compliance, and represent
+existing practice for many non-POSIX operating systems such as for Windows, it is not expected that they will cause any problems.
+There are additions to header <fstream>. 
+These have been carefully specified to avoid breaking existing code in common operating environments such as POSIX, 
+Windows, and OpenVMS. See <a href="#Suggestions-for-fstream">
+Suggestions for <code><fstream></code> implementations</a> for techniques to
+avoid breaking existing code in other environments, particularly on operating
+systems allowing slashes in filenames.
+Can it be implemented using today's compilers, or does it require
+language features that will only be available as part of C++0x?
+It can
+be (and has been) implemented with today's compilers.
+There is one minor function that can best be implemented by an addition to
+current C++ runtime libraries, although an acceptable workaround is documented.
+On operating systems with built-in support for wide-character file names,
+such as Windows, high-quality implementation of the header <fstream>
+additions require an addition to the C++ Standard Library implementation. The
+addition is relatively small and localized, and is already supplied by the most
+recent Dinkumware implementation of the Standard Library. There is a workaround that avoids
+modifying the standard library, but it is very much a hack and depends on a 
+Windows feature (8.3 filename support) which some users disable, thereby
+disabling the workaround. The issue doesn't affect implementations on operating
+systems which only support narrow character file names.
+<h2>Important <a name="Design">Design</a> Decisions</h2>
+<h4>Why did you choose the specific design that you did?</h4>
+Many of the specific design decisions were driven by the desire to provide a modern C++ interface
+that works
+well with the C++ Standard Library. The intent is that Standard Library users
+can become comfortable with the Filesystem Library in very short order.
+The proposed library encourages both syntactic and semantic portability, yet
+does not force implementors into heroic efforts on hopeless systems. This
+balances the benefits to users of both code and knowledge portability with the
+realities faced by implementors on some operating systems.
+
+In some
+cases users always need portable semantics. In some cases users always need
+platform specific semantics. In some cases users need to be able to choose
+between portable and platform specific semantics. The design evolved over a
+period of years to identify and meet each of those needs. 
+
+Because of the desire to support simple "script-like" usage, use cases often
+drove design choices. For example, users can write <code>if (exists("foo"))</code> rather than
+the lengthier <code>if (exists(path("foo")))</code>.
+
+Because filesystem operations often encounter unexpected runtime errors, the library
+by default reports runtime errors via C++ exceptions,
+and ensures enough information is provided for meaningful error messages,
+including internationalized error messages.
+
+What alternatives did you consider, and what are the tradeoffs?
+Additional observers and modifiers for file system attributes.
+Attribute functions which cannot supply portable semantics are not provided,
+avoiding the illusion of portability in cases where it cannot in fact exist.
+A larger number of operational convenience functions.
+Convenience functions (functions which can be portably created by composition
+from basic functions) were not provided unless there was widespread agreement on
+usefulness and need.
+Compile-time or run-time options for operational functions.
+Numerous trial implementations were abandoned because the added complexity
+out-weighed the benefits, and because consensus could not be reached on the
+feature set.
+Automatic path name checking. This feature, supplied by the Boost
+library for several years, allowed users to specify both default and per
+constructor path name checking, and thus allowed the desired degree of portability to be
+automatically enforced. This implicit name checking was abandoned because of user
+confusion and complaints of excessive nannyism..
+Separate path types for regular file and directory pathnames. Pathname
+formats that use different syntax for regular pathnames versus directory
+pathnames are passing into extinction. Why prolong the agony at the cost of
+torturing those using modern systems? It is perhaps significant that one of the few web
+sites dedicated to preserving a dual pathname format operating system is named
+Deathrow (http://deathrow.vistech.net/).
+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.
+What are the consequences of your choices, for users and implementors?
+The design has evolved over a period of four years of actual experience by
+Boost users, and the most frequent causes of user complaints (such as enforced
+name-checking and several over-strict preconditions) were eliminated. The TR
+process will allow further refinement. The intent is to ensure user needs are
+met.
+Because the Boost implementation is tested and
+used in a wide range of POSIX and Windows environments, many implementation
+concerns have already been addressed.
+What decisions are left up to implementors?
+Because implementations of the library are dependent on facilities of the
+underlying operating system, implementors are given unusual freedom to redefine
+semantics of the library. That being said, implementors are given strong
+normative encouragement to provide the TR described semantics whenever feasible.
+If there are any similar libraries in use, how do their design
+decisions compare to yours?
+There are a number of libraries which address the problem domain. Most of the
+C/C++ libraries have C, rather than C++ interfaces. For example, see the Apache Portable Runtime
+Project (http://apr.apache.org). The ACE
+toolkit (http://www.cs.wustl.edu/~schmidt/ACE.html)
+uses a C++ approach, but doesn't mesh well with the C++ Standard Library. For
+example, the ACE directory iterator differs greatly from Standard Library
+iterator requirements.
+<h2>Proposed <a name="Text">Text</a> for Technical Report 2</h2>
+Gray-shaded
+italic text is commentary on the proposal. It is not to be added to the TR.
+Italic text is editorial guidance.
+It is not to be added to the TR.
+
+<a name="frontmatter">Add</a> to the
+introductory section of the TR:
+The following standard contains provisions which, through reference in this
+text, constitute provisions of this Technical Report. At the time of
+publication, the editions indicated were valid. All standards are subject to
+revision, and parties to agreements based on this Technical Report are
+encouraged to investigate the possibility of applying the most recent editions
+of the standard indicated below. Members of IEC and ISO maintain registers of
+currently valid International Standards.
+ <ul>
+ <li>ISO/IEC 9945:2003, Portable Operating System Interface (POSIX¹),
+ part 1 (Base Definitions) and part 2 (System Interfaces), both as corrected by their
+ respective 2004 Correction 1 documents.[Note: ISO/IEC 9945:2003 is
+ also IEEE Std 1003.1-2001, and The Open Group Base Specifications, Issue 6,
+ and is also known as The Single Unix2
+ Specification, Version 3. It is available from each of those organizations,
+ and may be read online or downloaded from
+ <a href="http://www.unix.org/single_unix_specification/">
+ www.unix.org/single_unix_specification/</a> -- end note]
+ </li>
+ </ul>
+ISO/IEC 9945:2003, with the indicated corrections, is hereinafter called 
+POSIX.
+Some library behavior in this Technical Report is defined by reference to 
+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. 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>basic_filesystem_error</code> exception, a special
+return value, or some other manner. --end note]
+</blockquote>
+<a name="Footnote-1">Footnote 1</a>: POSIX® is a registered trademark of The
+IEEE.
+<a name="Footnote-2">Footnote 2</a>: UNIX® is a registered trademark of The
+Open Group.
+Add a new clause to the TR:
+<hr>
+<h2>Chapter (tbs) -
+<a name="Diagnostics-library">Diagnostics library</a></h2>
+<hr>
+This clause describes components that C++ programs may use to detect and
+report error conditions.
+<h3>Header <code><system_error></code></h3>
+<pre>namespace std
+{
+ namespace tr2
+ {
+ namespace sys
+ {
+ typedef implementation-defined system_error_type;
+ typedef int errno_type; // determined by C standard
+
+ system_error_type system_code(errno_type err);
+
+ errno_type iso_code(system_error_type err);
+
+ std::string& system_message(error_code err, std::string& target);
+ std::wstring& system_message(error_code err, std::wstring& target);
+
+ enum iso_t { iso };
+
+ class error_code;
+ class system_error;
+
+ } // namespace sys
+ } // namespace tr2
+} // namespace std</pre>
+Type <code>system_error_type</code> is the implementation-defined type used
+by the operating system to report error codes.
+<blockquote>
+[Note: On POSIX, <code>system_error_type</code> is normally <code>int</code>.
+On Windows it is normally <code>unsigned int</code>. This type might differ if
+the implementation is built on an emulation layer such as Cygwin. --
+end note]
+</blockquote>
+<pre>system_error_type system_code(errno_type err);</pre>
+<blockquote>
+Returns: An <code>system_error_type</code> value corresponding to
+<code>err</code>.
+[Note: There is no guarantee that for a value <code>err</code> of type
+<code>errno_type</code>, <code>err == iso_code( system_code(err) )</code>. --
+end note]
+</blockquote>
+<pre>errno_type iso_code(system_error_type err);</pre>
+<blockquote>
+ Returns: An <code>errno_type</code> value corresponding to <code>err</code>.
+[Note: There is no guarantee that for a value <code>err</code> of type
+<code>system_error_type</code>, <code>err == system_code( iso_code(err) )</code>.
+-- end note]
+</blockquote>
+<pre>std::string& system_message(error_code err, std::string& target);
+std::wstring& system_message(error_code err, std::wstring& target);</pre>
+<blockquote>
+ Effects: Appends to <code>target</code> an operating system specific
+ and locale specific message corresponding to <code>err.system()</code>.
+ Returns: <code>target</code>.
+ Remarks: Implementors and users are permitted to supply additional
+ overloads in namespace <code>std::tr2::sys</code>.
+</blockquote>
+<h3>Class <code>error_code</code></h3>
+<pre>namespace std
+{
+ namespace tr2
+ {
+ namespace sys
+ {
+ class error_code
+ {
+ public:
+ error_code();
+ error_code(system_error_type err);
+ error_code(errno_type err, iso_t);
+
+ system_error_type system() const;
+ void system(system_error_type err);
+
+ errno_type iso() const;
+ void iso(errno_type err);
+
+ bool error() const;
+
+ bool operator==(error_code rhs) const;
+ };
+ } // namespace sys
+ } // namespace tr2
+} // namespace std</pre>
+The class <code>error_code</code> defines the type of objects used to
+identify specific errors originating from the operating system.
+<pre>error_code();</pre>
+<blockquote>
+ Postcondition: <code>!error()&& iso()==0</code>, and <code>system()</code>
+ returns the value used by the operating system to represent not an error. 
+</blockquote>
+<pre>error_code(system_error_type err);</pre>
+<blockquote>
+ Postcondition: <code>system()==err</code>.
+</blockquote>
+<pre>error_code(errno_type err, iso_t);</pre>
+<blockquote>
+ Postcondition: <code>iso()==err</code>.
+</blockquote>
+<pre>system_error_type system() const;</pre>
+<blockquote>
+ Returns: If the most recent non-const function called, or the
+ constructor if no non-const function has been called, had an <code>err</code>
+ argument of type <code>system_error_type</code>, then return that argument.
+ Otherwise, return <code>system_code(iso())</code>.
+</blockquote>
+<pre>void system(system_error_type err);</pre>
+<blockquote>
+ Postcondition: <code>system()==err</code>.
+</blockquote>
+<pre>errno_type iso() const;</pre>
+<blockquote>
+ Returns: If the most recent non-const function called, or the
+ constructor if no non-const function has been called, had an <code>err</code>
+ argument of type <code>errno_type</code>, then return that argument.
+ Otherwise, return <code>iso_code(system())</code>.
+</blockquote>
+<pre>void iso(errno_type err);</pre>
+<blockquote>
+ Postcondition: <code>iso()==err</code>.
+</blockquote>
+<pre>bool error() const;</pre>
+<blockquote>
+ Returns: <code>system()==error_code(x),</code> where <code>x</code>
+ is the value used by the operating system to represent not an error.
+</blockquote>
+<pre>bool operator==(error_code rhs) const;</pre>
+<blockquote>
+ Returns: <code>system()==rhs.system()</code>.
+</blockquote>
+<h3>Class <code>system_error</code></h3>
+<pre>namespace std
+{
+ namespace tr2
+ {
+ namespace sys
+ {
+ class system_error : public std::runtime_error
+ {
+ public:
+ system_error(const std::string & what_arg, error_code ec);
+
+ error_code code() const;</pre>
+<pre> const char * what() const;
+ };
+ } // namespace sys
+ } // namespace tr2
+} // namespace std</pre>
+The class <code>system_error</code> defines the type of objects thrown as
+exceptions to report errors originating from the operating system.
+<pre>system_error(const std::string & what_arg, error_code ec);</pre>
+<blockquote>
+ Effects: Constructs an object of class <code>system_error</code>.
+ Postcondition: <code>strcmp(runtime_error::what(), what_arg .c_str()) == 0 &&
+ code() == ec</code>.
+</blockquote>
+<pre>error_code code() const;</pre>
+<blockquote>
+ Returns: the <code>ec</code> constructor argument.
+</blockquote>
+<pre>const char * what() const;</pre>
+<blockquote>
+ Returns: A string containing <code>runtime_error::what()</code> and
+ the result of calling <code>system_message()</code> with a first argument of
+ <code>code()</code>. The exact format is unspecified.
+</blockquote>
+Add a new clause to the TR:
+<hr>
+<h2>Chapter (tbs) - <a name="Filesystem-library">Filesystem library</a></h2>
+<hr>
+This clause describes components that C++ programs may use to interrogate and
+manipulate files (including directories), and certain of their
+attributes.
+This clause applies only to hosted implementations (C++ Std, 1.4,
+Implementation compliance [intro.compliance]).
+<blockquote>
+[Note: This clause applies to any hosted implementation.
+Specific operating systems such as OpenMVS3,
+UNIX, and Windows4 are mentioned only for purposes of illustration or to
+give guidance to implementors. No slight to other operating systems is implied
+or intended. --end note.]
+</blockquote>
+Unless otherwise specified, all components described in this clause are
+declared in namespace <code>std::tr2::sys</code>.
+<blockquote>
+[Note: The <code>sys</code> sub-namespace prevents collisions with
+names already in the standard library and emphasizes reliance on the
+operating system dependent behavior inherent in file system operations. -- end
+note]
+</blockquote>
+The Effects and Postconditions of functions described in this clause
+may not be achieved in
+the presence of race conditions. No diagnostic is required.
+If the possibility of race conditions makes 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>
+<a name="Footnote-3">Footnote 3</a>: OpenMVS® is a registered
+trademark of Hewlett-Packard Development Company.
+<a name="Footnote-4">Footnote 4</a>: Windows® is a registered
+trademark of Microsoft Corporation.
+<h3><a name="Definitions">Definitions</a></h3>
+The following definitions shall apply to this clause:
+<a name="File">File</a>: An object that can be written to, or read from, or both. A file
+has certain attributes, including type. File types include regular file,
+symbolic link, and directory. Other types of files 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. The format is as
+specified by the POSIX
+<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_169">
+Filename</a> base definition.
+<a name="Path">Path</a>: A sequence of elements which identify
+a location within a filesystem. The elements are the root-name, 
+root-directory, and each successive filename. See
+Pathname grammar.
+<a name="Pathname">Pathname</a>: A character string that represents a
+path.
+<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="Slash">Slash</a>: The character <tt>'/'</tt>, also known as
+solidus.
+<a name="Dot">Dot</a>: The character '.', also known as period.
+<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.
+<h3><a name="Requirements">Requirements</a></h3>
+<h4><a name="Requirements-on-programs">Requirements on programs</a></h4>
+The arguments for template parameters named <code>Path</code>, <code>Path1</code>,
+or <code>Path2</code> described in this clause shall be of type <code>basic_path</code>,
+or a class derived from <code>basic_path</code>, unless otherwise
+specified.
+<h4><a name="Requirements-on-implementations">Requirements on implementations</a></h4>
+Some function templates described in this clause have a template parameter
+named <code>Path</code>, <code>Path1</code>, or <code>Path2</code>. When called
+with a function argument <code>s</code> of type <code>char*</code> or <code>
+std::string</code>, the implementation shall treat the argument as if it were
+coded <code>path(s)</code>. When called with a function argument <code>s</code>
+of type <code>wchar_t*</code> or <code>std::wstring</code>, the implementation
+shall treat the argument as if it were coded <code>wpath(s)</code>. For
+functions with two arguments, implementations shall not supply this treatment
+when <code>Path1</code> and <code>Path2</code> are different types.
+<blockquote>
+[Note: This "do-the-right-thing" rule allows users to write <code>exists("foo")</code>,
+taking advantage of class <code>basic_path</code>'s string conversion
+constructor,  rather
+than the lengthier and more error prone <code>exists(path("foo"))</code>. This
+is particularly important for the simple, script-like, programs which are an
+important use case for the library. Calling two argument functions with
+different types is a very rare usage, and may well be a coding error, so
+automatic conversion is not supported for such cases.
+The implementation technique is unspecified. One possible implementation
+technique, using
+<code>exists()</code> as an example, is:
+ <blockquote>
+ <pre>template <class Path>
+ typename boost::enable_if<is_basic_path<Path>,bool>::type exists(const Path& p);
+inline bool exists(const path& p) { return exists<path>(p); }
+inline bool exists(const wpath& p) { return exists<wpath>(p); }</pre>
+ </blockquote>
+  The <code>enable_if</code> will fail for a C string or <code>
+ std::basic_string</code> argument, which will then be automatically converted
+ to a <code>basic_path</code> object via the appropriate <code>basic_path</code> conversion
+ constructor.   -- end note]
+ The two overloads are not given
+ in the normative text because:
+ <ul>
+ <li>Better techniques for
+ achieving the desired affect may be developed, perhaps enabled by core
+ language changes like Concepts.</li>
+ <li>Implementations may prefer
+ techniques that work with legacy compilers that do not support enable_if.</li>
+ <li>Spelling out the overloads
+ makes the text longer and harder to read without adding much benefit.</li>
+ <li>More overloads will probably
+ be needed for char16_t and char32_t (or whatever they end up being called),
+ making it even less attractive to actually spell out each one. 
+ </li>
+ </ul>
+</blockquote>
+Implementations of functions described in this clause are permitted to call the applications
+program interface (API) provided by the operating system. If such an operating
+system API call results in an error, implementations
+shall report the error by throwing exception <code>basic_filesystem_error</code>,
+unless otherwise specified.
+<blockquote>
+[Note: Such exceptions and the conditions that cause them to be thrown
+are not explicitly described in each Throws element within this clause.
+Because hardware failures, network failures, race conditions, and a plethora of
+other errors occur frequently in file system operations, users should be aware
+that unless otherwise specified any file system operation, not matter how apparently innocuous, may throw
+an exception. -- end note]
+</blockquote>
+Functions commonly used in contexts
+where errors are not exceptional have overloads taking an additional argument of
+type <code>error_code& ec</code>. Such overloaded functions shall not throw exceptions. If an error occurs,
+<code>ec</code> shall be set to the
+error code reported by the operating system, otherwise <code>ec</code> shall be set to 0. If
+an overload without an argument of type <code>
+error_code& ec</code> returns void, the other overload (with an argument of type <code>
+error_code& ec</code>) returns an <code>
+error_code</code> with the value of ec.
+<h3><a name="Header-filesystem-synopsis">Header <code><filesystem></code> synopsis</a></h3>
+<pre>namespace std
+{
+ namespace tr2
+ {
+ namespace sys
+ {
+ template <class String, class Traits> class basic_path;
+
+ template<class String, class Traits>
+ void swap(basic_path<String, Traits> & lhs, basic_path<String, Traits> & rhs);
+
+ template<class String, class Traits> bool operator<(a a, b b);
+ template<class String, class Traits> bool operator==(a a, b b);
+ template<class String, class Traits> bool operator!=(a a, b b);
+ template<class String, class Traits> bool operator>(a a, b b);
+ template<class String, class Traits> bool operator<=(a a, b b);
+ template<class String, class Traits> bool operator>=(a a, b b);
+ template<class String, class Traits> bool operator/(a a, b b);
+
+ template<class Path>
+ basic_ostream<typename Path::string_type::value_type, typename Path::string_type::traits_type> &
+ operator<<(basic_ostream<typename Path::string_type::value_type, typename Path::string_type::traits_type>& os, const Path & ph);
+
+ template<class Path>
+ basic_istream<typename Path::string_type::value_type, typename Path::string_type::traits_type> &
+ operator>>(basic_istream<typename Path::string_type::value_type, typename Path::string_type::traits_type>& is, Path & ph);
+
+ struct path_traits;
+ struct wpath_traits;
+
+ typedef basic_path<std::string, path_traits> path;
+ typedef basic_path<std::wstring, wpath_traits> wpath;
+
+ template<class Path> struct is_basic_path;
+
+ template<class Path> struct slash { static const char value = '/'; };
+ template<class Path> struct dot { static const char value = '.'; };
+ template<class Path> struct colon { static const char value = ':'; };
+
+ class filesystem_error;
+
+ template <class Path> class basic_filesystem_error;
+
+ typedef basic_filesystem_error<path> filesystem_error;
+ typedef basic_filesystem_error<wpath> wfilesystem_error;
+
+ template <class Path> class basic_directory_entry;
+
+ typedef basic_directory_entry<path> directory_entry;
+ typedef basic_directory_entry<wpath> wdirectory_entry;
+
+ template <class Path> class basic_directory_iterator;
+
+ typedef basic_directory_iterator<path> directory_iterator;
+ typedef basic_directory_iterator<wpath> wdirectory_iterator;
+
+ template <class Path> class basic_recursive_directory_iterator;
+
+ typedef basic_recursive_directory_iterator<path> recursive_directory_iterator;
+ typedef basic_recursive_directory_iterator<wpath> wrecursive_directory_iterator;
+
+ enum file_type { status_unknown, file_not_found, regular_file, directory_file,
+ symlink_file, block_file, character_file, fifo_file, socket_file,
+ type_unknown
+ };
+
+ class file_status;
+
+ struct space_info // returned by space function
+ {
+ uintmax_t capacity;
+ uintmax_t free;
+ uintmax_t available;
+ };
+
+ // status functions
+ template <class Path> file_status status(const Path& p);
+ template <class Path> file_status status(const Path& p, error_code& ec);
+ template <class Path> file_status symlink_status(const Path& p);
+ template <class Path> file_status symlink_status(const Path& p, error_code& ec);
+
+ // predicate functions
+ bool status_known( file_status s );
+ bool exists( file_status s );
+ bool is_regular( file_status s );
+ bool is_directory( file_status s );
+ bool is_symlink( file_status s );
+ bool is_other( file_status s );
+
+ template <class Path> bool exists(const Path& p);
+ template <class Path> bool is_directory(const Path& p);
+ template <class Path> bool is_regular(const Path& p);
+ template <class Path> bool is_other(const Path& p);
+ template <class Path> bool is_symlink(const Path& p);
+ template <class Path> bool is_empty(const Path& p);
+
+ template <class Path1, class Path2>
+ bool equivalent(const Path1& p1, const Path2& p2);
+
+ // attribute functions
+ template <class Path> Path current_path();
+ template <class Path> const Path& initial_path();
+ template <class Path> uintmax_t file_size(const Path& p);
+ template <class Path> space_info space(const Path& p);
+ template <class Path> std::time_t last_write_time(const Path& p);
+ template <class Path>
+ void last_write_time(const Path& p, const std::time_t new_time);
+
+ // operations functions
+ template <class Path> bool create_directory(const Path& dp);
+ template <class Path1, class Path2>
+ void create_hard_link(const Path1& old_fp, const Path2& new_fp);
+ template <class Path1, class Path2>
+ error_code create_hard_link(const Path1& old_fp, const Path2& new_fp, error_code& ec);
+ template <class Path1, class Path2>
+ void create_symlink(const Path1& old_fp, const Path2& new_fp);
+ template <class Path1, class Path2>
+ error_code create_symlink(const Path1& old_fp, const Path2& new_fp, error_code& ec);
+ template <class Path> bool remove(const Path& p);
+ template <class Path1, class Path2>
+ void rename(const Path1& from_p, const Path2& to_p);
+ template <class Path1, class Path2>
+ void copy_file(const Path1& from_fp, const Path2& to_fp);
+ template <class Path> Path system_complete(const Path& p);
+ template <class Path> Path complete(const Path& p, const Path& base=initial_path<Path>());
+
+ // convenience functions
+ template <class Path> bool create_directories(const Path& p);
+ template <class Path> typename Path::string_type extension(const Path& p);
+ template <class Path> typename Path::string_type basename(const Path& p);
+ template <class Path>
+ Path replace_extension(const Path& p, const typename Path::string_type& new_extension);
+
+ } // namespace sys
+ } // namespace tr2
+} // namespace std</pre>
+<h3><a name="Path-traits">Path traits</a></h3>
+This subclause defines requirements on classes representing path behavior
+traits, and defines two classes that satisfy those requirements for paths based
+on <code>string</code> and <code>wstring</code>.. It also defines several path
+additional path traits structure templates, and defines several specializations
+of them.
+Class template <code>basic_path</code> defined in this clause requires additional
+types, values, and behavior to complete the definition of its semantics.
+For purposes of exposition, Traits behaves as if it is a class with private
+members bool m_locked, initialized false, and std::locale m_locale, initialized 
+<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
+ <tr>
+ <td width="50%" align="center" colspan="2">
+ <a name="Path-Behavior-Traits-Requirements">Path Behavior Traits
+ Requirements</a></td>
+ </tr>
+ <tr>
+ <td width="38%" align="center">Expression</td>
+ <td width="62%" align="center">Requirements</td>
+ </tr>
+ <tr>
+ <td width="38%" valign="top"><code>Traits::external_string_type</code></td>
+ <td width="62%">A typedef which is a specialization of <code>basic_string</code>.
+ The <code>value_type</code> is a character type used by the operating system
+ to represent pathnames.</td>
+ </tr>
+ <tr>
+ <td width="38%" valign="top"><code>Traits::internal_string_type</code></td>
+ <td width="62%">A typedef which is a specialization of <code>basic_string</code>.
+ The <code>value_type</code> is a character type to be used by the program to
+ represent pathnames. Required be the same type as the <code>basic_path
+ String</code> template parameter. </td>
+ </tr>
+ <tr>
+ <td width="38%" valign="top"><code>Traits::to_external( p, is )</code></td>
+ <td width="62%"><code>is</code>, converted by the <code>m_locale</code>
+ <code>codecvt</code> facet to <code>external_string_type</code>.</td>
+ </tr>
+ <tr>
+ <td width="38%" valign="top"><code>Traits::to_internal( p, xs )</code></td>
+ <td width="62%"><code>xs</code>, converted by the <code>m_locale</code>
+ <code>codecvt</code> facet to to <code>internal_string_type</code>.</td>
+ </tr>
+ <tr>
+ <td width="38%" valign="top"><code>Traits::imbue(loc)</code></td>
+ <td width="62%">Effects: if <code>m_locked</code>, throw. Otherwise,
+ <code>m_locked = true; m_locale = loc; 
+ </code>Returns: <code>void</code> 
+ Throws: <code>basic_filesystem_error</code></td>
+ </tr>
+ <tr>
+ <td width="38%" valign="top"><code>Traits::imbue(loc, std::nothrow)</code></td>
+ <td width="62%">Effects: <code>if (!m_locked) m_locale = loc; bool
+ temp(m_locked); m_locked = true; 
+ </code>Returns: <code>temp</code></td>
+ </tr>
+</table>
+Type <code>is_basic_path</code> shall be a UnaryTypeTrait (TR1, 4.1).
+The primary template shall be derived directly or indirectly from <code>
+std::tr1::false_type</code>. Type <code>is_basic_path</code> shall be
+specialized for <code>path</code>, <code>wpath</code>, and any
+user-specialized <code>basic_path</code> types, and such specializations shall
+be derived directly or indirectly from <code>std::tr1::true_type</code>.
+Structure templates <code>slash</code>, <code>dot</code>, and <code>
+colon</code>
+are supplied with
+values of type <code>char</code>. If a user-specialized <code>basic_path</code>
+has a <code>
+value_type</code> type which is not convertible from <code>char</code>, the
+templates  <code>slash</code> and <code>dot</code> shall be specialized to
+provide <code>value</code> with type which is convertible to <code>
+basic_path::value_type</code>.
+<h3><a name="Class-template-basic_path">Class template <code>basic_path</code></a></h3>
+Class template <code>basic_path</code> provides a portable mechanism for
+representing paths in C++ programs, using a portable generic
+pathname grammar. When portability is not a
+requirement, native file system specific formats can be used. Class template
+<code>basic_path</code> is concerned only with the lexical and syntactic aspects
+of a path. The path does not have to exist in the operating system's file
+system, and may contain names which are not even valid for the current operating
+system. 
+<blockquote>
+ [Note: If the library's functions trafficked only in C++ or
+ C-style strings, they would provide only the illusion of portability since
+ while the syntax of function calls would be portable, the semantics of the
+ strings they operate on would not be portable. -- end note]
+</blockquote>
+<pre>namespace std
+{
+ namespace tr2
+ {
+ namespace sys
+ {
+ template <class String, class Traits> class basic_path
+ {
+ public:
+ typedef basic_path<String, Traits> path_type;
+ typedef String string_type;
+ typedef typename String::value_type value_type;
+ typedef Traits traits_type;
+ typedef typename Traits::external_string_type external_string_type;
+
+ // constructors/destructor
+ basic_path();
+ basic_path(const basic_path& p);
+ basic_path(const string_type& s);
+ basic_path(const value_type* s);
+ template <class InputIterator>
+ basic_path(InputIterator first, InputIterator last);
+
+ ~basic_path();
+
+ // assignments
+ basic_path& operator=(const basic_path& p);
+ basic_path& operator=(const string_type& s);
+ basic_path& operator=(const value_type* s);
+ template <class InputIterator>
+ basic_path& assign(InputIterator first, InputIterator last);
+
+ // modifiers
+ basic_path& operator/=(const basic_path& rhs);
+ basic_path& operator/=(const string_type& s);
+ basic_path& operator/=(const value_type* s);
+ template <class InputIterator>
+ basic_path& append(InputIterator first, InputIterator last);
+
+ void clear();
+ void swap( basic_path & rhs );
+ basic_path& remove_leaf();
+
+ // observers
+ const string_type string() const;
+ const string_type file_string() const;
+ const string_type directory_string() const;
+
+ const external_string_type external_file_string() const;
+ const external_string_type external_directory_string() const;
+
+ string_type root_name() const;
+ string_type root_directory() const;
+ basic_path root_path() const;
+ basic_path relative_path() const;
+ string_type leaf() const;
+ basic_path branch_path() const;
+
+ bool empty() const;
+ bool is_complete() const;
+ bool has_root_name() const;
+ bool has_root_directory() const;
+ bool has_root_path() const;
+ bool has_relative_path() const;
+ bool has_leaf() const;
+ bool has_branch_path() const;
+
+ // iterators
+ class iterator;
+ typedef iterator const_iterator;
+
+ iterator begin() const;
+ iterator end() const;
+
+ };
+
+ } // namespace sys
+ } // namespace tr2
+} // namespace std</pre>
+A <code>basic_path</code> object stores a possibly empty path.
+The internal form of the stored path is unspecified.
+<a name="pathname-resolution">Functions</a> described in this clause which access files or their attributes do so by
+resolving a <code>basic_path</code> object into a particular file in a file
+hierarchy. The pathname, suitably converted to the string type, format, and
+encoding
+required by the operating system, 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. The encoding of the resulting pathname is determined by the <code>Traits::to_external</code> conversion function.
+<blockquote>
+[Note: There is no guarantee that the path stored in a  <code>basic_path</code>
+object is valid for a particular operating system or file system. -- end note]
+</blockquote>
+Some functions in this clause return <code>basic_path</code> objects for
+paths composed partly or wholly of pathnames obtained from the operating system.
+Such pathnames are suitably converted from the actual format and string
+type supplied by the operating system. The encoding of the resulting path is determined by the <code>Traits::to_internal</code> conversion function.
+For member functions described as returning "<code>const string_type</code>" or
+"<code>const external_string_type</code>", implementations are permitted to return
+"<code>const string_type&</code>" or  "<code>const external_string_type&</code>"
+respectively.
+<blockquote>
+[Note: This allows implementations to avoid unnecessary copies.
+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>
+<h4><a name="Pathname-formats">Pathname formats</a></h4>
+There are two formats for string or sequence arguments that describe a
+path:
+<ul>
+ <li>The portable pathname format as described in <a href="#Pathname-grammar">
+ Pathname grammar</a> and by the POSIX Filename,
+<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_266">
+Pathname</a> and
+<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_11">
+Pathname Resolution</a> definitions.<blockquote>
+[Note: The POSIX format
+is the basis for the portable format because it is already an ISO standard, is
+the basis for the ubiquitous URL format, and is the native format or a
+subset of the native format for UNIX-like and Windows-like
+operating systems familiar to large numbers of programmers. 
+Use of the portable format does not alone guarantee
+portability; filenames must also be portable.
+See Filename conversions. Each operating system
+
+follows its own rules. Use of the portable format
+does not change that. -- end note]
+ </blockquote>
+ </li>
+ <li>A native pathname format
+ as defined by the operating system.<blockquote>
+ [Note: If an operating system supports only the POSIX
+ pathname format, the portable format and the native format are the same. 
+ Identifying user-provided paths
+ as native format is a common need, and ensures maximum portability, even
+ though not strictly needed except on systems where the native format
+ is not implicitly recognized.
+ Programs using hard-coding native
+ formats are likely to be non-portable.  -- end note]
+ </blockquote>
+ </li>
+</ul>
+All <code>basic_path</code> string or sequence arguments that describe a
+path shall accept the portable pathname format, and shall accept the native
+format if explicitly identified by a native format escape sequence prefix of
+<code>slash slash colon</code>.
+<blockquote>
+ [Note: <code>slash
+ slash colon</code> was chosen as the escape sequence because a leading <code>
+ slash slash</code>  is already implementation-defined by POSIX, <code>
+ colon</code> is prohibited in a Windows filename, and on any system a single
+ <code>slash</code> can be used when a filename beginning with a <code>colon</code>
+ is desired. These factors eliminate the chance of collision with a real
+ filename. -- end note]
+ </blockquote>
+Implementations are encouraged to
+implicitly recognize the native pathname format if it can be lexically
+identified. An implementation shall document whether or
+not the native pathname format is 
+implicitly recognized.
+<blockquote>
+[Example:
+-- OpenVMS: <code>"SYS1::DISK1:[JANE.TYLER.HARRY]</code>" is treated
+as a native pathname with a system name, drive name, and three directory
+filenames, rather than a portable pathname with one filename.
+-- Windows: <code>"c:\\jane\\tyler\\harry"</code> is treated as a
+native pathname with a drive letter, root-directory, and three filenames, rather
+than a portable pathname with one filename.
+-- Counter-example 1: An operating system that allows slashes in
+filenames and uses dot as a directory separator. Distinguishing between portable
+and native format argument strings or sequences is not possible as there is no
+other distinguishing syntax. The implementation does not accept native format
+pathnames unless the <code>native</code> argument is present.
+-- Counter-example 2: An operating system that allows slashes in
+filenames and uses some unusual character as a directory separator. The
+implementation does accept native format pathnames without the additional <code>
+native</code> argument, which only has to be used for native format arguments
+containing slashes in filenames.
+-- end example]
+[Note: This <a name="duck-rule">duck-rule</a> ("if it looks
+like a duck, walks like a duck, and quacks like a duck, it must be a duck")
+eliminates format confusion as a source of programmer error and support
+requests. -- end note]
+</blockquote>
+If both the portable and native formats are accepted, implementations shall
+document what characters or character sequences are used to distinguish between
+portable and native formats.
+<blockquote>
+[Note: Windows implementations are encouraged to define colons
+and backslashes as the characters which distinguish native from portable
+formats. --end note]
+</blockquote>
+<h4><a name="Pathname-grammar">Pathname grammar</a></h4>
+The grammar for the portable pathname format is as follows:
+<blockquote>
+pathname: 
+            root-nameopt
+root-directoryopt relative-pathopt
+root-name: 
+           
+implementation-defined
+root-directory: 
+            slash 
+           
+root-directory slash 
+           
+implementation-defined
+relative-path: 
+           
+filename 
+            relative-path
+slash 
+            relative-path
+slash filename
+filename: 
+            name 
+            dot 
+            dot dot
+slash: 
+            <code>
+slash<Path>::value</code>
+dot: 
+            <code>
+dot<Path>::value</code>
+</blockquote>
+The grammar is aligned with the POSIX  Filename,
+<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_266">
+Pathname</a> and
+<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_11">
+Pathname Resolution</a> definitions. Any conflict between the grammar and 
+POSIX is unintentional. This technical report defers to POSIX.
+<blockquote>
+The form of the above wording was taken
+from POSIX, which uses it in several places to defer to the C standard.
+[Note: Windows implementations are encouraged to define slash slash
+name as a permissible root-name. POSIX permits, but does not
+require, implementations to do the same. Windows implementations are
+encouraged to define an additional root-directory element 
+root_directory name. It is applicable only to the slash slash name
+form of root-name.
+ Windows implementations are encouraged to recognize a name
+followed by a colon as a native format root-name,
+and a backslash as a format element equivalent to slash. -- end note]
+</blockquote>
+<h4><a name="Filename-conversion">Filename conversion</a></h4>
+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.]
+The Boost implementation for
+Windows currently does not map invalid characters. Pending feedback from the LWG,
+Boost may settle on % hex hex as the preferred escape sequence. If so, should
+there be normative encouragement?
+</blockquote>
+<h4><a name="basic_path-requirements">Requirements</a></h4>
+The argument for the template parameter named <code>String</code> shall be a
+class that includes members with the same names, types, values, and semantics as
+class template <code>basic_string</code>.
+The argument for the template parameter named <code>Traits</code> shall be a
+class that satisfies the requirements specified in the
+Path Behavior Traits Requirements
+table.
+The argument for template parameters named <code>InputIterator</code> shall satisfy the
+requirements of an input iterator (C++ Std, 24.1.1, Input iterators [lib.input.iterators]) and shall have a value type convertible to
+<code>basic_path::value_type</code>. 
+Some function templates with a template
+parameter named <code>InputIterator</code> also have non-template overloads. Implementations shall
+only select the function template overload if the type named by <code>InputIterator</code>
+is not <code>path_format_t</code>.
+<blockquote>
+[Note: This "do-the-right-thing" rule ensures that the
+overload expected by the user is selected. The implementation technique is unspecified -
+implementations may use
+enable_if or
+other techniques to achieve the effect. -- end note]
+</blockquote>
+<h4> <a name="basic_path-constructors"> <code>basic_path</code> constructors</a></h4>
+<pre>basic_path();</pre>
+<blockquote>
+ Postconditions: <code>empty()</code>.
+ </blockquote>
+<pre>basic_path(const string_type& s);
+basic_path(const value_type * s);
+template <class InputIterator>
+ basic_path(InputIterator s, InputIterator last);</pre>
+<blockquote>
+ Remarks: The format of string <code>s</code> and sequence [<code>first</code>,<code>last</code>)
+ is described in Pathname formats.
+ Effects: The path elements in string <code>s</code> or sequence [<code>first</code>,<code>last</code>)
+ are stored.
+</blockquote>
+<h4> <a name="basic_path-assignments"> <code>basic_path</code> assignments</a></h4>
+<pre>basic_path& operator=(const string_type& s);
+basic_path& operator=(const value_type* s);
+template <class InputIterator>
+ basic_path& assign(InputIterator first, InputIterator last);</pre>
+<blockquote>
+ Remarks: The format of string <code>s</code> and sequence [<code>first</code>,<code>last</code>)
+ is described in Pathname formats.
+ Effects: The path elements in string <code>s</code> or sequence [<code>first</code>,<code>last</code>)
+ are stored.
+ Returns: <code>*this</code>
+ </blockquote>
+<h4> <a name="basic_path-modifiers"> <code>basic_path</code> modifiers</a></h4>
+<pre>basic_path& operator/=(const basic_path& rhs);</pre>
+<blockquote>
+ Effects: The path stored in <code>rhs</code> is appended to the
+ stored path.
+ Returns: <code>*this</code>
+</blockquote>
+<pre>basic_path& operator/=(const string_type& s);
+basic_path& operator/=(const value_type* s);
+template <class InputIterator>
+basic_path& append(InputIterator first, InputIterator last);</pre>
+<blockquote>
+ Remarks: The format of string <code>s</code> and sequence [<code>first</code>,<code>last</code>)
+ is described in Pathname formats.
+Effects: The path elements in string <code>s</code> or sequence [<code>first</code>,<code>last</code>)
+ are appended to the stored path.
+ Returns: <code>*this</code>
+ </blockquote>
+<pre>void clear();</pre>
+<blockquote>
+Postcondition: <code>this->empty()</code> is true.
+</blockquote>
+<pre><code>void swap( basic_path & rhs );</code></pre>
+<blockquote>
+ Effects:
+ Swaps the contents of the two paths.
+ Throws: 
+ nothing.
+ Postcondition:
+ <code>this->string()</code>
+ contains the same sequence of characters that were in <code>
+ rhs.string()</code>, <code>
+ rhs.string()</code>
+ contains the same sequence of characters that were is <code>
+ this->string()</code>.
+ Complexity: 
+ constant time.
+</blockquote>
+<pre>basic_path& remove_leaf();</pre>
+<blockquote>
+ Effects: If <code>has_branch_path()</code> then remove the last filename from the stored path. If that leaves
+ the stored path with one or more trailing slash elements not
+ representing  root-directory, remove them.
+ Returns: <code>*this</code>
+ [Note: This function is needed to efficiently implement <code>
+ basic_directory_iterator</code>. It is made public to allow additional uses. -- end
+ note]
+</blockquote>
+<h4> <a name="basic_path-observers"> <code>basic_path</code> observers</a></h4>
+<blockquote>
+See the
+Path decomposition table for examples
+for values returned by decomposition functions.
+</blockquote>
+<pre>const string_type string() const;</pre>
+<blockquote>
+Returns: The stored path, formatted according to the
+Pathname grammar rules.
+</blockquote>
+<pre>const string_type file_string() const;</pre>
+<blockquote>
+Returns: The stored path, formatted according to the
+operating system rules for regular file pathnames, with any
+Filename conversion applied.
+[Note: For some operating systems, including POSIX and 
+Windows, the native format for regular file pathnames and directory
+pathnames is the same, so <code>file_string()</code> and <code>directory_string()</code>
+return the same string. On OpenMVS, however, the expression <code>path("/cats/jane").file_string()</code>
+would return the string <code>"[CATS]JANE"</code> while <code>path("/cats/jane").directory_string()</code>
+would return the string <code>"[CATS.JANE]"</code>. -- end note]
+</blockquote>
+<pre>const string_type directory_string() const;</pre>
+<blockquote>
+Returns: The stored path, formatted according to the
+operating system rules for directory pathnames, with any
+Filename conversion applied.
+</blockquote>
+<pre>const external_string_type external_file_string() const;</pre>
+<blockquote>
+Returns: The stored path, formatted according to the
+operating system rules for regular file pathnames, with any
+Filename conversion applied, and encoded by the <code>Traits::to_external</code>
+conversion function.
+</blockquote>
+<pre>const external_string_type external_directory_string() const;</pre>
+<blockquote>
+Returns: The stored path, formatted according to the
+operating system rules for directory pathnames, with any
+Filename conversion applied, and encoded by the <code>Traits::to_external</code>
+conversion function.
+</blockquote>
+<pre>string_type root_name() const;</pre>
+<blockquote>
+Returns: root-name, if the stored path includes 
+root-name, otherwise <code>string_type()</code>. 
+</blockquote>
+<pre>string_type root_directory() const;</pre>
+<blockquote>
+Returns: root-directory, if the stored path includes 
+root-directory, otherwise <code>string_type()</code>.
+If root-directory is composed slash name, slash is
+excluded from the returned string.
+</blockquote>
+<pre>basic_path root_path() const;</pre>
+<blockquote>
+ Returns: <code>root_name() / root_directory()</code>
+</blockquote>
+<pre>basic_path relative_path() const;</pre>
+<blockquote>
+Returns: A <code>basic_path</code> composed from the the stored path, if any, beginning
+with the first filename after root-path.
+Otherwise, an empty <code>basic_path</code>.
+</blockquote>
+<pre>string_type leaf() const;</pre>
+<blockquote>
+ Returns: <code>empty() ? string_type() : *--end()</code>
+</blockquote>
+<pre>basic_path branch_path() const;</pre>
+<blockquote>
+ Returns: <code>(string().empty() || begin() == --end()) ? path_type("") :
+ br</code>, where <code>br</code> is constructed as if by
+ starting with an empty <code>basic_path</code> and successively applying <code>
+ operator/=</code> for each element in the range <code>begin()</code>, <code>
+ --end()</code>.
+</blockquote>
+<pre>bool empty() const;</pre>
+<blockquote>
+ Returns: <code>string().empty()</code>.
+</blockquote>
+<pre>bool is_complete() const;</pre>
+<blockquote>
+ Returns: <code>true</code>,
+ if the elements of root_path() uniquely identify a directory, else <code>false</code>.
+</blockquote>
+<pre>bool has_root_path() const;</pre>
+<blockquote>
+ Returns: <code>!root_path().empty()</code>
+</blockquote>
+<pre>bool has_root_name() const;</pre>
+<blockquote>
+ Returns: <code>!root_name().empty()</code>
+</blockquote>
+<pre>bool has_root_directory() const;</pre>
+<blockquote>
+ Returns: <code>!root_directory().empty()</code>
+</blockquote>
+<pre>bool has_relative_path() const;</pre>
+<blockquote>
+ Returns: <code>!relative_path().empty()</code>
+</blockquote>
+<pre>bool has_leaf() const;</pre>
+<blockquote>
+ Returns: <code>!leaf().empty()</code>
+</blockquote>
+<pre>bool has_branch_path() const;</pre>
+<blockquote>
+ Returns: <code>!branch_path().empty()</code>
+</blockquote>
+<h4> <a name="basic_path-iterators"> <code>basic_path</code> iterators</a></h4>
+ A <code>basic_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>string_type</code>.
+ Calling any non-const member function of a <code>basic_path</code> object
+ invalidates all iterators referring to elements of the 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>
+<h4> <a name="basic_path-non-member-functions">
+basic_path non-member functions</a></h4>
+<pre>template<class String, class Traits>
+void swap( basic_path<String, Traits> & lhs, basic_path<String, Traits> & rhs )</pre>
+<blockquote>
+ Effects: <code>
+ lhs.swap(
+ rhs )</code>
+</blockquote>
+ <h4>basic_path non-member operators</h4>
+ There are seven basic_path non-member operators (/,
+ <code>==</code>,
+ <code>
+ !=</code>,
+ <code><</code>,
+ <code>></code>,
+ <code><=</code>,
+ <code>>=</code>),
+ each with five overloads. For brevity, the specifications are given in tabular
+ form. Each of the resulting thirty-five signatures is a template, with
+ template parameter list template<code><class
+ String, class Traits></code>.
+ The format of such arguments is described in <a href="#Pathname-formats">
+ Pathname formats</a>.
+ <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
+ <tr>
+ <td width="100%">
+ Argument type overloads</td>
+ </tr>
+ <tr>
+ <td width="100%"><code>
+ basic_path<String, Traits>& a, basic_path<String, Traits>&
+ b</code></td>
+ </tr>
+ <tr>
+ <td width="100%"><code>const
+ typename basic_path<String, Traits>::string_type& a,
+ basic_path<String, Traits>& b</code></td>
+ </tr>
+ <tr>
+ <td width="100%"><code>const
+ typename basic_path<String, Traits>::string_type::value_type* a,
+ basic_path<String, Traits>& b</code></td>
+ </tr>
+ <tr>
+ <td width="100%"><code>const
+ basic_path<String, Traits>& a, typename basic_path<String, Traits>::string_type&
+ b</code></td>
+ </tr>
+ <tr>
+ <td width="100%"><code>const
+ basic_path<String, Traits>& a, typename
+ basic_path<String, Traits>::string_type::value_type* b</code></td>
+ </tr>
+ </table>
+ In the 
+ basic_path non-member operators 
+ table, <code>
+ a</code>
+ and <code>b</code>
+ are of the types given in the 
+ Argument type overloads
+ table. If <code>a</code>
+ or <code>b</code>
+ is of type <code>const
+ basic_path<String, Traits>&</code>,
+ then a<code>'</code>
+ or b'
+ respectively is <code>a</code>
+ or <code>b</code>
+ respectively. Otherwise a<code>'</code>
+ or b'
+ respectively represent named or unnamed temporary <code>
+ basic_path<String, Traits></code>
+ objects constructed from <code>
+ a</code> or <code>
+ b</code>
+ respectively.
+<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%" height="280">
+ <tr>
+ <td width="100%" colspan="3" align="center" height="19">
+ basic_path non-member operators</td>
+ </tr>
+ <tr>
+ <td width="20%" align="center" height="19">
+ Expression</td>
+ <td width="25%" align="center" height="19">
+ Return type</td>
+ <td width="55%" align="center" height="19">
+ Semantics</td>
+ </tr>
+ <tr>
+ <td width="20%" align="center" height="30" valign="top"><code>
+ a / b</code></td>
+ <td width="25%" align="center" height="30" valign="top"><code>
+ basic_path<String, Traits></code></td>
+ <td width="55%" height="30"><code>
+ basic_path<String, Traits> tmp(a); 
+ return a /= </code>b'<code>;</code></td>
+ </tr>
+ <tr>
+ <td width="20%" align="center" height="19" valign="top"><code>
+ a < b</code></td>
+ <td width="25%" align="center" height="19" valign="top"><code>
+ bool</code></td>
+ <td width="55%" height="19"><code>
+ return lexicographical_compare(</code>a<code>'.begin(), </code>
+ a<code>'.end(), </code>
+ b'<code>.begin(), </code>
+ b'<code>.end());</code></td>
+ </tr>
+ <tr>
+ <td width="20%" align="center" height="19" valign="top"><code>
+ a == b</code></td>
+ <td width="25%" align="center" height="19" valign="top"><code>
+ bool</code></td>
+ <td width="55%" height="19"><code>
+ return !(</code>a<code>'
+ < </code>b'<code>)
+ && !(</code>b'<code>
+ < </code>a<code>');</code></td>
+ </tr>
+ <tr>
+ <td width="20%" align="center" height="19" valign="top"><code>
+ a != b</code></td>
+ <td width="25%" align="center" height="19" valign="top"><code>
+ bool</code></td>
+ <td width="55%" height="19"><code>
+ return !(</code>a<code>'
+ == </code>b'<code>);</code></td>
+ </tr>
+ <tr>
+ <td width="20%" align="center" height="19" valign="top"><code>
+ a > b</code></td>
+ <td width="25%" align="center" height="19" valign="top"><code>
+ bool</code></td>
+ <td width="55%" height="19"><code>
+ return </code>b'<code>
+ < </code>a<code>';</code></td>
+ </tr>
+ <tr>
+ <td width="20%" align="center" height="19" valign="top"><code>
+ a <= b</code></td>
+ <td width="25%" align="center" height="19" valign="top"><code>
+ bool</code></td>
+ <td width="55%" height="19"><code>
+ return !(</code>b'<code>
+ < </code>a<code>');</code></td>
+ </tr>
+ <tr>
+ <td width="20%" align="center" height="19" valign="top"><code>
+ a >= b</code></td>
+ <td width="25%" align="center" height="19" valign="top"><code>
+ bool</code></td>
+ <td width="55%" height="19"><code>
+ return !(</code>a<code>'
+ < </code>b'<code>);</code></td>
+ </tr>
+</table>
+ <blockquote>
+ [Note:
+ <a name="Path-equality">Path equality</a> and path
+ equivalence have different semantics.
+ Equality is determined by 
+ basic_path's
+ non-member <code><a href="#operator-eq">
+ operator==</a></code>, which considers the two path's lexical representations
+ only. Paths "abc" and "ABC" are never equal.
+ Equivalence is determined by the
+ equivalent()
+ non-member function, which determines if two paths 
+ resolve to the same file system entity.
+ Paths "abc"
+ and "ABC" may or may not resolve to the same file, depending on the file
+ system.
+ 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>
+ <h4><a name="basic_path-inserter-extractor"> <code>
+ basic_path</code> inserter
+ and extractor</a></h4>
+<pre>template<class Path>
+ basic_istream<typename Path::string_type::value_type, typename Path::string_type::traits_type>&
+ operator>>(basic_istream< typename Path::string_type::value_type, typename Path::string_type::traits_type>& is,
+ Path& ph );</pre>
+<blockquote>
+ Effects:  
+ <code>typename Path::string_type str; 
+       
+ is >> str; 
+       
+ ph = str;</code>
+ Returns:
+ <code>is</code>
+</blockquote>
+<pre>template<class Path>
+ basic_ostream<typename Path::string_type::value_type, typename Path::string_type::traits_type>&
+ operator<<(basic_ostream< typename Path::string_type::value_type, typename Path::string_type::traits_type>& os,
+ const Path& ph );</pre>
+<blockquote>
+ Effects: 
+ <code>os << ph.string()</code>
+ Returns:
+ <code>os</code>
+</blockquote>
+<h3><a name="Class-template-basic_filesystem_error">Class template <code>basic_filesystem_error</code></a></h3>
+<pre>namespace std
+{
+ namespace tr2
+ {
+ namespace sys
+ {
+ template <class Path> class basic_filesystem_error : public system_error
+ {
+ public:
+ typedef Path path_type;
+
+ explicit basic_filesystem_error(const std::string& what_arg, error_code ec);
+ basic_filesystem_error(const std::string& what_arg, const path_type& p1, error_code ec);
+ basic_filesystem_error(const std::string& what_arg, const path_type& p1, const path_type& p2, error_code ec);
+
+ const path_type& path1() const;
+ const path_type& path2() const;
+
+ const char * what() const;
+ };
+ } // namespace sys
+ } // namespace tr2
+} // namespace std</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="basic_filesystem_error-constructors"> <code>basic_filesystem_error</code> constructors</a></h4>
+<pre>explicit basic_filesystem_error(const std::string& what_arg, error_code ec);</pre>
+<blockquote>
+ Postconditions:
+ <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>basic_filesystem_error(const std::string& what_arg, const path_type& p1, error_code ec);</pre>
+<blockquote>
+ Postconditions:
+ <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>basic_filesystem_error(const std::string& what_arg, const path_type& p1, const path_type& p2, error_code ec);</pre>
+<blockquote>
+ Postconditions:
+ <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>
+<h4> <a name="basic_filesystem_error-observers"> <code>basic_filesystem_error</code> observers</a></h4>
+<pre>const path_type& path1() 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_type& path2() 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 * what() const;</pre>
+<blockquote>
+ Returns: A string containing <code>runtime_error::what()</code> and
+ the result of calling <code>system_message()</code> with a first argument of
+ <code>code()</code>. The exact format is unspecified.
+The implementation shall supply a specialization <code>template<> const char
+* basic_filesystem_error<path>::what() const</code> that returns a string
+containing <code>runtime_error::what(),</code> the result of calling <code>
+system_message()</code> with a first argument of <code>code()</code>, and if
+non-empty, <code>path1().file_string()</code> and <code>path2.file_string()</code>.
+The exact format is unspecified.
+Implementations and users are permitted to provide other specializations of
+the <code>what</code> member function.
+</blockquote>
+<h3><a name="Class-template-basic_directory_entry">Class template <code>basic_directory_entry</code></a></h3>
+<pre>namespace std
+{
+ namespace tr2
+ {
+ namespace sys
+ {
+ template <class Path> class basic_directory_entry
+ {
+ public:
+ typedef Path path_type;
+ typedef typename Path::string_type string_type;
+
+ // constructors
+ basic_directory_entry();
+ explicit basic_directory_entry(const path_type& p,
+ file_status st=file_status(), file_status symlink_st=file_status());
+
+ // modifiers
+ void assign(const path_type& p, file_status st=file_status(), file_status symlink_st=file_status());
+ void replace_leaf(const string_type& s, file_status st=file_status(), file_status symlink_st=file_status());
+
+ // observers
+ const Path& path() const;
+ operator const Path&() const;
+
+ file_status status() const;
+ file_status status(error_code& ec) const;
+ file_status symlink_status() const;
+ file_status symlink_status(error_code& ec) const;
+
+ // comparisons
+ bool operator<(const basic_directory_entry<Path>& rhs);
+ bool operator==(const basic_directory_entry<Path>& rhs);
+ bool operator!=(const basic_directory_entry<Path>& rhs);
+ bool operator>(const basic_directory_entry<Path>& rhs);
+ bool operator<=(const basic_directory_entry<Path>& rhs);
+ bool operator>=(const basic_directory_entry<Path>& 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 sys
+ } // namespace tr2
+} // namespace std</pre>
+A <code>basic_directory_entry</code> object stores a <code>basic_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 speedup expected on Linux and BSD-derived
+Unix variants that provide status during directory iteration.
+</blockquote>
+<h4> <a name="basic_directory_entry-constructors"> <code>basic_directory_entry </code>constructors</a></h4>
+<pre>basic_directory_entry();</pre>
+<blockquote>
+ Postconditions:
+ <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 basic_directory_entry(const path_type& p, file_status st=file_status(), file_status symlink_st=file_status());</pre>
+<blockquote>
+ Postconditions:
+ <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="basic_directory_entry-modifiers"> <code>basic_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>
+ Postconditions:
+ <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_leaf(const string_type& s, file_status st=file_status(), file_status symlink_st=file_status());</pre>
+<blockquote>
+ Postconditions:
+ <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="basic_directory_entry-observers"> <code>basic_directory_entry</code> observers</a></h4>
+<pre>const Path& path() const;
+operator const Path&() const;</pre>
+<blockquote>
+ Returns: <code>m_path</code>
+</blockquote>
+<pre>file_status status() 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); }
+}</pre>
+ </blockquote>
+ Throws: See <code>status</code>
+ function.
+ Returns: <code>m_status</code>
+</blockquote>
+<pre>file_status status(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); }
+}
+else ec = 0;</pre>
+ </blockquote>
+ Returns: <code>m_status</code>
+</blockquote>
+<pre>file_status symlink_status() const;</pre>
+<blockquote>
+Effects:
+As if,
+ <blockquote>
+ <pre>if ( !status_known( m_symlink_status ) )
+{
+ m_symlink_status = symlink_status(m_path);
+}</pre>
+ </blockquote>
+ Throws: See <code>symlink_status</code>
+ function.
+ Returns: <code>
+ m_symlink_status</code>
+</blockquote>
+<pre>file_status symlink_status(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);
+}
+else ec = 0;</pre>
+ </blockquote>
+ Returns: <code>m_symlink_status</code>
+</blockquote>
+<h3><a name="Class-template-basic_directory_iterator">Class template <code>basic_directory_iterator</code></a></h3>
+<pre>namespace std
+{
+ namespace tr2
+ {
+ namespace sys
+ {
+ template <class Path>
+ class basic_directory_iterator :
+ public iterator<input_iterator_tag, basic_directory_entry<Path> >
+ {
+ public:
+ typedef Path path_type;
+
+ // constructors
+ basic_directory_iterator();
+ explicit basic_directory_iterator(const Path& dp);
+ basic_directory_iterator(const Path& dp, error_code& ec);
+ basic_directory_iterator(const basic_directory_iterator& bdi);
+ basic_directory_iterator& operator=(const basic_directory_iterator& bdi);
+ ~basic_directory_iterator();
+
+ // other members as required by
+ // C++ Std, 24.1.1 Input iterators [lib.input.iterators]
+ };
+
+ } // namespace sys
+ } // namespace tr2
+} // namespace std</pre>
+ <code>basic_directory_iterator</code> satisfies the requirements of an
+input iterator (C++ Std, 24.1.1, Input iterators [lib.input.iterators]).
+A <code>basic_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>basic_directory_iterator</code> is constructed, and every time
+<code>operator++</code> is called,
+it reads and stores a value of <code>basic_directory_entry<Path></code>
+and possibly stores associated status values.
+<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 be used only 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>basic_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 basic_directory_entry<Path>&</code> is returned. The result of
+<code>operator-></code> on an end iterator is not defined. For any other
+iterator value a <code>const basic_directory_entry<Path>*</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. Commentary was shortened and
+moved into a note.
+</blockquote>
+The result of calling the <code>path()</code> member of the <code>
+basic_directory_entry</code> object obtained by dereferencing a <code>
+basic_directory_iterator</code> is a reference to a <code>basic_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>. 
+<blockquote>
+[<a name="Example-program">Example</a>: This program accepts an
+optional command line argument, and if that argument is a directory pathname,
+iterates over the contents of the directory. For each directory entry, the name
+is output, and if the entry is for a regular file, the size of the file is
+output.
+ <blockquote>
+ <pre>#include <iostream>
+#include <filesystem>
+
+using std::tr2::sys;
+using std::cout;
+
+int main(int argc, char* argv[])
+{
+ std::string p(argc <= 1 ? "." : argv[1]);
+
+ if (is_directory(p))
+ {
+ for (directory_iterator itr(p); itr!=directory_iterator(); ++itr)
+ {
+ cout << itr->path().leaf() << ' '; // display filename only
+ if (is_regular(itr->status())) cout << " [" << file_size(itr->path()) << ']';
+ cout << '\n';
+ }
+ }
+ else cout << (exists(p) : "Found: " : "Not found: ") <
+ </blockquote>
+ -- end example]
+</blockquote>
+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>basic_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>basic_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="basic_directory_iterator-constructors"><code>basic_directory_iterator</code> constructors</a></h4>
+
+<code>basic_directory_iterator();</code>
+
+<blockquote>
+
+Effects: Constructs the end iterator.
+
+</blockquote>
+
+<code>explicit basic_directory_iterator(const Path& dp);</code>
+
+<blockquote>
+
+Effects: Constructs a iterator representing the first
+entry in the directory resolved to by <code>dp</code>, otherwise, the end iterator.
+
+[Note: To iterate over the current directory, write <code>
+directory_iterator(".")</code> rather than <code>directory_iterator("")</code>.
+-- end note]
+</blockquote>
+<pre><code>basic_directory_iterator(const Path& dp, error_code& ec );</code></pre>
+<blockquote>
+
+Effects: Constructs a iterator representing the first
+entry in the directory resolved to by <code>dp</code>, otherwise, the end iterator.
+If an error occurs while establishing the results, the iterator constructed
+represents the end iterator and <code>ec</code> is set to the error code
+reported by the operating system, otherwise to 0.
+
+</blockquote>
+<h3><a name="Class-template-basic_recursive_directory_iterator">Class template <code>basic_recursive_directory_iterator</code></a></h3>
+<pre>namespace std
+{
+ namespace tr2
+ {
+ namespace sys
+ {
+ template <class Path>
+ class basic_recursive_directory_iterator :
+ public iterator<input_iterator_tag, basic_directory_entry<Path> >
+ {
+ public:
+ typedef Path path_type;
+
+ // constructors
+ basic_recursive_directory_iterator();
+ explicit basic_recursive_directory_iterator(const Path& dp);
+ basic_recursive_directory_iterator(const basic_recursive_directory_iterator& brdi);
+ basic_recursive_directory_iterator& operator=(const basic_recursive_directory_iterator& brdi);
+ ~basic_recursive_directory_iterator();
+
+ // observers
+ int level() const;
+
+ // modifiers
+ void pop();
+ void no_push();
+
+ // other members as required by
+ // C++ Std, 24.1.1 Input iterators [lib.input.iterators]
+
+ private:
+ int m_level; // for exposition only
+ };
+
+ } // namespace sys
+ } // namespace tr2
+} // namespace std</pre>
+The behavior of a <code>basic_recursive_directory_iterator</code> is the same
+as a <code>basic_directory_iterator</code> unless otherwise specified.
+<ul>
+ <li>When an iterator is constructed, <code>m_level</code> is set to 0;</li>
+ <li>When an iterator <code>it</code> is incremented, if <code>it->is_directory()</code>
+ is true and <code>no_push()</code> had not been called subsequent to
+ the most recent increment operation (or construction, if no increment has
+ occurred), then  <code>m_level</code> is incremented, the
+ directory is visited, and its contents recursively iterated over.</li>
+ <li>When an iterator 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 continues with the parent directory, until the
+ directory specified in the constructor argument is reached.</li>
+ <li><code>level()</code> returns <code>m_level</code>.</li>
+ <li><code>level()</code>, <code>pop()</code>, and <code>no_push()</code> all
+ require that the iterator not be the end iterator.</li>
+</ul>
+<blockquote>
+ [Note: One of the uses of <code>no_push()</code> is to prevent
+ unwanted recursion into symlinked directories. This may be necessary to
+ prevent loops on some operating systems. --end note]
+</blockquote>
+<h3><a name="file_status">Class file_status</a></h3>
+<pre>namespace std
+{
+ namespace tr2
+ {
+ namespace sys
+ {
+ class file_status
+ {
+ public:
+ explicit file_status( file_type v = status_unknown );
+
+ file_type type() const;
+ void type( file_type v );
+ };
+ } // namespace sys
+ } // namespace tr2
+} // namespace std</pre>
+A <code>file_status</code> object stores information about the status of a
+file. The internal form of the stored information is unspecified.
+<blockquote>
+ [Note: The class may be extended in the future to store
+ additional status information. --end note]
+</blockquote>
+<h4>Members</h4>
+<pre>explicit file_status( file_type v = status_unknown );</pre>
+<blockquote>
+ Effects: Stores <code>v</code>.
+</blockquote>
+<pre>file_type type() const;</pre>
+<blockquote>
+ Returns: The stored <code>file_type</code>.
+</blockquote>
+<pre>void type( file_type v );</pre>
+<blockquote>
+ Effects: Stores <code>v</code>, replacing the previously stored
+ value.
+</blockquote>
+<h3><a name="Non-member-functions">Non-member operational functions</a></h3>
+<h4><a name="Status-functions">Status functions</a></h4>
+<pre>template <class Path> file_status status(const Path& p, error_code& ec);
+template <class Path> file_status symlink_status(const Path& p, error_code& ec);</pre>
+<blockquote>
+ Returns:
+ <blockquote>
+ For <code>status,</code> determine the attributes
+ of
+ <code>p</code> as if by POSIX <code>
+ stat()</code>,
+ for <code>symlink_status</code> determine the attributes as if by POSIX <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/lstat.html">
+ lstat()</a></code>.<blockquote>
+ [Note: For symbolic links, <code>stat()</code> continues
+ pathname resolution using the contents of the symbolic link, <code>lstat()</code>
+ does not. --
+ end note]
+ </blockquote>
+ If the operating system reports an error during attribute determination:
+ <ul>
+ <li>If the error indicating that <code>p</code> could not
+ be resolved, as if by POSIX error codes ENOENT or ENOTDIR, set ec to 0 and return <code>
+ file_status(not_found_flag)</code>.</li>
+ </ul>
+ <ul>
+ <li>Otherwise, set ec to the error code reported by the operating system
+ and return <code>
+ file_status(status_unknown)</code>.</li>
+ </ul>
+ Otherwise:<ul>
+ <li>If the attributes indicate a regular file, as if by POSIX S_ISREG(),
+ return <code>
+ file_status(regular_file)</code>.</li>
+ <li>Else if the attributes indicate a directory, as if by POSIX S_ISDIR(),
+ return <code>
+ file_status(directory_file)</code>.</li>
+ <li>Else if the attributes indicate a symbolic link, as if by POSIX S_ISLNK(),
+ return <code>
+ file_status(symlink_file)</code>. [Note: Only possible for <code>
+ symlink_status</code>. --end note]</li>
+ <li>Else if the attributes indicate a block special file, as if by POSIX S_ISBLK(),
+ return <code>
+ file_status(block_file)</code>.</li>
+ <li>Else if the attributes indicate a character special file, as if by POSIX S_ISCHR(),
+ return <code>
+ file_status(character_file)</code>.</li>
+ <li>Else if the attributes indicate a fifo or pipe file, as if by POSIX S_ISFIFO(),
+ return <code>
+ file_status(fifo_file)</code>.</li>
+ <li>Else if the attributes indicate a socket, as if by POSIX S_ISSOCK(),
+ return <code>
+ file_status(socket_file)</code>.</li>
+ <li>Else return <code>
+ file_status(type_unknown)</code>.</li>
+ </ul>
+ </blockquote>
+[Note: <code>directory_file</code> implies <code>
+basic_directory_iterator</code> on the file would succeed, and <code>
+regular_file</code> implies appropriate <code><fstream></code> operations would succeed,
+assuming no hardware, permission, access, or race
+condition errors. For <code>regular_file,</code> the converse is not true; lack of
+<code>regular_file</code> does not necessarily imply <code><fstream></code> operations would
+fail on a directory.
+-- end note]
+</blockquote>
+<pre>template <class Path> file_status status(const Path& p);</pre>
+<blockquote>
+ Effects: <code>system_error_code ec;</code> 
+             
+ <code>file_status stat(status(p, ec));</code>
+ Throws: <code>basic_filesystem_error<Path></code> if <code>ec
+ != 0</code>
+ Returns: <code>stat</code>
+</blockquote>
+<pre>template <class Path> file_status symlink_status(const Path& p);</pre>
+<blockquote>
+ Effects: <code>system_error_code ec;</code> 
+             
+ <code>file_status stat(symlink_status(p, ec));</code>
+ Throws: <code>basic_filesystem_error<Path></code> if <code>ec
+ != 0</code>
+ Returns: <code>stat</code>
+</blockquote>
+<h4><a name="Predicate-functions">Predicate functions</a></h4>
+<pre>bool status_known(file_status s);</pre>
+<blockquote>
+ Returns:
+ <code>s.type() != status_unknown</code>
+</blockquote>
+<pre>bool <a name="exists">exists</a>(file_status s);</pre>
+<blockquote>
+ Returns:
+ <code>status_known(s) && s.type() != file_not_found</code>
+</blockquote>
+<pre>template <class Path> bool <a name="exists">exists</a>(const Path& p);</pre>
+<blockquote>
+ Returns: <code>exists( status(p) )</code>
+</blockquote>
+<pre>bool <code>is_regular</code>(file_status s);</pre>
+<blockquote>
+ Returns:
+ <code>s.type() == regular_file</code>
+</blockquote>
+<pre><code>template <class Path> bool is_regular(const Path& p);</code></pre>
+<blockquote>
+ Returns: <code>is_regular( status(p) )</code>
+</blockquote>
+<pre>bool <code>is_directory</code>(file_status s);</pre>
+<blockquote>
+ Returns: 
+ <code>s.type() == directory_file</code>
+</blockquote>
+<pre><code>template <class Path> bool is_directory(const Path& p);</code></pre>
+<blockquote>
+ Returns: <code>is_directory( status(p) )</code>
+</blockquote>
+<pre>bool <a name="exists">is_symlink</a>(file_status s);</pre>
+<blockquote>
+ Returns: 
+ <code>s.type() == symlink_file</code>
+</blockquote>
+<pre><code>template <class Path> bool is_symlink(const Path& p);</code></pre>
+<blockquote>
+ Returns: <code>is_symlink( symlink_status(p) )</code>
+</blockquote>
+<pre>bool <a name="exists">is_other</a>(file_status s);</pre>
+<blockquote>
+ Returns:
+ <code>return exists(s) && !is_regular(s) && !is_directory(s) && !is_symlink(s)</code>
+ [Note: The specification of
+ <code>is_other()</code> will remain unchanged even if additional <code>is_xxx()</code>
+ functions are added in the future. -- end note]
+</blockquote>
+<pre><code>template <class Path> bool is_other(const Path& p);</code></pre>
+<blockquote>
+ Returns: <code>is_other( status(p) )</code>
+</blockquote>
+<pre><code>template <class Path> bool is_empty(const Path& p);</code></pre>
+<blockquote>
+ Effects: Determines <code>file_status s</code>, as if by <code>
+ status(p)</code>.
+ Throws: <code>basic_filesystem_error<Path></code> if <code>!exist(s) ||
+ is_other(s)</code>.
+ Returns: <code>is_directory(s) 
+         ?
+ basic_directory_iterator<Path>(p) == basic_directory_iterator<Path>() 
+         : file_size(p) == 0;</code>
+</blockquote>
+<pre><code>template <class Path1, class Path2> bool <a name="equivalent">equivalent</a>(const Path1& p1, const Path2& p2);</code></pre>
+<blockquote>
+ Requires: <code>Path1::external_string_type</code> and <code>
+ Path2::external_string_type</code> are the same type. 
+ Effects: Determines <code>file_status s1</code> and <code>s2</code>,
+ as if by <code>status(p1)</code> and  <code>status(p2)</code>,
+ respectively.
+ Throws: <code>basic_filesystem_error<Path1></code> 
+ if <code>(!exists(s1) && !exists(s2)) || (is_other(s1) &&
+ is_other(s2))</code>.
+ Returns: <code>true</code>, if <code>sf1 == sf2</code> and <code>p1</code> and <code>p2</code>
+ resolve to the same file system entity, else <code>false</code>.
+ 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>
+ stat</code>
+ structure<code>,</code> obtained as if by <code>
+ stat()</code> for the two paths, having equal
+ <code>st_dev</code> values and equal <code>st_ino</code> values.
+ [Note: 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>
+<h4><a name="Attribute-functions">Attribute functions</a></h4>
+[Note: A strictly limited number of attribute functions are provided
+because few file system attributes are portable. Even the functions provided will be impossible to implement on some file
+systems. --end note.]
+<pre>template <class Path> const Path& <a name="initial_path">initial_path</a>();</pre>
+<blockquote>
+ Returns: <code>current_path()</code> at the time of entry to <code>
+ main()</code>.
+ [Note: These semantics turn a dangerous global variable into a safer
+ global constant. --end note]
+ [Note: Full implementation requires runtime library support.
+ Implementations which cannot provide runtime library support are encouraged to
+ instead store the value of <code>current_path()</code> at the first call of
+ <a name="initial_path"><code>initial_path</code></a><code>()</code>, and
+ return this value for all subsequent calls. Programs using
+ <a name="initial_path"><code>initial_path</code></a><code>()</code> are
+ encouraged to call it immediately on entrance to <code>main()</code> so that
+ they will work correctly with such partial implementations. --end note]
+</blockquote>
+<pre>template <class Path> Path current_path();</pre>
+<blockquote>
+ Returns: The current path, as if by POSIX
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/getcwd.html">
+ <code>getcwd()</code></a>.
+ Postcondition: <code>current_path().is_complete()</code>
+ [Note: The current path as returned by many operating systems is a
+ dangerous global variable. It may be changed unexpectedly by a third-party or
+ system library functions, or by another thread. Although dangerous, the
+ function is useful in dealing with other libraries.. For a safer alternative,
+ see <code>initial_path()</code>. The <code>
+ current_path()</code> name was chosen to emphasize that the return is a
+ complete path, not just a single directory name. -- end note]
+</blockquote>
+<pre>template <class Path> uintmax_t file_size(const Path& p);</pre>
+<blockquote>
+ Returns: 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>.
+</blockquote>
+<pre><a name="space">template</a> <class Path> space_info space(const Path& p);</pre>
+<blockquote>
+ Returns: A <code>space_info</code>
+ object. 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.
+</blockquote>
+<pre>template <class Path> std::time_t last_write_time(const Path& p);</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>template <class Path> void last_write_time(const Path& p, const std::time_t new_time);</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>.
+ [Note: The apparent postcondition <code>last_write_time(p) ==
+ new_time</code> is not specified since it would not hold for many file systems
+ due to coarse time mechanism granularity. -- end note]
+</blockquote>
+<h4>Other o<a name="Operations-functions">perations functions</a></h4>
+<pre>template <class Path> bool create_directory(const Path& dp);</pre>
+<blockquote>
+ Effects: Attempts to create the directory <code>dp</code> resolves to,
+ as if by POSIX <code>
+ mkdir()</code> with a second argument of S_IRWXU|S_IRWXG|S_IRWXO. 
+ Throws: <code>basic_filesystem_error<Path></code> if 
+ Effects fails for any reason other than because the directory already exists.
+ Returns: True if a new directory was created, otherwise false.
+ Postcondition: <code>is_directory(dp)</code>
+</blockquote>
+<pre>template <class Path1, class Path2>
+ error_code create_hard_link(const Path1& to_p, const Path2& from_p, error_code& ec);</pre>
+<blockquote>
+ Requires:
+ <code>Path1::external_string_type</code> and
+ <code>
+ Path2::external_string_type</code> are the same type.
+ Effects: Establishes the postcondition, as if by
+ POSIX
+ <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/link.html">
+ link()</a></code>.
+ Returns: If the
+ postcondition cannot be established, a system error code
+ indicating the reason for the failure, otherwise 0.
+ Postcondition:
+ <ul>
+ <li> <code>exists(to_p) && exists(from_p) && equivalent(to_p,
+ from_p)</code></li>
+ <li>The contents of the file or directory
+ <code>to_p</code> resolves to are unchanged.</li>
+ </ul>
+ [Note:
+ Some operating systems do not support hard links or support
+ them only for regular files. Some operating systems limit the number of links per
+ file.
+ Some file systems that do not
+ support
+ hard links - the FAT system used on floppy discs, memory cards and flash
+ drives,
+ for example. Thus hard links should be avoided if wide portability is
+ a concern. -- end note]
+ </blockquote>
+<pre>template <class Path1, class Path2>
+ void create_hard_link(const Path1& to_p, const Path2& from_p);</pre>
+<blockquote>
+ Requires:
+ <code>Path1::external_string_type</code> and
+ <code>
+ Path2::external_string_type</code> are the same type.
+ Effects:
+ As if <code>system_error_code ec( create_hard_link( to_p, from_p ) );</code>
+ Throws:
+ <code>basic_filesystem_error<Path1, Path2></code>
+ if <code>ec</code> is not zero.
+ </blockquote>
+<pre>template <class Path1, class Path2>
+ error_code create_symlink(const Path1& to_p, const Path2& from_p, error_code& ec);</pre>
+<blockquote>
+ Requires:
+ <code>Path1::external_string_type</code> and
+ <code>
+ Path2::external_string_type</code> are the same type.
+ Effects: Establishes the postcondition, as if by
+ POSIX
+ <code>
+ 
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/symlink.html">
+ symlink()</a></code>.
+ Returns: If the
+ postcondition cannot be established, a system error code
+ indicating the reason for the failure, otherwise 0.
+ Postcondition: <code>from_p</code>
+ resolves to a symbolic link file that contains an unspecified representation
+ of <code>to_p</code>.
+ [Note:
+ Some operating systems do not support symbolic links at all or support
+ them only for regular files. Thus symbolic links should be avoided if code portability is
+ a concern. -- end note]
+ </blockquote>
+<pre>template <class Path1, class Path2>
+ void create_symlink(const Path1& to_p, const Path2& from_p);</pre>
+<blockquote>
+ Requires:
+ <code>Path1::external_string_type</code> and
+ <code>
+ Path2::external_string_type</code> are the same type.
+ Effects:
+ As if <code>system_error_code ec( create_symlink( to_p, from_p ) );</code>
+ Throws:
+ <code>basic_filesystem_error<Path1, Path2></code>
+ if <code>ec</code> is not zero.
+ </blockquote>
+<pre>template <class Path> bool remove(const Path& p);</pre>
+<blockquote>
+ Precondition: <code>!p.empty()</code>
+ Effects:  Attempts to delete the file <code>p</code> resolves
+ to,
+ as if by POSIX <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/link.html">
+ remove()</a></code>.
+ Returns: The value of <code>exists(p)</code> prior to the
+ establishment of the postcondition.
+ Postcondition: <code>!exists(p)</code>
+ Throws: <code>basic_filesystem_error<Path></code> if:
+ <ul>
+ <li><code>p.empty() || (exists(p) && is_directory(p) && !empty(p))</code>.</li>
+ <li>Effects fails for any reason other than because <code>p</code>
+ does not resolve to an existing file.</li>
+ </ul>
+ [Note: A symbolic link is itself removed, rather than what it
+ resolves to being removed. -- end note]
+</blockquote>
+<pre>template <class Path1, class Path2> void rename(const Path1& from_p, const Path2& to_p);</pre>
+<blockquote>
+ Requires: <code>Path1::external_string_type</code> and <code>
+ Path2::external_string_type</code> are the same type. 
+ Effects: Renames <code>from_p</code> to <code>to_p</code>, as if by
+ POSIX <code>
+ <a href="http://www.opengroup.org/onlinepubs/000095399/functions/rename.html">
+ rename()</a></code>.
+ Postconditions: <code>!exists(from_p) && exists(to_p)</code>, and
+ the contents and attributes of the file originally named <code>from_p</code>
+ are otherwise unchanged.
+ [Note: If <code>from_p</code> and <code>to_p</code> resolve to the
+ same file, no action is taken. Otherwise, if <code>to_p</code> resolves to an
+ existing file, it is removed. A symbolic link is itself renamed, rather than
+ the file it resolves to being renamed. -- end note]
+</blockquote>
+<pre>template <class Path1, class Path2> void copy_file(const Path1& from_fp, const Path2& to_fp);</pre>
+<blockquote>
+ Requires: <code>Path1::external_string_type</code> and <code>
+ Path2::external_string_type</code> are the same type. 
+ Effects: The contents and attributes of the file <code>from_fp</code>
+ resolves to are copied to the file <code>to_fp</code> resolves to.
+ Throws: <code>basic_filesystem_error<Path></code> if <code>
+ from_fp.empty() || to_fp.empty() ||!exists(from_fp) || !is_regular(from_fp)
+ || exists(to_fp)</code>
+</blockquote>
+<pre>template <class Path> Path complete(const Path& p, const Path& base=initial_path<Path>());</pre>
+<blockquote>
+ Effects: Composes a complete path from <code>p</code> and <code>base</code>,
+ using the following rules:
+ <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
+ <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>p</code></td>
+ <td align="center">precondition failure</td>
+ </tr>
+ <tr>
+ <td align="center"><code>!p.has_root_name()</code></td>
+ <td align="center"><code>base.root_name() 
+ / p</code></td>
+ <td align="center"><code>base / p</code></td>
+ </tr>
+ </table>
+ Returns: The composed path.
+ Postcondition: For the returned path, <code>rp,</code> <code>
+ rp.is_complete()</code> is true.
+ Throws:
+ If <code>
+ !(base.is_complete() && (p.is_complete() || !p.has_root_name()))</code>
+ [<a name="complete_note">Note</a>: When portable behavior is
+ required, use complete(). When operating system dependent behavior is
+ required, use system_complete().
+ Portable behavior is useful when dealing with paths created
+ internally within a program, particularly if the program should exhibit the
+ same behavior on all operating systems.
+ Operating system dependent behavior is useful when dealing with
+ paths supplied by user input, reported to program users, or when such behavior
+ is expected by program users. --
+ end note]
+</blockquote>
+<pre>template <class Path> Path system_complete(const Path& p);</pre>
+<blockquote>
+ Effects: Composes a complete path from <code>p</code>, using the
+ same rules used by the operating system to resolve a path passed as the
+ filename argument to standard library open functions.
+ Returns: The composed path.
+ Postcondition: For the returned path, <code>rp,</code> <code>
+ rp.is_complete()</code> is true.
+ Throws: If <code>p.empty()</code>.
+ [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_complete() || !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="file:///C|/boost/site/libs/filesystem/doc/operations.htm#complete_note">
+ complete() note</a> for usage suggestions. -- end note]
+</blockquote>
+<h4><a name="Convenience-functions">Convenience functions</a></h4>
+<pre>template <class Path> bool create_directories(const Path & p);</pre>
+<blockquote>
+ Requires: <code>p.empty() || 
+ forall px: px == p || is_parent(px, p): is_directory(px) || !exists( px )</code>
+ 
+ Returns: The value of <code>!exists(p)</code> prior to the
+ establishment of the postcondition.
+ Postcondition: <code>is_directory(p)</code>
+ Throws:  <code>basic_filesystem_error<Path></code> if<code>
+ exists(p) && !is_directory(p)</code>
+</blockquote>
+<pre>template <class Path> typename Path::string_type extension(const Path & p);</pre>
+<blockquote>
+ Returns: if <code>p.leaf()</code> contains a dot, returns the
+ substring of <code>p.leaf()</code> starting at the rightmost dot and
+ ending at the string's end. Otherwise, returns an empty string. 
+ [Note: The dot is included in the return value so that
+ it is possible to distinguish between no extension and an empty extension. 
+ Implementations are permitted but not required to define additional
+ behavior for file systems which append additional elements to extensions, such
+ as alternate data stream or partitioned dataset names. -- end note]
+</blockquote>
+<pre>template <class Path> typename Path::string_type basename(const Path & p);</pre>
+<blockquote>
+ Returns: if <code>p.leaf()</code> contains a dot, returns the
+ substring of <code>p.leaf()</code> starting at its beginning and ending at the
+ last dot (the dot is not included). Otherwise, returns <code>
+ p.leaf()</code>.
+</blockquote>
+<pre>template <class Path>
+ Path replace_extension(const Path & p, const typename Path::string_type & new_extension);</pre>
+<blockquote>
+ Postcondition: <code>basename(return_value) == basename(p) &&
+ extension(return_value) == new_extension</code> 
+ [Note: It follows from the semantics of <code>extension()</code>
+ that <code>new_extension</code> should include dot to achieve
+ reasonable results. -- end note]
+</blockquote>
+<h3><a name="header-cerrno">Additions</a> to header <code><cerrno></code></h3>
+The header <cerrno> shall include an additional symbolic constant macro for
+each of the values returned by the to_errno
+function. The macro names shall be as defined in POSIX
+<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/errno.h.html">
+errno.h</a>, with the additions below.
+<blockquote>
+This codifies existing practice.
+The required names are only a sub-set of those defined by POSIX, and are usually already
+supplied in <errno.h> (as wrapped by <cerrno>) as shipped with POSIX and Windows compilers.
+These implementations require no changes to their underlying C headers to conform with the above
+requirement.
+<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="33%">
+ <tr>
+ <td width="18%" align="center">Name</td>
+ <td width="82%" align="center">Meaning</td>
+ </tr>
+ <tr>
+ <td width="18%"><code>EBADHANDLE</code></td>
+ <td width="82%">Bad operating system handle.</td>
+ </tr>
+ <tr>
+ <td width="18%"><code>EOTHER</code></td>
+ <td width="82%">Other error.</td>
+ </tr>
+</table>
+</blockquote>
+<h3><a name="header-fstream">Additions</a> to header <code><fstream></code></h3>
+<blockquote>
+These additions have been carefully
+specified to avoid breaking existing code in common operating environments such as
+ POSIX,
+ 
+Windows, and
+ OpenVMS.
+See <a href="#Suggestions-for-fstream">
+Suggestions for <code><fstream></code>
+implementations</a> for
+techniques to avoid breaking existing code in other environments, particularly
+on operating systems allowing slashes in filenames.
+[Note: The
+"do-the-right-thing" rule from <a href="#Requirements-on-implementations">
+Requirements on implementations</a> does apply to header <code><fstream></code>.
+The overloads
+below are specified as additions rather than replacements for existing
+functions. This preserves existing code (perhaps
+using a <a name="home-grown-path">home-grown path</a> class) that relies on an
+automatic conversion to <code>const char*</code>. -- end note]
+</blockquote>
+In 27.8.1.1 Class template
+basic_filebuf [lib.filebuf] synopsis preceding paragraph 1, add the function:
+<blockquote>
+<pre>template <class Path> basic_filebuf<charT,traits>* open(const Path& p, ios_base::openmode mode);</pre>
+</blockquote>
+In 27.8.1.3 Member functions [lib.filebuf.members],
+add the above to the signature preceding paragraph 2, and replace the
+sentence:
+<blockquote>
+It then opens a file, if possible,
+whose name is the NTBS s (“as if” by calling <code>std::fopen(s ,modstr
+))</code>.
+</blockquote>
+with:
+<blockquote>
+It then opens, if possible, the file
+that
+<code>p</code> or <code>path(s)</code> resolves to, “as if” by calling <code>std::fopen()</code> with a
+second argument of modstr.
+</blockquote>
+In 27.8.1.5 Class template
+basic_ifstream [lib.ifstream] synopsis preceding paragraph 1, add the functions:
+<blockquote>
+ <pre>template <class Path> explicit basic_ifstream(const Path& p, ios_base::openmode mode = ios_base::in);
+template <class Path> void open(const Path& p, ios_base::openmode mode = ios_base::in);</pre>
+</blockquote>
+In 27.8.1.6 basic_ifstream
+constructors [lib.ifstream.cons] 
+add the above constructor to the signature preceding
+paragraph 2, and in paragraph 2 replace
+<blockquote>
+<code>rdbuf()->open(s, mode |
+ios_base::in)</code>
+</blockquote>
+with
+<blockquote>
+<code>rdbuf()->open(path(s), mode |
+ios_base::in)</code> or <code>rdbuf()->open(p, mode | ios_base::in)</code> as
+appropriate
+</blockquote>
+In 27.8.1.7 Member functions [lib.ifstream.members]
+add the above open
+function to the signature
+preceding paragraph 3, and in paragraph 3 replace
+<blockquote>
+<code>rdbuf()->open(s, mode |
+ios_base::in)</code>
+</blockquote>
+with
+<blockquote>
+<code>rdbuf()->open(path(s), mode |
+ios_base::in)</code> or <code>rdbuf()->open(p, mode | ios_base::in)</code> as
+appropriate
+</blockquote>
+In 27.8.1.8 Class template
+basic_ofstream [lib.ofstream] synopsis preceding paragraph 1, add the
+
+functions:
+<blockquote>
+ <pre>template <class Path> explicit basic_ofstream(const Path& p, ios_base::openmode mode = ios_base::out);
+template <class Path> void open(const Path& p, ios_base::openmode mode = ios_base::out);</pre>
+</blockquote>
+In 27.8.1.9 basic_ofstream
+constructors [lib.ofstream.cons] 
+add the above constructor to the signature preceding
+paragraph 2, and in paragraph 2 replace
+<blockquote>
+<code>rdbuf()->open(s, mode |
+ios_base::out)</code>
+</blockquote>
+with
+<blockquote>
+<code>rdbuf()->open(path(s), mode |
+ios_base::out)</code> or <code>rdbuf()->open(p, mode | ios_base::out)</code> as
+appropriate
+</blockquote>
+In 27.8.1.10 Member functions [lib.ofstream.members]
+add the above open
+function to the signature
+preceding paragraph 3, and in paragraph 3 replace
+<blockquote>
+<code>rdbuf()->open(s, mode |
+ios_base::out)</code>
+</blockquote>
+with
+<blockquote>
+<code>rdbuf()->open(path(s), mode |
+ios_base::out)</code> or <code>rdbuf()->open(p, mode | ios_base::out)</code> as
+appropriate
+</blockquote>
+In 27.8.1.11 Class template
+basic_fstream [lib.fstream] synopsis preceding paragraph 1, add the functions:
+<blockquote>
+ <pre>template <class Path> explicit basic_fstream(const Path& p, ios_base::openmode mode = ios_base::in|ios_base::out);
+template <class Path> void open(const Path& p, ios_base::openmode mode = ios_base::in|ios_base::out);</pre>
+</blockquote>
+In 27.8.1.12 basic_fstream
+constructors [lib.fstream.cons] 
+add the above constructor to the signature preceding
+paragraph 2, and in paragraph 2 replace
+<blockquote>
+<code>rdbuf()->open(s, mode)</code>
+</blockquote>
+with
+<blockquote>
+<code>rdbuf()->open(path(s), mode)</code>
+or <code>rdbuf()->open(p, mode)</code> as appropriate
+</blockquote>
+In 27.8.1.13 Member functions [lib.fstream.members]
+add the above open
+function to the signature
+preceding paragraph 3, and in paragraph 3 replace
+<blockquote>
+<code>rdbuf()->open(s, mode)</code>
+</blockquote>
+with
+<blockquote>
+<code>rdbuf()->open(path(s), mode)</code>
+or <code>rdbuf()->open(p, mode)</code> as appropriate
+</blockquote>
+End of proposed text.
+<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" width="1066">
+
+<tr><td width="112">Constructor argument</td>
+<td width="160">Elements found by iteration</td>
+<td width="112"><code>string()</code></td>
+<td width="112"><code>file_ string()</td>
+<td width="72"><code>root_ path() .string()</code></td>
+<td width="48"><code>root_ name()</code></td>
+<td width="88"><code>root_ directory()</code></td>
+<td width="96"><code>relative_ path() .string()</code></td>
+<td width="72"><code>branch_ path() .string()</code></td>
+<td width="72"><code>leaf()</code></td>
+</tr>
+<tr>
+<td width="112"><code>""</code></td>
+<td width="160"><code>""</code></td>
+<td width="112"><code>""</code></td>
+<td width="112"><code>""</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>""</code></td>
+<td width="72"><code>""</code></td>
+<td width="72"><code>""</code></td>
+</tr>
+<tr>
+<td width="112"><code>"."</code></td>
+<td width="160"><code>"."</code></td>
+<td width="112"><code>"."</code></td>
+<td width="112"><code>"."</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"."</code></td>
+<td width="72"><code>""</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>".."</code></td>
+<td width="160"><code>".."</code></td>
+<td width="112"><code>".."</code></td>
+<td width="112"><code>".."</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>".."</code></td>
+<td width="72"><code>""</code></td>
+<td width="72"><code>".."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"foo"</code></td>
+<td width="160"><code>"foo"</code></td>
+<td width="112"><code>"foo"</code></td>
+<td width="112"><code>"foo"</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"foo"</code></td>
+<td width="72"><code>""</code></td>
+<td width="72"><code>"foo"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"/"</code></td>
+<td width="160"><code>"/"</code></td>
+<td width="112"><code>"/"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"/" "\"</code></td>
+<td width="72"><code>"/"</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>"/"</code></td>
+<td width="96"><code>""</code></td>
+<td width="72"><code>""</code></td>
+<td width="72"><code>"/"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"/foo"</code></td>
+<td width="160"><code>"/","foo"</code></td>
+<td width="112"><code>"/foo"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"/foo" "\foo"</code></td>
+<td width="72"><code>"/"</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>"/"</code></td>
+<td width="96"><code>"foo"</code></td>
+<td width="72"><code>"/"</code></td>
+<td width="72"><code>"foo"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"foo/"</code></td>
+<td width="160"><code>"foo","."</code></td>
+<td width="112"><code>"foo/"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"foo/" "foo\"</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"foo/"</code></td>
+<td width="72"><code>"foo"</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"/foo/"</code></td>
+<td width="160"><code>"/","foo","."</code></td>
+<td width="112"><code>"/foo/"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"/foo/" "\foo\"</code></td>
+<td width="72"><code>"/"</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>"/"</code></td>
+<td width="96"><code>"foo/"</code></td>
+<td width="72"><code>"/foo"</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"foo/bar"</code></td>
+<td width="160"><code>"foo","bar"</code></td>
+<td width="112"><code>"foo/bar"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"foo/bar" "foo\bar"</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"foo/bar"</code></td>
+<td width="72"><code>"foo"</code></td>
+<td width="72"><code>"bar"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"/foo/bar"</code></td>
+<td width="160"><code>"/","foo","bar"</code></td>
+<td width="112"><code>"/foo/bar"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"/foo/bar" "\foo\bar"</code></td>
+<td width="72"><code>"/"</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>"/"</code></td>
+<td width="96"><code>"foo/bar"</code></td>
+<td width="72"><code>"/foo"</code></td>
+<td width="72"><code>"bar"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"///foo///"</code></td>
+<td width="160"><code>"/","foo","."</code></td>
+<td width="112"><code>"///foo///"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"///foo///" "\foo\\\"</code></td>
+<td width="72"><code>"/"</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>"/"</code></td>
+<td width="96"><code>"foo///"</code></td>
+<td width="72"><code>"///foo"</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"///foo///bar"</code></td>
+<td width="160"><code>"/","foo","bar"</code></td>
+<td width="112"><code>"///foo///bar"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"///foo///bar" "\foo\\\bar"</code></td>
+<td width="72"><code>"/"</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>"/"</code></td>
+<td width="96"><code>"foo///bar"</code></td>
+<td width="72"><code>"///foo"</code></td>
+<td width="72"><code>"bar"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"/."</code></td>
+<td width="160"><code>"/","."</code></td>
+<td width="112"><code>"/."</code></td>
+<td bgcolor="#99FF66" width="112"><code>"/." "\."</code></td>
+<td width="72"><code>"/"</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>"/"</code></td>
+<td width="96"><code>"."</code></td>
+<td width="72"><code>"/"</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"./"</code></td>
+<td width="160"><code>".","."</code></td>
+<td width="112"><code>"./"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"./" ".\"</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"./"</code></td>
+<td width="72"><code>"."</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"/.."</code></td>
+<td width="160"><code>"/",".."</code></td>
+<td width="112"><code>"/.."</code></td>
+<td bgcolor="#99FF66" width="112"><code>"/.." "\.."</code></td>
+<td width="72"><code>"/"</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>"/"</code></td>
+<td width="96"><code>".."</code></td>
+<td width="72"><code>"/"</code></td>
+<td width="72"><code>".."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"../"</code></td>
+<td width="160"><code>"..","."</code></td>
+<td width="112"><code>"../"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"../" "..\"</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"../"</code></td>
+<td width="72"><code>".."</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"foo/."</code></td>
+<td width="160"><code>"foo","."</code></td>
+<td width="112"><code>"foo/."</code></td>
+<td bgcolor="#99FF66" width="112"><code>"foo/." "foo\."</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"foo/."</code></td>
+<td width="72"><code>"foo"</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"foo/.."</code></td>
+<td width="160"><code>"foo",".."</code></td>
+<td width="112"><code>"foo/.."</code></td>
+<td bgcolor="#99FF66" width="112"><code>"foo/.." "foo\.."</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"foo/.."</code></td>
+<td width="72"><code>"foo"</code></td>
+<td width="72"><code>".."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"foo/./"</code></td>
+<td width="160"><code>"foo",".","."</code></td>
+<td width="112"><code>"foo/./"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"foo/./" "foo\.\"</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"foo/./"</code></td>
+<td width="72"><code>"foo/."</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"foo/./bar"</code></td>
+<td width="160"><code>"foo",".","bar"</code></td>
+<td width="112"><code>"foo/./bar"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"foo/./bar" "foo\.\bar"</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"foo/./bar"</code></td>
+<td width="72"><code>"foo/."</code></td>
+<td width="72"><code>"bar"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"foo/.."</code></td>
+<td width="160"><code>"foo",".."</code></td>
+<td width="112"><code>"foo/.."</code></td>
+<td bgcolor="#99FF66" width="112"><code>"foo/.." "foo\.."</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"foo/.."</code></td>
+<td width="72"><code>"foo"</code></td>
+<td width="72"><code>".."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"foo/../"</code></td>
+<td width="160"><code>"foo","..","."</code></td>
+<td width="112"><code>"foo/../"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"foo/../" "foo\..\"</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"foo/../"</code></td>
+<td width="72"><code>"foo/.."</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"foo/../bar"</code></td>
+<td width="160"><code>"foo","..","bar"</code></td>
+<td width="112"><code>"foo/../bar"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"foo/../bar" "foo\..\bar"</code></td>
+<td width="72"><code>""</code></td>
+<td width="48"><code>""</code></td>
+<td width="88"><code>""</code></td>
+<td width="96"><code>"foo/../bar"</code></td>
+<td width="72"><code>"foo/.."</code></td>
+<td width="72"><code>"bar"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:"</code></td>
+<td width="160"><code>"c:"</code></td>
+<td width="112"><code>"c:"</code></td>
+<td width="112"><code>"c:"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1; border-top-style: solid; border-top-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td width="88"><code>""</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:" ""</code></td>
+<td width="72"><code>""</code></td>
+<td width="72"><code>"c:"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:/"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:","." "c:","/"</code></td>
+<td width="112"><code>"c:/"</code></td>
+<td bgcolor="#99FF66" width="112"><code>
+"c:/" "c:\"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:/"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td bgcolor="#99FF66" width="88"><code>"" "/"</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:/" ""</code></td>
+<td width="72"><code>"c:"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"." "/"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:foo"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:foo" "c:","foo"</code></td>
+<td width="112"><code>"c:foo"</code></td>
+<td width="112"><code>"c:foo"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td width="88"><code>""</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:foo" "foo"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"c:foo" "foo"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:/foo"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:","foo" "c:","/","foo"</code></td>
+<td width="112"><code>"c:/foo"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"c:/foo" "c:\foo"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:/"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td bgcolor="#99FF66" width="88"><code>"" "/"</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:/foo" "foo"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"c:" "c:/"</code></td>
+<td width="72"><code>"foo"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:foo/"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:foo","." "c:","foo","."</code></td>
+<td width="112"><code>"c:foo/"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"c:foo/" "c:foo\"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td width="88"><code>""</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:foo/" "foo/"</code></td>
+<td width="72"><code>"c:foo"</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:/foo/"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:","foo","." "c:","/","foo","."</code></td>
+<td width="112"><code>"c:/foo/"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"c:/foo/" "c:\foo\"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:/"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td bgcolor="#99FF66" width="88"><code>"" "/"</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:/foo/" "foo/"</code></td>
+<td width="72"><code>"c:/foo"</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:/foo/bar"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:","foo","bar" "c:","/","foo","bar"</code></td>
+<td width="112"><code>"c:/foo/bar"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"c:/foo/bar" "c:\foo\bar"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:/"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td bgcolor="#99FF66" width="88"><code>"" "/"</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:/foo/bar" "foo/bar"</code></td>
+<td width="72"><code>"c:/foo"</code></td>
+<td width="72"><code>"bar"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"prn:"</code></td>
+<td width="160"><code>"prn:"</code></td>
+<td width="112"><code>"prn:"</code></td>
+<td width="112"><code>"prn:"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "prn:"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "prn:"</code></td>
+<td width="88"><code>""</code></td>
+<td bgcolor="#99FF66" width="96"><code>"prn:" ""</code></td>
+<td width="72"><code>""</code></td>
+<td width="72"><code>"prn:"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:\"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:\" "c:","/"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"c:\" "c:/"</code></td>
+<td width="112"><code>"c:\"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:/"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td bgcolor="#99FF66" width="88"><code>"" "/"</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:\" ""</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"c:\" "/"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:foo"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:foo" "c:","foo"</code></td>
+<td width="112"><code>"c:foo"</code></td>
+<td width="112"><code>"c:foo"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td width="88"><code>""</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:foo" "foo"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"c:foo" "foo"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:\foo"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:\foo" "c:","/","foo"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"c:\foo" "c:/foo"</code></td>
+<td width="112"><code>"c:\foo"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:/"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td bgcolor="#99FF66" width="88"><code>"" "/"</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:\foo" "foo"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:/"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"c:\foo" "foo"</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:foo\"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:foo\" "c:","foo","."</code></td>
+<td bgcolor="#99FF66" width="112"><code>"c:foo\" "c:foo/"</code></td>
+<td width="112"><code>"c:foo\"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td width="88"><code>""</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:foo\" "foo/"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:foo"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"c:foo\" "."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:\foo\"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:\foo\" "c:","/","foo","."</code></td>
+<td bgcolor="#99FF66" width="112"><code>"c:\foo\" "c:/foo/"</code></td>
+<td width="112"><code>"c:\foo\"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:/"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td bgcolor="#99FF66" width="88"><code>"" "/"</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:\foo\" "foo/"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:/foo"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"c:\foo\" "."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:\foo/"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:\foo","." "c:","/","foo","."</code></td>
+<td bgcolor="#99FF66" width="112"><code>"c:\foo/" "c:/foo/"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"c:\foo/" "c:\foo\"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:/"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td bgcolor="#99FF66" width="88"><code>"" "/"</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:\foo/" "foo/"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"c:\foo" "c:/foo"</code></td>
+<td width="72"><code>"."</code></td>
+</tr>
+<tr>
+<td width="112"><code>"c:/foo\bar"</code></td>
+<td bgcolor="#99FF66" width="160"><code>"c:","foo\bar" "c:","/","foo","bar"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"c:/foo\bar" "c:/foo/bar"</code></td>
+<td bgcolor="#99FF66" width="112"><code>"c:/foo\bar" "c:\foo\bar"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"" "c:/"</code></td>
+<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1; border-bottom-style: solid; border-bottom-width: 1" width="48"><code>
+"" "c:"</code></td>
+<td bgcolor="#99FF66" width="88"><code>"" "/"</code></td>
+<td bgcolor="#99FF66" width="96"><code>"c:/foo\bar" "foo/bar"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"c:" "c:/foo"</code></td>
+<td bgcolor="#99FF66" width="72"><code>"foo\bar" "bar"</code></td>
+</tr>
+</table>
+<h2><a name="Suggestions-for-fstream">Suggestions for <code><fstream></code></a>
+implementations</h2>
+The change in semantics to functions
+taking <code>const char*</code> arguments can break existing code, but only on
+operating systems where implementations don't
+implicitly accept native format pathnames or
+operating systems that allow slashes in filenames. Thus on POSIX,
+Windows, and OpenVMS, for example, there is no problem if the
+implementation follows encouraged behavior.
+For most of the Filesystem Library,
+there is no existing code, so the issue preserving existing code that uses
+slashes in filenames doesn't arise. New code simply must use basic_path
+constructors with <code>path_format_t</code> arguments of <code>native</code>.
+To preserve existing fstream code that uses slashes in filenames, an
+implementation may wish to provide a mechanism such as a macro to control
+selection of the old behavior.
+Implementations are already required
+by the TR front-matter to provide a mechanism such as a macro to control
+selection of the old behavior (useful to guarantee protection of existing code)
+or new behavior (useful in new code, and code being ported from other systems)
+for headers. Because use of the rest of the Filesystem Library is independent of
+use of the <code><fstream></code> additions, affected implementations are
+encouraged to allow disabling the <code><fstream></code> additions separately
+from other TR features.
+An rejected alternative was to supply
+new fstream classes in namespace <code>sys</code>, inheriting from the current
+classes, overriding the constructors and opens taking pathname arguments, and
+providing the additional overloads. In Lillehammer LWG members indicated lack of
+support for this alternative, feeling that costs outweigh benefits.
+<h2><a name="Issues">Issues</a></h2>
+<h3>1. Return type of certain basic_path members returning strings. [Howard
+Hinnant]</h3>
+For member functions described as returning "<code>const string_type</code>"
+or "<code>const external_string_type</code>", implementations are permitted to
+return "<code>const string_type&</code>" or  "<code>const
+external_string_type&</code>" respectively.
+This allows implementations to avoid unnecessary copies. Return-by-value is
+specified as
+<code>const</code> to ensure programs won't break if moved to a
+return-by-reference implementation.
+For example, the Boost implementation keeps the internal representation of a
+pathname in the portable format, so string() returns by reference and is inlined:
+<blockquote>
+ <pre>const string_type & string() const { return m_path; }</pre>
+</blockquote>
+Howard Hinnant comments: This may inhibit optimization if rvalue reference is
+accepted.  Const-qualified return types can't be moved from.  I'd
+rather see either the return type specified as
+<code>const string_type&</code> or <code>string_type</code>.
+Beman Dawes comments: I can't make up my mind. Removing the const will bite
+users, but not very often. OTOH, excessive copying is a real concern, and if
+move semantics can alleviate that, I'm all for it. What does the LWG think?
+<h3>2. Basic_path canonize() and normalize() removed. [Beman Dawes]</h3>
+The Boost implementation has basic_path functions canonize() and normalize()
+which return cleaned up string representations of a pathname. They have been
+removed from the proposal as messy to specify and implement, not hugely useful,
+and possible to implement by users as non-member functions without any loss of
+functionality or efficiency. There was also a concern the proposal was getting a
+bit large.
+These functions can be added later as convenience functions if the LWG so
+desires..
+<h3>3. Filename checking functions. [Beman Dawes]</h3>
+Boost has a set of predicate functions that determine if a filename is valid
+for a particular operating or system. These can be used as building blocks for
+functions that determine if an entire pathname is valid for a particular
+operating or file system.
+Users can use these functions to ensure that pathnames are in fact portable
+to target operating or file systems, without having to actually test on the
+target systems.
+These functions are not included in the proposal because of lack of time, and
+uncertainty as to their fit with the Standard Library. They can be added later
+if the LWG so desires.
+<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 Kühl 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.
+Howard Hinnant and John Maddock reviewed a draft of the proposal, and
+identified a number of mistakes or weaknesses, resulting in a more polished
+final document.
+<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>
+<h2><a name="Revision-History">Revision History</a></h2>
+<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
+ <tr>
+ <td width="11%" valign="top">
+ <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1841.html">
+ N1841</a></td>
+ <td width="89%">
+ <ul>
+ <li>Initial version, August, 2005, pre-Tremblant mailing</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td width="11%" valign="top" bgcolor="#FFFFFF">
+ <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1889.html">
+ N1889</a> 
+ Revision 1</td>
+ <td width="89%" bgcolor="#FFFFFF">
+ <ul>
+ <li>Missing argument name <code>fmt</code> added to several <code>
+ basic_path</code> members.</li>
+ <li> <code>is_empty()</code> name discrepancy between synopsis and
+ description corrected.</li>
+ <li><code>file_size()</code> return type changed from <code>intmax_t</code>
+ to <code>uintmax_t</code>.  Wording slightly clarified.</li>
+ <li><code>struct space_info</code> and non-member function <code>space()</code>
+ added.</li>
+ <li>A paragraph was added to Important design decisions
+ mentioning the need for both portable and platform specific semantics.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td width="11%" valign="top" bgcolor="#FFFFFF">
+ <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1934.html">
+ N1934</a> 
+ Revision 2</td>
+ <td width="89%" bgcolor="#FFFFFF">
+ <ul>
+ <li>Changed native path identification from constructor argument to
+ <code>"//:"</code> escape prefix. Rationale: simplifies basic_path
+ constructor interfaces, easier use for platforms needing explicit native
+ format identification.</li>
+ <li>Introduced a new base class, filesystem_error, to
+ allow users to catch a single exception type if desired, or to deal with
+ the case where the templated type is unknown. Rename filesystem_error and
+ wfilesystem_error accordingly.</li>
+ <li>Rewording
+ basic_filesystem_error text to more closely follow the form of clause 19
+ of the standard.</li>
+ <li>Removed dual specification of
+ certain errors in both "Reguires" and "Throws" paragraphs. Since throwing
+ an exception is well-defined behavior, the error condition does not result
+ in undefined behavior as implied by "Requires". (Suggested by Dave
+ Abrahams)</li>
+ <li>Added a non-throwing version
+ of create_hard_link().</li>
+ <li>Added two create_symlink()
+ functions.</li>
+ <li>Added basic_path inserter and
+ extractor. (Suggested by Vladimir Prus)</li>
+ <li>Added basic_path member and
+ non-member swap() functions.</li>
+ <li>Aligned basic_path operator
+ functions with std::basic_string practice. </li>
+ <li>Replaced status_flags with
+ file_type enum and file_status class to improve encapsulation and allow
+ for future expansion of file_status.</li>
+ <li>Added predicate functions
+ overloaded on file_status (Suggested by Martin Adrian). This change,
+ coupled with the introduction of file_status, clarifies the meaning of
+ file types and related predicate operations, and eliminates the need for
+ user bit manipulation, which was a source of user error.</li>
+ <li>Predicate function
+ specification clarified accordingly.</li>
+ <li>Revised and explicitly
+ documented policy for non-throwing versions of functions to increase
+ consistency.</li>
+ <li>Added basic_directory_iterator
+ constructor non-throwing overload (Suggested by Martin Adrian).</li>
+ <li>Changed symlink awareness to
+ separately name functions to cut clutter caused by addition of
+ non-throwing overloads.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td width="11%" valign="top" bgcolor="#FFFFFF">
+ N1975 
+ Revision 3</td>
+ <td width="89%" bgcolor="#FFFFFF">
+ <ul>
+ <li>Factored non-filesystem
+ related error handling into separate <system_error> header. This
+ change grew out of a Boost developer's list discussion of error handling
+ guidelines for functions likely to use operating system API calls.</li>
+ <li>Added <code>basic_path::clear()</code>
+ in response to user request.</li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+<hr>
+© Copyright Beman Dawes, 2002-2006
+Revised
+2006-04-04
+
+</body>
+
+</html>

Date view	Thread view	Subject view	Author view

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