]>
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> |