| 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 Library</title> |
|---|
| 9 | </head> |
|---|
| 10 | |
|---|
| 11 | <body bgcolor="#FFFFFF"> |
|---|
| 12 | |
|---|
| 13 | <h1> |
|---|
| 14 | <img border="0" src="../../../boost.png" align="center" width="277" height="86">Boost |
|---|
| 15 | Filesystem Library</h1> |
|---|
| 16 | <table border="0" cellpadding="0" width="100%"> |
|---|
| 17 | <tr> |
|---|
| 18 | <td width="50%" valign="top"><font size="4">This Document</font><br> |
|---|
| 19 | <a href="#Introduction">Introduction</a><br> |
|---|
| 20 | <a href="#tutorial">Two-minute tutorial</a><br> |
|---|
| 21 | <a href="#Examples">Examples</a><br> |
|---|
| 22 | |
|---|
| 23 | <a href="#Definitions">Definitions</a><br> |
|---|
| 24 | <a href="#Common_Specifications">Common Specifications</a><br> |
|---|
| 25 | <a href="#Race-condition">Race-condition danger</a><br> |
|---|
| 26 | <a href="#Implementation">Implementation</a><br> |
|---|
| 27 | <a href="#Building">Building the object-library</a><br> |
|---|
| 28 | <a href="#Cgywin">Notes for Cygwin users</a><br> |
|---|
| 29 | <a href="#Acknowledgements">Acknowledgements</a><br> |
|---|
| 30 | <a href="#Change-history">Change history</a></td> |
|---|
| 31 | <td width="50%"><font size="4">Other Documents</font><br> |
|---|
| 32 | <a href="design.htm">Library Design</a><br> |
|---|
| 33 | <a href="faq.htm">FAQ</a><br> |
|---|
| 34 | <a href="portability_guide.htm">Portability Guide</a><br> |
|---|
| 35 | <a href="path.htm"><b><i>path.hpp</i></b> documentation</a><br> |
|---|
| 36 | <a href="operations.htm"><b><i>operations.hpp</i></b> documentation</a><br> |
|---|
| 37 | <a href="fstream.htm"><b><i>fstream.hpp</i></b> documentation</a><br> |
|---|
| 38 | <a href="exception.htm"><b><i>exception.hpp</i></b> documentation</a><br> |
|---|
| 39 | <a href="convenience.htm"><b><i>convenience.hpp</i></b> |
|---|
| 40 | documentation</a><br> |
|---|
| 41 | <a href="do-list.htm">Do-list</a></td> |
|---|
| 42 | </tr> |
|---|
| 43 | </table> |
|---|
| 44 | <h2><a name="Introduction">Introduction</a></h2> |
|---|
| 45 | <p>The Boost Filesystem Library provides portable facilities to query and |
|---|
| 46 | manipulate paths, files, and directories.</p> |
|---|
| 47 | |
|---|
| 48 | <p>The motivation for the library is the need to be able to perform portable script-like operations from within C++ programs. The intent is not to |
|---|
| 49 | compete with Python, Perl, or shell languages, but rather to provide portable filesystem |
|---|
| 50 | operations when C++ is already the language of choice. The <a href="design.htm"> |
|---|
| 51 | design</a> encourages, but does not require, safe and portable filesystem usage.</p> |
|---|
| 52 | |
|---|
| 53 | <p>The Filesystem Library supplies several headers, all in |
|---|
| 54 | directory boost/filesystem:</p> |
|---|
| 55 | |
|---|
| 56 | <ul> |
|---|
| 57 | <li>Header <i><a href="../../../boost/filesystem/path.hpp">path.hpp</a></i> provides class <i>path, </i>a portable mechanism for representing |
|---|
| 58 | <a href="#path">paths</a> in C++ programs. Validity checking |
|---|
| 59 | functions are also provided. See <a href="path.htm">path.hpp documentation</a>.<br> |
|---|
| 60 | </li> |
|---|
| 61 | <li>Header <i><a href="../../../boost/filesystem/operations.hpp">operations.hpp</a></i> provides functions operating on files and directories, |
|---|
| 62 | and includes class <i>directory_iterator</i>. See <a href="operations.htm"> |
|---|
| 63 | operations.hpp documentation</a>.<br> |
|---|
| 64 | </li> |
|---|
| 65 | <li>Header <i><a href="../../../boost/filesystem/fstream.hpp">fstream.hpp</a></i> provides the same components as the C++ Standard |
|---|
| 66 | Library's <i>fstream</i> header, except |
|---|
| 67 | that files are identified by <i>path</i> objects rather that <i>char *</i>'s. |
|---|
| 68 | See <a href="fstream.htm">fstream.hpp documentation</a>.<br> |
|---|
| 69 | </li> |
|---|
| 70 | <li>Header <i><a href="../../../boost/filesystem/exception.hpp">exception.hpp</a></i> provides class <i>filesystem_error</i>. See |
|---|
| 71 | <a href="exception.htm">exception.hpp documentation</a>.<br> |
|---|
| 72 | </li> |
|---|
| 73 | <li>Header <a href="../../../boost/filesystem/convenience.hpp">convenience.hpp</a> |
|---|
| 74 | provides convenience functions that combine lower-level functions in useful |
|---|
| 75 | ways. See <a href="convenience.htm">convenience.hpp documentation</a>.</li> |
|---|
| 76 | </ul> |
|---|
| 77 | <p>The organizing principle is that purely lexical operations on<i> </i> |
|---|
| 78 | <a href="#path">paths</a> are supplied as <i>class path</i> member |
|---|
| 79 | functions in <i>path.hpp</i>, while operations performed by the operating system |
|---|
| 80 | on the actual external filesystem directories and files are provided in <i> |
|---|
| 81 | operations.hpp,</i> primarily as free functions.</p> |
|---|
| 82 | <h2>Two-minute <a name="tutorial">tutorial</a></h2> |
|---|
| 83 | <p>First some preliminaries:</p> |
|---|
| 84 | <blockquote> |
|---|
| 85 | <pre>#include "boost/filesystem/operations.hpp" // includes boost/filesystem/path.hpp |
|---|
| 86 | #include "boost/filesystem/fstream.hpp" // ditto |
|---|
| 87 | #include <iostream> // for std::cout |
|---|
| 88 | using boost::filesystem; // for ease of tutorial presentation; |
|---|
| 89 | // a namespace alias is preferred in real code</pre> |
|---|
| 90 | </blockquote> |
|---|
| 91 | <p>A <a href="path.htm#synopsis">class <i>path</i></a> object can be created:</p> |
|---|
| 92 | <blockquote> |
|---|
| 93 | <pre>path my_path( "some_dir/file.txt" );</pre> |
|---|
| 94 | </blockquote> |
|---|
| 95 | <p>The string passed to the <i>path</i> constructor is in a |
|---|
| 96 | <a href="path.htm#Grammar">portable generic path format</a>. Access functions |
|---|
| 97 | make <i>my_path</i> contents available in an operating system dependent format, |
|---|
| 98 | such as <code>"some_dir:file.txt"</code>, <code>"[some_dir]file.txt"</code>, |
|---|
| 99 | <code>"some_dir/file.txt"</code>, or whatever is appropriate for the |
|---|
| 100 | operating system.</p> |
|---|
| 101 | <p>Class <i>path</i> has conversion constructors from <i>const char*</i> and <i> |
|---|
| 102 | const std:: string&</i>, so that even though the Filesystem Library functions in |
|---|
| 103 | the following code snippet take <i>const path&</i> arguments, the user can just |
|---|
| 104 | code C-style strings:</p> |
|---|
| 105 | <blockquote> |
|---|
| 106 | <pre>remove_all( "foobar" ); |
|---|
| 107 | create_directory( "foobar" ); |
|---|
| 108 | ofstream file( "foobar/cheeze" ); |
|---|
| 109 | file << "tastes good!\n"; |
|---|
| 110 | file.close(); |
|---|
| 111 | if ( !exists( "foobar/cheeze" ) ) |
|---|
| 112 | std::cout << "Something is rotten in foobar\n";</pre> |
|---|
| 113 | </blockquote> |
|---|
| 114 | <p>Additional class path constructors provide for an operating system dependent |
|---|
| 115 | format, useful for user provided input:</p> |
|---|
| 116 | <blockquote> |
|---|
| 117 | <pre>int main( int argc, char * argv[] ) { |
|---|
| 118 | path arg_path( argv[1], native ); // native means use O/S path format</pre> |
|---|
| 119 | </blockquote> |
|---|
| 120 | <p>To make class <i>path</i> objects easy to use in expressions, <i>operator/</i> |
|---|
| 121 | appends paths:</p> |
|---|
| 122 | <blockquote> |
|---|
| 123 | <pre>ifstream file1( arg_path / "foo/bar" ); |
|---|
| 124 | ifstream file2( arg_path / "foo" / "bar" );</pre> |
|---|
| 125 | </blockquote> |
|---|
| 126 | <p>The expressions <i>arg_path / "foo/bar"</i> and <i>arg_path / "foo" |
|---|
| 127 | / "bar"</i> yield identical results.</p> |
|---|
| 128 | <p>Paths can include references to the parent directory, using the "<code>..</code>" |
|---|
| 129 | notation. Paths are always automatically converted to |
|---|
| 130 | <a href="path.htm#Canonical">canonical form</a>, so <i>"foo/../bar"</i> gets |
|---|
| 131 | converted to <i>"bar"</i>, and <i>"../foo/../bar"</i> gets converted to <i> |
|---|
| 132 | "../bar"</i>.</p> |
|---|
| 133 | <p><a href="operations.htm#directory_iterator">Class <i>directory_iterator</i></a> |
|---|
| 134 | is an important component of the library. It provides input iterators over the |
|---|
| 135 | contents of a directory, with the value type being class <i>path</i>.</p> |
|---|
| 136 | <p>The following function, given a directory path and a file name, recursively |
|---|
| 137 | searches the directory and its sub-directories for the file name, returning a |
|---|
| 138 | bool, and if successful, the path to the file that was found. The code |
|---|
| 139 | below is extracted from a real program, slightly modified for clarity:</p> |
|---|
| 140 | <blockquote> |
|---|
| 141 | <pre>bool find_file( const path & dir_path, // in this directory, |
|---|
| 142 | const std::string & file_name, // search for this name, |
|---|
| 143 | path & path_found ) // placing path here if found |
|---|
| 144 | { |
|---|
| 145 | if ( !exists( dir_path ) ) return false; |
|---|
| 146 | directory_iterator end_itr; // default construction yields past-the-end |
|---|
| 147 | for ( directory_iterator itr( dir_path ); |
|---|
| 148 | itr != end_itr; |
|---|
| 149 | ++itr ) |
|---|
| 150 | { |
|---|
| 151 | if ( is_directory( *itr ) ) |
|---|
| 152 | { |
|---|
| 153 | if ( find_file( *itr, file_name, path_found ) ) return true; |
|---|
| 154 | } |
|---|
| 155 | else if ( itr->leaf() == file_name ) // see below |
|---|
| 156 | { |
|---|
| 157 | path_found = *itr; |
|---|
| 158 | return true; |
|---|
| 159 | } |
|---|
| 160 | } |
|---|
| 161 | return false; |
|---|
| 162 | }</pre> |
|---|
| 163 | </blockquote> |
|---|
| 164 | <p>The expression <i>itr->leaf() == file_name</i>, in the line commented <i>// |
|---|
| 165 | see below</i>, calls the <i>leaf()</i> function on the <i>path</i> object |
|---|
| 166 | returned by the iterator. <i>leaf()</i> returns a string which is a copy of the |
|---|
| 167 | last (closest to the leaf, farthest from the root) file or directory name in the |
|---|
| 168 | <i>path</i> object.</p> |
|---|
| 169 | <p>In addition to <i>leaf()</i>, several other function names use the |
|---|
| 170 | tree/root/branch/leaf metaphor.</p> |
|---|
| 171 | <p>Notice that <i>find_file()</i> does not do explicit error checking, such as |
|---|
| 172 | verifying that the <i>dir_path</i> argument really represents a directory. All |
|---|
| 173 | Filesystem Library functions throw <a href="exception.htm">filesystem_error</a> |
|---|
| 174 | exceptions if they do not complete successfully, so there is enough implicit |
|---|
| 175 | error checking that this application doesn't need to supply additional error |
|---|
| 176 | checking code.</p> |
|---|
| 177 | <p>The tutorial is now over; hopefully you now are ready to write simple, |
|---|
| 178 | script-like, programs using the Filesystem Library!</p> |
|---|
| 179 | <h2><a name="Examples">Examples</a></h2> |
|---|
| 180 | <h3>simple_ls.cpp</h3> |
|---|
| 181 | <p>The example program <a href="../example/simple_ls.cpp">simple_ls.cpp</a> is |
|---|
| 182 | given a path as a command line argument. Since the command line argument may be |
|---|
| 183 | a relative path, the complete path is determined so that messages displayed |
|---|
| 184 | can be more precise.</p> |
|---|
| 185 | <p>The program checks to see if the path exists; if not a message is printed.</p> |
|---|
| 186 | <p>If the path identifies a directory, the directory is iterated through, |
|---|
| 187 | printing the name of the entries found, and an indication if they are |
|---|
| 188 | directories. A count of directories and files is updated, and then printed after |
|---|
| 189 | the iteration is complete.</p> |
|---|
| 190 | <p>If the path is for a file, a message indicating that is printed.</p> |
|---|
| 191 | <p>Try compiling and executing <a href="../example/simple_ls.cpp">simple_ls.cpp</a> |
|---|
| 192 | to see how it works on your system. Try various path arguments to see what |
|---|
| 193 | happens.</p> |
|---|
| 194 | <h3>Other examples</h3> |
|---|
| 195 | <p>The programs used to generate the Boost regression test status tables use the |
|---|
| 196 | Filesystem Library extensively. See:</p> |
|---|
| 197 | <ul> |
|---|
| 198 | <li><a href="../../../tools/regression/process_jam_log.cpp"> |
|---|
| 199 | process_jam_log.cpp</a></li> |
|---|
| 200 | <li><a href="../../../tools/regression/compiler_status.cpp"> |
|---|
| 201 | compiler_status.cpp</a></li> |
|---|
| 202 | </ul> |
|---|
| 203 | <p>Test programs are sometimes useful in understanding a library, as they |
|---|
| 204 | illustrate what the developer expected to work and not work. See:</p> |
|---|
| 205 | <ul> |
|---|
| 206 | <li><a href="../test/path_test.cpp">path_test.cpp</a></li> |
|---|
| 207 | <li><a href="../test/operations_test.cpp">operations_test.cpp</a></li> |
|---|
| 208 | <li><a href="../test/fstream_test.cpp">fstream_test.cpp</a></li> |
|---|
| 209 | </ul> |
|---|
| 210 | <h2><a name="Definitions">Definitions</a></h2> |
|---|
| 211 | <p><b><a name="directory">directory</a> </b>- A container provided by the operating system, |
|---|
| 212 | containing the names of files, other directories, or both. Directories are identified |
|---|
| 213 | by <a href="#directory_path">directory path</a>.</p> |
|---|
| 214 | <p><b><a name="directory_tree">directory tree</a></b> - A directory and file |
|---|
| 215 | hierarchy viewed as an acyclic graph. The tree metaphor is reflected in the |
|---|
| 216 | root/branch/leaf naming convention for many <a href="#path">path</a> related |
|---|
| 217 | functions.</p> |
|---|
| 218 | <p><b><a name="path">path</a> </b>- A possibly empty sequence of <a href="#name">names</a>. Each |
|---|
| 219 | element in the sequence, except the last, names a <a href="#directory">directory</a> |
|---|
| 220 | which contains the |
|---|
| 221 | next element. The last element may name either a directory or file. The first |
|---|
| 222 | element is closest to the <a href="#root">root</a> of the directory tree, the last element is |
|---|
| 223 | farthest from the root.</p> |
|---|
| 224 | <p>It is traditional to represent a path as a string, where each element in the |
|---|
| 225 | path is represented by a <a href="#name">name</a>, and some operating system |
|---|
| 226 | defined syntax distinguishes between the name elements. Other representations of |
|---|
| 227 | a path are possible, such as each name being an element in a <code>std::vector<std::string></code>.</p> |
|---|
| 228 | <p><b><a name="file path">file path</a></b> - A <a href="#path">path</a> whose |
|---|
| 229 | last element is a file.</p> |
|---|
| 230 | <p><b><a name="directory_path">directory path</a></b> - A <a href="#path">path</a> |
|---|
| 231 | whose last element is a directory.</p> |
|---|
| 232 | <p><b><a name="complete_path">complete path</a></b> - A <a href="#path">path</a> |
|---|
| 233 | which contains all the elements required by the operating system to uniquely |
|---|
| 234 | identify a file or directory. (There is an odd |
|---|
| 235 | <a href="path.htm#is_complete_note">corner case</a> where a complete path can |
|---|
| 236 | still be ambiguous on a few operating systems.)</p> |
|---|
| 237 | <p><b><a name="relative_path">relative path</a></b> - A <a href="#root">path</a> |
|---|
| 238 | which is not <a href="#complete_path">complete</a>. Before actual use, relative |
|---|
| 239 | paths are turned into <a href="#complete_path">complete paths</a> either |
|---|
| 240 | implicitly by the filesystem adding default elements, or explicitly by the |
|---|
| 241 | program adding the missing elements via function call. Use of relative paths |
|---|
| 242 | often makes a program much more flexible.</p> |
|---|
| 243 | <p><b><a name="name">name</a></b> - A file or directory name, without any |
|---|
| 244 | <a href="#directory_path">directory path</a> information to indicate the file or |
|---|
| 245 | directory's actual location within a directory tree. For some |
|---|
| 246 | operating systems, files and directories may have more than one valid name, such |
|---|
| 247 | as a short-form name and a long-form name.</p> |
|---|
| 248 | <p><b><a name="root">root</a></b> - The initial node in the acyclic graph which |
|---|
| 249 | represents the <a href="#directory_path">directory tree</a> for a filesystem.</p> |
|---|
| 250 | <p><b><a name="multi-root_filesystem">multi-root operating system</a></b> - An |
|---|
| 251 | operating system which has multiple <a href="#root">roots</a>. Some operating systems |
|---|
| 252 | have different <a href="#directory_tree">directory trees</a> for each different |
|---|
| 253 | disk, drive, device, volume, share, or other entity managed the system, with each having its |
|---|
| 254 | own root-name.</p> |
|---|
| 255 | <p><b><a name="link">link</a></b> - A name in a <a href="#directory"> |
|---|
| 256 | directory</a> can be viewed as a pointer to some underlying directory or file |
|---|
| 257 | content. Modern operating systems permit multiple directory elements to point to |
|---|
| 258 | the same underlying directory or file content. Such a pointer is often called a |
|---|
| 259 | link. Not all operating systems support the |
|---|
| 260 | concept of links. Links may be reference-counted (<a href="#hard-link">hard link</a>) |
|---|
| 261 | or non-reference-counted (<a href="#symbolic-link">symbolic link</a>).</p> |
|---|
| 262 | <p><b><a name="hard-link">hard link</a></b> - A reference-counted |
|---|
| 263 | <a href="#link">link</a>. Because the operating system manages the underlying |
|---|
| 264 | file or directory, hard links are transparent to programs. They "just work" |
|---|
| 265 | without the programmer needing to be aware of their existence.</p> |
|---|
| 266 | <p><b><a name="symbolic-link">symbolic link</a></b> - A non-reference-counted |
|---|
| 267 | <a href="#hard-link">link</a>. The operating system manages some aspects of |
|---|
| 268 | symbolic links. Most uses, such as opening or querying files, automatically |
|---|
| 269 | resolve to the file or directory being pointed to rather than to the symbolic |
|---|
| 270 | link itself. A few uses, such as remove() and rename(), modify the symbolic link |
|---|
| 271 | rather than it's target. See an important |
|---|
| 272 | <a href="operations.htm#symbolic-link-warning">symbolic links warning</a>.</p> |
|---|
| 273 | <h2><a name="Common_Specifications">Common Specifications</a></h2> |
|---|
| 274 | <p>Unless otherwise specified, all Filesystem Library member and non-member |
|---|
| 275 | functions have the following common specifications:</p> |
|---|
| 276 | <p><b>Postconditions not guaranteed in the presence of race-conditions</b> - |
|---|
| 277 | Filesystem function specifications follow the form of C++ Standard Library |
|---|
| 278 | specifications, and so sometimes specify behavior in terms of postconditions. If |
|---|
| 279 | a <a href="#Race-condition">race-condition</a> exists, a function's |
|---|
| 280 | postconditions may no longer be true by the time the function returns to the |
|---|
| 281 | caller.</p> |
|---|
| 282 | <p><b>May throw exceptions</b> - Filesystem Library functions may throw <i><a href="exception.htm">filesystem_error</a></i> |
|---|
| 283 | exceptions if they cannot successfully complete their operational |
|---|
| 284 | specifications. Function implementations may use C++ Standard Library functions, |
|---|
| 285 | which may throw <i>std::bad_alloc</i>. These exceptions may be thrown even |
|---|
| 286 | though the error condition leading to the exception is not explicitly specified |
|---|
| 287 | in the function's "Throws" paragraph.</p> |
|---|
| 288 | <p><b>Exceptions thrown via <a href="../../utility/throw_exception.html"> |
|---|
| 289 | boost::throw_exception()</a></b> - All exceptions thrown by the Filesystem |
|---|
| 290 | Library are implemented by calling <a href="../../utility/throw_exception.html"> |
|---|
| 291 | boost::throw_exception()</a>. Thus exact behavior may differ depending on |
|---|
| 292 | BOOST_NO_EXCEPTIONS at the time the filesystem source files are compiled.</p> |
|---|
| 293 | <p><b><a name="link_rules">Links follow operating system rules</a></b>- <a href="#link">Links</a> are |
|---|
| 294 | transparent in that Filesystem Library functions simply follow operating system |
|---|
| 295 | rules. That implies that some functions may throw <i><a href="exception.htm">filesystem_error</a></i> |
|---|
| 296 | exceptions if a link is cyclic or has other problems. Also, see an important |
|---|
| 297 | <a href="operations.htm#symbolic-link-warning">symbolic links warning</a>.</p> |
|---|
| 298 | <p>Typical operating systems rules call for deep operations on all links except |
|---|
| 299 | that destructive operations on non-reference counted links are either shallow, |
|---|
| 300 | or fail altogether in the case of trying to remove a non-reference counted link |
|---|
| 301 | to a directory.</p> |
|---|
| 302 | <p>Rationale: Follows existing practice (POSIX, Windows, etc.).</p> |
|---|
| 303 | <p><b>No atomic-operation or rollback guarantee</b> - Filesystem Library |
|---|
| 304 | functions which throw exceptions may leave the external file system in an |
|---|
| 305 | altered state. It is suggested that implementations provide stronger guarantees |
|---|
| 306 | when possible.</p> |
|---|
| 307 | <p>Rationale: Implementers shouldn't be required to provide guarantees which are |
|---|
| 308 | impossible to meet on some operating systems. Implementers should be given |
|---|
| 309 | normative encouragement to provide those guarantees when possible.</p> |
|---|
| 310 | <p><b>Graceful degradation</b> - Filesystem Library functions which cannot |
|---|
| 311 | be fully supported on a particular operating system will be partially supported |
|---|
| 312 | if possible. Implementations must document such partial support. Functions which |
|---|
| 313 | are requested to provide some operation which they cannot support should report |
|---|
| 314 | an error at compile time (preferred) or throw an exception at runtime.</p> |
|---|
| 315 | <p>Rationale: Implementations on less-powerful operating systems should provide |
|---|
| 316 | useful functionality if possible, but are not be required to simulate |
|---|
| 317 | features not present in the underlying operating system.</p> |
|---|
| 318 | <h2><a name="Race-condition">Race-condition</a> d<a name="Dangers">anger</a></h2> |
|---|
| 319 | <p>The state of files and directories is often |
|---|
| 320 | globally shared, and thus may be changed unexpectedly by other threads, |
|---|
| 321 | processes, or even other computers having network access to the filesystem. As an |
|---|
| 322 | example of the difficulties this can cause, note that the following asserts |
|---|
| 323 | may fail:</p> |
|---|
| 324 | <blockquote> |
|---|
| 325 | <p><code>assert( exists( "foo" ) == exists( "foo" ) ); // |
|---|
| 326 | (1)<br> |
|---|
| 327 | <br> |
|---|
| 328 | remove_all( "foo" );<br> |
|---|
| 329 | assert( !exists( "foo" ) ); // (2)<br> |
|---|
| 330 | <br> |
|---|
| 331 | assert( is_directory( "foo" ) == is_directory( "foo" ) ); // |
|---|
| 332 | (3)</code></p> |
|---|
| 333 | </blockquote> |
|---|
| 334 | <p>(1) will fail if a non-existent "foo" comes into existence, or an |
|---|
| 335 | existent "foo" is removed, between the first and second call to <i>exists()</i>. |
|---|
| 336 | This could happen if, during the execution of the example code, another thread, |
|---|
| 337 | process, or computer is also performing operations in the same directory.</p> |
|---|
| 338 | <p>(2) will fail if between the call to <i>remove_all()</i> and the call to |
|---|
| 339 | <i>exists()</i> a new file or directory named "foo" is created by another |
|---|
| 340 | thread, process, or computer.</p> |
|---|
| 341 | <p>(3) will fail if another thread, process, or computer removes an |
|---|
| 342 | existing file "foo" and then creates a directory named "foo", between the |
|---|
| 343 | example code's two calls to <i>is_directory()</i>.</p> |
|---|
| 344 | <p>A program which needs to be robust when operating on potentially-shared file |
|---|
| 345 | or directory resources should be prepared for <i>filesystem_error</i> exceptions |
|---|
| 346 | to be thrown from any filesystem function except those explicitly specified as |
|---|
| 347 | not throwing exceptions.</p> |
|---|
| 348 | <h2><a name="Implementation">Implementation</a></h2> |
|---|
| 349 | <p>The current implementation supports operating systems that have |
|---|
| 350 | either the POSIX or Windows API's available.</p> |
|---|
| 351 | <p>The following tests are provided:</p> |
|---|
| 352 | <ul> |
|---|
| 353 | <li><a href="../test/path_test.cpp">path_test.cpp</a></li> |
|---|
| 354 | <li><a href="../test/operations_test.cpp">operations_test.cpp</a></li> |
|---|
| 355 | <li><a href="../test/fstream_test.cpp">fstream_test.cpp</a></li> |
|---|
| 356 | <li><a href="../test/convenience_test.cpp">convenience_test.cpp</a></li> |
|---|
| 357 | </ul> |
|---|
| 358 | <p>The library is in regular use on Apple Mac OS, HP-UX, IBM AIX, Linux, |
|---|
| 359 | Microsoft Windows, SGI IRIX, and Sun Solaris operating systems using a variety |
|---|
| 360 | of compilers.</p> |
|---|
| 361 | <h2><a name="Building">Building</a> the object-library</h2> |
|---|
| 362 | <p>The object-library will normally be built automatically. See |
|---|
| 363 | <a href="../../../more/getting_started.html">Getting Started</a>. It can also be |
|---|
| 364 | built manually using a <a href="../build/Jamfile">Jamfile</a> |
|---|
| 365 | supplied in directory libs/filesystem/build, or the user can construct an IDE |
|---|
| 366 | project or make file which includes the object-library source files.</p> |
|---|
| 367 | <p>The object-library source files (<a href="../src/convenience.cpp">convenience.cpp</a>, |
|---|
| 368 | <a href="../src/exception.cpp">exception.cpp</a>, |
|---|
| 369 | <a href="../src/operations_posix_windows.cpp">operations_posix_windows.cpp</a>, |
|---|
| 370 | and <a href="../src/path_posix_windows.cpp">path_posix_windows.cpp</a>) are |
|---|
| 371 | supplied in directory libs/filesystem/src. These source files implement the |
|---|
| 372 | library for POSIX or Windows compatible operating systems; no implementation is |
|---|
| 373 | supplied for other operating systems. Note that many operating systems not |
|---|
| 374 | normally thought of as POSIX systems, such as mainframe legacy |
|---|
| 375 | operating systems or embedded operating systems, support POSIX compatible file |
|---|
| 376 | systems which will work with the Filesystem Library.</p> |
|---|
| 377 | <p>The object-library can be built for static or dynamic (shared/dll) linking. |
|---|
| 378 | This is controlled by the BOOST_ALL_DYN_LINK or BOOST_FILESYSTEM_DYN_LINK |
|---|
| 379 | macros. See the <a href="../../../more/separate_compilation.html">Separate |
|---|
| 380 | Compilation</a> page for a description of the techniques used.</p> |
|---|
| 381 | <h3>Note for <a name="Cgywin">Cygwin</a> users</h3> |
|---|
| 382 | <p>The library's implementation code automatically detects the current platform, |
|---|
| 383 | and compiles the POSIX or Windows implementation code accordingly. Automatic |
|---|
| 384 | platform detection during object library compilation can be overridden by |
|---|
| 385 | defining BOOST_POSIX or BOOST_WINDOWS macros. With the exception of the Cygwin |
|---|
| 386 | environment, there is usually no reason to define one of the macros, as the |
|---|
| 387 | software development kits supplied with most compilers only support a single |
|---|
| 388 | platform.</p> |
|---|
| 389 | <p>The <a href="http://www.cygwin.com/">Cygwin</a> package of tools supports |
|---|
| 390 | traditional Windows usage, but also provides an emulation layer and other tools |
|---|
| 391 | which can be used to make Windows act as Linux (and thus POSIX), and provide the |
|---|
| 392 | Linux look-and-feel. GCC is usually the compiler of choice in this environment, |
|---|
| 393 | as it can be installed via the Cygwin install process. Other compilers can also |
|---|
| 394 | use the Cygwin emulation of POSIX, at least in theory.</p> |
|---|
| 395 | <p>Those wishing to use the Cygwin POSIX emulation layer should define the |
|---|
| 396 | BOOST_POSIX macro when compiling the Boost Filesystem Library's object-library. |
|---|
| 397 | The macro does not need to be defined (and will have no effect if defined) for |
|---|
| 398 | Boost Filesystem Library user programs.</p> |
|---|
| 399 | <h2><a name="Acknowledgements">Acknowledgements</a></h2> |
|---|
| 400 | <p>The Filesystem Library was designed and implemented by Beman Dawes. The <i>directory_iterator</i> and <i>filesystem_error</i> classes were |
|---|
| 401 | based on prior work from Dietmar Kühl, as modified by Jan Langer. Thomas Witt |
|---|
| 402 | was a particular help in later stages of development.</p> |
|---|
| 403 | |
|---|
| 404 | <p>Key <a href="design.htm#Requirements">design requirements</a> and |
|---|
| 405 | <a href="design.htm#Realities">design realities</a> were developed during |
|---|
| 406 | extensive discussions on the Boost mailing list, followed by comments on the |
|---|
| 407 | initial implementation. Numerous helpful comments were then received during the |
|---|
| 408 | Formal Review.<p>Participants included |
|---|
| 409 | Aaron Brashears, |
|---|
| 410 | Alan Bellingham, |
|---|
| 411 | Aleksey Gurtovoy, |
|---|
| 412 | Alex Rosenberg, |
|---|
| 413 | Alisdair Meredith, |
|---|
| 414 | Andy Glew, |
|---|
| 415 | Anthony Williams, |
|---|
| 416 | Baptiste Lepilleur, |
|---|
| 417 | Beman Dawes, |
|---|
| 418 | Bill Kempf, |
|---|
| 419 | Bill Seymour, |
|---|
| 420 | Carl Daniel, |
|---|
| 421 | Chris Little, |
|---|
| 422 | Chuck Allison, |
|---|
| 423 | Craig Henderson, |
|---|
| 424 | Dan Nuffer, |
|---|
| 425 | Dan'l Miller, |
|---|
| 426 | Daniel Frey, |
|---|
| 427 | Darin Adler, |
|---|
| 428 | David Abrahams, |
|---|
| 429 | David Held, |
|---|
| 430 | Davlet Panech, |
|---|
| 431 | Dietmar Kuehl, |
|---|
| 432 | Douglas Gregor, |
|---|
| 433 | Dylan Nicholson, |
|---|
| 434 | Ed Brey, |
|---|
| 435 | Eric Jensen, |
|---|
| 436 | Eric Woodruff, |
|---|
| 437 | Fedder Skovgaard, |
|---|
| 438 | Gary Powell, |
|---|
| 439 | Gennaro Prota, |
|---|
| 440 | Geoff Leyland, |
|---|
| 441 | George Heintzelman, |
|---|
| 442 | Giovanni Bajo, |
|---|
| 443 | Glen Knowles, |
|---|
| 444 | Hillel Sims, |
|---|
| 445 | Howard Hinnant, |
|---|
| 446 | Jaap Suter, |
|---|
| 447 | James Dennett, |
|---|
| 448 | Jan Langer, |
|---|
| 449 | Jani Kajala, |
|---|
| 450 | Jason Stewart, |
|---|
| 451 | Jeff Garland, |
|---|
| 452 | Jens Maurer, |
|---|
| 453 | Jesse Jones, |
|---|
| 454 | Jim Hyslop, |
|---|
| 455 | Joel de Guzman, |
|---|
| 456 | Joel Young, |
|---|
| 457 | John Levon, |
|---|
| 458 | John Maddock, |
|---|
| 459 | John Williston, |
|---|
| 460 | Jonathan Caves, |
|---|
| 461 | Jonathan Biggar, |
|---|
| 462 | Jurko, |
|---|
| 463 | Justus Schwartz, |
|---|
| 464 | Keith Burton, |
|---|
| 465 | Ken Hagen, |
|---|
| 466 | Kostya Altukhov, |
|---|
| 467 | Mark Rodgers, |
|---|
| 468 | Martin Schuerch, |
|---|
| 469 | Matt Austern, |
|---|
| 470 | Matthias Troyer, |
|---|
| 471 | Mattias Flodin, |
|---|
| 472 | Michiel Salters, |
|---|
| 473 | Mickael Pointier, |
|---|
| 474 | Misha Bergal, |
|---|
| 475 | Neal Becker, |
|---|
| 476 | Noel Yap, |
|---|
| 477 | Parksie, |
|---|
| 478 | Patrick Hartling, Pavel Vozenilek, |
|---|
| 479 | Pete Becker, |
|---|
| 480 | Peter Dimov, |
|---|
| 481 | Rainer Deyke, |
|---|
| 482 | Rene Rivera, |
|---|
| 483 | Rob Lievaart, |
|---|
| 484 | Rob Stewart, |
|---|
| 485 | Ron Garcia, |
|---|
| 486 | Ross Smith, |
|---|
| 487 | Sashan, |
|---|
| 488 | Steve Robbins, |
|---|
| 489 | Thomas Witt, |
|---|
| 490 | Tom Harris, |
|---|
| 491 | Toon Knapen, |
|---|
| 492 | Victor Wagner, |
|---|
| 493 | Vincent Finn, |
|---|
| 494 | Vladimir Prus, and |
|---|
| 495 | Yitzhak Sapir |
|---|
| 496 | |
|---|
| 497 | <p>A lengthy discussion on the C++ committee's library reflector illuminated the "illusion |
|---|
| 498 | of portability" problem, particularly in postings by PJ Plauger and Pete Becker.</p> |
|---|
| 499 | |
|---|
| 500 | <p>Walter Landry provided much help illuminating symbolic link use cases for |
|---|
| 501 | version 1.31.0.</p> |
|---|
| 502 | |
|---|
| 503 | <h2><a name="Change-history">Change history</a></h2> |
|---|
| 504 | |
|---|
| 505 | <h3>Version 1.32.0</h3> |
|---|
| 506 | |
|---|
| 507 | <ul> |
|---|
| 508 | <li><a href="operations.htm#file_size">file_size()</a> function added.</li> |
|---|
| 509 | <li>Class path <a href="path.htm#operator_eq">relational operators</a> added.</li> |
|---|
| 510 | <li><a href="operations.htm#equivalent">equivalent()</a> function added.</li> |
|---|
| 511 | <li><a href="operations.htm#create_directory">create_directory()</a> no longer |
|---|
| 512 | throws if the directory already exists. A bool is returned, indicating that |
|---|
| 513 | the directory did not preexist. Similar changes made to |
|---|
| 514 | <a href="convenience.htm">create_directories()</a>.</li> |
|---|
| 515 | <li><a href="#Cgywin">Docs added</a> for users wishing Cygwin/POSIX behavior |
|---|
| 516 | on Windows.</li> |
|---|
| 517 | <li>For POSIX, Large File Support (LSF) is enabled if available, such as on |
|---|
| 518 | Linux.</li> |
|---|
| 519 | <li><a href="operations.htm#current_path">current_path()</a> and |
|---|
| 520 | <a href="operations.htm#initial_path">initial_path()</a> on POSIX now handle |
|---|
| 521 | very long paths correctly.</li> |
|---|
| 522 | </ul> |
|---|
| 523 | |
|---|
| 524 | <h3>Version 1.31.0</h3> |
|---|
| 525 | |
|---|
| 526 | <ul> |
|---|
| 527 | <li>The object library can now be <a href="#Building">built</a> for either |
|---|
| 528 | static or dynamic (shared/dll) linking. </li> |
|---|
| 529 | <li>Several added functions, including improved checking for directory and |
|---|
| 530 | file name portability. See <a href="path.htm#default_name_check">Default name |
|---|
| 531 | check functions</a>, <a href="path.htm#name_check_mechanism">Default name |
|---|
| 532 | check mechanism</a>, and <a href="portability_guide.htm#name_check_functions"> |
|---|
| 533 | Name check functions</a>.</li> |
|---|
| 534 | <li>Separation of <a href="path.htm#Canonical">Canonical form</a> and |
|---|
| 535 | <a href="path.htm#Normalized">Normalized form</a> and a new path member |
|---|
| 536 | function <a href="path.htm#normalize">normalize()</a>. This changes behavior, |
|---|
| 537 | in that canonical form is now different, but eliminates a subtle |
|---|
| 538 | <a href="design.htm#symbolic-link-use-case">bug</a> when symbolic links to |
|---|
| 539 | directories are present. </li> |
|---|
| 540 | </ul> |
|---|
| 541 | |
|---|
| 542 | <hr> |
|---|
| 543 | <p>Revised |
|---|
| 544 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->02 August, 2005<!--webbot bot="Timestamp" endspan i-checksum="34600" --></p> |
|---|
| 545 | |
|---|
| 546 | <p>© Copyright Beman Dawes, 2002</p> |
|---|
| 547 | <p> Use, modification, and distribution are subject to the Boost Software |
|---|
| 548 | License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt"> |
|---|
| 549 | LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt"> |
|---|
| 550 | www.boost.org/LICENSE_1_0.txt</a>)</p> |
|---|
| 551 | |
|---|
| 552 | </body> |
|---|
| 553 | |
|---|
| 554 | </html> |
|---|
