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