123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456 |
- <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=utf-8">
- <title>Filesystem Home</title>
- <link href="styles.css" rel="stylesheet">
- </head>
- <body>
- <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
- bordercolor="#111111">
- <tr>
- <td width="277">
- <a href="../../../index.htm">
- <img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle"
- width="300" height="86" border="0"></a></td>
- <td align="middle">
- <font size="7">Filesystem Library<br>
- Version 3</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">Home</a>
- <a href="tutorial.html">Tutorial</a>
- <a href="reference.html">Reference</a>
- <a href="faq.htm">FAQ</a>
- <a href="release_history.html">Releases</a>
- <a href="portability_guide.htm">Portability</a>
- <a href="v3.html">V3 Intro</a>
- <a href="v3_design.html">V3 Design</a>
- <a href="deprecated.html">Deprecated</a>
- <a href="issue_reporting.html">Bug Reports</a>
- </td>
- </table>
- <p></p>
- <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="#Documentation">Documentation</a><br>
- <a href="#Using">Using the library</a><br>
- <a href="#Coding-guidelines">Coding guidelines</a><br>
- <a href="#Cautions">Cautions</a><br>
- <a href="#Headers">Headers</a><br>
- <a href="#Examples">Example programs</a><br>
- <a href="#Implementation">Implementation</a><br>
- <a href="#Macros">Macros</a><br>
- <a href="#Building">Building the object-library</a><br>
- <a href="#Cgywin">Notes for Cygwin users</a><br>
- <a href="#Change-history">Version history<br>
- with acknowledgements</a></td>
- </tr>
- </table>
- <p></p>
- <h2><a name="Introduction">Introduction</a></h2>
- <p>The Boost.Filesystem library provides facilities to manipulate files and directories,
- and the paths that identify them.</p>
- <p>The features of the library include:</p>
- <ul>
- <li><b>A modern C++ interface, highly compatible with the C++ standard
- library.</b></li>
- </ul>
- <blockquote>
- <blockquote>
- <p>Many users say the interface is their primary motivation for using
- Boost.Filesystem. They like its use of familiar idioms based on standard library
- containers, iterators, and algorithms. They like having errors reported by
- throwing exceptions.</p>
- </blockquote>
- </blockquote>
- <ul>
- <li><b>Portability between operating systems.</b><br>
- <ul>
- <li>At the C++ syntax level, it is convenient to learn and use one interface
- regardless of the operating system.</li>
- <li>At the semantic level, behavior of code is reasonably portable across
- operating systems.</li>
- <li>Dual generic or native path format support encourages program
- portability, yet still allows communication with users in system specific
- formats.<br>
- </li>
- </ul>
- </li>
- <li><b>Error handling and reporting via C++ exceptions (the default) or error
- codes.</b><br>
- <ul>
- <li>C++ exceptions are the preferred error reporting mechanism for most
- applications. The exception thrown includes the detailed error code
- information important for diagnosing the exact cause of file system errors.</li>
- <li>Error reporting via error code allows user code that provides detailed
- error recovery to avoid becoming so littered with try-catch blocks as to be
- unmaintainable. <br>
- </li>
- </ul>
- </li>
- <li><b>Suitable for a broad spectrum of applications, ranging from simple
- script-like operations to extremely complex production code.</b><br>
- <ul>
- <li>At the simple script-like end of the spectrum, the intent is not to
- compete with Python, Perl, or shell languages, but rather to provide
- filesystem operations when C++ is already the language of choice.</li>
- <li dir="ltr">
- <p dir="ltr">Finer grained control over operations and error handling is available to
- support more complex applications or other cases where throwing exceptions
- isn't desired.<br>
- </li>
- </ul>
- </li>
- <li>
- <p dir="ltr"><b>Forms the basis for
- <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4100.pdf">
- ISO/IEC TS 18822</a>, the C++ standard library Filesystem Technical
- Specification.</b></li>
- </ul>
- <h2><a name="Documentation">Documentation</a></h2>
- <p><b><a href="tutorial.html">Tutorial</a></b> - A gentle introduction to
- the library, with example programs provided for you to experiment with.</p>
- <p><b><a href="reference.html">Reference</a></b> - Formal documentation in the
- style of the C++ standard for
- every component of the library.</p>
- <p><b><a href="faq.htm">FAQ</a></b> - Frequently asked questions.</p>
- <p><b><a href="portability_guide.htm">Portability Guide</a></b> - Help for those
- concerned with writing code to run on multiple operating systems.</p>
- <p><b><a href="deprecated.html">Deprecated Features</a></b> - Identifies
- deprecated features and their replacements.</p>
- <p><b><a href="v3.html">Version 3 Introduction</a></b> - Aimed at users of prior
- Boost.Filesystem versions.</p>
- <p><b><a href="v3_design.html">Version 3 Design</a></b> - Historical document
- from the start of the Version 3 design process.</p>
- <p><b><a href="design.htm">Original Design</a></b> - Historical document from
- the start of the Version 1 design process.</p>
- <p><b><a href="do_list.html">Do List</a></b> - Boost.Filesystem development work
- in the pipeline.</p>
- <h2><a name="Using">Using</a> the library</h2>
- <p>Boost.Filesystem is implemented as a separately compiled library, so you must install
- binaries in a location that can be found by your linker. If you followed the
- <a href="http://www.boost.org/doc/libs/release/more/getting_started/index.html">Boost Getting Started</a> instructions, that's already been done for you.</p>
- <h2><a name="Coding-guidelines">Coding guidelines</a></h2>
- <p>For new code, defining <code>BOOST_FILESYSTEM_NO_DEPRECATED</code> before
- including filesystem headers is strongly recommended. This prevents inadvertent
- use of old features, particularly legacy function names, that have been replaced
- and are going to go away in the future.</p>
- <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>E<b>xceptions</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 to report failures such as I/O errors. Implementations may also use C++ Standard Library functions
- which can throw <i>std::bad_alloc </i>exceptions to report memory allocation
- errors. 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>Nominally non-throwing versions are provided for
- <a href="reference.html#Operational-functions">operational functions</a> that
- access the external file system, since these are often used
- in contexts where error codes may be the preferred way to report an error. Even
- the nominally non-throwing versions of functions will throw <i>std::bad_alloc </i>
- exceptions to report memory allocation errors. However, functions marked <code>
- noexcept</code> never throw exceptions.</p>
- <h2><a name="Headers">Headers</a></h2>
- <p>The Boost.Filesystem library provides several headers:</p>
- <ul>
- <li>Header <<a href="../../../boost/filesystem.hpp">boost/filesystem.hpp</a>>
- provides access to all features of the library, except file streams.<br>
- </li>
- <li>Header <<a href="../../../boost/filesystem/fstream.hpp">boost/filesystem<i>/</i>fstream.hpp</a>>
- inherits the same components as the C++ Standard
- Library's <i>fstream</i> header, but files are identified by <code>const path&</code>
- arguments rather that <code>const char*</code> arguments.</li>
- </ul>
- <h2><a name="Examples">Example programs</a></h2>
- <p>See the <a href="tutorial.html">tutorial</a> for example programs.</p>
- <h2><a name="Implementation">Implementation</a></h2>
- <p>The current implementation supports operating systems which provide
- the POSIX or Windows API's.</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. It is also used by several smart phone operating systems.</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_NO_DEPRECATED</code></td>
- <td valign="top">Not defined.</td>
- <td valign="top">Deprecated features are excluded from headers.</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">The Boost.Filesystem 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.Filesystem library does not use the Boost auto-link
- facility.</td>
- </tr>
- </table>
- <p>User-defined BOOST_POSIX_API and BOOST_WINDOWS_API macros are no longer
- supported.</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 the <a href="../src">src directory</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 and so 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> <a href="http://www.cygwin.com/">Cygwin</a> version 1.7 or later is
- required because only versions of GCC with wide character strings are supported.</p>
- <p> The library's implementation code treats Cygwin as a Windows platform, and
- thus uses the Windows API and uses Windows path syntax as the native path
- syntax.</p>
- <h2><a name="Change-history">Version history</a></h2>
- <h3>Version 4</h3>
- <p><b>Under development </b>- Add support for the
- <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4099.html">ISO
- C++ File System Technical Specification</a>. The Filesystem TS is based on
- Boost.Filesystem Version 3, with only a small number of changes. Most user code
- written for Version 3 should work unchanged with Version 4.</p>
- <h3>Version 3</h3>
- <p>Boost 1.44.0 - June, 2010 - Internationalization via single class <code>path</code>.
- More uniform error handling.</p>
- <p>Peter Dimov suggested use of a single path class rather than a <code>basic_path</code>
- class template. That idea was the basis for the Version 3 redesign.</p>
- <p>Thanks for comments from Robert Stewart, Zach Laine, Peter Dimov, Gregory
- Peele, Scott McMurray, John Bytheway, Jeff Flinn, Jeffery Bosboom.</p>
- <h3>Version 2</h3>
- <p>Boost 1.34.0 - May, 2007 - Internationalization via <code>basic_path</code>
- template.</p>
- <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>
- <h3>Version 1</h3>
- <p>Boost 1.30.0 - March, 2003 - Initial official Boost release.</p>
- <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>
- <hr>
- <p>Revised
- <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->25 October, 2015<!--webbot bot="Timestamp" endspan i-checksum="38877" --></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>
|