| 1 | <html> |
|---|
| 2 | |
|---|
| 3 | <head> |
|---|
| 4 | <meta http-equiv="Content-Language" content="en-us"> |
|---|
| 5 | <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> |
|---|
| 6 | <meta name="ProgId" content="FrontPage.Editor.Document"> |
|---|
| 7 | <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> |
|---|
| 8 | <title>Boost Filesystem operations.hpp Header</title> |
|---|
| 9 | </head> |
|---|
| 10 | |
|---|
| 11 | <body bgcolor="#FFFFFF"> |
|---|
| 12 | |
|---|
| 13 | <h1> |
|---|
| 14 | <img border="0" src="../../../boost.png" align="center" width="277" height="86"><a href="../../../boost/filesystem/operations.hpp">boost/filesystem/operations.hpp</a></h1> |
|---|
| 15 | |
|---|
| 16 | <p><a href="#Introduction">Introduction</a><br> |
|---|
| 17 | <a href="#Synopsis">Header synopsis</a><br> |
|---|
| 18 | <a href="#directory_iterator">Class directory_iterator</a><br> |
|---|
| 19 | <a href="#constructors">Constructors</a><br> |
|---|
| 20 | <a href="#Other_functions">Other_functions</a><br> |
|---|
| 21 | <a href="#Non-member_functions">Operations functions</a><br> |
|---|
| 22 | <a href="#exists">exists</a><br> |
|---|
| 23 | <a href="#symbolic_link_exists">symbolic_link_exists</a><br> |
|---|
| 24 | <a href="#is_directory">is_directory</a><br> |
|---|
| 25 | <a href="#is_empty">is_empty</a><br> |
|---|
| 26 | <a href="#equivalent">equivalent</a><br> |
|---|
| 27 | <a href="#file_size">file_size</a><br> |
|---|
| 28 | <a href="#last_write_time">last_write_time</a><br> |
|---|
| 29 | <a href="#create_directory">create_directory</a><br> |
|---|
| 30 | <a href="#remove">remove</a><br> |
|---|
| 31 | <a href="#remove_all">remove_all</a><br> |
|---|
| 32 | <a href="#rename">rename</a><br> |
|---|
| 33 | <a href="#copy_file">copy_file</a><br> |
|---|
| 34 | <a href="#initial_path">initial_path</a><br> |
|---|
| 35 | <a href="#complete">complete</a><br> |
|---|
| 36 | <a href="#system_complete">system_complete</a></p> |
|---|
| 37 | |
|---|
| 38 | <h2><a name="Introduction">Introduction</a></h2> |
|---|
| 39 | |
|---|
| 40 | <p>The <a href="../../../boost/filesystem/operations.hpp"> |
|---|
| 41 | boost/filesystem/operations.hpp</a> header provides operations on files and |
|---|
| 42 | directories.</p> |
|---|
| 43 | |
|---|
| 44 | <p>These operations traffic in paths; see <a href="path.htm"> |
|---|
| 45 | boost/filesystem/path.hpp documentation</a>.</p> |
|---|
| 46 | |
|---|
| 47 | <p>For file I/O streams, see <a href="fstream.htm">boost/filesystem/fstream.hpp |
|---|
| 48 | documentation</a>.</p> |
|---|
| 49 | |
|---|
| 50 | <p>The Filesystem Library's <a href="index.htm#Common_Specifications">Common |
|---|
| 51 | Specifications</a> apply to all member and non-member functions supplied by this |
|---|
| 52 | header. </p> |
|---|
| 53 | |
|---|
| 54 | <h2>Header <a href="../../../boost/filesystem/operations.hpp">boost/filesystem/operations.hpp</a> |
|---|
| 55 | <a name="Synopsis">synopsis</a></h2> |
|---|
| 56 | <pre>namespace boost |
|---|
| 57 | { |
|---|
| 58 | namespace filesystem |
|---|
| 59 | { |
|---|
| 60 | |
|---|
| 61 | class <a href="#directory_iterator">directory_iterator</a> |
|---|
| 62 | { |
|---|
| 63 | public: |
|---|
| 64 | typedef <a href="path.htm">path</a> value_type; |
|---|
| 65 | typedef std::ptrdiff_t difference_type; |
|---|
| 66 | typedef const path * pointer; |
|---|
| 67 | typedef const path & reference; |
|---|
| 68 | typedef std::input_iterator_tag iterator_category; |
|---|
| 69 | |
|---|
| 70 | <a href="#constructors">directory_iterator</a>(); |
|---|
| 71 | explicit <a href="#constructors">directory_iterator</a>( const path & directory_ph ); |
|---|
| 72 | |
|---|
| 73 | // <a href="#Other_functions">Other_functions</a> |
|---|
| 74 | // ... |
|---|
| 75 | }; |
|---|
| 76 | |
|---|
| 77 | bool <a href="#exists">exists</a>( const path & ph ); |
|---|
| 78 | bool <a href="#symbolic_link_exists">symbolic_link_exists</a>( const path & ph ); |
|---|
| 79 | bool <a href="#is_directory">is_directory</a>( const path & ph ); |
|---|
| 80 | bool <a href="#is_empty">is_empty</a>( const path & ph ); |
|---|
| 81 | bool <a href="#equivalent">equivalent</a>( const path & ph1, const path & ph2 ); |
|---|
| 82 | |
|---|
| 83 | boost::intmax_t <a href="#file_size">file_size</a>( const path & ph ); |
|---|
| 84 | |
|---|
| 85 | std::time_t <a href="#last_write_time">last_write_time</a>( const path & ph ); |
|---|
| 86 | void <a href="#last_write_time">last_write_time</a>( const path & ph, std::time_t new_time ); |
|---|
| 87 | |
|---|
| 88 | bool <a href="#create_directory">create_directory</a>( const path & directory_ph ); |
|---|
| 89 | bool <a href="#remove">remove</a>( const path & ph ); |
|---|
| 90 | unsigned long <a href="#remove_all">remove_all</a>( const path & ph ); |
|---|
| 91 | void <a href="#rename">rename</a>( const path & from_path, |
|---|
| 92 | const path & to_path ); |
|---|
| 93 | void <a href="#copy_file">copy_file</a>( const path & source_file, |
|---|
| 94 | const path & target_file ); |
|---|
| 95 | |
|---|
| 96 | const path & <a href="#initial_path">initial_path</a>(); |
|---|
| 97 | path <a href="#current_path">current_path</a>(); |
|---|
| 98 | path <a href="#complete">complete</a>( const path & ph, |
|---|
| 99 | const path & base = initial_path() ); |
|---|
| 100 | path <a href="#system_complete">system_complete</a>( const path & ph ); |
|---|
| 101 | |
|---|
| 102 | } // namespace filesystem |
|---|
| 103 | } // namespace boost |
|---|
| 104 | </pre> |
|---|
| 105 | |
|---|
| 106 | <h2><a name="directory_iterator">Class directory_iterator</a></h2> |
|---|
| 107 | |
|---|
| 108 | <p>Class <i>directory_iterator</i> provides a C++ standard conforming input |
|---|
| 109 | iterator which accesses the contents of a <a href="index.htm#directory"> |
|---|
| 110 | directory</a>. </p> |
|---|
| 111 | |
|---|
| 112 | <p>The value type is <i><a href="path.htm">boost::filesystem::path</a></i>, so |
|---|
| 113 | dereferencing a <i>directory_iterator</i> yields a <a href="index.htm#path"> |
|---|
| 114 | path</a> to a file or sub-directory contained within the directory represented by |
|---|
| 115 | the directory-path argument supplied at construction. The path returned by |
|---|
| 116 | dereferencing a <i>directory_iterator</i> is composed by appending the name of |
|---|
| 117 | the directory entry to the directory path supplied at construction.</p> |
|---|
| 118 | |
|---|
| 119 | <p>The order of the path entries returned by dereferencing successive increments |
|---|
| 120 | of a <i>directory_iterator</i> is unspecified. Thus depending on the ordering |
|---|
| 121 | provided by a particular implementation will result in non-portable code.</p> |
|---|
| 122 | |
|---|
| 123 | <p>A path returned by dereferencing a <i>directory_iterator</i> is, if |
|---|
| 124 | representing a directory, suitable for use as an argument to Filesystem Library |
|---|
| 125 | functions specified as accepting paths or directory paths. If not representing a |
|---|
| 126 | directory, the dereferenced path is suitable for use as an argument to |
|---|
| 127 | Filesystem Library functions specified as accepting paths or file paths, or C++ |
|---|
| 128 | Standard Library functions specified as taking file names. The leaf of a path |
|---|
| 129 | returned by dereferencing a <i>directory_iterator</i> will never be <code>".."</code> |
|---|
| 130 | or <code>"."</code>.</p> |
|---|
| 131 | |
|---|
| 132 | <p><b>Note:</b> The implication of the above requirement is that if an operating |
|---|
| 133 | system's directories can contain entries which are not usable by Filesystem |
|---|
| 134 | Library or Standard Library functions, these entries will be skipped during |
|---|
| 135 | directory iteration. Such entries are by definition non-portable, but can always |
|---|
| 136 | be accessed via the native operating system API if required.</p> |
|---|
| 137 | |
|---|
| 138 | <p><b><a name="symbolic-link-warning">Warning</a>:</b> Programs performing |
|---|
| 139 | directory iteration may wish to test, via <a href="#exists">exists()</a>, if the |
|---|
| 140 | path returned by dereferencing an iterator actually exists. It could be a |
|---|
| 141 | <a href="index.htm#symbolic-link">symbolic link</a> to a non-existent file or |
|---|
| 142 | directory. Programs recursively walking directory trees for purposes of removing |
|---|
| 143 | and renaming entries may wish to avoid following symbolic links, which can be |
|---|
| 144 | detected with <a href="#symbolic_link_exists">symbolic_link_exists()</a>.</p> |
|---|
| 145 | |
|---|
| 146 | <p><b>Warning:</b> If a file or sub-directory is removed from or added to a |
|---|
| 147 | directory after the construction of a <i>directory_iterator</i> for the |
|---|
| 148 | directory, it is unspecified whether or not subsequent incrementing of the |
|---|
| 149 | iterator will ever result in an iterator whose value is the removed or added |
|---|
| 150 | directory entry.</p> |
|---|
| 151 | |
|---|
| 152 | <h3><a name="constructors">Constructors</a></h3> |
|---|
| 153 | <blockquote> |
|---|
| 154 | |
|---|
| 155 | <p><code>directory_iterator();</code></p> |
|---|
| 156 | |
|---|
| 157 | <p><b>Effects:</b> Constructs a <i>directory_iterator</i> having the <i> |
|---|
| 158 | past-the-end</i> value as described in the C++ standard, section 24.1.</p> |
|---|
| 159 | |
|---|
| 160 | <p><code>explicit directory_iterator( const path & directory_ph );</code></p> |
|---|
| 161 | |
|---|
| 162 | <p><b>Effects:</b> Constructs a <i>directory_iterator</i> with a value |
|---|
| 163 | representing the first path in <i>directory_ph</i>, or if <code> |
|---|
| 164 | empty(directory_ph)</code>, the <i>past-the-end</i> value.</p> |
|---|
| 165 | |
|---|
| 166 | <p><b>Throws:</b> if <code>!exists( directory_ph )</code></p> |
|---|
| 167 | |
|---|
| 168 | <p><b>Note:</b> To iterate over the current directory, write <code> |
|---|
| 169 | directory_iterator(current_path())</code> rather than <code>directory_iterator("")</code>.</p> |
|---|
| 170 | </blockquote> |
|---|
| 171 | |
|---|
| 172 | <h3><a name="Other_functions">Other functions</a></h3> |
|---|
| 173 | |
|---|
| 174 | <p>Class <i>directory_iterator</i> also supplies all the other functions |
|---|
| 175 | required by the C++ standard clause 24 for input iterators, such as <i>operator==</i>, |
|---|
| 176 | <i>operator++</i>, and <i>operator*</i>.</p> |
|---|
| 177 | |
|---|
| 178 | <h2><a name="Non-member_functions">Non-member functions</a></h2> |
|---|
| 179 | |
|---|
| 180 | <p> |
|---|
| 181 | The non-member functions provide common operations on files and directories. |
|---|
| 182 | They follow traditional practice of the C and C++ standard libraries, except |
|---|
| 183 | that |
|---|
| 184 | they:</p> |
|---|
| 185 | |
|---|
| 186 | <ul> |
|---|
| 187 | <li>Traffic in <i><a href="path.htm">paths</a></i> rather than <code>char*</code>'s, for much |
|---|
| 188 | enhanced portability.</li> |
|---|
| 189 | <li>Report errors by throwing exceptions, for safer and better error handling.</li> |
|---|
| 190 | <li>Tighten specifications slightly, for improved portability.</li> |
|---|
| 191 | </ul> |
|---|
| 192 | |
|---|
| 193 | <p> |
|---|
| 194 | <b>Rationale:</b> Functions which already exist in the C++ Standard Library, |
|---|
| 195 | such as <i><a href="#remove">remove()</a></i> and <i><a href="#rename">rename()</a></i>, |
|---|
| 196 | retain the same names and general behavior in the Filesystem Library, to |
|---|
| 197 | minimize surprises.</p> |
|---|
| 198 | |
|---|
| 199 | <p> |
|---|
| 200 | <b><a name="not-precondition-rationale">Rationale</a>:</b> Some errors which might |
|---|
| 201 | at first glance appear to be preconditions are not |
|---|
| 202 | specified as such, but instead will throw exceptions. This is |
|---|
| 203 | because the possibility of <a href="index.htm#Race-condition">race-conditions</a> |
|---|
| 204 | makes it unreliable to test for preconditions before calling the function. As a |
|---|
| 205 | design practice, preconditions are not specified when it is not reasonable for a |
|---|
| 206 | program to test for them before calling the function. </p> |
|---|
| 207 | |
|---|
| 208 | <p><b>Empty path r<a name="empty_rationale">ationale</a>:</b> Some errors, |
|---|
| 209 | particularly function arguments of empty paths, are specified both in <i> |
|---|
| 210 | Precondition</i> and in <i>Throws</i> paragraphs. A non-empty path is specified |
|---|
| 211 | as a precondition because an empty path is almost certainly an error, the error |
|---|
| 212 | meets the usual criteria for <i>Preconditions</i> as specified in the C++ |
|---|
| 213 | Standard clause 17, and user pre-detection of the error does not suffer from the |
|---|
| 214 | <a href="#not-precondition-rationale">precondition race</a> problem described |
|---|
| 215 | above. The error condition is also specified in the <i>Throws</i> paragraph to |
|---|
| 216 | ensure that the error results in well-defined rather than implementation-defined |
|---|
| 217 | behavior, and because existing practice for the equivalent operating system |
|---|
| 218 | function is usually to treat an empty path as an error. The intended use of the |
|---|
| 219 | Filesystem Library in script-like programs makes undefined behavior particularly |
|---|
| 220 | unattractive.</p> |
|---|
| 221 | |
|---|
| 222 | <p> |
|---|
| 223 | <b>Naming Rationale:</b> See class <i>path</i> |
|---|
| 224 | <a href="path.htm#Naming_Rationale">Naming Rationale</a>.</p> |
|---|
| 225 | |
|---|
| 226 | <h3><a name="exists">exists</a></h3> |
|---|
| 227 | <blockquote> |
|---|
| 228 | <p><code>bool exists( const path & ph );</code></p> |
|---|
| 229 | <p><b>Returns:</b> True if the operating system reports the path |
|---|
| 230 | represented by <i>ph</i> exists, else false.</p> |
|---|
| 231 | <p><b>Note: </b>Even if <code>exists( ph ) == true</code>, there is no guarantee that it |
|---|
| 232 | will be possible to perform other operations on the file or directory. Access |
|---|
| 233 | rights or other security concerns, for example, may cause other operations to |
|---|
| 234 | fail.</p> |
|---|
| 235 | <p><b>Note:</b> <code>exists("")</code> is valid and returns false;</p> |
|---|
| 236 | </blockquote> |
|---|
| 237 | <h3><a name="symbolic_link_exists">symbolic_link_exists</a></h3> |
|---|
| 238 | <blockquote> |
|---|
| 239 | <p><code>bool symbolic_link_exists( const path & ph );</code></p> |
|---|
| 240 | <p><b>Returns:</b> True if the operating system reports the path represented by |
|---|
| 241 | <i>ph</i> is present and is a <a href="index.htm#symbolic-link">symbolic link</a>, else false.</p> |
|---|
| 242 | <p><b>Note:</b> See the <a href="#symbolic-link-warning">directory iterator |
|---|
| 243 | warning</a> for one use of <code>symbolic_link_exists()</code>.</p> |
|---|
| 244 | <p><b>Note:</b> The Microsoft Windows operating system does not currently |
|---|
| 245 | support symbolic links, so <code>symbolic_link_exists()</code> always returns |
|---|
| 246 | false on that platform. (Short-cut files (.lnk) are a Windows application |
|---|
| 247 | feature, not an O/S feature.) Programmers should still test for symbolic links |
|---|
| 248 | where applicable in case Windows adds the feature, and also so that programs |
|---|
| 249 | will be portable to systems like POSIX, where symbolic links may be present.</p> |
|---|
| 250 | <p><b>Rationale:</b> The function does not throw if <i>ph</i> is not present, |
|---|
| 251 | and is accordingly named <code>symbolic_link_exists</code> rather than <code> |
|---|
| 252 | is_symbolic_link</code>. Non-throwing behavior permits testing for all four |
|---|
| 253 | possible conditions:</p> |
|---|
| 254 | <ul> |
|---|
| 255 | <li><i>ph</i> not present: <code>!exists(ph) && !symbolic_link_exists(ph)</code></li> |
|---|
| 256 | <li><i>ph</i> present and is not a symbolic link: <code>exists(ph) && !symbolic_link_exists(ph)</code></li> |
|---|
| 257 | <li><i>ph</i> present and is a symbolic link to a non-existent file or |
|---|
| 258 | directory: <code>!exists(ph) && symbolic_link_exists(ph)</code></li> |
|---|
| 259 | <li><i>ph</i> present and is a symbolic link to an existing file or |
|---|
| 260 | directory: <code>exists(ph) && symbolic_link_exists(ph)</code></li> |
|---|
| 261 | </ul> |
|---|
| 262 | </blockquote> |
|---|
| 263 | <h3><a name="is_directory">is_directory</a></h3> |
|---|
| 264 | <blockquote> |
|---|
| 265 | <p><code>bool is_directory( const path & ph );</code></p> |
|---|
| 266 | <p><b>Returns:</b> True if the operating system reports the path represented by |
|---|
| 267 | <i>ph</i> is a directory, else false.</p> |
|---|
| 268 | <p><b>Throws:</b> if <code>!exists(ph)</code></p> |
|---|
| 269 | <p><b>Rationale:</b> Treating <code>!exists(ph)</code> as an exception rather |
|---|
| 270 | than just returning false came about because in real code <code>!exists(ph)</code> |
|---|
| 271 | has |
|---|
| 272 | often been the first indicate of a programming error. A compound function returning <code> |
|---|
| 273 | exists(ph) && is_directory(ph)</code> can always be added later.</p> |
|---|
| 274 | </blockquote> |
|---|
| 275 | <h3><a name="is_empty">is_empty</a></h3> |
|---|
| 276 | <blockquote> |
|---|
| 277 | <p><code>bool is_empty( const path & ph );</code></p> |
|---|
| 278 | <p><b>Returns:</b> True if the operating system reports the path represented by |
|---|
| 279 | <i>ph</i> is an empty file or empty directory, else false.</p> |
|---|
| 280 | <p><b>Throws:</b> if <code>!exists(ph)</code></p> |
|---|
| 281 | <p>This function determines if the file or directory identified by the |
|---|
| 282 | contents of <i>ph</i> is empty. To determine if a path string itself is empty, |
|---|
| 283 | use the <i><a href="path.htm#empty">path::empty()</a></i> function.</p> |
|---|
| 284 | </blockquote> |
|---|
| 285 | <h3><a name="equivalent">equivalent</a></h3> |
|---|
| 286 | <blockquote> |
|---|
| 287 | <pre>bool equivalent( const path & ph1, const path & ph2 );</pre> |
|---|
| 288 | <p><b>Returns:</b> <code>false</code> if <code>!exists(ph1) || !exists(ph2)</code>. |
|---|
| 289 | Otherwise, returns <code>true</code> if ph1 and ph2 resolve to the same file |
|---|
| 290 | or directory, else <code>false</code>. The criteria used to determine sameness |
|---|
| 291 | are implementation defined:</p> |
|---|
| 292 | <blockquote> |
|---|
| 293 | <ul> |
|---|
| 294 | <li>POSIX: stat() reports identical st_dev, st_ino, st_size, and st_mtime |
|---|
| 295 | values. The POSIX implementation does not protect against |
|---|
| 296 | <a href="index.htm#Race-condition">race conditions</a>.<br> |
|---|
| 297 | </li> |
|---|
| 298 | <li>Windows: GetFileInformationByHandle() reports identical dwVolumeSerialNumber, |
|---|
| 299 | nFileIndexHigh, nFileIndexLow, nFileSizeHigh, nFileSizeLow values, |
|---|
| 300 | ftLastWriteTime.dwLowDateTime, and ftLastWriteTime.dwHighDateTime. |
|---|
| 301 | Note that for identical media (particularly bit-for-bit duplicate CD's, |
|---|
| 302 | Floppies, or memory cards) equivalent() will return <code>true</code> even though the |
|---|
| 303 | media are physically different. The Windows implementation does protect |
|---|
| 304 | against <a href="index.htm#Race-condition">race conditions</a>.</li> |
|---|
| 305 | </ul> |
|---|
| 306 | </blockquote> |
|---|
| 307 | <p><b>Throws:</b> if <code>!exists(ph1) && !exists(ph2)</code></p> |
|---|
| 308 | <p><b>Warning:</b> This function may be impossible to implement on some |
|---|
| 309 | operating systems; users may wish to avoid use for code which may be ported to |
|---|
| 310 | operating systems with limited filesystem support.</p> |
|---|
| 311 | </blockquote> |
|---|
| 312 | <h3><a name="file_size">file_size</a></h3> |
|---|
| 313 | <blockquote> |
|---|
| 314 | <p><code>boost::intmax_t file_size( const path & ph );</code></p> |
|---|
| 315 | <p><b>Returns:</b> The size of the file in bytes as reported by the operating |
|---|
| 316 | system.</p> |
|---|
| 317 | <p><b>Throws:</b> if <code>!exists(ph) || is_directory(ph) || </code>the file |
|---|
| 318 | size cannot be determined (such as for an input stream).</p> |
|---|
| 319 | <p><b>Warming:</b> If a compiler does not support <code>maxint_t</code> large |
|---|
| 320 | enough to represent the operating system's maximum file size, or if the |
|---|
| 321 | implementation does not know how to query the operating system for large file |
|---|
| 322 | sizes, the returned value could be incorrect. This is not a problem with modern |
|---|
| 323 | compilers on modern versions of Linux or Windows. Users on other platforms |
|---|
| 324 | should build and run the <a href="../example/file_size.cpp">file_size.cpp</a> |
|---|
| 325 | sample program against a large file to verify correct operation.</p> |
|---|
| 326 | <p><b>Rationale:</b> Directories are excluded because the complexity of finding |
|---|
| 327 | the size of a file is typically constant, while finding the size of a directory |
|---|
| 328 | is typically linear. It was felt this would be surprising. The function is named |
|---|
| 329 | accordingly. Users needing the size of a directory can trivially provide a user |
|---|
| 330 | function which iterates over a directory returning a count.</p> |
|---|
| 331 | </blockquote> |
|---|
| 332 | <h3><a name="last_write_time">last_write_time</a></h3> |
|---|
| 333 | <blockquote> |
|---|
| 334 | <p><b>Warning:</b> The times associated with files are subject to many |
|---|
| 335 | vicissitudes. Each type of filesystem differs slightly in the details and |
|---|
| 336 | resolution of how times are recorded. The resolution is as low as one hour on |
|---|
| 337 | some filesystems. It is not uncommon for a program to |
|---|
| 338 | simultaneously have access to files maintained by FAT, ISO9660, NTFS, and POSIX |
|---|
| 339 | filesystems, and so experience different last_write_time behavior for different |
|---|
| 340 | files. During program execution, the system clock may be set to a new |
|---|
| 341 | value by some other, possibly automatic, process. Another thread or process may |
|---|
| 342 | write to a file, causing the last write time to change unexpectedly.</p> |
|---|
| 343 | <p><code>std::time_t last_write_time( const path & ph );</code></p> |
|---|
| 344 | <p><b>Returns:</b> The time the file was last modified, as reported by the |
|---|
| 345 | operating system. If the time cannot be determined, returns (std::time_t)(-1).</p> |
|---|
| 346 | <p>To convert the returned value to UTC or local time, use <code>std::gmtime()</code> |
|---|
| 347 | or <code>std::localtime()</code> respectively.</p> |
|---|
| 348 | <p><b>Throws:</b> if <code>!exists(ph)</code></p> |
|---|
| 349 | <p><code>void last_write_time( const path & ph, std::time_t new_time );</code></p> |
|---|
| 350 | <p><b>Effects:</b> Asks the operating system to set the last write time to <code> |
|---|
| 351 | new_time</code>, or to the current time if <code>new_time==std::time_t()</code>.</p> |
|---|
| 352 | <p><b>Throws:</b> if <code>!exists(ph)</code></p> |
|---|
| 353 | <p><b>Rationale:</b> <code>last_write_time(ph)==new_time</code> is not specified |
|---|
| 354 | as a postcondition because the times may differ somewhat on some operating |
|---|
| 355 | systems.</p> |
|---|
| 356 | </blockquote> |
|---|
| 357 | <h3><a name="create_directory">create_directory</a></h3> |
|---|
| 358 | <blockquote> |
|---|
| 359 | <p><code>bool create_directory( const path & directory_ph );</code></p> |
|---|
| 360 | <p><b>Precondition:</b> <code>!directory_ph.empty()</code></p> |
|---|
| 361 | <p><b>Returns:</b> The value of <code>!exists( directory_ph )</code> prior to the |
|---|
| 362 | establishment of the postcondition.</p> |
|---|
| 363 | <p><b>Postcondition:</b> <code>exists(directory_ph) && |
|---|
| 364 | is_directory(directory_ph)</code></p> |
|---|
| 365 | <p><b>Throws: </b>if <code>directory_ph.empty() || (exists(directory_ph) && !is_directory(directory_ph)) || !exists(directory_ph/"..")</code>. |
|---|
| 366 | See <a href="#empty_rationale">empty path rationale</a>.</p> |
|---|
| 367 | </blockquote> |
|---|
| 368 | <h3><a name="remove">remove</a></h3> |
|---|
| 369 | <blockquote> |
|---|
| 370 | <p><code>bool remove( const path & ph );</code></p> |
|---|
| 371 | <p><b>Precondition:</b> <code>!ph.empty()</code></p> |
|---|
| 372 | <p><b>Returns:</b> The value of <code>exists( ph )</code> prior to the |
|---|
| 373 | establishment of the postcondition. </p> |
|---|
| 374 | <p><b>Postcondition:</b> <code>!exists( ph )</code></p> |
|---|
| 375 | <p><b>Throws:</b> if<code> ph.empty() || (exists(ph) && is_directory(ph) && !is_empty(ph))</code>. |
|---|
| 376 | See <a href="#empty_rationale">empty path rationale</a>.</p> |
|---|
| 377 | <p><b>Note:</b> <a href="index.htm#symbolic-link">Symbolic links</a> are |
|---|
| 378 | themselves deleted, rather than what they point to being deleted.</p> |
|---|
| 379 | <p><b>Rationale:</b> Does not throw when <code>!exists( ph )</code> because not |
|---|
| 380 | throwing:</p> |
|---|
| 381 | <ul> |
|---|
| 382 | <li>Works correctly if <code>ph</code> is a dangling symbolic link. </li> |
|---|
| 383 | <li>Is slightly easier-to-use for many common use cases.</li> |
|---|
| 384 | <li>Is slightly higher-level because it implies use of postcondition semantics |
|---|
| 385 | rather than effects semantics, which would be specified in the somewhat |
|---|
| 386 | lower-level terms of interactions with the operating system.</li> |
|---|
| 387 | </ul> |
|---|
| 388 | <p>There is, however, a slight decrease in safety because some errors will slip |
|---|
| 389 | by which otherwise would have been detected. For example, a misspelled path name |
|---|
| 390 | could go undetected for a long time.</p> |
|---|
| 391 | <p>The initial version of the library threw an exception when the path did not exist; it |
|---|
| 392 | was changed to reflect user complaints.</p> |
|---|
| 393 | </blockquote> |
|---|
| 394 | <h3><a name="remove_all">remove_all</a></h3> |
|---|
| 395 | <blockquote> |
|---|
| 396 | <p><code>unsigned long remove_all( const path & ph );</code></p> |
|---|
| 397 | <p><b>Precondition:</b> <code>!ph.empty()</code></p> |
|---|
| 398 | <p><b>Postcondition:</b> <code>!exists( ph ) && !symbolic_link_exists( ph )</code></p> |
|---|
| 399 | <p><b>Returns:</b> The number of files and directories removed.</p> |
|---|
| 400 | <p><b>Throws:</b> if<code> ph.empty()</code>. See <a href="#empty_rationale"> |
|---|
| 401 | empty path rationale</a>.</p> |
|---|
| 402 | <p><b>Note:</b> <a href="index.htm#symbolic-link">Symbolic links</a> are |
|---|
| 403 | themselves deleted, rather than what they point to being deleted.</p> |
|---|
| 404 | </blockquote> |
|---|
| 405 | <h3><a name="rename">rename</a></h3> |
|---|
| 406 | <blockquote> |
|---|
| 407 | <p><code>void rename( const path & source, const path & target |
|---|
| 408 | );</code></p> |
|---|
| 409 | <p><b>Precondition:</b> <code>!source.empty() && !target.empty()</code></p> |
|---|
| 410 | <p><b>Effects:</b> Changes the name of file or directory <i>source</i> |
|---|
| 411 | to <i>target</i>. Specifically:</p> |
|---|
| 412 | <table border="1" cellpadding="5"> |
|---|
| 413 | <tr> |
|---|
| 414 | <td><b>Source</b></td> |
|---|
| 415 | <td><b>Target</b></td> |
|---|
| 416 | <td><b>Result is "as if" these actions occur</b></td> |
|---|
| 417 | </tr> |
|---|
| 418 | <tr> |
|---|
| 419 | <td>!exists()</td> |
|---|
| 420 | <td> </td> |
|---|
| 421 | <td>Throw <a href="exception.htm">filesystem_error</a>. Note that !exists() |
|---|
| 422 | covers the source.empty() case. [case 1] </td> |
|---|
| 423 | </tr> |
|---|
| 424 | <tr> |
|---|
| 425 | <td> </td> |
|---|
| 426 | <td>target.empty()</td> |
|---|
| 427 | <td>Throw <a href="exception.htm">filesystem_error</a>. See |
|---|
| 428 | <a href="#empty_rationale">create_directory() rationale</a>. [case 2] </td> |
|---|
| 429 | </tr> |
|---|
| 430 | <tr> |
|---|
| 431 | <td> </td> |
|---|
| 432 | <td>exists()</td> |
|---|
| 433 | <td>Throw <a href="exception.htm">filesystem_error</a>. [case 3] </td> |
|---|
| 434 | </tr> |
|---|
| 435 | <tr> |
|---|
| 436 | <td>!is_directory()</td> |
|---|
| 437 | <td> </td> |
|---|
| 438 | <td>If !exists( target / ".." ) throw <a href="exception.htm"> |
|---|
| 439 | filesystem_error</a>. [case 4A] <br> |
|---|
| 440 | The source.leaf() name is changed to |
|---|
| 441 | target.leaf(). [case 4B] <br> |
|---|
| 442 | If source / ".." resolves to a different directory than |
|---|
| 443 | target / "..", the renamed source file is moved there. [case 4C] </td> |
|---|
| 444 | </tr> |
|---|
| 445 | <tr> |
|---|
| 446 | <td>is_directory()</td> |
|---|
| 447 | <td> </td> |
|---|
| 448 | <td>If !exists( target / ".." ) throw <a href="exception.htm"> |
|---|
| 449 | filesystem_error</a>. [case 5A]<br> |
|---|
| 450 | The source.leaf() name is changed to |
|---|
| 451 | target.leaf(). [case 5B] <br> |
|---|
| 452 | If system_complete(source.banch_path()) resolves to a |
|---|
| 453 | different directory than system_complete(target.branch_path()), the |
|---|
| 454 | renamed source directory is moved there. [case 5C] </td> |
|---|
| 455 | </tr> |
|---|
| 456 | </table> |
|---|
| 457 | <p><b>Postconditions:</b> <code>!exists(source) && exists(target)</code>, |
|---|
| 458 | and the <i>source</i> file or directory contents and attributes are otherwise unchanged.</p> |
|---|
| 459 | <p><b>Throws:</b> See Effects table above. See <a href="#empty_rationale">empty |
|---|
| 460 | path rationale</a>.</p> |
|---|
| 461 | <p><b>Rationale:</b> Because <i>rename</i> is logically the same operation as <i>move</i>, |
|---|
| 462 | there is no need for a separate <i>move</i> function. The choice of the name is |
|---|
| 463 | based on existing practice in the C, C++, and POSIX libraries, and because the |
|---|
| 464 | name <i>move</i> implies physical file movement, which does not in fact occur.</p> |
|---|
| 465 | <p><b>Note:</b> Some operating systems with |
|---|
| 466 | <a href="index.htm#multi-root_filesystem">multiple roots</a> do not allow <i>rename</i> |
|---|
| 467 | operations between roots, and such an attempted <i>rename</i> with throw a <i> |
|---|
| 468 | <a href="exception.htm">filesystem_error</a></i> exception.. Implementations should not take heroic efforts, such |
|---|
| 469 | as switching to a copy mode, to make an otherwise failing <i>rename </i>succeed |
|---|
| 470 | across roots.</p> |
|---|
| 471 | <p><b>Note:</b> <a href="index.htm#symbolic-link">Symbolic links</a> are |
|---|
| 472 | themselves renamed, rather than what they point to being renamed.</p> |
|---|
| 473 | </blockquote> |
|---|
| 474 | <h3><a name="copy_file">copy_file</a></h3> |
|---|
| 475 | <blockquote> |
|---|
| 476 | <p><code>void copy_file( const path & source_file, const path & |
|---|
| 477 | target_file );</code></p> |
|---|
| 478 | <p><b>Precondition:</b> <code>!source.empty() && !target.empty()</code></p> |
|---|
| 479 | <p><b>Effects:</b> Copies the file represented by <i>source_file</i> to <i> |
|---|
| 480 | target_file</i>.</p> |
|---|
| 481 | <p><b>Throws:</b> if <code>!exists(source_file) || is_directory(source_file) |
|---|
| 482 | || exists(target_file) || target_file.empty() || !exists(to_file_path/".."))</code>. |
|---|
| 483 | See <a href="#empty_rationale">empty path rationale</a>.</p> |
|---|
| 484 | <p><b>Note:</b> File attributes are also copied. Specifically, POSIX <i> |
|---|
| 485 | stat::st_mode</i>, and Windows <i>BY_HANDLE_FILE_INFORMATION::dwFileAttributes</i>. </p> |
|---|
| 486 | </blockquote> |
|---|
| 487 | <h3><a name="initial_path">initial_path</a></h3> |
|---|
| 488 | <blockquote> |
|---|
| 489 | <p><code>const path & initial_path();</code></p> |
|---|
| 490 | <p><b>Effects:</b> The first time called, stores the path returned by |
|---|
| 491 | <a href="#current_path">current_path()</a>.</p> |
|---|
| 492 | <p>The preferred implementation would be to call <i>initial_path()</i> during program |
|---|
| 493 | initialization, before the call to <i>main()</i>. This is, however, not possible |
|---|
| 494 | with changing the C++ runtime library.</p> |
|---|
| 495 | <p><b>Returns:</b> A reference to the stored path.</p> |
|---|
| 496 | <p><b>Rationale:</b> The semantics, in effect, turn a dangerous global variable into |
|---|
| 497 | a safer global constant. The preferred implementation requires runtime library |
|---|
| 498 | support, so alternate semantics are supplied for those implementations which |
|---|
| 499 | cannot change an existing the runtime library.</p> |
|---|
| 500 | <p><b>Note:</b> It is good practice for a program dependent on <i> |
|---|
| 501 | initial_path()</i> to call it immediately upon entering<i> main()</i>. That |
|---|
| 502 | protects against another function altering the current working |
|---|
| 503 | directory (using a native platform function) before the first call to <i> |
|---|
| 504 | initial_path()</i>.</p> |
|---|
| 505 | |
|---|
| 506 | </blockquote> |
|---|
| 507 | <h3><a name="current_path">current_path</a></h3> |
|---|
| 508 | <blockquote> |
|---|
| 509 | <pre>path current_path();</pre> |
|---|
| 510 | <p><b>Returns:</b> The current path as maintained by the operating system.</p> |
|---|
| 511 | <p><b>Postcondition:</b> <code>current_path().is_complete()</code></p> |
|---|
| 512 | <p><b>Note:</b> The equivalent POSIX function is <i>getcwd()</i>. The |
|---|
| 513 | equivalent Windows function is <i>GetCurrentDirectoryA()</i>.</p> |
|---|
| 514 | <p><b>Warning:</b> The current path maintained by the operating system is |
|---|
| 515 | in-effect a dangerous global variable. It may be changed unexpectedly by a |
|---|
| 516 | third-party or system library function, or by another thread. For a safer |
|---|
| 517 | alternative, see <a href="#initial_path">initial_path()</a>.</p> |
|---|
| 518 | <p><b>Rationale:</b> Although dangerous, the function is useful in dealing |
|---|
| 519 | with other libraries. The <i>current_path()</i> name was chosen to emphasize |
|---|
| 520 | that the function returns a complete path, not just a single directory name.</p> |
|---|
| 521 | </blockquote> |
|---|
| 522 | <h3><a name="complete">complete</a></h3> |
|---|
| 523 | |
|---|
| 524 | <blockquote> |
|---|
| 525 | <p><code>path complete( const path & ph, const path & base = initial_path() );</code></p> |
|---|
| 526 | |
|---|
| 527 | <p><b>Precondition:</b> <code>!ph.empty() && base.is_complete() && (ph.is_complete() || !ph.has_root_name())</code></p> |
|---|
| 528 | |
|---|
| 529 | <p><b>Effects:</b> Composes a complete path from <code>ph</code> and <code>base</code>, |
|---|
| 530 | using the following rules:</p> |
|---|
| 531 | |
|---|
| 532 | <p>For single-root operating systems (POSIX-like systems, for example), if <code>ph.empty()</code> |
|---|
| 533 | or <code>ph.is_complete()</code>, the composed path is <code>ph</code>, |
|---|
| 534 | otherwise the composed path is <code>base/ph</code>.</p> |
|---|
| 535 | |
|---|
| 536 | <p>For <a href="index.htm#multi-root_filesystem">multi-root</a> operating systems (Windows, Classic Mac, many others), the rules are |
|---|
| 537 | give by this table:</p> |
|---|
| 538 | <table border="1" cellpadding="5"> |
|---|
| 539 | <tr> |
|---|
| 540 | <td align="center"> </td> |
|---|
| 541 | <td align="center"><code>ph.has_root_directory()</code></td> |
|---|
| 542 | <td align="center"><code>!ph.has_root_directory()</code></td> |
|---|
| 543 | </tr> |
|---|
| 544 | <tr> |
|---|
| 545 | <td align="center"><code>ph.has_root_name()</code></td> |
|---|
| 546 | <td align="center"><code>ph</code></td> |
|---|
| 547 | <td align="center"><code>(precondition failure)</code></td> |
|---|
| 548 | </tr> |
|---|
| 549 | <tr> |
|---|
| 550 | <td align="center"><code>!ph.has_root_name()</code></td> |
|---|
| 551 | <td align="center"><code>base.root_name()<br> |
|---|
| 552 | / ph</code></td> |
|---|
| 553 | <td align="center"><code>base / ph</code></td> |
|---|
| 554 | </tr> |
|---|
| 555 | </table> |
|---|
| 556 | <p><b>Returns:</b> The composed path.</p> |
|---|
| 557 | |
|---|
| 558 | <p><b>Postcondition:</b> For the returned path, <code>p,</code> <code>p.is_complete()</code> |
|---|
| 559 | is true.</p> |
|---|
| 560 | |
|---|
| 561 | <p><b>Throws:</b> On precondition failure. See <a href="#empty_rationale">empty |
|---|
| 562 | path rationale</a>.</p> |
|---|
| 563 | |
|---|
| 564 | <p><b><a name="complete_note">Note</a>:</b> When portable behavior is required, |
|---|
| 565 | use <i>complete()</i>. When operating system dependent behavior is required, use |
|---|
| 566 | <i>system_complete()</i>.</p> |
|---|
| 567 | |
|---|
| 568 | <p>Portable behavior is preferred when dealing with paths created internally |
|---|
| 569 | within a program, particularly where the program should exhibit the same |
|---|
| 570 | behavior on all operating systems.</p> |
|---|
| 571 | |
|---|
| 572 | <p>Operating system dependent behavior is preferred when dealing with paths |
|---|
| 573 | supplied by user input, reported to program users, or which should result in |
|---|
| 574 | program behavior familiar to and expected by program users. The |
|---|
| 575 | <a href="../example/simple_ls.cpp">simple_ls.cpp</a> program, for example, |
|---|
| 576 | operates on a path supplied in the native operating system format, so uses |
|---|
| 577 | <i>system_complete()</i> to ensure that the path behaves as expected for the |
|---|
| 578 | particular operating system.</p> |
|---|
| 579 | |
|---|
| 580 | <p><b>Rationale:</b> The <code>!ph.has_root_name()</code> portion of the |
|---|
| 581 | precondition disallows the error condition of <code>ph.root_name()</code> |
|---|
| 582 | being not equivalent to <code>base.root_name()</code>. The restriction is |
|---|
| 583 | broader that would appear necessary, in that is also prohibits the case where |
|---|
| 584 | they are equivalent. There is, however, no portable way to express the |
|---|
| 585 | root_name() equivalence requirement.</p> |
|---|
| 586 | |
|---|
| 587 | </blockquote> |
|---|
| 588 | <h3><a name="system_complete">system_complete</a></h3> |
|---|
| 589 | |
|---|
| 590 | <blockquote> |
|---|
| 591 | <p><code>path system_complete( const path & ph );</code></p> |
|---|
| 592 | |
|---|
| 593 | <p><b>Precondition:</b> <code>!ph.empty()</code></p> |
|---|
| 594 | |
|---|
| 595 | <p><b>Effects:</b> Composes a complete path from <code>ph</code>, using the same |
|---|
| 596 | rules used by the operating system to resolve a path passed as the filename |
|---|
| 597 | argument to standard library open functions.</p> |
|---|
| 598 | |
|---|
| 599 | <p>For POSIX-like systems, system_complete( ph ) has the same semantics as <code> |
|---|
| 600 | complete( ph, current_path() )</code>.</p> |
|---|
| 601 | |
|---|
| 602 | <p><a name="windows_effects">For Widows</a>, system_complete( ph ) has the same |
|---|
| 603 | semantics as <code>complete( ph, current_path() )</code> if ph.is_complete() || |
|---|
| 604 | !ph.has_root_name() or ph and base have the same root_name(). |
|---|
| 605 | Otherwise it acts like <code>complete( ph, kinky )</code>, where <code>kinky</code> |
|---|
| 606 | is the current directory for the <code>ph.root_name()</code> drive. This |
|---|
| 607 | will be the current directory of that drive the last time it was set, and thus |
|---|
| 608 | may well be <b>residue left over from some prior program</b> run by the command |
|---|
| 609 | processor! Although these semantics are often useful, they are also very |
|---|
| 610 | error-prone, and certainly deserve to be called "kinky".</p> |
|---|
| 611 | |
|---|
| 612 | <p><b>Returns:</b> The composed path.</p> |
|---|
| 613 | |
|---|
| 614 | <p><b>Postcondition:</b> For the returned path, <code>p,</code> <code>p.is_complete()</code> |
|---|
| 615 | is true.</p> |
|---|
| 616 | |
|---|
| 617 | <p><b>Throws:</b> If <code>ph.empty()</code>. See <a href="#empty_rationale"> |
|---|
| 618 | empty path rationale</a>.</p> |
|---|
| 619 | |
|---|
| 620 | <p><b>Note:</b> See <a href="#complete_note"><i>complete()</i> note</a> for |
|---|
| 621 | usage suggestions.</p> |
|---|
| 622 | |
|---|
| 623 | <p><b>Warning:</b> This function relies on a global variable (current_path()), |
|---|
| 624 | and so tends to be more error-prone than the similar function |
|---|
| 625 | <a href="#complete">complete()</a>. This function is doubly dangerous on |
|---|
| 626 | Windows, where under cross-drive conditions it may be relying on a directory set |
|---|
| 627 | by a prior program run by the command processor.</p> |
|---|
| 628 | |
|---|
| 629 | </blockquote> |
|---|
| 630 | |
|---|
| 631 | <hr> |
|---|
| 632 | <p>Revised |
|---|
| 633 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->02 August, 2005<!--webbot bot="Timestamp" endspan i-checksum="34600" --></p> |
|---|
| 634 | <p>© Copyright Beman Dawes, 2002</p> |
|---|
| 635 | <p> Use, modification, and distribution are subject to the Boost Software |
|---|
| 636 | License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt"> |
|---|
| 637 | LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt"> |
|---|
| 638 | www.boost.org/LICENSE_1_0.txt</a>)</p> |
|---|
| 639 | |
|---|
| 640 | </body> |
|---|
| 641 | |
|---|
| 642 | </html> |
|---|
