| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> |
| <meta name="ProgId" content="FrontPage.Editor.Document"> |
| <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> |
| <title>Filesystem Home</title> |
| <link rel="stylesheet" type="text/css" href="../../../../doc/src/minimal.css"> |
| </head> |
| |
| <body> |
| |
| <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="710"> |
| <tr> |
| <td width="277"> |
| <a href="../../../../index.htm"> |
| <img src="../../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td> |
| <td width="410" align="middle"> |
| <font size="7">Filesystem Library<br> |
| Version 2</font> |
| </td> |
| </tr> |
| </table> |
| |
| <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%"> |
| <tr> |
| <td><a href="../../../../index.htm">Boost Home</a> |
| <a href="index.htm">Library Home</a> <a href="#tutorial">Tutorial</a> <a href="reference.html"> |
| Reference</a> <a href="faq.htm">FAQ</a></td> |
| </tr> |
| </table> |
| |
| <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right"> |
| <tr> |
| <td width="100%" bgcolor="#D7EEFF" align="center"> |
| <i><b>Contents</b></i></td> |
| </tr> |
| <tr> |
| <td width="100%" bgcolor="#E8F5FF"> |
| <a href="#Introduction">Introduction</a><br> |
| <a href="#Using">Using the library</a><br> |
| <a href="#tutorial">Two-minute tutorial</a><br> |
| <a href="#Cautions">Cautions</a><br> |
| <a href="#Examples">Example programs</a><br> |
| <a href="#Implementation">Implementation</a><br> |
| <a href="#Macros">Macros</a><br> |
| <a href="#Deprecated-names">Deprecated names and features</a><br> |
| <a href="#narrow-only">Using only narrow character paths</a><br> |
| <a href="#Building">Building the object-library</a><br> |
| <a href="#Cgywin">Notes for Cygwin users</a><br> |
| <a href="#Acknowledgements">Acknowledgements</a><br> |
| <a href="#Change-history">Change history</a></td> |
| </tr> |
| <tr> |
| <td width="100%" bgcolor="#D7EEFF" align="center"> |
| <i><b>Other Documents</b></i></td> |
| </tr> |
| <tr> |
| <td width="100%" bgcolor="#E8F5FF"> |
| <a href="reference.html">Reference</a><br> |
| <a href="design.htm">Library Design</a><br> |
| <a href="faq.htm">FAQ</a><br> |
| <a href="portability_guide.htm">Portability Guide</a><br> |
| <a href="do-list.htm">Do-list</a> |
| </td> |
| </tr> |
| </table> |
| |
| <div align="center"> |
| <center> |
| <table border="1" cellpadding="10" cellspacing="1" style="border-collapse: collapse" bordercolor="#111111"> |
| <tr> |
| <td> |
| <p align="center"><b>This is Version 2 of the Filesystem library.</b></p> |
| <p align="center"><a href="../../v3/doc/index.htm">Version 3</a>, a major revision with many new and improved |
| features is also available, but breaks some existing code.</p> |
| <p align="center">Version 2 is the default version for Boost release 1.44 |
| only. Version 3 will become the default starting with release 1.45.</p> |
| <p align="center">Existing code should be moved to version 3 as soon as |
| convenient. New code should be written for version 3.</p> |
| <p align="center">Version 2 is deprecated, and will be removed from Boost |
| releases at the end of a transition period.</p> |
| </td> |
| </tr> |
| </table> |
| </center> |
| </div> |
| |
| <h2><a name="Introduction">Introduction</a></h2> |
| <p>The Boost.Filesystem library provides portable facilities to query and |
| manipulate paths, files, and directories.</p> |
| |
| <p>The motivation for the library is the need to perform portable script-like operations from within C++ programs. The intent is not to |
| compete with Python, Perl, or shell languages, but rather to provide portable filesystem |
| operations when C++ is already the language of choice. The <a href="design.htm"> |
| design</a> encourages, but does not require, safe and portable usage.</p> |
| |
| <p>Programs using the library are <b><i>portable</i></b>, both in the sense that |
| the syntax of program code is portable, and the sense that the semantics or |
| behavior of code is portable. The <a href="reference.html">generic path |
| grammar</a> is another important aid to portability.</p> |
| |
| <p>Usage is <i><b>safe</b></i> in the sense that errors cannot be ignored since most functions throw C++ |
| exceptions when errors are detected. This is also convenient for users because |
| it alleviates the need to explicitly check error |
| return codes.</p> |
| |
| <p>A proposal, |
| <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1975.html"> |
| N1975</a>, to include Boost.Filesystem in Technical Report 2 has been accepted |
| by the C++ Standards Committee. The Boost.Filesystem library will stay in |
| alignment with the TR2 Filesystem proposal as it works its way through the TR2 |
| process. Note, however, that namespaces and header granularity differs between |
| Boost.Filesystem and the TR2 proposal.</p> |
| |
| <p>The Boost.Filesystem library provides several headers:</p> |
| |
| <ul> |
| <li>Header <<a href="../../../../boost/filesystem.hpp">boost/filesystem.hpp</a>> provides class <i> |
| basic_path, </i>a portable mechanism for representing |
| <a href="#path">paths</a> in C++ programs. Typedefs <i>path</i> and <i> |
| wpath</i> ease the most common usages of <i>basic_path</i>. Operational |
| functions provide useful query and maintenance operations on files and directories. |
| Class <i>basic_directory_iterator</i> with typdefs <i> |
| directory_iterator</i> and <i>wdirectory_iterator</i> provide iteration over |
| the contents of directories. Convenience functions and classes combine lower-level functionality |
| in useful ways.<br> |
| </li> |
| <li>Header <<a href="../../../../boost/filesystem/fstream.hpp">boost/filesystem<i>/</i>fstream.hpp</a>> provides the same components as the C++ Standard |
| Library's <i>fstream</i> header, except |
| that files are identified by <i>basic_path</i> objects rather that <i>char *</i>'s.</li> |
| </ul> |
| <h2><a name="Using">Using</a> the library</h2> |
| <p>Boost.Filesystem is implemented as a separately compiled library, so before |
| using it you must install it in a location that can be found by your linker. See |
| <a href="#Building">Building the object-library</a>. </p> |
| <p>The library's <a href="../example">example directory</a> contains very simple |
| scripts for building the <a href="#Examples">example programs</a> on various |
| platforms. You can use these scripts to see what's needed to compile and link |
| your own programs.</p> |
| <h2>Two-minute <a name="tutorial">tutorial</a></h2> |
| <p>(A |
| <a href="http://beans.seartipy.com/2006/05/10/boost-filesystem-library-writing-portable-c-programs-to-acess-the-filesystem/"> |
| more elaborate tutorial</a> is also available from Tabrez Iqbal.)</p> |
| <p>First some preliminaries:</p> |
| <blockquote> |
| <pre>#include "boost/filesystem.hpp" // includes all needed Boost.Filesystem declarations |
| #include <iostream> // for std::cout |
| using boost::filesystem; // for ease of tutorial presentation; |
| // a namespace alias is preferred practice in real code</pre> |
| </blockquote> |
| <p>A <a href="reference.html#Class-template-basic_path">class <i>path</i></a> object can be created:</p> |
| <blockquote> |
| <pre>path my_path( "some_dir/file.txt" );</pre> |
| </blockquote> |
| <p>The string passed to the <i>path</i> constructor may be in a |
| <a href="reference.html#Pathname-formats">portable generic path format</a> or an |
| implementation-defined native operating system format. Access functions |
| make <i>my_path</i> contents available to the underlying operating system API in an operating system dependent format, |
| such as <code>"some_dir:file.txt"</code>, <code>"[some_dir]file.txt"</code>, |
| <code>"some_dir/file.txt"</code>, or whatever is appropriate for the |
| operating system. If class <i>wpath</i> is used instead of class <i>path</i>, |
| translation between wide and narrow character paths is performed automatically |
| if necessary for the operating system.</p> |
| <p>Class <i>path</i> has conversion constructors from <i>const char*</i> and <i> |
| const std:: string&</i>, so that even though the Filesystem Library |
| functions used in the following code snippet have <i>const path&</i> formal |
| parameters, the user can just |
| code C-style strings as actual arguments:</p> |
| <blockquote> |
| <pre>remove_all( "foobar" ); |
| create_directory( "foobar" ); |
| ofstream file( "foobar/cheeze" ); |
| file << "tastes good!\n"; |
| file.close(); |
| if ( !exists( "foobar/cheeze" ) ) |
| std::cout << "Something is rotten in foobar\n";</pre> |
| </blockquote> |
| <p>To make class <i>path</i> objects easy to use in expressions, <i>operator/</i> |
| appends paths:</p> |
| <blockquote> |
| <pre>ifstream file1( arg_path / "foo/bar" ); |
| ifstream file2( arg_path / "foo" / "bar" );</pre> |
| </blockquote> |
| <p>The expressions <i>arg_path / "foo/bar"</i> and <i>arg_path / "foo" |
| / "bar"</i> yield identical results.</p> |
| <p>Paths can include references to the current directory, using "<code>.</code>" |
| notation, and the parent directory, using "<code>..</code>" |
| notation.</p> |
| <p><a href="reference.html#Class-template-basic_directory_iterator">Class <i>basic_directory_iterator</i></a> |
| is an important component of the library. It provides an input iterator over the |
| contents of a directory, with the value type being class <i>basic_path</i>. |
| Typedefs <i>directory_iterator</i> and <i>wdirectory_iterator</i> are provided |
| to cover the most common use cases.</p> |
| <p>The following function, given a directory path and a file name, recursively |
| searches the directory and its sub-directories for the file name, returning a |
| bool, and if successful, the path to the file that was found. The code |
| below is extracted from a real program, slightly modified for clarity:</p> |
| <blockquote> |
| <pre>bool find_file( const path & dir_path, // in this directory, |
| const std::string & file_name, // search for this name, |
| path & path_found ) // placing path here if found |
| { |
| if ( !exists( dir_path ) ) return false; |
| directory_iterator end_itr; // default construction yields past-the-end |
| for ( directory_iterator itr( dir_path ); |
| itr != end_itr; |
| ++itr ) |
| { |
| if ( is_directory(itr->status()) ) |
| { |
| if ( find_file( itr->path(), file_name, path_found ) ) return true; |
| } |
| else if ( itr->path().filename() == file_name ) // see below |
| { |
| path_found = itr->path(); |
| return true; |
| } |
| } |
| return false; |
| }</pre> |
| </blockquote> |
| <p>The expression <i>itr->path().filename() == file_name</i>, in the line commented <i>// |
| see below</i>, calls the <i>filename()</i> function on the <i>path</i> returned by |
| calling the <i>path()</i> function of the <i>directory_entry </i>object pointed |
| to by the iterator. <i>filename()</i> returns a string which is a copy of the |
| last (closest to the leaf, farthest from the root) file or directory name in the |
| <i>path</i> object.</p> |
| <p>Notice that <i>find_file()</i> does not do explicit error checking, such as |
| verifying that the <i>dir_path</i> argument really represents a directory. |
| Boost.Filesystem functions throw |
| exceptions if they do not complete successfully, so there is enough implicit |
| error checking that this application doesn't need to supply additional error |
| checking code unless desired. Several Boost.Filesystem functions have non-throwing |
| versions, to ease use cases where exceptions would not be appropriate.</p> |
| <blockquote> |
| <p><i>Note: </i>Recursive |
| directory iteration was added as a convenience function after the above tutorial code |
| was written, so nowadays you |
| don't have to actually code the recursion yourself.</p> |
| </blockquote> |
| <h2><a name="Cautions">Cautions</a></h2> |
| <p>After reading the tutorial you can dive right into simple, |
| script-like programs using the Filesystem Library! Before doing any serious |
| work, however, there a few cautions to be aware of:</p> |
| <h4><b>Effects and Postconditions not guaranteed in the presence of race-conditions</b></h4> |
| <p>Filesystem function specifications follow the C++ Standard Library form, specifying behavior in terms of |
| effects and postconditions. If |
| a <a href="reference.html#Race-condition">race-condition</a> exists, a function's |
| postconditions may no longer be true by the time the function returns to the |
| caller.</p> |
| <blockquote> |
| <p><b><i>Explanation: </i></b>The state of files and directories is often |
| globally shared, and thus may be changed unexpectedly by other threads, |
| processes, or even other computers having network access to the filesystem. As an |
| example of the difficulties this can cause, note that the following asserts |
| may fail:</p> |
| <blockquote> |
| <p><code>assert( exists( "foo" ) == exists( "foo" ) ); // |
| (1)<br> |
| <br> |
| remove_all( "foo" );<br> |
| assert( !exists( "foo" ) ); // (2)<br> |
| <br> |
| assert( is_directory( "foo" ) == is_directory( "foo" ) ); // |
| (3)</code></p> |
| </blockquote> |
| <p>(1) will fail if a non-existent "foo" comes into existence, or an |
| existent "foo" is removed, between the first and second call to <i>exists()</i>. |
| This could happen if, during the execution of the example code, another thread, |
| process, or computer is also performing operations in the same directory.</p> |
| <p>(2) will fail if between the call to <i>remove_all()</i> and the call to |
| <i>exists()</i> a new file or directory named "foo" is created by another |
| thread, process, or computer.</p> |
| <p>(3) will fail if another thread, process, or computer removes an |
| existing file "foo" and then creates a directory named "foo", between the |
| example code's two calls to <i>is_directory()</i>.</p> |
| </blockquote> |
| <h4><b>May throw exceptions</b></h4> |
| <p>Unless otherwise specified, Boost.Filesystem functions throw <i> |
| <a href="reference.html#basic_filesystem_error-constructors">basic_filesystem_error</a></i> |
| exceptions if they cannot successfully complete their operational |
| specifications. Also, implementations may use C++ Standard Library functions, |
| which may throw <i>std::bad_alloc</i>. These exceptions may be thrown even |
| though the error condition leading to the exception is not explicitly specified |
| in the function's "Throws" paragraph.</p> |
| <p>All exceptions thrown by the Filesystem |
| Library are implemented by calling <a href="../../../utility/throw_exception.html"> |
| boost::throw_exception()</a>. Thus exact behavior may differ depending on |
| BOOST_NO_EXCEPTIONS at the time the filesystem source files are compiled.</p> |
| <p>Non-throwing versions are provided of several functions that are often used |
| in contexts where error codes may be the preferred way to report an error.</p> |
| <h2><a name="Examples">Example programs</a></h2> |
| <h3><a href="../example/simple_ls.cpp">simple_ls.cpp</a></h3> |
| <p>The example program <a href="../example/simple_ls.cpp">simple_ls.cpp</a> is |
| given a path as a command line argument. Since the command line argument may be |
| a relative path, the complete path is determined so that messages displayed |
| can be more precise.</p> |
| <p>The program checks to see if the path exists; if not a message is printed.</p> |
| <p>If the path identifies a directory, the directory is iterated through, |
| printing the name of the entries found, and an indication if they are |
| directories. A count of directories and files is updated, and then printed after |
| the iteration is complete.</p> |
| <p>If the path is for a file, a message indicating that is printed.</p> |
| <p>Try compiling and executing <a href="../example/simple_ls.cpp">simple_ls.cpp</a> |
| to see how it works on your system. Try various path arguments to see what |
| happens.</p> |
| <h3><a href="../example/file_size.cpp">file_size.cpp</a></h3> |
| <p>This example program prints the file's size if it is a regular file.</p> |
| <h3>Other examples</h3> |
| <p>The programs used to generate the Boost regression test status tables use the |
| Filesystem Library extensively. See:</p> |
| <ul> |
| <li><a href="../../../../tools/regression/src/process_jam_log.cpp">process_jam_log.cpp</a></li> |
| <li><a href="../../../../tools/regression/src/compiler_status.cpp">compiler_status.cpp</a></li> |
| </ul> |
| <p>Test programs are sometimes useful in understanding a library, as they |
| illustrate what the developer expected to work and not work. See:</p> |
| <ul> |
| <li><a href="../test/wide_test.cpp">wide_test.cpp</a></li> |
| <li><a href="../test/path_test.cpp">path_test.cpp</a></li> |
| <li><a href="../test/operations_test.cpp">operations_test.cpp</a></li> |
| <li><a href="../test/fstream_test.cpp">fstream_test.cpp</a></li> |
| </ul> |
| <h2><a name="Implementation">Implementation</a></h2> |
| <p>The current implementation supports operating systems which provide |
| either the POSIX or Windows API.</p> |
| <p>The library is in regular use on Apple OS X, HP-UX, IBM AIX, Linux, |
| Microsoft Windows, SGI IRIX, and Sun Solaris operating systems using a variety |
| of compilers.</p> |
| <h2><a name="Macros">Macros</a></h2> |
| <p>Users may defined the following macros if desired. Sensible defaults are |
| provided, so users can ignore these macros unless they have special needs.</p> |
| <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111"> |
| <tr> |
| <td><b><i>Macro Name</i></b></td> |
| <td><b><i>Default</i></b></td> |
| <td><b><i>Effect if defined</i></b></td> |
| </tr> |
| <tr> |
| <td valign="top"><code>BOOST_FILESYSTEM_DYN_LINK</code></td> |
| <td valign="top">Defined if <code>BOOST_ALL_DYN_LINK</code> is defined, |
| otherwise not defined.</td> |
| <td valign="top">Boost.System library is dynamically linked. If not defined, |
| static linking is assumed.</td> |
| </tr> |
| <tr> |
| <td valign="top"><code>BOOST_FILESYSTEM_NO_LIB</code></td> |
| <td valign="top">Defined if <code>BOOST_ALL_NO_LIB</code> is defined, |
| otherwise not defined.</td> |
| <td valign="top">Boost.System library does not use the Boost auto-link |
| facility.</td> |
| </tr> |
| <tr> |
| <td valign="top"><code>BOOST_FILESYSTEM_NARROW_ONLY</code></td> |
| <td valign="top">Not defined.</td> |
| <td valign="top">Removes features that require wchar_t support.</td> |
| </tr> |
| <tr> |
| <td valign="top"><code>BOOST_FILESYSTEM_NO_DEPRECATED</code></td> |
| <td valign="top">Not defined.</td> |
| <td valign="top">Deprecated features are excluded.</td> |
| </tr> |
| </table> |
| <h2><a name="Deprecated-names">Deprecated names</a> and features</h2> |
| <p style="font-size: 10pt">User-defined BOOST_POSIX_API and BOOST_WINDOWS_API |
| macros are no longer supported.</p> |
| <p style="font-size: 10pt">As the library evolves over time, names sometimes |
| change or features are removed. To ease transition, Boost.Filesystem deprecates |
| the old names and features, but continues to provide them unless macro <code> |
| BOOST_FILESYSTEM_NO_DEPRECATED</code> is defined.</p> |
| <table border="1" cellpadding="5" cellspacing="1" style="border-collapse: collapse" bordercolor="#111111"> |
| <tr> |
| <td style="font-size: 10pt"> |
| <b><i>Component</i></b></td> |
| <td style="font-size: 10pt"> |
| <p style="font-size: 10pt"><b><i>Old name, now deprecated</i></b></td> |
| <td style="font-size: 10pt"> |
| <p style="font-size: 10pt"><b><i>New name</i></b></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"><code>basic_path</code></td> |
| <td style="font-size: 10pt"><code>leaf()</code></td> |
| <td style="font-size: 10pt"><code>filename()</code></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"><code>basic_path</code></td> |
| <td style="font-size: 10pt"><code>branch_path()</code></td> |
| <td style="font-size: 10pt"><code>parent_path()</code></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"><code>basic_path</code></td> |
| <td style="font-size: 10pt"><code>has_leaf()</code></td> |
| <td style="font-size: 10pt"><code>has_filename()</code></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"><code>basic_path</code></td> |
| <td style="font-size: 10pt"><code>has_branch_path()</code></td> |
| <td style="font-size: 10pt"><code>has_parent_path()</code></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_path</code></td> |
| <td style="font-size: 10pt"> |
| <p style="font-size: 10pt"><code>remove_leaf()</code></td> |
| <td style="font-size: 10pt"> |
| <p style="font-size: 10pt"><code>remove_filename()</code></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_path</code></td> |
| <td style="font-size: 10pt"> |
| <code>basic_path( const string_type & str,<br> |
| name_check )</code></td> |
| <td style="font-size: 10pt"> |
| <i><code>feature removed</code></i></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_path</code></td> |
| <td style="font-size: 10pt"> |
| <code>basic_path( const string_type::value_type * s,<br> |
| name_check )</code></td> |
| <td style="font-size: 10pt"> |
| <i><code>feature removed</code></i></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_path</code></td> |
| <td style="font-size: 10pt"> |
| <code>native_file_string()</code></td> |
| <td style="font-size: 10pt"> |
| <code>file_string()</code></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_path</code></td> |
| <td style="font-size: 10pt"> |
| <code>native_directory_string()</code></td> |
| <td style="font-size: 10pt"> |
| <code>directory_string()</code></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_path</code></td> |
| <td style="font-size: 10pt"> |
| <code>default_name_check_writable()</code></td> |
| <td style="font-size: 10pt"> |
| <i><code>feature removed</code></i></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_path</code></td> |
| <td style="font-size: 10pt"> |
| <code>default_name_check( name_check )</code></td> |
| <td style="font-size: 10pt"> |
| <i><code>feature removed</code></i></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_path</code></td> |
| <td style="font-size: 10pt"> |
| <code>default_name_check()</code></td> |
| <td style="font-size: 10pt"> |
| <i><code>feature removed</code></i></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_path</code></td> |
| <td style="font-size: 10pt"> |
| <code>canonize()</code></td> |
| <td style="font-size: 10pt"> |
| <i><code>feature removed</code></i></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_path</code></td> |
| <td style="font-size: 10pt"> |
| <code>normalize()</code></td> |
| <td style="font-size: 10pt"> |
| <i><code>feature removed</code></i></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>operations.hpp</code></td> |
| <td style="font-size: 10pt"> |
| <code>is_regular( file_status f )</code></td> |
| <td style="font-size: 10pt"> |
| <code>is_regular_file( file_status f )</code></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>operations.hpp</code></td> |
| <td style="font-size: 10pt"> |
| <code>symbolic_link_exists( const path & ph )</code></td> |
| <td style="font-size: 10pt"> |
| <i><code>feature removed</code></i></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_directory_status</code></td> |
| <td style="font-size: 10pt"> |
| <code>filename()</code></td> |
| <td style="font-size: 10pt"> |
| <i><code>feature removed, use path().filename() instead</code></i></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_directory_status</code></td> |
| <td style="font-size: 10pt"> |
| <code>leaf()</code></td> |
| <td style="font-size: 10pt"> |
| <i><code>feature removed, use path().filename() instead</code></i></td> |
| </tr> |
| <tr> |
| <td style="font-size: 10pt" valign="top"> |
| <code>basic_directory_status</code></td> |
| <td style="font-size: 10pt"> |
| <code>string()</code></td> |
| <td style="font-size: 10pt"> |
| <i><code>feature removed, use path().string() instead</code></i></td> |
| </tr> |
| </table> |
| <h2><a name="narrow-only">Restricting library to narrow character paths</a></h2> |
| <p>Compilers or standard libraries which do not support wide characters (wchar_t) |
| or wide character strings (std::wstring) are detected automatically, and cause |
| the library to compile code that is restricted to narrow character paths |
| (boost::filesystem::path). Users can force this restriction by defining the |
| macro BOOST_FILESYSTEM_NARROW_ONLY. That may be useful for dealing with legacy |
| compilers or operating systems.</p> |
| <h2><a name="Building">Building</a> the object-library</h2> |
| <p>The object-library will be built automatically if you are using the Boost |
| build system. See |
| <a href="../../../../more/getting_started.html">Getting Started</a>. It can also be |
| built manually using a <a href="../build/Jamfile.v2">Jamfile</a> |
| supplied in directory libs/filesystem/build, or the user can construct an IDE |
| project or make file which includes the object-library source files.</p> |
| <p>The object-library source files are |
| supplied in directory <a href="../src">libs/filesystem/src</a>. These source files implement the |
| library for POSIX or Windows compatible operating systems; no implementation is |
| supplied for other operating systems. Note that many operating systems not |
| normally thought of as POSIX systems, such as mainframe legacy |
| operating systems or embedded operating systems, support POSIX compatible file |
| systems which will work with the Filesystem Library.</p> |
| <p>The object-library can be built for static or dynamic (shared/dll) linking. |
| This is controlled by the BOOST_ALL_DYN_LINK or BOOST_FILESYSTEM_DYN_LINK |
| macros. See the <a href="http://www.boost.org/development/separate_compilation.html">Separate |
| Compilation</a> page for a description of the techniques used.</p> |
| <h3>Note for <a name="Cgywin">Cygwin</a> users</h3> |
| <p>The library's implementation code treats <a href="http://www.cygwin.com/">Cygwin</a> |
| as a Windows platform, and thus uses the Windows API.</p> |
| <h2><a name="Acknowledgements">Acknowledgements</a></h2> |
| <p>The Filesystem Library was designed and implemented by Beman Dawes. The |
| original <i>directory_iterator</i> and <i>filesystem_error</i> classes were |
| based on prior work from Dietmar Kuehl, as modified by Jan Langer. Thomas Witt |
| was a particular help in later stages of initial development. Peter Dimov and |
| Rob Stewart made many useful suggestions and comments over a long period of |
| time. Howard Hinnant helped with internationalization issues.</p> |
| |
| <p>Key <a href="design.htm#Requirements">design requirements</a> and |
| <a href="design.htm#Realities">design realities</a> were developed during |
| extensive discussions on the Boost mailing list, followed by comments on the |
| initial implementation. Numerous helpful comments were then received during the |
| Formal Review.<p>Participants included |
| Aaron Brashears, |
| Alan Bellingham, |
| Aleksey Gurtovoy, |
| Alex Rosenberg, |
| Alisdair Meredith, |
| Andy Glew, |
| Anthony Williams, |
| Baptiste Lepilleur, |
| Beman Dawes, |
| Bill Kempf, |
| Bill Seymour, |
| Carl Daniel, |
| Chris Little, |
| Chuck Allison, |
| Craig Henderson, |
| Dan Nuffer, |
| Dan'l Miller, |
| Daniel Frey, |
| Darin Adler, |
| David Abrahams, |
| David Held, |
| Davlet Panech, |
| Dietmar Kuehl, |
| Douglas Gregor, |
| Dylan Nicholson, |
| Ed Brey, |
| Eric Jensen, |
| Eric Woodruff, |
| Fedder Skovgaard, |
| Gary Powell, |
| Gennaro Prota, |
| Geoff Leyland, |
| George Heintzelman, |
| Giovanni Bajo, |
| Glen Knowles, |
| Hillel Sims, |
| Howard Hinnant, |
| Jaap Suter, |
| James Dennett, |
| Jan Langer, |
| Jani Kajala, |
| Jason Stewart, |
| Jeff Garland, |
| Jens Maurer, |
| Jesse Jones, |
| Jim Hyslop, |
| Joel de Guzman, |
| Joel Young, |
| John Levon, |
| John Maddock, |
| John Williston, |
| Jonathan Caves, |
| Jonathan Biggar, |
| Jurko, |
| Justus Schwartz, |
| Keith Burton, |
| Ken Hagen, |
| Kostya Altukhov, |
| Mark Rodgers, |
| Martin Schuerch, |
| Matt Austern, |
| Matthias Troyer, |
| Mattias Flodin, |
| Michiel Salters, |
| Mickael Pointier, |
| Misha Bergal, |
| Neal Becker, |
| Noel Yap, |
| Parksie, |
| Patrick Hartling, Pavel Vozenilek, |
| Pete Becker, |
| Peter Dimov, |
| Rainer Deyke, |
| Rene Rivera, |
| Rob Lievaart, |
| Rob Stewart, |
| Ron Garcia, |
| Ross Smith, |
| Sashan, |
| Steve Robbins, |
| Thomas Witt, |
| Tom Harris, |
| Toon Knapen, |
| Victor Wagner, |
| Vincent Finn, |
| Vladimir Prus, and |
| Yitzhak Sapir |
| |
| <p>A lengthy discussion on the C++ committee's library reflector illuminated the "illusion |
| of portability" problem, particularly in postings by PJ Plauger and Pete Becker.</p> |
| |
| <p>Walter Landry provided much help illuminating symbolic link use cases for |
| version 1.31.0.</p> |
| |
| <h3>Version 1.34 (<a href="i18n.html">i18n</a>) acknowledgements</h3> |
| |
| <p>So many people have contributed comments and bug reports that it isn't any |
| longer possible to acknowledge them individually. That said, Peter Dimov and Rob |
| Stewart need to be specially thanked for their many constructive criticisms and |
| suggestions. Terence |
| Wilson and Chris Frey contributed timing programs which helped illuminate |
| performance issues.</p> |
| |
| <h2><a name="Change-history">Change history</a></h2> |
| |
| <h3>Version 1.37.0</h3> |
| |
| <ul> |
| <li>Doc fixes: Update release history, add tables of macros and deprecated |
| names.</li> |
| <li>Bug fix: convenience.hpp didn't fully apply BOOST_FILESYSTEM_NO_DEPRECATED |
| to name changes.</li> |
| <li>Bug fix: Ticket #1972 'remove' fixes.</li> |
| <li>Bug fix: Restore deprecated basic_directory_entry names inadvertently |
| removed.</li> |
| <li>Bug fix: Provide deprecated functions has_branch_path and has_leaf, |
| inadvertently omitted from 1.36.0</li> |
| <li>Add workarounds for Codegear/Borland C++ Builder 2009.</li> |
| </ul> |
| |
| <h3>Version 1.36.0 - August 14th, 2008</h3> |
| |
| <ul> |
| <li>Added stem(), extension(), and replace_extension() member functions to |
| basic_path, based on the basename(), extension(), and change_extension() |
| functions from convenience.hpp.</li> |
| <li>Changed path.hpp function names:<ul> |
| <li>leaf() -> filename().</li> |
| <li>has_leaf() -> has_filename().</li> |
| <li>branch_path() -> parent_path().</li> |
| <li>has_branch_path() -> has_parent_path().</li> |
| <li>remove_leaf() -> remove_filename().</li> |
| </ul> |
| </li> |
| <li>Changed operations.hpp function names:<ul> |
| <li>is_regular() -> is_regular_file().</li> |
| </ul> |
| </li> |
| <li>Bug fix: Add path.cpp #include <cwchar></li> |
| <li>Cleared path.hpp gcc shadow warnings.</li> |
| </ul> |
| |
| <h3>Version 1.35.0 - March 29th, 2008</h3> |
| |
| <ul> |
| <li>Diagnostics moved to the separate <a href="../../../system/doc/index.html"> |
| Boost.System</a> library.</li> |
| <li>current_path() function added to set the current directory path.</li> |
| <li>Test coverage extended.</li> |
| <li>A few minor implementation fixes.</li> |
| </ul> |
| |
| <h3>Version 1.34.1 - July 24th, 2007</h3> |
| |
| <h3><a href="i18n.html">Version 1.34.0</a> - May 12th, 2007</h3> |
| |
| <ul> |
| <li><a href="i18n.html#Internationalization">Internationalization</a>, provided by |
| class templates <i>basic_path</i>, <i>basic_filesystem_error</i>, and <i> |
| basic_directory_iterator</i>.</li> |
| <li><a href="i18n.html#Simplification">Simplification</a> of the path interface, |
| including elimination of distinction between native and generic formats, |
| and separation of name checking functionality from general path functionality.</li> |
| <li><a href="i18n.html#Rationalization">Rationalization</a> of predicate |
| function design, including the addition of several new functions.</li> |
| <li><a href="i18n.html#Preservation">Preservation</a> of existing user code whenever |
| possible. Deprecated features (<i>symbolic_link_exists()</i>, etc.) remain |
| available for legacy code.</li> |
| <li>Clearer specification, by reference to [<a href="design.htm#POSIX-01">POSIX-01</a>], |
| the ISO/IEEE Single Unix Standard, with provisions for Windows and other |
| operating systems.</li> |
| <li>New functions <a href="reference.html#Status-functions">status</a>, |
| <a href="reference.html#Status-functions">symlink_status</a>, |
| <a href="reference.html#Predicate-functions">is_file</a>, |
| <a href="reference.html#Predicate-functions">is_symlink</a>, |
| <a href="reference.html#Operations-functions">create_hard_link</a>, |
| <a href="reference.html#Operations-functions">create_symlink</a>, path member and non-member swap, path inserter, path |
| extractor, additional path relational and "/" operator overloads, additional |
| path member template functions taking iterator arguments.</li> |
| <li><a href="i18n.html#More_efficient">More efficient operations</a> when iterating over directories.</li> |
| <li>Separation within the implementation of the distinction between the native |
| operating system path syntax and API. This is important for CYGWIN users |
| because it allows them to build for either the Windows or POSIX API's.</li> |
| <li>Numerous small implementation fixes.</li> |
| </ul> |
| |
| <h3>Version 1.33.0 - August 11th, 2005</h3> |
| |
| <ul> |
| <li>Some small implementation fixes.</li> |
| </ul> |
| |
| <h3>Version 1.32.0 - November 19th, 2004</h3> |
| |
| <ul> |
| <li><a href="reference.html#Attribute-functions">file_size()</a> function added.</li> |
| <li>Class path <a href="reference.html#basic_path-non-member-functions">relational operators</a> added.</li> |
| <li><a href="reference.html#Predicate-functions">equivalent()</a> function added.</li> |
| <li><a href="reference.html#Operations-functions">create_directory()</a> no longer |
| throws if the directory already exists. A bool is returned, indicating that |
| the directory did not preexist. Similar changes made to |
| <a href="reference.html#Convenience-functions">create_directories()</a>.</li> |
| <li><a href="#Cgywin">Docs added</a> for users wishing Cygwin/POSIX behavior |
| on Windows.</li> |
| <li>For POSIX, Large File Support (LSF) is enabled if available, such as on |
| Linux.</li> |
| <li><a href="reference.html#initial_path">current_path()</a> and |
| <a href="reference.html#initial_path">initial_path()</a> on POSIX now handle |
| very long paths correctly.</li> |
| </ul> |
| |
| <h3>Version 1.31.0 - January 26th, 2004</h3> |
| |
| <ul> |
| <li>The object library can now be <a href="#Building">built</a> for either |
| static or dynamic (shared/dll) linking. </li> |
| <li>Several added functions, including improved checking for directory and |
| file name portability. See <a href="portability_guide.htm#name_check_functions"> |
| Name check functions</a>.</li> |
| <li>Separation of canonical form and normalized form and a new path member |
| function normalize(). This changes behavior, |
| in that canonical form is now different, but eliminates a subtle |
| <a href="design.htm#symbolic-link-use-case">bug</a> when symbolic links to |
| directories are present.</li> |
| </ul> |
| |
| <h3> <br> |
| Version 1.30.0 - March 19th, 2003</h3> |
| <ul> |
| <li>Initial official Boost version.</li> |
| </ul> |
| |
| <hr> |
| <p>Revised |
| <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->21 June, 2010<!--webbot bot="Timestamp" endspan i-checksum="19840" --></p> |
| |
| <p>© Copyright Beman Dawes, 2002-2005</p> |
| <p> Use, modification, and distribution are subject to the Boost Software |
| License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt"> |
| www.boost.org/LICENSE_1_0.txt</a></p> |
| |
| </body> |
| |
| </html> |