1<html> 2<!-- © Copyright Beman Dawes, 2002, 2006, 2007, 2009, 2010, 2011 --> 3<!-- Distributed under the Boost Software License, Version 1.0. --> 4<!-- See http://www.boost.org/LICENSE_1_0.txt --> 5 6<!-- generate-section-numbers=false --> 7 8<head> 9<meta http-equiv="Content-Language" content="en-us"> 10<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> 11<meta name="ProgId" content="FrontPage.Editor.Document"> 12<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 13<link href="styles.css" rel="stylesheet"> 14<title>Filesystem Reference</title> 15</head> 16 17<body> 18 19 20 21<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111"> 22 <tr> 23 <td width="277"> 24<p> 25<a href="../../../index.htm"> 26<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="300" height="86" border="0"></a></td> 27 <td align="middle"> 28 <font size="7">Filesystem Library<br> 29 </font> 30 <font size="6">Version 3</font></td> 31 </tr> 32</table> 33 34<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" 35 bordercolor="#111111" bgcolor="#D7EEFF" width="100%"> 36 <tr> 37 <td><a href="index.htm">Home</a> 38 <a href="tutorial.html">Tutorial</a> 39 <a href="reference.html">Reference</a> 40 <a href="faq.htm">FAQ</a> 41 <a href="release_history.html">Releases</a> 42 <a href="portability_guide.htm">Portability</a> 43 <a href="v3.html">V3 Intro</a> 44 <a href="v3_design.html">V3 Design</a> 45 <a href="deprecated.html">Deprecated</a> 46 <a href="issue_reporting.html">Bug Reports </a> 47 </td> 48</table> 49 50<h1>Reference Documentation</h1> 51 52 53 54<h2><a name="TOC">Table of Contents</a></h2> 55 56<table border="0" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%"> 57 <tr> 58 <td width="33%" valign="top"> 59 <p><a href="#Introduction">Introduction</a><br> 60 <a href="#Definitions">Definitions</a><br> 61 <a href="#Conformance">Conformance</a><br> 62 <a href="#Header-filesystem-synopsis"> 63 Header <code><boost/filesystem.hpp></code> synopsis</a><br> 64 <a href="#Error-reporting">Error reporting</a><br> 65 <a href="#class-path">Class <code>path</code></a><br> 66 <a href="#path-Conversions"><code>path</code> conversions</a><br> 67 <a href="#path-Conversions-to-native-format"><code>path</code> 68 conversions to native format</a><br> 69 <a href="#path-Conversions-to-generic-format"><code>path</code> 70 conversions to generic format</a><br> 71 <a href="#path-Encoding-conversions"><code>path</code> 72 encoding conversions</a><br> 73 <a href="#path-Requirements"><code>path</code> requirements</a><br> 74 <a href="#path-constructors"><code>path</code> constructors</a><br> 75 <a href="#path-assignments"><code>path</code> assignments</a><br> 76 <a href="#path-appends"><code>path</code> appends</a><br> 77 <a href="#path-concatenation"><code>path</code> concatenation</a><br> 78 <a href="#path-modifiers"><code>path</code> modifiers</a><br> 79 <a href="#path-native-format-observers"><code>path</code> native 80 format observers</a><br> 81 <a href="#path-generic-format-observers"><code>path</code> generic 82 format observers</a><br> 83 <a href="#path-compare"><code>path</code> compare</a><br> 84 <a href="#path-decomposition"><code>path</code> decomposition</a><br> 85 <a href="#path-query"><code>path</code> query</a><br> 86 <a href="#path-iterators"><code>path</code> iterators</a><br> 87 88 <a href="#path-deprecated-functions"><code>path</code> deprecated functions</a><br> 89 <a href="#path-non-member-functions"><code>path</code> non-member functions</a><br> 90 <a href="#path-inserter-extractor"><code>path</code> inserters and extractors</a><br> 91 <a href="#Class-filesystem_error">Class <code>filesystem_error</code></a><br> 92 <a href="#filesystem_error-members"><code>filesystem_error</code> 93 constructors</a><br> 94 <a href="#filesystem_error-path1"><code>filesystem_error</code> path1</a><br> 95 <a href="#filesystem_error-path2"><code>filesystem_error</code> path2</a><br> 96 <a href="#filesystem_error-what"><code>filesystem_error</code> what</a></td> 97 <td width="33%" valign="top"> 98 <p> 99 <a href="#Enum-file_type">Enum <code>file_type</code></a><br> 100 <a href="#Enum-perms">Enum <code>perms</code></a><br> 101 <a href="#file_status">Class 102 <code>file_status</code></a><br> 103 104 <a href="#file_status"> 105 <code>file_status</code></a><a href="#file_status-constructors"> constructors</a><br> 106 <code><a href="#file_status-modifiers">file_status-modifiers</a></code><a href="#directory_entry-observers"> observers</a><br> 107 <code><a href="#file_status-observers">file_status-observers</a></code><a href="#directory_entry-modifiers"> modifiers</a><br> 108<a href="#Class-directory_entry">Class <code>directory_entry</code></a><br> 109 110<a href="#directory_entry-constructors"><code>directory_entry</code> constructors</a><br> 111 <a href="#directory_entry-observers"><code>directory_entry</code> observers</a><br> 112 <a href="#directory_entry-modifiers"><code>directory_entry</code> modifiers</a><br> 113<a href="#Class-directory_iterator">Class <code>directory_iterator</code></a><br> 114 <a href="#directory_iterator-members"><code>directory_iterator</code> 115 members</a><br> 116<a href="#Class-recursive_directory_iterator">Class <code>recursive_directory_iterator</code></a><br> 117 <a href="#Operational-functions"> 118 Operational functions</a><br> 119 <code> <a href="#absolute">absolute</a><br> 120 <a href="#canonical">canonical</a><br> 121 <a href="#copy">copy</a><br> 122 <a href="#copy_directory">copy_directory</a><br> 123 <a href="#copy_file">copy_file</a><br> 124 <a href="#copy_symlink">copy_symlink</a><br> 125 <a href="#create_directories">create_directories</a><br> 126 <a href="#create_directory">create_directory</a><br> 127 <a href="#create_hard_link">create_hard_link</a><br> 128 <a href="#create_symlink">create_symlink</a><br> 129 <a href="#current_path">current_path</a><br> 130 <a href="#exists">exists</a><br> 131 <a href="#equivalent">equivalent</a><br> 132 <a href="#file_size">file_size</a><br> 133 <a href="#hard_link_count">hard_link_count</a><br> 134 <a href="#initial_path">initial_path</a><br> 135 i<a href="#is_directory">s_directory</a><br> 136 <a href="#is_empty">is_empty</a></code></td> 137 <td width="34%" valign="top"> 138 <p> 139 <code> <a href="#is_other">is_other</a><br> 140 <a href="#is_regular_file">is_regular_file</a><br> 141 <a href="#is_symlink">is_symlink</a><br> 142 <a href="#last_write_time">last_write_time</a><br> 143 <a href="#permissions">permissions</a><br> 144 <a href="#read_symlink">read_symlink</a><br> 145 <a href="#relative">relative</a><br> 146 <a href="#remove">remove</a><br> 147 <a href="#remove_all">remove_all</a><br> 148 <a href="#rename">rename</a><br> 149 <a href="#resize_file">resize_file</a><br> 150 <a href="#space">space</a><br> 151 <a href="#status">status</a><br> 152 <a href="#status_known">status_known</a><br> 153 <a href="#symlink_status">symlink_status</a><br> 154 <a href="#system_complete">system_complete</a><br> 155 <a href="#temp_directory_path">temp_directory_path</a><br> 156 <a href="#unique_path">unique_path</a><br> 157 <a href="#weakly_canonical">weakly_canonical</a><br></code> 158 <a href="#File-streams">File streams</a><br> 159<a href="#path-decomposition-table">Path decomposition table</a><br> 160 <a href="#long-path-warning">Warning: Long paths on Windows and the 161 extended-length <b>\\?\ </b>prefix</a><br> 162<a href="#Acknowledgements">Acknowledgements</a><br> 163<a href="#References">References</a><br> 164 </td> 165 </tr> 166</table> 167 168 169<h2><a name="Introduction">Introduction</a></h2> 170 171<p>This reference documentation describes components that C++ programs may use 172to perform operations involving file systems, including paths, regular files, 173and directories.</p> 174 175<blockquote> 176<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" 177 bordercolor="#111111" bgcolor="#D7EEFF" width="90%"> 178 <tr> 179 <td width="100%" align="center" colspan="2"> 180 <p align="center"><b>C++11 Support</b><p align="left">This reference 181 documentation is written as if all compilers supported C++11. Where 182 possible, the implementation falls back to C++03 if a C++11 feature is not 183 available.</td> 184 </tr> 185 <tr> 186 <td width="35%" align="center"> 187 <p> 188 <b>C++11 Feature</b></td> 189 <td width="65%" align="center"> 190 <p> 191 <b>Action if not supported by compiler</b></td> 192 </tr> 193 <tr> 194 <td width="35%" align="left"> 195 <p> 196 <code>noexcept</code></td> 197 <td width="65%" align="left"> 198 <p>Keyword omitted.</td> 199 </tr> 200 <tr> 201 <td width="35%" align="left"> 202 <p> 203 <code>constexpr</code></td> 204 <td width="65%" align="left"> 205 <p>Keyword omitted.</td> 206 </tr> 207 <tr> 208 <td width="35%" align="left"> 209 <p>R-value references</td> 210 <td width="65%" align="left"> 211 <p>Function signature omitted.</td> 212 </tr> 213 <tr> 214 <td width="35%" align="left"> 215 <p>New character types</td> 216 <td width="65%" align="left"> 217 <p>The <code>boost::filesystem</code> interface doesn't use the 218 new types directly. It does use <code>u16string</code> and <code>u32string</code> 219 in namespace <code>boost</code>. These are typedefs to <code>std::u16string</code> 220 and <code>std::u32string</code> for C++11, or to <code> 221 std::basic_string<boost::u16_t></code> and <code> 222 std::basic_string<boost::u32_t></code> for C++03.</td> 223 </tr> 224 <tr> 225 <td width="35%" align="left"> 226 <p>Defaulted and deleted functions</td> 227 <td width="65%" align="left"> 228 <p>Workaround replacement functions provided.</td> 229 </tr> 230 <tr> 231 <td width="35%" align="left"> 232 <p>Initializer lists</td> 233 <td width="65%" align="left"> 234 <p>Not currently used.</td> 235 </tr> 236 <tr> 237 <td width="35%" align="left"> 238 <p>Variadic templates</td> 239 <td width="65%" align="left"> 240 <p>Not currently used.</td> 241 </tr> 242 <tr> 243 <td width="35%" align="left"> 244 <p>Range-based for statements</td> 245 <td width="65%" align="left"> 246 <p>Supporting functions always provided; they do no harm even for C++03 247 compilers.</td> 248 </tr> 249</table> 250</blockquote> 251 252 253 254<h2><a name="Conformance">Conformance</a> [fs.conformance]</h2> 255 256<h3>ISO/IEC 9945 conformance [fs.conform.9945]</h3> 257<p>Some behavior in this reference documentation is specified by reference to ISO/IEC 9945. How such behavior is actually implemented is unspecified.</p> 258<blockquote> 259<p>[<i>Note:</i> This constitutes an "as if" rule for implementation of 260operating system dependent behavior. In practice implementations will usually call native 261operating system API's. <i>—end note</i>]</p> 262</blockquote> 263<p>Implementations are encouraged to provide such behavior 264 265as it is defined by ISO/IEC 9945. Implementations shall document any 266behavior that differs from the behavior defined by ISO/IEC 9945. Implementations that do not support exact 267ISO/IEC 9945 behavior are 268encouraged to provide behavior as close to ISO/IEC 9945 behavior as is reasonable given the 269limitations of actual operating systems and file systems. If an implementation cannot provide any 270reasonable behavior, the implementation shall report an error in an 271implementation-defined manner.</p> 272<blockquote> 273<p>[<i>Note:</i> Such errors might be reported by an #error directive, a <code> 274static_assert</code>, a <code>filesystem_error</code> exception, a special 275return value, or some other manner. <i>—end note</i>]</p> 276</blockquote> 277<p>Implementations are not required to provide behavior that is not supported by 278a particular file system.</p> 279<blockquote> 280<p>[<i>Example:</i> The <a href="http://en.wikipedia.org/wiki/FAT_filesystem"> 281FAT file system</a> used by some memory cards, camera memory, and floppy discs 282does not support hard links, symlinks, and many other features of more capable 283file systems. Implementations are only required to support the FAT features 284supported by the host operating system. <i>—end example</i>]</p> 285</blockquote> 286<p>The behavior of functions described in this 287reference 288may differ from their specification in 289the presence of <a href="#file-system-race">file system races</a>. No diagnostic is required.</p> 290<p>If the possibility of a file system race would make it unreliable for a program to 291test for a precondition before calling a function described in this reference documentation, <i> 292Requires</i> is not specified for the condition. Instead, the condition is 293specified as a <i>Throws</i> condition.</p> 294<blockquote> 295<p>[<i>Note:</i> As a design practice, preconditions are not specified when it 296is unreasonable for a program to detect them prior to calling the function. <i> 297—end note</i>]</p> 298</blockquote> 299<h3>Operating system dependent conformance [fs.conform.os]</h3> 300<p>Some behavior is specified in this reference documentation as being 301operating system dependent ([fs.def.osdep]). The operation system an 302implementation is dependent upon is implementation defined.</p> 303<p>It is permissible for an implementation to be dependent upon an operating 304system emulator rather than the actual operating system.</p> 305<blockquote> 306<p>[<i>Example:</i> An implementation uses Cygwin, a Linux® API emulator for 307some Windows® operating system versions. The implementation would define Cygwin 308as its operating system. Users could refer to the Cygwin documentation to find 309details of the operating system dependent behavior. <i>—end example</i>]</p> 310<p><span style="background-color: #E0E0E0"><i>It is user and conformance test 311detectable that such an implementation is running on Cygwin. Users would be 312misled and conformance tests would fail if the implementation defined Linux or 313Windows rather than Cygwin as the operating system, since real behavior is a 314blend of the two.</i></span> </p> 315</blockquote> 316<h2><a name="Definitions">Definitions</a> [fs.definitions]</h2> 317<p>The following definitions shall apply throughout this reference documentation:</p> 318<h3><a name="operating system dependent">operating system dependent</a> behavior 319[fs.def.osdep]</h3> 320<p>Behavior that is dependent upon the behavior 321and characteristics of an operating system. See [fs.conform.os].</p> 322<h3><a name="file">file</a> [fs.def.file]</h3> 323<p>An object that can be written to, or read from, or both. A file 324has certain attributes, including type. File types include regular files 325and directories. Other types of files, such as symbolic links, may be supported by the 326implementation.</p> 327<h3><a name="file-system">file system</a> [fs.def.filesystem]</h3> 328<p>A collection of files and certain of their attributes.</p> 329<h3><a name="filename">filename</a> [fs.def.filename]</h3> 330 <p>The name of a file. Filenames <code> 331 "."</code> 332and <code>".."</code> have special meaning. The follow characteristics of 333 filenames are operating system dependent:</p> 334<ul> 335 <li> 336 <p>The permitted characters. See [<a href="#Operating-system-examples">fs.os.examples</a>].</p> 337 </li> 338 <li> 339 <p>Specific filenames that are not permitted.</p> 340 </li> 341 <li> 342 <p>Additional filenames that have special meaning.</p> 343 </li> 344 <li> 345 <p>Case awareness and sensitivity during path resolution.</p> 346 </li> 347 <li> 348 <p>Special rules that may apply to file types other than regular 349 files, such as directories.</p> 350 </li> 351</ul> 352<h3><a name="path">path</a> [fs.def.path]</h3> 353<p>A sequence of elements that identify 354the location of a file within a filesystem. The elements are the <i>root-name<sub>opt</sub></i>, <i> 355root-directory<sub>opt</sub></i>, and an optional sequence of filenames. [<i>Note:</i> 356A <a href="#pathname">pathname</a> is the concrete representation of a path. <i>—end note</i>]</p> 357 358<h3><a name="Absolute-path">absolute path</a> [fs.def.absolute-path]</h3> 359<p>A path that 360unambiguously 361identifies the location of a file without reference to an additional starting 362location. The elements of a path that determine if it is absolute are 363operating system dependent.</p> 364 365<h3><a name="Relative-path">relative path</a> [fs.def.relative-path]</h3> 366<p>A path that 367is not absolute, and so only 368unambiguously 369identifies the location of a file when resolved relative to 370an implied starting location. The elements of a path that determine if it is 371relative are operating system dependent. [<i>Note:</i> 372Paths <code>"."</code> and <code>".."</code> are relative paths. <i>—end note</i>]</p> 373<h3><a name="canonical-path">canonical path</a> [fs.def.canonical-path]</h3> 374<p>An absolute path that has 375no elements that are symbolic links, and no <code>"."</code> or <code>".."</code> elements.</p> 376<h3><a name="pathname">pathname</a> [fs.def.pathname]</h3> 377<p>A character string that represents 378the name of a 379path. Pathnames are formatted according to the generic pathname grammar or an 380operating system dependent 381native pathname format.</p> 382 383<h3><a name="native-pathname-format">native pathname format</a> [fs.def.native]</h3> 384<p>The operating system dependent pathname format accepted by the host operating system.</p> 385<h3><a name="normal-form">normal form</a> path [fs.def.normal]</h3> 386<p>A path with no redundant current directory (<i>dot</i>) or parent directory (<i>dot-dot</i>) 387elements. The normal form for an empty path is an empty path. The normal form 388for a path ending in a <i>directory-separator</i> that is not the root directory 389is the same path with a current directory (<i>dot</i>) element appended.</p> 390<h3><a name="link">link</a> [fs.def.link]</h3> 391<p>A directory entry object that associates a 392filename with a file. On some file systems, several directory entries can 393associate names with the same file.</p> 394<h3><a name="hard-link">hard link</a> [fs.def.hardlink]</h3> 395<p>A link to an existing file. Some 396file systems support multiple hard links to a file. If the last hard link to a 397file is removed, the file itself is removed.</p> 398<blockquote> 399<p>[<i>Note:</i> A hard link can be thought of as a shared-ownership smart 400pointer to a file.<i> —end note</i>]<i> </i></p> 401</blockquote> 402<h3><a name="symbolic-link">symbolic link</a> [fs.def.symlink]</h3> 403<p>A type of file with the 404property that when the file is encountered during pathname resolution, a string 405stored by the file is used to modify the pathname resolution.</p> 406<blockquote> 407<p>[<i>Note:</i> A symbolic link can be thought of as a raw pointer to a file. 408If the file pointed to does not exist, the symbolic link is said to be a 409"dangling" symbolic link.<i> —end note</i>]<i> </i></p> 410</blockquote> 411<h3><a name="file-system-race">file system race</a> [fs.def.race]</h3> 412<p>The condition that occurs 413when multiple threads, processes, or computers interleave access and 414modification of 415the same object within a file system.</p> 416<h2><a name="generic-pathname-format">Generic pathname format</a> [path.generic]</h2> 417<p><i>pathname:<br> 418 root-name<sub>opt</sub> 419root-directory<sub>opt</sub> relative-path<sub>opt</sub></i></p> 420<p><i>root-name:<br> 421 </i>An 422operating system dependent name that identifies the starting location for 423absolute paths. </p> 424<blockquote> 425 <blockquote> 426<p>[<i>Note:</i> Many operating systems define a name 427beginning with two <i>directory-separator</i> characters as a <i>root-name</i> 428that identifies network or other resource locations. Some operating systems define a single letter followed by a colon as a drive 429specifier - a <i>root-name</i> identifying a specific device such as a disc drive. <i>—end note</i>]</p> 430 </blockquote> 431</blockquote> 432<p><i>root-directory:<br> 433 434directory-separator</i></p> 435<p><i>relative-path:<br> 436 437filename<br> 438 relative-path 439directory-separator<br> 440 relative-path 441directory-separator filename</i></p> 442<p><i>filename:<br> 443 name<br> 444 </i><code>"."</code><i><br> 445 </i><code> 446".."</code></p> 447<p><i>preferred-separator:<br> 448 </i>An 449operating system dependent directory separator character. May be a synonym for <i> <code>"/"</code>.</i></p> 450<p><i>directory-separator:<br> 451 <code>"/"<br> 452 "/"</code> directory-separator<br> 453 454preferred-separator<br> 455 456preferred-separator directory-separator</i></p> 457<p>Multiple successive <i>directory-separator</i> characters are considered to 458be the same as one <i>directory-separator</i> character.</p> 459<p>The <i>filename</i> 460<code>"."</code> is considered to be a reference to the current directory. The 461<i>filename</i> <code>".."</code> is considered to be a reference to the 462parent 463directory. Specific <i>filenames</i> may have special meanings for a particular 464operating system.</p> 465<h2><a name="Operating-system-examples">Operating system dependent examples</a> (Informative) [fs.os.examples]</h2> 466<p>Certain features are specified in this reference documentation as being operating system dependent. The following table shows the application of those 467specifications for operating systems that use the ISO/IEC 9945 or Windows® application program interfaces 468(APIs).<sup>[footnote1]</sup></p> 469<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111"> 470 <tr> 471 <td valign="top" align="center"> 472 <p><b>Feature</b></td> 473 <td valign="top" align="center"> 474 <p><b>Section</b></td> 475 <td valign="top" align="center"> 476 <p><b>ISO/IEC 9945<br> 477 POSIX</b>®<b> API</b></td> 478 <td valign="top" align="center"> 479 <p><b>Windows</b>®<b> API</b></td> 480 <td valign="top" align="center"> 481 <p><b>Notes</b></td> 482 </tr> 483 <tr> 484 <td valign="top"> 485 <p><code>path<br> 486 ::value_type</code></td> 487 <td valign="top"> 488 <p>[<a href="#class-path">class.path</a>]</td> 489 <td valign="top"> 490 <p><code>char</code></td> 491 <td valign="top"> 492 <p><code>wchar_t</code></td> 493 <td valign="top"> 494 <p> </td> 495 </tr> 496 <tr> 497 <td valign="top"> 498 <p><code>path::preferred<br> 499 _separator</code></td> 500 <td valign="top"> 501 <p>[<a href="#class-path">class.path</a>]</td> 502 <td valign="top"> 503 <p><code>'/'</code></td> 504 <td valign="top"> 505 <p><code>L'\\'</code> (single backslash)</td> 506 <td valign="top"> 507 <p> </td> 508 </tr> 509 <tr> 510 <td valign="top"> 511 <p><code>path("/")<br> 512 .is_absolute()<br> 513 path("c:/")<br> 514 .is_absolute()</code></td> 515 <td valign="top"> 516 <p>[<a href="#path-query">path</a><br> 517 <a href="#path-query">.query</a>]</td> 518 <td valign="top"> 519 <p><code><br> 520 true<br> 521 <br> 522 false</code></td> 523 <td valign="top"> 524 <p><code><br> 525 false<br> 526 <br> 527 true</code></td> 528 <td valign="top"> 529 <p> </td> 530 </tr> 531 <tr> 532 <td valign="top"> 533 <p><code>path</code> argument disambiguation between generic format and 534 native format</td> 535 <td valign="top"> 536 <p>[<a href="#path-Conversions-to-native-format">path.arg</a><br> 537 <a href="#path-Conversions-to-native-format">.fmt.cvt</a>]</td> 538 <td valign="top"> 539 <p>Not required</td> 540 <td valign="top"> 541 <p>Not required</td> 542 <td valign="top"> 543 <p>There is no need to distinguish between the generic format and native 544 format for these operating systems.</td> 545 </tr> 546 <tr> 547 <td valign="top"> 548 <p><code>path</code> argument format conversion</td> 549 <td valign="top"> 550 <p>[<a href="#path-Conversions-to-native-format">path.arg</a><br> 551 <a href="#path-Conversions-to-native-format">.fmt.cvt</a>]</td> 552 <td valign="top"> 553 <p>No conversion performed</td> 554 <td valign="top"> 555 <p>No conversion performed</td> 556 <td valign="top"> 557 <p>The generic format is already acceptable to the native API of these operating systems.</td> 558 </tr> 559 <tr> 560 <td valign="top"> 561 <p><code>path<br> 562 ("/cats/jane")<br> 563 .c_str()<br> 564 path|<br> 565 ("/cats/jane/")<br> 566 .c_str()</code></td> 567 <td valign="top"> 568 <p>[<a href="#path-Conversions-to-native-format">path.arg</a><br> 569 <a href="#path-Conversions-to-native-format">.fmt.cvt</a>]</td> 570 <td valign="top"> 571 <p> <code><br> 572 <br> 573 "/cats/jane"<br> 574 <br> 575 <br> 576 "/cats/jane/"</code></td> 577 <td valign="top"> 578 <p><code><br> 579 <br> 580 L"/cats/jane"<br> 581 <br> 582 <br> 583 L"/cats/jane/"</code></td> 584 <td valign="top"> 585 <p>These operating systems accept the same native separator between 586 directory names and a final file name, so no format conversion is performed. 587 Other operating systems might require conversion.</td> 588 </tr> 589 <tr> 590 <td valign="top"> 591 <p>Format conversion by <code>path</code> native format observers</td> 592 <td valign="top"> 593 <p>[<a href="#path-native-format-observers">path.native</a><br> 594 <a href="#path-native-format-observers">.obs</a>]</td> 595 <td valign="top"> 596 <p>No conversion performed</td> 597 <td valign="top"> 598 <p>No conversion performed</td> 599 <td valign="top"> 600 <p>For efficiency, <code>path</code> objects are required to store pathnames in the native 601 format regardless of operating system.</td> 602 </tr> 603 <tr> 604 <td valign="top"> 605 <p>Format conversion by <code>path</code> generic format observers</td> 606 <td valign="top"> 607 <p>[<a href="#path-generic-format-observers">path</a><br> 608 <a href="#path-generic-format-observers">.generic</a><br> 609 <a href="#path-generic-format-observers">.obs</a>]</td> 610 <td valign="top"> 611 <p>No conversion performed</td> 612 <td valign="top"> 613 <p>Backslashes converted to slashes</td> 614 <td valign="top"> 615 <p> </td> 616 </tr> 617 <tr> 618 <td valign="top"> 619 <p><code>p.<br> 620 make_preferred()</code></td> 621 <td valign="top"> 622 <p>[<a href="#path-modifiers">fs.path</a><br> 623 <a href="#path-modifiers">.modifiers</a>]</td> 624 <td valign="top"> 625 <p>No change</td> 626 <td valign="top"> 627 <p>Slashes converted to backslashes</td> 628 <td valign="top"> 629 <p> </td> 630 </tr> 631 <tr> 632 <td valign="top"> 633 <p>Characters prohibited in filenames</td> 634 <td valign="top"> 635 <p>[<a href="#filename">fs.def</a><br> 636 <a href="#filename">.filename</a>]</td> 637 <td valign="top"> 638 <p>0x00, <code>'/'</code></td> 639 <td valign="top"> 640 <p>0x00-0x1F, <code>'"'</code>, <code>'*'</code>,<code> '*'</code>, 641 <code>'<'</code>, 642 <code>'>'</code>, <code>'?'</code>, <code>'\\'</code> (single backslash), 643 <code>'/'</code>, <code>'|'</code></td> 644 <td valign="top"> 645 <p>Many operating systems prohibit the ASCII control characters (0x00-0x1F) 646 in filenames.</td> 647 </tr> 648 <tr> 649 <td valign="top"> 650 <p>Initial imbued <code>path</code> locale</td> 651 <td valign="top"> 652 <p>[<a href="#path-imbued-locale">path</a><br> 653 <a href="#path-imbued-locale">.imbued</a><br> 654 <a href="#path-imbued-locale">.locale</a>]</td> 655 <td valign="top"> 656 <p> <code>std::<br> 657 locale("")<br> 658 </code><sup>[footnote 2]</sup></td> 659 <td valign="top"> 660 <p>Implementation supplied locale using <code>MultiByte<br> 661 ToWideChar</code> 662 and <code>WideChar<br> 663 ToMultiByte</code> with a codepage of <code>CP_ACP</code> 664 if <code>AreFileApisANSI</code> is true, otherwise codepage <code>CP_OEMCP</code>.<sup>[footnote 665 3]</sup></td> 666 <td valign="top"> 667 <p>Apple OS X®: Implementation supplied locale providing UTF-8 <code>codecvt</code> 668 facet.<sup>[footnote 4]</sup></td> 669 </tr> 670</table> 671<p><sup>[footnote1]</sup> OS X® and Windows® are examples of commercially 672available operating systems. This information is given for the convenience of 673users of this document and does not constitute an endorsement by ISO or IEC of 674these products.</p> 675<p><sup>[footnote 2] </sup>Rationale: ISO C specifies <code>std::locale("")</code> as "the locale-specific native 676environment", while ISO/IEC 9945 says it "Specifies an implementation-defined native 677environment."</p> 678<p><sup>[footnote 3] </sup>Rationale: This is the current behavior of C and C++ 679standard library functions that perform file operations using narrow character 680strings to identify paths. Changing this behavior would be surprising and at 681variance with existing code, particularly where user input is involved.</p> 682<p><sup>[footnote 4]</sup> Rationale: Vendor's documentation states "All BSD 683system functions expect their string parameters to be in UTF-8 encoding and 684nothing else."</p> 685<h2><a name="Header-filesystem-synopsis">Header <code><boost/filesystem.hpp></code> synopsis</a> 686[filesystem.synopsis]</h2> 687 688 689 690<pre>namespace boost 691{ 692 namespace filesystem 693 { 694 class <a href="#class-path">path</a>; 695 696 bool lexicographical_compare(path::iterator first1, path::iterator last1, 697 path::iterator first2, path::iterator last2); 698 void swap(path& lhs, path& rhs); 699 std::size_t <a href="#hash_value">hash_value</a>(const path& p); 700 701 bool operator==(const path& lhs, const path& rhs); 702 bool operator!=(const path& lhs, const path& rhs); 703 bool operator< (const path& lhs, const path& rhs); 704 bool operator<=(const path& lhs, const path& rhs); 705 bool operator> (const path& lhs, const path& rhs); 706 bool operator>=(const path& lhs, const path& rhs); 707 708 path operator/ (const path& lhs, const path& rhs); 709 710 std::ostream& operator<<( std::ostream& os, const path& p ); 711 std::wostream& operator<<( std::wostream& os, const path& p ); 712 std::istream& operator>>( std::istream& is, path& p ); 713 std::wistream& operator>>( std::wistream& is, path& p ) 714 715 class <a href="#Class-filesystem_error">filesystem_error</a>; 716 class <a href="#Class-directory_entry">directory_entry</a>; 717 718 class <a href="#Class-directory_iterator">directory_iterator</a>; 719 720 // enable c++11 range-based for statements 721 const directory_iterator& <a href="#directory_iterator-non-member-functions">begin</a>(const directory_iterator& iter); 722 directory_iterator <a href="#directory_iterator-non-member-functions">end</a>(const directory_iterator&); 723 724 725 // enable BOOST_FOREACH 726 directory_iterator& range_begin(directory_iterator& iter); 727 directory_iterator range_begin(const directory_iterator& iter); 728 directory_iterator range_end(const directory_iterator&); 729 730 class <a href="#Class-recursive_directory_iterator">recursive_directory_iterator</a>; 731 732 // enable c++11 range-based for statements 733 const recursive_directory_iterator& 734 <a href="#recursive_directory_iterator-non-member-functions">begin</a>(const recursive_directory_iterator& iter); 735 recursive_directory_iterator 736 <a href="#recursive_directory_iterator-non-member-functions">end</a>(const recursive_directory_iterator&); 737 738 739 // enable BOOST_FOREACH 740 recursive_directory_iterator& 741 range_begin(recursive_directory_iterator& iter); 742 recursive_directory_iterator 743 range_begin(const recursive_directory_iterator& iter); 744 recursive_directory_iterator 745 range_end(const recursive_directory_iterator&); 746 747 enum <a name="file_type" href="#Enum-file_type">file_type</a> 748 { 749 status_error, file_not_found, regular_file, directory_file, 750 symlink_file, block_file, character_file, fifo_file, socket_file, 751 reparse_file, type_unknown 752 }; 753 754 enum <a href="#Enum-perms">perms</a> 755 { 756 no_perms, 757 owner_read, owner_write, owner_exe, owner_all, 758 group_read, group_write, group_exe, group_all, 759 others_read, others_write, others_exe, others_all, all_all, 760 set_uid_on_exe, set_gid_on_exe, sticky_bit, 761 perms_mask, perms_not_known, 762 add_perms, remove_perms, symlink_perms 763 }; 764 765 class <a href="#file_status">file_status</a>; 766 767 struct <a name="space_info">space_info</a> // returned by <a href="#space" style="text-decoration: none">space</a> function 768 { 769 uintmax_t capacity; 770 uintmax_t free; 771 uintmax_t available; // free space available to non-privileged process 772 }; 773 774 enum class <a name="copy_options">copy_options</a> 775 { 776 none = 0u, 777 // <a href="#copy_file">copy_file</a> options 778 skip_existing, 779 overwrite_existing, 780 update_existing, 781 // <a href="#copy">copy</a> options 782 recursive, 783 copy_symlinks, 784 skip_symlinks, 785 directories_only, 786 create_symlinks, 787 create_hard_links 788 }; 789 790 // Deprecated, use <a href="#copy_options">copy_options</a> instead 791 enum class <a name="copy_option">copy_option</a> 792 { 793 none = copy_options::none, 794 fail_if_exists = none, 795 overwrite_if_exists = copy_options::overwrite_existing 796 }; 797 798 enum class <a name="directory_options">directory_options</a> 799 { 800 none = 0u, 801 skip_permission_denied, 802 follow_directory_symlink, 803 pop_on_error 804 }; 805 806 // Deprecated, use <a href="#directory_options">directory_options</a> instead 807 enum class <a name="symlink_option">symlink_option</a> 808 { 809 none = directory_options::none, 810 no_recurse = none, 811 recurse = directory_options::follow_directory_symlink 812 }; 813 814 // <a href="#Operational-functions">operational functions</a> 815 816 path <a href="#absolute">absolute</a>(const path& p, const path& base=current_path()); 817 path <a href="#absolute">absolute</a>(const path& p, system::error_code& ec); 818 path <a href="#absolute">absolute</a>(const path& p, const path& base, 819 system::error_code& ec); 820 821 path <a href="#canonical">canonical</a>(const path& p, const path& base = current_path()); 822 path <a href="#canonical">canonical</a>(const path& p, system::error_code& ec); 823 path <a href="#canonical">canonical</a>(const path& p, const path& base, 824 system::error_code& ec); 825 826 void <a href="#copy">copy</a>(const path& from, const path& to); 827 void <a href="#copy">copy</a>(const path& from, const path& to, 828 system::error_code& ec); 829 void <a href="#copy">copy</a>(const path& from, const path& to, 830 <a href="#copy_options">copy_options</a> options); 831 void <a href="#copy">copy</a>(const path& from, const path& to, 832 <a href="#copy_options">copy_options</a> options, system::error_code& ec); 833 834 // Deprecated, use <a href="#create_directory">create_directory</a> instead 835 void <a href="#copy_directory">copy_directory</a>(const path& from, const path& to); 836 void <a href="#copy_directory">copy_directory</a>(const path& from, const path& to, 837 system::error_code& ec); 838 839 bool <a href="#copy_file">copy_file</a>(const path& from, const path& to); 840 bool <a href="#copy_file">copy_file</a>(const path& from, const path& to, 841 system::error_code& ec); 842 bool <a href="#copy_file">copy_file</a>(const path& from, const path& to, 843 <a href="#copy_options">copy_options</a> options); 844 bool <a href="#copy_file">copy_file</a>(const path& from, const path& to, 845 <a href="#copy_options">copy_options</a> options, system::error_code& ec); 846 // Deprecated, use overloads taking <a href="#copy_options">copy_options</a> instead 847 bool <a href="#copy_file">copy_file</a>(const path& from, const path& to, 848 <a href="#copy_option">copy_option</a> options); 849 bool <a href="#copy_file">copy_file</a>(const path& from, const path& to, 850 <a href="#copy_option">copy_option</a> options, system::error_code& ec); 851 852 void <a href="#copy_symlink">copy_symlink</a>(const path& existing_symlink, 853 const path& new_symlink); 854 void <a href="#copy_symlink">copy_symlink</a>(const path& existing_symlink, 855 const path& new_symlink, system::error_code& ec); 856 857 bool <a href="#create_directories">create_directories</a>(const path& p); 858 bool <a href="#create_directories">create_directories</a>(const path& p, 859 system::error_code& ec); 860 861 bool <a href="#create_directory">create_directory</a>(const path& p); 862 bool <a href="#create_directory">create_directory</a>(const path& p, system::error_code& ec); 863 bool <a href="#create_directory">create_directory</a>(const path& p, const path& existing); 864 bool <a href="#create_directory">create_directory</a>(const path& p, const path& existing, system::error_code& ec); 865 866 void <a href="#create_directory_symlink">create_directory_symlink</a>(const path& to, 867 const path& new_symlink); 868 void <a href="#create_directory_symlink">create_directory_symlink</a>(const path& to, 869 const path& new_symlink, system::error_code& ec); 870 871 void <a href="#create_hard_link">create_hard_link</a>(const path& to, const path& new_hard_link); 872 void <a href="#create_hard_link">create_hard_link</a>(const path& to, const path& new_hard_link, 873 system::error_code& ec); 874 875 void <a href="#create_symlink">create_symlink</a>(const path& to, const path& new_symlink); 876 void <a href="#create_symlink">create_symlink</a>(const path& to, const path& new_symlink, 877 system::error_code& ec); 878 879 path <a href="#current_path">current_path</a>(); 880 path <a href="#current_path">current_path</a>(system::error_code& ec); 881 void <a href="#current_path">current_path</a>(const path& p); 882 void <a href="#current_path">current_path</a>(const path& p, system::error_code& ec); 883 884 bool <a href="#exists">exists</a>(file_status s) noexcept; 885 bool <a href="#exists">exists</a>(const path& p); 886 bool <a href="#exists">exists</a>(const path& p, system::error_code& ec) noexcept; 887 888 bool <a href="#equivalent">equivalent</a>(const path& p1, const path& p2); 889 bool <a href="#equivalent">equivalent</a>(const path& p1, const path& p2, 890 system::error_code& ec); 891 892 uintmax_t <a href="#file_size">file_size</a>(const path& p); 893 uintmax_t <a href="#file_size">file_size</a>(const path& p, system::error_code& ec); 894 895 uintmax_t <a href="#hard_link_count">hard_link_count</a>(const path& p); 896 uintmax_t <a href="#hard_link_count">hard_link_count</a>(const path& p, system::error_code& ec); 897 898 const path& <a href="#initial_path">initial_path</a>(); 899 const path& <a href="#initial_path">initial_path</a>(<code>system::error_code& ec</code>); 900 901 bool <a href="#is_directory">is_directory</a>(file_status s) noexcept; 902 bool <a href="#is_directory2">is_directory</a>(const path& p); 903 bool <a href="#is_directory2">is_directory</a>(const path& p, 904 system::error_code& ec) noexcept; 905 906 bool <a href="#is_empty">is_empty</a>(const path& p); 907 bool <a href="#is_empty">is_empty</a>(const path& p, system::error_code& ec); 908 909 bool <a href="#is_other">is_other</a>(file_status s) noexcept; 910 bool <a href="#is_other2">is_other</a>(const path& p,); 911 bool <a href="#is_other2">is_other</a>(const path& p, system::error_code& ec) noexcept; 912 913 bool <a href="#is_regular_file">is_regular_file</a>(file_status s) noexcept; 914 bool <a href="#is_regular_file2">is_regular_file</a>(const path& p); 915 bool <a href="#is_regular_file2">is_regular_file</a>(const path& p, 916 system::error_code& ec) noexcept; 917 918 bool <a href="#is_symlink">is_symlink</a>(file_status s noexcept); 919 bool <a href="#is_symlink2">is_symlink</a>(const path& p); 920 bool <a href="#is_symlink2">is_symlink</a>(const path& p, system::error_code& ec) noexcept; 921 922 std::time_t <a href="#last_write_time">last_write_time</a>(const path& p); 923 std::time_t <a href="#last_write_time">last_write_time</a>(const path& p, system::error_code& ec); 924 void <a href="#last_write_time2">last_write_time</a>(const path& p, const std::time_t new_time); 925 void <a href="#last_write_time2">last_write_time</a>(const path& p, const std::time_t new_time, 926 system::error_code& ec); 927 928 path <a href="#read_symlink">read_symlink</a>(const path& p); 929 path <a href="#read_symlink">read_symlink</a>(const path& p, system::error_code& ec); 930 931 path <a href="#relative">relative</a>(const path& p, system::error_code& ec); 932 path <a href="#relative">relative</a>(const path& p, const path& base=current_path()); 933 path <a href="#relative">relative</a>(const path& p, 934 const path& base, system::error_code& ec); 935 936 bool <a href="#remove">remove</a>(const path& p); 937 bool <a href="#remove">remove</a>(const path& p, system::error_code& ec); 938 939 uintmax_t <a href="#remove_all">remove_all</a>(const path& p); 940 uintmax_t <a href="#remove_all">remove_all</a>(const path& p, system::error_code& ec); 941 942 void <a href="#rename">rename</a>(const path& from, const path& to); 943 void <a href="#rename">rename</a>(const path& from, const path& to, 944 system::error_code& ec); 945 946 void <a href="#resize_file">resize_file</a>(const path& p, uintmax_t size); 947 void <a href="#resize_file2">resize_file</a>(const path& p, uintmax_t size, 948 system::error_code& ec); 949 950 <a href="#space_info">space_info</a> <a href="#space">space</a>(const path& p); 951 <a href="#space_info">space_info</a> <a href="#space">space</a>(const path& p, system::error_code& ec); 952 953 <a href="#file_status">file_status</a> <a href="#status">status</a>(const path& p); 954 <a href="#file_status">file_status</a> <a href="#status">status</a>(const path& p, system::error_code& ec) noexcept; 955 956 bool <a href="#status_known">status_known</a>(file_status s) noexcept; 957 958 <a href="#file_status">file_status</a> <a href="#symlink_status">symlink_status</a>(const path& p); 959 <a href="#file_status">file_status</a> <a href="#symlink_status">symlink_status</a>(const path& p, 960 system::error_code& ec) noexcept; 961 962 path <a href="#system_complete">system_complete</a>(const path& p); 963 path <a href="#system_complete">system_complete</a>(const path& p, system::error_code& ec); 964 965 path <a href="#temp_directory_path">temp_directory_path</a>(); 966 path <a href="#temp_directory_path">temp_directory_path</a>(system::error_code& ec); 967 968 path <a href="#unique_path">unique_path</a>(const path& model="%%%%-%%%%-%%%%-%%%%"); 969 path <a href="#unique_path">unique_path</a>(const path& model, system::error_code& ec); 970 971 path <a href="#weakly_canonical">weakly_canonical</a>(const path& p); 972 path <a href="#weakly_canonical">weakly_canonical</a>(const path& p, system::error_code& ec); 973 974 } // namespace filesystem 975} // namespace boost</pre> 976 977 978 979<h2><a name="Error-reporting">Error reporting</a> [fs.err.report]</h2> 980<p>Filesystem library functions often provide two overloads, one that 981throws an exception to report file system errors, and another that sets an <code>error_code</code>.</p> 982<blockquote> 983<p>[<i>Note:</i> This supports two common use cases:</p> 984<ul> 985 <li> 986 <p>Uses where file system 987errors are truly exceptional and indicate a serious failure. Throwing an 988 exception is the most appropriate response. This is the preferred default for 989 most everyday programming.<br> 990 </li> 991 <li> 992 <p>Uses where file system errors are routine and do not necessarily represent 993 failure. Returning an error code is the most appropriate response. This allows 994 application specific error handling, including simply ignoring the error.</li> 995</ul> 996 <p><i>—end note</i>]</p> 997</blockquote> 998<p>Functions <b>not</b> having an argument of type <code>system::error_code&</code> report errors as follows, unless otherwise specified:</p> 999 <ul> 1000 <li> 1001 <p>When a call by the 1002 implementation to an operating system or other underlying API results in an 1003 error that prevents the function from meeting its specifications, an exception 1004 of type 1005<code>filesystem_error</code> is thrown.<br> 1006 </li> 1007 <li> 1008 <p>Failure to allocate storage is reported by throwing an exception as described in the C++ standard, 1009 17.6.4.10 [res.on.exception.handling].<br> 1010 </li> 1011 <li> 1012 <p>Destructors throw nothing.</li> 1013 </ul> 1014 <p>Functions having an argument of type <code>system::error_code&</code> report errors as follows, unless otherwise 1015 specified:</p> 1016<ul> 1017 <li> 1018 <p>If a call by the 1019 implementation to an operating system or other underlying API results in an 1020 error that prevents the function from meeting its specifications, the 1021<code>system::error_code&</code> argument is set as 1022 appropriate for the specific error. Otherwise, <code>clear()</code> 1023 is called on the 1024<code>system::error_code&</code> argument.<br> 1025 </li> 1026 <li> 1027 <p>Failure to allocate storage is reported by 1028 throwing an exception as described in the C++ standard, 1029 17.6.4.10 [res.on.exception.handling].</li> 1030</ul> 1031<h2><a name="class-path">Class <code>path</code> [class.path]</a></h2> 1032<p>An object of class <code>path</code> represents a <a href="#path">path</a>, 1033and contains a <a href="#pathname">pathname</a> Such an object is concerned only with the lexical and syntactic aspects 1034of a path. The path does not necessarily exist in external storage, and the 1035pathname is not necessarily valid for the current operating 1036system or for a particular file system.</p> 1037 1038<div dir="ltr"> 1039 1040<pre>namespace boost 1041{ 1042 namespace filesystem 1043 { 1044 class path 1045 { 1046 public: 1047 typedef <b><i><a href="#value_type">see below</a></i></b> value_type; 1048 typedef std::basic_string<value_type> string_type; 1049 typedef std::codecvt<wchar_t, char, std::mbstate_t> codecvt_type; 1050 constexpr value_type dot; 1051 constexpr value_type separator; 1052 constexpr value_type preferred_separator; 1053 1054 // <a href="#path-constructors">constructors</a> and destructor 1055 path(); 1056 path(const path& p); 1057 path(path&& p) noexcept; 1058 1059 template <class <a href="#Source">Source</a>> 1060 path(Source const& source, const codecvt_type& cvt=codecvt()); 1061 1062 template <class <a href="#InputIterator">InputIterator</a>> 1063 path(InputIterator begin, InputIterator end, 1064 const codecvt_type& cvt=codecvt()); 1065 1066 ~path(); 1067 1068 // <a href="#path-assignments">assignments</a> 1069 path& operator=(const path& p); 1070 path& operator=(path&& p) noexcept; 1071 1072 template <class <a href="#Source">Source</a>> 1073 path& operator=(Source const& source); 1074 1075 template <class <a href="#Source">Source</a>> 1076 path& assign(Source const& source, const codecvt_type& cvt) 1077 1078 template <class <a href="#InputIterator">InputIterator</a>> 1079 path& assign(InputIterator begin, InputIterator end, 1080 const codecvt_type& cvt=codecvt()); 1081 1082 // <a href="#path-appends">appends</a> 1083 path& operator/=(const path& p); 1084 1085 template <class <a href="#Source">Source</a>> 1086 path& operator/=(Source const& source); 1087 1088 template <class <a href="#Source">Source</a>> 1089 path& append(Source const& source, const codecvt_type& cvt); 1090 1091 template <class <a href="#InputIterator">InputIterator</a>> 1092 path& append(InputIterator begin, InputIterator end, 1093 const codecvt_type& cvt=codecvt()); 1094 1095 // <a href="#path-concatenation">concatenation</a> 1096 path& operator+=(const path& x); 1097 path& operator+=(const string_type& x); 1098 path& operator+=(const value_type* x); 1099 path& operator+=(value_type x); 1100 template <class Source> 1101 path& operator+=(Source const& x); 1102 template <class CharT> 1103 path& operator+=(CharT x); 1104 template <class Source> 1105 path& concat(Source const& x, const codecvt_type& cvt); 1106 template <class InputIterator> 1107 path& concat(InputIterator begin, InputIterator end); 1108 template <class InputIterator> 1109 path& concat(InputIterator begin, InputIterator end, 1110 const codecvt_type& cvt); 1111 1112 // <a href="#path-modifiers">modifiers</a> 1113 void <a href="#path-clear">clear</a>(); 1114 path& <a href="#path-make_preferred">make_preferred</a>(); 1115 path& <a href="#path-remove_filename">remove_filename</a>(); 1116 path& <a href="#path-replace_extension">replace_extension</a>(const path& new_extension = path()); 1117 void <a href="#path-swap">swap</a>(path& rhs); 1118 1119 // lexical operations 1120 path <a href="#lexically_normal">lexically_normal</a>() const; 1121 path <a href="#lexically_relative">lexically_relative</a>(const path& base) const; 1122 path <a href="#lexically_proximate">lexically_proximate</a>(const path& base) const; 1123 1124 // <a href="#path-native-format-observers">native format observers</a> 1125 const string_type& <a href="#native">native</a>() const noexcept; // native format, encoding 1126 const value_type* <a href="#c_str">c_str</a>() const noexcept; // native().c_str() 1127 string_type::size_type <a href="#path-size">size</a>() const noexcept; // native().size() 1128 1129 template <class String> 1130 String <a href="#string-template">string</a>(const codecvt_type& cvt=codecvt()) const; 1131 string <a href="#string">string</a>(const codecvt_type& cvt=codecvt()) const; 1132 wstring <a href="#wstring">wstring</a>(const codecvt_type& cvt=codecvt()) const; 1133 u16string <a href="#u16string">u16string</a>() const; 1134 u32string <a href="#u32wstring">u32string</a>() const; 1135 1136 // <a href="#path-generic-format-observers">generic format observers</a> 1137 template <class String> 1138 String <a href="#generic_string-template">generic_string</a>() const; 1139 1140 string <a href="#generic_string">generic_string</a>(const codecvt_type& cvt=codecvt()) const; 1141 wstring <a href="#generic_wstring">generic_wstring</a>(const codecvt_type& cvt=codecvt()) const; 1142 u16string <a href="#generic_u16string">generic_u16string</a>() 1143 u32string <a href="#generic_u32wstring">generic_u32string</a>() 1144 1145 // <a href="#path-compare">compare</a> 1146 int <a href="#path-compare">compare</a>(const path& p) const noexcept; 1147 int <a href="#path-compare">compare</a>(const std::string& s) const; 1148 int <a href="#path-compare">compare</a>(const value_type* s) const; 1149 1150 // <a href="#path-decomposition">decomposition</a> 1151 path <a href="#path-root_name">root_name</a>() const; 1152 path <a href="#path-root_directory">root_directory</a>() const; 1153 path <a href="#path-root_path">root_path</a>() const; 1154 path <a href="#path-relative_path">relative_path</a>() const; 1155 path <a href="#path-parent_path">parent_path</a>() const; 1156 path <a href="#path-filename">filename</a>() const; 1157 path <a href="#path-stem">stem</a>() const; 1158 path <a href="#path-extension">extension</a>() const; 1159 1160 // <a href="#path-query">query</a> 1161 bool <a href="#path-query">empty</a>() const; 1162 bool <a href="#filename_is_dot">filename_is_dot</a>() const; 1163 bool <a href="#filename_is_dot_dot">filename_is_dot_dot</a>() const; 1164 bool <a href="#path-has_root_name">has_root_name</a>() const; 1165 bool <a href="#path-has_root_directory">has_root_directory</a>() const; 1166 bool <a href="#path-has_root_path">has_root_path</a>() const; 1167 bool <a href="#path-has_relative_path">has_relative_path</a>() const; 1168 bool <a href="#path-has_parent_path">has_parent_path</a>() const; 1169 bool <a href="#path-has_filename">has_filename</a>() const; 1170 bool <a href="#path-has_stem">has_stem</a>() const; 1171 bool <a href="#path-has_extension">has_extension</a>() const; 1172 bool <a href="#path-is_absolute">is_absolute</a>() const; 1173 bool <a href="#path-is_relative">is_relative</a>() const; 1174 1175 // <a href="#path-iterators">iterators</a> 1176 class iterator; 1177 typedef iterator const_iterator; 1178 class reverse_iterator; 1179 typedef reverse_iterator const_reverse_iterator; 1180 1181 iterator begin() const; 1182 iterator end() const; 1183 reverse_iterator rbegin() const; 1184 reverse_iterator rend() const; 1185 1186 // <a href="#path-imbued-locale">imbued locale</a> 1187 static std::locale <a href="#path-imbue">imbue</a>(const std::locale& loc); 1188 static const codecvt_type & <a href="#path-codecvt">codecvt</a>(); 1189 1190 private: 1191 string_type pathname; // <b><i>exposition only</i></b> 1192 }; 1193 1194 } // namespace filesystem 1195} // namespace boost</pre> 1196 1197</div> 1198 1199<p><code><a name="value_type">value_type</a></code> is a <code>typedef</code> for the 1200character type used by the operating system to represent pathnames.</p> 1201 1202 1203<h3><a name="path-Usage"><code>path</code> Usage concerns</a> [path.usage]</h3> 1204 1205<h4>Multithreading concerns</h4> 1206 1207<p>Filesystem library functions are not protected against data races. [Modifying 1208an object of a Filesystem library type that is shared between threads risks 1209undefined behavior unless objects of that type are explicitly specified as being 1210sharable without data races or the user supplies a locking mechanism. <i>—end 1211note</i>] [<i>Note:</i> Thus the Filesystem library behaves as if it were part 1212of the standard library, and C++ standard 17.6.4.10 <i>Shared objects and the 1213library</i> [res.on.objects] would thus apply. <i>—end note</i>]</p> 1214 1215<h4>Windows concerns</h4> 1216 1217<p>Visual C++ at least through version 2012 does not employ C++11-style static 1218initialization locks, so the initialization of <code>path::codecvt()</code> can 1219race, either with itself or <code>path::imbue::()</code> if they are called from 1220a different thread. A workaround is to call:</p> 1221 1222<blockquote> 1223<p><code>path::codecvt(); // ensure VC++ does not race during 1224initialization.</code></p> 1225 1226</blockquote> 1227<p>in the main thread before launching any additional threads. [<i>Note:</i> The 1228obvious fix of the Filesystem implementation doing the locking doesn't work 1229because of unrelated problems with the Microsoft compiler; for static linking 1230the runtime tries to do the initialization before main() starts, but doesn't 1231permit operating system lock calls at that time. <i>—end note</i>]</p> 1232 1233<h4>POSIX concerns</h4> 1234 1235<p>Filesystem library initialization may throw an exception on POSIX 1236systems (e.g. Linux, but not Mac OS X) that use environmental variables to 1237determine the encoding of paths. This happens when <code>std::locale("")</code> 1238throws because an environmental variable such as LANG is set to an invalid 1239value, so it can affect any use of <code>std::locale("")</code>, not just 1240the Filesystem library. Filesystem uses lazy initialization so the exception is 1241only thrown if a valid <code>std::locale("")</code> is actually needed, and also 1242so that the exception is thrown after <code>main()</code> starts.</p> 1243 1244<p>Rather than waiting until a call to some Filesystem library function 1245unexpectedly triggers the exception when it calls <code>path::codecvt()</code>, 1246a program that needs be highly robust against environmental variable problems 1247may want to preemptively call <code>std::locale("")</code> within a try block, 1248catch the exception, and diagnose or repair the invalid environmental variable.</p> 1249 1250<h3><a name="path-Conversions"><code>path</code> Conversions</a> [path.cvt]</h3> 1251<h4><code>path</code> argument conversions [<a name="path.arg.convert">path.arg.cvt</a>]</h4> 1252<h5><a name="path-Conversions-to-native-format"><code>path</code> argument 1253format conversions</a> [path.arg.fmt.cvt]</h5> 1254<p>Member function arguments that take character sequences representing paths 1255may use the <a href="#generic-pathname-format">generic pathname format</a> or 1256the <a href="#native-pathname-format">native pathname format</a>. Iff such arguments 1257are in the generic format and the generic format is not acceptable to the 1258operating system as a native path, conversion to native format shall be performed 1259during the processing of the argument. See [<a href="#Operating-system-examples">fs.os.examples</a>].</p> 1260<blockquote> 1261<p>[<i>Note:</i> Depending on the operating system, there may be no unambiguous way for an implementation to 1262always be able to distinguish between native format and generic format arguments. 1263This is by design as it simplifies use for operating systems that do not require 1264disambiguation. Should an implementation encounter an 1265operating system where disambiguation is required, an implementation can defined 1266an extension to distinguish between the formats. <i> 1267—end note</i>]</p> 1268</blockquote> 1269 1270<p>If the native format requires 1271paths for regular files to be formatted differently from paths for directories, the 1272path shall be treated as a directory path if last element is a separator, 1273otherwise it shall be treated as a regular file path.</p> 1274 1275<h5><a name="path-Encoding-conversions"><code> 1276path</code> argument encoding conversions</a> 1277[path.arg.encoding.cvt]</h5> 1278<p>For member function arguments that take character sequences representing 1279paths, if the value type of the argument is not <code>value_type and </code>one 1280of the value types is <code>char</code> and the other is <code>wchar_t</code>, conversion to <code>value_type</code> 1281shall be performed by the <code>path::codecvt()</code> facet. ([<a href="#path-imbued-locale">path.imbued.locale</a>]).</p> 1282<h4><a name="path-Conversions-to-generic-format"><code>path</code> Conversions 1283to generic format</a> [fs.cvt.to.generic]</h4> 1284<p><a href="#path-generic-format-observers">Generic format observer</a> functions 1285shall return strings formatted according to the <a href="#generic-pathname-format">generic pathname format</a> 1286using <i>preferred-separator</i>. See [<a href="#Operating-system-examples">fs.os.examples</a>].</p> 1287<h3><a name="path-Requirements"><code>path</code> Requirements</a> [path.req]</h3> 1288<p>Template parameters named <code><a name="InputIterator">InputIterator</a></code> are required meet the 1289requirements for a C++ standard library <code>RandomIterator</code> compliant iterator. The iterator's value type is required to be <code>char</code>, <code>wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.</p> 1290<p>Template parameters named <code><a name="Source">Source</a></code> are required to be one of:</p> 1291<ul> 1292 <li> 1293 <p>A container with a value type of <code>char</code>, <code> 1294 wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.</li> 1295 <li> 1296 <p>An iterator for a null terminated byte-string. The value type is required 1297 to be <code>char</code>, <code>wchar_t</code>, <code>char16_t</code>, or <code> 1298 char32_t</code>.</li> 1299 <li> 1300 <p>A C-array. The value type is required to be <code>char</code>, <code> 1301 wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.</li> 1302 <li> 1303 <p>A <code>boost::filesystem::directory_entry</code>.</li> 1304</ul> 1305 1306<h3> <a name="path-constructors"> <code> 1307<font size="4">path</font></code> constructors</a> [path.construct]</h3> 1308 1309<pre>template <class <a href="#Source">Source</a>> 1310 path(Source const& source, const codecvt_type& cvt=codecvt());</pre> 1311 1312 1313<pre>template <class <a href="#InputIterator">InputIterator</a>> 1314 path(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());</pre> 1315 1316<blockquote> 1317 <p><i>Effects:</i> Stores the contents [<code>begin</code>,<code>end</code>) 1318 or <code>source</code> in <code>pathname</code>, converting format and 1319 encoding if required ([<a href="#path.arg.convert">path.arg.convert</a>]).</p> 1320</blockquote> 1321<h3> <a name="path-assignments"> <code> 1322<font size="4">path</font></code> assignments</a> [path.assign]</h3> 1323 1324<pre>template <class <a href="#Source">Source</a>> 1325 path& operator=(Source const& source); 1326 template <class <a href="#Source">Source</a>> 1327 path& assign(Source const& source, const codecvt_type& cvt); 1328 template <class <a href="#InputIterator">InputIterator</a>> 1329 path& assign(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());</pre> 1330 1331<blockquote> 1332 <p><i>Effects:</i> Stores the contents [<code>begin</code>,<code>end</code>) 1333 or <code>source</code> in <code>pathname</code>, converting format and 1334 encoding if required ([<a href="#path.arg.convert">path.arg.convert</a>]). </p> 1335 <p> 1336 <i>Returns: </i><code>*this</code></p> 1337 </blockquote> 1338<h3><a name="path-appends"><code><font size="4"> path</font></code> appends</a> 1339[path.append]</h3> 1340 <p>The append operations use <code> 1341 operator/=</code> to denote their semantic effect of appending <i> 1342 preferred-separator</i> when needed. </p> 1343 1344<pre>path& operator/=(const path& p);</pre> 1345 1346<blockquote> 1347 <p><i>Effects:</i></p> 1348 <blockquote> 1349 <p>Appends <code>path::preferred_separator</code> to <code>pathname</code>, 1350 converting format and encoding if required ([<a href="#path.arg.convert">path.arg.convert</a>]), unless:</p> 1351 <ul> 1352 <li> 1353 <p>an added separator 1354 would be redundant, or</li> 1355 <li> 1356 <p>would change a relative path to an absolute path, or</li> 1357 <li> 1358 <p><code>p.empty()</code>, or</li> 1359 <li> 1360 <p><code>*p.native().cbegin()</code> is a directory separator.</li> 1361 </ul> 1362 <p>Then appends <code>p.native()</code> to <code>pathname</code>.</p> 1363 </blockquote> 1364 <p><i>Returns: </i><code>*this</code></p> 1365</blockquote> 1366 1367<pre>template <class <a href="#Source">Source</a>> 1368 path& operator/=(Source const & source); 1369 template <class <a href="#Source">Source</a>> 1370 path& append(Source const & source, const codecvt_type& cvt); 1371 template <class <a href="#InputIterator">InputIterator</a>> 1372 path& append(InputIterator begin, InputIterator end, const codecvt_type& cvt=codecvt());</pre> 1373 1374<blockquote> 1375 <p><i>Effects:</i></p> 1376 <blockquote> 1377 <p>Appends <code>path::preferred_separator</code> to <code>pathname</code>, converting 1378 format and encoding if required ([<a href="#path.arg.convert">path.arg.convert</a>]), unless:</p> 1379 <ul> 1380 <li> 1381 <p>an added separator 1382 would be redundant, or</li> 1383 <li> 1384 <p>would change a relative path to an absolute path, or</li> 1385 <li> 1386 <p><code>p.empty()</code>, or</li> 1387 <li> 1388 <p><code>*p.native().cbegin()</code> is a separator.</li> 1389 </ul> 1390 <p>Appends the contents [<code>begin</code>,<code>end</code>) 1391 or <code>source</code> to <code>pathname</code>, converting format and 1392 encoding if required ([<a href="#path.arg.convert">path.arg.convert</a>]).</p> 1393 </blockquote> 1394 <p><i>Returns: </i><code>*this</code></p> 1395 </blockquote> 1396 1397<h3><a name="path-concatenation"><code>path</code> concatenation</a> [path.concat]</h3> 1398 1399<pre>path& operator+=(const path& x); 1400path& operator+=(const string_type& x); 1401path& operator+=(const value_type* x); 1402path& operator+=(value_type x); 1403template <class Source> 1404 path& operator+=(Source const& x); 1405template <class CharT> 1406 path& operator+=(CharT x); 1407template <class InputIterator> 1408 path& concat(InputIterator begin, InputIterator end); 1409template <class InputIterator> 1410 path& concat(InputIterator begin, InputIterator end, const codecvt_type& cvt);</pre> 1411 1412<blockquote><p><i>Postcondition:</i> <code>native() == prior_native + <i>effective-argument</i></code>, 1413 where <code>prior_native</code> is <code>native()</code> prior to the call to <code>operator+=</code>, 1414 and <code><i>effective-argument</i></code> is:</p> 1415 <ul><li> 1416 <p><code>x.native()</code> if <code>x</code> is present and is <code>const path&</code>, otherwise</li> 1417 <li> 1418 <p><code>s</code>, where <code>s</code> is 1419 <code>std::basic_string<typename std::iterator_traits<InputIterator>::value_type><br>s(begin, end)</code>, 1420 if <code>begin</code> and <code>end</code> arguments are present, otherwise</li> 1421 <li> 1422 <p><code>x</code>.</li></ul><p>If the value type of <code><i>effective-argument</i></code> would not be <code>path::value_type</code>, the actual argument or argument range is first 1423 converted so that <code><i>effective-argument</i></code> has value type <code>path::value_type</code>.</li> </p> 1424 <p><i>Returns: </i><code>*this</code></p> 1425 </blockquote> 1426<h3><a name="path-modifiers"> <code> 1427path</code> modifiers</a> [path.modifiers]</h3> 1428 1429 <pre>void <a name="path-clear">clear</a>();</pre> 1430 1431<blockquote> 1432<p><i>Postcondition:</i> <code>this->empty()</code> is true.</p> 1433</blockquote> 1434 1435<pre>path& <a name="path-make_preferred">make_preferred</a>();</pre> 1436 1437<blockquote> 1438 <p><i>Effects:</i> <i>directory-separator</i>s are converted to <i>preferred-separator</i>s. 1439 See [<a href="#Operating-system-examples">fs.os.examples</a>].</p> 1440 <p><i>Returns:</i> <code>*this</code></p> 1441</blockquote> 1442 1443 1444 1445<pre>path& <a name="path-remove_filename">remove_filename</a>();</pre> 1446 1447<blockquote> 1448 <p><i>Returns: </i>As if, <code>*this = parent_path();</code></p> 1449 <p>[<i>Note:</i> This function is needed to efficiently implement <code>directory_iterator</code>. It is exposed to allow additional uses. The actual 1450 implementation may be much more efficient than <code>*this = parent_path()</code> <i>—end 1451 note</i>]</p> 1452</blockquote> 1453 1454<pre>path& <a name="path-replace_extension">replace_extension</a>(const path& new_extension = path());</pre> 1455 1456<blockquote> 1457 <p><i>Effects:</i></p> 1458 <ul> 1459 <li> 1460 <p>Any existing <code>extension()</code> is removed from the stored path, 1461 then</li> 1462 <li> 1463 <p>iff 1464 <code>new_extension</code> is not empty and does not begin with a dot 1465 character, a dot character is appended to the stored path, then</li> 1466 <li> 1467 <p> 1468 <code>new_extension</code> is appended to the stored path.</li> 1469 </ul> 1470 <p><i>Returns:</i> <code>*this</code></p> 1471</blockquote> 1472 1473<pre><code>void <a name="path-swap">swap</a>(path& rhs) noexcept;</code></pre> 1474 1475<blockquote> 1476 <p><i>Effects:</i> Swaps the contents of the two paths.</p> 1477 <p><i>Complexity: </i>constant time.</p> 1478</blockquote> 1479 1480 <h3><a name="path-lexical-operations"><code>path</code> lexical operations</a> 1481 [path.lex.ops]</h3> 1482 <pre>path <a name="lexically_normal">lexically_normal</a>() const;</pre> 1483<blockquote> 1484<p><i>Overview:</i> Returns <code>*this</code> with redundant current directory 1485(<i>dot</i>), parent directory (<i>dot-dot</i>), and <i>directory-separator</i> elements removed.</p> 1486<p><i>Returns:</i> <code>*this</code> in <a href="#normal-form">normal form</a>.</p> 1487<p><i>Remarks:</i> Uses <code>operator/=</code> to compose the returned path.</p> 1488<p>[<i>Example:</i></p> 1489<p><code>assert(path("foo/./bar/..").lexically_normal() == "foo");<br> 1490assert(path("foo/.///bar/../").lexically_normal() == "foo/.");</code></p> 1491<p>The above assertions will succeed.<i> </i>On Windows, the 1492returned path's <i>directory-separator</i> characters will be backslashes rather than slashes, but that 1493does not affect <code>path</code> equality.<i> —end example</i>]</p> 1494</blockquote> 1495 1496<pre>path <a name="lexically_relative">lexically_relative</a>(const path& base) const;</pre> 1497 <blockquote> 1498 <p><i>Overview:</i> Returns <code>*this</code> made relative to <code>base</code>. 1499 Treats empty or identical paths as corner cases, not errors. Does not resolve 1500 symlinks. Does not first normalize <code>*this</code> or <code>base</code>.</p> 1501 1502 <p><i>Remarks:</i> Uses <code>std::mismatch(begin(), end(), base.begin(), base.end())</code>, to determine the first mismatched element of 1503 <code>*this</code> and <code>base</code>. Uses <code>operator==</code> to 1504 determine if elements match. </p> 1505 1506 <p><i>Returns:</i> </p> 1507 1508 <ul> 1509 <li> 1510 <code>path()</code> if the first mismatched element of <code>*this</code> is equal to <code> 1511 begin()</code> or the first mismatched element 1512 of <code>base</code> is equal to <code>base.begin()</code>, or<br> 1513 </li> 1514 <li> 1515 <code>path(".")</code> if the first mismatched element of <code> 1516 *this</code> is equal to <code> 1517 end()</code> and the first mismatched element 1518 of <code>base</code> is equal to <code>base.end()</code>, or<br> 1519 </li> 1520 <li>An object of class <code>path</code> composed via application of <code> 1521 operator/= path("..")</code> for each element in the half-open 1522 range [first 1523 mismatched element of <code>base</code>, <code>base.end()</code>), and then 1524 application of <code>operator/=</code> for each element in the half-open 1525 range 1526 [first mismatched element of <code>*this</code>, <code>end()</code>). 1527 </li> 1528</ul> 1529 1530<p>[<i>Example:</i></p> 1531<p><code>assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");<br> 1532assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");<br> 1533assert(path("a/b/c").lexically_relative("a") == "b/c");<br> 1534assert(path("a/b/c").lexically_relative("a/b/c/x/y") == "../..");<br> 1535assert(path("a/b/c").lexically_relative("a/b/c") == ".");<br> 1536assert(path("a/b").lexically_relative("c/d") == "");</code></p> 1537<p>The above assertions will succeed.<i> </i>On Windows, the 1538returned path's <i>directory-separator</i>s will be backslashes rather than 1539forward slashes, but that 1540does not affect <code>path</code> equality.<i> —end example</i>]</p> 1541 1542 <p>[<i>Note:</i> If symlink following semantics are desired, use the operational function <code> 1543 <a href="#relative">relative</a></code> <i>—end note</i>]</p> 1544 1545 <p>[<i>Note:</i> If <a href="#lexically_normal">normalization</a> is needed to ensure 1546 consistent matching of elements, apply <code><a href="#lexically_normal">lexically_normal()</a></code> 1547 to <code>*this</code>, <code>base</code>, or both. <i>—end note</i>]</p> 1548 1549<pre>path <a name="lexically_proximate">lexically_proximate</a>(const path& base) const;</pre> 1550<blockquote> 1551<p><i>Returns:</i> If <code>lexically_relative(base)</code> returns a non-empty path, returns that path. 1552Otherwise returns <code>*this</code>.</p> 1553 1554 <p>[<i>Note:</i> If symlink following semantics are desired, use the operational function <code> 1555 <a href="#relative">relative</a></code> <i>—end note</i>]</p> 1556 1557 <p>[<i>Note:</i> If <a href="#lexically_normal">normalization</a> is needed to ensure 1558 consistent matching of elements, apply <code><a href="#lexically_normal">lexically_normal()</a></code> 1559 to <code>*this</code>, <code>base</code>, or both. <i>—end note</i>]</p> 1560 1561</blockquote> 1562 1563 1564<h3> <a name="path-native-format-observers"><code><font size="4">path</font></code> native format observers</a> 1565[path.native.obs]</h3> 1566<p>The string returned by all native format observers is in the <a href="#native-pathname-format">native pathname format</a>.</p> 1567 1568<pre>const string_type& <a name="native">native</a>() const noexcept;</pre> 1569 1570<blockquote> 1571<p><i>Returns:</i> <code>pathname</code>.</p> 1572</blockquote> 1573 1574<pre>const value_type* <a name="c_str">c_str</a>() const noexcept;</pre> 1575 1576<blockquote> 1577<p><i>Returns:</i> <code>pathname.c_str()</code>.</p> 1578</blockquote> 1579 1580<pre>string_type::size_type <a name="path-size">size</a>() const noexcept;</pre> 1581 1582<blockquote> 1583<p><i>Returns:</i> <code>pathname.size()</code>.</p> 1584</blockquote> 1585 1586<pre>template <class String> 1587String <a name="string-template">string</a>(const codecvt_type& cvt=codecvt()) const;</pre> 1588 1589<blockquote> 1590 <p><i>Returns:</i> <code>pathname</code>.</p> 1591<p><i>Remarks:</i> If <code>string_type</code> is a different type than <code>String</code>, conversion is performed by <code>cvt</code>.</p> 1592</blockquote> 1593 1594<pre>string <a name="string">string</a>(const codecvt_type& cvt=codecvt()) const; 1595wstring <a name="wstring">wstring</a>(const codecvt_type& cvt=codecvt()) const; 1596u16string <a name="u16string">u16string</a>() const; 1597u32wstring <a name="u32wstring">u32wstring</a>() const; </pre> 1598 1599<blockquote> 1600<p><i>Returns:</i> <code>pathname</code>.</p> 1601<p><i>Remarks:</i> If <code>string_type</code> is a different type than 1602function's return type, conversion is performed by <code>cvt</code>.</p> 1603</blockquote> 1604 1605<h3> <a name="path-generic-format-observers"><code><font size="4">path</font></code> generic format observers</a> 1606[path.generic.obs]</h3> 1607<p>The string returned by all generic format observers is in the <a href="#generic-pathname-format">generic pathname format</a>.</p> 1608 1609<pre>template <class String> 1610String <a name="generic_string-template">generic_string</a>(const codecvt_type& cvt=codecvt()) const;</pre> 1611 1612<blockquote> 1613 <p><i>Returns:</i> <code>pathname</code>.</p> 1614<p><i>Remarks:</i> If <code>string_type</code> is a different type than <code>String</code>, conversion is performed by <code>cvt</code>.</p> 1615</blockquote> 1616 1617<pre>string <a name="generic_string">generic_string</a>(const codecvt_type& cvt=codecvt()) const; 1618wstring <a name="generic_wstring">generic_wstring</a>(const codecvt_type& cvt=codecvt()) const; 1619u16string <a name="generic_u16string">generic_u16string</a>() const; 1620u32wstring <a name="generic_u32wstring">generic_u32wstring</a>() const; </pre> 1621 1622<blockquote> 1623<p><i>Returns:</i> <code>pathname</code>.</p> 1624<p><i>Remarks:</i> If <code>string_type</code> is a different type than 1625function's return type, conversion is performed by <code>cvt</code>.</p> 1626</blockquote> 1627 1628<h3> <a name="path-compare"><code>path</code> compare</a> [path.compare]</h3> 1629 1630<pre>int compare(const path& p) const noexcept;</pre> 1631 1632<blockquote> 1633 <p><i>Returns:</i> A value less than 0 if the elements of <code>*this</code> are lexicographically less than the elements of <code>p</code>, otherwise a 1634 value greater than 0 if the elements of <code>*this</code> are 1635 lexicographically greater than the elements of <code>p</code>, otherwise 0.</p> 1636 <p>Remark: The elements are determined as if by iteration over the half-open 1637 range [<code>begin()</code>, <code>end()</code>) for <code>*this</code> and <code>p</code>.</p> 1638</blockquote> 1639 1640<pre>int compare(const std::string& s) const</pre> 1641 1642<blockquote> 1643 <p><i>Returns:</i> <code>compare(path(s))</code>.</p> 1644</blockquote> 1645 1646<pre>int compare(const value_type* s) const</pre> 1647 1648<blockquote> 1649 <p><i>Returns:</i> <code>compare(path(s))</code>.</p> 1650</blockquote> 1651<h3> <a name="path-decomposition"> <code><font size="4">path</font></code> decomposition</a> 1652[path.decompose]</h3> 1653<p><span style="background-color: #E0E0E0"><i>See the <a href="#path-decomposition-table">Path decomposition table</a> for examples 1654for values returned by decomposition functions. The <a href="tutorial.html#Using-path-decomposition">Tutorial</a> may also be 1655helpful.</i></span></p> 1656 1657<pre>path <a name="path-root_name">root_name</a>() const;</pre> 1658 1659<blockquote> 1660<p><i>Returns:</i> <i>root-name,</i> if <code>pathname</code> includes <i>root-name</i>, otherwise <code>path()</code>. </p> 1661</blockquote> 1662 1663<pre>path <a name="path-root_directory">root_directory</a>() const;</pre> 1664 1665<blockquote> 1666<p><i>Returns:</i> <i>root-directory</i>, if <code>pathname</code> includes <i>root-directory</i>, otherwise <code>path()</code>.</p> 1667<p>If <i>root-directory</i> is composed of <i>slash name</i>, <i>slash</i> is 1668excluded from the returned string.</p> 1669</blockquote> 1670 1671<pre>path <a name="path-root_path">root_path</a>() const;</pre> 1672 1673<blockquote> 1674 <p><i>Returns:</i> <code>root_name() / root_directory()</code></p> 1675</blockquote> 1676 1677<pre>path <a name="path-relative_path">relative_path</a>() const;</pre> 1678 1679<blockquote> 1680<p><i>Returns:</i> A <code>path</code> composed from <code>pathname</code>, if <code>!empty()</code>, beginning 1681with the first <i>filename</i> after <i>root-path</i>. Otherwise, <code>path()</code>.</p> 1682</blockquote> 1683 1684<pre>path <a name="path-parent_path">parent_path</a>() const;</pre> 1685 1686<blockquote> 1687 <p><i>Returns:</i> <code>(empty() || begin() == —end()) ? path() : <i>pp</i></code>, where <code><i>pp</i></code> is constructed as if by 1688 starting with an empty <code>path</code> and successively applying <code>operator/=</code> for each element in the range <code>begin()</code>, <code>—end()</code>.</p> 1689 <p>[<i>Example:</i></p> 1690 <blockquote> 1691 1692 <pre>std::cout << path("/foo/bar.txt").parent_path(); // outputs "/foo" 1693std::cout << path("/foo/bar").parent_path(); // outputs "/foo" 1694std::cout << path("/foo/bar/").parent_path(); // outputs "/foo/bar" 1695std::cout << path("/").parent_path(); // outputs "" 1696std::cout << path(".").parent_path(); // outputs "" 1697std::cout << path("..").parent_path(); // outputs ""</pre> 1698 1699 </blockquote> 1700 <p> See the last bullet item in the <a href="#path-iterators"> 1701 forward traversal order</a> list for why the <code>"/foo/bar/"</code> example 1702 doesn't output <code>"/foo"</code>.</p> 1703 <p> <i>—end example</i>]</p> 1704</blockquote> 1705 1706<pre>path <a name="path-filename">filename</a>() const;</pre> 1707 1708<blockquote> 1709 <p><i>Returns:</i> <code>empty() ? path() : *—end()</code></p> 1710 <p>[<i>Example:</i></p> 1711 <blockquote> 1712 1713 <pre>std::cout << path("/foo/bar.txt").filename(); // outputs "bar.txt" 1714std::cout << path("/foo/bar").filename(); // outputs "bar" 1715std::cout << path("/foo/bar/").filename(); // outputs "." 1716std::cout << path("/").filename(); // outputs "/" 1717std::cout << path(".").filename(); // outputs "." 1718std::cout << path("..").filename(); // outputs ".."</pre> 1719 1720 </blockquote> 1721 <p> See the last bullet item in the <a href="#path-iterators"> 1722 forward traversal order</a> list for why the <code>"/foo/bar/"</code> example 1723 doesn't output <code>"bar"</code>.</p> 1724 <p> <i>—end example</i>]</p> 1725</blockquote> 1726 1727<pre>path <a name="path-stem">stem</a>() const;</pre> 1728 1729<blockquote> 1730 <p><i>Returns:</i> if <code>p.filename()</code> contains a dot but does not 1731 consist solely of one or to two dots, returns 1732 the substring of <code>p.filename()</code> starting at its beginning and 1733 ending at the last dot (the dot is not included). Otherwise, 1734 returns <code>p.filename()</code>.</p> 1735 <p>[<i>Example:</i></p> 1736 <blockquote> 1737 1738 <pre><code>std::cout << path("/foo/bar.txt").stem();</code> // outputs "<code>bar</code>" 1739path p = "foo.bar.baz.tar"; 1740for (; !p.extension().empty(); p = p.stem()) 1741 std::cout << p.extension() << '\n'; 1742 // outputs: .tar 1743 // .baz 1744 // .bar</pre> 1745 1746 </blockquote> 1747 <p> <i>—end example</i>]</p> 1748</blockquote> 1749 1750<pre>path <a name="path-extension">extension</a>() const;</pre> 1751 1752<blockquote> 1753 <p><i>Returns:</i> if <code>p.filename()</code> contains a dot but does not 1754 consist solely of one or to two dots, returns 1755 the substring of <code>p.filename()</code> starting at the rightmost dot 1756 and ending at the path's end. Otherwise, returns an empty <code>path</code> object. </p> 1757 <p><i>Remarks:</i> Implementations are permitted but not required to define additional 1758 behavior for file systems which append additional elements to extensions, such 1759 as alternate data streams or partitioned dataset names.</p> 1760 <p>[<i>Example:</i></p> 1761 <blockquote> 1762 1763 <pre><code>std::cout << path("/foo/bar.txt").extension(); //</code> outputs "<code>.txt</code>"</pre> 1764 1765 </blockquote> 1766 <p> <i>—end example</i>]</p> 1767 <p>[<i>Note:<b> </b></i>The dot is included in the return value so that it is 1768 possible to distinguish between no extension and an empty extension. 1769 See <a href="https://lists.boost.org/Archives/boost/2010/02/162028.php"> 1770 https://lists.boost.org/Archives/boost/2010/02/162028.php</a> for more 1771 extensive rationale. <i>—end note</i>]</p> 1772</blockquote> 1773<h3> <a name="path-query"> <code><font size="4">path</font></code> query</a> [path.query]</h3> 1774 1775<pre>bool <a name="path-empty">empty</a>() const;</pre> 1776 1777<blockquote> 1778 <p><i>Returns:</i> <code>m_pathname.empty()</code>.</p> 1779</blockquote> 1780 1781<pre>bool <a name="filename_is_dot">filename_is_dot</a>() const;</pre> 1782 1783<blockquote> 1784 <p><i>Returns:</i> <code>filename() == path(".")</code></p> 1785 <p>[<i>Example:</i></p> 1786 <blockquote> 1787 1788 <pre>std::cout << path(".").filename_is_dot(); // outputs 1 1789std::cout << path("/.").filename_is_dot(); // outputs 1 1790std::cout << path("foo/.").filename_is_dot(); // outputs 1 1791std::cout << path("foo/").filename_is_dot(); // outputs 1 1792std::cout << path("/").filename_is_dot(); // outputs 0 1793std::cout << path("/foo").filename_is_dot(); // outputs 0 1794std::cout << path("/foo.").filename_is_dot(); // outputs 0 1795std::cout << path("..").filename_is_dot(); // outputs 0</pre> 1796 1797 </blockquote> 1798 <p> See the last bullet item in the <a href="#path-iterators">forward traversal order</a> 1799 list for why <code>path("foo/").filename()</code> is a dot filename.</p> 1800 <p> <i>—end example</i>]</p> 1801</blockquote> 1802 1803<pre>bool <a name="filename_is_dot_dot">filename_is_dot_dot</a>() const;</pre> 1804 1805<blockquote> 1806 <p><i>Returns:</i> <code>filename() == path("..")</code></p> 1807</blockquote> 1808 1809<pre>bool <a name="path-has_root_path">has_root_path</a>() const;</pre> 1810 1811<blockquote> 1812 <p><i>Returns:</i> <code>!<a href="#path-root_path">root_path</a>().empty()</code></p> 1813</blockquote> 1814 1815<pre>bool <a name="path-has_root_name">has_root_name</a>() const;</pre> 1816 1817<blockquote> 1818 <p><i>Returns:</i> <code>!<a href="#path-root_name">root_name</a>().empty()</code></p> 1819</blockquote> 1820 1821<pre>bool <a name="path-has_root_directory">has_root_directory</a>() const;</pre> 1822 1823<blockquote> 1824 <p><i>Returns:</i> <code>!<a href="#path-root_directory">root_directory</a>().empty()</code></p> 1825</blockquote> 1826 1827<pre>bool <a name="path-has_relative_path">has_relative_path</a>() const;</pre> 1828 1829<blockquote> 1830 <p><i>Returns:</i> <code>!<a href="#path-has_relative_path">relative_path</a>().empty()</code></p> 1831</blockquote> 1832 1833<pre>bool <a name="path-has_parent_path">has_parent_path</a>() const;</pre> 1834 1835<blockquote> 1836 <p><i>Returns:</i> <code>!<a href="#path-parent_path">parent_path</a>().empty()</code></p> 1837</blockquote> 1838 1839<pre>bool <a name="path-has_filename">has_filename</a>() const;</pre> 1840 1841<blockquote> 1842 <p><i>Returns:</i> <code>!<a href="#path-filename">filename</a>().empty()</code></p> 1843</blockquote> 1844 1845<pre>bool <a name="path-has_stem">has_stem</a>() const;</pre> 1846 1847<blockquote> 1848 <p><i>Returns:</i> <code>!<a href="#path-stem">stem</a>().empty()</code></p> 1849</blockquote> 1850 1851<pre>bool <a name="path-has_extension">has_extension</a>() const;</pre> 1852 1853<blockquote> 1854 <p><i>Returns:</i> <code>!<a href="#path-has_extension">extension</a>().empty()</code></p> 1855</blockquote> 1856 1857<pre>bool <a name="path-is_absolute">is_absolute</a>() const;</pre> 1858 1859<blockquote> 1860 <p><i>Returns:</i> <code>true</code> if the elements of <code>root_path()</code> uniquely identify a directory, else <code>false</code>.</p> 1861</blockquote> 1862 1863<pre>bool <a name="path-is_relative">is_relative</a>() const;</pre> 1864 1865<blockquote> 1866 <p><i>Returns:</i> <code>!is_absolute()</code>.</p> 1867</blockquote> 1868<h3> <a name="path-iterators"> <code> 1869<font size="4">path</font></code> iterators</a> [path.itr]</h3> 1870<p> Path iterators <code>iterator</code>, <code>const_iterator</code>, 1871<code>reverse_iterator</code>, and <code>const_reverse_iterator</code> iterate over the elements of the stored pathname.</p> 1872<p> Path iterators are constant iterators satisfying 1873the requirements of a bidirectional iterator (C++ Std, 24.1.4 Bidirectional 1874iterators [lib.bidirectional.iterators]). The <code>value_type</code> of 1875an iterator is <code>path</code>.</p> 1876 <blockquote> 1877<p> [<i>Note:</i> Path iterators store their value objects internally 1878and when dereferenced return references to those internal objects. They cannot 1879be used with iterator adaptors such as <code>std::reverse_iterator</code> that 1880assume references obtained by dereferencing an iterator point to objects that 1881out-live the iterator itself. <i>—end note</i>] </p> 1882</blockquote> 1883 <p>Calling any non-const member function of a <code>path</code> object 1884 invalidates all iterators referring to elements of that object.</p> 1885<p> The forward traversal order is as follows:</p> 1886<ul> 1887 <li>The <i>root-name</i> element, if present.</li> 1888 <li>The <i>root-directory</i> element, if present, in the generic format. <i> 1889 [note:</i> the generic format is required to ensure lexicographical 1890 comparison works correctly. <i>—end note</i>]</li> 1891 <li>Each successive <i>filename</i> element, if present.</li> 1892 <li><i>Dot</i>, if one or more trailing non-root <i>slash</i> 1893 characters are present.|</li> 1894</ul> 1895 <blockquote> 1896 <p>[<i>Note:</i> Treating the last element during iteration as <i>dot</i> when 1897 there is a trailing directory separator enables lexical (i.e. syntactic) 1898 distinction between paths to directories versus paths to regular files. Such a 1899 distinction is usually irrelevant on POSIX and Windows based operating 1900 systems, but may be a requirement on other operating systems. <i>—end note</i>]</p> 1901 </blockquote> 1902 <p>The backward traversal order is the reverse of forward traversal.</p> 1903 <pre>iterator begin() const;</pre> 1904<blockquote> 1905 <p><i>Returns:</i> An iterator for the first element in forward traversal 1906 order. If no elements are present, the end iterator.</p> 1907</blockquote> 1908<pre>iterator end() const;</pre> 1909<blockquote> 1910 <p><i>Returns:</i> The end iterator.</p> 1911</blockquote> 1912 <pre>reverse_iterator rbegin() const;</pre> 1913<blockquote> 1914 <p><i>Returns:</i> An iterator for the first element in backward traversal 1915 order. If no elements are present, the end iterator.</p> 1916</blockquote> 1917<pre>reverse_iterator rend() const;</pre> 1918<blockquote> 1919 <p><i>Returns:</i> The end iterator.</p> 1920</blockquote> 1921 <h3><a name="path-imbued-locale"><code><font size="4"> path</font></code> 1922 imbued locale</a> [path.imbued.locale]</h3> 1923 <p><code>path</code> operations sometimes require encoding conversions between 1924 <code>pathname</code> and some other string object where one of the value types 1925 is <code>char</code> and the other is <code>wchar_t</code>. Such conversions 1926 shall be performed by the <code>path::codecvt()</code> facet.</p> 1927 <blockquote> 1928 <p><span style="background-color: #FFFF00">[</span><i><span style="background-color: #FFFF00">Example:</span></i><span style="background-color: #FFFF00"> 1929 ... </span><i><span style="background-color: #FFFF00">—end example</span></i><span style="background-color: #FFFF00">]</span></p> 1930 </blockquote> 1931 <pre>static std::locale <a name="path-imbue">imbue</a>(const std::locale& loc);</pre> 1932<blockquote> 1933 <p><i>Effects:</i> Stores a copy of <code>loc</code> as the imbued <code>path</code> 1934 locale.</p> 1935 <p><i>Returns:</i> The previous imbued <code>path</code> locale.</p> 1936 <p><i>Remarks:</i> The initial value of the imbued <code>path</code> locale is 1937 operating system dependent. It shall be a locale with a <code>codecvt</code> 1938 facet for a <code>char</code> string encoding appropriate for the operating 1939 system. See ([<a href="#Operating-system-examples">fs.os.examples</a>]). </p> 1940</blockquote> 1941<pre>static const codecvt_type& <a name="path-codecvt">codecvt</a>();</pre> 1942<blockquote> 1943 <p><i>Returns:</i> The <code>codecvt</code> facet for the imbued<code> path</code> 1944 locale .</p> 1945</blockquote> 1946 1947 1948<h3> <a name="path-deprecated-functions"><code><font size="4"> path</font></code> deprecated functions</a></h3> 1949<p> Several member functions from previous versions of <code>class path</code> have been deprecated, either because they have been renamed or because the 1950functionality is no longer desirable or has become obsolete.</p> 1951<p> Deprecated functions available by default; will be suppressed if <code>BOOST_FILESYSTEM_NO_DEPRECATED</code> is defined:</p> 1952<blockquote> 1953 <pre>path& remove_leaf() { return remove_filename(); } 1954path leaf() const { return filename(); } 1955path branch_path() const { return parent_path(); } 1956bool has_leaf() const { return !m_path.empty(); } 1957bool has_branch_path() const { return !parent_path().empty(); }</pre> 1958</blockquote> 1959<p> Deprecated functions not available by default; will be supplied if <code>BOOST_FILESYSTEM_DEPRECATED</code> is defined:</p> 1960<blockquote> 1961<pre>const std::string file_string() const { return native_string(); } 1962const std::string directory_string() const { return native_string(); } 1963const std::string native_file_string() const { return native_string(); } 1964const std::string native_directory_string() const { return native_string(); } 1965const string_type external_file_string() const { return native(); } 1966const string_type external_directory_string() const { return native(); }</pre> 1967</blockquote> 1968 1969<h3> <a name="path-non-member-functions"> <code><font size="4">path</font></code> non-member functions</a> 1970[path.non-member]</h3> 1971 1972 <pre>bool lexicographical_compare(path::iterator first1, path::iterator last1, 1973 path::iterator first2, path::iterator last2);</pre> 1974<blockquote> 1975 <p><i>Returns:</i> <code>true</code> if the sequence of <code>native()</code> strings for the elements defined by the half-open range <code>[first1,last1)</code> is 1976 lexicographically less than the sequence of <code>native()</code> strings for 1977 the elements defined by the half-open range <code>[first2,last2)</code>. Returns <code>false</code> otherwise.</p> 1978 <p><i>Remarks:</i> If two sequences have the same number of elements and their 1979 corresponding elements are equivalent, then neither sequence is 1980 lexicographically less than the other. If one sequence is a prefix of the 1981 other, then the shorter sequence is lexicographically less than the longer 1982 sequence. Otherwise, the lexicographical comparison of the sequences yields 1983 the same result as the comparison of the first corresponding pair of elements 1984 that are not equivalent.</p> 1985 <p>[<i>Note:</i> A <code>path</code> aware <code>lexicographical_compare</code> algorithm is provided for historical reasons. <i>—end note</i>]</p> 1986</blockquote> 1987 1988 <div> 1989 1990 <pre>path <a name="lex-normal">lexically_normal</a>(const path& p);</pre> 1991 1992 </div> 1993 1994<blockquote> 1995 <p><i>Overview:</i> Returns <code>p</code> with redundant current 1996 directory (<i>dot</i>), parent directory (<i>dot-dot</i>), and <i> 1997 directory-separator</i> elements removed.</p> 1998 <p><i>Returns:</i> <code>p</code> in 1999 <a href="#normal-form"> 2000 normal form</a>.</p> 2001 <p><i>Remarks:</i> Uses <code>operator/=</code> to compose the 2002 returned path.</p> 2003 <p>[<i>Example:</i></p> 2004 <p><code>assert(lexically_normal("foo/./bar/..") == "foo");<br> 2005 assert(lexically_normal("foo/.///bar/../") == "foo/.");</code></p> 2006 <p>All of the above assertions will succeed.<i> </i>On Windows, the 2007 returned path's <i>directory-separator</i> characters will be backslashes 2008 rather than slashes, but that does not affect <code>path</code> equality.<i> 2009 —end example</i>]</p> 2010</blockquote> 2011 2012 <div> 2013 2014 <pre>path lexically_<a name="lex-relative">relative</a>(const path& p, const path& base);</pre> 2015 2016 </div> 2017 2018<blockquote> 2019 <p><i>Overview:</i> Returns <code>p</code> made relative to <code> 2020 base</code>. Treats empty or identical paths as corner cases, not errors. Does 2021 not resolve symlinks. Does not first normalize <code>p</code> or <code>base</code>.</p> 2022 <p><i>Remarks:</i> Uses <code>std::mismatch(p.begin(), p.end(), 2023 base.begin(), base.end())</code>, to determine the first mismatched element of 2024 <code>p</code> and <code>base</code>. Uses <code>operator==</code> to 2025 determine if elements match. </p> 2026 <p><i>Returns:</i> </p> 2027 <ul> 2028 <li> 2029 <p><code>path()</code> if the first mismatched element of <code>p</code> 2030 is equal to <code>p.begin()</code> or the first mismatched element of <code> 2031 base</code> is equal to <code>base.begin()</code>, or<br> 2032 </li> 2033 <li> 2034 <p><code>path(".")</code> if the first mismatched element of <code> 2035 p</code> is equal to <code>p.end()</code> and the first mismatched element 2036 of <code>base</code> is equal to <code>base.end()</code>, or<br> 2037 </li> 2038 <li> 2039 <p>An object of class <code>path</code> composed via application 2040 of <code>operator/= path("..")</code> for each element in the half-open 2041 range [first mismatched element of <code>base</code>, <code>base.end()</code>), 2042 and then application of <code>operator/=</code> for each element in the 2043 half-open range [first mismatched element of <code>p</code>, <code>p.end()</code>). 2044 </li> 2045 </ul> 2046 <p>[<i>Example:</i></p> 2047 <p><code>assert(lexically_relative("/a/d", "/a/b/c") == "../../d");<br> 2048 assert(lexically_relative("/a/b/c", "/a/d") == "../b/c");<br> 2049 assert(lexically_relative("a/b/c", "a") == "b/c");<br> 2050 assert(lexically_relative("a/b/c", "a/b/c/x/y") == "../..");<br> 2051 assert(lexically_relative("a/b/c", "a/b/c") == ".");<br> 2052 assert(lexically_relative("a/b", "c/d") == "");</code></p> 2053 <p>All of the above assertions will succeed.<i> </i>On Windows, the 2054 returned path's <i>directory-separator</i>s will be backslashes rather than 2055 forward slashes, but that does not affect <code>path</code> equality.<i> —end 2056 example</i>]</p> 2057 <p>[<i>Note:</i> If symlink following semantics are desired, use the 2058 operational function <code> 2059 <a href="#relative"> 2060 relative</a></code> <i>—end note</i>]</p> 2061 <p>[<i>Note:</i> If <a href="#normal-form">normalization</a> is needed to ensure consistent matching of elements, wrap 2062 <code>p</code>, <code>base</code>, or both in calls <code> 2063 <a href="#lex-normal"> 2064 lexically_normal()</a></code>. <i>—end note</i>]</p> 2065</blockquote> 2066<pre>void swap( path& lhs, path& rhs )</pre> 2067<blockquote> 2068 <p><i>Effects: </i><code>lhs.swap(rhs)</code>.</p> 2069</blockquote> 2070<pre>std::size_t <a name="hash_value">hash_value</a> (const path& p);</pre> 2071<blockquote> 2072 <p><i>Returns:</i> A hash value for the path <code>p</code>. If 2073 for two paths, <code>p1 == p2</code> then <code>hash_value(p1) == hash_value(p2)</code>.</p> 2074 <p>This allows paths to be used with <a href="../../functional/hash/index.html">Boost.Hash</a>.</p> 2075</blockquote> 2076<pre>bool operator< (const path& lhs, const path& rhs);</pre> 2077<blockquote> 2078 <p><i>Returns:</i> <code>return lhs.compare(rhs.begin) < 0</code>.</p> 2079</blockquote> 2080<pre>bool operator<=(const path& lhs, const path& rhs);</pre> 2081<blockquote> 2082 <p><i>Returns:</i> <code>!(rhs < lhs)</code>.</p> 2083</blockquote> 2084<pre>bool operator> (const path& lhs, const path& rhs);</pre> 2085<blockquote> 2086 <p><i>Returns:</i> <code>rhs < lhs</code>.</p> 2087</blockquote> 2088<pre>bool operator>=(const path& lhs, const path& rhs);</pre> 2089<blockquote> 2090 <p><i>Returns:</i> <code>!(lhs < rhs)</code>.</p> 2091</blockquote> 2092<pre>bool operator==(const path& lhs, const path& rhs);</pre> 2093<blockquote> 2094 <p><i>Returns:</i> <code>!(lhs < rhs) && !(rhs < lhs)</code>.</p> 2095 <p>[<i>Note:</i> <a name="Path-equality">Path equality</a> and path 2096 equivalence have different semantics.</p> 2097 <p>Equality is determined by the <code>path</code> non-member <code>operator==</code>, which considers the two path's lexical 2098 representations only. Thus <code>path("foo") == "bar"</code> is never <code>true</code>.</p> 2099 <p>Equivalence is determined by the <a href="#equivalent"><code>equivalent()</code></a> non-member function, which determines if two paths <a href="#path">resolve</a> to the same file system entity. 2100 Thus <code>equivalent("foo", "bar")</code> will be <code>true</code> when both paths resolve to the same file.</p> 2101 <p>Programmers wishing to determine if two paths are "the same" must decide if 2102 "the same" means "the same representation" or "resolve to the same actual 2103 file", and choose the appropriate function accordingly. <i>—end note</i>]</p> 2104</blockquote> 2105<pre>bool operator!=(const path& lhs, const path& rhs);</pre> 2106<blockquote> 2107 <p><i>Returns:</i> <code>!(lhs == rhs)</code>.</p> 2108</blockquote> 2109<pre>path operator/ (const path& lhs, const path& rhs);</pre> 2110<blockquote> 2111 <p><i>Returns:</i> <code>path(lhs) /= rhs</code>.</p> 2112</blockquote> 2113<h3> <a name="path-non-member-operators"><code><font size="4">path</font></code></a><a name="path-inserter-extractor"> inserter 2114 and extractor</a> [path.io]</h3> 2115<p> The inserter and extractor delimit the string with double-quotes (<code>"</code>) 2116so that paths with embedded spaces will round trip correctly. Ampersand (<code>&</code>) 2117is as an escape character, so the path can itself contain double quotes.</p> 2118<pre>template <class Char, class Traits> 2119std::basic_ostream<Char, Traits>& operator<<(std::basic_ostream<Char, Traits>& os, 2120 const path& p) 2121</pre> 2122<blockquote> 2123 <p><i>Effects: </i>Insert characters into <code>os</code>:</p> 2124 <ul> 2125 <li> 2126 <p>A double-quote.</p> 2127 </li> 2128 <li> 2129 <p>Each character in <code>p.string<std::basic_string<Char>>()</code>. 2130 If the character to be inserted is equal to the escape character or a 2131 double-quote, as determined by <code>operator==</code>, first insert the 2132 escape character.</p> 2133 </li> 2134 <li> 2135 <p>A double-quote.</p> 2136 </li> 2137 </ul> 2138 <p><i>Returns:</i> <code>os</code></p> 2139</blockquote> 2140<pre>template <class Char, class Traits> 2141inline std::basic_istream<Char, Traits>& operator>>(std::basic_istream<Char, Traits>& is, 2142 path& p) 2143</pre> 2144<blockquote> 2145 <p><i>Effects: </i><code> std::basic_string<Char> str;<br> 2146 is >> <a href="../../io/doc/quoted_manip.html">boost::io::quoted</a>(str, static_cast<Char>('&'));<br> 2147 p = str;</code></p> 2148 <p><i>Effects: </i>Extract characters from os:</p> 2149 <ul> 2150 <li>If the first character that would be extracted is equal to double-quote, 2151 as determined by <code>operator==</code>, then:<ul> 2152 <li>Discard the initial double-quote.</li> 2153 <li>Save the value and then turn off the <code>skipws</code> flag.</li> 2154 <li><code>p.clear()</code></li> 2155 <li>Until an unescaped double-quote character is reached or <code> 2156 is.not_good()</code>, extract characters from <code>os</code> and append 2157 them to <code>p</code>, except that if an escape character is reached, 2158 ignore it and append the next character to <code>p</code>.</li> 2159 <li>Discard the final double-quote character.</li> 2160 <li>Restore the <code>skipws</code> flag to its original value.</li> 2161 </ul> 2162 </li> 2163 <li>Otherwise, <code>os >> p</code>.</li> 2164 </ul> 2165 <p><i>Returns:</i> <code>is</code></p> 2166 </blockquote> 2167<h2><a name="Class-filesystem_error">Class <code>filesystem_error</code> 2168[class.filesystem_error]</a></h2> 2169<pre>namespace boost 2170{ 2171 namespace filesystem 2172 { 2173 class filesystem_error : public system_error 2174 { 2175 public: 2176 filesystem_error(); 2177 filesystem_error(const filesystem_error&); 2178 <a href="#filesystem_error-2-arg">filesystem_error</a>(const std::string& what_arg, 2179 system::error_code ec); 2180 <a href="#filesystem_error-3-arg">filesystem_error</a>(const std::string& what_arg, 2181 const path& p1, system::error_code ec); 2182 <a href="#filesystem_error-4-arg">filesystem_error</a>(const std::string& what_arg, 2183 const path& p1, const path& p2, system::error_code ec); 2184 2185 filesystem_error& filesystem_error(const filesystem_error&); 2186 ~filesystem_error(); 2187 2188 filesystem_error& operator=(const filesystem_error&); 2189 2190 const path& <a href="#filesystem_error-path1">path1</a>() const; 2191 const path& <a href="#filesystem_error-path2">path2</a>() const; 2192 2193 const char * <a href="#filesystem_error-what">what</a>() const; 2194 }; 2195 } // namespace filesystem 2196} // namespace boost</pre> 2197<p>The class template <code>filesystem_error</code> defines the type of 2198objects thrown as exceptions to report file system errors from functions described in this 2199reference documentation.</p> 2200<h3> <a name="filesystem_error-members"> <code>filesystem_error</code> members</a> 2201[filesystem_error.members]</h3> 2202<pre><a name="filesystem_error-2-arg">filesystem_error</a>(const std::string& what_arg, error_code ec);</pre> 2203<blockquote> 2204 <p><i>Postcondition:</i></p> 2205 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="46%"> 2206 <tr> 2207 <td width="18%"><b>Expression</b></td> 2208 <td width="82%"><b>Value</b></td> 2209 </tr> 2210 <tr> 2211 <td width="18%" bgcolor="#FFFFFF"><code> 2212 runtime_error::what()</code></td> 2213 <td width="82%" bgcolor="#FFFFFF"> 2214 <code><i>what_arg</i>.c_str()</code></td> 2215 </tr> 2216 <tr> 2217 <td width="18%"><code>code()</code></td> 2218 <td width="82%"><code>ec</code></td> 2219 </tr> 2220 <tr> 2221 <td width="18%"><code>path1().empty()</code></td> 2222 <td width="82%"><code>true</code></td> 2223 </tr> 2224 <tr> 2225 <td width="18%"><code>path2().empty()</code></td> 2226 <td width="82%"><code>true</code></td> 2227 </tr> 2228 </table> 2229</blockquote> 2230<pre><a name="filesystem_error-3-arg">filesystem_error</a>(const std::string& what_arg, const path& p1, error_code ec);</pre> 2231<blockquote> 2232 <p><i>Postcondition:</i></p> 2233 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="46%"> 2234 <tr> 2235 <td width="18%"><b>Expression</b></td> 2236 <td width="82%"><b>Value</b></td> 2237 </tr> 2238 <tr> 2239 <td width="18%" valign="top"><code> 2240 runtime_error::what()</code></td> 2241 <td width="82%"> 2242 <code><i>what_arg</i>.c_str()</code></td> 2243 </tr> 2244 <tr> 2245 <td width="18%" valign="top"><code>code()</code></td> 2246 <td width="82%"><code>ec</code></td> 2247 </tr> 2248 <tr> 2249 <td width="18%" valign="top"><code>path1()</code></td> 2250 <td width="82%">Reference to stored copy of <code>p1</code></td> 2251 </tr> 2252 <tr> 2253 <td width="18%" valign="top"><code>path2().empty()</code></td> 2254 <td width="82%"><code>true</code></td> 2255 </tr> 2256 </table> 2257</blockquote> 2258<pre><a name="filesystem_error-4-arg">filesystem_error</a>(const std::string& what_arg, const path& p1, const path& p2, error_code ec);</pre> 2259<blockquote> 2260 <p><i>Postcondition:</i></p> 2261 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="46%"> 2262 <tr> 2263 <td width="18%"><b>Expression</b></td> 2264 <td width="82%"><b>Value</b></td> 2265 </tr> 2266 <tr> 2267 <td width="18%"><code> 2268 runtime_error::what()</code></td> 2269 <td width="82%"> 2270 <u> 2271 <code><i>w</i></code></u><code><i>hat_arg</i>.c_str()</code></td> 2272 </tr> 2273 <tr> 2274 <td width="18%"><code>code()</code></td> 2275 <td width="82%"><code>ec</code></td> 2276 </tr> 2277 <tr> 2278 <td width="18%"><code>path1()</code></td> 2279 <td width="82%">Reference to stored copy of <code>p1</code></td> 2280 </tr> 2281 <tr> 2282 <td width="18%"><code>path2()</code></td> 2283 <td width="82%">Reference to stored copy of <code>p2</code></td> 2284 </tr> 2285 </table> 2286</blockquote> 2287<pre>const path& <a name="filesystem_error-path1">path1</a>() const;</pre> 2288<blockquote> 2289 <p><i>Returns:</i> Reference to copy of <code>p1</code> stored by the 2290 constructor, or, if none, an empty path.</p> 2291</blockquote> 2292<pre>const path& <a name="filesystem_error-path2">path2</a>() const;</pre> 2293<blockquote> 2294 <p><i>Returns:</i> Reference to copy of <code>p2</code> stored by the 2295 constructor, or, if none, an empty path.</p> 2296</blockquote> 2297<pre>const char* <a name="filesystem_error-what">what</a>() const;</pre> 2298<blockquote> 2299 <p><i>Returns: </i>A string containing <code>runtime_error::what()</code>. The exact format is unspecified. 2300 Implementations are encouraged but not required to include <code>path1.native_string()</code>if not empty, <code>path2.native_string()</code>if 2301 not empty, and <code>system_error::what()</code> strings in the returned 2302 string.</p> 2303</blockquote> 2304<h2><a name="Enum-file_type">Enum file_type</a> [enum.file_type]</h2> 2305<p>This enum specifies constants uses to identify file types.</p> 2306<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111"> 2307 <tr> 2308 <td><b>Constant Name</b></td> 2309 <td><b>Meaning</b></td> 2310 </tr> 2311 <tr> 2312 <td><code>status_error</code></td> 2313 <td>An error occurred while trying to obtain the status of the file. The 2314 file simply not being found is <b><u>not</u></b> considered a status error. </td> 2315 </tr> 2316 <tr> 2317 <td><code>file_not_found</code></td> 2318 <td>The file could not be found</td> 2319 </tr> 2320 <tr> 2321 <td><code>regular_file</code></td> 2322 <td>Regular file</td> 2323 </tr> 2324 <tr> 2325 <td><code>directory_file</code></td> 2326 <td>Directory file</td> 2327 </tr> 2328 <tr> 2329 <td><code>symlink_file</code></td> 2330 <td>Symbolic link file</td> 2331 </tr> 2332 <tr> 2333 <td><code>block_file</code></td> 2334 <td>Block special file</td> 2335 </tr> 2336 <tr> 2337 <td><code>character_file</code></td> 2338 <td>Character special file</td> 2339 </tr> 2340 <tr> 2341 <td><code>fifo_file</code></td> 2342 <td>FIFO or pipe file</td> 2343 </tr> 2344 <tr> 2345 <td><code>socket_file</code></td> 2346 <td>Socket file</td> 2347 </tr> 2348 <tr> 2349 <td><code>type_unknown</code></td> 2350 <td>The file exists, but it is of a system specific type not covered by any 2351 of the above cases.</td> 2352 </tr> 2353</table> 2354<h2><a name="Enum-perms">Enum perms</a> [enum.perms]</h2> 2355<p>This <code>enum</code> specifies bitmask constants uses to identify file 2356permissions. <i><span style="background-color: #E0E0E0">ISO/</span><span style="background-color: #E0E0E0">IEC</span><span style="background-color: #E0E0E0"> 9945 2357(POSIX) specifies actual values, and those values have been adopted here because 2358they are very familiar and ingrained for many POSIX 2359users.</span></i></p> 2360<blockquote> 2361<p><span style="background-color: #FFFF00">Windows: All permissions except write are currently ignored. There is only a 2362single write permission; setting write permission for owner, group, or others 2363sets write permission for all, and removing write permission for owner, group, 2364or others removes write permission for all. </span> </p> 2365</blockquote> 2366<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111"> 2367 <tr> 2368 <td><b>Name</b></td> 2369 <td align="center"><b>Value<br> 2370 (octal)</b></td> 2371 <td align="center"><b>ISO/IEC 9945<br> 2372 macro</b></td> 2373 <td><b>Definition or notes</b></td> 2374 </tr> 2375 2376<tr><td> 2377 <p><code>no_perms</code></td><td><code>0</code></td><td></td> 2378 <td>There are no permissions set for the file. Note: <code>file_not_found</code> is <code>no_perms</code> rather than <code>perms_not_known</code></td> 2379</tr> 2380<tr><td><code>owner_read</code></td><td><code>0400</code></td><td> <code>S_IRUSR</code></td> 2381 <td> Read permission, owner</td> 2382</tr> 2383<tr><td><code>owner_write</code></td><td><code>0200</code></td><td> <code>S_IWUSR</code></td> 2384 <td> Write permission, owner</td> 2385</tr> 2386<tr><td><code>owner_exe</code></td><td><code>0100</code></td><td> <code>S_IXUSR</code></td> 2387 <td> Execute/search permission, owner</td> 2388</tr> 2389<tr><td><code>owner_all</code></td><td><code>0700</code></td><td> <code>S_IRWXU</code></td> 2390 <td> Read, write, execute/search by owner; <code>owner_read | owner_write | owner_exe</code></td> 2391</tr> 2392<tr><td><code>group_read</code></td><td><code>040</code></td><td> <code>S_IRGRP</code></td> 2393 <td> Read permission, group</td> 2394</tr> 2395<tr><td><code>group_write</code></td><td><code>020</code></td><td> <code>S_IWGRP</code></td> 2396 <td> Write permission, group</td> 2397</tr> 2398<tr><td><code>group_exe</code></td><td><code>010</code></td><td> <code>S_IXGRP</code></td> 2399 <td> Execute/search permission, group</td> 2400</tr> 2401<tr><td><code>group_all</code></td><td><code>070</code></td><td> <code>S_IRWXG</code></td> 2402 <td> Read, write, execute/search by group; <code>group_read | group_write | group_exe</code></td> 2403</tr> 2404<tr><td><code>others_read</code></td><td><code>04</code></td><td> <code>S_IROTH</code></td> 2405 <td> Read permission, others</td> 2406</tr> 2407<tr><td><code>others_write</code></td><td><code>02</code></td><td> <code>S_IWOTH</code></td> 2408 <td> Write permission, others</td> 2409</tr> 2410<tr><td><code>others_exe</code></td><td><code>01</code></td><td> <code>S_IXOTH</code></td> 2411 <td> Execute/search permission, others</td> 2412</tr> 2413<tr><td><code>others_all</code></td><td><code>07</code></td><td> <code>S_IRWXO</code></td> 2414 <td>Read, write, execute/search by others; <code>others_read | others_write | others_exe</code></td> 2415</tr> 2416<tr><td><code>all_all</code></td><td><code>0777</code></td><td> </td><td><code>owner_all | group_all | others_all</code></td> 2417</tr> 2418<tr><td><code>set_uid_on_exe</code></td><td><code>04000</code></td><td> <code>S_ISUID</code></td> 2419 <td> Set-user-ID on execution</td> 2420</tr> 2421<tr><td><code>set_gid_on_exe</code></td><td><code>02000</code></td><td> <code>S_ISGID</code></td> 2422 <td> Set-group-ID on execution</td> 2423</tr> 2424<tr><td><code><a name="sticky_bit">sticky_bit</a> </code></td><td><code>01000</code></td><td> <code>S_ISVTX</code></td> 2425 <td> Operating system dependent. Inherently non-portable, even between ISO/IEC 9945 2426 operating systems.</td> 2427</tr> 2428<tr><td><code><a name="perms_mask">perms_mask</a></code></td><td><code>07777</code></td><td> </td> 2429 <td><code>all_all | set_uid_on_exe | set_gid_on_exe | sticky_bit</code></td> 2430</tr> 2431<tr><td><code>perms_not_known</code></td><td><code>0xFFFF</code></td><td></td><td> 2432 The permissions are not known, such as when a <code>file_status</code> object 2433 is created without specifying the permissions</td> 2434</tr> 2435<tr><td> 2436 <p><code>add_perms</code></td><td><code>0x1000</code></td><td></td><td> 2437 <p><code>permissions()</code> adds the argument permission bits to the 2438 file's current bits</td> 2439</tr> 2440<tr><td><code>remove_perms</code></td><td><code>0x2000</code></td><td></td><td> 2441 <code>permissions()</code> removes the argument permission bits from the 2442 file's current bits</td> 2443</tr> 2444<tr><td><code><a name="symlink_perms">symlink_perms</a></code></td><td><code>0x4000</code></td><td></td><td> 2445 <span style="background-color: #FFFF00">On ISO/</span><span style="background-color: #FFFF00">IEC</span><span style="background-color: #FFFF00"> 9945 2446 </span> <code><span style="background-color: #FFFF00">permissions()</span></code><span style="background-color: #FFFF00"> resolves symlinks unless 2447 </span> <code><span style="background-color: #FFFF00">symlink_perms</span></code><span style="background-color: #FFFF00"> is specified. 2448 Meaningless on Windows as </span> <code> 2449 <span style="background-color: #FFFF00">permissions()</span></code><span style="background-color: #FFFF00"> never resolves symlinks. 2450 Meaningless on Mac OS X and some other BSD systems as </span> <code> 2451 <span style="background-color: #FFFF00">permissions()</span></code><span style="background-color: #FFFF00"> always resolves symlinks. Get over it.</span></td> 2452</tr> 2453 2454</table> 2455<h2><a name="file_status">Class file_status</a> [class.file_status]</h2> 2456<pre>namespace boost 2457{ 2458 namespace filesystem 2459 { 2460 class file_status 2461 { 2462 public: 2463 2464 // <a href="#file_status-constructors">constructors</a> 2465 file_status() noexcept; 2466 explicit file_status(<a href="#file_type">file_type</a> ft, <a href="#Enum-perms">perms</a> prms = perms_not_known) noexcept; 2467 2468 // compiler generated 2469 file_status(const file_status&) noexcept; 2470 file_status& operator=(const file_status&) noexcept; 2471 ~file_status() noexcept; 2472 2473 // <a href="#file_status-observers">observers</a> 2474 <a href="#file_type">file_type</a> type() const noexcept; 2475 <a href="#Enum-perms">perms</a> permissions() const noexcept; 2476 2477 // <a href="#file_status-modifiers">modifiers</a> 2478 void type(<a href="#file_type">file_type</a> ft) noexcept; 2479 void permissions(<a href="#Enum-perms">perms</a> prms) noexcept; 2480 }; 2481 } // namespace filesystem 2482} // namespace boost</pre> 2483<p>An object of type <code>file_status</code> stores information about the type 2484and permissions of a file.</p> 2485<h3><a name="file_status-constructors"><code>file_status</code> constructors</a> 2486[file_status.cons]</h3> 2487<pre>explicit file_status() noexcept;</pre> 2488<blockquote> 2489 <p><i>Postconditions:</i> <code>type() == status_error</code>, <code>permissions() == perms_not_known</code>.</p> 2490</blockquote> 2491<pre>explicit file_status(<a href="#file_type">file_type</a> ft, <a href="#Enum-perms">perms</a> prms = perms_not_known) noexcept;</pre> 2492<blockquote> 2493 <p><i>Postconditions:</i> <code>type() == ft</code>, <code>permissions() == prms</code>.</p> 2494</blockquote> 2495 <h3><a name="file_status-observers"><code>file_status</code> observers</a> [file_status.obs]</h3> 2496<pre><a href="#file_type">file_type</a> type() const noexcept;</pre> 2497<blockquote> 2498 <p><i>Returns: </i>The value of <code>type()</code> specified by the <i>postconditions</i> of the most recent call to a constructor, operator=, or <code>type(file_type)</code> function.</p> 2499</blockquote> 2500<pre><a href="#Enum-perms">perms</a> permissions() const noexcept;</pre> 2501<blockquote> 2502 <p><i>Returns: </i>The value of <code>permissions()</code> specified by the <i>postconditions</i> of the most recent call to a constructor, operator=, or <code>permissions(perms)</code> function.</p> 2503</blockquote> 2504<h3><a name="file_status-modifiers"><code>file_status</code> modifiers</a> [file_status.mods]</h3> 2505<pre>void type(<a href="#file_type">file_type</a> ft) noexcept;</pre> 2506<blockquote> 2507 <p><i>Postconditions:</i> <code>type() == ft</code>.</p> 2508</blockquote> 2509<pre>void permissions(<a href="#Enum-perms">perms</a> prms) noexcept;</pre> 2510<blockquote> 2511 <p><i>Postconditions:</i> <code>permissions() == prms</code>.</p> 2512</blockquote> 2513<h2><a name="Class-directory_entry">Class <code>directory_entry</code></a> [class.directory_entry]</h2> 2514 2515<pre>namespace boost 2516{ 2517 namespace filesystem 2518 { 2519 class directory_entry 2520 { 2521 public: 2522 2523 // <a href="#directory_entry-constructors">constructors</a> and destructor 2524 directory_entry(); 2525 directory_entry(const directory_entry&); 2526 explicit directory_entry(const path& p, file_status st=file_status(), 2527 file_status symlink_st=file_status()); 2528 ~directory_entry(); 2529 2530 // <a href="#directory_entry-modifiers">modifiers</a> 2531 directory_entry& operator=(const directory_entry&); 2532 void assign(const path& p, file_status st=file_status(), 2533 file_status symlink_st=file_status()); 2534 void replace_filename(const path& p, file_status st=file_status(), 2535 file_status symlink_st=file_status()); 2536 2537 // <a href="#directory_entry-observers">observers</a> 2538 const path& path() const; 2539 file_status status() const; 2540 file_status status(system::error_code& ec) const; 2541 file_status symlink_status() const; 2542 file_status symlink_status(system::error_code& ec) const; 2543 2544 bool operator< (const directory_entry& rhs); 2545 bool operator==(const directory_entry& rhs); 2546 bool operator!=(const directory_entry& rhs); 2547 bool operator< (const directory_entry& rhs); 2548 bool operator<=(const directory_entry& rhs); 2549 bool operator> (const directory_entry& rhs); 2550 bool operator>=(const directory_entry& rhs); 2551 private: 2552 path m_path; // for exposition only 2553 mutable file_status m_status; // for exposition only; stat()-like 2554 mutable file_status m_symlink_status; // for exposition only; lstat()-like 2555 }; 2556 2557 } // namespace filesystem 2558} // namespace boost</pre> 2559 2560<p>A <code>directory_entry</code> object stores a <code>path object</code>, 2561a <code>file_status</code> object for non-symbolic link status, and a <code>file_status</code> object for symbolic link status. The <code>file_status</code> objects act as value caches.</p> 2562<blockquote> 2563<p>[<i>Note:</i> Because <code>status()</code>on a pathname may be a relatively expensive operation, 2564some operating systems provide status information as a byproduct of directory 2565iteration. Caching such status information can result is significant time savings. Cached and 2566non-cached results may differ in the presence of file system races. <i>—end note</i>]</p> 2567<p><span style="background-color: #E0E0E0"><i>Actual cold-boot timing of iteration over 2568a directory with 15,047 entries was six seconds for non-cached status queries 2569versus one second for cached status queries. Windows XP, 3.0 GHz processor, with 2570a moderately fast hard-drive. Similar speedups are expected on Linux and BSD-derived 2571systems that provide status as a by-product of directory iteration.</i></span></p> 2572</blockquote> 2573<h3> <a name="directory_entry-constructors"> <code>directory_entry </code>constructors</a> 2574[directory_entry.cons]</h3> 2575<pre>directory_entry();</pre> 2576<blockquote> 2577 <p><i>Postcondition:</i></p> 2578 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="36%"> 2579 <tr> 2580 <td width="18%"><b>Expression</b></td> 2581 <td width="82%"><b>Value</b></td> 2582 </tr> 2583 <tr> 2584 <td width="18%"><code>path().empty()</code></td> 2585 <td width="82%"><code>true</code></td> 2586 </tr> 2587 <tr> 2588 <td width="18%"><code>status()</code></td> 2589 <td width="82%"><code>file_status()</code></td> 2590 </tr> 2591 <tr> 2592 <td width="18%"><code>symlink_status()</code></td> 2593 <td width="82%"><code>file_status()</code></td> 2594 </tr> 2595 </table> 2596</blockquote> 2597<pre>explicit directory_entry(const path& p, file_status st=file_status(), file_status symlink_st=file_status());</pre> 2598<blockquote> 2599 <p><i>Postcondition:</i></p> 2600 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="36%"> 2601 <tr> 2602 <td width="18%"><b>Expression</b></td> 2603 <td width="82%"><b>Value</b></td> 2604 </tr> 2605 <tr> 2606 <td width="18%"><code>path()</code></td> 2607 <td width="82%"><code>p</code></td> 2608 </tr> 2609 <tr> 2610 <td width="18%"><code>status()</code></td> 2611 <td width="82%"><code>st</code></td> 2612 </tr> 2613 <tr> 2614 <td width="18%"><code>symlink_status()</code></td> 2615 <td width="82%"><code>symlink_st</code></td> 2616 </tr> 2617 </table> 2618</blockquote> 2619<h3> <a name="directory_entry-modifiers"> <code>directory_entry </code>modifiers</a> 2620[directory_entry.mods]</h3> 2621<pre>void assign(const path& p, file_status st=file_status(), file_status symlink_st=file_status());</pre> 2622<blockquote> 2623 <p><i>Postcondition:</i></p> 2624 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="36%"> 2625 <tr> 2626 <td width="18%"><b>Expression</b></td> 2627 <td width="82%"><b>Value</b></td> 2628 </tr> 2629 <tr> 2630 <td width="18%"><code>path()</code></td> 2631 <td width="82%"><code>p</code></td> 2632 </tr> 2633 <tr> 2634 <td width="18%"><code>status()</code></td> 2635 <td width="82%"><code>st</code></td> 2636 </tr> 2637 <tr> 2638 <td width="18%"><code>symlink_status()</code></td> 2639 <td width="82%"><code>symlink_st</code></td> 2640 </tr> 2641 </table> 2642</blockquote> 2643<pre>void replace_filename(const path& p, file_status st=file_status(), file_status symlink_st=file_status());</pre> 2644<blockquote> 2645 <p><i>Postcondition:</i></p> 2646 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="43%"> 2647 <tr> 2648 <td width="18%"><b>Expression</b></td> 2649 <td width="82%"><b>Value</b></td> 2650 </tr> 2651 <tr> 2652 <td width="18%"><code>path()</code></td> 2653 <td width="82%"><code>path().branch() / s</code></td> 2654 </tr> 2655 <tr> 2656 <td width="18%"><code>status()</code></td> 2657 <td width="82%"><code>st</code></td> 2658 </tr> 2659 <tr> 2660 <td width="18%"><code>symlink_status()</code></td> 2661 <td width="82%"><code>symlink_st</code></td> 2662 </tr> 2663 </table> 2664</blockquote> 2665<h3> <a name="directory_entry-observers"> <code>directory_entry</code> observers</a> 2666[directory_entry.obs]</h3> 2667<pre>const path& path() const;</pre> 2668<blockquote> 2669 <p><i>Returns:</i> <code>m_path</code></p> 2670</blockquote> 2671<pre>file_status status() const; 2672file_status status(system::error_code& ec) const;</pre> 2673<blockquote> 2674<p><i>Effects:</i> As if,</p> 2675 <blockquote> 2676 <pre>if ( !status_known( m_status ) ) 2677{ 2678 if ( status_known(m_symlink_status) && !is_symlink(m_symlink_status) ) 2679 { m_status = m_symlink_status; } 2680 else { m_status = status(m_path<i>[, ec]</i>); } 2681}</pre> 2682 </blockquote> 2683 <p><i>Returns:</i> <code>m_status</code></p> 2684 2685 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 2686 2687</blockquote> 2688<pre>file_status symlink_status() const; 2689file_status symlink_status(system::error_code& ec) const;</pre> 2690<blockquote> 2691<p> 2692 <i>Effects:</i> As if,</p> 2693 <blockquote> 2694 <pre>if ( !status_known( m_symlink_status ) ) 2695{ 2696 m_symlink_status = symlink_status(m_path<i>[, ec]</i>); 2697}</pre> 2698 </blockquote> 2699 <p><i>Returns:</i> <code>m_symlink_status</code></p> 2700 2701 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 2702 2703</blockquote> 2704<pre>bool operator==(const directory_entry& rhs);</pre> 2705<blockquote> 2706 <p><i>Returns:</i> <code>m_path == rhs.m_path</code>.</p> 2707</blockquote> 2708<pre>bool operator!=(const directory_entry& rhs);</pre> 2709<blockquote> 2710 <p><i>Returns:</i> <code>m_path != rhs.m_path</code>.</p> 2711</blockquote> 2712<pre>bool operator< (const directory_entry& rhs);</pre> 2713<blockquote> 2714 <p><i>Returns:</i> <code>m_path < rhs.m_path</code>.</p> 2715</blockquote> 2716<pre>bool operator<=(const directory_entry& rhs);</pre> 2717<blockquote> 2718 <p><i>Returns:</i> <code>m_path <= rhs.m_path</code>.</p> 2719</blockquote> 2720<pre>bool operator> (const directory_entry& rhs);</pre> 2721<blockquote> 2722 <p><i>Returns:</i> <code>m_path > rhs.m_path</code>.</p> 2723</blockquote> 2724<pre>bool operator>=(const directory_entry& rhs);</pre> 2725<blockquote> 2726 <p><i>Returns:</i> <code>m_path >= rhs.m_path</code>.</p> 2727</blockquote> 2728<h2><a name="Class-directory_iterator">Class <code>directory_iterator</code> 2729[class.directory_iterator]</a></h2> 2730<p>Objects of type <code>directory_iterator</code> provide standard library 2731compliant iteration over the contents of a directory. Also see class <code><a href="#Class-recursive_directory_iterator">recursive_directory_iterator</a></code>.</p> 2732<pre>namespace boost 2733{ 2734 namespace filesystem 2735 { 2736 class directory_iterator 2737 { 2738 public: 2739 // <a href="#directory_iterator-members">member functions</a> 2740 2741 directory_iterator() noexcept; // creates the "end" iterator 2742 directory_iterator(const directory_iterator&); 2743 explicit directory_iterator(const path& p, <a href="#directory_options">directory_options</a> opts = directory_options::none); 2744 directory_iterator(const path& p, system::error_code& ec); 2745 directory_iterator(const path& p, <a href="#directory_options">directory_options</a> opts, system::error_code& ec); 2746 ~directory_iterator(); 2747 2748 directory_iterator& operator=(const directory_iterator&); 2749 2750 directory_iterator& operator++(); 2751 directory_iterator& increment(system::error_code& ec); 2752 2753 // other members as required by 2754 // C++ Std, 24.1.1 Input iterators [input.iterators] 2755 }; 2756 2757 } // namespace filesystem 2758} // namespace boost</pre> 2759<p> <code>directory_iterator</code> satisfies the requirements of an 2760input iterator (C++ Std, 24.2.1, Input iterators [input.iterators]).</p> 2761<p>A <code>directory_iterator</code> reads successive elements from the directory for 2762which it was constructed, as if by calling ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/readdir_r.html">readdir() or readdir_r()</a></code>. After a <code>directory_iterator</code> is constructed, and every time <code>operator++</code> is called, 2763it reads a directory element and stores information about it in an object of type <code><a href="#Class-directory_entry">directory_entry</a></code>. <code>operator++</code> is not equality preserving; that is, <code>i == j</code> does not imply that <code>++i == ++j</code>. </p> 2764<blockquote> 2765<p>[<i>Note:</i> The practical consequence of not preserving equality is that directory iterators 2766can only be used for single-pass algorithms. <i>—end note</i>]</p> 2767</blockquote> 2768<p>If the end of the directory elements is reached, the iterator shall become equal to 2769the end iterator value. The constructor <code>directory_iterator()</code> with no arguments always constructs an end iterator object, which 2770shall be the only valid iterator for the end condition. The result of <code>operator*</code> on an end iterator is not defined. For any other iterator value 2771a <code>const directory_entry&</code> is returned. The result of <code>operator-></code> on an end iterator is 2772undefined behavior. For any other iterator value a <code>const directory_entry*</code> is 2773returned. </p> 2774<p>Two end iterators are always equal. An end iterator shall not be equal to a non-end 2775iterator.</p> 2776<blockquote> 2777<p><i><span style="background-color: #E0E0E0">The above wording is based on the 2778Standard Library's istream_iterator wording.</span></i></p> 2779</blockquote> 2780<p>The result of calling the <code>path()</code> member of the <code>directory_entry</code> object obtained by dereferencing a <code>directory_iterator</code> is a reference to a <code>path</code> object composed of the directory argument from which the iterator was 2781constructed with filename of the directory entry appended as if by <code>operator/=</code>. </p> 2782<p>Directory iteration shall not yield directory entries for the current (<i>dot</i>) 2783and parent (<i>dot dot</i>) directories.</p> 2784<p>The order of directory entries obtained by dereferencing successive 2785increments of a <code>directory_iterator</code> is unspecified.</p> 2786<blockquote> 2787<p>[<i>Note:</i> Programs performing directory iteration may wish to test if the 2788path obtained by dereferencing a directory iterator actually exists. It could be 2789a 2790symbolic link to a non-existent file. Programs recursively 2791walking directory trees for purposes of removing and renaming entries may wish 2792to avoid following symbolic links.</p> 2793<p>If a file is removed from or added to a directory after the 2794construction of a <code>directory_iterator</code> for the directory, it is 2795unspecified whether or not subsequent incrementing of the iterator will ever 2796result in an iterator whose value is the removed or added directory entry. See 2797ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/readdir_r.html">readdir_r()</a></code>. <i>—end note</i>]</p> 2798</blockquote> 2799<h3><a name="directory_iterator-members"><code>directory_iterator</code> members</a> 2800[directory_iterator.members]</h3> 2801 2802<p><code><a name="directory_iterator-default-ctor">directory_iterator</a>() 2803noexcept;</code></p> 2804 2805<blockquote> 2806 2807<p><i>Effects:</i> Constructs the end iterator.</p> 2808 2809</blockquote> 2810 2811<pre><code>explicit <a name="directory_iterator-ctor-path">directory_iterator</a>(</code>const path& p, <a href="#directory_options">directory_options</a> opts = directory_options::none<code>); 2812directory_iterator(</code>const path& p, system::error_code& ec<code>); 2813directory_iterator(</code>const path& p, <a href="#directory_options">directory_options</a> opts, system::error_code& ec<code>);</code></pre> 2814<blockquote> 2815 2816<p><i>Effects:</i> Constructs an iterator representing the first 2817entry in the directory <code>p</code> resolves to, if any; otherwise, the end iterator. 2818If opening the directory fails with a <code>permission_denied</code> error and <code>(opts & directory_options::skip_permission_denied) != 0</code>, 2819constructs the end iterator and ignores the error (the operation completes successfully). If <code>opts</code> is not specified, it is assumed to be <code>directory_options::none</code>.</p> 2820 2821<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 2822 2823<p>[<i>Note:</i> To iterate over the current directory, use <code>directory_iterator(".")</code> rather than <code>directory_iterator("")</code>. <i>—end note</i>]</p> 2824</blockquote> 2825<pre>directory_iterator& <a name="directory_iterator-increment">operator++</a>(); 2826directory_iterator& increment(system::error_code& ec);</pre> 2827<blockquote> 2828 2829<p><i>Effects:</i> As specified by the C++ Standard, 24.1.1 Input iterators [input.iterators]. In case of error the iterator is left in the end state.</p> 2830 2831<p><i>Returns:</i> <code>*this</code>.</p> 2832 2833<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 2834 2835</blockquote> 2836<h3><a name="directory_iterator-non-member-functions"><code>directory_iterator</code> non-member functions</a></h3> 2837<pre>const directory_iterator& begin(const directory_iterator& iter);</pre> 2838<blockquote> 2839 <p><i>Returns: </i><code>iter</code>.</p> 2840</blockquote> 2841<pre>directory_iterator end(const directory_iterator&);</pre> 2842<blockquote> 2843 <p><i>Returns: </i><code>directory_iterator()</code>.</p> 2844</blockquote> 2845<h2><a name="Class-recursive_directory_iterator">Class <code>recursive_directory_iterator</code> 2846[class.rec.dir.itr]</a></h2> 2847<p>Objects of type <code>recursive_directory_iterator</code> provide standard library 2848compliant iteration over the contents of a directory, including recursion into 2849its sub-directories.</p> 2850<pre>namespace boost 2851{ 2852 namespace filesystem 2853 { 2854 class recursive_directory_iterator : 2855 public iterator<input_iterator_tag, directory_entry> 2856 { 2857 public: 2858 2859 // constructors and destructor 2860 recursive_directory_iterator() noexcept; 2861 recursive_directory_iterator(const recursive_directory_iterator&); 2862 explicit recursive_directory_iterator(const path& p, 2863 <a href="#directory_options">directory_options</a> opts = directory_options::none); 2864 recursive_directory_iterator(const path& p, 2865 <a href="#directory_options">directory_options</a> opts, system::error_code& ec); 2866 // deprecated constructors, use overloads accepting directory_options instead 2867 explicit recursive_directory_iterator(const path& p, 2868 <a href="#symlink_option">symlink_option</a> opts = symlink_option::none); 2869 recursive_directory_iterator(const path& p, 2870 <a href="#symlink_option">symlink_option</a> opts, system::error_code& ec); 2871 recursive_directory_iterator(const path& p, system::error_code& ec); 2872 ~recursive_directory_iterator(); 2873 2874 // observers 2875 int depth() const noexcept; 2876 bool recursion_pending() const noexcept; 2877 2878 // deprecated observers 2879 int level() const noexcept; 2880 bool no_push_pending() const noexcept; 2881 2882 // modifiers 2883 recursive_directory_iterator& operator=(const recursive_directory_iterator&); 2884 2885 recursive_directory_iterator& operator++(); 2886 recursive_directory_iterator& increment(system::error_code& ec); 2887 2888 void pop(); 2889 void pop(system::error_code& ec); 2890 void disable_recursion_pending(bool value = true) noexcept; 2891 2892 // deprecated modifiers 2893 void no_push(bool value = true); 2894 2895 // other members as required by 2896 // C++ Std, Input iterators [input.iterators] 2897 2898 private: 2899<i><b> // actual data members will probably be stored in a shared object, 2900 // or some similar mechanism, to achieve the required input iterator 2901 // copy semantics</b></i> 2902 int m_depth; <b><i>// for exposition only</i></b> 2903 bool m_recursion_pending; <i><b>// for exposition only</b></i> 2904 <a href="#directory_options">directory_options</a> m_options; <i><b>// for exposition only</b></i> 2905 }; 2906 2907 } // namespace filesystem 2908} // namespace boost</pre> 2909 2910<p>The behavior of a <code>recursive_directory_iterator</code> is the same 2911as a <code>directory_iterator</code> unless otherwise specified.</p> 2912<ul> 2913 <li>Incrementing a <code>recursive_directory_iterator</code> pointing to a 2914 directory causes that directory itself to be iterated over, as specified by 2915 the <code>operator++</code> and <code>increment</code> functions.<br> 2916 </li> 2917 <li>When a <code>recursive_directory_iterator</code> reaches the end of the directory currently being iterated 2918 over, or when <code>pop()</code> is called, <code>m_depth</code> is 2919 decremented, and iteration of the parent directory continues.</li> 2920</ul> 2921<pre>recursive_directory_iterator() noexcept;</pre> 2922<blockquote> 2923 2924<p><i>Effects:</i> Constructs the end iterator.</p> 2925 2926</blockquote> 2927 2928<pre>explicit recursive_directory_iterator(const path& p, <a href="#directory_options">directory_options</a> opts = directory_options::none); 2929recursive_directory_iterator(const path& p, <a href="#directory_options">directory_options</a> opts, system::error_code& ec); 2930explicit recursive_directory_iterator(const path& p, <a href="#symlink_option">symlink_option</a> opts = symlink_option::none); 2931recursive_directory_iterator(const path& p, <a href="#symlink_option">symlink_option</a> opts, system::error_code& ec); 2932recursive_<code>directory_iterator(</code>const path& p, system::error_code& ec<code>);</code></pre> 2933<blockquote> 2934 2935<p><i>Effects:</i> Constructs an iterator representing the first 2936entry in the directory <code>p</code> resolves to, if any; otherwise, the end iterator.</p> 2937 2938<p><i>Postcondition: </i>Unless the end iterator was constructed,<i> </i><code>depth() == 0 && recursion_pending() == true && m_options == opts</code>. 2939For the signature without the <code>opts</code> argument, <code>opts</code> is assumed to be <code>directory_options::none</code>.</p> 2940 2941<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 2942 2943<p>[<i>Note:</i> To iterate over the current directory, use <code>recursive_directory_iterator(".")</code> rather than <code>recursive_directory_iterator("")</code>. <i>—end note</i>]</p> 2944 2945<p>[<i>Note:</i> By default, <code>recursive_directory_iterator</code> does not 2946follow directory symlinks. To follow directory symlinks, specify <code>directory_options::follow_directory_symlink</code> in <code>opts</code>. <i>—end note</i>]</p> 2947</blockquote> 2948<pre>int depth() const noexcept; 2949int level() const noexcept;</pre> 2950<blockquote> 2951 <p><i>Requires:</i> <code>*this != recursive_directory_iterator()</code>.</p> 2952 <p><i>Returns:</i> <code>m_depth</code>.</p> 2953</blockquote> 2954<pre>bool recursion_pending() const noexcept;</pre> 2955<blockquote> 2956 <p><i>Requires:</i> <code>*this != recursive_directory_iterator()</code>.</p> 2957 <p><i>Returns:</i> <code>m_recursion_pending</code>.</p> 2958</blockquote> 2959<pre>bool no_push_pending() const noexcept;</pre> 2960<blockquote> 2961 <p><i>Requires:</i> <code>*this != recursive_directory_iterator()</code>.</p> 2962 <p><i>Returns:</i> <code>!recursion_pending()</code>.</p> 2963</blockquote> 2964<pre><code>recursive_directory_iterator</code>& <a name="recursive_directory_iterator-increment">operator++</a>(); 2965recursive_directory_iterator& increment(system::error_code& ec);</pre> 2966<blockquote> 2967 2968<p><i>Effects:</i> As specified by the C++ Standard, 24.1.1 Input iterators [input.iterators], 2969except:</p> 2970 2971<ul> 2972 <li> 2973 2974<p>if <code>recursion_pending() && is_directory(this->status()) 2975&& (!is_symlink(this->symlink_status()) || (m_options & directory_options::follow_directory_symlink) != 0)</code> then: 2976 <ul> 2977 <li> 2978 <p>directory <code>(*this)->path()</code> is opened and recursively iterated into and <code>m_depth</code> is incremented;</p> 2979 </li> 2980 <li> 2981 <p>if opening the directory fails with a <code>permission_denied</code> error and <code>(m_options & directory_options::skip_permission_denied) != 0</code>, 2982 increment the iterator on the current level and ignore the error (the operation completes successfully).</p> 2983 </li> 2984 </ul> 2985</p> 2986 2987 </li> 2988 <li>if there are no more directory entries at this level then <code>m_depth</code> 2989is decremented and iteration of the parent directory resumes.</li> 2990</ul> 2991 2992<p>If the operation completes with an error, then 2993 <ul> 2994 <li>if <code>(m_options & directory_options::pop_on_error) != 0</code>, the iterator is left in a state as if after repeatedly calling <code>pop()</code> until it succeeds or the iterator becomes equal to an end iterator; any <code>pop()</code> failures are not reported to the caller;</li> 2995 <li>otherwise, the iterator is left equal to an end iterator.</li> 2996 </ul> 2997</p> 2998 2999<p><i>Postcondition:</i> <code>recursion_pending() == true</code>.</p> 3000 3001<p><i>Returns:</i> <code>*this</code>.</p> 3002 3003<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3004 3005</blockquote> 3006<pre>void pop(); 3007void pop(system::error_code& ec);</pre> 3008<blockquote> 3009 <p><i>Requires:</i> <code>*this != recursive_directory_iterator()</code>.</p> 3010 <p><i>Effects:</i> If <code>depth() == 0</code>, set <code>*this</code> to <code>recursive_directory_iterator()</code>. 3011 Otherwise, <code>--m_depth</code>, cease iteration of the directory currently being 3012 iterated over, and continue iteration over the parent directory.</p> 3013 <p>If the operation completes with an error, then 3014 <ul> 3015 <li>if <code>(m_options & directory_options::pop_on_error) != 0</code>, the iterator is left in a state as if after repeatedly calling <code>pop()</code> until it succeeds or the iterator becomes equal to an end iterator; any <code>pop()</code> failures are not reported to the caller;</li> 3016 <li>otherwise, the iterator is left equal to an end iterator.</li> 3017 </ul> 3018 </p> 3019</blockquote> 3020<pre>void disable_recursion_pending(bool value = true) noexcept; 3021void no_push(bool value = true) noexcept;</pre> 3022<blockquote> 3023 <p><i>Requires:</i> <code>*this != recursive_directory_iterator()</code>.</p> 3024 <p><i>Postcondition:</i> <code>recursion_pending() == !value</code>.</p> 3025 <p>[<i>Note:</i> These functions are used to prevent 3026 unwanted recursion into a directory. <i>—end note</i>]</p> 3027</blockquote> 3028<h3><a name="recursive_directory_iterator-non-member-functions"><code>recursive_directory_iterator</code> non-member functions</a></h3> 3029<pre>const recursive_directory_iterator& begin(const recursive_directory_iterator& iter);</pre> 3030<blockquote> 3031 <p><i>Returns: </i><code>iter</code>.</p> 3032</blockquote> 3033<pre>recursive_directory_iterator end(const recursive_directory_iterator&);</pre> 3034<blockquote> 3035 <p><i>Returns: </i><code>recursive_directory_iterator()</code>.</p> 3036</blockquote> 3037<h2><a name="Operational-functions">Operational functions</a> [fs.op.funcs]</h2> 3038<p>Operational functions query or modify files, including directories, in external 3039storage.</p> 3040<p>Operational functions access a file by resolving an 3041object of class <code>path</code> to a particular file in a file hierarchy. The 3042path is resolved as if by the ISO/IEC 9945 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_11">Pathname Resolution</a> mechanism.</p> 3043<p>[<i>Note: </i>Because hardware failures, network failures, <a href="#file-system-race">file system races</a>, and many 3044other kinds of errors occur frequently in file system operations, users should be aware 3045that any filesystem operational function, no matter how apparently innocuous, may encounter 3046an error. See <a href="#Error-reporting">Error reporting</a>. <i>—end note</i>]</p> 3047<pre>path <a name="absolute">absolute</a>(const path& p, const path& base=current_path()); 3048path absolute(const path& p, system::error_code& ec); 3049path absolute(const path& p, const path& base, system::error_code& ec);</pre> 3050 <blockquote> 3051 <p><i>Returns:</i> A <a href="#Absolute-path">absolute path</a> composed according to the 3052 following table</p> 3053 <table border="1" cellpadding="5" cellspacing="0" bordercolor="#111111" style="border-collapse: collapse"> 3054 <tr> 3055 <td align="center"> </td> 3056 <td align="center"><b><code>p.<br> 3057 has_root_directory()</code></b></td> 3058 <td align="center"><b><code>!p.has_root_directory()</code></b></td> 3059 </tr> 3060 <tr> 3061 <td align="center"><b><code>p.has_root_name()</code></b></td> 3062 <td align="left"><code>return p</code></td> 3063 <td align="left"><code>return<br> 3064 p.root_name()<br> 3065 / absolute(base)<br> 3066 .root_directory()<br> 3067 / absolute(base)<br> 3068 .relative_path()<br> 3069 / p.relative_path()</code></td> 3070 </tr> 3071 <tr> 3072 <td align="center"><b><code>!p.has_root_name()</code></b></td> 3073 <td align="left"><code>return<br> 3074 absolute(base)<br> 3075 .root_name()<br> 3076 / p</code></td> 3077 <td align="left"><code>return absolute(base)<br> 3078 / p</code></td> 3079 </tr> 3080 </table> 3081 <p>For the overload without a <code>base</code> argument, <code>base</code> is <code>current_path()</code>.</p> 3082 <p>[<i>Note:</i> For the returned path, <code>rp</code>, <code>rp.is_absolute()</code> is <code>true</code>. <i>—end note</i>]</p> 3083 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3084</blockquote> 3085<pre>path <a name="canonical">canonical</a>(const path& p, const path& base = current_path()); 3086path canonical(const path& p, system::error_code& ec); 3087path canonical(const path& p, const path& base, system::error_code& ec);</pre> 3088<blockquote> 3089<p><i>Overview:</i> Converts <code>p</code>, which must exist, to an absolute 3090path that has no symbolic link, <a href="#Dot">dot</a>, 3091or <a href="#Dot">dot-dot</a> elements. </p> 3092<p><i>Returns:</i> A <a href="#canonical-path">canonical path</a> that refers to 3093the same file system object as <code>absolute(p, base)</code>. For the overload 3094without a <code>base</code> argument, <code>base</code> is <code>current_path()</code>.</p> 3095 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3096 3097 <p><i>Remarks:</i> <code>!exists(p)</code> is an error.</p> 3098 3099 <p>[<i>Note:</i> Canonical pathnames allow security checking of a path (eg. 3100 does this path live in /home/goodguy or /home/badguy?) —end note]</p> 3101 3102</blockquote> 3103<pre>void copy(const path& from, const path& to); 3104void copy(const path& from, const path& to, system::error_code& ec);</pre> 3105<blockquote> 3106 <p><i>Effects: </i><code>copy(from, to, copy_options::none</code><i>[</i><code>, ec</code><i>]</i><code>)</code>.</p> 3107 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3108</blockquote> 3109<pre>void <a name="copy">copy</a>(const path& from, const path& to, <a href="#copy_options">copy_options</a> options); 3110void copy(const path& from, const path& to, <a href="#copy_options">copy_options</a> options, system::error_code& ec);</pre> 3111<blockquote> 3112 <p><i>Precondition:</i> <code>options</code> must contain at most one option from each of the following groups: 3113 <ul> 3114 <li><code>copy_options::skip_existing</code>, <code>copy_options::overwrite_existing</code> or <code>copy_options::update_existing</code>;</li> 3115 <li><code>copy_options::recursive</code>;</li> 3116 <li><code>copy_options::copy_symlinks</code> or <code>copy_options::skip_symlinks</code>;</li> 3117 <li><code>copy_options::directories_only</code>, <code>copy_options::create_symlinks</code> or <code>copy_options::create_hard_links</code>.</li> 3118 </ul></p> 3119 <p><i>Effects:</i> Let <code>f</code> and <code>t</code> be <code>file_status</code> objects obtained the following way: 3120 <ul> 3121 <li>If <code>(options & (copy_options::create_symlinks | copy_options::skip_symlinks)) != copy_options::none</code> then <code>f = <a href="#symlink_status">symlink_status</a>(from)</code> and <code>t = <a href="#symlink_status">symlink_status</a>(to)</code>;</li> 3122 <li>Otherwise, if <code>(options & copy_options::copy_symlinks) != copy_options::none</code> then <code>f = <a href="#symlink_status">symlink_status</a>(from)</code> and <code>t = <a href="#status">status</a>(to)</code>;</li> 3123 <li>Otherwise, <code>f = <a href="#status">status</a>(from)</code> and <code>t = <a href="#status">status</a>(to)</code>.</li> 3124 </ul> 3125 Then, report an error if: 3126 <ul> 3127 <li><code>!exists(f)</code>, or</li> 3128 <li><code>equivalent(from, to)</code>, or</li> 3129 <li><code>is_other(f) || is_other(t)</code>, or</li> 3130 <li><code>is_directory(f) && is_regular_file(t)</code>.</li> 3131 </ul> 3132 Otherwise, if <code>is_symlink(f)</code>, then: 3133 <ul> 3134 <li>If <code>(options & copy_options::skip_symlinks) != copy_options::none</code> then return;</li> 3135 <li>Otherwise if <code>!exists(t) && (options & copy_options::copy_symlinks) != copy_options::none</code> then <code><a href="#copy_symlink">copy_symlink</a>(from, to)</code>;</li> 3136 <li>Otherwise report error.</li> 3137 </ul> 3138 Otherwise, if <code>is_regular_file(f)</code>, then: 3139 <ul> 3140 <li>If <code>(options & copy_options::directories_only) != copy_options::none</code> then return;</li> 3141 <li>Otherwise if <code>(options & copy_options::create_symlinks) != copy_options::none</code> then <code><a href="#create_symlink">create_symlink</a>(link, to)</code>, where <code>link</code> is determined as follows: 3142 <ul> 3143 <li>If <code>from.is_absolute()</code> then <code>link</code> equals to <code>from</code>;</li> 3144 <li>Otherwise, <code>link</code> is equivalent to <code><a href="#relative">relative</a>(<a href="#absolute">absolute</a>(to.parent_path()), <a href="#absolute">absolute</a>(from.parent_path())) / from.filename()</code>.</li> 3145 </ul> 3146 </li> 3147 <li>Otherwise if <code>(options & copy_options::create_hard_links) != copy_options::none</code> then <code><a href="#create_hard_link">create_hard_link</a>(from, to)</code>;</li> 3148 <li>Otherwise if <code>is_directory(t)</code> then <code><a href="#copy_file">copy_file</a>(from, to / from.filename(), options)</code>;</li> 3149 <li>Otherwise <code><a href="#copy_file">copy_file</a>(from, to, options)</code>.</li> 3150 </ul> 3151 Otherwise, if <code>is_directory(f)</code>, then: 3152 <ul> 3153 <li>If <code>(options & copy_options::create_symlinks) != copy_options::none</code> then report error with error code equal to <code>make_error_code(system::errc::is_a_directory)</code>;</li> 3154 <li>Otherwise if 3155 <ul> 3156 <li><code>(options & copy_options::recursive) != copy_options::none</code>, or</li> 3157 <li><code>options == copy_options::none</code> and this call to <code>copy</code> is not a recursive call from <code>copy</code></li> 3158 </ul> 3159 then: 3160 <ul> 3161 <li>If <code>!exists(t)</code>, then <code><a href="#create_directory">create_directory</a>(to, from)</code>.</li> 3162 <li>Then, iterate over files in <code>from</code> and for each <code>directory_entry x</code> obtained during iteration invoke <code>copy(x.path(), to / x.path().filename(), options)</code>.</li> 3163 </ul> 3164 </li> 3165 <li>Otherwise, return.</li> 3166 </ul> 3167 Otherwise, for all unsupported file types of <code>f</code> report error.</p> 3168 3169 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3170 3171</blockquote> 3172<pre>void <a name="copy_directory">copy_directory</a>(const path& from, const path& to); 3173void copy_directory(const path& from, const path& to, system::error_code& ec);</pre> 3174<blockquote> 3175 <p><i>Effects: </i>Creates directory <code>to</code>, with 3176 attributes copied from directory <code>from</code>. The set of attributes 3177 copied is operating system dependent.</p> 3178 3179 <p>[<i>Note:</i> For ISO 9945/POSIX based operating systems the 3180 attributes are those copied by native API <code>stat(from.c_str(), &from_stat)</code> 3181 followed by <code>mkdir(to.c_str(),from_stat.st_mode)</code>. For 3182 Windows based operating systems the attributes are those copied by native 3183 API <code>CreateDirectoryExW(from.c_str(), to.c_str(), 0)</code>. <i> 3184 —end note</i>]</td> 3185 3186 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3187 3188 <p>[<i>Note:</i> This operation is deprecated, use <a href="#create_directory">create_directory</a> instead. —end note]</p> 3189</blockquote> 3190 3191<pre>bool copy_file(const path& from, const path& to); 3192bool copy_file(const path& from, const path& to, system::error_code& ec);</pre> 3193<blockquote> 3194 <p><i>Effects: </i><code>return copy_file(from, to, copy_options::none</code><i>[</i><code>, ec</code><i>]</i><code>)</code>.</p> 3195 3196 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3197 3198</blockquote> 3199<pre>bool <a name="copy_file">copy_file</a>(const path& from, const path& to, <a href="#copy_options">copy_options</a> options); 3200bool copy_file(const path& from, const path& to, <a href="#copy_options">copy_options</a> options, system::error_code& ec); 3201bool copy_file(const path& from, const path& to, <a href="#copy_option">copy_option</a> options); 3202bool copy_file(const path& from, const path& to, <a href="#copy_option">copy_option</a> options, system::error_code& ec);</pre> 3203<blockquote> 3204 <p><i>Precondition:</i> At most one of <code>copy_options::skip_existing</code>, <code>copy_options::overwrite_existing</code> or <code>copy_options::update_existing</code> must be specified in <code>options</code>.</p> 3205 <p><i>Effects:</i> Report an error if: 3206 <ul> 3207 <li><code>!is_regular_file(from)</code>, or</li> 3208 <li><code>exists(to) && !is_regular_file(to)</code>, or</li> 3209 <li><code>exists(to) && equivalent(from, to)</code>, or</li> 3210 <li><code>exists(to) && (options & (copy_options::skip_existing | copy_options::overwrite_existing)) == copy_options::none</code>.</li> 3211 </ul> 3212 Otherwise, return successfully with no effect if: 3213 <ul> 3214 <li><code>exists(to) && (options & copy_options::skip_existing) != copy_options::none</code>, or</li> 3215 <li><code>exists(to) && (options & copy_options::update_existing) != copy_options::none</code> and last write time of <code>from</code> is more recent than that of <code>to</code>.</li> 3216 </ul> 3217 Otherwise, the contents and attributes of the file <code>from</code> resolves to are copied to the file <code>to</code> resolves to.</p> 3218 <p><i>Returns:</i> <code>true</code> if the file was copied without error, otherwise <code>false</code>.</p> 3219 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3220 <p>[<i>Note:</i> The overloads taking <a href="#copy_option"><code>copy_option</code></a> are deprecated. Their effect is equivalent to the corresponding overloads taking <a href="#copy_options"><code>copy_options</code></a> after casting the <code>options</code> argument to <a href="#copy_options"><code>copy_options</code></a>.]</p> 3221 <p>[<i>Note:</i> When <code>copy_options::update_existing</code> is specified, checking the write times of <code>from</code> and <code>to</code> may not be atomic with the copy operation. Another process may create or modify the file identified by <code>to</code> after the file modification times have been checked but before copying starts. In this case the target file will be overwritten.]</p> 3222</blockquote> 3223<pre>void <a name="copy_symlink">copy_symlink</a>(const path& existing_symlink, const path& new_symlink); 3224void copy_symlink(const path& existing_symlink, const path& new_symlink, system::error_code& ec);</pre> 3225<blockquote> 3226 <p><i>Effects: </i><code>create_symlink(read_symlink(existing_symlink</code><i>[</i><code>, ec</code><i>]</i><code>), new_symlink</code><i>[</i><code>, ec</code><i>]</i><code>)</code>.</p> 3227 3228 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3229 3230</blockquote> 3231<pre>bool <a name="create_directories">create_directories</a>(const path& p); 3232bool <a name="create_directories2">create_directories</a>(const path& p, system::error_code& ec);</pre> 3233<blockquote> 3234 <p><i>Effects:</i> Establishes the postcondition by calling <code> 3235 create_directory()</code> for any element of <code>p</code> that does not 3236 exist.</p> 3237 <p><i>Postcondition:</i> <code>is_directory(p)</code></p> 3238 <p><i>Returns:</i> <code>true</code> if a new directory was created, otherwise <code> 3239 false</code>.</p> 3240 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3241 <p><i>Complexity:</i> <i>O(n+1)</i> where <i>n</i> is the number of elements 3242 of <code>p</code> that do not exist.</p> 3243</blockquote> 3244<pre>bool <a name="create_directory">create_directory</a>(const path& p); 3245bool create_directory(const path& p, system::error_code& ec); 3246bool create_directory(const path& p, const path& existing); 3247bool create_directory(const path& p, const path& existing, system::error_code& ec);</pre> 3248<blockquote> 3249 <p><i>Effects:</i> Establishes the postcondition by attempting to create the 3250 directory <code>p</code> resolves to, as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/mkdir.html"> 3251 mkdir()</a></code>. For overloads without <code>existing</code> argument, the new directory is created with <code>S_IRWXU|S_IRWXG|S_IRWXO</code> mode. 3252 Overloads with <code>existing</code> argument obtain mode from <code>existing</code>, which must be a path to an existing directory. On Windows, 3253 <code>CreateDirectoryW(p.c_str(), NULL)</code> is used when <code>existing</code> is not specified and <code>CreateDirectoryExW(existing.c_str(), p.c_str(), NULL)</code> otherwise. 3254 Creation failure because <code>p</code> resolves to an existing directory shall not be 3255 treated as an error.</p> 3256 <p><i>Postcondition:</i> <code>is_directory(p)</code></p> 3257 <p><i>Returns:</i> <code>true</code> if a new directory was created, otherwise <code>false</code>.</p> 3258 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3259</blockquote> 3260<pre>void <a name="create_directory_symlink">create_directory_symlink</a>(const path& to, const path& new_symlink); 3261void create_directory_symlink(const path& to, const path& new_symlink, system::error_code& ec);</pre> 3262<blockquote> 3263 <p><i>Effects:</i> Establishes the postcondition, as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/symlink.html">symlink()</a></code>.</p> 3264 <p><i> 3265 Postcondition:</i> <code>new_symlink</code> resolves to a symbolic link file that 3266 contains an unspecified representation of <code>to</code>.</p> 3267 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3268 <p>[<i>Note:</i> Some operating systems, such as Windows, require symlink creation to 3269 identify that the link is to a directory. Portable code should use <code>create_directory_symlink()</code> to create directory symlinks rather than <code>create_symlink()</code> <i>—end note</i>]</p> 3270 <p>[<i>Note:</i> Some operating systems do not support symbolic links at all or support 3271 them only for regular files. 3272 Some file systems do not 3273 support 3274 symbolic links regardless of the operating system - the FAT file system used on 3275 memory cards and flash drives, for example. <i>—end note</i>]</p> 3276 </blockquote> 3277<pre>void <a name="create_hard_link">create_hard_link</a>(const path& to, const path& new_hard_link); 3278void <a name="create_hard_link2">create_hard_link</a>(const path& to, const path& new_hard_link, system::error_code& ec);</pre> 3279<blockquote> 3280 <p><i>Effects:</i> Establishes the postcondition, as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/link.html">link()</a></code>.</p> 3281 <p><i>Postcondition:</i></p> 3282 <ul> 3283 <li> <code>exists(to) && 3284 exists(</code><code>new_hard_link</code><code>) && equivalent(to, 3285 3286 </code><code>new_hard_link</code><code>)</code></li> 3287 <li>The contents of the file or directory 3288 <code>to</code> resolves to are unchanged.</li> 3289 </ul> 3290 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3291 <p>[<i>Note:</i> Some operating systems do not support hard links at all or support 3292 them only for regular files. Some file systems do not support hard 3293 links regardless of the operating system - the FAT file system used on memory 3294 cards and flash drives, for example. Some file systems limit the number of 3295 links per file. <i>—end note</i>]</p> 3296 </blockquote> 3297<pre>void <a name="create_symlink">create_symlink</a>(const path& to, const path& new_symlink); 3298void <a name="create_symlink2">create_symlink</a>(const path& to, const path& new_symlink, system::error_code& ec);</pre> 3299<blockquote> 3300 <p><i>Effects:</i> Establishes the postcondition, as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/symlink.html">symlink()</a></code>.</p> 3301 <p><i> 3302 Postcondition:</i> <code>new_symlink</code> resolves to a symbolic link file that 3303 contains an unspecified representation of <code>to</code>.</p> 3304 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3305 <p>[<i>Note:</i> Some operating systems do not support symbolic links at all or support 3306 them only for regular files. 3307 Some file systems do not 3308 support 3309 symbolic links regardless of the operating system - the FAT system used on 3310 memory cards and flash drives, for example. <i>—end note</i>]</p> 3311 </blockquote> 3312<pre>path <a name="current_path">current_path</a>(); 3313path <a name="current_path2">current_path</a>(system::error_code& ec);</pre> 3314<blockquote> 3315 <p><i>Returns:</i> The current working directory path, as if by ISO/IEC 3316 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/getcwd.html">getcwd()</a></code>. <code>is_absolute()</code> is true for the returned path.</p> 3317 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3318 <p>[<i>Note: </i>The <code>current_path()</code> name was chosen to emphasize that the return is a 3319 path, not just a single directory name.</p> 3320 <p>The current path as returned by many operating systems is a dangerous 3321 global variable. It may be changed unexpectedly by a third-party or system 3322 library functions, or by another thread. <i>—end note</i>]</p> 3323</blockquote> 3324<pre>void current_path(const path& p); 3325void current_path(const path& p, system::error_code& ec);</pre> 3326<blockquote> 3327 <p><i>Effects:</i> Establishes the postcondition, as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/chdir.html">chdir()</a></code>.</p> 3328<p><i>Postcondition:</i> <code>equivalent(p, current_path())</code>.</p> 3329<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3330 <p>[<i>Note: </i>The current path for many operating systems is a dangerous 3331 global state. It may be changed unexpectedly by a third-party or system 3332 library functions, or by another thread. <i>—end note</i>]</p> 3333</blockquote> 3334<pre>bool <a name="exists">exists</a>(file_status s) noexcept;</pre> 3335<blockquote> 3336 <p><i>Returns:</i> <code>status_known(s) && s.type() != file_not_found</code></p> 3337</blockquote> 3338<pre>bool <a name="exists2">exists</a>(const path& p); 3339bool <a name="exists3">exists</a>(const path& p, system::error_code& ec) noexcept;</pre> 3340<blockquote> 3341 <p><i>Returns:</i> <code>exists(status(p))</code> or <code>exists(status(p, ec))</code>, 3342 respectively. If ec != 0 and an error</p> 3343<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3344</blockquote> 3345<pre><code>bool <a name="equivalent">equivalent</a>(const path& p1, const path& p2); 3346bool <a name="equivalent2">equivalent</a>(const path& p1, const path& p2, system::error_code& ec);</code></pre> 3347<blockquote> 3348 <p><i>Effects:</i> Determines <code>file_status s1</code> and <code>s2</code>, as if by <code>status(p1)</code> and <code>status(p2)</code>, 3349 respectively.</p> 3350 <p><i>Returns:</i> <code>true</code>, if <code>sf1 == 3351 sf2</code> and <code>p1</code> and <code>p2</code> resolve to the same file 3352 system entity, else <code>false</code>.</p> 3353 <blockquote> 3354 <p>Two paths are considered to resolve to the same 3355 file system entity if two candidate entities reside on the same device at the 3356 same location. This is determined as if by the values of the ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">stat</a></code> structure<code>,</code> obtained as if by <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code> for the two paths, having equal <code>st_dev</code> values 3357 and equal <code>st_ino</code> values.</p> 3358 <p>[<i>Note:</i> ISO/IEC 9945 requires that <i>"st_dev</i> must be unique within a Local Area Network". Conservative 3359 ISO/IEC 9945 implementations may also wish to check for equal <code>st_size</code> and <code>st_mtime</code> values. <i>Windows</i> implementations may use <code>GetFileInformationByHandle()</code> as a surrogate for <code>stat()</code>, 3360 and consider "same" to be equal values for <code>dwVolumeSerialNumber</code>, <code>nFileIndexHigh</code>, <code>nFileIndexLow</code>, <code>nFileSizeHigh</code>, <code>nFileSizeLow</code>, <code>ftLastWriteTime.dwLowDateTime</code>, and <code>ftLastWriteTime.dwHighDateTime</code>. <i>—end note</i>]</p> 3361 </blockquote> 3362 <p><i>Throws:</i> <code>filesystem_error</code> if <code>(!exists(s1) && !exists(s2)) || (is_other(s1) && is_other(s2))</code>, 3363 otherwise as specified in <a href="#Error-reporting">Error reporting</a>.</p> 3364</blockquote> 3365 3366<pre>uintmax_t <a name="file_size">file_size</a>(const path& p); 3367uintmax_t <a name="file_size2">file_size</a>(const path& p, system::error_code& ec);</pre> 3368 3369<blockquote> 3370 <p><i>Returns:</i> If <code>exists(p) && is_regular_file(p)</code>, the size 3371 in bytes 3372 of the file <code>p</code> resolves to, determined as if by the value of 3373 the ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">stat</a></code> structure member <code>st_size</code> obtained as if by 3374 ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>. 3375 Otherwise, <code>static_cast<uintmax_t>(-1)</code>.</p> 3376 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3377</blockquote> 3378<pre>uintmax_t <a name="hard_link_count">hard_link_count</a>(const path& p); 3379uintmax_t hard_link_count(const path& p, system::error_code& ec);</pre> 3380<blockquote> 3381 3382 <p><i>Returns:</i> The number of hard links for <code>p</code>.</p> 3383 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3384 3385</blockquote> 3386 3387<pre>const path& <a name="initial_path">initial_path</a>(); 3388const path& <a name="initial_path2">initial_path</a>(<code>system::error_code& ec</code>);</pre> 3389<blockquote> 3390 <p><i>Returns:</i> <code>current_path()</code> as of the first call to <code>initial_path()</code>.</p> 3391 <p>[<i>Note:</i> <code>initial_path()</code> is not thread safe, and may return an undesirable result 3392 if called subsequent to a change to the current directory. These problems can 3393 be avoided by calling <code>initial_path()</code> immediately on entry to 3394 main(). <i>—end note</i>]</p> 3395 <p><i>Throws:</i> For the first call, as specified in <a href="#Error-reporting">Error reporting</a>. Subsequent calls throw nothing.</p> 3396</blockquote> 3397<pre>bool <code><a name="is_directory">is_directory</a></code>(file_status s) noexcept;</pre> 3398<blockquote> 3399 <p><i>Returns:</i> <code>s.type() == directory_file</code></p> 3400</blockquote> 3401<pre><code>bool <a name="is_directory2">is_directory</a>(const path& p); 3402bool <a name="is_directory3">is_directory</a>(const path& p, system::error_code& ec) noexcept;</code></pre> 3403<blockquote> 3404 <p><i>Returns:</i> <code>is_directory(status(p))</code> or <code>is_directory(status(p, ec))</code>, 3405 respectively.</p> 3406<p><i>Throws:</i> <code>filesystem_error</code>; overload with <code>error_code&</code> throws 3407nothing.</p> 3408</blockquote> 3409<pre><code>bool <a name="is_empty">is_empty</a>(const path& p); 3410bool <a name="is_empty2">is_empty</a></a>(const path& p, system::error_code& ec);</code></pre> 3411<blockquote> 3412 <p><i>Effects:</i> Determines <code>file_status s</code>, as if by <code>status(p, ec)</code>.</p> 3413 <p><i>Returns:</i> <code>is_directory(s)<br> 3414 ? directory_iterator(p) == directory_iterator()<br> 3415 : file_size(p) == 0;</code></p> 3416</blockquote> 3417<pre>bool <code><a name="is_regular_file">is_regular_file</a></code>(file_status s) noexcept;</pre> 3418<blockquote> 3419 <p><i>Returns:</i> <code>s.type() == regular_file</code></p> 3420</blockquote> 3421<pre><code>bool <a name="is_regular_file2">is_regular_file</a>(const path& p);</code></pre> 3422<blockquote> 3423 <p><i>Returns:</i> <code>is_regular_file(status(p))</code>.</p> 3424 <p><i>Throws:</i> <code>filesystem_error</code> if <code>status(p)</code> would throw <code>filesystem_error.</code></p> 3425 </blockquote> 3426<pre><code>bool <a name="is_regular_file3">is_regular_file</a>(const path& p, system::error_code& ec) noexcept;</code></pre> 3427<blockquote> 3428 <p><i>Effects:</i> Sets <code>ec</code> as if by <code>status(p, ec)</code>. [<i>Note:</i> <code>status_error</code>, <code>file_not_found</code> and <code>type_unknown</code> cases set <code>ec</code> to error values. To distinguish between cases, call the <code>status</code> function directly. <i>—end 3429 note</i>] </p> 3430 <p><i>Returns:</i> <code>is_regular_file(status(p, ec))</code>.</p> 3431</blockquote> 3432<pre>bool <a name="is_other">is_other</a>(file_status s) noexcept;</pre> 3433<blockquote> 3434 <p><i>Returns:</i> <code>return exists(s) && !is_regular_file(s) && !is_directory(s) && !is_symlink(s)</code></p> 3435</blockquote> 3436<pre><code>bool <a name="is_other2">is_other</a>(const path& p); 3437bool <a name="is_other3">is_other</a>(const path& p, system::error_code& ec) noexcept;</code></pre> 3438<blockquote> 3439 <p><i>Returns:</i> <code>is_other(status(p))</code> or <code>is_other(status(p, ec))</code>, 3440 respectively.</p> 3441 <p><i>Throws:</i> <code>filesystem_error</code>; overload with <code>error_code&</code> throws 3442 nothing.</p> 3443</blockquote> 3444<pre>bool <a name="is_symlink">is_symlink</a>(file_status s) noexcept;</pre> 3445<blockquote> 3446 <p><i>Returns:</i> <code>s.type() == symlink_file</code></p> 3447</blockquote> 3448<pre><code>bool <a name="is_symlink2">is_symlink</a>(const path& p); 3449bool <a name="is_symlink3">is_symlink</a>(const path& p, system::error_code& ec) noexcept;</code></pre> 3450<blockquote> 3451 <p><i>Returns:</i> <code>is_symlink(symlink_status(p))</code> or <code>is_symlink(symlink_status(p, ec))</code>, 3452 respectively.</p> 3453 <p><i>Throws:</i> <code>filesystem_error</code>; overload with <code>error_code&</code> throws 3454 nothing.</p> 3455</blockquote> 3456<pre>std::time_t <a name="last_write_time">last_write_time</a>(const path& p); 3457std::time_t <a name="last_write_time2">last_write_time</a>(const path& p<code>, system::error_code& ec</code>);</pre> 3458<blockquote> 3459 <p><i>Returns:</i> The time of last data modification of <code>p</code>, determined as if by the 3460 value of the ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">stat</a></code> structure member <code>st_mtime</code> obtained 3461 as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>.</p> 3462 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3463</blockquote> 3464<pre>void <a name="last_write_time3">last_write_time</a>(const path& p, const std::time_t new_time); 3465void <a name="last_write_time4">last_write_time</a>(const path& p, const std::time_t new_time<code>, system::error_code& ec</code>);</pre> 3466<blockquote> 3467 <p><i>Effects:</i> Sets the time of last data modification of the file 3468 resolved to by <code>p</code> to <code>new_time</code>, as if by ISO/IEC 3469 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code> followed by 3470 ISO/IEC 9945 <a href="http://www.opengroup.org/onlinepubs/000095399/functions/utime.html"><code>utime()</code></a>.</p> 3471 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3472 <p>[<i>Note:</i> A postcondition of <code>last_write_time(p) == new_time</code> is not specified since it might not hold for file systems 3473 with coarse time granularity. <i>—end note</i>]</p> 3474</blockquote> 3475<pre>void <a name="permissions">permissions</a>(const path& p, <a href="#symlink_perms">perms</a> prms); 3476void permissions(const path& p, <a href="#symlink_perms">perms</a> prms, system::error_code& ec);</pre> 3477<blockquote> 3478 <p> 3479 <i>Requires:</i> <code>!((prms & add_perms) && (prms & remove_perms))</code>.</p> 3480 <p><i>Effects:</i> Applies the effective permissions bits from <code>prms</code> to the file <code>p</code> resolves to, as if by 3481 ISO/IEC 9945 <code><a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/fchmodat.html">fchmodat()</a></code>. The effective permission bits are determined as 3482 specified by the following table. </p> 3483 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111"> 3484 <tr> 3485 <td><b>bits present in <code>prms</code></b></td> 3486 <td><b>Effective bits applied</b></td> 3487 </tr> 3488 <tr> 3489 <td>Neither <code>add_perms</code> nor <code>remove_perms</code></td> 3490 <td><code>prms & perms_mask</code></td> 3491 </tr> 3492 <tr> 3493 <td><code>add_perms</code></td> 3494 <td> 3495 <p><code>status(p).permissions() | (prms & <a href="#perms_mask">perms_mask</a>)</code> </td> 3496 </tr> 3497 <tr> 3498 <td><code>remove_perms</code></td> 3499 <td><code>status(p)</code><code>.permissions() & ~(prms & <a href="#perms_mask">perms_mask</a>) </code></td> 3500 </tr> 3501 </table> 3502 <p>[<i>Note:</i> Conceptually permissions are viewed as bits, but the actual 3503 implementation may use some other mechanism. -- <i>end note</i>]</p> 3504 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3505</blockquote> 3506<pre>path <a name="read_symlink">read_symlink</a>(const path& p); 3507path read_symlink(const path& p, system::error_code& ec);</pre> 3508<blockquote> 3509 <p><i>Returns:</i> If <code>p</code> resolves to a symbolic 3510 link, a <code>path</code> object containing the contents of that symbolic 3511 link. Otherwise an empty <code>path</code> object.</p> 3512 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>. [<i>Note:</i> It is an error if <code>p</code> does not 3513 resolve to a symbolic link. <i>—end note</i>]</p> 3514</blockquote> 3515<pre>path <a name="relative">relative</a>(const path& p, system::error_code& ec);</pre> 3516<blockquote> 3517 <p><i>Returns:</i> <code>relative(p, current_path(), ec)</code>.</p> 3518 <p><i>Throws:</i> As specified in Error reporting.</p> 3519</blockquote> 3520<pre>path relative(const path& p, const path& base=current_path()); 3521path relative(const path& p, const path& base, system::error_code& ec);</pre> 3522<blockquote> 3523 <p><i>Overview:</i> Returns <code>p</code> made relative to <code>base</code>. 3524 Treats empty or identical paths as corner cases, not errors. Resolves symlinks 3525 and normalizes both <code>p</code> and <code>base</code> before other 3526 processing.</p> 3527 <p><i>Returns:</i> <code><a href="#weakly_canonical">weakly_canonical</a>(p).<a href="#lex-relative">lexically_relative</a>(<a href="#weakly_canonical">weakly_canonical</a>(base))</code>. The second form returns <code>path()</code> 3528 if an error occurs.</p> 3529 <p><i>Throws:</i> As specified in Error reporting.</p> 3530</blockquote> 3531<pre>bool <a name="remove">remove</a>(const path& p); 3532bool <a name="remove2">remove</a>(const path& p, system::error_code& ec);</pre> 3533<blockquote> 3534 <p><i>Effects:</i> If <code>exists(symlink_status(p,ec))</code>, it is 3535 removed 3536 as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/remove.html">remove()</a></code>.</p> 3537 <blockquote> 3538 <p>[<i>Note:</i> A symbolic link is itself removed, rather than the file it 3539 resolves to being removed. <i>—end note</i>]</p> 3540 </blockquote> 3541 <p><i>Postcondition:</i> <code>!exists(symlink_status(p))</code>.</p> 3542 <p><i>Returns:</i> <code>false</code> if p did not exist in the first 3543 place, otherwise <code>true</code>.</p> 3544 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3545</blockquote> 3546<pre>uintmax_t <a name="remove_all">remove_all</a>(const path& p); 3547uintmax_t <a name="remove_all2">remove_all</a>(const path& p, system::error_code& ec);</pre> 3548<blockquote> 3549 <p><i>Effects:</i> Recursively deletes the contents of p if it exists, 3550 then deletes file <code>p</code> itself, 3551 as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/remove.html">remove()</a></code>.</p> 3552 <blockquote> 3553 <p>[<i>Note:</i> A symbolic link is itself removed, rather than the file it 3554 resolves to being removed. <i>—end note</i>]</p> 3555 </blockquote> 3556 <p><i>Postcondition:</i> <code>!exists(p)</code></p> 3557 <p><i>Returns:</i> The number of files removed.</p> 3558 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3559</blockquote> 3560<pre>void <a name="rename">rename</a>(const path& old_p, const path& new_p); 3561void <a name="rename2">rename</a>(const path& old_p, const path& new_p, system::error_code& ec);</pre> 3562<blockquote> 3563 <p><i>Effects:</i> Renames <code>old_p</code> to <code>new_p</code>, as if by 3564 ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/rename.html">rename()</a></code>.</p> 3565 <blockquote> 3566 <p>[<i>Note:</i> If <code>old_p</code> and <code>new_p</code> resolve to the 3567 same existing file, no action is taken. Otherwise, if <code>new_p</code> resolves to an 3568 existing non-directory file, it is removed, while if <code>new_p</code> resolves to an 3569 existing directory, it is removed if empty on ISO/IEC 9945 but is an error on Windows. A symbolic link is itself renamed, rather than 3570 the file it resolves to being renamed. <i>—end note</i>]</p> 3571 </blockquote> 3572 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3573</blockquote> 3574<pre>void <a name="resize_file">resize_file</a>(const path& p, uintmax_t new_size); 3575void <a name="resize_file2">resize_file</a>(const path& p, uintmax_t new_size, system::error_code& ec);</pre> 3576<blockquote> 3577<p><i>Postcondition:</i> <code>file_size() == new_size</code>.</p> 3578<p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3579 <p><i>Remarks:</i> Achieves its postconditions as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/truncate.html">truncate()</a></code>.</p> 3580</blockquote> 3581<pre>space_info <a name="space">space</a>(const path& p); 3582space_info <a name="space2">space</a>(const path& p, system::error_code& ec);</pre> 3583<blockquote> 3584 <p><i>Returns:</i> An object of type <code><a href="#space_info">space_info</a></code>. The value of the <code>space_info</code> object is determined as if by 3585 using ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/statvfs.html" 3586 style="text-decoration: none">statvfs()</a></code> to obtain an ISO/IEC 9945 struct 3587 <code><a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/statvfs.h.html" style="text-decoration: none">statvfs</a></code>, 3588 and then multiplying its <code>f_blocks</code>, <code>f_bfree</code>, 3589 and <code>f_bavail</code> members by its <code>f_frsize</code> member, 3590 and assigning the results to the <code>capacity</code>, <code>free</code>, 3591 and <code>available</code> members respectively. Any members for which the 3592 value cannot be determined shall be set to -1.</p> 3593 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3594</blockquote> 3595<pre><a href="#file_status">file_status</a> <a name="status">status</a>(const path& p);</pre> 3596<blockquote> 3597 <p><i>Effects: </i>As if:</p> 3598 <blockquote> 3599 <pre>system::error_code ec; 3600file_status result = status(p, ec); 3601if (result == status_error) 3602 throw filesystem_error(<i>implementation-supplied-message</i>, p, ec); 3603return result;</pre> 3604 </blockquote> 3605 <p><i>Returns:</i> See above.</p> 3606 <p><i>Throws:</i> <code>filesystem_error</code>. 3607[<i>Note:</i> <code>result</code> values of <code>file_status(file_not_found)</code>and <code>file_status(type_unknown)</code> are not considered failures and do not 3608 cause an exception to be 3609thrown.<i> —end note</i>] </p> 3610 </blockquote> 3611<pre><a href="#file_status">file_status</a> <a name="status2">status</a>(const path& p, system::error_code& ec) noexcept;</pre> 3612<blockquote> 3613 <p><i>Effects: </i></p> 3614 <blockquote> 3615 <p>If possible, determines the attributes 3616 of the file <code>p</code> resolves to, as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/stat.html">stat()</a></code>.</p> 3617 If, during attribute determination, the underlying file system API reports 3618 an error, sets <code>ec</code> to indicate the specific error reported. 3619 Otherwise, <code>ec.clear()</code>.<blockquote> 3620 <p>[<i>Note:</i> This allows users to inspect the specifics of underlying 3621 API errors even when the value returned by <code>status()</code> is not <code>file_status(status_error)</code>. <i>—end note</i>]</p> 3622 </blockquote> 3623 </blockquote> 3624 <p><i>Returns:</i></p> 3625 <blockquote> 3626 <p>If <code>ec != error_code()</code>:</p> 3627 <ul> 3628 <li>If the specific error indicates that <code>p</code> cannot be resolved 3629 because some element of the path does not exist, return <code> 3630 file_status(file_not_found)</code>. [<i>Note:</i> ISO/IEC 9945 errors that 3631 indicate this are ENOENT or ENOTDIR. Windows equivalents 3632 include ERROR_FILE_NOT_FOUND, ERROR_PATH_NOT_FOUND, ERROR_INVALID_NAME, 3633 ERROR_INVALID_PARAMETER, ERROR_BAD_PATHNAME, and ERROR_BAD_NETPATH. <i>-- 3634 end note</i>]<br> 3635 </li> 3636 <li>Otherwise, if the specific error indicates that <code>p</code> can be resolved 3637 but the attributes cannot be determined, return <code> 3638 file_status(type_unknown)</code>. [<i>Note: </i>For example, Windows 3639 ERROR_SHARING_VIOLATION errors. For ISO/IEC 9945, the case never arises. <i>—end 3640 note</i>]<br> 3641 </li> 3642 <li>Otherwise, return <code> 3643 file_status(status_error)</code>.</li> 3644 </ul> 3645 <blockquote> 3646 <p>[<i>Note:</i> These semantics distinguish between <code>p</code> being known not to exist, <code>p</code> existing but not being able to determine its attributes, 3647 and there being an error that prevents even knowing if <code>p</code> exists. These 3648 distinctions are important to some use cases. <i>—end note</i>]</p> 3649 </blockquote> 3650 <p>Otherwise,</p> 3651 <ul> 3652 <li>If the attributes indicate a regular file, as if by ISO/IEC 9945 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISREG()</a>, 3653 return <code> 3654 file_status(regular_file)</code>. [<i>Note:</i> <code> 3655regular_file</code> implies appropriate <code><fstream></code> operations 3656 would succeed, assuming no hardware, permission, access, or file system 3657 race 3658 errors. Lack of 3659<code>regular_file</code> does not necessarily imply <code><fstream></code> operations would 3660fail on a directory. 3661<i>—end note</i>]<br> 3662 </li> 3663 <li>Otherwise, if the attributes indicate a directory, as if by ISO/IEC 9945 3664 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISDIR()</a>, 3665 return <code> 3666 file_status(directory_file)</code>. [<i>Note:</i> <code>directory_file</code> implies <code> 3667directory_iterator(p)</code>would succeed. 3668<i>—end note</i>]<br> 3669 </li> 3670 <li>Otherwise, if the attributes indicate a block special file, as if by ISO/IEC 9945 3671 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISBLK()</a>, 3672 return <code> 3673 file_status(block_file)</code>.<br> 3674 </li> 3675 <li>Otherwise, if the attributes indicate a character special file, as if by ISO/IEC 9945 3676 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISCHR()</a>, 3677 return <code> 3678 file_status(character_file)</code>.<br> 3679 </li> 3680 <li>Otherwise, if the attributes indicate a fifo or pipe file, as if by 3681 ISO/IEC 9945 3682 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISFIFO()</a>, 3683 return <code> 3684 file_status(fifo_file)</code>.<br> 3685 </li> 3686 <li>Otherwise, if the attributes indicate a socket, as if by ISO/IEC 3687 9945 3688 <a href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISSOCK()</a>, 3689 return <code> 3690 file_status(socket_file)</code>.<br> 3691 </li> 3692 <li>Otherwise, return <code> 3693 file_status(type_unknown)</code>.</li> 3694 </ul> 3695 </blockquote> 3696 <p><i>Remarks:</i> If a symbolic link is encountered during pathname 3697 resolution, 3698 pathname resolution continues using the contents of the symbolic link.</p> 3699</blockquote> 3700<pre>bool <a name="status_known">status_known</a>(file_status s) noexcept;</pre> 3701<blockquote> 3702 <p><i>Returns:</i> <code>s.type() != status_error</code></p> 3703</blockquote> 3704<pre>file_status <a name="symlink_status">symlink_status</a>(const path& p); 3705file_status <a name="symlink_status2">symlink_status</a>(const path& p, system::error_code& ec) noexcept;</pre> 3706<blockquote> 3707 <p><i>Effects:</i> Same as <a href="#status">status()</a>, above, 3708 except that the attributes 3709 of <code>p</code> are determined as if by ISO/IEC 9945 <code><a href="http://www.opengroup.org/onlinepubs/000095399/functions/lstat.html">lstat()</a></code>.</p> 3710</blockquote> 3711<blockquote> 3712 <p><i>Returns:</i> Same as <a href="#status">status()</a>, above, except 3713 that if the attributes indicate a symbolic link, as if by ISO/IEC 9945 <a class="external" href="http://www.opengroup.org/onlinepubs/000095399/basedefs/sys/stat.h.html">S_ISLNK()</a>, return <code>file_status(symlink_file)</code>.</p> 3714 <p><i>Remarks:</i> Pathname resolution terminates if <code>p</code> names a symbolic link.</p> 3715 <p><i>Throws:</i> <code>filesystem_error</code>; overload with <code>error_code&</code> throws 3716 nothing.</p> 3717</blockquote> 3718<pre>path <a name="system_complete">system_complete</a>(const path& p); 3719path <a name="system_complete2">system_complete</a>(const path& p, system::error_code& ec);</pre> 3720<blockquote> 3721 <p><i>Effects:</i> Composes an absolute path from <code>p</code>, using the 3722 same rules used by the operating system to resolve a path passed as the 3723 filename argument to standard library open functions.</p> 3724 <p><i>Returns:</i> The composed path.</p> 3725 <p><i>Postcondition:</i> For the returned path, <code>rp</code>, <code>rp.is_absolute()</code> is true.</p> 3726 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3727 <p>[<i>Note:</i> For ISO/IEC 9945, <code>system_complete(p)</code> has the same semantics as <code><a href="#absolute">absolute</a>(p, <a href="#current_path">current_path</a>())</code>.</p> 3728 <p><a name="windows_effects">For <i>Windows</i></a>, <code>system_complete(p)</code> has the 3729 same semantics as <code><a href="#absolute">absolute</a>(p, <a href="#current_path">current_path</a>())</code> if <code>p.is_absolute() || !p.has_root_name()</code> or <code>p</code> and <code>base</code> have the same <code>root_name()</code>. 3730 Otherwise it acts like <code><a href="#absolute">absolute</a>(p, kinky)</code>, where <code>kinky</code> is the current directory for the <code>p.root_name()</code> drive. This will 3731 be the current directory of that drive the last time it was set, and thus may 3732 be <b>residue left over from a prior program</b> run by the command 3733 processor! Although these semantics are often useful, they are also very 3734 error-prone.</p> 3735</blockquote> 3736<pre>path <a name="temp_directory_path">temp_directory_path</a>(); 3737path temp_directory_path(system::error_code& ec);</pre> 3738<blockquote> 3739 <p><i>Returns:</i> A directory path suitable for temporary files under the 3740 conventions of the operating system. The specifics of how this path is 3741 determined are implementation defined. An error shall be reported if<code> !exists(p) 3742 || !is_directory(p)</code>, where <code>p</code> is the path to be returned.</p> 3743 <p>ISO/IEC 9945: The path supplied by the first environment variable found in the 3744 list TMPDIR, TMP, TEMP, TEMPDIR. If none of these are found, <code>"/tmp"</code>, 3745 or, if macro <code>__ANDROID__ </code>is defined, <code>"/data/local/tmp"</code>.</p> 3746 <p><i>Windows:</i> The path reported by the <i>Windows</i> <code>GetTempPath</code> API function.</p> 3747 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3748 <p>[<i>Note: </i>The <code>temp_directory_path()</code> name was chosen to emphasize that the return is a 3749 path, not just a single directory name. <i>—end note</i>]</p> 3750</blockquote> 3751<pre>path <a name="unique_path">unique_path</a>(const path& model="%%%%-%%%%-%%%%-%%%%"); 3752path unique_path(const path& model, system::error_code& ec);</pre> 3753<blockquote> 3754 <p>The <code>unique_path</code> function generates a path name suitable for 3755 creating temporary files, including directories. The name is based 3756 on a model that uses the percent sign character to specify replacement by a 3757 random hexadecimal digit. [<i>Note:</i> The more bits of randomness in the 3758 generated path name, the less likelihood of prior existence or being guessed. 3759 Each replacement hexadecimal digit in the model adds four bits of randomness. 3760 The default model thus provides 64 bits of randomness. This is sufficient for 3761 most applications. <i>—end note</i>]</p> 3762 <p><i>Returns:</i> A path identical to <code>model</code>, except that each 3763 occurrence of a percent sign character is replaced by a random hexadecimal 3764 digit character in the range 0-9, a-f.</p> 3765 <p><i>Throws:</i> As specified in <a href="#Error-reporting">Error reporting</a>.</p> 3766 <p><i>Remarks:</i> Implementations are encouraged to obtain the required 3767 randomness via a <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator">cryptographically secure pseudo-random number generator</a>, such as one 3768 provided by the operating system. [<i>Note</i>: Such generators may block 3769 until sufficient entropy develops. <i>—end note</i>]</p> 3770</blockquote> 3771<pre>path <a name="weakly_canonical">weakly_canonical</a>(const path& p); 3772path weakly_canonical(const path& p, system::error_code& ec);</pre> 3773<blockquote> 3774 <p><i>Overview:</i> Returns <code>p</code> with symlinks resolved and the 3775 result normalized.</p> 3776 <p><i>Returns: </i>A path composed of the result of calling the <code> 3777 canonical</code> function on a path composed of the leading elements of <code> 3778 p</code> that exist, if any, followed by the elements of <code>p</code> that 3779 do not exist, if any.</p> 3780 <p><i>Postcondition:</i> The returned path is in 3781 <a href="#normal-form"> 3782 normal form</a>.</p> 3783 <p><i>Remarks:</i> Uses <code>operator/=</code> to compose the returned path. 3784 Uses the <code>status</code> function to determine existence.</p> 3785 <p><i>Remarks:</i> Implementations are encouraged to avoid unnecessary 3786 normalization such as when <code>canonical</code> has already been called on 3787 the entirety of <code>p</code>.</p> 3788 <p><i>Throws:</i> As specified in Error reporting.</p> 3789</blockquote> 3790<hr> 3791 3792<!-- generate-section-numbers=false --> 3793 3794 3795<h3><a name="File-streams">File streams</a> - 3796<a href="../../../boost/filesystem/fstream.hpp"><boost/filesystem/fstream.hpp></a></h3> 3797<p>Replacements are provided for the file stream classes from the C++ standard 3798library's <code><fstream></code> header. These replacement classes 3799publicly inherit from the standard library classes. In the Boost.Filesystem 3800version, constructors and open functions take <code>const path&</code> arguments 3801instead of <code> 3802const char*</code> arguments. There are no other differences in syntax or 3803semantics.</p> 3804<pre>namespace boost 3805{ 3806 namespace filesystem 3807 { 3808 template < class charT, class traits = std::char_traits<charT> > 3809 class basic_filebuf : public std::basic_filebuf<charT,traits> 3810 { 3811 public: 3812 basic_filebuf<charT,traits>* 3813 open(const path& p, std::ios_base::openmode mode); 3814 }; 3815 3816 template < class charT, class traits = std::char_traits<charT> > 3817 class basic_ifstream : public std::basic_ifstream<charT,traits> 3818 { 3819 public: 3820 explicit basic_ifstream(const path& p, std::ios_base::openmode mode=std::ios_base::in) 3821 void open(const path& p, std::ios_base::openmode mode=std::ios_base::in); 3822 }; 3823 3824 template < class charT, class traits = std::char_traits<charT> > 3825 class basic_ofstream : public std::basic_ofstream<charT,traits> 3826 { 3827 public: 3828 explicit basic_ofstream(const path& p, std::ios_base::openmode mode=std::ios_base::out); 3829 void open(const path& p, std::ios_base::openmode mode=std::ios_base::out); 3830 }; 3831 3832 template < class charT, class traits = std::char_traits<charT> > 3833 class basic_fstream : public std::basic_fstream<charT,traits> 3834 { 3835 public: 3836 explicit basic_fstream(const path& p, 3837 std::ios_base::openmode mode=std::ios_base::in | std::ios_base::out); 3838 void open(const path& p, 3839 std::ios_base::openmode mode=std::ios_base::in | std::ios_base::out); 3840 }; 3841 3842 typedef basic_filebuf<char> filebuf; 3843 typedef basic_ifstream<char> ifstream; 3844 typedef basic_ofstream<char> ofstream; 3845 typedef basic_fstream<char> fstream; 3846 3847 typedef basic_filebuf<wchar_t> wfilebuf; 3848 typedef basic_ifstream<wchar_t> wifstream; 3849 typedef basic_fstream<wchar_t> wfstream; 3850 typedef basic_ofstream<wchar_t> wofstream; 3851 3852 } // namespace filesystem 3853} // namespace boost</pre> 3854 3855 3856 3857<h2><a name="path-decomposition-table">Path decomposition table</a></h2> 3858<p>The table is generated by a program compiled with the Boost implementation.</p> 3859<p>Shaded entries indicate cases where ISO/IEC 9945 (POSIX) and Windows implementations yield different results. The top value is the 3860ISO/IEC 9945 result and the bottom value is the Windows result. <br> 3861<table border="1" cellspacing="0" cellpadding="5"> 3862<p> 3863<tr><td><b>Constructor<br>argument</b></td> 3864<td><b>Iteration<br>over<br>Elements</b></td> 3865<td><b><code>string()</code></b></td> 3866<td><b><code>generic_<br>string()</code></b></td> 3867<td><b><code>root_<br>path()</code></b></td> 3868<td><b><code>root_<br>name()</code></b></td> 3869<td><b><code>root_<br>directory()</code></b></td> 3870<td><b><code>relative_<br>path()</code></b></td> 3871<td><b><code>parent_<br>path()</code></b></td> 3872<td><b><code>filename()</code></b></td> 3873</tr> 3874<tr> 3875<td><font size="-1"><i>empty</i></font></td> 3876<td><font size="-1"><i>empty</i></font></td> 3877<td><font size="-1"><i>empty</i></font></td> 3878<td><font size="-1"><i>empty</i></font></td> 3879<td><font size="-1"><i>empty</i></font></td> 3880<td><font size="-1"><i>empty</i></font></td> 3881<td><font size="-1"><i>empty</i></font></td> 3882<td><font size="-1"><i>empty</i></font></td> 3883<td><font size="-1"><i>empty</i></font></td> 3884<td><font size="-1"><i>empty</i></font></td> 3885</tr> 3886<tr> 3887<td><code>.</code></td> 3888<td><code>.</code></td> 3889<td><code>.</code></td> 3890<td><code>.</code></td> 3891<td><font size="-1"><i>empty</i></font></td> 3892<td><font size="-1"><i>empty</i></font></td> 3893<td><font size="-1"><i>empty</i></font></td> 3894<td><code>.</code></td> 3895<td><font size="-1"><i>empty</i></font></td> 3896<td><code>.</code></td> 3897</tr> 3898<tr> 3899<td><code>..</code></td> 3900<td><code>..</code></td> 3901<td><code>..</code></td> 3902<td><code>..</code></td> 3903<td><font size="-1"><i>empty</i></font></td> 3904<td><font size="-1"><i>empty</i></font></td> 3905<td><font size="-1"><i>empty</i></font></td> 3906<td><code>..</code></td> 3907<td><font size="-1"><i>empty</i></font></td> 3908<td><code>..</code></td> 3909</tr> 3910<tr> 3911<td><code>foo</code></td> 3912<td><code>foo</code></td> 3913<td><code>foo</code></td> 3914<td><code>foo</code></td> 3915<td><font size="-1"><i>empty</i></font></td> 3916<td><font size="-1"><i>empty</i></font></td> 3917<td><font size="-1"><i>empty</i></font></td> 3918<td><code>foo</code></td> 3919<td><font size="-1"><i>empty</i></font></td> 3920<td><code>foo</code></td> 3921</tr> 3922<tr> 3923<td><code>/</code></td> 3924<td><code>/</code></td> 3925<td><code>/</code></td> 3926<td><code>/</code></td> 3927<td><code>/</code></td> 3928<td><font size="-1"><i>empty</i></font></td> 3929<td><code>/</code></td> 3930<td><font size="-1"><i>empty</i></font></td> 3931<td><font size="-1"><i>empty</i></font></td> 3932<td><code>/</code></td> 3933</tr> 3934<tr> 3935<td><code>/foo</code></td> 3936<td><code>/,foo</code></td> 3937<td><code>/foo</code></td> 3938<td><code>/foo</code></td> 3939<td><code>/</code></td> 3940<td><font size="-1"><i>empty</i></font></td> 3941<td><code>/</code></td> 3942<td><code>foo</code></td> 3943<td><code>/</code></td> 3944<td><code>foo</code></td> 3945</tr> 3946<tr> 3947<td><code>foo/</code></td> 3948<td><code>foo,.</code></td> 3949<td><code>foo/</code></td> 3950<td><code>foo/</code></td> 3951<td><font size="-1"><i>empty</i></font></td> 3952<td><font size="-1"><i>empty</i></font></td> 3953<td><font size="-1"><i>empty</i></font></td> 3954<td><code>foo/</code></td> 3955<td><code>foo</code></td> 3956<td><code>.</code></td> 3957</tr> 3958<tr> 3959<td><code>/foo/</code></td> 3960<td><code>/,foo,.</code></td> 3961<td><code>/foo/</code></td> 3962<td><code>/foo/</code></td> 3963<td><code>/</code></td> 3964<td><font size="-1"><i>empty</i></font></td> 3965<td><code>/</code></td> 3966<td><code>foo/</code></td> 3967<td><code>/foo</code></td> 3968<td><code>.</code></td> 3969</tr> 3970<tr> 3971<td><code>foo/bar</code></td> 3972<td><code>foo,bar</code></td> 3973<td><code>foo/bar</code></td> 3974<td><code>foo/bar</code></td> 3975<td><font size="-1"><i>empty</i></font></td> 3976<td><font size="-1"><i>empty</i></font></td> 3977<td><font size="-1"><i>empty</i></font></td> 3978<td><code>foo/bar</code></td> 3979<td><code>foo</code></td> 3980<td><code>bar</code></td> 3981</tr> 3982<tr> 3983<td><code>/foo/bar</code></td> 3984<td><code>/,foo,bar</code></td> 3985<td><code>/foo/bar</code></td> 3986<td><code>/foo/bar</code></td> 3987<td><code>/</code></td> 3988<td><font size="-1"><i>empty</i></font></td> 3989<td><code>/</code></td> 3990<td><code>foo/bar</code></td> 3991<td><code>/foo</code></td> 3992<td><code>bar</code></td> 3993</tr> 3994<tr> 3995<td><code>//net</code></td> 3996<td><code>//net</code></td> 3997<td><code>//net</code></td> 3998<td><code>//net</code></td> 3999<td><code>//net</code></td> 4000<td><code>//net</code></td> 4001<td><font size="-1"><i>empty</i></font></td> 4002<td><font size="-1"><i>empty</i></font></td> 4003<td><font size="-1"><i>empty</i></font></td> 4004<td><code>//net</code></td> 4005</tr> 4006<tr> 4007<td><code>//net/foo</code></td> 4008<td><code>//net,/,foo</code></td> 4009<td><code>//net/foo</code></td> 4010<td><code>//net/foo</code></td> 4011<td><code>//net/</code></td> 4012<td><code>//net</code></td> 4013<td><code>/</code></td> 4014<td><code>foo</code></td> 4015<td><code>//net/</code></td> 4016<td><code>foo</code></td> 4017</tr> 4018<tr> 4019<td><code>///foo///</code></td> 4020<td><code>/,foo,.</code></td> 4021<td><code>///foo///</code></td> 4022<td><code>///foo///</code></td> 4023<td><code>/</code></td> 4024<td><font size="-1"><i>empty</i></font></td> 4025<td><code>/</code></td> 4026<td><code>foo///</code></td> 4027<td><code>///foo</code></td> 4028<td><code>.</code></td> 4029</tr> 4030<tr> 4031<td><code>///foo///bar</code></td> 4032<td><code>/,foo,bar</code></td> 4033<td><code>///foo///bar</code></td> 4034<td><code>///foo///bar</code></td> 4035<td><code>/</code></td> 4036<td><font size="-1"><i>empty</i></font></td> 4037<td><code>/</code></td> 4038<td><code>foo///bar</code></td> 4039<td><code>///foo</code></td> 4040<td><code>bar</code></td> 4041</tr> 4042<tr> 4043<td><code>/.</code></td> 4044<td><code>/,.</code></td> 4045<td><code>/.</code></td> 4046<td><code>/.</code></td> 4047<td><code>/</code></td> 4048<td><font size="-1"><i>empty</i></font></td> 4049<td><code>/</code></td> 4050<td><code>.</code></td> 4051<td><code>/</code></td> 4052<td><code>.</code></td> 4053</tr> 4054<tr> 4055<td><code>./</code></td> 4056<td><code>.,.</code></td> 4057<td><code>./</code></td> 4058<td><code>./</code></td> 4059<td><font size="-1"><i>empty</i></font></td> 4060<td><font size="-1"><i>empty</i></font></td> 4061<td><font size="-1"><i>empty</i></font></td> 4062<td><code>./</code></td> 4063<td><code>.</code></td> 4064<td><code>.</code></td> 4065</tr> 4066<tr> 4067<td><code>/..</code></td> 4068<td><code>/,..</code></td> 4069<td><code>/..</code></td> 4070<td><code>/..</code></td> 4071<td><code>/</code></td> 4072<td><font size="-1"><i>empty</i></font></td> 4073<td><code>/</code></td> 4074<td><code>..</code></td> 4075<td><code>/</code></td> 4076<td><code>..</code></td> 4077</tr> 4078<tr> 4079<td><code>../</code></td> 4080<td><code>..,.</code></td> 4081<td><code>../</code></td> 4082<td><code>../</code></td> 4083<td><font size="-1"><i>empty</i></font></td> 4084<td><font size="-1"><i>empty</i></font></td> 4085<td><font size="-1"><i>empty</i></font></td> 4086<td><code>../</code></td> 4087<td><code>..</code></td> 4088<td><code>.</code></td> 4089</tr> 4090<tr> 4091<td><code>foo/.</code></td> 4092<td><code>foo,.</code></td> 4093<td><code>foo/.</code></td> 4094<td><code>foo/.</code></td> 4095<td><font size="-1"><i>empty</i></font></td> 4096<td><font size="-1"><i>empty</i></font></td> 4097<td><font size="-1"><i>empty</i></font></td> 4098<td><code>foo/.</code></td> 4099<td><code>foo</code></td> 4100<td><code>.</code></td> 4101</tr> 4102<tr> 4103<td><code>foo/..</code></td> 4104<td><code>foo,..</code></td> 4105<td><code>foo/..</code></td> 4106<td><code>foo/..</code></td> 4107<td><font size="-1"><i>empty</i></font></td> 4108<td><font size="-1"><i>empty</i></font></td> 4109<td><font size="-1"><i>empty</i></font></td> 4110<td><code>foo/..</code></td> 4111<td><code>foo</code></td> 4112<td><code>..</code></td> 4113</tr> 4114<tr> 4115<td><code>foo/./</code></td> 4116<td><code>foo,.,.</code></td> 4117<td><code>foo/./</code></td> 4118<td><code>foo/./</code></td> 4119<td><font size="-1"><i>empty</i></font></td> 4120<td><font size="-1"><i>empty</i></font></td> 4121<td><font size="-1"><i>empty</i></font></td> 4122<td><code>foo/./</code></td> 4123<td><code>foo/.</code></td> 4124<td><code>.</code></td> 4125</tr> 4126<tr> 4127<td><code>foo/./bar</code></td> 4128<td><code>foo,.,bar</code></td> 4129<td><code>foo/./bar</code></td> 4130<td><code>foo/./bar</code></td> 4131<td><font size="-1"><i>empty</i></font></td> 4132<td><font size="-1"><i>empty</i></font></td> 4133<td><font size="-1"><i>empty</i></font></td> 4134<td><code>foo/./bar</code></td> 4135<td><code>foo/.</code></td> 4136<td><code>bar</code></td> 4137</tr> 4138<tr> 4139<td><code>foo/..</code></td> 4140<td><code>foo,..</code></td> 4141<td><code>foo/..</code></td> 4142<td><code>foo/..</code></td> 4143<td><font size="-1"><i>empty</i></font></td> 4144<td><font size="-1"><i>empty</i></font></td> 4145<td><font size="-1"><i>empty</i></font></td> 4146<td><code>foo/..</code></td> 4147<td><code>foo</code></td> 4148<td><code>..</code></td> 4149</tr> 4150<tr> 4151<td><code>foo/../</code></td> 4152<td><code>foo,..,.</code></td> 4153<td><code>foo/../</code></td> 4154<td><code>foo/../</code></td> 4155<td><font size="-1"><i>empty</i></font></td> 4156<td><font size="-1"><i>empty</i></font></td> 4157<td><font size="-1"><i>empty</i></font></td> 4158<td><code>foo/../</code></td> 4159<td><code>foo/..</code></td> 4160<td><code>.</code></td> 4161</tr> 4162<tr> 4163<td><code>foo/../bar</code></td> 4164<td><code>foo,..,bar</code></td> 4165<td><code>foo/../bar</code></td> 4166<td><code>foo/../bar</code></td> 4167<td><font size="-1"><i>empty</i></font></td> 4168<td><font size="-1"><i>empty</i></font></td> 4169<td><font size="-1"><i>empty</i></font></td> 4170<td><code>foo/../bar</code></td> 4171<td><code>foo/..</code></td> 4172<td><code>bar</code></td> 4173</tr> 4174<tr> 4175<td><code>c:</code></td> 4176<td><code>c:</code></td> 4177<td><code>c:</code></td> 4178<td><code>c:</code></td> 4179<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4180<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4181<td><font size="-1"><i>empty</i></font></td> 4182<td><code>c:</code><br><font size="-1"><i>empty</i></font></td> 4183<td><font size="-1"><i>empty</i></font></td> 4184<td><code>c:</code></td> 4185</tr> 4186<tr> 4187<td><code>c:/</code></td> 4188<td><code>c:,.</code><br><code>c:,/</code></td> 4189<td><code>c:/</code></td> 4190<td><code>c:/</code></td> 4191<td><font size="-1"><i>empty</i></font><br><code>c:/</code></td> 4192<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4193<td><font size="-1"><i>empty</i></font><br><code>/</code></td> 4194<td><code>c:/</code><br><font size="-1"><i>empty</i></font></td> 4195<td><code>c:</code></td> 4196<td><code>.</code><br><code>/</code></td> 4197</tr> 4198<tr> 4199<td><code>c:foo</code></td> 4200<td><code>c:foo</code><br><code>c:,foo</code></td> 4201<td><code>c:foo</code></td> 4202<td><code>c:foo</code></td> 4203<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4204<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4205<td><font size="-1"><i>empty</i></font></td> 4206<td><code>c:foo</code><br><code>foo</code></td> 4207<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4208<td><code>c:foo</code><br><code>foo</code></td> 4209</tr> 4210<tr> 4211<td><code>c:/foo</code></td> 4212<td><code>c:,foo</code><br><code>c:,/,foo</code></td> 4213<td><code>c:/foo</code></td> 4214<td><code>c:/foo</code></td> 4215<td><font size="-1"><i>empty</i></font><br><code>c:/</code></td> 4216<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4217<td><font size="-1"><i>empty</i></font><br><code>/</code></td> 4218<td><code>c:/foo</code><br><code>foo</code></td> 4219<td><code>c:</code><br><code>c:/</code></td> 4220<td><code>foo</code></td> 4221</tr> 4222<tr> 4223<td><code>c:foo/</code></td> 4224<td><code>c:foo,.</code><br><code>c:,foo,.</code></td> 4225<td><code>c:foo/</code></td> 4226<td><code>c:foo/</code></td> 4227<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4228<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4229<td><font size="-1"><i>empty</i></font></td> 4230<td><code>c:foo/</code><br><code>foo/</code></td> 4231<td><code>c:foo</code></td> 4232<td><code>.</code></td> 4233</tr> 4234<tr> 4235<td><code>c:/foo/</code></td> 4236<td><code>c:,foo,.</code><br><code>c:,/,foo,.</code></td> 4237<td><code>c:/foo/</code></td> 4238<td><code>c:/foo/</code></td> 4239<td><font size="-1"><i>empty</i></font><br><code>c:/</code></td> 4240<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4241<td><font size="-1"><i>empty</i></font><br><code>/</code></td> 4242<td><code>c:/foo/</code><br><code>foo/</code></td> 4243<td><code>c:/foo</code></td> 4244<td><code>.</code></td> 4245</tr> 4246<tr> 4247<td><code>c:/foo/bar</code></td> 4248<td><code>c:,foo,bar</code><br><code>c:,/,foo,bar</code></td> 4249<td><code>c:/foo/bar</code></td> 4250<td><code>c:/foo/bar</code></td> 4251<td><font size="-1"><i>empty</i></font><br><code>c:/</code></td> 4252<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4253<td><font size="-1"><i>empty</i></font><br><code>/</code></td> 4254<td><code>c:/foo/bar</code><br><code>foo/bar</code></td> 4255<td><code>c:/foo</code></td> 4256<td><code>bar</code></td> 4257</tr> 4258<tr> 4259<td><code>prn:</code></td> 4260<td><code>prn:</code></td> 4261<td><code>prn:</code></td> 4262<td><code>prn:</code></td> 4263<td><font size="-1"><i>empty</i></font><br><code>prn:</code></td> 4264<td><font size="-1"><i>empty</i></font><br><code>prn:</code></td> 4265<td><font size="-1"><i>empty</i></font></td> 4266<td><code>prn:</code><br><font size="-1"><i>empty</i></font></td> 4267<td><font size="-1"><i>empty</i></font></td> 4268<td><code>prn:</code></td> 4269</tr> 4270<tr> 4271<td><code>c:\</code></td> 4272<td><code>c:\</code><br><code>c:,/</code></td> 4273<td><code>c:\</code></td> 4274<td><code>c:\</code><br><code>c:/</code></td> 4275<td><font size="-1"><i>empty</i></font><br><code>c:\</code></td> 4276<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4277<td><font size="-1"><i>empty</i></font><br><code>\</code></td> 4278<td><code>c:\</code><br><font size="-1"><i>empty</i></font></td> 4279<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4280<td><code>c:\</code><br><code>\</code></td> 4281</tr> 4282<tr> 4283<td><code>c:foo</code></td> 4284<td><code>c:foo</code><br><code>c:,foo</code></td> 4285<td><code>c:foo</code></td> 4286<td><code>c:foo</code></td> 4287<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4288<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4289<td><font size="-1"><i>empty</i></font></td> 4290<td><code>c:foo</code><br><code>foo</code></td> 4291<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4292<td><code>c:foo</code><br><code>foo</code></td> 4293</tr> 4294<tr> 4295<td><code>c:\foo</code></td> 4296<td><code>c:\foo</code><br><code>c:,/,foo</code></td> 4297<td><code>c:\foo</code></td> 4298<td><code>c:\foo</code><br><code>c:/foo</code></td> 4299<td><font size="-1"><i>empty</i></font><br><code>c:\</code></td> 4300<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4301<td><font size="-1"><i>empty</i></font><br><code>\</code></td> 4302<td><code>c:\foo</code><br><code>foo</code></td> 4303<td><font size="-1"><i>empty</i></font><br><code>c:\</code></td> 4304<td><code>c:\foo</code><br><code>foo</code></td> 4305</tr> 4306<tr> 4307<td><code>c:foo\</code></td> 4308<td><code>c:foo\</code><br><code>c:,foo,.</code></td> 4309<td><code>c:foo\</code></td> 4310<td><code>c:foo\</code><br><code>c:foo/</code></td> 4311<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4312<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4313<td><font size="-1"><i>empty</i></font></td> 4314<td><code>c:foo\</code><br><code>foo\</code></td> 4315<td><font size="-1"><i>empty</i></font><br><code>c:foo</code></td> 4316<td><code>c:foo\</code><br><code>.</code></td> 4317</tr> 4318<tr> 4319<td><code>c:\foo\</code></td> 4320<td><code>c:\foo\</code><br><code>c:,/,foo,.</code></td> 4321<td><code>c:\foo\</code></td> 4322<td><code>c:\foo\</code><br><code>c:/foo/</code></td> 4323<td><font size="-1"><i>empty</i></font><br><code>c:\</code></td> 4324<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4325<td><font size="-1"><i>empty</i></font><br><code>\</code></td> 4326<td><code>c:\foo\</code><br><code>foo\</code></td> 4327<td><font size="-1"><i>empty</i></font><br><code>c:\foo</code></td> 4328<td><code>c:\foo\</code><br><code>.</code></td> 4329</tr> 4330<tr> 4331<td><code>c:\foo/</code></td> 4332<td><code>c:\foo,.</code><br><code>c:,/,foo,.</code></td> 4333<td><code>c:\foo/</code></td> 4334<td><code>c:\foo/</code><br><code>c:/foo/</code></td> 4335<td><font size="-1"><i>empty</i></font><br><code>c:\</code></td> 4336<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4337<td><font size="-1"><i>empty</i></font><br><code>\</code></td> 4338<td><code>c:\foo/</code><br><code>foo/</code></td> 4339<td><code>c:\foo</code></td> 4340<td><code>.</code></td> 4341</tr> 4342<tr> 4343<td><code>c:/foo\bar</code></td> 4344<td><code>c:,foo\bar</code><br><code>c:,/,foo,bar</code></td> 4345<td><code>c:/foo\bar</code></td> 4346<td><code>c:/foo\bar</code><br><code>c:/foo/bar</code></td> 4347<td><font size="-1"><i>empty</i></font><br><code>c:/</code></td> 4348<td><font size="-1"><i>empty</i></font><br><code>c:</code></td> 4349<td><font size="-1"><i>empty</i></font><br><code>/</code></td> 4350<td><code>c:/foo\bar</code><br><code>foo\bar</code></td> 4351<td><code>c:</code><br><code>c:/foo</code></td> 4352<td><code>foo\bar</code><br><code>bar</code></td> 4353</tr> 4354</table> 4355<h2><a name="long-path-warning"></a>Warning: Long paths on Windows and the 4356extended-length <b>\\?\ </b>prefix</h2> 4357<p>The Microsoft Windows "Maximum Path Length Limitation" specifies:</p> 4358<blockquote> 4359<p>In the Windows API (with some exceptions ...), the maximum length for a path 4360is MAX_PATH, which is defined as 260 characters.</p> 4361<p>The Windows API has many functions that also have Unicode versions to permit 4362an extended-length path for a maximum total path length of 32,767 characters. 4363... To specify an extended-length path, use the <b>"\\?\" prefix</b>. For 4364example, "\\?\D:\<em>very long path</em>". <i>[C++ string literals require backslashes be doubled, of course.]</i></p> 4365</blockquote> 4366<p>Because most Boost.Filesystem operational functions just pass the contents of 4367a class path object to the Windows API, they do work with the extended-length 4368prefixes. But some won't work, because to the limitations imposed by Windows. 4369Read the following cautions carefully!</p> 4370<h3>Cautions for paths with extended-length prefixes</h3> 4371<ul> 4372 <li>Individual components of a path are still are limited to whatever is 4373 supported for the particular filesystem, commonly 255 characters.</li> 4374 <li>Only backslashes are acceptable as directory separators. Slashes are 4375 not treated as separators.</li> 4376 <li>All paths must be absolute - relative paths are not allowed.</li> 4377 <li>Once an absolute path grows beyond 260 characters, it is essentially 4378 poisoned and all operations must use extended-length prefixes. So even a 4379 simple operation like <code>create_directory("a")</code> will fail if the 4380 absolute path of the resulting directory would exceed 260 characters.</li> 4381 <li>Certain Boost.Filesystem functions that decompose their argument path and 4382 then work on individual relative directories or files will not work properly 4383 with extended-length prefix paths.</li> 4384</ul> 4385<h2><a name="Acknowledgements">Acknowledgements</a></h2> 4386<p>This Filesystem Library is dedicated to my wife, Sonda, who provided the 4387support necessary to see both a trial implementation and the proposal itself 4388through to completion. She gave me the strength to continue after a difficult 4389year of cancer treatment in the middle of it all.</p> 4390<p>Many people contributed technical comments, ideas, and suggestions to the 4391Boost Filesystem Library. See <a href="http://www.boost.org/libs/filesystem/doc/index.htm#Acknowledgements">http://www.boost.org/libs/filesystem/doc/index.htm#Acknowledgements</a>.</p> 4392<p>Dietmar Kuehl contributed the original Boost Filesystem Library directory_iterator design. Peter Dimov, Walter Landry, Rob Stewart, and Thomas 4393Witt were particularly helpful in refining the library.</p> 4394<p>The create_directories, extension, basename, and replace_extension functions 4395were developed by Vladimir Prus. The temp_directory_path function was 4396contributed by Jeff Flinn. David Svoboda suggested the canonical function and 4397provided pseudo-code.</p> 4398<p>Howard Hinnant and John Maddock reviewed a draft of the version 2 proposal, and 4399identified a number of mistakes or weaknesses, resulting in a more polished 4400final document.</p> 4401<p>Peter Dimov suggested a single class path, with member templates to adapt to 4402multiple string types. His idea became the basis for the version 3 path design.</p> 4403<h2><a name="References">References</a></h2> 4404<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%"> 4405 <tr> 4406 <td width="16%" valign="top">[<a name="ISO_POSIX">ISO/IEC 9945</a>]</td> 4407 <td width="84%">ISO/IEC 9945:2003, IEEE Std 1003.1-2001, and The Open Group 4408 Base Specifications, Issue 6. Also known as The Single Unix<font face="Times New Roman">® 4409 Specification, Version 3. Available from each of the organizations involved 4410 in its creation. For example, read online or download from <a href="http://www.unix.org/single_unix_specification/">www.unix.org/single_unix_specification/</a>.</font> The ISO JTC1/SC22/WG15 - 4411 POSIX homepage is <a href="http://www.open-std.org/jtc1/sc22/WG15/">www.open-std.org/jtc1/sc22/WG15/</a></td> 4412 </tr> 4413 <tr> 4414 <td width="16%" valign="top">[Abrahams]</td> 4415 <td width="84%">Dave Abrahams, Error and Exception Handling, <a href="http://www.boost.org/more/error_handling.html">www.boost.org/more/error_handling.html</a></td> 4416 </tr> 4417</table> 4418<hr> 4419<p><font size="2">© Copyright Beman Dawes, 2002, 2006, 2007, 2009, 2010, 2011</font></p> 4420<p><font size="2">Distributed under the Boost Software License, Version 1.0. See 4421</font> 4422<a href="http://www.boost.org/LICENSE_1_0.txt"><font size="2">www.boost.org/LICENSE_1_0.txt</font></a></p> 4423<p><font size="2">Revised 4424<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->01 December 2015<!--webbot bot="Timestamp" endspan i-checksum="39286" --></font></p> 4425</body> 4426</html> 4427
