Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/filesystem/doc/tr2_proposal.html @ 30

Last change on this file since 30 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 192.0 KB
Line 
1<html>
2
3<head>
4<meta http-equiv="Content-Language" content="en-us">
5<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
6<meta name="ProgId" content="FrontPage.Editor.Document">
7<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
8<title>Filesystem Library Proposal
9</title>
10</head>
11
12<body bgcolor="#FFFFFF">
13
14<p>Doc. no.&nbsp;&nbsp; WG21/D1934=06-0004<br>
15Date:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2006-01-31<br>
16Project:&nbsp;&nbsp;&nbsp;&nbsp; Programming Language C++<br>
17Reply to:&nbsp;&nbsp; Beman Dawes &lt;<a href="mailto:bdawes@acm.org">bdawes@acm.org</a>&gt;</p>
18
19<h1 align="center"><i><font size="7">Draft</font></i></h1>
20
21<h1>Filesystem Library Proposal for TR2 (Revision 2)</h1>
22
23<h2><a name="TOC">Table of Contents</a></h2>
24
25<table border="0" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
26  <tr>
27    <td width="26%" valign="top"><a href="#Introduction">Introduction</a><br>
28<a href="#Motivation">Motivation and Scope</a><br>
29<a href="#Impact">Impact on the Standard</a><br>
30<a href="#Design">Important Design Decisions</a><br>
31<a href="#Text">Proposed Text for TR2</a><br>
32&nbsp;&nbsp;&nbsp; <a href="#Text">Introductory chapter</a><br>
33&nbsp;&nbsp;&nbsp; <a href="#Filesystem-library">Filesystem library chapter</a><br>
34&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#Definitions">Definitions</a><br>
35&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#Requirements">Requirements</a><br>
36&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
37<a href="#Requirements-on-programs">Requirements on programs</a><br>
38&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
39<a href="#Requirements-on-implementations">Requirements</a><br>
40&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
41<a href="#Requirements-on-implementations">on implementations</a><br>
42&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#Header-filesystem-synopsis">
43    Header &lt;filesystem&gt; synopsis</a><br>
44&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#Path-traits">Path traits</a><br>
45&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#Class-template-basic_path">
46    Class template basic_path</a><br>
47&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
48<a href="#Pathname-formats">Pathname formats</a><br>
49&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
50<a href="#Pathname-grammar">Pathname grammar</a><br>
51&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
52<a href="#Filename-conversion">Filename conversion</a><br>
53&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
54<a href="#basic_path-requirements">Requirements</a> </td>
55    <td width="35%" valign="top">&nbsp;Class template basic_path (continued)<br>
56&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
57<a href="#basic_path-requirements">basic_path constructors</a><br>
58&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
59<a href="#basic_path-assignments">basic_path assignments</a><br>
60&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
61<a href="#basic_path-modifiers">basic_path modifiers</a><br>
62&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
63<a href="#basic_path-inserter-extractor">basic_path operators</a><br>
64&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
65<a href="#basic_path-observers">basic_path observers</a><br>
66&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
67<a href="#basic_path-iterators">basic_path iterators</a><br>
68&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
69<a href="#basic_path-non-member-functions">basic_path non-member functions</a><br>
70&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
71<a href="#basic_path-inserter-extractor">basic_path inserter and extractor</a><span style="background-color: #FFFFFF"><br>
72&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
73</span> <a href="#Class-filesystem_error">
74<span style="background-color: #FFFFFF">Class filesystem_error</span></a><span style="background-color: #FFFFFF"><br>
75</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
76<a href="#Class-template-basic_filesystem_error">Class template
77    basic_filesystem_error</a><br>
78&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
79<a href="#basic_filesystem_error-constructors">basic_filesystem_error
80    constructors</a><br>
81&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
82<a href="#basic_filesystem_error-observers">basic_filesystem_error observers</a><br>
83&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
84<a href="#Class-template-basic_directory_entry">Class template
85    basic_directory_entry</a><br>
86&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
87<a href="#basic_directory_entry-constructors">basic_directory_entry constructors</a><br>
88&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
89<a href="#basic_directory_entry-modifiers">basic_directory_entry modifiers</a><br>
90&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
91<a href="#basic_directory_entry-observers">basic_directory_entry observers</a><br>
92&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
93<a href="#basic_directory_entry-comparisons">basic_directory_entry comparisons</a></td>
94    <td width="89%" valign="top">Filesystem library chapter (continued)<br>
95&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
96<a href="#Class-template-basic_directory_iterator">Class template
97    basic_directory_iterator</a><br>
98&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
99<a href="#basic_directory_iterator-constructors">basic_directory_iterator
100    constructors</a><br>
101&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
102<a href="#Class-template-basic_recursive_directory_iterator">Class template
103    basic_recursive_directory_iterator</a><br>
104&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#file_status">Class
105    file_status</a><br>
106&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#Non-member-functions">
107    Non-member operational functions</a><br>
108&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
109<a href="#Status-functions">Status functions</a><br>
110&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
111<a href="#Predicate-functions">Predicate functions</a><br>
112&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
113<a href="#Attribute-functions">Attribute functions</a><br>
114&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
115<a href="#Operations-functions">Other operations functions</a><br>
116&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
117<a href="#Convenience-functions">Convenience functions</a><br>
118&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#header-cerrno">Additions to
119    header &lt;cerrno&gt;</a><br>
120&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#header-fstream">Additions
121    to header &lt;fstream&gt;</a><br>
122<a href="#Suggestions-for-fstream">Suggestions for <code>&lt;fstream&gt;</code></a><code><br>
123&nbsp; </code>
124<a href="#Suggestions-for-fstream">&nbsp;implementations</a><br>
125<a href="#Path-decomposition-table">Path decomposition table</a><br>
126<a href="#Issues">Issues</a><br>
127<a href="#Acknowledgements">Acknowledgements</a><br>
128<a href="#References">References</a><br>
129<a href="#Revision-History"><span style="background-color: #FFFFFF">Revision
130History</span></a></td>
131  </tr>
132</table>
133
134<h2><a name="Introduction">Introduction</a></h2>
135<p>This paper proposes addition of a&nbsp; filesystem library component
136to the C++ Standard Library Technical Report 2. The proposal is based on the Boost Filesystem Library (see <a href="http://www.boost.org/libs/filesystem">www.boost.org/libs/filesystem</a>).</p>
137<p>The library provides portable facilities to query and
138manipulate paths, files, and directories. The Boost version of the library is widely used. It would
139be a pure addition to the C++ standard, leaving in place existing
140standard library functionality in the relatively few areas where there is overlap.</p>
141<p>Users say they prefer the Boost Filesystem Library  interface to native
142operating system or
143<i>POSIX</i> API's, even in code without portability requirements, because the design
144follows modern C++ practice.</p>
145<p>The proposed text includes an <a href="#Example-program">example</a> of a
146program using the library.</p>
147<h2><a name="Motivation">Motivation</a> and Scope</h2>
148<p><b><i>Why is this important? </i></b></p>
149<p>The motivation for the library is the desire to perform <i><b>safe, portable,  script-like filesystem operations</b></i> from within C++ programs. Because the
150C++ Standard Library currently contains no facilities for such filesystem tasks
151as directory iteration or directory creation, programmers currently must rely on
152operating system specific  interfaces, making it difficult to write
153portable programs.</p>
154<p>The intent is not to compete
155with Python, Perl, or shell scripting languages, but rather to provide
156file system operations where C++ is already the language of choice. The design
157encourages, but does not require, safe and portable usage.</p>
158<p><b><i>What kinds of problems does it address, and what kinds of programmers is
159it intended to support?</i></b></p>
160<p>The library addresses everyday needs, for both application programs and
161libraries. It is useful across every application domain that uses files. It is
162intended to be useful to all levels of programmers, from rank beginners to
163seasoned experts.</p>
164<p><b><i>Is it based on existing practice?</i></b></p>
165<p>Yes, very much so. The proposal is based on the Boost Filesystem Library,
166which has been in use since 2002 and by now is in very wide use. For example,
167current versions of Adobe Systems products such as Adobe Reader use the Boost
168Filesystem Library on the many platforms they support.</p>
169<p>Note, however, that until recently all the Boost experience was with a
170narrow-character only version of the library. The internationalized version as
171described in this proposal is just starting to be used, and will not be fully
172released until Boost release 1.34.</p>
173<p>The underlying mechanisms have been in use for decades on the world's most
174wide-spread operating systems, such as <i>POSIX</i>, <i>Windows</i>, and various
175mainframe operating systems. What this proposal brings to the table is an
176approach that is C++
177Standard Library friendly and fully internationalized.</p>
178<p><b><i>Is there a reference implementation?</i></b></p>
179<p>Yes. The Boost Filesystem Library is freely and publicly available.  The Boost library will track the TR2 proposed
180library as the proposal evolves.</p>
181<h2><a name="Impact">Impact</a> on the Standard</h2>
182<p><b><i>What does it depend on, and what depends on it?</i></b></p>
183<p>It depends on
184some standard library components, such as basic_string. No other proposals
185depend on it.</p>
186<p>If a revision to the Code Conversion Proposal (See
187<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1683.html">
188http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1683.html</a>) is
189accepted, it may be advantageous for the Filesystem Library
190to use that library rather than the current code conversion facilities proposed
191below.</p>
192<p><b><i>Is it a pure extension, or does it require changes to standard
193components?</i></b></p>
194<p>Most of the proposed library is a pure extension.</p>
195<p>There are <a href="#header-cerrno">additions to header &lt;cerrno&gt;</a>. Since
196the critical portions that might require change to C headers (always a sore
197point) are already mandated for <i>POSIX</i> compliance, and codify
198existing practice for many non-<i>POSIX</i> implementations such as for <i>Windows</i>, it is not expected that they will cause any problems.</p>
199<p>There are <a href="#header-fstream">additions to header &lt;fstream&gt;</a>.&nbsp; 
200These have been carefully specified to avoid breaking existing code in common operating environments such as <i>POSIX</i>, <i>
201Windows</i>, and <i>OpenVMS</i>. See <a href="#Suggestions-for-fstream">
202Suggestions for <code>&lt;fstream&gt;</code> implementations</a> for techniques to
203avoid breaking existing code in other environments, particularly on operating
204systems allowing slashes in filenames.</p>
205<p><b><i>Can it be implemented using today's compilers, or does it require
206language features that will only be available as part of C++0x?</i></b></p>
207<p>It can
208be (and has been) implemented with today's compilers.</p>
209<p>There is one minor function that can best be implemented by an addition to
210current C++ runtime libraries, although an acceptable workaround is documented.</p>
211<p>On operating systems with built-in support for wide-character file names,
212such as <i>Windows</i>, high-quality implementation of the header &lt;fstream&gt; 
213additions require an addition to the C++ Standard Library implementation. The
214addition is relatively small and localized. There is a workaround that avoids
215modifying the standard library, but it is very much a hack and depends on a <i>
216Windows</i> feature (8.3 filename support) which some users disable, thereby
217disabling the workaround. The issue doesn't affect implementations on operating
218systems which only support narrow character file names.</p>
219<h2>Important <a name="Design">Design</a> Decisions</h2>
220<h4><i>Why did you choose the specific design that you did?</i></h4>
221<p>Many of the specific design decisions were driven by the desire to provide a modern C++ interface
222that works
223well with the C++ Standard Library. The intent is that Standard Library users
224can become comfortable with the Filesystem Library in very short order.</p>
225<p>The proposed library encourages both syntactic and semantic portability, yet
226does not force implementors into heroic efforts on hopeless systems. This
227balances the benefits to users of both code and knowledge portability with the
228realities faced by implementors on some operating systems.</p>
229
230<p><span style="background-color: #FFFFFF">In some
231cases users always need portable semantics. In some cases users always need
232platform specific semantics. In some cases users need to be able to choose
233between portable and platform specific semantics. The design evolved over a
234period of years to identify and meet each of those needs. </span></p>
235
236<p>Because of the desire to support simple &quot;script-like&quot; usage, use cases often
237drove design choices. For example, users can write <code>if (exists(&quot;foo&quot;))</code> rather than
238the lengthier <code>if (exists(path(&quot;foo&quot;)))</code>.</p>
239
240<p>Because filesystem operations often encounter unexpected runtime errors, the library reports runtime errors via C++ exceptions,
241and ensures enough information is provided for meaningful error messages,
242including internationalized error messages.</p>
243
244<p><b><i>What alternatives did you consider, and what are the tradeoffs?</i></b></p>
245<p><i>Additional observers and modifiers for file system attributes.</i> 
246Attribute functions which cannot supply portable semantics are not provided,
247avoiding the illusion of portability in cases where it cannot in fact exist.</p>
248<p><i>A larger number of operational convenience functions.</i> 
249Convenience functions (functions which can be portably created by composition
250from basic functions) were not provided unless there was widespread agreement on
251usefulness and need.</p>
252<p><i>Compile-time or run-time options for  operational functions.</i> 
253Numerous trial implementations were abandoned because the added complexity
254out weighed the benefits, and because consensus could not be reached on the
255feature set.</p>
256<p><i>Automatic path name checking.</i> This feature, supplied by the Boost
257library for several years, allowed users to specify both default and per
258constructor path name checking, and thus allowed the desired degree of portability to be
259automatically enforce. This implicit name checking was abandoned because of user
260confusion and complaints.</p>
261<p><i>Separate path types for regular file and directory pathnames.</i> Pathname
262formats that use different syntax for regular pathnames versus directory
263pathnames are passing into extinction. Why prolong the agony at the cost of
264torturing those using modern systems? It is perhaps significant that one of the few web
265sites dedicated to preserving a dual pathname format operating system is named
266<i>Deathrow</i> (<a href="http://deathrow.vistech.net/">http://deathrow.vistech.net/</a>).</p>
267<p><i>Single path type which can at runtime accept narrow or wide character
268pathnames.</i> Although certainly interesting, and possibly superior, such a
269design would not interoperate well with the current Standard Library's compile-time
270typed <code>basic_string</code>. A new runtime polymorphic string class would be
271the best place to experiment with this concept, not a path class.</p>
272<p><b><i>What are the consequences of your choices, for users and implementors?</i></b></p>
273<p>The design has evolved over a period of four years of actual experience by
274Boost users, and the most frequent causes of user complaints (such as enforced
275name-checking and several over-strict preconditions) were eliminated. The TR
276process will allow further refinement. The intent is to ensure user needs are
277met.</p>
278<p>Because the Boost implementation is tested and
279used in a wide range of <i>POSIX</i> and <i>Windows</i> environments, many implementation
280concerns have already been addressed.</p>
281<p><b><i>What decisions are left up to implementors?</i></b></p>
282<p>Because implementations of the library are dependent on facilities of the
283underlying operating system, implementors are given unusual freedom to redefine
284semantics of the library. That being said, implementors are given strong
285normative encouragement to provide the TR described semantics whenever feasible.</p>
286<p><b><i>If there are any similar libraries in use, how do their design
287decisions compare to yours?</i></b></p>
288<p>There are a number of libraries which address the problem domain. Most of the
289C/C++ libraries have C, rather than C++ interfaces. For example, see the Apache Portable Runtime
290Project (<a href="http://apr.apache.org">http://apr.apache.org</a>). The ACE
291toolkit (<a href="http://www.cs.wustl.edu/~schmidt/ACE.html">http://www.cs.wustl.edu/~schmidt/ACE.html</a>)
292uses a C++ approach, but doesn't mesh well with the C++ Standard Library. For
293example, the ACE directory iterator differs greatly from Standard Library
294iterator requirements.</p>
295<h2>Proposed <a name="Text">Text</a> for Technical Report 2</h2>
296<p><span style="font-style: italic; background-color: #E0E0E0">Gray-shaded
297italic text is commentary on the proposal. It is not to be added to the TR.</span></p>
298<p><span style="background-color: #FFFFFF"><i>Italic text is editorial guidance.
299It is not to be added to the TR.</i></span></p>
300<p><span style="font-style: italic; background-color: #FFFFFF">
301<a name="frontmatter">Add</a> to the
302introductory section of the TR:</span></p>
303<p>The following standard contains provisions which, through reference in this
304text, constitute provisions of this Technical Report. At the time of
305publication, the editions indicated were valid. All standards are subject to
306revision, and parties to agreements based on this Technical Report are
307encouraged to investigate the possibility of applying the most recent editions
308of the standard indicated below. Members of IEC and ISO maintain registers of
309currently valid International Standards.</p>
310  <ul>
311    <li>ISO/IEC 9945:2003, <i>Portable Operating System Interface (POSIX<a href="#Footnote-1"><sup>1</sup></a>),
312    part 1 (Base Definitions) and part 2 (System Interfaces)</i>, both as corrected by their
313    respective 2004 Correction 1 documents.<p>[<i>Note:</i> ISO/IEC 9945:2003 is
314    also IEEE&nbsp;Std&nbsp;1003.1-2001, and The Open Group Base Specifications, Issue 6,
315    and also known as The Single Unix<font face="Times New Roman"><sup><a href="#Footnote-2">2</a></sup><i><b>
316    </b></i>Specification, Version 3. It is available from each of those organizations,
317    and may be read online or downloaded from
318    <a href="http://www.unix.org/single_unix_specification/">
319    www.unix.org/single_unix_specification/</a> <i>-- end note</i>]</font></p>
320    </li>
321  </ul>
322<p>ISO/IEC 9945:2003, with the indicated corrections, is hereinafter called <i>
323POSIX</i>.</p>
324<p>Some library behavior in this Technical Report is defined by reference to <i>
325POSIX</i>. How such behavior is actually implemented is unspecified.</p>
326<blockquote>
327<p>[<i>Note:</i> This constitutes an &quot;as if&quot; rule for implementation of
328operating system dependent behavior. Presumably implementations will actually call native
329operating system API's. <i>--end note</i>]</p>
330</blockquote>
331<p>Implementations are encouraged, but not required, to support such behavior
332 
333as it is defined by <i>POSIX</i>. Implementations shall document any
334behavior that differs from the <i>POSIX</i> defined behavior. Implementations that do not support exact <i>POSIX</i> behavior are
335encouraged to provide behavior as close to <i>POSIX</i> behavior as is reasonable given the
336limitations of actual operating systems. If an implementation cannot provide any
337reasonable behavior, the implementation shall report an error in an
338implementation-defined manner.</p>
339<blockquote>
340<p>[<i>Note:</i> Such errors might be reported by an #error directive, a <code>
341static_assert</code>, a <code>basic_filesystem_error</code> exception, a special
342return value, or some other manner. <i>--end note</i>]</p>
343</blockquote>
344<p><a name="Footnote-1">Footnote 1</a>: <i>POSIX</i>® is a registered trademark of The
345IEEE.</p>
346<p><a name="Footnote-2">Footnote 2</a>: <i>UNIX</i>® is a registered trademark of The
347Open Group.</p>
348<p><span style="background-color: #FFFFFF"><i>Add a new clause to the TR:</i></span></p>
349<hr>
350<h2>Chapter <span style="font-weight: 400"><i>(tbs)</i></span> - <a name="Filesystem-library">Filesystem library</a></h2>
351<hr>
352<p>This clause describes components that C++ programs may use to interrogate and
353manipulate  files (including directories), and certain of their
354attributes.</p>
355<p>This clause applies only to hosted implementations (C++ Std, 1.4,
356Implementation compliance [intro.compliance]).</p>
357<blockquote>
358<p>[<i>Note:</i> This clause  applies to any hosted implementation.
359Specific operating systems such as <i>OpenMVS</i><sup><a href="#Footnote-3">3</a></sup>,
360<i>UNIX</i>, and <i>Windows</i><sup><a href="#Footnote-4">4</a></sup> are mentioned only for purposes of illustration or to
361give guidance to implementors. No slight to other operating systems is implied
362or intended. <i>--end note</i>.]</p>
363</blockquote>
364<p>Unless otherwise specified, all components described in this clause are
365declared in namespace <code>std::tr2::sys</code>.</p>
366<blockquote>
367<p>[<i>Note:</i> The <code>sys</code> sub-namespace prevents collisions with
368names already in the standard library and emphasizes reliance on the
369operating system dependent behavior inherent in file system operations. <i>-- end
370note</i>]</p>
371</blockquote>
372<p>The <i>Effects</i> and <i>Postconditions</i> of functions described in this clause
373may not be achieved in
374the presence of <a href="#Race-condition">race conditions</a>. No diagnostic is required.</p>
375<p>If the possibility of race conditions makes it unreliable for a program to
376test for a precondition before calling a function described in this clause, <i>
377Requires</i> is not specified for the condition. Instead, the condition is
378specified as a <i>Throws</i> condition.</p>
379<blockquote>
380<p>[<i>Note:</i> As a design practice, preconditions are not specified when it
381is unreasonable for a program to detect them prior to calling the function. <i>
382-- end note</i>]</p>
383</blockquote>
384<p><a name="Footnote-3">Footnote 3</a>: <i>OpenMVS</i>® is a registered
385trademark of Hewlett-Packard Development Company.</p>
386<p><a name="Footnote-4">Footnote 4</a>: <i>Windows</i>® is a registered
387trademark of Microsoft Corporation.</p>
388<h3><a name="Definitions">Definitions</a></h3>
389<p>The following definitions shall apply to this clause:</p>
390<p><i><a name="File">File</a>: </i>An object that can be written to, or read from, or both. A file
391has certain attributes, including type. File types include regular file,
392symbolic link, and directory. Other types of files may be supported by the
393implementation.</p>
394<p><i><a name="File-system">File system</a>:</i> A collection of files and certain of their attributes.</p>
395<p><i><a name="Filename">Filename</a>:</i> The name of a file. The format is as
396specified by the <i>POSIX
397<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_169">
398Filename</a></i> base definition.</p>
399<p><i><a name="Path">Path</a>:</i> A sequence of elements which identify
400a location within a filesystem. The elements are the <i>root-name</i>, <i>
401root-directory</i>, and each successive <i>filename</i>. See
402<a href="#Pathname-grammar">Pathname grammar</a>.</p>
403<p><i><a name="Pathname">Pathname</a>: </i>A character string that represents a
404path.</p>
405<p><i><a name="Link">Link</a>: </i>A directory entry object that associates a
406filename with a file. On some file systems, several directory entries can
407associate names with the same file.</p>
408<p><i><a name="Hard-link">Hard link</a>:</i> A link to an existing file. Some
409file systems support multiple hard links to a file. If the last hard link to a
410file is removed, the file itself is removed.</p>
411<blockquote>
412<p>[<i>Note:</i> A hard link can be thought of as a shared-ownership smart
413pointer to a file.<i> -- end note</i>]<i> </i></p>
414</blockquote>
415<p><i><a name="Symbolic-link">Symbolic link</a>: </i>A type of file with the
416property that when the file is encountered during pathname resolution, a string
417stored by the file is used to modify the pathname resolution.</p>
418<blockquote>
419<p>[<i>Note:</i> A symbolic link can be thought of as a raw pointer to a file.
420If the file pointed to does not exist, the symbolic link is said to be a
421&quot;dangling&quot; symbolic link.<i> -- end note</i>]<i> </i></p>
422</blockquote>
423<p><i><a name="Slash">Slash</a>:</i> The character <tt>'/'</tt>, also known as
424solidus.</p>
425<p><i><a name="Dot">Dot</a>:</i> The character '.', also known as period.</p>
426<p><i><a name="Race-condition">Race condition</a>:</i> The condition that occurs
427when multiple threads, processes, or computers interleave access and
428modification of
429the same object within a file system.</p>
430<h3><a name="Requirements">Requirements</a></h3>
431<h4><a name="Requirements-on-programs">Requirements on programs</a></h4>
432<p>The arguments for template parameters named <code>Path</code>, <code>Path1</code>,
433or <code>Path2</code> described in this clause shall be of type <code>basic_path</code>,
434or a class derived from <code>basic_path</code>, unless otherwise
435specified.</p>
436<h4><a name="Requirements-on-implementations">Requirements on implementations</a></h4>
437<p>Some function templates described in this clause have a template parameter
438named <code>Path</code>, <code>Path1</code>, or <code>Path2</code>. When called
439with a function argument <code>s</code> of type <code>char*</code> or <code>
440std::string</code>, the implementation shall treat the argument as if it were
441coded <code>path(s)</code>. When called with a function argument <code>s</code> 
442of type <code>wchar_t*</code> or <code>std::wstring</code>, the implementation
443shall treat the argument as if it were coded <code>wpath(s)</code>. For
444functions with two arguments, implementations shall not supply this treatment
445when <code>Path1</code> and <code>Path2</code> are different types.</p>
446<blockquote>
447<p>[<i>Note:</i> This &quot;do-the-right-thing&quot; rule allows users to write <code>exists(&quot;foo&quot;)</code>,
448taking advantage of class <code>basic_path</code>'s string conversion
449constructor,&nbsp; rather
450than the lengthier and more error prone <code>exists(path(&quot;foo&quot;))</code>. This
451is particularly important for the simple, script-like, programs which are an
452important use case for the library. Calling two argument functions with
453different types is a very rare usage, and may well be a coding error, so
454automatic conversion is not supported for such cases.</p>
455<p>The implementation technique is unspecified. One possible implementation
456technique, using
457<code>exists()</code> as an example, is:</p>
458  <blockquote>
459    <pre>template &lt;class Path&gt;
460  typename boost::enable_if&lt;is_basic_path&lt;Path&gt;,bool&gt;::type exists(const Path&amp; p);
461inline bool exists(const path&amp; p) { return exists&lt;path&gt;(p); }
462inline bool exists(const wpath&amp; p) { return exists&lt;wpath&gt;(p); }</pre>
463  </blockquote>
464  <p>&nbsp;The <code>enable_if</code> will fail for a C string or <code>
465  std::basic_string</code> argument, which will then be automatically converted
466  to a <code>basic_path</code> object via the appropriate <code>basic_path</code> conversion
467  constructor.&nbsp;&nbsp; <i>-- end note</i>]</p>
468  <p><span style="background-color: #E0E0E0"><i>The two overloads are not given
469  in the normative text because:</i></span></p>
470  <ul>
471    <li><span style="background-color: #E0E0E0"><i>Better techniques for
472    achieving the desired affect may be developed, perhaps enabled by core
473    language changes like Concepts.</i></span></li>
474    <li><span style="background-color: #E0E0E0"><i>Implementations may prefer
475    techniques that work with legacy compilers that do not support enable_if.</i></span></li>
476    <li><span style="background-color: #E0E0E0"><i>Spelling out the overloads
477    makes the text longer and harder to read without adding much benefit.</i></span></li>
478    <li><span style="background-color: #E0E0E0"><i>More overloads will probably
479    be needed for char16_t and char32_t (or whatever they end up being called),
480    making it even less attractive to actually spell out each one. </i></span>
481    </li>
482  </ul>
483</blockquote>
484<p>Implementations of functions described in this clause are permitted to call the applications
485program interface (API) provided by the operating system. If such an operating
486system API call results in an error, implementations
487shall report the error by throwing exception <code>basic_filesystem_error</code>,
488unless otherwise specified.</p>
489<blockquote>
490<p>[<i>Note: </i>Such exceptions and the conditions that cause them to be thrown
491are not explicitly described in each <i>Throws</i> element within this clause.
492Because hardware failures, network failures, race conditions, and a plethora of
493other errors occur frequently in file system operations, users should be aware
494that <span style="background-color: #FFFFFF">unless otherwise specified</span> any file system operation, not matter how apparently innocuous, may throw
495an exception. <i>-- end note</i>]</p>
496</blockquote>
497<p><span style="background-color: #FFFFFF">Functions commonly used in contexts
498where errors are not exceptional have overloads taking an additional argument of
499type </span><code><span style="background-color: #FFFFFF">system_error_code&amp;</span></code><span style="background-color: #FFFFFF"> 
500ec. Such overloaded functions shall not throw exceptions. If an error occurs,
501<code>ec</code> shall be set to the
502error code reported by the operating system, otherwise <code>ec</code> shall be set to 0. If
503an overload without an argument of type </span><code>
504<span style="background-color: #FFFFFF">system_error_code&amp;</span></code><span style="background-color: #FFFFFF"> 
505ec returns void, the other overload (without an argument of type </span><code>
506<span style="background-color: #FFFFFF">system_error_code&amp;</span></code><span style="background-color: #FFFFFF"> 
507ec) returns a <code>system_error_code</code> with the value of ec.</span></p>
508<h3><a name="Header-filesystem-synopsis">Header <code>&lt;filesystem&gt;</code> synopsis</a></h3>
509<pre>namespace std
510{
511  namespace tr2
512  {
513    namespace sys
514    {
515      template &lt;class String, class Traits&gt; class <a href="#Class-template-basic_path">basic_path</a>;
516
517      template&lt;class String, class Traits&gt;
518      void swap(basic_path&lt;String, Traits&gt; &amp; lhs, basic_path&lt;String, Traits&gt; &amp; rhs);
519
520      template&lt;class String, class Traits&gt; bool operator&lt;(<i>a</i> a, <i>b</i> b);
521      template&lt;class String, class Traits&gt; bool operator==(<i>a</i> a, <i>b</i> b);
522      template&lt;class String, class Traits&gt; bool operator!=(<i>a</i> a, <i>b</i> b);
523      template&lt;class String, class Traits&gt; bool operator&gt;(<i>a</i> a, <i>b</i> b);
524      template&lt;class String, class Traits&gt; bool operator&lt;=(<i>a</i> a, <i>b</i> b);
525      template&lt;class String, class Traits&gt; bool operator&gt;=(<i>a</i> a, <i>b</i> b);
526      template&lt;class String, class Traits&gt; bool operator/(<i>a</i> a, <i>b</i> b);
527
528      template&lt;class Path&gt;
529        basic_ostream&lt;typename Path::string_type::value_type, typename Path::string_type::traits_type&gt; &amp;
530          operator&lt;&lt;(basic_ostream&lt;typename Path::string_type::value_type, typename Path::string_type::traits_type&gt;&amp; os, const Path &amp; ph);
531
532      template&lt;class Path&gt;
533        basic_istream&lt;typename Path::string_type::value_type, typename Path::string_type::traits_type&gt; &amp;
534          operator&gt;&gt;(basic_istream&lt;typename Path::string_type::value_type, typename Path::string_type::traits_type&gt;&amp; is, Path &amp; ph);
535     
536      struct path_traits;
537      struct wpath_traits;
538
539      typedef basic_path&lt;std::string, path_traits&gt;    path;
540      typedef basic_path&lt;std::wstring, wpath_traits&gt;  wpath;
541
542      template&lt;class Path&gt; struct is_basic_path;
543
544      template&lt;class Path&gt; struct slash { static const char value = '/'; };
545      template&lt;class Path&gt; struct dot   { static const char value = '.'; };
546<span style="background-color: #FFFFFF">      template&lt;class Path&gt; struct colon { static const char value = ':'; };</span><span style="background-color: #FFFF00">
547</span>
548      typedef int errno_type;  // type is determined by the C standard
549      typedef<i> implementation-defined </i>system_error_type; // usually int or unsigned
550
551      <span style="background-color: #FFFFFF">class filesystem_error;</span><span style="background-color: #FFFF00">
552</span>     
553      template &lt;class Path&gt; class <a href="#Class-template-basic_filesystem_error">basic_filesystem_error</a>;
554
555      typedef basic_filesystem_error&lt;path&gt; filesystem<span style="background-color: #FFFFFF">_path</span>_error;
556      typedef basic_filesystem_error&lt;wpath&gt; filesystem<span style="background-color: #FFFFFF">_wpath</span>_error;
557
558      <span style="background-color: #FFFFFF">template &lt;class Path&gt; class <a href="#Class-template-basic_directory_entry">basic_directory_entry</a>;
559
560      typedef basic_directory_entry&lt;path&gt; directory_entry;
561      typedef basic_directory_entry&lt;wpath&gt; wdirectory_entry;
562</span>
563      template &lt;class Path&gt; class <a href="#Class-template-basic_directory_iterator">basic_directory_iterator</a>;
564
565      typedef basic_directory_iterator&lt;path&gt; directory_iterator;
566      typedef basic_directory_iterator&lt;wpath&gt; wdirectory_iterator;
567
568      template &lt;class Path&gt; class <a href="#Class-template-basic_recursive_directory_iterator">basic_recursive_directory_iterator</a>;
569
570      typedef basic_recursive_directory_iterator&lt;path&gt; recursive_directory_iterator;
571      typedef basic_recursive_directory_iterator&lt;wpath&gt; wrecursive_directory_iterator;
572
573      enum file_type { status_unknown, file_not_found, regular_file, directory_file,
574                       symlink_file, block_file, character_file, fifo_file, socket_file,
575                       type_unknown
576                     };
577
578      class <a href="#file_status">file_status</a>;
579
580      <span style="background-color: #FFFFFF">struct space_info  // returned by </span><a href="#space" style="text-decoration: none"><span style="background-color: #FFFFFF">space</span></a><span style="background-color: #FFFFFF"> function
581      {
582        uintmax_t capacity;
583        uintmax_t free;
584        uintmax_t available;
585      };
586</span>
587      //  <a href="#Status-functions">status functions</a>
588      template &lt;class Path&gt; file_status status(const Path&amp; p);
589      template &lt;class Path&gt; file_status status(const Path&amp; p, system_error_code&amp; ec);
590      template &lt;class Path&gt; file_status symlink_status(const Path&amp; p);
591      template &lt;class Path&gt; file_status symlink_status(const Path&amp; p, system_error_code&amp; ec);
592
593      //  <a href="#Predicate-functions">predicate functions</a>
594      bool status_known( file_status s );
595      bool exists( file_status s );
596      bool is_regular( file_status s );
597      bool is_directory( file_status s );
598      bool is_symlink( file_status s );
599      bool is_other( file_status s );
600
601      template &lt;class Path&gt; bool exists(const Path&amp; p);
602      template &lt;class Path&gt; bool is_directory(const Path&amp; p);
603      template &lt;class Path&gt; bool is_regular(const Path&amp; p);
604      template &lt;class Path&gt; bool is_other(const Path&amp; p);
605      template &lt;class Path&gt; bool is_symlink(const Path&amp; p);
606      template &lt;class Path&gt; bool is_empty(const Path&amp; p);
607
608      template &lt;class Path1, class Path2&gt;
609        bool equivalent(const Path1&amp; p1, const Path2&amp; p2);
610
611      //  <a href="#Attribute-functions">attribute functions</a>
612      template &lt;class Path&gt; Path current_path();
613      template &lt;class Path&gt; const Path&amp; initial_path();
614      template &lt;class Path&gt; <span style="background-color: #FFFFFF; ">uintmax_t</span> file_size(const Path&amp; p);
615<span style="background-color: #FFFFFF">      template &lt;class Path&gt; space_info space(const Path&amp; p);</span><span style="background-color: #FFFF00">
616</span>      template &lt;class Path&gt; std::time_t last_write_time(const Path&amp; p);
617      template &lt;class Path&gt;
618        void last_write_time(const Path&amp; p, const std::time_t new_time);
619
620      //  <a href="#Operations-functions">operations functions</a>
621      template &lt;class Path&gt; bool create_directory(const Path&amp; dp);
622      template &lt;class Path1, class Path2&gt;
623        void create_hard_link(const Path1&amp; old_fp, const Path2&amp; new_fp);
624<span style="background-color: #FFFFFF">      template &lt;class Path1, class Path2&gt;
625        system_error_type create_hard_link(const Path1&amp; old_fp, const Path2&amp; new_fp, system_error_code&amp; ec);
626      template &lt;class Path1, class Path2&gt;
627        void create_symlink(const Path1&amp; old_fp, const Path2&amp; new_fp);
628      template &lt;class Path1, class Path2&gt;
629        system_error_type create_symlink(const Path1&amp; old_fp, const Path2&amp; new_fp, system_error_code&amp; ec);
630</span>      template &lt;class Path&gt; bool remove(const Path&amp; p);
631      template &lt;class Path1, class Path2&gt;
632        void rename(const Path1&amp; from_p, const Path2&amp; to_p);
633      template &lt;class Path1, class Path2&gt;
634        void copy_file(const Path1&amp; from_fp, const Path2&amp; to_fp);
635      template &lt;class Path&gt; Path system_complete(const Path&amp; p);
636      template &lt;class Path&gt; Path complete(const Path&amp; p, const Path&amp; base=initial_path&lt;Path&gt;());
637      errno_type lookup_errno(system_error_type code);
638      void system_message(system_error_type code, std::string &amp; target);
639      void system_message(system_error_type code, std::wstring &amp; target);
640
641      //  <a href="#Convenience-functions">convenience functions</a>
642      template &lt;class Path&gt; bool create_directories(const Path &amp; p);
643      template &lt;class Path&gt; typename Path::string_type extension(const Path &amp; p);
644      template &lt;class Path&gt; typename Path::string_type basename(const Path &amp; p);
645      template &lt;class Path&gt;
646        Path replace_extension(const Path &amp; p, const typename Path::string_type &amp; new_extension);
647
648    } // namespace sys
649  } // namespace tr2
650} // namespace std</pre>
651<h3><a name="Path-traits">Path traits</a></h3>
652<p>This subclause defines requirements on classes representing path behavior
653traits, and defines two classes that satisfy those requirements for paths based
654on <code>string</code> and <code>wstring</code>.. It also defines several path
655additional path traits structure templates, and defines several specializations
656of them.</p>
657<p>Class template <code>basic_path</code> defined in this clause requires additional
658types, values, and behavior to complete the definition of its semantics.</p>
659<p>For purposes of exposition, Traits behaves as if it is a class with private
660members bool m_locked, initialized false, and std::locale m_locale, initialized  </p>
661<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
662  <tr>
663    <td width="50%" align="center" colspan="2"><b><i>
664    <a name="Path-Behavior-Traits-Requirements">Path Behavior Traits
665    Requirements</a></i></b></td>
666  </tr>
667  <tr>
668    <td width="38%" align="center"><b><i>Expression</i></b></td>
669    <td width="62%" align="center"><b><i>Requirements</i></b></td>
670  </tr>
671  <tr>
672    <td width="38%" valign="top"><code>Traits::external_string_type</code></td>
673    <td width="62%">A typedef which is a specialization of <code>basic_string</code>.
674    The <code>value_type</code> is a character type used by the operating system
675    to represent pathnames.</td>
676  </tr>
677  <tr>
678    <td width="38%" valign="top"><code>Traits::internal_string_type</code></td>
679    <td width="62%">A typedef which is a specialization of <code>basic_string</code>.
680    The <code>value_type</code> is a character type to be used by the program to
681    represent pathnames. Required be the same type as the <code>basic_path
682    String</code> template parameter. </td>
683  </tr>
684  <tr>
685    <td width="38%" valign="top"><code>Traits::to_external( p, is )</code></td>
686    <td width="62%"><code>is</code>, converted by the <code>m_locale</code>
687    <code>codecvt</code> facet to <code>external_string_type</code>.</td>
688  </tr>
689  <tr>
690    <td width="38%" valign="top"><code>Traits::to_internal( p, xs )</code></td>
691    <td width="62%"><code>xs</code>, converted by the <code>m_locale</code>
692    <code>codecvt</code> facet to to <code>internal_string_type</code>.</td>
693  </tr>
694  <tr>
695    <td width="38%" valign="top"><code>Traits::imbue(loc)</code></td>
696    <td width="62%"><i>Effects:</i> if <code>m_locked</code>, throw. Otherwise,
697    <code>m_locked = true; m_locale = loc;<br>
698    </code><i>Returns:</i> <code>void</code><b><br>
699    </b><i>Throws:</i> <code>basic_filesystem_error</code></td>
700  </tr>
701  <tr>
702    <td width="38%" valign="top"><code>Traits::imbue(loc, std::nothrow)</code></td>
703    <td width="62%"><i>Effects:</i> <code>if (!m_locked) m_locale = loc; bool
704    temp(m_locked); m_locked = true;<br>
705    </code><i>Returns:</i> <code>temp</code></td>
706  </tr>
707</table>
708<p>Type <code>is_basic_path</code> shall be a <i>UnaryTypeTrait</i> (TR1, 4.1).
709The primary template shall be derived directly or indirectly from <code>
710std::tr1::false_type</code>. Type <code>is_basic_path</code> shall be
711specialized for <code>path</code>, <code>wpath</code>, and any
712user-specialized <code>basic_path</code> types, and such specializations shall
713be derived directly or indirectly from <code>std::tr1::true_type</code>.</p>
714<p>Structure templates <code>slash</code>, <code>dot</code>, and <code>
715<span style="background-color: #FFFFFF">colon</span></code><span style="background-color: #FFFFFF">
716</span>are supplied with
717values of type <code>char</code>. If a user-specialized <code>basic_path</code> 
718has a <code>
719value_type</code> type which is not convertible from <code>char</code>, the
720templates&nbsp; <code>slash</code> and <code>dot</code> shall be specialized to
721provide <code>value</code> with type which is convertible to <code>
722basic_path::value_type</code>.</p>
723<h3><a name="Class-template-basic_path">Class template <code>basic_path</code></a></h3>
724<p>Class template <code>basic_path</code> provides a portable mechanism for
725representing <a href="#Path">paths</a> in C++ programs, using a portable generic
726pathname <a href="#Pathname-grammar">grammar</a>. When portability is not a
727requirement, native file system specific formats can be used.&nbsp;Class template
728<code>basic_path</code> is concerned only with the lexical and syntactic aspects
729of a path. The path does not have to exist in the operating system's file
730system, and may contain names which are not even valid for the current operating
731system. </p>
732<blockquote>
733  <p>[<i>Note: </i>If the library's functions trafficked only in C++<i> </i>or
734  C-style strings, they would provide only the illusion of portability since
735  while the syntax of function calls would be portable, the semantics of the
736  strings they operate on would not be portable. <i>-- end note</i>]</p>
737</blockquote>
738<pre>namespace std
739{
740  namespace tr2
741  {
742    namespace sys
743    {
744      template &lt;class String, class Traits&gt; class basic_path
745      {
746      public:
747        typedef basic_path&lt;String, Traits&gt; path_type;
748        typedef String string_type;
749        typedef typename String::value_type value_type;
750        typedef Traits traits_type;
751        typedef typename Traits::external_string_type external_string_type;
752
753        // <a href="#basic_path-constructors">constructors/destructor</a>
754        basic_path();
755        basic_path(const basic_path&amp; p);
756        basic_path(const string_type&amp; s);
757        basic_path(const value_type* s);
758        template &lt;class InputIterator&gt;
759          basic_path(InputIterator first, InputIterator last);
760
761       ~basic_path();
762
763        // <a href="#basic_path-assignments">assignments</a>
764        basic_path&amp; operator=(const basic_path&amp; p);
765        basic_path&amp; operator=(const string_type&amp; s);
766        basic_path&amp; operator=(const value_type* s);
767        template &lt;class InputIterator&gt;
768          basic_path&amp; assign(InputIterator first, InputIterator last);
769
770        // <a href="#basic_path-modifiers">modifiers</a>
771        basic_path&amp; operator/=(const basic_path&amp; rhs);
772        basic_path&amp; operator/=(const string_type&amp; s);
773        basic_path&amp; operator/=(const value_type* s);
774        template &lt;class InputIterator&gt;
775          basic_path&amp; append(InputIterator first, InputIterator last);
776
777        <span style="background-color: #FFFFFF">void swap( basic_path &amp; rhs );</span>
778        basic_path&amp; remove_leaf();
779
780        // <a href="#basic_path-observers">observers</a>
781        const string_type string() const;
782        const string_type file_string() const;
783        const string_type directory_string() const;
784
785        const external_string_type external_file_string() const;
786        const external_string_type external_directory_string() const;
787
788        string_type  root_name() const;
789        string_type  root_directory() const;
790        basic_path   root_path() const;
791        basic_path   relative_path() const;
792        string_type  leaf() const;
793        basic_path   branch_path() const;
794
795        bool empty() const;
796        bool is_complete() const;
797        bool has_root_name() const;
798        bool has_root_directory() const;
799        bool has_root_path() const;
800        bool has_relative_path() const;
801        bool has_leaf() const;
802        bool has_branch_path() const;
803
804        // <a href="#basic_path-iterators">iterators</a>
805        class iterator;
806        typedef iterator const_iterator;
807
808        iterator begin() const;
809        iterator end() const;
810
811      };
812
813    } // namespace sys
814  } // namespace tr2
815} // namespace std</pre>
816<p>A <code>basic_path</code> object stores a possibly empty <a href="#Path">path</a>.
817The internal form of the stored path is unspecified.</p>
818<p><a name="pathname-resolution">Functions</a> described in this clause which access files or their attributes do so by
819resolving a <code>basic_path</code> object into a particular file in a file
820hierarchy. The pathname, suitably converted to the string type, format, and
821encoding
822required by the operating system, is resolved as if by the <i>POSIX</i>
823<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_11">
824Pathname Resolution</a> mechanism. The encoding of the resulting pathname is determined by the <code>Traits::to_external</code> conversion function.</p>
825<blockquote>
826<p>[<i>Note:</i> There is no guarantee that the path stored in a&nbsp; <code>basic_path</code> 
827object is valid for a particular operating system or file system. <i>-- end note</i>]</p>
828</blockquote>
829<p>Some functions in this clause return <code>basic_path</code> objects for
830paths composed partly or wholly of pathnames obtained from the operating system.
831Such pathnames are suitably converted from the actual format and string
832type supplied by the operating system. The encoding of the resulting path is determined by the <code>Traits::to_internal</code> conversion function.</p>
833<p>For member functions described as returning &quot;<code>const string_type</code>&quot; or
834&quot;<code>const external_string_type</code>&quot;, implementations are permitted to return
835&quot;<code>const string_type&amp;</code>&quot; or&nbsp; &quot;<code>const external_string_type&amp;</code>&quot; 
836respectively.</p>
837<blockquote>
838<p>[<i>Note:</i> This allows implementations to avoid unnecessary copies.
839Return-by-value is specified as
840<code>const</code> to ensure programs won't break if moved to a return-by-reference
841implementation. <i>--
842end note</i>]</p>
843</blockquote>
844<h4><a name="Pathname-formats">Pathname formats</a></h4>
845<p>There are two formats for string or sequence arguments that describe a
846path:</p>
847<ul>
848  <li>The portable pathname format as described in <a href="#Pathname-grammar">
849  Pathname grammar</a> and by the <i>POSIX</i> <i><a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_169">Filename</a>,
850<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_266">
851Pathname</a> </i>and<i>
852<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_11">
853Pathname Resolution</a></i> definitions.<blockquote>
854<p>[<i>Note:</i> <span style="background-color: #FFFFFF">The <i>POSIX</i> format
855is the basis for the portable format because it is already an ISO standard, is
856the basis for the ubiquitous <i>URL</i> format, and is the native format or a
857subset of the native format for <i>UNIX</i>-like and <i>Windows</i>-like
858operating systems familiar to large numbers of programmers. </span></p>
859<p>Use of the portable format does not alone guarantee
860portability;  filenames must also be portable.<span style="background-color: #FFFFFF"> 
861See <a href="#Filename-conversion">Filename conversions</a>. Each operating system
862always follows its own rules. Use of the portable format
863does not change that. </span> <i>-- end note</i>]</p>
864  </blockquote>
865  </li>
866  <li>A native pathname format
867  as defined by the operating system.<blockquote>
868    <p>[<i>Note:</i> If an operating system supports only the <i>POSIX</i> 
869    pathname format, the portable format and the native format are the same. </p>
870    <p><span style="background-color: #FFFFFF">Identifying user-provided paths
871    as native format is a common need, and ensures maximum portability, even
872    though not strictly needed except on systems where the native format
873    is not implicitly recognized.</span></p>
874    <p><span style="background-color: #FFFFFF">Programs using hard-coding native
875    formats are likely to be non-portable.&nbsp; --</span><i><span style="background-color: #FFFFFF"> end note</span></i><span style="background-color: #FFFFFF">]</span></p>
876  </blockquote>
877  </li>
878</ul>
879<p><span style="background-color: #FFFFFF">All <code>basic_path</code> string or sequence arguments that describe a
880path shall accept the portable pathname format, and shall accept the native
881format if explicitly identified by a native format escape sequence prefix of
882<code>slash slash colon</code>.</span></p>
883<blockquote>
884    <p><span style="background-color: #FFFFFF">[<i>Note:</i> <code>slash
885    slash colon</code> was chosen as the escape sequence because a leading <code>
886    slash slash</code>&nbsp; is already implementation-defined by POSIX, <code>
887    colon</code> is prohibited in a Windows filename, and on any system a single
888    <code>slash</code> can be used when a filename beginning with a <code>colon</code> 
889    is desired.&nbsp;These factors eliminate the chance of collision with a real
890    filename. --</span><i><span style="background-color: #FFFFFF"> end note</span></i><span style="background-color: #FFFFFF">]</span></p>
891    </blockquote>
892<p><span style="background-color: #FFFFFF">Implementations are encouraged to
893implicitly recognize the native pathname format if it can be lexically
894identified. An implementation  </span>shall document whether or
895not the native pathname format is <span style="background-color: #FFFFFF">
896implicitly recognized</span>.</p>
897<blockquote>
898<p>[<i>Example:</i></p>
899<p><i>-- OpenVMS:</i> <code>&quot;SYS1::DISK1:[JANE.TYLER.HARRY]</code>&quot; is treated
900as a native pathname with a system name, drive name,&nbsp;and three directory
901filenames, rather than a portable pathname with one filename.</p>
902<p><i>-- Windows: </i><code>&quot;c:\\jane\\tyler\\harry&quot;</code> is treated as a
903native pathname with a drive letter, root-directory, and three filenames, rather
904than a portable pathname with one filename.</p>
905<p><i>-- Counter-example 1:</i> An operating system that allows slashes in
906filenames and uses dot as a directory separator. Distinguishing between portable
907and native format argument strings or sequences is not possible as there is no
908other distinguishing syntax. The implementation does not accept native format
909pathnames unless the <code>native</code> argument is present.</p>
910<p><i>-- Counter-example 2:</i> An operating system that allows slashes in
911filenames and uses some unusual character as a directory separator. The
912implementation does accept native format pathnames without the additional <code>
913native</code> argument, which only has to be used for native format arguments
914containing slashes in filenames.</p>
915<p><i>-- end example</i>]</p>
916<p>[<i>Note:</i> This <i><a name="duck-rule">duck-rule</a></i> (&quot;if it looks
917like a duck, walks like a duck, and quacks like a duck, it must be a duck&quot;)
918eliminates format confusion as a source of programmer error and support
919requests. <i>-- end note</i>]</p>
920</blockquote>
921<p>If both the portable and native formats are accepted, implementations shall
922document what characters or character sequences are used to distinguish between
923portable and native formats.</p>
924<blockquote>
925<p>[<i>Note:</i> <i>Windows</i> implementations are encouraged to define colons
926and backslashes as the characters which distinguish native from portable
927formats. <i>--end note</i>]</p>
928</blockquote>
929<h4><a name="Pathname-grammar">Pathname grammar</a></h4>
930<p>The grammar for the portable pathname format is as follows:</p>
931<blockquote>
932<p><i>pathname:<br>
933&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; root-name<sub>opt</sub> 
934root-directory<sub>opt</sub> relative-path<sub>opt</sub></i></p>
935<p><i>root-name:<br>
936&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
937implementation-defined</i></p>
938<p><i>root-directory:<br>
939&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; slash<br>
940&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
941root-directory slash<br>
942&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
943implementation-defined</i></p>
944<p><i>relative-path:<br>
945&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
946filename<br>
947&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; relative-path
948slash<br>
949&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; relative-path
950slash filename</i></p>
951<p><i>filename:<br>
952&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; name<br>
953&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; dot<br>
954&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; dot dot</i></p>
955<p><i>slash:<br>
956&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>
957slash&lt;Path&gt;::value</code></i></p>
958<p><i>dot:<br>
959&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>
960dot&lt;Path&gt;::value</code></i></p>
961</blockquote>
962<p>The grammar is aligned with the <i>POSIX </i>&nbsp;<i><a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_169">Filename</a>,
963<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_266">
964Pathname</a> </i>and<i>
965<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_11">
966Pathname Resolution</a></i> definitions. Any conflict between the grammar and <i>
967POSIX</i> is unintentional. This technical report defers to <i>POSIX</i>.</p>
968<blockquote>
969<p><span style="background-color: #E0E0E0"><i>The form of the above wording was taken
970from POSIX, which uses it in several places to defer to the C standard.</i></span></p>
971<p>[<i>Note: Windows</i> implementations are encouraged to define <i>slash slash
972name</i> as a permissible <i>root-name</i>. <i>POSIX</i> permits, but does not
973require, implementations to do the same. <i>Windows</i> implementations are
974encouraged to define an additional <i>root-directory</i> element <i>
975root_directory name.</i> It is applicable only to the <i>slash slash name</i> 
976form of <i>root-name.</i></p>
977<p> <i>Windows</i> implementations are encouraged to recognize a <i>name</i> 
978followed by a colon as a native format <i>root-name</i>,
979and a backslash as a format element equivalent to <i>slash</i>. <i>-- end note</i>]</p>
980</blockquote>
981<h4><a name="Filename-conversion">Filename conversion</a></h4>
982<p>When converting filenames to the native operating system format,
983implementations are encouraged, but not required, to convert otherwise invalid
984characters or character sequences to valid characters or character sequences.
985Such conversions are implementation-defined.</p>
986<blockquote>
987<p>[<i>Note:</i> Filename conversion allows much wider portability of both
988programs and filenames that would otherwise be possible.</p>
989<p>Implementations are encouraged to base conversion on existing standards or
990practice. Examples include the Uniform Resource Locator escape syntax of a percent sign (<code>'%'</code>)
991followed by two hex digits representing the character value. On
992<i>OpenVMS</i>, which does not allow percent signs in filenames, a dollar sign (<code>'$'</code>)
993followed by two hex digits is the existing practice, as is converting lowercase
994letters to uppercase.<i> -- end note.</i>]</p>
995<p><span style="background-color: #E0E0E0"><i>The Boost implementation for
996Windows currently does not map invalid characters. Pending feedback from the LWG,
997Boost may settle on % hex hex as the preferred escape sequence. If so, should
998there be normative encouragement?</i></span></p>
999</blockquote>
1000<h4><a name="basic_path-requirements">Requirements</a></h4>
1001<p>The argument for the template parameter named <code>String</code> shall be a
1002class that includes members with the same names, types, values, and semantics as
1003class template <code>basic_string</code>.</p>
1004<p>The argument for the template parameter named <code>Traits</code> shall be a
1005class that satisfies the requirements specified in the
1006<a href="#Path-Behavior-Traits-Requirements">Path Behavior Traits Requirements</a> 
1007table.</p>
1008<p>The argument for template parameters named <code>InputIterator</code> shall satisfy the
1009requirements of an input iterator (C++ Std, 24.1.1, Input iterators [lib.input.iterators]) and shall have a value type convertible to
1010<code>basic_path::value_type</code>. </p>
1011<p>Some function templates with a template
1012parameter named <code>InputIterator</code> also have non-template overloads. Implementations shall
1013only select the function template overload if the type named by <code>InputIterator</code> 
1014is not <code>path_format_t</code>.</p>
1015<blockquote>
1016<p>[<i>Note:</i> This &quot;do-the-right-thing&quot; rule ensures that the
1017overload expected by the user is selected. The implementation technique is unspecified -
1018implementations may use
1019<a href="http://www.boost.org/libs/utility/enable_if.html">enable_if</a> or
1020other techniques to achieve the effect. <i>-- end note</i>]</p>
1021</blockquote>
1022<h4> <a name="basic_path-constructors"> <code>basic_path</code> constructors</a></h4>
1023<pre>basic_path();</pre>
1024<blockquote>
1025  <p><i>Postconditions:</i> <code>empty()</code>.</p>
1026  </blockquote>
1027<pre>basic_path(const string_type&amp; s);
1028basic_path(const value_type * s);
1029template &lt;class InputIterator&gt;
1030  basic_path(InputIterator s, InputIterator last);</pre>
1031<blockquote>
1032  <p><i>Remarks:</i> The format of string <code>s</code> and sequence [<code>first</code>,<code>last</code>)
1033  is described in <a href="#Pathname-formats">Pathname formats</a>.</p>
1034  <p><i>Effects:</i> The path elements in string <code>s</code> or sequence [<code>first</code>,<code>last</code>)
1035  are stored.</p>
1036</blockquote>
1037<h4> <a name="basic_path-assignments"> <code>basic_path</code> assignments</a></h4>
1038<pre>basic_path&amp; operator=(const string_type&amp; s);
1039basic_path&amp; operator=(const value_type* s);
1040template &lt;class InputIterator&gt;
1041  basic_path&amp; assign(InputIterator first, InputIterator last);</pre>
1042<blockquote>
1043  <p><i>Remarks:</i> The format of string <code>s</code> and sequence [<code>first</code>,<code>last</code>)
1044  is described in <a href="#Pathname-formats">Pathname formats</a>.</p>
1045  <p><i>Effects:</i> The path elements in string <code>s</code> or sequence [<code>first</code>,<code>last</code>)
1046  are stored.</p>
1047  <p><i>Returns: </i><code>*this</code></p>
1048  </blockquote>
1049<h4> <a name="basic_path-modifiers"> <code>basic_path</code> modifiers</a></h4>
1050<pre>basic_path&amp; operator/=(const basic_path&amp; rhs);</pre>
1051<blockquote>
1052  <p><i>Effects:</i> The path stored in <code>rhs</code> is appended to the
1053  stored path.</p>
1054  <p><i>Returns:</i> <code>*this</code></p>
1055</blockquote>
1056<pre>basic_path&amp; operator/=(const string_type&amp; s);
1057basic_path&amp; operator/=(const value_type* s);
1058template &lt;class InputIterator&gt;
1059basic_path&amp; append(InputIterator first, InputIterator last);</pre>
1060<blockquote>
1061  <p><i>Remarks:</i> The format of string <code>s</code> and sequence [<code>first</code>,<code>last</code>)
1062  is described in <a href="#Pathname-formats">Pathname formats</a>.</p>
1063<p><i>Effects:</i> The path elements in string <code>s</code> or sequence [<code>first</code>,<code>last</code>)
1064  are appended to the stored path.</p>
1065  <p><i>Returns: </i><code>*this</code></p>
1066  </blockquote>
1067<pre><code><span style="background-color: #FFFFFF">void swap( basic_path &amp; rhs );</span></code></pre>
1068<blockquote>
1069  <p><i><span style="background-color: #FFFFFF">Effects:</span></i><span style="background-color: #FFFFFF"> 
1070  Swaps the contents of the two paths.</span></p>
1071  <p><i><span style="background-color: #FFFFFF">Throws: </span></i>
1072  <span style="background-color: #FFFFFF">nothing.</span></p>
1073  <p><i><span style="background-color: #FFFFFF">Postcondition:</span></i><span style="background-color: #FFFFFF">
1074  </span><code><span style="background-color: #FFFFFF">this-&gt;string()</span></code><span style="background-color: #FFFFFF"> 
1075  contains the same sequence of characters that were in </span><code>
1076  <span style="background-color: #FFFFFF">rhs</span></code><span style="background-color: #FFFFFF">,
1077  </span><code><span style="background-color: #FFFFFF">rhs</span></code><span style="background-color: #FFFFFF"> 
1078  contains the same sequence of characters that were is </span><code>
1079  <span style="background-color: #FFFFFF">this-&gt;string()</span></code><span style="background-color: #FFFFFF">.</span></p>
1080  <p><i><span style="background-color: #FFFFFF">Complexity: </span></i>
1081  <span style="background-color: #FFFFFF">constant time.</span></p>
1082</blockquote>
1083<pre>basic_path&amp; remove_leaf();</pre>
1084<blockquote>
1085  <p><i>Effects:</i> If <code>has_branch_path()</code> then remove the last <i>filename</i> from the stored path. If that leaves
1086  the stored path with one or more trailing <i>slash</i> elements not
1087  representing&nbsp; <i>root-directory</i>, remove them.</p>
1088  <p><i>Returns:</i> <code>*this</code></p>
1089  <p>[<i>Note:</i> This function is needed to efficiently implement <code>
1090  basic_directory_iterator</code>. It is made public to allow additional uses. <i>-- end
1091  note</i>]</p>
1092</blockquote>
1093<h4> <a name="basic_path-observers"> <code>basic_path</code> observers</a></h4>
1094<blockquote>
1095<p><span style="background-color: #E0E0E0"><i>See the
1096<a href="#Path-decomposition-table">Path decomposition table</a> for examples
1097for values returned by decomposition functions.</i></span></p>
1098</blockquote>
1099<pre>const string_type string() const;</pre>
1100<blockquote>
1101<p><i>Returns:</i> The  stored path, formatted according to the
1102<a href="#Pathname-grammar">Pathname grammar</a> rules.</p>
1103</blockquote>
1104<pre>const string_type file_string() const;</pre>
1105<blockquote>
1106<p><i>Returns:</i> The  stored path, formatted according to the
1107operating system rules for regular file pathnames, with any
1108<a href="#Filename-conversion">Filename conversion</a> applied.</p>
1109<p>[<i>Note:</i> For some operating systems, including <i>POSIX</i> and <i>
1110Windows</i>, the native format for regular file pathnames and directory
1111pathnames is the same, so <code>file_string()</code> and <code>directory_string()</code> 
1112return the same string. On OpenMVS, however, the expression <code>path(&quot;/cats/jane&quot;).file_string()</code> 
1113would return the string <code>&quot;[CATS]JANE&quot;</code> while <code>path(&quot;/cats/jane&quot;).directory_string()</code> 
1114would return the string <code>&quot;[CATS.JANE]&quot;</code>. <i>-- end note</i>]</p>
1115</blockquote>
1116<pre>const string_type directory_string() const;</pre>
1117<blockquote>
1118<p><i>Returns:</i> The  stored path, formatted according to the
1119operating system rules for directory pathnames, with any
1120<a href="#Filename-conversion">Filename conversion</a> applied.</p>
1121</blockquote>
1122<pre>const external_string_type external_file_string() const;</pre>
1123<blockquote>
1124<p><i>Returns:</i> The  stored path, formatted according to the
1125operating system rules for regular file pathnames, with any
1126<a href="#Filename-conversion">Filename conversion</a> applied, and encoded by the <code>Traits::to_external</code> 
1127conversion function.</p>
1128</blockquote>
1129<pre>const external_string_type external_directory_string() const;</pre>
1130<blockquote>
1131<p><i>Returns:</i> The  stored path, formatted according to the
1132operating system rules for directory pathnames, with any
1133<a href="#Filename-conversion">Filename conversion</a> applied, and encoded by the <code>Traits::to_external</code> 
1134conversion function.</p>
1135</blockquote>
1136<pre>string_type root_name() const;</pre>
1137<blockquote>
1138<p><i>Returns:</i> <i>root-name,</i> if the stored path includes <i>
1139root-name</i>, otherwise <code>string_type()</code>. </p>
1140</blockquote>
1141<pre>string_type root_directory() const;</pre>
1142<blockquote>
1143<p><i>Returns:</i> <i>root-directory</i>, if the stored path includes <i>
1144root-directory</i>, otherwise <code>string_type()</code>.</p>
1145<p>If <i>root-directory</i> is composed <i>slash name</i>, <i>slash</i> is
1146excluded from the returned string.</p>
1147</blockquote>
1148<pre>basic_path root_path() const;</pre>
1149<blockquote>
1150  <p><i>Returns:</i> <code>root_name() / root_directory()</code></p>
1151</blockquote>
1152<pre>basic_path relative_path() const;</pre>
1153<blockquote>
1154<p><i>Returns:</i> A <code>basic_path</code> composed from the the stored path, if any, beginning
1155with the first <i>filename</i> after <i>root-path</i>.
1156Otherwise, an empty <code>basic_path</code>.</p>
1157</blockquote>
1158<pre>string_type leaf() const;</pre>
1159<blockquote>
1160  <p><i>Returns:</i> <code>empty() ? string_type() : *--end()</code></p>
1161</blockquote>
1162<pre>basic_path branch_path() const;</pre>
1163<blockquote>
1164  <p><i>Returns:</i> <code>(string().empty() || begin() == --end()) ? path_type(&quot;&quot;) :
1165  <i>br</i></code>, where <code><i>br</i></code> is constructed as if by
1166  starting with an empty <code>basic_path</code> and successively applying <code>
1167  operator/=</code> for each element in the range <code>begin()</code>, <code>
1168  --end()</code>.</p>
1169</blockquote>
1170<pre>bool empty() const;</pre>
1171<blockquote>
1172  <p><i>Returns:</i> <code>string().empty()</code>.</p>
1173</blockquote>
1174<pre>bool is_complete() const;</pre>
1175<blockquote>
1176  <p><span style="background-color: #FFFFFF"><i>Returns:</i> <code>true</code>,
1177  if the elements of root_path() uniquely identify a directory, else <code>false</code>.</span></p>
1178</blockquote>
1179<pre>bool has_root_path() const;</pre>
1180<blockquote>
1181  <p><i>Returns:</i> <code>!root_path().empty()</code></p>
1182</blockquote>
1183<pre>bool has_root_name() const;</pre>
1184<blockquote>
1185  <p><i>Returns:</i> <code>!root_name().empty()</code></p>
1186</blockquote>
1187<pre>bool has_root_directory() const;</pre>
1188<blockquote>
1189  <p><i>Returns:</i> <code>!root_directory().empty()</code></p>
1190</blockquote>
1191<pre>bool has_relative_path() const;</pre>
1192<blockquote>
1193  <p><i>Returns:</i> <code>!relative_path().empty()</code></p>
1194</blockquote>
1195<pre>bool has_leaf() const;</pre>
1196<blockquote>
1197  <p><i>Returns:</i> <code>!leaf().empty()</code></p>
1198</blockquote>
1199<pre>bool has_branch_path() const;</pre>
1200<blockquote>
1201  <p><i>Returns:</i> <code>!branch_path().empty()</code></p>
1202</blockquote>
1203<h4> <a name="basic_path-iterators"> <code>basic_path</code> iterators</a></h4>
1204<p> A <code>basic_path::iterator</code> is a constant iterator satisfying all
1205the requirements of a bidirectional iterator (C++ Std, 24.1.4 Bidirectional
1206iterators [lib.bidirectional.iterators]). Its <code>value_type</code> is
1207<code>string_type</code>.</p>
1208  <p>Calling any non-const member function of a <code>basic_path</code> object
1209  invalidates all iterators referring to elements of the object.</p>
1210<p> The forward traversal order is as follows:</p>
1211<ul>
1212  <li>The <i>root-name</i> element, if present.</li>
1213  <li>The <i>root-directory</i> element, if present.</li>
1214  <li>Each successive <i>filename</i> element, if present.</li>
1215  <li><i>Dot</i>, if one or more trailing non-root <i>slash</i> 
1216  characters are present.</li>
1217</ul>
1218  <p>The backward traversal order is the reverse of forward traversal.</p>
1219  <pre>iterator begin() const;</pre>
1220<blockquote>
1221  <p><i>Returns:</i> An iterator for the first present element in the traversal
1222  list above. If no elements are present, the end iterator.</p>
1223</blockquote>
1224<pre>iterator end() const;</pre>
1225<blockquote>
1226  <p><i>Returns:</i> The end iterator.</p>
1227</blockquote>
1228<h4> <a name="basic_path-non-member-functions">
1229<span style="background-color: #FFFFFF">basic_path non-member functions</span></a></h4>
1230<pre><span style="background-color: #FFFFFF">template&lt;class String, class Traits&gt;
1231void swap( basic_path&lt;String, Traits&gt; &amp; lhs, basic_path&lt;String, Traits&gt; &amp; rhs )</span></pre>
1232<blockquote>
1233  <p><i><span style="background-color: #FFFFFF">Effects: </span></i><code>
1234  <span style="background-color: #FFFFFF">lhs.swap(
1235  rhs )</span></code></p>
1236</blockquote>
1237  <h4><span style="background-color: #FFFFFF">basic_path non-member operators</span></h4>
1238  <p><span style="background-color: #FFFFFF">There are seven basic_path non-member operators (/,
1239  </span> <code><span style="background-color: #FFFFFF">==</span></code><span style="background-color: #FFFFFF">,
1240  </span> <code>
1241  <span style="background-color: #FFFFFF">!=</span></code><span style="background-color: #FFFFFF">,
1242  </span> <code><span style="background-color: #FFFFFF">&lt;</span></code><span style="background-color: #FFFFFF">,
1243  </span> <code><span style="background-color: #FFFFFF">&gt;</span></code><span style="background-color: #FFFFFF">,
1244  </span> <code><span style="background-color: #FFFFFF">&lt;=</span></code><span style="background-color: #FFFFFF">,
1245  </span> <code><span style="background-color: #FFFFFF">&gt;=</span></code><span style="background-color: #FFFFFF">),
1246  each with five overloads. For brevity, the specifications are given in tabular
1247  form. Each of the resulting thirty-five signatures is a template, with
1248  template parameter list template</span><code><span style="background-color: #FFFFFF">&lt;class
1249  String, class Traits&gt;</span></code><span style="background-color: #FFFFFF">.
1250  The format of such arguments is described in </span> <a href="#Pathname-formats">
1251  <span style="background-color: #FFFFFF">Pathname formats</span></a><span style="background-color: #FFFFFF">.</span></p>
1252    <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
1253      <tr>
1254        <td width="100%">
1255        <p align="center"><i><b><span style="background-color: #FFFFFF">Argument type overloads</span></b></i></td>
1256      </tr>
1257      <tr>
1258        <td width="100%"><span style="background-color: #FFFFFF"><code>
1259        basic_path&lt;String, Traits&gt;&amp; a, basic_path&lt;String, Traits&gt;&amp; 
1260        b</code></span></td>
1261      </tr>
1262      <tr>
1263        <td width="100%"><span style="background-color: #FFFFFF"><code>const
1264        typename basic_path&lt;String, Traits&gt;::string_type&amp; a,
1265        basic_path&lt;String, Traits&gt;&amp; b</code></span></td>
1266      </tr>
1267      <tr>
1268        <td width="100%"><span style="background-color: #FFFFFF"><code>const
1269        typename basic_path&lt;String, Traits&gt;::string_type::value_type* a,
1270        basic_path&lt;String, Traits&gt;&amp; b</code></span></td>
1271      </tr>
1272      <tr>
1273        <td width="100%"><span style="background-color: #FFFFFF"><code>const
1274        basic_path&lt;String, Traits&gt;&amp; a, typename basic_path&lt;String, Traits&gt;::string_type&amp; 
1275        b</code></span></td>
1276      </tr>
1277      <tr>
1278        <td width="100%"><span style="background-color: #FFFFFF"><code>const
1279        basic_path&lt;String, Traits&gt;&amp; a, typename
1280        basic_path&lt;String, Traits&gt;::string_type::value_type* b</code></span></td>
1281      </tr>
1282    </table>
1283  <p><span style="background-color: #FFFFFF">In the </span><b><i>
1284  <span style="background-color: #FFFFFF">basic_path non-member operators </span>
1285  </i></b><span style="background-color: #FFFFFF">table, </span><code>
1286  <span style="background-color: #FFFFFF">a</span></code><span style="background-color: #FFFFFF"> 
1287  and </span><code><span style="background-color: #FFFFFF">b</span></code><span style="background-color: #FFFFFF"> 
1288  are of the types given in the </span><i><b>
1289  <span style="background-color: #FFFFFF">Argument type overloads</span></b></i><span style="background-color: #FFFFFF"> 
1290  table. If </span><code><span style="background-color: #FFFFFF">a</span></code><span style="background-color: #FFFFFF"> 
1291  or </span><code><span style="background-color: #FFFFFF">b</span></code><span style="background-color: #FFFFFF"> 
1292  is of type </span><code><span style="background-color: #FFFFFF">const
1293  basic_path&lt;String, Traits&gt;&amp;</span></code><span style="background-color: #FFFFFF">,
1294  then </span><i><b><span style="background-color: #FFFFFF">a</span></b></i><code><i><b><span style="background-color: #FFFFFF">'</span></b></i></code><span style="background-color: #FFFFFF"> 
1295  or </span><i><b><span style="background-color: #FFFFFF">b'</span></b></i><span style="background-color: #FFFFFF"> 
1296  respectively is </span><code><span style="background-color: #FFFFFF">a</span></code><span style="background-color: #FFFFFF"> 
1297  or </span><code><span style="background-color: #FFFFFF">b</span></code><span style="background-color: #FFFFFF"> 
1298  respectively. Otherwise </span><i><b><span style="background-color: #FFFFFF">a</span></b></i><code><i><b><span style="background-color: #FFFFFF">'</span></b></i></code><span style="background-color: #FFFFFF"> 
1299  or </span><i><b><span style="background-color: #FFFFFF">b'</span></b></i><span style="background-color: #FFFFFF"> 
1300  respectively represent named or unnamed temporary </span><code>
1301  <span style="background-color: #FFFFFF">basic_path&lt;String, Traits&gt;</span></code><span style="background-color: #FFFFFF"> 
1302  objects constructed from </span><code><span style="background-color: #FFFFFF">
1303  a</span></code><span style="background-color: #FFFFFF"> or </span><code>
1304  <span style="background-color: #FFFFFF">b</span></code><span style="background-color: #FFFFFF"> 
1305  respectively.</span></p>
1306<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%" height="280">
1307  <tr>
1308    <td width="100%" colspan="3" align="center" height="19"><b><i>
1309    <span style="background-color: #FFFFFF">basic_path non-member operators</span></i></b></td>
1310  </tr>
1311  <tr>
1312    <td width="20%" align="center" height="19"><i><b>
1313    <span style="background-color: #FFFFFF">Expression</span></b></i></td>
1314    <td width="25%" align="center" height="19"><i><b>
1315    <span style="background-color: #FFFFFF">Return type</span></b></i></td>
1316    <td width="55%" align="center" height="19"><i><b>
1317    <span style="background-color: #FFFFFF">Semantics</span></b></i></td>
1318  </tr>
1319  <tr>
1320    <td width="20%" align="center" height="30" valign="top"><code>
1321    <span style="background-color: #FFFFFF">a / b</span></code></td>
1322    <td width="25%" align="center" height="30" valign="top"><code>
1323    <span style="background-color: #FFFFFF">basic_path&lt;String, Traits&gt;</span></code></td>
1324    <td width="55%" height="30"><code><span style="background-color: #FFFFFF">
1325    basic_path&lt;String, Traits&gt; tmp(a);<br>
1326    return a /= </span></code><i><b><span style="background-color: #FFFFFF">b'</span></b></i><code><span style="background-color: #FFFFFF">;</span></code></td>
1327  </tr>
1328  <tr>
1329    <td width="20%" align="center" height="19" valign="top"><code>
1330    <span style="background-color: #FFFFFF">a &lt; b</span></code></td>
1331    <td width="25%" align="center" height="19" valign="top"><code>
1332    <span style="background-color: #FFFFFF">bool</span></code></td>
1333    <td width="55%" height="19"><code><span style="background-color: #FFFFFF">
1334    return lexicographical_compare(</span></code><span style="background-color: #FFFFFF"><i><b>a</b></i></span><code><span style="background-color: #FFFFFF"><i><b>'</b></i>.begin(), </span></code><i><b>
1335    <span style="background-color: #FFFFFF">a</span></b></i><code><span style="background-color: #FFFFFF"><i><b>'</b></i>.end(), </span></code><i><b>
1336    <span style="background-color: #FFFFFF">b'</span></b></i><code><span style="background-color: #FFFFFF">.begin(), </span></code><i><b>
1337    <span style="background-color: #FFFFFF">b'</span></b></i><code><span style="background-color: #FFFFFF">.end());</span></code></td>
1338  </tr>
1339  <tr>
1340    <td width="20%" align="center" height="19" valign="top"><code>
1341    <span style="background-color: #FFFFFF">a == b</span></code></td>
1342    <td width="25%" align="center" height="19" valign="top"><code>
1343    <span style="background-color: #FFFFFF">bool</span></code></td>
1344    <td width="55%" height="19"><code><span style="background-color: #FFFFFF">
1345    return !(</span></code><i><b><span style="background-color: #FFFFFF">a</span></b></i><code><i><b><span style="background-color: #FFFFFF">'</span></b></i><span style="background-color: #FFFFFF"> 
1346    &lt; </span></code><i><b><span style="background-color: #FFFFFF">b'</span></b></i><code><span style="background-color: #FFFFFF">)
1347    &amp;&amp; !(</span></code><i><b><span style="background-color: #FFFFFF">b'</span></b></i><code><span style="background-color: #FFFFFF"> 
1348    &lt; </span></code><i><b><span style="background-color: #FFFFFF">a</span></b></i><code><i><b><span style="background-color: #FFFFFF">'</span></b></i><span style="background-color: #FFFFFF">);</span></code></td>
1349  </tr>
1350  <tr>
1351    <td width="20%" align="center" height="19" valign="top"><code>
1352    <span style="background-color: #FFFFFF">a != b</span></code></td>
1353    <td width="25%" align="center" height="19" valign="top"><code>
1354    <span style="background-color: #FFFFFF">bool</span></code></td>
1355    <td width="55%" height="19"><code><span style="background-color: #FFFFFF">
1356    return !(</span></code><i><b><span style="background-color: #FFFFFF">a</span></b></i><code><i><b><span style="background-color: #FFFFFF">'</span></b></i><span style="background-color: #FFFFFF"> 
1357    == </span></code><i><b><span style="background-color: #FFFFFF">b'</span></b></i><code><span style="background-color: #FFFFFF">);</span></code></td>
1358  </tr>
1359  <tr>
1360    <td width="20%" align="center" height="19" valign="top"><code>
1361    <span style="background-color: #FFFFFF">a &gt; b</span></code></td>
1362    <td width="25%" align="center" height="19" valign="top"><code>
1363    <span style="background-color: #FFFFFF">bool</span></code></td>
1364    <td width="55%" height="19"><code><span style="background-color: #FFFFFF">
1365    return </span></code><i><b><span style="background-color: #FFFFFF">b'</span></b></i><code><span style="background-color: #FFFFFF"> 
1366    &lt; </span></code><i><b><span style="background-color: #FFFFFF">a</span></b></i><code><i><b><span style="background-color: #FFFFFF">'</span></b></i><span style="background-color: #FFFFFF">;</span></code></td>
1367  </tr>
1368  <tr>
1369    <td width="20%" align="center" height="19" valign="top"><code>
1370    <span style="background-color: #FFFFFF">a &lt;= b</span></code></td>
1371    <td width="25%" align="center" height="19" valign="top"><code>
1372    <span style="background-color: #FFFFFF">bool</span></code></td>
1373    <td width="55%" height="19"><code><span style="background-color: #FFFFFF">
1374    return !(</span></code><i><b><span style="background-color: #FFFFFF">b'</span></b></i><code><span style="background-color: #FFFFFF"> 
1375    &lt; </span></code><i><b><span style="background-color: #FFFFFF">a</span></b></i><code><i><b><span style="background-color: #FFFFFF">'</span></b></i><span style="background-color: #FFFFFF">);</span></code></td>
1376  </tr>
1377  <tr>
1378    <td width="20%" align="center" height="19" valign="top"><code>
1379    <span style="background-color: #FFFFFF">a &gt;= b</span></code></td>
1380    <td width="25%" align="center" height="19" valign="top"><code>
1381    <span style="background-color: #FFFFFF">bool</span></code></td>
1382    <td width="55%" height="19"><code><span style="background-color: #FFFFFF">
1383    return !(</span></code><i><b><span style="background-color: #FFFFFF">a</span></b></i><code><i><b><span style="background-color: #FFFFFF">'</span></b></i><span style="background-color: #FFFFFF"> 
1384    &lt; </span></code><i><b><span style="background-color: #FFFFFF">b'</span></b></i><code><span style="background-color: #FFFFFF">);</span></code></td>
1385  </tr>
1386</table>
1387  <blockquote>
1388  <p><span style="background-color: #FFFFFF">[</span><i><span style="background-color: #FFFFFF">Note:</span></i><span style="background-color: #FFFFFF">
1389  </span> <a name="Path-equality"><span style="background-color: #FFFFFF">Path equality</span></a><span style="background-color: #FFFFFF"> and path
1390  equivalence have different semantics.</span></p>
1391  <p><span style="background-color: #FFFFFF">Equality is determined by </span> <i>
1392  <span style="background-color: #FFFFFF">basic_path</span></i><span style="background-color: #FFFFFF">'s
1393  non-member </span> <code><a href="#operator-eq">
1394  <span style="background-color: #FFFFFF">operator==</span></a></code><span style="background-color: #FFFFFF">, which considers the two path's lexical representations
1395  only. Paths &quot;abc&quot; and &quot;ABC&quot; are never equal.</span></p>
1396  <p><span style="background-color: #FFFFFF">Equivalence is determined by the
1397  </span> <a href="#equivalent"><span style="background-color: #FFFFFF">equivalent()</span></a><span style="background-color: #FFFFFF"> 
1398  non-member function, which determines if two paths </span>
1399  <a href="#pathname-resolution"><span style="background-color: #FFFFFF">resolve</span></a><span style="background-color: #FFFFFF"> to the same file system entity.
1400  Paths &quot;abc&quot; 
1401  and &quot;ABC&quot; may or may not resolve to the same file, depending on the file
1402  system.</span></p>
1403  <p><span style="background-color: #FFFFFF">Programmers wishing to determine if two paths are &quot;the same&quot; must decide if
1404  &quot;the same&quot; means &quot;the same representation&quot; or &quot;resolve to the same actual
1405  file&quot;, and choose the appropriate function accordingly. </span> <i>
1406  <span style="background-color: #FFFFFF">-- end note</span></i><span style="background-color: #FFFFFF">]</span></p>
1407</blockquote>
1408  <h4><a name="basic_path-inserter-extractor"> <code>
1409  <span style="background-color: #FFFFFF">basic_path</span></code><span style="background-color: #FFFFFF"> inserter
1410  and extractor</span></a></h4>
1411<pre><span style="background-color: #FFFFFF">template&lt;class Path&gt;
1412  basic_istream&lt;typename Path::string_type::value_type, typename Path::string_type::traits_type&gt;&amp;
1413    operator&gt;&gt;(basic_istream&lt; typename Path::string_type::value_type, typename Path::string_type::traits_type&gt;&amp; is,
1414               Path&amp; ph );</span></pre>
1415<blockquote>
1416  <p><i><span style="background-color: #FFFFFF">Effects:&nbsp; </span></i>
1417      <code><span style="background-color: #FFFFFF">typename Path::string_type str;<br>
1418      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1419      is &gt;&gt; str;<br>
1420      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1421      ph = str;</span></code></p>
1422  <p><i><span style="background-color: #FFFFFF">Returns:</span></i><span style="background-color: #FFFFFF">
1423  </span> <code><span style="background-color: #FFFFFF">is</span></code></p>
1424</blockquote>
1425<pre><span style="background-color: #FFFFFF">template&lt;class Path&gt;
1426  basic_ostream&lt;typename Path::string_type::value_type, typename Path::string_type::traits_type&gt;&amp;
1427    operator&lt;&lt;(basic_ostream&lt; typename Path::string_type::value_type, typename Path::string_type::traits_type&gt;&amp; os,
1428               const Path&amp; ph );</span></pre>
1429<blockquote>
1430  <p><i><span style="background-color: #FFFFFF">Effects:</span></i><span style="background-color: #FFFFFF">&nbsp;
1431  </span> <code><span style="background-color: #FFFFFF">os &lt;&lt; ph.string()</span></code></p>
1432  <p><i><span style="background-color: #FFFFFF">Returns:</span></i><span style="background-color: #FFFFFF">
1433  </span> <code><span style="background-color: #FFFFFF">os</span></code></p>
1434</blockquote>
1435<h3><u><a name="Class-filesystem_error"><span style="background-color: #FFFFFF">
1436Class </span><code><span style="background-color: #FFFFFF">filesystem_error</span></code></a></u></h3>
1437<pre><span style="background-color: #FFFFFF">namespace std
1438{
1439  namespace tr2
1440  {
1441    namespace sys
1442    {
1443      class filesystem_error : public std::runtime_error
1444      {
1445      public:
1446        explicit filesystem_error(const std::string &amp; what_arg, system_error_type ec=0);
1447        system_error_type system_error() const;
1448      };
1449    } // namespace sys
1450  } // namespace tr2
1451} // namespace std</span></pre>
1452<p><span style="background-color: #FFFFFF">The class <code>filesystem_error</code> defines the
1453base type of
1454objects thrown as exceptions to report file system errors from functions described in this
1455clause.</span></p>
1456<blockquote>
1457  <p><span style="background-color: #FFFFFF">[</span><i><span style="background-color: #FFFFFF">Note:</span></i><span style="background-color: #FFFFFF"> 
1458  A non-template base class allows users who are uninterested in path specifics
1459  to catch a single exception type. </span> <i>
1460  <span style="background-color: #FFFFFF">-- end note</span></i><span style="background-color: #FFFFFF">]</span></p>
1461</blockquote>
1462<pre><span style="background-color: #FFFFFF">explicit filesystem_error(const std::string &amp; what_arg, system_error_type ec=0);</span></pre>
1463<blockquote>
1464  <p><span style="background-color: #FFFFFF"><i>Postcondition:</i> <code>
1465  strcmp(what(), <i>what_arg</i>.c_str()) == 0 &amp;&amp; system_error() == <i>ec</i></code></span></p>
1466</blockquote>
1467<pre><span style="background-color: #FFFFFF">system_error_type system_error() const;</span></pre>
1468<blockquote>
1469  <p><span style="background-color: #FFFFFF"><i>Returns: <code>ec</code></i></span></p>
1470</blockquote>
1471<h3><a name="Class-template-basic_filesystem_error">Class template <code>basic_filesystem_error</code></a></h3>
1472<pre>namespace std
1473{
1474  namespace tr2
1475  {
1476    namespace sys
1477    {
1478      template &lt;class Path&gt; class basic_filesystem_error : public <u><span style="background-color: #FFFFFF">filesystem</span>_error</u>
1479      {
1480      public:
1481        typedef Path path_type;
1482
1483        explicit basic_filesystem_error(const std::string&amp; <u><span style="background-color: #FFFFFF">what_arg</span></u>, system_error_type ec=0);
1484        basic_filesystem_error(const std::string&amp; <u><span style="background-color: #FFFFFF">what_arg</span></u>, const path_type&amp; p1, system_error_type ec);
1485        basic_filesystem_error(const std::string&amp; <u><span style="background-color: #FFFFFF">what_arg</span></u>, const path_type&amp; p1, const path_type&amp; p2, system_error_type ec);
1486
1487        const path_type&amp; path1() const;
1488        const path_type&amp; path2() const;
1489      };
1490
1491    } // namespace sys
1492  } // namespace tr2
1493} // namespace std</pre>
1494<p>The class template <code>basic_filesystem_error</code> defines the type of
1495objects thrown as exceptions to report file system errors from functions described in this
1496clause.</p>
1497<h4> <a name="basic_filesystem_error-constructors"> <code>basic_filesystem_error</code> constructors</a></h4>
1498<pre>explicit basic_filesystem_error(const std::string&amp; <u><span style="background-color: #FFFFFF">what_arg</span></u>, system_error_type ec=0);</pre>
1499<blockquote>
1500  <p><i>Postconditions:</i></p>
1501  <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="41%">
1502    <tr>
1503      <td width="18%"><b>Expression</b></td>
1504      <td width="82%"><b>Value</b></td>
1505    </tr>
1506    <tr>
1507      <td width="18%" bgcolor="#FFFFFF"><code>
1508      <span style="background-color: #FFFFFF">what</span>()</code></td>
1509      <td width="82%" bgcolor="#FFFFFF"><span style="background-color: #FFFFFF">
1510      <code><i>what_arg</i>.c_str()</code></span></td>
1511    </tr>
1512    <tr>
1513      <td width="18%"><code>system_error()</code></td>
1514      <td width="82%"><code>ec</code></td>
1515    </tr>
1516    <tr>
1517      <td width="18%"><code>path1().empty()</code></td>
1518      <td width="82%"><code>true</code></td>
1519    </tr>
1520    <tr>
1521      <td width="18%"><code>path2().empty()</code></td>
1522      <td width="82%"><code>true</code></td>
1523    </tr>
1524  </table>
1525</blockquote>
1526<pre>basic_filesystem_error(const std::string&amp; <span style="background-color: #FFFFFF">what_arg</span>, const path_type&amp; p1, system_error_type ec);</pre>
1527<blockquote>
1528  <p><i>Postconditions:</i></p>
1529  <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="41%">
1530    <tr>
1531      <td width="18%"><b>Expression</b></td>
1532      <td width="82%"><b>Value</b></td>
1533    </tr>
1534    <tr>
1535      <td width="18%"><code><span style="background-color: #FFFFFF">what</span>()</code></td>
1536      <td width="82%"><span style="background-color: #FFFFFF">
1537      <code><i>what_arg</i>.c_str()</code></span></td>
1538    </tr>
1539    <tr>
1540      <td width="18%"><code>system_error()</code></td>
1541      <td width="82%"><code>ec</code></td>
1542    </tr>
1543    <tr>
1544      <td width="18%"><code>path1()</code></td>
1545      <td width="82%"><span style="background-color: #FFFFFF">Reference to stored copy of
1546      </span> <code>p1</code></td>
1547    </tr>
1548    <tr>
1549      <td width="18%"><code>path2().empty()</code></td>
1550      <td width="82%"><code>true</code></td>
1551    </tr>
1552  </table>
1553</blockquote>
1554<pre>basic_filesystem_error(const std::string&amp; <span style="background-color: #FFFFFF">what_arg</span>, const path_type&amp; p1, const path_type&amp; p2, system_error_type ec);</pre>
1555<blockquote>
1556  <p><i>Postconditions:</i></p>
1557  <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="41%">
1558    <tr>
1559      <td width="18%"><b>Expression</b></td>
1560      <td width="82%"><b>Value</b></td>
1561    </tr>
1562    <tr>
1563      <td width="18%"><code><span style="background-color: #FFFFFF">what</span>()</code></td>
1564      <td width="82%"><span style="background-color: #FFFFFF">
1565      <u>
1566      <code><i>w</i></code></u><code><i>hat_arg</i>.c_str()</code></span></td>
1567    </tr>
1568    <tr>
1569      <td width="18%"><code>system_error()</code></td>
1570      <td width="82%"><code>ec</code></td>
1571    </tr>
1572    <tr>
1573      <td width="18%"><code>path1()</code></td>
1574      <td width="82%"><span style="background-color: #FFFFFF">Reference to stored copy of
1575      </span> <code>p1</code></td>
1576    </tr>
1577    <tr>
1578      <td width="18%"><code>path2()</code></td>
1579      <td width="82%"><span style="background-color: #FFFFFF">Reference to stored copy of
1580      </span> <code>p2</code></td>
1581    </tr>
1582  </table>
1583</blockquote>
1584<h4> <a name="basic_filesystem_error-observers"> <code>basic_filesystem_error</code> observers</a></h4>
1585<pre>const path_type&amp; path1() const;</pre>
1586<blockquote>
1587  <p><i>Returns:</i> Reference to copy of <code>p1</code> stored by the
1588  constructor, or, if none, an empty path.</p>
1589</blockquote>
1590<pre>const path_type&amp; path2() const;</pre>
1591<blockquote>
1592  <p><i>Returns:</i> Reference to copy of <code>p2</code> stored by the
1593  constructor, or, if none, an empty path.</p>
1594</blockquote>
1595<h3><a name="Class-template-basic_directory_entry">Class template <code>basic_directory_entry</code></a></h3>
1596<pre>namespace std
1597{
1598  namespace tr2
1599  {
1600    namespace sys
1601    {
1602      template &lt;class Path&gt; class basic_directory_entry
1603      {
1604      public:
1605        typedef Path path_type;
1606        typedef typename Path::string_type string_type;
1607
1608        // <a href="#basic_directory_entry-constructors">constructors</a>
1609        basic_directory_entry();
1610        explicit basic_directory_entry(const path_type&amp; p,
1611          <span style="background-color: #FFFFFF">file_status</span> st=file_status(), <span style="background-color: #FFFFFF">file_status</span> symlink_st=file_status());
1612
1613        // <a href="#basic_directory_entry-modifiers">modifiers</a>
1614        void assign(const path_type&amp; p, <span style="background-color: #FFFFFF">file_status</span> st=file_status(), <span style="background-color: #FFFFFF">file_status</span> symlink_st=file_status());
1615        void replace_leaf(const string_type&amp; s, <span style="background-color: #FFFFFF">file_status</span> st=file_status(), <span style="background-color: #FFFFFF">file_status</span> symlink_st=file_status());
1616
1617        // <a href="#basic_directory_entry-observers">observers</a>
1618        const Path&amp; path() const;
1619        operator const Path&amp;() const;
1620<span style="background-color: #FFFFFF">
1621        file_status  status() const;
1622        file_status  status(system_error_code&amp; ec) const;
1623        file_status  symlink_status() const;
1624        file_status  symlink_status(system_error_code&amp; ec) const;
1625</span><span style="background-color: #FFFF00">
1626</span>        // <a href="#basic_directory_entry-comparisons">comparisons</a>
1627        bool operator&lt;(const basic_directory_entry&lt;Path&gt;&amp; rhs);
1628        bool operator==(const basic_directory_entry&lt;Path&gt;&amp; rhs);
1629        bool operator!=(const basic_directory_entry&lt;Path&gt;&amp; rhs);
1630        bool operator&gt;(const basic_directory_entry&lt;Path&gt;&amp; rhs);
1631        bool operator&lt;=(const basic_directory_entry&lt;Path&gt;&amp; rhs);
1632        bool operator&gt;=(const basic_directory_entry&lt;Path&gt;&amp; rhs);
1633
1634      private:
1635        path_type            m_path;           // for exposition only
1636        mutable <span style="background-color: #FFFFFF">file_status</span>  m_status;         // for exposition only; stat()-like
1637        mutable <span style="background-color: #FFFFFF">file_status</span>  m_symlink_status; // for exposition only; lstat()-like
1638      };
1639
1640    } // namespace sys
1641  } // namespace tr2
1642} // namespace std</pre>
1643<p>A <code>basic_directory_entry</code> object stores a <code>basic_path object</code>,
1644a <code>file_status</code> object for non-symbolic link status, and a <code>
1645file_status</code> object for symbolic link status. The <code>file_status</code> 
1646objects act as value caches.</p>
1647<blockquote>
1648<p>[<i>Note:</i> Because <code>status()</code>on a pathname may be a very expensive operation,
1649some operating systems provide status information as a byproduct of directory
1650iteration. Caching such status information can result is significant time savings. Cached and
1651non-cached results may differ in the presence of race conditions. <i>-- end note</i>]</p>
1652<p><span style="background-color: #E0E0E0"><i>Actual cold-boot timing of iteration over
1653a directory with 15,047 entries was six seconds for non-cached status queries
1654versus one second for cached status queries. Windows XP, 3.0 GHz processor, with
1655a moderately fast hard-drive. Similar speedup expected on Linux and BSD-derived
1656Unix variants that provide status during directory iteration.</i></span></p>
1657</blockquote>
1658<h4> <a name="basic_directory_entry-constructors"> <code>basic_directory_entry </code>constructors</a></h4>
1659<pre>basic_directory_entry();</pre>
1660<blockquote>
1661  <p><i>Postconditions:</i></p>
1662  <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="36%">
1663    <tr>
1664      <td width="18%"><b>Expression</b></td>
1665      <td width="82%"><b>Value</b></td>
1666    </tr>
1667    <tr>
1668      <td width="18%"><code>path().empty()</code></td>
1669      <td width="82%"><code>true</code></td>
1670    </tr>
1671    <tr>
1672      <td width="18%"><code>status()</code></td>
1673      <td width="82%"><code>file_status()</code></td>
1674    </tr>
1675    <tr>
1676      <td width="18%"><code>symlink_status()</code></td>
1677      <td width="82%"><code>file_status()</code></td>
1678    </tr>
1679  </table>
1680</blockquote>
1681<pre>explicit basic_directory_entry(const path_type&amp; p, <span style="background-color: #FFFFFF">file_status</span> st=file_status(), <span style="background-color: #FFFFFF">file_status</span> symlink_st=file_status());</pre>
1682<blockquote>
1683  <p><i>Postconditions:</i></p>
1684  <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="36%">
1685    <tr>
1686      <td width="18%"><b>Expression</b></td>
1687      <td width="82%"><b>Value</b></td>
1688    </tr>
1689    <tr>
1690      <td width="18%"><code>path()</code></td>
1691      <td width="82%"><code>p</code></td>
1692    </tr>
1693    <tr>
1694      <td width="18%"><code>status()</code></td>
1695      <td width="82%"><code>st</code></td>
1696    </tr>
1697    <tr>
1698      <td width="18%"><code>symlink_status()</code></td>
1699      <td width="82%"><code>symlink_st</code></td>
1700    </tr>
1701  </table>
1702</blockquote>
1703<h4> <a name="basic_directory_entry-modifiers"> <code>basic_directory_entry </code>modifiers</a></h4>
1704<pre>void assign(const path_type&amp; p, <span style="background-color: #FFFFFF">file_status</span> st=file_status(), <span style="background-color: #FFFFFF">file_status</span> symlink_st=file_status());</pre>
1705<blockquote>
1706  <p><i>Postconditions:</i></p>
1707  <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="36%">
1708    <tr>
1709      <td width="18%"><b>Expression</b></td>
1710      <td width="82%"><b>Value</b></td>
1711    </tr>
1712    <tr>
1713      <td width="18%"><code>path()</code></td>
1714      <td width="82%"><code>p</code></td>
1715    </tr>
1716    <tr>
1717      <td width="18%"><code>status()</code></td>
1718      <td width="82%"><code>st</code></td>
1719    </tr>
1720    <tr>
1721      <td width="18%"><code>symlink_status()</code></td>
1722      <td width="82%"><code>symlink_st</code></td>
1723    </tr>
1724  </table>
1725</blockquote>
1726<pre>void replace_leaf(const string_type&amp; s, <span style="background-color: #FFFFFF">file_status</span> st=file_status(), <span style="background-color: #FFFFFF">file_status</span> symlink_st=file_status());</pre>
1727<blockquote>
1728  <p><i>Postconditions:</i></p>
1729  <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="43%">
1730    <tr>
1731      <td width="18%"><b>Expression</b></td>
1732      <td width="82%"><b>Value</b></td>
1733    </tr>
1734    <tr>
1735      <td width="18%"><code>path()</code></td>
1736      <td width="82%"><code>path().branch() / s</code></td>
1737    </tr>
1738    <tr>
1739      <td width="18%"><code>status()</code></td>
1740      <td width="82%"><code>st</code></td>
1741    </tr>
1742    <tr>
1743      <td width="18%"><code>symlink_status()</code></td>
1744      <td width="82%"><code>symlink_st</code></td>
1745    </tr>
1746  </table>
1747</blockquote>
1748<h4> <a name="basic_directory_entry-observers"> <code>basic_directory_entry</code> observers</a></h4>
1749<pre>const Path&amp; path() const;
1750operator const Path&amp;() const;</pre>
1751<blockquote>
1752  <p><i>Returns:</i> <code>m_path</code></p>
1753</blockquote>
1754<pre><span style="background-color: #FFFFFF">file_status status() const;</span></pre>
1755<blockquote>
1756<p><span style="font-style: italic; background-color: #FFFFFF">Effects:</span><span style="background-color: #FFFFFF"> 
1757As if,</span></p>
1758  <blockquote>
1759    <pre><span style="background-color: #FFFFFF">if ( !status_known( m_status ) )
1760{
1761  if ( status_known(m_symlink_status) &amp;&amp; !is_symlink(m_symlink_status) )
1762    { m_status = m_symlink_status; }
1763  else { m_status = status(m_path); }
1764}</span></pre>
1765  </blockquote>
1766  <p><span style="background-color: #FFFFFF"><i>Throws:</i> See <code>status</code> 
1767  function.</span></p>
1768  <p><span style="background-color: #FFFFFF"><i>Returns:</i> <code>m_status</code></span></p>
1769</blockquote>
1770<pre><span style="background-color: #FFFFFF">file_status status(system_error_code&amp; ec) const;</span></pre>
1771<blockquote>
1772<p><span style="font-style: italic; background-color: #FFFFFF">Effects:</span><span style="background-color: #FFFFFF"> 
1773As if,</span></p>
1774  <blockquote>
1775    <pre><span style="background-color: #FFFFFF">if ( !status_known( m_status ) )
1776{
1777  if ( status_known(m_symlink_status) &amp;&amp; !is_symlink(m_symlink_status) )
1778    { m_status = m_symlink_status; }
1779  else { m_status = status(m_path, ec); }
1780}
1781else ec = 0;</span></pre>
1782  </blockquote>
1783  <p><span style="background-color: #FFFFFF"><i>Returns:</i> <code>m_status</code></span></p>
1784</blockquote>
1785<pre><span style="background-color: #FFFFFF">file_status symlink_status() const;</span></pre>
1786<blockquote>
1787<p><span style="font-style: italic; background-color: #FFFFFF">Effects:</span><span style="background-color: #FFFFFF"> 
1788As if,</span></p>
1789  <blockquote>
1790    <pre><span style="background-color: #FFFFFF">if ( !status_known( m_symlink_status ) )
1791{
1792  m_symlink_status = symlink_status(m_path);
1793}</span></pre>
1794  </blockquote>
1795  <p><span style="background-color: #FFFFFF"><i>Throws:</i> See <code>symlink_status</code> 
1796  function.</span></p>
1797  <p><span style="background-color: #FFFFFF"><i>Returns:</i> <code>
1798  m_symlink_status</code></span></p>
1799</blockquote>
1800<pre><span style="background-color: #FFFFFF">file_status symlink_status(system_error_code&amp; ec) const;</span></pre>
1801<blockquote>
1802<p><span style="font-style: italic; background-color: #FFFFFF">Effects:</span><span style="background-color: #FFFFFF"> 
1803As if,</span></p>
1804  <blockquote>
1805    <pre><span style="background-color: #FFFFFF">if ( !status_known( m_symlink_status ) )
1806{
1807  m_symlink_status = symlink_status(m_path, ec);
1808}
1809else ec = 0;</span></pre>
1810  </blockquote>
1811  <p><span style="background-color: #FFFFFF"><i>Returns:</i> <code>m_symlink_status</code></span></p>
1812</blockquote>
1813<h3><a name="Class-template-basic_directory_iterator">Class template <code>basic_directory_iterator</code></a></h3>
1814<pre>namespace std
1815{
1816  namespace tr2
1817  {
1818    namespace sys
1819    {
1820      template &lt;class Path&gt;
1821      class basic_directory_iterator :
1822        public iterator&lt;input_iterator_tag, basic_directory_entry&lt;Path&gt; &gt;
1823      {
1824      public:
1825        typedef Path path_type;
1826
1827        // <a href="#basic_directory_iterator-constructors">constructors</a>
1828        basic_directory_iterator();
1829        explicit basic_directory_iterator(const Path&amp; dp);
1830        basic_directory_iterator(const Path&amp; dp, system_error_type&amp; ec);
1831        basic_directory_iterator(const basic_directory_iterator&amp; bdi);
1832        basic_directory_iterator&amp; operator=(const basic_directory_iterator&amp; bdi);
1833       ~basic_directory_iterator();
1834
1835        // other members as required by
1836        //  C++ Std, 24.1.1 Input iterators [lib.input.iterators]
1837      };
1838
1839    } // namespace sys
1840  } // namespace tr2
1841} // namespace std</pre>
1842<p> <code>basic_directory_iterator</code> satisfies the requirements of an
1843input iterator (C++ Std, 24.1.1, Input iterators [lib.input.iterators]).</p>
1844<p>A <code>basic_directory_iterator</code> reads successive elements from the directory for
1845which it was constructed, as if by calling <i>POSIX</i>
1846<code>
1847<a href="http://www.opengroup.org/onlinepubs/000095399/functions/readdir_r.html">readdir_r()</a></code>. After a <code>basic_directory_iterator</code> is constructed, and every time
1848<code>operator++</code> is called,
1849it reads and stores a value of <code>basic_directory_entry&lt;Path&gt;</code> 
1850and possibly stores associated status values.
1851<code>operator++</code> is not equality preserving; that is, <code>i == j</code> does not imply that
1852<code>++i == ++j</code>. </p>
1853<blockquote>
1854<p>[<i>Note:</i> The practical consequence of not preserving equality is that directory iterators
1855can be used only for single-pass algorithms. <i>--end note</i>]</p>
1856</blockquote>
1857<p>If the end of the directory elements is reached, the iterator becomes equal to
1858the end iterator value. The constructor <code>basic_directory_iterator()</code> 
1859with no arguments always constructs an end iterator object, which is the only
1860legitimate iterator to be used for the end condition. The result of <code>
1861operator*</code> on an end iterator is not defined. For any other iterator value
1862a <code>const basic_directory_entry&lt;Path&gt;&amp;</code> is returned. The result of
1863<code>operator-&gt;</code> on an end iterator is not defined. For any other
1864iterator value a <code>const basic_directory_entry&lt;Path&gt;*</code> is
1865returned. </p>
1866<p>Two end iterators are always equal. An end iterator is not equal to a non-end
1867iterator.</p>
1868<blockquote>
1869<p><i><span style="background-color: #E0E0E0">The above wording is based on the
1870Standard Library's istream_iterator wording. Commentary was shortened and
1871moved into a note.</span></i></p>
1872</blockquote>
1873<p>The result of calling the <code>path()</code> member of the <code>
1874basic_directory_entry</code> object obtained by dereferencing a <code>
1875basic_directory_iterator</code> is a reference to a <code>basic_path</code> 
1876object composed of the directory argument from which the iterator was
1877constructed with filename of the directory entry appended as if by <code>
1878operator/=</code>. </p>
1879<blockquote>
1880<p>[<i><a name="Example-program">Example</a>: </i>This program accepts an
1881optional command line argument, and if that argument is a directory pathname,
1882iterates over the contents of the directory. For each directory entry, the name
1883is output, and if the entry is for a regular file, the size of the file is
1884output.</p>
1885  <blockquote>
1886    <pre>#include &lt;iostream&gt;
1887#include &lt;filesystem&gt;
1888
1889using std::tr2::sys;
1890using std::cout;
1891
1892int main(int argc, char* argv[])
1893{
1894  std::string p(argc &lt;= 1 ? &quot;.&quot; : argv[1]);
1895
1896  if (is_directory(p))
1897  {
1898    for (directory_iterator itr(p); itr!=directory_iterator(); ++itr)
1899    {
1900      cout &lt;&lt; itr-&gt;path().leaf() &lt;&lt; ' '; // display filename only
1901      if (is_regular(itr-&gt;status())) cout &lt;&lt; &quot; [&quot; &lt;&lt; file_size(itr-&gt;path()) &lt;&lt; ']';
1902      cout &lt;&lt; '\n';
1903    }
1904  }
1905  else cout &lt;&lt; (exists(p) : &quot;Found: &quot; : &quot;Not found: &quot;) &lt;&lt; p &lt;&lt; '\n';
1906
1907  return 0;
1908}</pre>
1909  </blockquote>
1910  <p><i>-- end example</i>]</p>
1911</blockquote>
1912<p>Directory iteration shall not yield directory entries for the current (<i>dot</i>)
1913and parent (<i>dot dot</i>) directories.</p>
1914<p>The order of directory entries obtained by dereferencing successive
1915increments of a <code>basic_directory_iterator</code> is unspecified.</p>
1916<blockquote>
1917<p>[<i>Note:</i> Programs performing directory iteration may wish to test if the
1918path obtained by dereferencing a directory iterator actually exists. It could be
1919a
1920symbolic link to a non-existent file. Programs recursively
1921walking directory trees for purposes of removing and renaming entries may wish
1922to avoid following symbolic links.</p>
1923<p>If a file  is removed from or added to a directory after the
1924construction of a <code>basic_directory_iterator</code> for the directory, it is
1925unspecified whether or not subsequent incrementing of the iterator will ever
1926result in an iterator whose value is the removed or added directory entry. See
1927<i>POSIX</i>
1928<code>
1929<a href="http://www.opengroup.org/onlinepubs/000095399/functions/readdir_r.html">readdir_r()</a></code>. <i>
1930--end note</i>]</p>
1931</blockquote>
1932<h4><a name="basic_directory_iterator-constructors"><code>basic_directory_iterator</code> constructors</a></h4>
1933
1934<p><code>basic_directory_iterator();</code></p>
1935
1936<blockquote>
1937
1938<p><i>Effects:</i> Constructs the end iterator.</p>
1939
1940</blockquote>
1941
1942<p><code>explicit basic_directory_iterator(const Path&amp; dp);</code></p>
1943
1944<blockquote>
1945
1946<p><i>Effects:</i> Constructs a iterator representing the first
1947entry in the directory resolved to by <code>dp</code>, otherwise, the end iterator.</p>
1948
1949<p>[<i>Note:</i> To iterate over the current directory, write <code>
1950directory_iterator(&quot;.&quot;)</code> rather than <code>directory_iterator(&quot;&quot;)</code>.
1951<i>-- end note</i>]</p>
1952</blockquote>
1953<pre><code>basic_directory_iterator(const Path&amp; dp, system_error_type&amp; ec );</code></pre>
1954<blockquote>
1955
1956<p><i>Effects:</i> Constructs a iterator representing the first
1957entry in the directory resolved to by <code>dp</code>, otherwise, the end iterator.
1958If an error occurs while establishing the results, the iterator constructed
1959represents the end iterator and <code>ec</code> is set to the error code
1960reported by the operating system, otherwise to 0.</p>
1961
1962</blockquote>
1963<h3><a name="Class-template-basic_recursive_directory_iterator">Class template <code>basic_recursive_directory_iterator</code></a></h3>
1964<pre>namespace std
1965{
1966  namespace tr2
1967  {
1968    namespace sys
1969    {
1970      template &lt;class Path&gt;
1971      class basic_recursive_directory_iterator :
1972        public iterator&lt;input_iterator_tag, basic_directory_entry&lt;Path&gt; &gt;
1973      {
1974      public:
1975        typedef Path path_type;
1976
1977        // constructors
1978        basic_recursive_directory_iterator();
1979        explicit basic_recursive_directory_iterator(const Path&amp; dp);
1980        basic_recursive_directory_iterator(const basic_recursive_directory_iterator&amp; brdi);
1981        basic_recursive_directory_iterator&amp; operator=(const basic_recursive_directory_iterator&amp; brdi);
1982       ~basic_recursive_directory_iterator();
1983
1984        // observers
1985        int level() const;
1986
1987        // modifiers
1988        void pop();
1989        void no_push();
1990
1991        // other members as required by
1992        //  C++ Std, 24.1.1 Input iterators [lib.input.iterators]
1993
1994      private:
1995        int m_level; // for exposition only
1996      };
1997
1998    } // namespace sys
1999  } // namespace tr2
2000} // namespace std</pre>
2001<p>The behavior of a <code>basic_recursive_directory_iterator</code> is the same
2002as a <code>basic_directory_iterator</code> unless otherwise specified.</p>
2003<ul>
2004  <li>When an iterator is constructed, <code>m_level</code> is set to 0;</li>
2005  <li>When an iterator <code>it</code> is incremented, if <code>it-&gt;is_directory()</code> 
2006  is true and <code>no_push()</code> had not been called subsequent to
2007  the most recent increment operation (or construction, if no increment has
2008  occurred), then&nbsp; <code>m_level</code> is incremented, the
2009  directory is visited, and its contents recursively iterated over.</li>
2010  <li>When an iterator reaches the end of the directory currently being iterated
2011  over, or when <code>pop()</code> is called, <code>m_level</code> is
2012  decremented, and iteration continues with the parent directory, until the
2013  directory specified in the constructor argument is reached.</li>
2014  <li><code>level()</code> returns <code>m_level</code>.</li>
2015  <li><code>level()</code>, <code>pop()</code>, and <code>no_push()</code> all
2016  require that the iterator not be the end iterator.</li>
2017</ul>
2018<blockquote>
2019  <p>[<i>Note:</i> One of the uses of <code>no_push()</code> is to prevent
2020  unwanted recursion into symlinked directories. This may be necessary to
2021  prevent loops on some operating systems. <i>--end note</i>]</p>
2022</blockquote>
2023<h3><a name="file_status">Class file_status</a></h3>
2024<pre>namespace std
2025{
2026  namespace tr2
2027  {
2028    namespace sys
2029    {
2030      class file_status
2031      {
2032      public:
2033        explicit file_status( file_type v = status_unknown );
2034
2035        file_type type() const;
2036        void type( file_type v );
2037      };
2038    } // namespace sys
2039  } // namespace tr2
2040} // namespace std</pre>
2041<p>A <code>file_status</code> object stores information about the status of a
2042file. The internal form of the stored information is unspecified.</p>
2043<blockquote>
2044  <p><i>[Note: </i>The class may be extended in the future to store
2045  additional status information. <i>--end note]</i></p>
2046</blockquote>
2047<h4>Members</h4>
2048<pre>explicit file_status( file_type v = status_unknown );</pre>
2049<blockquote>
2050  <p><i>Effects:</i> Stores <code>v</code>.</p>
2051</blockquote>
2052<pre>file_type type() const;</pre>
2053<blockquote>
2054  <p><i>Returns: </i>The stored <code>file_type</code>.</p>
2055</blockquote>
2056<pre>void type( file_type v );</pre>
2057<blockquote>
2058  <p><i>Effects:</i> Stores <code>v</code>, replacing the previously stored
2059  value.</p>
2060</blockquote>
2061<h3><a name="Non-member-functions">Non-member operational functions</a></h3>
2062<h4><a name="Status-functions">Status functions</a></h4>
2063<pre>template &lt;class Path&gt; file_status status(const Path&amp; p, system_error_code&amp; ec);
2064template &lt;class Path&gt; file_status symlink_status(const Path&amp; p, system_error_code&amp; ec);</pre>
2065<blockquote>
2066  <p><i>Returns:</i></p>
2067  <blockquote>
2068    For <code>status,</code> determine the attributes
2069    of
2070    <code>p</code> as if by<i> POSIX </i> <code>
2071  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>,
2072    for <code>symlink_status</code> determine the attributes as if by <i>POSIX </i> <code>
2073    <a href="http://www.opengroup.org/onlinepubs/000095399/functions/lstat.html">
2074    lstat()</a></code>.<blockquote>
2075      <p>[<i>Note:</i> For symbolic links, <code>stat()</code> continues
2076      pathname resolution using the contents of the symbolic link, <code>lstat()</code> 
2077      does not. <i>--
2078    end note</i>]</p>
2079    </blockquote>
2080    <p>If the operating system reports an error during attribute determination:</p>
2081    <ul>
2082      <li>If the error indicating that <code>p</code> could not
2083      be resolved, as if by POSIX error codes ENOENT or ENOTDIR, set ec to 0 and return <code>
2084      file_status(not_found_flag)</code>.</li>
2085    </ul>
2086    <ul>
2087      <li>Otherwise, set ec to the error code reported by the operating system
2088      and return <code>
2089      file_status(status_unknown)</code>.</li>
2090    </ul>
2091    Otherwise:<ul>
2092      <li>If the attributes indicate a regular file, as if by <i>POSIX</i>&nbsp;S_<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">ISREG()</a>,
2093      return <code>
2094      file_status(regular_file)</code>.</li>
2095      <li>Else if the attributes indicate a directory, as if by <i>POSIX</i> S_<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">ISDIR()</a>,
2096      return <code>
2097      file_status(directory_file)</code>.</li>
2098      <li>Else if the attributes indicate a symbolic link, as if by <i>POSIX</i> S_<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">ISLNK()</a>,
2099      return <code>
2100      file_status(symlink_file)</code>. <i>[Note: </i>Only possible for <code>
2101      symlink_status</code>. <i>--end note]</i></li>
2102      <li>Else if the attributes indicate a block special file, as if by <i>POSIX</i> S_<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">ISBLK()</a>,
2103      return <code>
2104      file_status(block_file)</code>.</li>
2105      <li>Else if the attributes indicate a character special file, as if by <i>POSIX</i> S_<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">ISCHR()</a>,
2106      return <code>
2107      file_status(character_file)</code>.</li>
2108      <li>Else if the attributes indicate a fifo or pipe file, as if by <i>POSIX</i> S_<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">ISFIFO()</a>,
2109      return <code>
2110      file_status(fifo_file)</code>.</li>
2111      <li>Else if the attributes indicate a socket, as if by <i>POSIX</i> S_<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">ISSOCK()</a>,
2112      return <code>
2113      file_status(socket_file)</code>.</li>
2114      <li>Else return <code>
2115      file_status(type_unknown)</code>.</li>
2116    </ul>
2117    </blockquote>
2118<p>[<i>Note:</i> <code>directory_file</code> implies <code>
2119basic_directory_iterator</code> on the file would succeed, and <code>
2120regular_file</code> implies appropriate <code>&lt;fstream&gt;</code> operations would succeed,
2121assuming no hardware, permission, access, or race
2122condition errors. For <code>regular_file,</code> the converse is not true; lack of
2123<code>regular_file</code> does not necessarily imply <code>&lt;fstream&gt;</code> operations would
2124fail on a directory.
2125<i>-- end note</i>]</p>
2126</blockquote>
2127<pre>template &lt;class Path&gt; file_status status(const Path&amp; p);</pre>
2128<blockquote>
2129  <p><i>Effects:</i> <code>system_error_code ec;</code><br>
2130&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
2131  <code>file_status stat(status(p, ec));</code></p>
2132  <p><i>Throws:</i> <code>basic_filesystem_error&lt;Path&gt;</code> if <code>ec
2133  != 0</code></p>
2134  <p><i>Returns:</i> <code>stat</code></p>
2135</blockquote>
2136<pre>template &lt;class Path&gt; file_status symlink_status(const Path&amp; p);</pre>
2137<blockquote>
2138  <p><i>Effects:</i> <code>system_error_code ec;</code><br>
2139&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
2140  <code>file_status stat(symlink_status(p, ec));</code></p>
2141  <p><i>Throws:</i> <code>basic_filesystem_error&lt;Path&gt;</code> if <code>ec
2142  != 0</code></p>
2143  <p><i>Returns: </i><code>stat</code></p>
2144</blockquote>
2145<h4><a name="Predicate-functions">Predicate functions</a></h4>
2146<pre><span style="background-color: #FFFFFF">bool status_known(file_status s);</span></pre>
2147<blockquote>
2148  <p><i><span style="background-color: #FFFFFF">Returns:</span></i><span style="background-color: #FFFFFF">
2149  <code>s.type() != status_unknown</code></span></p>
2150</blockquote>
2151<pre><span style="background-color: #FFFFFF">bool </span><a name="exists"><span style="background-color: #FFFFFF">exists</span></a><span style="background-color: #FFFFFF">(file_status</span><span style="background-color: #FFFFFF"> s);</span></pre>
2152<blockquote>
2153  <p><i><span style="background-color: #FFFFFF">Returns:</span></i><span style="background-color: #FFFFFF">
2154  <code>status_known(s) &amp;&amp; s.type() != file_not_found</code></span></p>
2155</blockquote>
2156<pre>template &lt;class Path&gt; bool <a name="exists">exists</a>(const Path&amp; p);</pre>
2157<blockquote>
2158  <p><i>Returns:</i> <code>exists( status(p) )</code></p>
2159</blockquote>
2160<pre><span style="background-color: #FFFFFF">bool </span><code><span style="background-color: #FFFFFF">is_regular</span></code><span style="background-color: #FFFFFF">(file_status</span><span style="background-color: #FFFFFF"> s);</span></pre>
2161<blockquote>
2162  <p><i><span style="background-color: #FFFFFF">Returns:</span></i><span style="background-color: #FFFFFF">
2163  <code>s.type() == regular_file</code></span></p>
2164</blockquote>
2165<pre><code>template &lt;class Path&gt; bool is_regular(const Path&amp; p);</code></pre>
2166<blockquote>
2167  <p><i>Returns:</i> <code>is_regular( status(p) )</code></p>
2168</blockquote>
2169<pre><span style="background-color: #FFFFFF">bool </span><code><span style="background-color: #FFFFFF">is_directory</span></code><span style="background-color: #FFFFFF">(file_status</span><span style="background-color: #FFFFFF"> s);</span></pre>
2170<blockquote>
2171  <p><i><span style="background-color: #FFFFFF">Returns:</span></i><span style="background-color: #FFFFFF"> </span>
2172  <code><span style="background-color: #FFFFFF">s.type() == directory_file</span></code></p>
2173</blockquote>
2174<pre><code>template &lt;class Path&gt; bool is_directory(const Path&amp; p);</code></pre>
2175<blockquote>
2176  <p><i>Returns:</i> <code>is_directory( status(p) )</code></p>
2177</blockquote>
2178<pre><span style="background-color: #FFFFFF">bool <a name="exists">is_symlink</a>(file_status s);</span></pre>
2179<blockquote>
2180  <p><i><span style="background-color: #FFFFFF">Returns:</span></i><span style="background-color: #FFFFFF"> </span>
2181  <code><span style="background-color: #FFFFFF">s.type() == symlink_file</span></code></p>
2182</blockquote>
2183<pre><code>template &lt;class Path&gt; bool is_symlink(const Path&amp; p);</code></pre>
2184<blockquote>
2185  <p><i>Returns:</i> <code>is_symlink( symlink_status(p) )</code></p>
2186</blockquote>
2187<pre><span style="background-color: #FFFFFF">bool <a name="exists">is_other</a>(file_status s);</span></pre>
2188<blockquote>
2189  <p><i><span style="background-color: #FFFFFF">Returns:</span></i><span style="background-color: #FFFFFF">
2190  <code>return exists(s) &amp;&amp; !is_regular(s) &amp;&amp; !is_directory(s) &amp;&amp; !is_symlink(s)</code></span></p>
2191</blockquote>
2192<pre><code>template &lt;class Path&gt; bool is_other(const Path&amp; p);</code></pre>
2193<blockquote>
2194  <p><i>Returns:</i> <code>is_other( status(p) )</code></p>
2195</blockquote>
2196<pre><code>template &lt;class Path&gt; bool <span style="background-color: #FFFFFF; text-decoration:underline">is_</span>empty(const Path&amp; p);</code></pre>
2197<blockquote>
2198  <p><i>Effects:</i> Determines <code>file_status s</code>, as if by <code>
2199  status(p)</code>.</p>
2200  <p><i>Throws:</i> <code>basic_filesystem_error&lt;Path&gt;</code> if <code>!exist(s) ||
2201  is_other(s)</code>.</p>
2202  <p><i>Returns:</i> <code>is_directory(s)<br>
2203&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ?
2204  basic_directory_iterator&lt;Path&gt;(p) == basic_directory_iterator&lt;Path&gt;()<br>
2205&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; : file_size(p) == 0;</code></p>
2206</blockquote>
2207<pre><code>template &lt;class Path1, class Path2&gt; bool <a name="equivalent">equivalent</a>(const Path1&amp; p1, const Path2&amp; p2);</code></pre>
2208<blockquote>
2209  <p><i>Requires:</i> <code>Path1::external_string_type</code> and <code>
2210  Path2::external_string_type</code> are the same type. </p>
2211  <p><i>Effects:</i> Determines <code>file_status s1</code> and <code>s2</code>,
2212  as if by <code>status(p1)</code> and&nbsp; <code>status(p2)</code>,
2213  respectively.</p>
2214  <p><i>Throws:</i> <code>basic_filesystem_error&lt;Path1&gt;</code><span style="background-color: #FFFFFF"> </span>
2215  if <code>(!exists(s1) &amp;&amp; !exists(s2)) || (is_other(s1) &amp;&amp; 
2216  is_other(s2))</code>.</p>
2217  <p><i>Returns:</i> <code>true</code>, if <code>sf1 == sf2</code> and <code>p1</code> and <code>p2</code> 
2218  resolve to the same file system entity, else <code>false</code>.</p>
2219  <p>Two paths are considered to resolve to
2220  the same file system entity if two candidate entities reside on the same
2221  device at the same location. This is determined as if by the values of the <i>POSIX</i> <code>
2222  <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">stat</a></code> 
2223  structure<code>,</code> obtained as if by <code>
2224  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code> for the two paths, having equal
2225  <code>st_dev</code> values and equal <code>st_ino</code> values.</p>
2226    <p>[<i>Note:</i> <i>POSIX</i> requires that <i>&quot;st_dev</i> must be unique
2227    within a Local Area Network&quot;. Conservative <i>POSIX</i> implementations may
2228    also wish to check for equal <code>st_size</code> and <code>st_mtime</code> 
2229    values. <i>Windows</i> implementations may use <code>GetFileInformationByHandle()</code> as a surrogate for <code>
2230    stat()</code>, and consider &quot;same&quot; to be equal values for <code>
2231    dwVolumeSerialNumber</code>, <code>nFileIndexHigh</code>, <code>
2232    nFileIndexLow</code>, <code>nFileSizeHigh</code>, <code>nFileSizeLow</code>,
2233    <code>ftLastWriteTime.dwLowDateTime</code>, and <code>
2234    ftLastWriteTime.dwHighDateTime</code>. <i>-- end note</i>]</p>
2235</blockquote>
2236<h4><a name="Attribute-functions">Attribute functions</a></h4>
2237<p>[<i>Note:</i> A strictly limited number of attribute functions are provided
2238because few file system attributes are portable. Even the functions provided will be impossible to implement on some file
2239systems. <i>--end note</i>.]</p>
2240<pre>template &lt;class Path&gt; const Path&amp; <a name="initial_path">initial_path</a>();</pre>
2241<blockquote>
2242  <p><i>Returns:</i> <code>current_path()</code> at the time of entry to <code>
2243  main()</code>.</p>
2244  <p>[<i>Note:</i> These semantics turn a dangerous global variable into a safer
2245  global constant. <i>--end note</i>]</p>
2246  <p>[<i>Note:</i> Full implementation requires runtime library support.
2247  Implementations which cannot provide runtime library support are encouraged to
2248  instead store the value of <code>current_path()</code> at the first call of
2249  <a name="initial_path"><code>initial_path</code></a><code>()</code>, and
2250  return this value for all subsequent calls. Programs using
2251  <a name="initial_path"><code>initial_path</code></a><code>()</code> are
2252  encouraged to call it immediately on entrance to <code>main()</code> so that
2253  they will work correctly with such partial implementations. <i>--end note</i>]</p>
2254</blockquote>
2255<pre>template &lt;class Path&gt; Path current_path();</pre>
2256<blockquote>
2257  <p><i>Returns:</i> The current path, as if by <i>POSIX</i>
2258  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/getcwd.html">
2259  <code>getcwd()</code></a>.</p>
2260  <p><i>Postcondition:</i> <code>current_path().is_complete()</code></p>
2261  <p>[<i>Note:</i> The current path as returned by many operating systems is a
2262  dangerous global variable. It may be changed unexpectedly by a third-party or
2263  system library functions, or by another thread. Although dangerous, the
2264  function is useful in dealing with other libraries.. For a safer alternative,
2265  see <code><a href="#initial_path">initial_path()</a></code>. The <code>
2266  current_path()</code> name was chosen to emphasize that the return is a
2267  complete path, not just a single directory name. <i>-- </i><i>end note</i>]</p>
2268</blockquote>
2269<pre>template &lt;class Path&gt; <span style="background-color: #FFFFFF; ">uintmax_t</span> file_size(const Path&amp; p);</pre>
2270<blockquote>
2271  <p><i>Returns:</i> The size
2272  <span style="background-color: #FFFFFF; ">in bytes</span> 
2273  of the file <code>p</code> resolves to, determined as if by the value of
2274  the <i>POSIX</i> <code>
2275  <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">stat</a></code> structure member <code>st_size</code> 
2276  obtained as if by <i>POSIX</i> <code>
2277  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>.</p>
2278</blockquote>
2279<pre><span style="background-color: #FFFFFF"><a name="space">template</a> &lt;class Path&gt; space_info space(const Path&amp; p);</span></pre>
2280<blockquote>
2281  <p><span style="background-color: #FFFFFF"><i>Returns:</i> A <code>space_info</code> 
2282  object. The value of the <code>space_info</code> object is determined as if by
2283  using </span> <i><span style="background-color: #FFFFFF">POSIX</span></i><span style="background-color: #FFFFFF"> <code>
2284  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/statvfs.html" style="text-decoration: none">
2285  statvfs()</a></code> to obtain a <i>POSIX</i> struct <code>
2286  <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/statvfs.h.html" style="text-decoration: none">
2287  statvfs</a></code>, and then multiplying its <code>f_blocks</code>, <code>
2288  f_bfree</code>, and <code>f_bavail</code> members by its <code>f_frsize</code> 
2289  member, and assigning the results to the <code>capacity</code>, <code>free</code>,
2290  and <code>available</code> members respectively. Any members for which the
2291  value cannot be determined shall be set to -1.</span></p>
2292</blockquote>
2293<pre>template &lt;class Path&gt; std::time_t last_write_time(const Path&amp; p);</pre>
2294<blockquote>
2295  <p><i>Returns:</i> The time of last data modification of <code>p</code>, determined as if by the
2296  value of the <i>POSIX</i> <code>
2297  <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">stat</a></code> structure member <code>st_mtime</code>&nbsp; obtained
2298  as if by <i>POSIX</i> <code>
2299  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>.</p>
2300</blockquote>
2301<pre>template &lt;class Path&gt; void last_write_time(const Path&amp; p, const std::time_t new_time);</pre>
2302<blockquote>
2303  <p><i>Effects:</i> Sets the time of last data modification of the file
2304  resolved to by <code>p</code> 
2305  to <code>new_time</code>, as if by <i>POSIX</i> <code>
2306  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code> 
2307  followed by <i>POSIX</i>
2308  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/utime.html">
2309  <code>utime()</code></a>.</p>
2310  <p>[<i>Note:</i> The apparent postcondition <code>last_write_time(p) ==
2311  new_time</code> is not specified since it would not hold for many file systems
2312  due to coarse time mechanism granularity. <i>-- end note</i>]</p>
2313</blockquote>
2314<h4>Other o<a name="Operations-functions">perations functions</a></h4>
2315<pre>template &lt;class Path&gt; bool create_directory(const Path&amp; dp);</pre>
2316<blockquote>
2317  <p><i>Effects:</i> Attempts to create the directory <code>dp</code> resolves to,
2318  as if by<i> POSIX </i><code>
2319  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/mkdir.html">mkdir()</a></code> with a second argument of S_IRWXU|S_IRWXG|S_IRWXO. </p>
2320  <p><i>Throws:</i> <code>basic_filesystem_error&lt;Path&gt;</code> if <i>
2321  Effects</i> fails for any reason other than because the directory already exists.</p>
2322  <p><i>Returns:</i> True if a new directory was created, otherwise false.</p>
2323  <p><i>Postcondition:</i> <code>is_directory(dp)</code></p>
2324</blockquote>
2325<pre><span style="background-color: #FFFFFF">template &lt;class Path1, class Path2&gt;
2326  system_error_type create_hard_link(const Path1&amp; to_p, const Path2&amp; from_p, system_error_code&amp; ec);</span></pre>
2327<blockquote>
2328  <p><i><span style="background-color: #FFFFFF">Requires:</span></i><span style="background-color: #FFFFFF">
2329  </span> <code><span style="background-color: #FFFFFF">Path1::external_string_type</span></code><span style="background-color: #FFFFFF"> and
2330  </span> <code>
2331  <span style="background-color: #FFFFFF">Path2::external_string_type</span></code><span style="background-color: #FFFFFF"> are the same type.</span></p>
2332  <p><i><span style="background-color: #FFFFFF">Effects:</span></i><span style="background-color: #FFFFFF"> Establishes the postcondition, as if by
2333  </span> <i><span style="background-color: #FFFFFF">POSIX</span></i><span style="background-color: #FFFFFF">
2334  </span> <code>
2335  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/link.html">
2336  <span style="background-color: #FFFFFF">link()</span></a></code><span style="background-color: #FFFFFF">.</span></p>
2337  <p><i><span style="background-color: #FFFFFF">Returns:</span></i><span style="background-color: #FFFFFF"> If the
2338  postcondition cannot be established, a system error code
2339  indicating the reason for the failure, otherwise 0.</span></p>
2340  <p><i><span style="background-color: #FFFFFF">Postcondition:</span></i></p>
2341  <ul>
2342    <li><span style="background-color: #FFFFFF">&nbsp;</span><code><span style="background-color: #FFFFFF">exists(to_p) &amp;&amp; exists(from_p) &amp;&amp; equivalent(to_p,
2343    from_p)</span></code></li>
2344    <li><span style="background-color: #FFFFFF">The contents of the file or directory
2345    </span> <code><span style="background-color: #FFFFFF">to_p</span></code><span style="background-color: #FFFFFF"> resolves to are unchanged.</span></li>
2346  </ul>
2347  <p><span style="background-color: #FFFFFF">[</span><i><span style="background-color: #FFFFFF">Note:</span></i><span style="background-color: #FFFFFF"> 
2348  Some operating systems do not support hard links or support
2349  them only for regular files. Some operating systems limit the number of links per
2350  file.
2351  Some file systems that do not
2352  support
2353  hard links - the FAT system used on floppy discs, memory cards and flash
2354  drives,
2355  for example. Thus hard links should be avoided if wide portability is
2356  a concern. </span> <i><span style="background-color: #FFFFFF">-- end note</span></i><span style="background-color: #FFFFFF">]</span></p>
2357  </blockquote>
2358<pre><span style="background-color: #FFFFFF">template &lt;class Path1, class Path2&gt;
2359  void create_hard_link(const Path1&amp; to_p, const Path2&amp; from_p);</span></pre>
2360<blockquote>
2361  <p><i><span style="background-color: #FFFFFF">Requires:</span></i><span style="background-color: #FFFFFF">
2362  </span> <code><span style="background-color: #FFFFFF">Path1::external_string_type</span></code><span style="background-color: #FFFFFF"> and
2363  </span> <code>
2364  <span style="background-color: #FFFFFF">Path2::external_string_type</span></code><span style="background-color: #FFFFFF"> are the same type.</span></p>
2365  <p><i><span style="background-color: #FFFFFF">Effects:</span></i><span style="background-color: #FFFFFF"> 
2366  As if <code>system_error_code ec( create_hard_link( to_p, from_p ) );</code></span></p>
2367  <p><span style="font-style: italic; background-color: #FFFFFF">Throws:</span><span style="background-color: #FFFFFF">
2368  </span> <code>basic_filesystem_error&lt;Path1, Path2&gt;</code><span style="background-color: #FFFFFF"> 
2369  if <code>ec</code> is not zero.</span></p>
2370  </blockquote>
2371<pre><span style="background-color: #FFFFFF">template &lt;class Path1, class Path2&gt;
2372  system_error_type create_symlink(const Path1&amp; to_p, const Path2&amp; from_p, system_error_code&amp; ec);</span></pre>
2373<blockquote>
2374  <p><i><span style="background-color: #FFFFFF">Requires:</span></i><span style="background-color: #FFFFFF">
2375  </span> <code><span style="background-color: #FFFFFF">Path1::external_string_type</span></code><span style="background-color: #FFFFFF"> and
2376  </span> <code>
2377  <span style="background-color: #FFFFFF">Path2::external_string_type</span></code><span style="background-color: #FFFFFF"> are the same type.</span></p>
2378  <p><i><span style="background-color: #FFFFFF">Effects:</span></i><span style="background-color: #FFFFFF"> Establishes the postcondition, as if by
2379  </span> <i><span style="background-color: #FFFFFF">POSIX</span></i><span style="background-color: #FFFFFF">
2380  </span> <code>
2381  <span style="background-color: #FFFFFF">
2382  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/symlink.html">
2383  symlink()</a></span></code><span style="background-color: #FFFFFF">.</span></p>
2384  <p><i><span style="background-color: #FFFFFF">Returns:</span></i><span style="background-color: #FFFFFF"> If the
2385  postcondition cannot be established, a system error code
2386  indicating the reason for the failure, otherwise 0.</span></p>
2387  <p><span style="background-color: #FFFFFF"><i>Postcondition:</i> <code>from_p</code> 
2388  resolves to a symbolic link file that contains an unspecified representation
2389  of <code>to_p</code>.</span></p>
2390  <p><span style="background-color: #FFFFFF">[</span><i><span style="background-color: #FFFFFF">Note:</span></i><span style="background-color: #FFFFFF"> 
2391  Some operating systems do not support symbolic links at all or support
2392  them only for regular files. Thus symbolic links should be avoided if code portability is
2393  a concern. </span> <i><span style="background-color: #FFFFFF">-- end note</span></i><span style="background-color: #FFFFFF">]</span></p>
2394  </blockquote>
2395<pre><span style="background-color: #FFFFFF">template &lt;class Path1, class Path2&gt;
2396  void create_symlink(const Path1&amp; to_p, const Path2&amp; from_p);</span></pre>
2397<blockquote>
2398  <p><i><span style="background-color: #FFFFFF">Requires:</span></i><span style="background-color: #FFFFFF">
2399  </span> <code><span style="background-color: #FFFFFF">Path1::external_string_type</span></code><span style="background-color: #FFFFFF"> and
2400  </span> <code>
2401  <span style="background-color: #FFFFFF">Path2::external_string_type</span></code><span style="background-color: #FFFFFF"> are the same type.</span></p>
2402  <p><i><span style="background-color: #FFFFFF">Effects:</span></i><span style="background-color: #FFFFFF"> 
2403  As if <code>system_error_code ec( create_symlink( to_p, from_p ) );</code></span></p>
2404  <p><span style="font-style: italic; background-color: #FFFFFF">Throws:</span><span style="background-color: #FFFFFF">
2405  </span> <code>basic_filesystem_error&lt;Path1, Path2&gt;</code><span style="background-color: #FFFFFF"> 
2406  if <code>ec</code> is not zero.</span></p>
2407  </blockquote>
2408<pre>template &lt;class Path&gt; bool remove(const Path&amp; p);</pre>
2409<blockquote>
2410  <p><i>Precondition:</i> <code>!p.empty()</code></p>
2411  <p><i>Effects:</i>&nbsp; Attempts to delete the file <code>p</code> resolves
2412  to,
2413  as if by<i> POSIX </i><code>
2414  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/link.html">
2415  remove()</a></code>.</p>
2416  <p><i>Returns:</i> The value of <code>exists(p)</code> prior to the
2417  establishment of the postcondition.</p>
2418  <p><i>Postcondition:</i> <code>!exists(p)</code></p>
2419  <p><i>Throws:</i> <code>basic_filesystem_error&lt;Path&gt;</code> if:</p>
2420  <ul>
2421    <li><code>p.empty() || (exists(p) &amp;&amp; is_directory(p) &amp;&amp; !empty(p))</code>.</li>
2422    <li><i>Effects</i> fails for any reason other than because <code>p</code> 
2423    does not resolve to an existing file.</li>
2424  </ul>
2425  <p>[<i>Note:</i> A symbolic link is itself removed, rather than what it
2426  resolves to being removed. <i>-- end note</i>]</p>
2427</blockquote>
2428<pre>template &lt;class Path1, class Path2&gt; void rename(const Path1&amp; from_p, const Path2&amp; to_p);</pre>
2429<blockquote>
2430  <p><i>Requires:</i> <code>Path1::external_string_type</code> and <code>
2431  Path2::external_string_type</code> are the same type. </p>
2432  <p><i>Effects:</i> Renames <code>from_p</code> to <code>to_p</code>, as if by
2433  <i>POSIX</i> <code>
2434  <a href="http://www.opengroup.org/onlinepubs/000095399/functions/rename.html">
2435  rename()</a></code>.</p>
2436  <p><i>Postconditions:</i> <code>!exists(from_p) &amp;&amp; exists(to_p)</code>, and
2437  the contents and attributes of the file originally named <code>from_p</code> 
2438  are otherwise unchanged.</p>
2439  <p>[<i>Note:</i> If <code>from_p</code> and <code>to_p</code> resolve to the
2440  same file, no action is taken. Otherwise, if <code>to_p</code> resolves to an
2441  existing file, it is removed. A symbolic link is itself renamed, rather than
2442  the file it resolves to being renamed. <i>-- end note</i>]</p>
2443</blockquote>
2444<pre>template &lt;class Path1, class Path2&gt; void copy_file(const Path1&amp; from_fp, const Path2&amp; to_fp);</pre>
2445<blockquote>
2446  <p><i>Requires:</i> <code>Path1::external_string_type</code> and <code>
2447  Path2::external_string_type</code> are the same type. </p>
2448  <p><i>Effects:</i> The contents and attributes of the file <code>from_fp</code> 
2449  resolves to are copied to the file <code>to_fp</code> resolves to.</p>
2450  <p><i>Throws:</i> <code>basic_filesystem_error&lt;Path&gt;</code> if <code>
2451  from_fp.empty() || to_fp.empty() ||!exists(from_fp) || !is_regular(from_fp)
2452  || exists(to_fp)</code></p>
2453</blockquote>
2454<pre>template &lt;class Path&gt; Path complete(const Path&amp; p, const Path&amp; base=initial_path&lt;Path&gt;());</pre>
2455<blockquote>
2456  <p><i>Effects:</i> Composes a complete path from <code>p</code> and <code>base</code>,
2457  using the following rules:</p>
2458  <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
2459    <tr>
2460      <td align="center">&nbsp;</td>
2461      <td align="center"><b><code>p.has_root_directory()</code></b></td>
2462      <td align="center"><b><code>!p.has_root_directory()</code></b></td>
2463    </tr>
2464    <tr>
2465      <td align="center"><b><code>p.has_root_name()</code></b></td>
2466      <td align="center"><code>p</code></td>
2467      <td align="center">precondition failure</td>
2468    </tr>
2469    <tr>
2470      <td align="center"><b><code>!p.has_root_name()</code></b></td>
2471      <td align="center"><code>base.root_name()<br>
2472      / p</code></td>
2473      <td align="center"><code>base / p</code></td>
2474    </tr>
2475  </table>
2476  <p><i>Returns:</i> The composed path.</p>
2477  <p><i>Postcondition:</i> For the returned path, <code>rp,</code> <code>
2478  rp.is_complete()</code> is true.</p>
2479  <p><i>Throws:</i>
2480  <span style="background-color: #FFFFFF">If </span> <code>
2481  <span style="background-color: #FFFFFF">!(base.is_complete() &amp;&amp; (p.is_complete() || !p.has_root_name()))</span></code></p>
2482  <p>[<i><a name="complete_note">Note</a>:</i> When portable behavior is
2483  required, use <i>complete()</i>. When operating system dependent behavior is
2484  required, use <i>system_complete()</i>.</p>
2485  <p>Portable behavior is useful when dealing with paths created
2486  internally within a program, particularly if the program should exhibit the
2487  same behavior on all operating systems.</p>
2488  <p>Operating system dependent behavior is useful when dealing with
2489  paths supplied by user input, reported to program users, or when such behavior
2490  is expected by program users. <i>--
2491  end note</i>]</p>
2492</blockquote>
2493<pre>template &lt;class Path&gt; Path system_complete(const Path&amp; p);</pre>
2494<blockquote>
2495  <p><i>Effects:</i> Composes a complete path from <code>p</code>, using the
2496  same rules used by the operating system to resolve a path passed as the
2497  filename argument to standard library open functions.</p>
2498  <p><i>Returns:</i> The composed path.</p>
2499  <p><i>Postcondition:</i> For the returned path, <code>rp,</code> <code>
2500  rp.is_complete()</code> is true.</p>
2501  <p><i>Throws:</i> <span style="background-color: #FFFFFF">If <code>p.empty()</code>.</span></p>
2502  <p>[<i>Note:</i> For <i>POSIX</i>, <code>system_complete(p)</code> has the same semantics as
2503  <code>complete(p, current_path())</code>.</p>
2504  <p><a name="windows_effects">For <i>Windows</i></a>, <code>system_complete(p)</code> has the
2505  same semantics as <code>complete(ph, current_path())</code> if
2506  <code>p.is_complete() || !p.has_root_name()</code> or <code>p</code> and <code>base</code> have the same
2507  <code>root_name()</code>.
2508  Otherwise it acts like <code>complete(p, kinky)</code>, where <code>kinky</code> 
2509  is the current directory for the <code>p.root_name()</code> drive. This will
2510  be the current directory of that drive the last time it was set, and thus may
2511  be <b>residue left over from a prior program</b> run by the command
2512  processor! Although these semantics are often useful, they are also very
2513  error-prone.</p>
2514  <p>See
2515  <a href="file:///C|/boost/site/libs/filesystem/doc/operations.htm#complete_note">
2516  <i>complete()</i> note</a> for usage suggestions. <i>-- end note</i>]</p>
2517</blockquote>
2518<pre>errno_type <a name="to_errno">to_errno</a>( system_error_type code );</pre>
2519<blockquote>
2520<p><i>Returns:</i> The value of the <code>errno</code> error number which
2521corresponds to the operating system's error code <code>code</code>. The exact
2522correspondence is implementation defined. Implementations are only required to
2523support error codes reported by <code>basic_filesystem_error</code> exceptions
2524thrown by functions defined in this clause.</p>
2525</blockquote>
2526<pre>void system_message( system_error_type ec, std::string &amp; target );
2527void system_message( system_error_type ec, std::wstring &amp; target );</pre>
2528<blockquote>
2529<p><i>Effects:</i> Appends a message corresponding to <code>ec</code> to <code>
2530target</code>.</p>
2531<p>[<i>Note:</i> Implementations are encouraged to supply a localized message. <i>-- end note</i>]</p>
2532</blockquote>
2533<h4><a name="Convenience-functions">Convenience functions</a></h4>
2534<pre>template &lt;class Path&gt; bool create_directories(const Path &amp; p);</pre>
2535<blockquote>
2536  <p><i>Requires:</i> <code>p.empty() || <br>
2537  forall px: px == p || is_parent(px, p): is_directory(px) || !exists( px )</code>
2538  </p>
2539  <p><i>Returns:</i> The value of <code>!exists(p)</code> prior to the
2540  establishment of the postcondition.</p>
2541  <p><i>Postcondition:</i> <code>is_directory(p)</code></p>
2542  <p><i>Throws:</i>&nbsp; <code>basic_filesystem_error&lt;Path&gt;</code> if<code> 
2543  exists(p) &amp;&amp; !is_directory(p)</code></p>
2544</blockquote>
2545<pre>template &lt;class Path&gt; typename Path::string_type extension(const Path &amp; p);</pre>
2546<blockquote>
2547  <p><i>Returns:</i> if <code>p.leaf()</code> contains a <i>dot</i>, returns the
2548  substring of <code>p.leaf()</code> starting at the rightmost <i>dot</i> and
2549  ending at the string's end. Otherwise, returns an empty string. </p>
2550  <p>[<i>Note:<b> </b></i>The <i>dot</i> is included in the return value so that
2551  it is possible to distinguish between no extension and an empty extension. </p>
2552  <p>Implementations are permitted but not required to define additional
2553  behavior for file systems which append additional elements to extensions, such
2554  as alternate data stream or partitioned dataset names. <i>-- end note</i>]</p>
2555</blockquote>
2556<pre>template &lt;class Path&gt; typename Path::string_type basename(const Path &amp; p);</pre>
2557<blockquote>
2558  <p><i>Returns:</i> if <code>p.leaf()</code> contains a <i>dot</i>, returns the
2559  substring of <code>p.leaf()</code> starting at its beginning and ending at the
2560  last <i>dot</i> (the <i>dot</i> is not included). Otherwise, returns <code>
2561  p.leaf()</code>.</p>
2562</blockquote>
2563<pre>template &lt;class Path&gt;
2564  Path replace_extension(const Path &amp; p, const typename Path::string_type &amp; new_extension);</pre>
2565<blockquote>
2566  <p><i>Postcondition:</i> <code>basename(<i>return_value</i>) == basename(p) &amp;&amp; 
2567  extension(<i>return_value</i>) == new_extension</code> </p>
2568  <p>[<i>Note:</i> It follows from the semantics of <code>extension()</code> 
2569  that <code>new_extension</code> should include <i>dot</i> to achieve
2570  reasonable results. <i>-- end note</i>]</p>
2571</blockquote>
2572<h3><a name="header-cerrno">Additions</a> to header <code>&lt;cerrno&gt;</code></h3>
2573<p>The header &lt;cerrno&gt; shall include an additional symbolic constant macro for
2574each of the values  returned by the <a href="#to_errno">to_errno</a> 
2575function. The macro names shall be as defined in <i>POSIX</i>
2576<a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/errno.h.html">
2577errno.h</a>, with the additions below.</p>
2578<blockquote>
2579<p><i><span style="background-color: #E0E0E0">This codifies existing practice.
2580The required names are only a sub-set of those defined by POSIX, and are usually already
2581supplied in &lt;errno.h&gt; (as wrapped by &lt;cerrno&gt;) as shipped with POSIX and Windows compilers.
2582These implementations require no changes to their underlying C headers to conform with the above
2583requirement.</span></i></p>
2584<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="33%">
2585  <tr>
2586    <td width="18%" align="center"><i><b>Name</b></i></td>
2587    <td width="82%" align="center"><i><b>Meaning</b></i></td>
2588  </tr>
2589  <tr>
2590    <td width="18%"><code>EBADHANDLE</code></td>
2591    <td width="82%">Bad operating system handle.</td>
2592  </tr>
2593  <tr>
2594    <td width="18%"><code>EOTHER</code></td>
2595    <td width="82%">Other error.</td>
2596  </tr>
2597</table>
2598</blockquote>
2599<h3><a name="header-fstream">Additions</a> to header <code>&lt;fstream&gt;</code></h3>
2600<blockquote>
2601<p><span style="background-color: #E0E0E0; font-style:italic">These additions have been carefully
2602specified to avoid breaking existing code in common operating environments such as
2603</span> <i><span style="background-color: #E0E0E0">POSIX</span></i><span style="background-color: #E0E0E0; font-style:italic">,
2604</span> <i>
2605<span style="background-color: #E0E0E0">Windows</span></i><span style="background-color: #E0E0E0; font-style:italic">, and
2606</span> <i><span style="background-color: #E0E0E0">OpenVMS.
2607See </span><a href="#Suggestions-for-fstream">
2608<span style="background-color: #E0E0E0">Suggestions for <code>&lt;fstream&gt;</code> 
2609implementations</span></a><span style="background-color: #E0E0E0"> for
2610techniques to avoid breaking existing code in other environments, particularly
2611on operating systems allowing slashes in filenames.</span></i></p>
2612<p><span style="background-color: #FFFFFF">[<i>Note:</i> The
2613&quot;do-the-right-thing&quot; rule from <a href="#Requirements-on-implementations">
2614Requirements on implementations</a> does apply to header <code>&lt;fstream&gt;</code>.</span></p>
2615<p><span style="background-color: #FFFFFF">The overloads
2616below are specified as additions rather than replacements for existing
2617functions. This preserves existing code (perhaps
2618using a <a name="home-grown-path">home-grown path</a> class) that relies on an
2619automatic conversion to <code>const char*</code>.<i> -- end note</i>]</span></p>
2620</blockquote>
2621<p><span style="background-color: #FFFFFF"><i>In 27.8.1.1 Class template
2622basic_filebuf [lib.filebuf] synopsis preceding paragraph 1, add the function:</i></span></p>
2623<blockquote>
2624<pre><span style="background-color: #FFFFFF">template &lt;class Path&gt; </span><span style="background-color: #FFFFFF">basic_filebuf</span><span style="background-color: #FFFFFF">&lt;charT,traits&gt;* </span><span style="background-color: #FFFFFF">open(const</span><span style="background-color: #FFFFFF"> Path&amp; p, </span><span style="background-color: #FFFFFF">ios_base::openmode</span><span style="background-color: #FFFFFF"> mode);</span></pre>
2625</blockquote>
2626<p><span style="background-color: #FFFFFF"><i>In 27.8.1.3 Member functions [lib.filebuf.members],
2627add the above to the signature preceding paragraph 2, and replace the
2628sentence:</i></span></p>
2629<blockquote>
2630<p><span style="background-color: #FFFFFF">It then opens a file, if possible,
2631whose name is the NTBS s (“as if” by calling <code>std::fopen(s ,<i>modstr</i> 
2632))</code>.</span></p>
2633</blockquote>
2634<p><span style="background-color: #FFFFFF"><i>with:</i></span></p>
2635<blockquote>
2636<p><span style="background-color: #FFFFFF">It then opens, if possible, the file
2637that
2638<code>p</code> or <code>path(s)</code> resolves to, “as if” by calling <code>std::fopen()</code> with a
2639second argument of <i>modstr</i>.</span></p>
2640</blockquote>
2641<p><span style="background-color: #FFFFFF"><i>In 27.8.1.5 Class template
2642basic_ifstream [lib.ifstream] synopsis preceding paragraph 1, add the functions:</i></span></p>
2643<blockquote>
2644  <pre><span style="background-color: #FFFFFF">template &lt;class Path&gt; explicit basic_ifstream(const Path&amp; p, ios_base::openmode mode = ios_base::in);
2645template &lt;class Path&gt; void open(const Path&amp; p, ios_base::openmode mode = ios_base::in);</span></pre>
2646</blockquote>
2647<p><i><span style="background-color: #FFFFFF">In 27.8.1.6 basic_ifstream
2648constructors [lib.ifstream.cons] </span></i>
2649<span style="background-color: #FFFFFF"><i>add the above constructor to the signature preceding
2650paragraph 2, and in paragraph 2 replace</i></span></p>
2651<blockquote>
2652<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(s, mode |
2653ios_base::in)</code></span></p>
2654</blockquote>
2655<p><span style="background-color: #FFFFFF"><i>with</i></span></p>
2656<blockquote>
2657<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(path(s), mode |
2658ios_base::in)</code> or <code>rdbuf()-&gt;open(p, mode | ios_base::in)</code> as
2659appropriate</span></p>
2660</blockquote>
2661<p><i><span style="background-color: #FFFFFF">In 27.8.1.7 Member functions [lib.ifstream.members]
2662</span></i><span style="background-color: #FFFFFF"><i>add the above open
2663function to the signature
2664preceding paragraph 3, and in paragraph 3 replace</i></span></p>
2665<blockquote>
2666<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(s, mode |
2667ios_base::in)</code></span></p>
2668</blockquote>
2669<p><span style="background-color: #FFFFFF"><i>with</i></span></p>
2670<blockquote>
2671<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(path(s), mode |
2672ios_base::in)</code> or <code>rdbuf()-&gt;open(p, mode | ios_base::in)</code> as
2673appropriate</span></p>
2674</blockquote>
2675<p><span style="background-color: #FFFFFF"><i>In 27.8.1.8 Class template
2676basic_ofstream [lib.ofstream] synopsis preceding paragraph 1, add the
2677 
2678functions:</i></span></p>
2679<blockquote>
2680  <pre><span style="background-color: #FFFFFF">template &lt;class Path&gt; explicit basic_ofstream(const Path&amp; p, ios_base::openmode mode = ios_base::out);
2681template &lt;class Path&gt; void open(const Path&amp; p, ios_base::openmode mode = ios_base::out);</span></pre>
2682</blockquote>
2683<p><i><span style="background-color: #FFFFFF">In 27.8.1.9 basic_ofstream
2684constructors [lib.ofstream.cons] </span></i>
2685<span style="background-color: #FFFFFF"><i>add the above constructor to the signature preceding
2686paragraph 2, and in paragraph 2 replace</i></span></p>
2687<blockquote>
2688<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(s, mode |
2689ios_base::out)</code></span></p>
2690</blockquote>
2691<p><span style="background-color: #FFFFFF"><i>with</i></span></p>
2692<blockquote>
2693<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(path(s), mode |
2694ios_base::out)</code> or <code>rdbuf()-&gt;open(p, mode | ios_base::out)</code> as
2695appropriate</span></p>
2696</blockquote>
2697<p><i><span style="background-color: #FFFFFF">In 27.8.1.10 Member functions [lib.ofstream.members]
2698</span></i><span style="background-color: #FFFFFF"><i>add the above open
2699function to the signature
2700preceding paragraph 3, and in paragraph 3 replace</i></span></p>
2701<blockquote>
2702<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(s, mode |
2703ios_base::out)</code></span></p>
2704</blockquote>
2705<p><span style="background-color: #FFFFFF"><i>with</i></span></p>
2706<blockquote>
2707<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(path(s), mode |
2708ios_base::out)</code> or <code>rdbuf()-&gt;open(p, mode | ios_base::out)</code> as
2709appropriate</span></p>
2710</blockquote>
2711<p><span style="background-color: #FFFFFF"><i>In 27.8.1.11 Class template
2712basic_fstream [lib.fstream] synopsis preceding paragraph 1, add the  functions:</i></span></p>
2713<blockquote>
2714  <pre><span style="background-color: #FFFFFF">template &lt;class Path&gt; explicit basic_fstream(const Path&amp; p, ios_base::openmode mode = ios_base::in|ios_base::out);
2715template &lt;class Path&gt; void open(const Path&amp; p, ios_base::openmode mode = ios_base::in|ios_base::out);</span></pre>
2716</blockquote>
2717<p><i><span style="background-color: #FFFFFF">In 27.8.1.12 basic_fstream
2718constructors [lib.fstream.cons] </span></i>
2719<span style="background-color: #FFFFFF"><i>add the above constructor to the signature preceding
2720paragraph 2, and in paragraph 2 replace</i></span></p>
2721<blockquote>
2722<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(s, mode)</code></span></p>
2723</blockquote>
2724<p><span style="background-color: #FFFFFF"><i>with</i></span></p>
2725<blockquote>
2726<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(path(s), mode)</code> 
2727or <code>rdbuf()-&gt;open(p, mode)</code> as appropriate</span></p>
2728</blockquote>
2729<p><i><span style="background-color: #FFFFFF">In 27.8.1.13 Member functions [lib.fstream.members]
2730</span></i><span style="background-color: #FFFFFF"><i>add the above open
2731function to the signature
2732preceding paragraph 3, and in paragraph 3 replace</i></span></p>
2733<blockquote>
2734<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(s, mode)</code></span></p>
2735</blockquote>
2736<p><span style="background-color: #FFFFFF"><i>with</i></span></p>
2737<blockquote>
2738<p><span style="background-color: #FFFFFF"><code>rdbuf()-&gt;open(path(s), mode)</code> 
2739or <code>rdbuf()-&gt;open(p, mode)</code> as appropriate</span></p>
2740</blockquote>
2741<p><span style="background-color: #FFFFFF"><i>End of proposed text.</i></span></p>
2742<h2><a name="Path-decomposition-table">Path decomposition table</a></h2>
2743<p>The table is generated by a program compiled with the Boost implementation.</p>
2744<p>Shaded entries indicate cases where <i>POSIX</i> and <i>Windows</i> 
2745implementations yield different results. The top value is the
2746<i>POSIX</i> result and the bottom value is the <i>Windows</i> result. <br>
2747&nbsp;<table border="1" cellspacing="0" cellpadding="5" width="1066">
2748<p>
2749<tr><td width="112"><b>Constructor<br>argument</b></td>
2750<td width="160"><b>Elements found<br>by iteration</b></td>
2751<td width="112"><b><code>string()</code></b></td>
2752<td width="112"><code><b>file_<br>string()</b></td>
2753<td width="72"><b><code>root_<br>path()<br>.string()</code></b></td>
2754<td width="48"><b><code>root_<br>name()</code></b></td>
2755<td width="88"><b><code>root_<br>directory()</code></b></td>
2756<td width="96"><b><code>relative_<br>path()<br>.string()</code></b></td>
2757<td width="72"><b><code>branch_<br>path()<br>.string()</code></b></td>
2758<td width="72"><b><code>leaf()</code></b></td>
2759</tr>
2760<tr>
2761<td width="112"><code>&quot;&quot;</code></td>
2762<td width="160"><code>&quot;&quot;</code></td>
2763<td width="112"><code>&quot;&quot;</code></td>
2764<td width="112"><code>&quot;&quot;</code></td>
2765<td width="72"><code>&quot;&quot;</code></td>
2766<td width="48"><code>&quot;&quot;</code></td>
2767<td width="88"><code>&quot;&quot;</code></td>
2768<td width="96"><code>&quot;&quot;</code></td>
2769<td width="72"><code>&quot;&quot;</code></td>
2770<td width="72"><code>&quot;&quot;</code></td>
2771</tr>
2772<tr>
2773<td width="112"><code>&quot;.&quot;</code></td>
2774<td width="160"><code>&quot;.&quot;</code></td>
2775<td width="112"><code>&quot;.&quot;</code></td>
2776<td width="112"><code>&quot;.&quot;</code></td>
2777<td width="72"><code>&quot;&quot;</code></td>
2778<td width="48"><code>&quot;&quot;</code></td>
2779<td width="88"><code>&quot;&quot;</code></td>
2780<td width="96"><code>&quot;.&quot;</code></td>
2781<td width="72"><code>&quot;&quot;</code></td>
2782<td width="72"><code>&quot;.&quot;</code></td>
2783</tr>
2784<tr>
2785<td width="112"><code>&quot;..&quot;</code></td>
2786<td width="160"><code>&quot;..&quot;</code></td>
2787<td width="112"><code>&quot;..&quot;</code></td>
2788<td width="112"><code>&quot;..&quot;</code></td>
2789<td width="72"><code>&quot;&quot;</code></td>
2790<td width="48"><code>&quot;&quot;</code></td>
2791<td width="88"><code>&quot;&quot;</code></td>
2792<td width="96"><code>&quot;..&quot;</code></td>
2793<td width="72"><code>&quot;&quot;</code></td>
2794<td width="72"><code>&quot;..&quot;</code></td>
2795</tr>
2796<tr>
2797<td width="112"><code>&quot;foo&quot;</code></td>
2798<td width="160"><code>&quot;foo&quot;</code></td>
2799<td width="112"><code>&quot;foo&quot;</code></td>
2800<td width="112"><code>&quot;foo&quot;</code></td>
2801<td width="72"><code>&quot;&quot;</code></td>
2802<td width="48"><code>&quot;&quot;</code></td>
2803<td width="88"><code>&quot;&quot;</code></td>
2804<td width="96"><code>&quot;foo&quot;</code></td>
2805<td width="72"><code>&quot;&quot;</code></td>
2806<td width="72"><code>&quot;foo&quot;</code></td>
2807</tr>
2808<tr>
2809<td width="112"><code>&quot;/&quot;</code></td>
2810<td width="160"><code>&quot;/&quot;</code></td>
2811<td width="112"><code>&quot;/&quot;</code></td>
2812<td bgcolor="#99FF66" width="112"><code>&quot;/&quot;<br>&quot;\&quot;</code></td>
2813<td width="72"><code>&quot;/&quot;</code></td>
2814<td width="48"><code>&quot;&quot;</code></td>
2815<td width="88"><code>&quot;/&quot;</code></td>
2816<td width="96"><code>&quot;&quot;</code></td>
2817<td width="72"><code>&quot;&quot;</code></td>
2818<td width="72"><code>&quot;/&quot;</code></td>
2819</tr>
2820<tr>
2821<td width="112"><code>&quot;/foo&quot;</code></td>
2822<td width="160"><code>&quot;/&quot;,&quot;foo&quot;</code></td>
2823<td width="112"><code>&quot;/foo&quot;</code></td>
2824<td bgcolor="#99FF66" width="112"><code>&quot;/foo&quot;<br>&quot;\foo&quot;</code></td>
2825<td width="72"><code>&quot;/&quot;</code></td>
2826<td width="48"><code>&quot;&quot;</code></td>
2827<td width="88"><code>&quot;/&quot;</code></td>
2828<td width="96"><code>&quot;foo&quot;</code></td>
2829<td width="72"><code>&quot;/&quot;</code></td>
2830<td width="72"><code>&quot;foo&quot;</code></td>
2831</tr>
2832<tr>
2833<td width="112"><code>&quot;foo/&quot;</code></td>
2834<td width="160"><code>&quot;foo&quot;,&quot;.&quot;</code></td>
2835<td width="112"><code>&quot;foo/&quot;</code></td>
2836<td bgcolor="#99FF66" width="112"><code>&quot;foo/&quot;<br>&quot;foo\&quot;</code></td>
2837<td width="72"><code>&quot;&quot;</code></td>
2838<td width="48"><code>&quot;&quot;</code></td>
2839<td width="88"><code>&quot;&quot;</code></td>
2840<td width="96"><code>&quot;foo/&quot;</code></td>
2841<td width="72"><code>&quot;foo&quot;</code></td>
2842<td width="72"><code>&quot;.&quot;</code></td>
2843</tr>
2844<tr>
2845<td width="112"><code>&quot;/foo/&quot;</code></td>
2846<td width="160"><code>&quot;/&quot;,&quot;foo&quot;,&quot;.&quot;</code></td>
2847<td width="112"><code>&quot;/foo/&quot;</code></td>
2848<td bgcolor="#99FF66" width="112"><code>&quot;/foo/&quot;<br>&quot;\foo\&quot;</code></td>
2849<td width="72"><code>&quot;/&quot;</code></td>
2850<td width="48"><code>&quot;&quot;</code></td>
2851<td width="88"><code>&quot;/&quot;</code></td>
2852<td width="96"><code>&quot;foo/&quot;</code></td>
2853<td width="72"><code>&quot;/foo&quot;</code></td>
2854<td width="72"><code>&quot;.&quot;</code></td>
2855</tr>
2856<tr>
2857<td width="112"><code>&quot;foo/bar&quot;</code></td>
2858<td width="160"><code>&quot;foo&quot;,&quot;bar&quot;</code></td>
2859<td width="112"><code>&quot;foo/bar&quot;</code></td>
2860<td bgcolor="#99FF66" width="112"><code>&quot;foo/bar&quot;<br>&quot;foo\bar&quot;</code></td>
2861<td width="72"><code>&quot;&quot;</code></td>
2862<td width="48"><code>&quot;&quot;</code></td>
2863<td width="88"><code>&quot;&quot;</code></td>
2864<td width="96"><code>&quot;foo/bar&quot;</code></td>
2865<td width="72"><code>&quot;foo&quot;</code></td>
2866<td width="72"><code>&quot;bar&quot;</code></td>
2867</tr>
2868<tr>
2869<td width="112"><code>&quot;/foo/bar&quot;</code></td>
2870<td width="160"><code>&quot;/&quot;,&quot;foo&quot;,&quot;bar&quot;</code></td>
2871<td width="112"><code>&quot;/foo/bar&quot;</code></td>
2872<td bgcolor="#99FF66" width="112"><code>&quot;/foo/bar&quot;<br>&quot;\foo\bar&quot;</code></td>
2873<td width="72"><code>&quot;/&quot;</code></td>
2874<td width="48"><code>&quot;&quot;</code></td>
2875<td width="88"><code>&quot;/&quot;</code></td>
2876<td width="96"><code>&quot;foo/bar&quot;</code></td>
2877<td width="72"><code>&quot;/foo&quot;</code></td>
2878<td width="72"><code>&quot;bar&quot;</code></td>
2879</tr>
2880<tr>
2881<td width="112"><code>&quot;///foo///&quot;</code></td>
2882<td width="160"><code>&quot;/&quot;,&quot;foo&quot;,&quot;.&quot;</code></td>
2883<td width="112"><code>&quot;///foo///&quot;</code></td>
2884<td bgcolor="#99FF66" width="112"><code>&quot;///foo///&quot;<br>&quot;\foo\\\&quot;</code></td>
2885<td width="72"><code>&quot;/&quot;</code></td>
2886<td width="48"><code>&quot;&quot;</code></td>
2887<td width="88"><code>&quot;/&quot;</code></td>
2888<td width="96"><code>&quot;foo///&quot;</code></td>
2889<td width="72"><code>&quot;///foo&quot;</code></td>
2890<td width="72"><code>&quot;.&quot;</code></td>
2891</tr>
2892<tr>
2893<td width="112"><code>&quot;///foo///bar&quot;</code></td>
2894<td width="160"><code>&quot;/&quot;,&quot;foo&quot;,&quot;bar&quot;</code></td>
2895<td width="112"><code>&quot;///foo///bar&quot;</code></td>
2896<td bgcolor="#99FF66" width="112"><code>&quot;///foo///bar&quot;<br>&quot;\foo\\\bar&quot;</code></td>
2897<td width="72"><code>&quot;/&quot;</code></td>
2898<td width="48"><code>&quot;&quot;</code></td>
2899<td width="88"><code>&quot;/&quot;</code></td>
2900<td width="96"><code>&quot;foo///bar&quot;</code></td>
2901<td width="72"><code>&quot;///foo&quot;</code></td>
2902<td width="72"><code>&quot;bar&quot;</code></td>
2903</tr>
2904<tr>
2905<td width="112"><code>&quot;/.&quot;</code></td>
2906<td width="160"><code>&quot;/&quot;,&quot;.&quot;</code></td>
2907<td width="112"><code>&quot;/.&quot;</code></td>
2908<td bgcolor="#99FF66" width="112"><code>&quot;/.&quot;<br>&quot;\.&quot;</code></td>
2909<td width="72"><code>&quot;/&quot;</code></td>
2910<td width="48"><code>&quot;&quot;</code></td>
2911<td width="88"><code>&quot;/&quot;</code></td>
2912<td width="96"><code>&quot;.&quot;</code></td>
2913<td width="72"><code>&quot;/&quot;</code></td>
2914<td width="72"><code>&quot;.&quot;</code></td>
2915</tr>
2916<tr>
2917<td width="112"><code>&quot;./&quot;</code></td>
2918<td width="160"><code>&quot;.&quot;,&quot;.&quot;</code></td>
2919<td width="112"><code>&quot;./&quot;</code></td>
2920<td bgcolor="#99FF66" width="112"><code>&quot;./&quot;<br>&quot;.\&quot;</code></td>
2921<td width="72"><code>&quot;&quot;</code></td>
2922<td width="48"><code>&quot;&quot;</code></td>
2923<td width="88"><code>&quot;&quot;</code></td>
2924<td width="96"><code>&quot;./&quot;</code></td>
2925<td width="72"><code>&quot;.&quot;</code></td>
2926<td width="72"><code>&quot;.&quot;</code></td>
2927</tr>
2928<tr>
2929<td width="112"><code>&quot;/..&quot;</code></td>
2930<td width="160"><code>&quot;/&quot;,&quot;..&quot;</code></td>
2931<td width="112"><code>&quot;/..&quot;</code></td>
2932<td bgcolor="#99FF66" width="112"><code>&quot;/..&quot;<br>&quot;\..&quot;</code></td>
2933<td width="72"><code>&quot;/&quot;</code></td>
2934<td width="48"><code>&quot;&quot;</code></td>
2935<td width="88"><code>&quot;/&quot;</code></td>
2936<td width="96"><code>&quot;..&quot;</code></td>
2937<td width="72"><code>&quot;/&quot;</code></td>
2938<td width="72"><code>&quot;..&quot;</code></td>
2939</tr>
2940<tr>
2941<td width="112"><code>&quot;../&quot;</code></td>
2942<td width="160"><code>&quot;..&quot;,&quot;.&quot;</code></td>
2943<td width="112"><code>&quot;../&quot;</code></td>
2944<td bgcolor="#99FF66" width="112"><code>&quot;../&quot;<br>&quot;..\&quot;</code></td>
2945<td width="72"><code>&quot;&quot;</code></td>
2946<td width="48"><code>&quot;&quot;</code></td>
2947<td width="88"><code>&quot;&quot;</code></td>
2948<td width="96"><code>&quot;../&quot;</code></td>
2949<td width="72"><code>&quot;..&quot;</code></td>
2950<td width="72"><code>&quot;.&quot;</code></td>
2951</tr>
2952<tr>
2953<td width="112"><code>&quot;foo/.&quot;</code></td>
2954<td width="160"><code>&quot;foo&quot;,&quot;.&quot;</code></td>
2955<td width="112"><code>&quot;foo/.&quot;</code></td>
2956<td bgcolor="#99FF66" width="112"><code>&quot;foo/.&quot;<br>&quot;foo\.&quot;</code></td>
2957<td width="72"><code>&quot;&quot;</code></td>
2958<td width="48"><code>&quot;&quot;</code></td>
2959<td width="88"><code>&quot;&quot;</code></td>
2960<td width="96"><code>&quot;foo/.&quot;</code></td>
2961<td width="72"><code>&quot;foo&quot;</code></td>
2962<td width="72"><code>&quot;.&quot;</code></td>
2963</tr>
2964<tr>
2965<td width="112"><code>&quot;foo/..&quot;</code></td>
2966<td width="160"><code>&quot;foo&quot;,&quot;..&quot;</code></td>
2967<td width="112"><code>&quot;foo/..&quot;</code></td>
2968<td bgcolor="#99FF66" width="112"><code>&quot;foo/..&quot;<br>&quot;foo\..&quot;</code></td>
2969<td width="72"><code>&quot;&quot;</code></td>
2970<td width="48"><code>&quot;&quot;</code></td>
2971<td width="88"><code>&quot;&quot;</code></td>
2972<td width="96"><code>&quot;foo/..&quot;</code></td>
2973<td width="72"><code>&quot;foo&quot;</code></td>
2974<td width="72"><code>&quot;..&quot;</code></td>
2975</tr>
2976<tr>
2977<td width="112"><code>&quot;foo/./&quot;</code></td>
2978<td width="160"><code>&quot;foo&quot;,&quot;.&quot;,&quot;.&quot;</code></td>
2979<td width="112"><code>&quot;foo/./&quot;</code></td>
2980<td bgcolor="#99FF66" width="112"><code>&quot;foo/./&quot;<br>&quot;foo\.\&quot;</code></td>
2981<td width="72"><code>&quot;&quot;</code></td>
2982<td width="48"><code>&quot;&quot;</code></td>
2983<td width="88"><code>&quot;&quot;</code></td>
2984<td width="96"><code>&quot;foo/./&quot;</code></td>
2985<td width="72"><code>&quot;foo/.&quot;</code></td>
2986<td width="72"><code>&quot;.&quot;</code></td>
2987</tr>
2988<tr>
2989<td width="112"><code>&quot;foo/./bar&quot;</code></td>
2990<td width="160"><code>&quot;foo&quot;,&quot;.&quot;,&quot;bar&quot;</code></td>
2991<td width="112"><code>&quot;foo/./bar&quot;</code></td>
2992<td bgcolor="#99FF66" width="112"><code>&quot;foo/./bar&quot;<br>&quot;foo\.\bar&quot;</code></td>
2993<td width="72"><code>&quot;&quot;</code></td>
2994<td width="48"><code>&quot;&quot;</code></td>
2995<td width="88"><code>&quot;&quot;</code></td>
2996<td width="96"><code>&quot;foo/./bar&quot;</code></td>
2997<td width="72"><code>&quot;foo/.&quot;</code></td>
2998<td width="72"><code>&quot;bar&quot;</code></td>
2999</tr>
3000<tr>
3001<td width="112"><code>&quot;foo/..&quot;</code></td>
3002<td width="160"><code>&quot;foo&quot;,&quot;..&quot;</code></td>
3003<td width="112"><code>&quot;foo/..&quot;</code></td>
3004<td bgcolor="#99FF66" width="112"><code>&quot;foo/..&quot;<br>&quot;foo\..&quot;</code></td>
3005<td width="72"><code>&quot;&quot;</code></td>
3006<td width="48"><code>&quot;&quot;</code></td>
3007<td width="88"><code>&quot;&quot;</code></td>
3008<td width="96"><code>&quot;foo/..&quot;</code></td>
3009<td width="72"><code>&quot;foo&quot;</code></td>
3010<td width="72"><code>&quot;..&quot;</code></td>
3011</tr>
3012<tr>
3013<td width="112"><code>&quot;foo/../&quot;</code></td>
3014<td width="160"><code>&quot;foo&quot;,&quot;..&quot;,&quot;.&quot;</code></td>
3015<td width="112"><code>&quot;foo/../&quot;</code></td>
3016<td bgcolor="#99FF66" width="112"><code>&quot;foo/../&quot;<br>&quot;foo\..\&quot;</code></td>
3017<td width="72"><code>&quot;&quot;</code></td>
3018<td width="48"><code>&quot;&quot;</code></td>
3019<td width="88"><code>&quot;&quot;</code></td>
3020<td width="96"><code>&quot;foo/../&quot;</code></td>
3021<td width="72"><code>&quot;foo/..&quot;</code></td>
3022<td width="72"><code>&quot;.&quot;</code></td>
3023</tr>
3024<tr>
3025<td width="112"><code>&quot;foo/../bar&quot;</code></td>
3026<td width="160"><code>&quot;foo&quot;,&quot;..&quot;,&quot;bar&quot;</code></td>
3027<td width="112"><code>&quot;foo/../bar&quot;</code></td>
3028<td bgcolor="#99FF66" width="112"><code>&quot;foo/../bar&quot;<br>&quot;foo\..\bar&quot;</code></td>
3029<td width="72"><code>&quot;&quot;</code></td>
3030<td width="48"><code>&quot;&quot;</code></td>
3031<td width="88"><code>&quot;&quot;</code></td>
3032<td width="96"><code>&quot;foo/../bar&quot;</code></td>
3033<td width="72"><code>&quot;foo/..&quot;</code></td>
3034<td width="72"><code>&quot;bar&quot;</code></td>
3035</tr>
3036<tr>
3037<td width="112"><code>&quot;c:&quot;</code></td>
3038<td width="160"><code>&quot;c:&quot;</code></td>
3039<td width="112"><code>&quot;c:&quot;</code></td>
3040<td width="112"><code>&quot;c:&quot;</code></td>
3041<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:&quot;</code></td>
3042<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>
3043&quot;&quot;<br>&quot;c:&quot;</code></td>
3044<td width="88"><code>&quot;&quot;</code></td>
3045<td bgcolor="#99FF66" width="96"><code>&quot;c:&quot;<br>&quot;&quot;</code></td>
3046<td width="72"><code>&quot;&quot;</code></td>
3047<td width="72"><code>&quot;c:&quot;</code></td>
3048</tr>
3049<tr>
3050<td width="112"><code>&quot;c:/&quot;</code></td>
3051<td bgcolor="#99FF66" width="160"><code>&quot;c:&quot;,&quot;.&quot;<br>&quot;c:&quot;,&quot;/&quot;</code></td>
3052<td width="112"><code>&quot;c:/&quot;</code></td>
3053<td bgcolor="#99FF66" width="112"><code><span style="background-color: #99FF66">
3054&quot;c:/&quot;<br>&quot;c:\&quot;</span></code></td>
3055<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:/&quot;</code></td>
3056<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3057&quot;&quot;<br>&quot;c:&quot;</code></td>
3058<td bgcolor="#99FF66" width="88"><code>&quot;&quot;<br>&quot;/&quot;</code></td>
3059<td bgcolor="#99FF66" width="96"><code>&quot;c:/&quot;<br>&quot;&quot;</code></td>
3060<td width="72"><code>&quot;c:&quot;</code></td>
3061<td bgcolor="#99FF66" width="72"><code>&quot;.&quot;<br>&quot;/&quot;</code></td>
3062</tr>
3063<tr>
3064<td width="112"><code>&quot;c:foo&quot;</code></td>
3065<td bgcolor="#99FF66" width="160"><code>&quot;c:foo&quot;<br>&quot;c:&quot;,&quot;foo&quot;</code></td>
3066<td width="112"><code>&quot;c:foo&quot;</code></td>
3067<td width="112"><code>&quot;c:foo&quot;</code></td>
3068<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:&quot;</code></td>
3069<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3070&quot;&quot;<br>&quot;c:&quot;</code></td>
3071<td width="88"><code>&quot;&quot;</code></td>
3072<td bgcolor="#99FF66" width="96"><code>&quot;c:foo&quot;<br>&quot;foo&quot;</code></td>
3073<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:&quot;</code></td>
3074<td bgcolor="#99FF66" width="72"><code>&quot;c:foo&quot;<br>&quot;foo&quot;</code></td>
3075</tr>
3076<tr>
3077<td width="112"><code>&quot;c:/foo&quot;</code></td>
3078<td bgcolor="#99FF66" width="160"><code>&quot;c:&quot;,&quot;foo&quot;<br>&quot;c:&quot;,&quot;/&quot;,&quot;foo&quot;</code></td>
3079<td width="112"><code>&quot;c:/foo&quot;</code></td>
3080<td bgcolor="#99FF66" width="112"><code>&quot;c:/foo&quot;<br>&quot;c:\foo&quot;</code></td>
3081<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:/&quot;</code></td>
3082<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3083&quot;&quot;<br>&quot;c:&quot;</code></td>
3084<td bgcolor="#99FF66" width="88"><code>&quot;&quot;<br>&quot;/&quot;</code></td>
3085<td bgcolor="#99FF66" width="96"><code>&quot;c:/foo&quot;<br>&quot;foo&quot;</code></td>
3086<td bgcolor="#99FF66" width="72"><code>&quot;c:&quot;<br>&quot;c:/&quot;</code></td>
3087<td width="72"><code>&quot;foo&quot;</code></td>
3088</tr>
3089<tr>
3090<td width="112"><code>&quot;c:foo/&quot;</code></td>
3091<td bgcolor="#99FF66" width="160"><code>&quot;c:foo&quot;,&quot;.&quot;<br>&quot;c:&quot;,&quot;foo&quot;,&quot;.&quot;</code></td>
3092<td width="112"><code>&quot;c:foo/&quot;</code></td>
3093<td bgcolor="#99FF66" width="112"><code>&quot;c:foo/&quot;<br>&quot;c:foo\&quot;</code></td>
3094<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:&quot;</code></td>
3095<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3096&quot;&quot;<br>&quot;c:&quot;</code></td>
3097<td width="88"><code>&quot;&quot;</code></td>
3098<td bgcolor="#99FF66" width="96"><code>&quot;c:foo/&quot;<br>&quot;foo/&quot;</code></td>
3099<td width="72"><code>&quot;c:foo&quot;</code></td>
3100<td width="72"><code>&quot;.&quot;</code></td>
3101</tr>
3102<tr>
3103<td width="112"><code>&quot;c:/foo/&quot;</code></td>
3104<td bgcolor="#99FF66" width="160"><code>&quot;c:&quot;,&quot;foo&quot;,&quot;.&quot;<br>&quot;c:&quot;,&quot;/&quot;,&quot;foo&quot;,&quot;.&quot;</code></td>
3105<td width="112"><code>&quot;c:/foo/&quot;</code></td>
3106<td bgcolor="#99FF66" width="112"><code>&quot;c:/foo/&quot;<br>&quot;c:\foo\&quot;</code></td>
3107<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:/&quot;</code></td>
3108<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3109&quot;&quot;<br>&quot;c:&quot;</code></td>
3110<td bgcolor="#99FF66" width="88"><code>&quot;&quot;<br>&quot;/&quot;</code></td>
3111<td bgcolor="#99FF66" width="96"><code>&quot;c:/foo/&quot;<br>&quot;foo/&quot;</code></td>
3112<td width="72"><code>&quot;c:/foo&quot;</code></td>
3113<td width="72"><code>&quot;.&quot;</code></td>
3114</tr>
3115<tr>
3116<td width="112"><code>&quot;c:/foo/bar&quot;</code></td>
3117<td bgcolor="#99FF66" width="160"><code>&quot;c:&quot;,&quot;foo&quot;,&quot;bar&quot;<br>&quot;c:&quot;,&quot;/&quot;,&quot;foo&quot;,&quot;bar&quot;</code></td>
3118<td width="112"><code>&quot;c:/foo/bar&quot;</code></td>
3119<td bgcolor="#99FF66" width="112"><code>&quot;c:/foo/bar&quot;<br>&quot;c:\foo\bar&quot;</code></td>
3120<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:/&quot;</code></td>
3121<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3122&quot;&quot;<br>&quot;c:&quot;</code></td>
3123<td bgcolor="#99FF66" width="88"><code>&quot;&quot;<br>&quot;/&quot;</code></td>
3124<td bgcolor="#99FF66" width="96"><code>&quot;c:/foo/bar&quot;<br>&quot;foo/bar&quot;</code></td>
3125<td width="72"><code>&quot;c:/foo&quot;</code></td>
3126<td width="72"><code>&quot;bar&quot;</code></td>
3127</tr>
3128<tr>
3129<td width="112"><code>&quot;prn:&quot;</code></td>
3130<td width="160"><code>&quot;prn:&quot;</code></td>
3131<td width="112"><code>&quot;prn:&quot;</code></td>
3132<td width="112"><code>&quot;prn:&quot;</code></td>
3133<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;prn:&quot;</code></td>
3134<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3135&quot;&quot;<br>&quot;prn:&quot;</code></td>
3136<td width="88"><code>&quot;&quot;</code></td>
3137<td bgcolor="#99FF66" width="96"><code>&quot;prn:&quot;<br>&quot;&quot;</code></td>
3138<td width="72"><code>&quot;&quot;</code></td>
3139<td width="72"><code>&quot;prn:&quot;</code></td>
3140</tr>
3141<tr>
3142<td width="112"><code>&quot;c:\&quot;</code></td>
3143<td bgcolor="#99FF66" width="160"><code>&quot;c:\&quot;<br>&quot;c:&quot;,&quot;/&quot;</code></td>
3144<td bgcolor="#99FF66" width="112"><code>&quot;c:\&quot;<br>&quot;c:/&quot;</code></td>
3145<td width="112"><code>&quot;c:\&quot;</code></td>
3146<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:/&quot;</code></td>
3147<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3148&quot;&quot;<br>&quot;c:&quot;</code></td>
3149<td bgcolor="#99FF66" width="88"><code>&quot;&quot;<br>&quot;/&quot;</code></td>
3150<td bgcolor="#99FF66" width="96"><code>&quot;c:\&quot;<br>&quot;&quot;</code></td>
3151<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:&quot;</code></td>
3152<td bgcolor="#99FF66" width="72"><code>&quot;c:\&quot;<br>&quot;/&quot;</code></td>
3153</tr>
3154<tr>
3155<td width="112"><code>&quot;c:foo&quot;</code></td>
3156<td bgcolor="#99FF66" width="160"><code>&quot;c:foo&quot;<br>&quot;c:&quot;,&quot;foo&quot;</code></td>
3157<td width="112"><code>&quot;c:foo&quot;</code></td>
3158<td width="112"><code>&quot;c:foo&quot;</code></td>
3159<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:&quot;</code></td>
3160<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3161&quot;&quot;<br>&quot;c:&quot;</code></td>
3162<td width="88"><code>&quot;&quot;</code></td>
3163<td bgcolor="#99FF66" width="96"><code>&quot;c:foo&quot;<br>&quot;foo&quot;</code></td>
3164<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:&quot;</code></td>
3165<td bgcolor="#99FF66" width="72"><code>&quot;c:foo&quot;<br>&quot;foo&quot;</code></td>
3166</tr>
3167<tr>
3168<td width="112"><code>&quot;c:\foo&quot;</code></td>
3169<td bgcolor="#99FF66" width="160"><code>&quot;c:\foo&quot;<br>&quot;c:&quot;,&quot;/&quot;,&quot;foo&quot;</code></td>
3170<td bgcolor="#99FF66" width="112"><code>&quot;c:\foo&quot;<br>&quot;c:/foo&quot;</code></td>
3171<td width="112"><code>&quot;c:\foo&quot;</code></td>
3172<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:/&quot;</code></td>
3173<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3174&quot;&quot;<br>&quot;c:&quot;</code></td>
3175<td bgcolor="#99FF66" width="88"><code>&quot;&quot;<br>&quot;/&quot;</code></td>
3176<td bgcolor="#99FF66" width="96"><code>&quot;c:\foo&quot;<br>&quot;foo&quot;</code></td>
3177<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:/&quot;</code></td>
3178<td bgcolor="#99FF66" width="72"><code>&quot;c:\foo&quot;<br>&quot;foo&quot;</code></td>
3179</tr>
3180<tr>
3181<td width="112"><code>&quot;c:foo\&quot;</code></td>
3182<td bgcolor="#99FF66" width="160"><code>&quot;c:foo\&quot;<br>&quot;c:&quot;,&quot;foo&quot;,&quot;.&quot;</code></td>
3183<td bgcolor="#99FF66" width="112"><code>&quot;c:foo\&quot;<br>&quot;c:foo/&quot;</code></td>
3184<td width="112"><code>&quot;c:foo\&quot;</code></td>
3185<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:&quot;</code></td>
3186<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3187&quot;&quot;<br>&quot;c:&quot;</code></td>
3188<td width="88"><code>&quot;&quot;</code></td>
3189<td bgcolor="#99FF66" width="96"><code>&quot;c:foo\&quot;<br>&quot;foo/&quot;</code></td>
3190<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:foo&quot;</code></td>
3191<td bgcolor="#99FF66" width="72"><code>&quot;c:foo\&quot;<br>&quot;.&quot;</code></td>
3192</tr>
3193<tr>
3194<td width="112"><code>&quot;c:\foo\&quot;</code></td>
3195<td bgcolor="#99FF66" width="160"><code>&quot;c:\foo\&quot;<br>&quot;c:&quot;,&quot;/&quot;,&quot;foo&quot;,&quot;.&quot;</code></td>
3196<td bgcolor="#99FF66" width="112"><code>&quot;c:\foo\&quot;<br>&quot;c:/foo/&quot;</code></td>
3197<td width="112"><code>&quot;c:\foo\&quot;</code></td>
3198<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:/&quot;</code></td>
3199<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3200&quot;&quot;<br>&quot;c:&quot;</code></td>
3201<td bgcolor="#99FF66" width="88"><code>&quot;&quot;<br>&quot;/&quot;</code></td>
3202<td bgcolor="#99FF66" width="96"><code>&quot;c:\foo\&quot;<br>&quot;foo/&quot;</code></td>
3203<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:/foo&quot;</code></td>
3204<td bgcolor="#99FF66" width="72"><code>&quot;c:\foo\&quot;<br>&quot;.&quot;</code></td>
3205</tr>
3206<tr>
3207<td width="112"><code>&quot;c:\foo/&quot;</code></td>
3208<td bgcolor="#99FF66" width="160"><code>&quot;c:\foo&quot;,&quot;.&quot;<br>&quot;c:&quot;,&quot;/&quot;,&quot;foo&quot;,&quot;.&quot;</code></td>
3209<td bgcolor="#99FF66" width="112"><code>&quot;c:\foo/&quot;<br>&quot;c:/foo/&quot;</code></td>
3210<td bgcolor="#99FF66" width="112"><code>&quot;c:\foo/&quot;<br>&quot;c:\foo\&quot;</code></td>
3211<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:/&quot;</code></td>
3212<td bgcolor="#99FF66" style="border-left-style: solid; border-left-width: 1; border-right-style: solid; border-right-width: 1" width="48"><code>
3213&quot;&quot;<br>&quot;c:&quot;</code></td>
3214<td bgcolor="#99FF66" width="88"><code>&quot;&quot;<br>&quot;/&quot;</code></td>
3215<td bgcolor="#99FF66" width="96"><code>&quot;c:\foo/&quot;<br>&quot;foo/&quot;</code></td>
3216<td bgcolor="#99FF66" width="72"><code>&quot;c:\foo&quot;<br>&quot;c:/foo&quot;</code></td>
3217<td width="72"><code>&quot;.&quot;</code></td>
3218</tr>
3219<tr>
3220<td width="112"><code>&quot;c:/foo\bar&quot;</code></td>
3221<td bgcolor="#99FF66" width="160"><code>&quot;c:&quot;,&quot;foo\bar&quot;<br>&quot;c:&quot;,&quot;/&quot;,&quot;foo&quot;,&quot;bar&quot;</code></td>
3222<td bgcolor="#99FF66" width="112"><code>&quot;c:/foo\bar&quot;<br>&quot;c:/foo/bar&quot;</code></td>
3223<td bgcolor="#99FF66" width="112"><code>&quot;c:/foo\bar&quot;<br>&quot;c:\foo\bar&quot;</code></td>
3224<td bgcolor="#99FF66" width="72"><code>&quot;&quot;<br>&quot;c:/&quot;</code></td>
3225<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>
3226&quot;&quot;<br>&quot;c:&quot;</code></td>
3227<td bgcolor="#99FF66" width="88"><code>&quot;&quot;<br>&quot;/&quot;</code></td>
3228<td bgcolor="#99FF66" width="96"><code>&quot;c:/foo\bar&quot;<br>&quot;foo/bar&quot;</code></td>
3229<td bgcolor="#99FF66" width="72"><code>&quot;c:&quot;<br>&quot;c:/foo&quot;</code></td>
3230<td bgcolor="#99FF66" width="72"><code>&quot;foo\bar&quot;<br>&quot;bar&quot;</code></td>
3231</tr>
3232</table>
3233<h2><a name="Suggestions-for-fstream">Suggestions for <code>&lt;fstream&gt;</code></a> 
3234implementations</h2>
3235<p><span style="background-color: #FFFFFF">The change in semantics to functions
3236taking <code>const char*</code> arguments can break existing code, but only on
3237operating systems where implementations don't
3238<a href="#Pathname-formats">implicitly accept native format pathnames</a> or
3239operating systems that allow slashes in filenames. Thus on <i>POSIX</i>,
3240<i>Windows,</i> and <i>OpenVMS</i>, for example, there is no problem if the
3241implementation follows encouraged behavior.</span></p>
3242<p><span style="background-color: #FFFFFF">For most of the Filesystem Library,
3243there is no existing code, so the issue preserving existing code that uses
3244slashes in filenames doesn't arise. New code simply must use basic_path
3245constructors with <code>path_format_t</code> arguments of <code>native</code>.
3246To preserve existing fstream code that uses slashes in filenames, an
3247implementation may wish to provide a mechanism such as a macro to control
3248selection of the old behavior.</span></p>
3249<p><span style="background-color: #FFFFFF">Implementations are already required
3250by the TR front-matter to provide a mechanism such as a macro to control
3251selection of the old behavior (useful to guarantee protection of existing code)
3252or new behavior (useful in new code, and code being ported from other systems)
3253for headers. Because use of the rest of the Filesystem Library is independent of
3254use of the <code>&lt;fstream&gt;</code> additions, affected implementations are
3255encouraged to allow disabling the <code>&lt;fstream&gt;</code> additions separately
3256from other TR features.</span></p>
3257<p><span style="background-color: #FFFFFF">An rejected alternative was to supply
3258new fstream classes in namespace <code>sys</code>, inheriting from the current
3259classes, overriding the constructors and opens taking pathname arguments, and
3260providing the additional overloads. In Lillehammer LWG members indicated lack of
3261support for this alternative, feeling that costs outweigh benefits.</span></p>
3262<h2><a name="Issues">Issues</a></h2>
3263<h3>1. Return type of certain basic_path members returning strings. [Howard
3264Hinnant]</h3>
3265<p>For member functions described as returning &quot;<code>const string_type</code>&quot; 
3266or &quot;<code>const external_string_type</code>&quot;, implementations are permitted to
3267return &quot;<code>const string_type&amp;</code>&quot; or&nbsp; &quot;<code>const
3268external_string_type&amp;</code>&quot; respectively.</p>
3269<p>This allows implementations to avoid unnecessary copies. Return-by-value is
3270specified as
3271<code>const</code> to ensure programs won't break if moved to a
3272return-by-reference implementation.</p>
3273<p>For example, the Boost implementation keeps the internal representation of a
3274pathname in the portable format, so string() returns by reference and is inlined:</p>
3275<blockquote>
3276  <pre>const string_type &amp; string() const { return m_path; }</pre>
3277</blockquote>
3278<p>Howard Hinnant comments: This may inhibit optimization if rvalue reference is
3279accepted.&nbsp; Const-qualified return types can't be moved from.&nbsp; I'd
3280rather see either the return type specified as
3281<code>const string_type&amp;</code> or <code>string_type</code>.</p>
3282<p>Beman Dawes comments: I can't make up my mind. Removing the const will bite
3283users, but not very often. OTOH, excessive copying is a real concern, and if
3284move semantics can alleviate that, I'm all for it. What does the LWG think?</p>
3285<h3>2. Basic_path canonize() and normalize() removed. [Beman Dawes]</h3>
3286<p>The Boost implementation has basic_path functions canonize() and normalize()
3287which return cleaned up string representations of a pathname. They have been
3288removed from the proposal as messy to specify and implement, not hugely useful,
3289and possible to implement by users as non-member functions without any loss of
3290functionality or efficiency. There was also a concern the proposal was getting a
3291bit large.</p>
3292<p>These functions can be added later as convenience functions if the LWG so
3293desires..</p>
3294<h3>3. Filename checking functions. [Beman Dawes]</h3>
3295<p>Boost has a set of predicate functions that determine if a filename is valid
3296for a particular operating or system. These can be used as building blocks for
3297functions that determine if an entire pathname is valid for a particular
3298operating or file system.</p>
3299<p>Users can use these functions to ensure that pathnames are in fact portable
3300to target operating or file systems, without having to actually test on the
3301target systems.</p>
3302<p>These functions are not included in the proposal because of lack of time, and
3303uncertainty as to their fit with the Standard Library. They can be added later
3304if the LWG so desires.</p>
3305<h2><a name="Acknowledgements">Acknowledgements</a></h2>
3306<p>This Filesystem Library is dedicated to my wife, Sonda, who provided the
3307support necessary to see both a trial implementation and the proposal itself
3308through to completion. She gave me the strength to continue after a difficult
3309year of cancer treatment in the middle of it all.</p>
3310<p>Many people contributed technical comments, ideas, and suggestions to the
3311Boost Filesystem Library. See
3312<a href="http://www.boost.org/libs/filesystem/doc/index.htm#Acknowledgements">
3313http://www.boost.org/libs/filesystem/doc/index.htm#Acknowledgements</a>.</p>
3314<p>Dietmar Kühl contributed the original Boost Filesystem Library
3315directory_iterator design. Peter Dimov, Walter Landry, Rob Stewart, and Thomas
3316Witt were particularly helpful in refining the library.</p>
3317<p>The create_directories, extension, basename, and replace_extension functions
3318were developed by Vladimir Prus.</p>
3319<p>Howard Hinnant and John Maddock reviewed a draft of the proposal, and
3320identified a number of mistakes or weaknesses, resulting in a more polished
3321final document.</p>
3322<h2><a name="References">References</a></h2>
3323<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
3324  <tr>
3325    <td width="16%" valign="top">[<a name="ISO_POSIX">ISO-POSIX</a>]</td>
3326    <td width="84%">ISO/IEC 9945:2003, IEEE&nbsp;Std&nbsp;1003.1-2001, and The Open Group
3327    Base Specifications, Issue 6. Also known as The Single Unix<font face="Times New Roman">®
3328    Specification, Version 3. Available from each of the organizations involved
3329    in its creation. For example, read online or download from
3330    <a href="http://www.unix.org/single_unix_specification/">
3331    www.unix.org/single_unix_specification/</a>.</font> The ISO JTC1/SC22/WG15 -
3332    POSIX homepage is <a href="http://www.open-std.org/jtc1/sc22/WG15/">
3333    www.open-std.org/jtc1/sc22/WG15/</a></td>
3334  </tr>
3335  <tr>
3336    <td width="16%" valign="top">[Abrahams]</td>
3337    <td width="84%">Dave Abrahams, Error and Exception Handling,
3338    <a href="http://www.boost.org/more/error_handling.html">
3339    www.boost.org/more/error_handling.html</a></td>
3340  </tr>
3341</table>
3342<h2><a name="Revision-History">Revision History</a></h2>
3343<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
3344  <tr>
3345    <td width="11%" valign="top">
3346    <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1841.html">
3347    N1841</a></td>
3348    <td width="89%">
3349    <ul>
3350      <li>Initial version, August, 2005, pre-Tremblant mailing</li>
3351    </ul>
3352    </td>
3353  </tr>
3354  <tr>
3355    <td width="11%" valign="top" bgcolor="#FFFFFF">
3356    <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1889.html">
3357    N1889</a><br>
3358    Revision 1</td>
3359    <td width="89%" bgcolor="#FFFFFF">
3360    <ul>
3361      <li>Missing argument name <code>fmt</code> added to several <code>
3362      basic_path</code> members.</li>
3363      <li> <code>is_empty()</code> name discrepancy between synopsis and
3364      description corrected.</li>
3365      <li><code>file_size()</code> return type changed from <code>intmax_t</code> 
3366      to <code>uintmax_t</code>.&nbsp; Wording slightly clarified.</li>
3367      <li><code>struct space_info</code> and non-member function <code>space()</code> 
3368      added.</li>
3369      <li>A paragraph was added to <b><i>Important design decisions</i></b> 
3370      mentioning the need for both portable and platform specific semantics.</li>
3371    </ul>
3372    </td>
3373  </tr>
3374  <tr>
3375    <td width="11%" valign="top" bgcolor="#FFFFFF">
3376    N1934<br>
3377    Revision 2</td>
3378    <td width="89%" bgcolor="#FFFFFF">
3379    <ul>
3380      <li>Changed native path identification from constructor argument to
3381      <code>&quot;//:&quot;</code> escape prefix. Rationale: simplifies basic_path
3382      constructor interfaces, easier use for platforms needing explicit native
3383      format identification.</li>
3384      <li>Introduced a new base class, filesystem_error, to<span style="background-color: #FFFFFF"> 
3385      allow users to catch a single exception type if desired, or to deal with
3386      the case where the templated type is unknown. Rename filesystem_error and
3387      wfilesystem_error accordingly.</span></li>
3388      <li><span style="background-color: #FFFFFF">Rewording
3389      basic_filesystem_error text to more closely follow the form of clause 19
3390      of the standard.</span></li>
3391      <li><span style="background-color: #FFFFFF">Removed dual specification of
3392      certain errors in both &quot;Reguires&quot; and &quot;Throws&quot; paragraphs. Since throwing
3393      an exception is well-defined behavior, the error condition does not result
3394      in undefined behavior as implied by &quot;Requires&quot;. (Suggested by Dave
3395      Abrahams)</span></li>
3396      <li><span style="background-color: #FFFFFF">Added a non-throwing version
3397      of create_hard_link().</span></li>
3398      <li><span style="background-color: #FFFFFF">Added two create_symlink()
3399      functions.</span></li>
3400      <li><span style="background-color: #FFFFFF">Added basic_path inserter and
3401      extractor. (Suggested by Vladimir Prus)</span></li>
3402      <li><span style="background-color: #FFFFFF">Added basic_path member and
3403      non-member swap() functions.</span></li>
3404      <li><span style="background-color: #FFFFFF">Aligned basic_path operator
3405      functions with std::basic_string practice. </span></li>
3406      <li><span style="background-color: #FFFFFF">Replaced status_flags with
3407      file_type enum and file_status class to improve encapsulation and allow
3408      for future expansion of file_status.</span></li>
3409      <li><span style="background-color: #FFFFFF">Added predicate functions
3410      overloaded on file_status (Suggested by Martin Adrian). This change,
3411      coupled with the introduction of file_status, clarifies the meaning of
3412      file types and related predicate operations, and eliminates the need for
3413      user bit manipulation, which was a source of user error.</span></li>
3414      <li><span style="background-color: #FFFFFF">Predicate function
3415      specification clarified accordingly.</span></li>
3416      <li><span style="background-color: #FFFFFF">Revised and explicitly
3417      documented policy for non-throwing versions of functions to increase
3418      consistency.</span></li>
3419      <li><span style="background-color: #FFFFFF">Added basic_directory_iterator
3420      constructor non-throwing overload (Suggested by Martin Adrian).</span></li>
3421      <li><span style="background-color: #FFFFFF">Changed symlink awareness to
3422      separately name functions to cut clutter caused by addition of
3423      non-throwing overloads.</span></li>
3424    </ul>
3425    </td>
3426  </tr>
3427  </table>
3428<hr>
3429<p>© Copyright Beman Dawes, 2002-2006</p>
3430<p>Revised
3431<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y-%m-%d" startspan -->2006-02-06<!--webbot bot="Timestamp" endspan i-checksum="12142" --></p>
3432
3433</body>
3434
3435</html>
Note: See TracBrowser for help on using the repository browser.