libs/filesystem/doc/reference.html

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