mirror of
https://github.com/boostorg/filesystem.git
synced 2026-01-30 07:52:08 +00:00
690 lines
35 KiB
HTML
690 lines
35 KiB
HTML
<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>Boost Filesystem Library</title>
|
||
</head>
|
||
|
||
<body bgcolor="#FFFFFF">
|
||
|
||
<h1>
|
||
<img border="0" src="../../../boost.png" align="center" width="277" height="86">Boost
|
||
Filesystem Library</h1>
|
||
<table border="0" cellpadding="0" width="100%">
|
||
<tr>
|
||
<td width="50%" valign="top"><font size="4">This Document</font><br>
|
||
<a href="#Introduction">Introduction</a><br>
|
||
<a href="#tutorial">Two-minute tutorial</a><br>
|
||
<a href="#Examples">Examples</a><br>
|
||
|
||
<a href="#Definitions">Definitions</a><br>
|
||
<a href="#Common_Specifications">Common Specifications</a><br>
|
||
<a href="#Race-condition">Race-condition danger</a><br>
|
||
<a href="#Implementation">Implementation</a><br>
|
||
<a href="#narrow-only">Restricting library to 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>
|
||
<td width="50%" valign="top"><font size="4">Other Documents</font><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="path.htm"><b><i>path.hpp</i></b> documentation</a><br>
|
||
<a href="exception.htm"><b><i>path.hpp</i></b> Error
|
||
Reporting documentation</a><br>
|
||
<a href="operations.htm"><b><i>operations.hpp</i></b> documentation</a><br>
|
||
<a href="fstream.htm"><b><i>fstream.hpp</i></b> documentation</a><br>
|
||
<a href="convenience.htm"><b><i>convenience.hpp</i></b>
|
||
documentation</a><br>
|
||
<br>
|
||
<a href="do-list.htm">Do-list</a><br>
|
||
<br>
|
||
<a href="http://www.esva.net/~beman/n1923.html">C++ Standards
|
||
Committee proposal for TR2</a></td>
|
||
</tr>
|
||
</table>
|
||
<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="path.htm#Grammar">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 <a href="http://www.esva.net/~beman/n1923.html">proposal</a> has been
|
||
submitted to the C++ Standards Committee for inclusion of the library in the
|
||
Standard Library Technical Report 2 (TR2). The Boost.Filesystem library will
|
||
stay in alignment with the TR2 Filesystem proposal as it works its way through
|
||
the committee process. Note, however, that namespaces and header granularity
|
||
differs between Boost.Filesystem and the TR2 proposal. </p>
|
||
|
||
<p>The Filesystem Library supplies several headers:</p>
|
||
|
||
<ul>
|
||
<li>Header<a href="../../../boost/filesystem.hpp"> boost/filesystem.hpp</a> in
|
||
turn includes the Boost.Filesystem path.hpp, operations.hpp, and
|
||
convenience.hpp headers.<br>
|
||
<ul>
|
||
<li>Header <a href="../../../boost/filesystem/path.hpp">boost/filesystem<i>/</i>path.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>. Supporting classes
|
||
and validity checking
|
||
functions are also provided. See <a href="path.htm">path.hpp documentation</a>.<br>
|
||
</li>
|
||
<li>Header <a href="../../../boost/filesystem/operations.hpp">boost/filesystem<i>/</i>operations.hpp</a> provides functions operating on files and directories,
|
||
and includes class <i>basic_directory_iterator</i> with typdefs <i>
|
||
directory_iterator</i> and <i>wdirectory_iterator</i>. See <a href="operations.htm">
|
||
operations.hpp documentation</a>.<br>
|
||
</li>
|
||
<li>Header <a href="../../../boost/filesystem/convenience.hpp">
|
||
boost/filesystem/convenience.hpp</a>
|
||
provides convenience functions that combine lower-level functions in useful
|
||
ways. See <a href="convenience.htm">convenience.hpp documentation</a>.<br>
|
||
</li>
|
||
</ul>
|
||
</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.
|
||
See <a href="fstream.htm">fstream.hpp documentation</a>.<br>
|
||
</li>
|
||
<li>Header <a href="../../../boost/filesystem/cerrno.hpp">
|
||
boost/filesystem/cerrno.hpp</a> provides POSIX errno macros used by
|
||
Boost.Filesystem, and two new macros (EBADHANDLE, EOTHER) not defined by
|
||
POSIX.</li>
|
||
</ul>
|
||
<p>The organizing principle is that purely lexical operations on<i> </i>
|
||
<a href="#path">paths</a> are supplied as class<i> basic_path</i> member
|
||
functions in <i>path.hpp</i>, while operations performed by the operating system
|
||
on the actual external filesystem directories and files are provided in <i>
|
||
operations.hpp,</i> primarily as free functions.</p>
|
||
<p><i><b>Heads up!</b></i> There are effectively two sets of documentation - the
|
||
traditional Boost documentation and the newer TR2 proposal. Although lots of
|
||
effort has gone into keeping them in sync, be warned that there are inadvertent
|
||
errors, omissions, and divergences.</p>
|
||
<h2>Two-minute <a name="tutorial">tutorial</a></h2>
|
||
<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="path.htm#synopsis">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="path.htm#Grammar">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="operations.htm#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 ( itr->is_directory() )
|
||
{
|
||
if ( find_file( itr->path(), file_name, path_found ) ) return true;
|
||
}
|
||
else if ( itr->leaf() == file_name ) // see below
|
||
{
|
||
path_found = itr->path();
|
||
return true;
|
||
}
|
||
}
|
||
return false;
|
||
}</pre>
|
||
</blockquote>
|
||
<p>The expression <i>itr->leaf() == file_name</i>, in the line commented <i>//
|
||
see below</i>, calls the <i>leaf()</i> function on the <i>path</i> object
|
||
returned by the iterator. <i>leaf()</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>In addition to <i>leaf()</i>, several other function names use the
|
||
tree/root/branch/leaf metaphor.</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 operations functions have <i>nothrow</i>
|
||
versions, to ease use cases where exceptions would not be appropriate.</p>
|
||
<blockquote>
|
||
<p><i>Note: </i>Sometime after the above tutorial code was added, recursive
|
||
directory iterations was provided as a convenience function. So nowadays you
|
||
don't have to actually code the recursion yourself.</p>
|
||
</blockquote>
|
||
<p>The tutorial is now over; hopefully you now are ready to write simple,
|
||
script-like programs using the Filesystem Library!</p>
|
||
<h2><a name="Examples">Examples</a></h2>
|
||
<h3>simple_ls.cpp</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>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/process_jam_log.cpp">
|
||
process_jam_log.cpp</a></li>
|
||
<li><a href="../../../tools/regression/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="Definitions">Definitions</a></h2>
|
||
<p><b><a name="directory">directory</a> </b>- A container provided by the operating system,
|
||
containing the names of files, other directories, or both. Directories are identified
|
||
by <a href="#directory_path">directory path</a>.</p>
|
||
<p><b><a name="directory_tree">directory tree</a></b> - A directory and file
|
||
hierarchy viewed as an acyclic graph. The tree metaphor is reflected in the
|
||
root/branch/leaf naming convention for many <a href="#path">path</a> related
|
||
functions.</p>
|
||
<p><b><a name="path">path</a> </b>- A possibly empty sequence of <a href="#name">names</a>. Each
|
||
element in the sequence, except the last, names a <a href="#directory">directory</a>
|
||
which contains the
|
||
next element. The last element may name either a directory or file. The first
|
||
element is closest to the <a href="#root">root</a> of the directory tree, the last element is
|
||
farthest from the root.</p>
|
||
<p>It is traditional to represent a path as a string, where each element in the
|
||
path is represented by a <a href="#name">name</a>, and some operating system
|
||
defined syntax distinguishes between the name elements. Other representations of
|
||
a path are possible, such as each name being an element in a <code>std::vector<std::string></code>.</p>
|
||
<p><b><a name="file path">file path</a></b> - A <a href="#path">path</a> whose
|
||
last element is a file.</p>
|
||
<p><b><a name="directory_path">directory path</a></b> - A <a href="#path">path</a>
|
||
whose last element is a directory.</p>
|
||
<p><b><a name="complete_path">complete path</a></b> - A <a href="#path">path</a>
|
||
which contains all the elements required by the operating system to uniquely
|
||
identify a file or directory. (There is an odd
|
||
<a href="path.htm#is_complete_note">corner case</a> where a complete path can
|
||
still be ambiguous on a few operating systems.)</p>
|
||
<p><b><a name="relative_path">relative path</a></b> - A <a href="#root">path</a>
|
||
which is not <a href="#complete_path">complete</a>. Before actual use, relative
|
||
paths are turned into <a href="#complete_path">complete paths</a> either
|
||
implicitly by the filesystem adding default elements, or explicitly by the
|
||
program adding the missing elements via function call. Use of relative paths
|
||
often makes a program much more flexible.</p>
|
||
<p><b><a name="name">name</a></b> - A file or directory name, without any
|
||
<a href="#directory_path">directory path</a> information to indicate the file or
|
||
directory's actual location within a directory tree. For some
|
||
operating systems, files and directories may have more than one valid name, such
|
||
as a short-form name and a long-form name.</p>
|
||
<p><b><a name="root">root</a></b> - The initial node in the acyclic graph which
|
||
represents the <a href="#directory_path">directory tree</a> for a filesystem.</p>
|
||
<p><b><a name="multi-root_filesystem">multi-root operating system</a></b> - An
|
||
operating system which has multiple <a href="#root">roots</a>. Some operating systems
|
||
have different <a href="#directory_tree">directory trees</a> for each different
|
||
disk, drive, device, volume, network share, or other entity managed the system, with each having its
|
||
own root-name.</p>
|
||
<p><b><a name="link">link</a></b> - A name in a <a href="#directory">
|
||
directory</a> can be viewed as a pointer to some underlying directory or file
|
||
content. Modern operating systems permit multiple directory elements to point to
|
||
the same underlying directory or file content. Such a pointer is often called a
|
||
link. Not all operating systems support the
|
||
concept of links. Links may be reference-counted (<a href="#hard-link">hard link</a>)
|
||
or non-reference-counted (<a href="#symbolic-link">symbolic link</a>).</p>
|
||
<p><b><a name="hard-link">hard link</a></b> - A reference-counted
|
||
<a href="#link">link</a>. Because the operating system manages the underlying
|
||
file or directory, hard links are transparent to programs. They "just work"
|
||
without the programmer needing to be aware of their existence.</p>
|
||
<p><b><a name="symbolic-link">symbolic link</a></b> - A non-reference-counted
|
||
<a href="#hard-link">link</a>. The operating system manages some aspects of
|
||
symbolic links. Most uses, such as opening or querying files, automatically
|
||
resolve to the file or directory being pointed to rather than to the symbolic
|
||
link itself. A few uses, such as remove() and rename(), modify the symbolic link
|
||
rather than it's target. See an important
|
||
<a href="operations.htm#symbolic-link-warning">symbolic links warning</a>.</p>
|
||
<h2><a name="Common_Specifications">Common Specifications</a></h2>
|
||
<p>Portions of the Boost.Filesystem specifications are defined by reference to
|
||
the <a href="design.htm#POSIX-01">[POSIX-01]</a> standard. How such
|
||
functionality is actually implemented is unspecified. In other words, an "as if"
|
||
rule applies to the actual implementation.</p>
|
||
<p><b>Rationale:</b> Reference to <a href="design.htm#POSIX-01">[POSIX-01]</a>
|
||
allows precise semantics based on a joint ISO and IEEE standard that is widely
|
||
implemented and has been proven and refined during many years of existing
|
||
practice. Operating-system wars neutrality is preserved by allowing implementers
|
||
freedom to use native operating system API's for actual implementations.</p>
|
||
<h3>Requirements on implementations</h3>
|
||
<p>Unless otherwise specified, all Filesystem Library member and non-member
|
||
functions meet the following common requirements.</p>
|
||
<h4>Portable Behavior</h4>
|
||
<p>Implementations are encouraged, but not required, to provide behavior as
|
||
specified for each Boost.Filesystem function. If the specified behavior is not
|
||
provided, an implementation shall document the actual behavior provided.</p>
|
||
<p><b>Rationale:</b> Portable behavior is strongly encouraged, since this is a
|
||
key objective of the library. It is not required because in some environments
|
||
portable behavior is impossible or unreasonably difficult to implement. The
|
||
documentation requirement allows users to be aware of potential portability
|
||
problems.</p>
|
||
<h4>Graceful degradation</h4>
|
||
<p>Filesystem Library functions which cannot
|
||
be fully supported on a particular operating system will be partially supported
|
||
if possible. Implementations must document such partial support. Functions which
|
||
are requested to provide some operation which they cannot support should report
|
||
an error at compile time (preferred) or throw an exception at runtime.</p>
|
||
<p>For environments not supporting file systems with hierarchical directory
|
||
structures Boost.Filesystem headers shall fail to compile.</p>
|
||
<p>If no file systems with hierarchical directory structures are available at
|
||
runtime, all Boost.Filesystem functions shall throw a basic_filesystem_error<path>
|
||
exception.</p>
|
||
<p>If a Boost.Filesystem component depends on file system functionality not
|
||
available in the current environment:</p>
|
||
<ul>
|
||
<li>Safe fallback behavior must be provided if possible.</li>
|
||
<li>Otherwise a basic_filesystem_error exception is thrown.</li>
|
||
</ul>
|
||
<p><b>Rationale:</b> Although the Boost.Filesystem implement runs on POSIX or
|
||
Windows, the above guidance is provided for implementations on operating systems
|
||
which can be supported only partially or not at all. Implementations on
|
||
less-powerful operating systems should provide useful functionality if possible,
|
||
but are not be required to simulate features not present in the underlying
|
||
operating system.</p>
|
||
<h4><b>Postconditions not guaranteed in the presence of race-conditions</b></h4>
|
||
<p>Filesystem function specifications follow the form of C++ Standard Library
|
||
specifications, and so sometimes specify behavior in terms of postconditions. If
|
||
a <a href="#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>
|
||
<h4><b>May throw exceptions</b></h4>
|
||
<p>Filesystem Library functions throw <i>
|
||
<a href="exception.htm">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>
|
||
<h4>Symbolic and hard links</h4>
|
||
<p><a name="link_rules">Links follow operating system rules</a>- <a href="#link">Links</a> are
|
||
transparent in that Filesystem Library functions simply follow operating system
|
||
rules. That implies that some functions may throw <i><a href="exception.htm">
|
||
basic_filesystem_error</a></i>
|
||
exceptions if a link is cyclic or has other problems. Also, see an important
|
||
<a href="operations.htm#symbolic-link-warning">symbolic links warning</a>.</p>
|
||
<p>Typical operating systems rules call for deep operations on all links except
|
||
that destructive operations on non-reference counted links are either shallow,
|
||
or fail altogether in the case of trying to remove a non-reference counted link
|
||
to a directory.</p>
|
||
<p><b>Rationale:</b> Follows existing practice (POSIX, Windows, etc.).</p>
|
||
<h4><b>No atomic-operation or rollback guarantee</b></h4>
|
||
<p>Filesystem Library
|
||
functions which throw exceptions may leave the external file system in an
|
||
altered state. It is suggested that implementations provide stronger guarantees
|
||
when reasonable.</p>
|
||
<p><b>Rationale:</b> Implementers shouldn't be required to provide guarantees which are
|
||
impossible to meet on some operating systems. Implementers are given
|
||
normative encouragement to provide those guarantees when reasonable.</p>
|
||
<h2><a name="Race-condition">Race-condition</a> d<a name="Dangers">anger</a></h2>
|
||
<p>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>
|
||
<p>A program which needs to be robust when operating on potentially-shared file
|
||
or directory resources should be prepared for <i>filesystem_error</i> exceptions
|
||
to be thrown from any filesystem function except those explicitly specified as
|
||
not throwing exceptions.</p>
|
||
<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 following tests are provided:</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>
|
||
<li><a href="../test/convenience_test.cpp">convenience_test.cpp</a></li>
|
||
</ul>
|
||
<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="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 normally be built automatically. See
|
||
<a href="../../../more/getting_started.html">Getting Started</a>. It can also be
|
||
built manually using a <a href="../build/Jamfile">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="../../../more/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 automatically detects the current platform,
|
||
and compiles the POSIX or Windows implementation code accordingly. Automatic
|
||
platform detection during object library compilation can be overridden by
|
||
defining either BOOST_POSIX_API or BOOST_WINDOWS_API macros. With the exception of the Cygwin
|
||
environment, there is usually no reason to define these macros, as the
|
||
software development kits supplied with most compilers only support a single
|
||
platform.</p>
|
||
<p>The <a href="http://www.cygwin.com/">Cygwin</a> package of tools supports
|
||
traditional Windows usage, but also provides an emulation layer and other tools
|
||
which can be used to make Windows act as Linux (and thus POSIX), and provide the
|
||
Linux look-and-feel. GCC is usually the compiler of choice in this environment,
|
||
as it can be installed via the Cygwin install process. Other compilers can also
|
||
use the Cygwin emulation of POSIX, at least in theory.</p>
|
||
<p>Those wishing to use the Cygwin POSIX emulation layer should define the
|
||
BOOST_POSIX_API macro when compiling bother user programs and the
|
||
Boost.Filesystem's object-library.</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 K<>hl, 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><a href="i18n.html">Version 1.34.0</a></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="operations.htm#status">status</a>,
|
||
<a href="operations.htm#symlink_status">symlink_status</a>,
|
||
<a href="operations.htm#is_file">is_file</a>,
|
||
<a href="operations.htm#is_symlink">is_symlink</a>, <a href="operations.htm#create_hard_link">create_hard_link</a>,
|
||
create_symlink, 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</h3>
|
||
|
||
<ul>
|
||
<li>Some small implementation fixes.</li>
|
||
</ul>
|
||
|
||
<h3>Version 1.32.0</h3>
|
||
|
||
<ul>
|
||
<li><a href="operations.htm#file_size">file_size()</a> function added.</li>
|
||
<li>Class path <a href="path.htm#operator_eq">relational operators</a> added.</li>
|
||
<li><a href="operations.htm#equivalent">equivalent()</a> function added.</li>
|
||
<li><a href="operations.htm#create_directory">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="convenience.htm">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="operations.htm#current_path">current_path()</a> and
|
||
<a href="operations.htm#initial_path">initial_path()</a> on POSIX now handle
|
||
very long paths correctly.</li>
|
||
</ul>
|
||
|
||
<h3>Version 1.31.0</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="path.htm#default_name_check">Default name
|
||
check functions</a>, <a href="path.htm#name_check<63>_mechanism">Default name
|
||
check mechanism</a>, and <a href="portability_guide.htm#name_check<63>_functions">
|
||
Name check functions</a>.</li>
|
||
<li>Separation of <a href="path.htm#Canonical">Canonical form</a> and
|
||
<a href="path.htm#Normalized">Normalized form</a> and a new path member
|
||
function <a href="path.htm#normalize">normalize()</a>. 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>
|
||
|
||
<hr>
|
||
<p>Revised
|
||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->16 December, 2005<!--webbot bot="Timestamp" endspan i-checksum="38518" --></p>
|
||
|
||
<p><EFBFBD> Copyright Beman Dawes, 2002-2005</p>
|
||
<p> Use, modification, and distribution are subject to the Boost Software
|
||
License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt">
|
||
LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
|
||
www.boost.org/LICENSE_1_0.txt</a>)</p>
|
||
|
||
</body>
|
||
|
||
</html> |