Switch docs to use TR2 proposal as reference document
[SVN r32677]
This commit is contained in:
Beman Dawes
parent
040c9372b3
commit
0962427fa0
@ -1,209 +0,0 @@
|
||||
<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 convenience.hpp Header</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF">
|
||||
|
||||
<h1>
|
||||
<img border="0" src="../../../boost.png" align="center" width="277" height="86"><a href="../../../boost/filesystem/convenience.hpp">boost/filesystem/convenience.hpp</a></h1>
|
||||
|
||||
<h2>Contents</h2>
|
||||
|
||||
<dl class="index">
|
||||
<dt><a href="#Introduction">Introduction</a><dt><a href="#create_directories">create_directories</a>
|
||||
<dt><a href="#extension">extension</a>
|
||||
<dt><a href="#basename">basename</a>
|
||||
<dt><a href="#change_extension">change_extension</a><br>
|
||||
<a href="#basic_recursive_directory_iterator">basic_recursive_directory_iterator</a></dl>
|
||||
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
|
||||
<p>Header <a href="../../../boost/filesystem/convenience.hpp">convenience.hpp</a>
|
||||
provides convenience functions that combine lower-level functions in useful
|
||||
ways.</p>
|
||||
|
||||
<p>The entire contents of the header is in namespace boost::filesystem.</p>
|
||||
|
||||
<h2 id="create_directoies"><a name="create_directories">create_directories</a></h2>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p><code>template<class Path><br>
|
||||
bool create_directories( const Path & ph );</code></p>
|
||||
|
||||
<p><b>Precondition:</b> <code>ph.empty() || <br>
|
||||
forall p: p == ph || is_parent(p, ph): is_directory(p) || !exists( p )</code>
|
||||
</p>
|
||||
<p><b>Returns:</b> The value of <code>!exists(ph)</code> prior to the
|
||||
establishment of the postcondition.</p>
|
||||
|
||||
<p><b>Postcondition:</b> <code>is_directory(ph)</code></p>
|
||||
|
||||
<p><b>Throws:</b> <code>exists(ph) && !is_directory(ph)</code></p>
|
||||
|
||||
<p>Contributed by Vladimir Prus.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<h2 id="extension"><a name="extension">extension</a></h2>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p><code>template<class Path><br>
|
||||
typename Path::string_type extension( const Path & ph );</code></p>
|
||||
|
||||
<p><b>Returns:</b> if <code>ph.leaf()</code> contains a dot ('.'),
|
||||
returns the substring of <code>ph.leaf()</code> starting from the last dot and
|
||||
ending at the string's end. Otherwise, returns an empty string.
|
||||
<p><b>Rationale:</b> <ul>
|
||||
<li>The dot is included in the return value so that it's
|
||||
possible to tell if extension is empty or absent.
|
||||
<li>It was noted that this definition of extension is probably not sufficient
|
||||
when using <a href="http://tinyurl.com/9tih">Alternate Data Streams</a> —
|
||||
a filesystem feature specific to NTFS. However, semantics in this case were not
|
||||
clear, and the current behavior is still quite useful.
|
||||
</ul>
|
||||
<p><b>Acknowlegements:</b> Carl Daniel and Pavel Vozenilek noticed and
|
||||
discussed the ADS issue.
|
||||
|
||||
<p>Contributed by Vladimir Prus.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<h2 id="basename"><a name="basename">basename</a></h2>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p><code>template<class Path><br>
|
||||
typename Path::string_type basename( const Path & ph );</code></p>
|
||||
|
||||
<p><b>Returns:</b> if <code>ph.leaf()</code> contains a dot ('.'),
|
||||
returns the substring of <code>ph.leaf()</code> starting from beginning and
|
||||
ending at the last dot (the dot is not included). Otherwise, returns
|
||||
<code>ph.leaf()</code>
|
||||
|
||||
</p>
|
||||
|
||||
<p>Contributed by Vladimir Prus.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<h2 id="change_extension"><a name="change_extension">change_extension</a></h2>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p><code>template<class Path><br>
|
||||
Path change_extension( const Path & ph, const typename Path::string_type & new_extension );</code></p>
|
||||
|
||||
<p><b>Postcondition:</b> <code>basename(return_value) == basename(ph)
|
||||
&& extension(return_value) == new_extension</code>
|
||||
<p><b>Note:</b> It follows from the semantic of <code>extension</code> that
|
||||
<code>new_extension</code> should include dot to achieve reasonable results.
|
||||
</p>
|
||||
<p><b>Rationale:</b> Previously, this functions had
|
||||
<code>!ph.leaf().empty()</code> as precondition. It's not clear if it was
|
||||
right or wrong. Changing extension of an empty path looks pointless. On the
|
||||
other hand, the value of precondition was questionable: one would better place such
|
||||
checks at the points where paths are entered by the user. Current decision
|
||||
is to drop the precondition.</p>
|
||||
|
||||
<p>Contributed by Vladimir Prus.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
|
||||
|
||||
<h2><a name="basic_recursive_directory_iterator">basic_recursive_directory_iterator</a></h2>
|
||||
|
||||
<pre>template< class Path >
|
||||
class basic_recursive_directory_iterator
|
||||
: public boost::iterator_facade<
|
||||
basic_recursive_directory_iterator<Path>, Path,
|
||||
boost::single_pass_traversal_tag >
|
||||
{
|
||||
public:
|
||||
typedef Path path_type;
|
||||
|
||||
basic_recursive_directory_iterator(){} // creates the "end" iterator
|
||||
|
||||
explicit basic_recursive_directory_iterator( const Path & dir_path );
|
||||
|
||||
int level() const;
|
||||
|
||||
void pop();
|
||||
void no_push();
|
||||
|
||||
status_flags status( system_error_type * ec=0 ) const;
|
||||
status_flags status( const symlink_t &, system_error_type * ec=0 ) const;
|
||||
|
||||
bool exists() const;
|
||||
bool is_directory() const;
|
||||
bool is_file() const;
|
||||
bool is_other() const;
|
||||
bool is_symlink() const;
|
||||
|
||||
private:
|
||||
int m_level; // for exposition only
|
||||
};
|
||||
|
||||
typedef basic_recursive_directory_iterator<path> recursive_directory_iterator;
|
||||
typedef basic_recursive_directory_iterator<wpath> wrecursive_directory_iterator;</pre>
|
||||
|
||||
<p>The behavior of <i>basic_recursive_directory_iterator</i> member functions is
|
||||
the same as <a href="operations.htm#directory_iterator">basic_directory_iterator</a>
|
||||
functions of the same name, except:</p>
|
||||
<ul>
|
||||
<li>When an iterator is constructed, <code>m_level</code> is set to 0;</li>
|
||||
<li>When an iterator <code>it</code> for which <code>it.is_directory()</code>
|
||||
is true is incremented, <code>++m_level</code>, the directory is visited, and
|
||||
its contents recursively iterated over, unless <code>no_push()</code> was
|
||||
called prior to incrementing.</li>
|
||||
<li>When an iterator reaches the end of the directory currently being iterated
|
||||
over, or when <code>pop()</code> is called, <code>--m_level</code>, and
|
||||
iteration continues with the parent directory, until the <code>dir_path</code>
|
||||
directory is reached.</li>
|
||||
<li><code>level()</code> returns <code>m_level</code>.</li>
|
||||
<li><code>level()</code>, <code>pop()</code>, and <code>no_push()</code> all
|
||||
have the precondition that the iterator not be the end iterator.</li>
|
||||
</ul>
|
||||
<p>The issue of duplicates (caused by symlinks and hard links) should be
|
||||
consider when using <i>basic_recursive_directory_iterator</i>.
|
||||
Both duplicate detecting and non-detecting are needed, depending on the
|
||||
application. Non-detecting is far
|
||||
more efficient, but some apps will require duplicate detection.</p>
|
||||
<p>When duplicate prevention is required, consider simply not following symlinks.
|
||||
Use the <code>no_push()</code> function to avoid recursion into directories
|
||||
reached by symlinks. If a more comprehensive solution is required, consider
|
||||
these factors:</p>
|
||||
<ul>
|
||||
<li>Names are useless for duplicate detection because of links and other file
|
||||
system alias mechanisms such as drive mapping, mounts.</li>
|
||||
<li>inodes are unstable if handles are not held open, and it isn't
|
||||
feasible to hold unlimited number of handles open.</li>
|
||||
<li>Size, dates, etc., are subject to race conditions.</li>
|
||||
<li>No one method is likely to serve all needs, but a starting point might
|
||||
be to keep a hash-table keyed on a size/date based signature, then do
|
||||
equivalent() on all equal keys.</li>
|
||||
</ul>
|
||||
|
||||
<p>Contributed by Beman Dawes</p>
|
||||
<hr>
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->12 July, 2005<!--webbot bot="Timestamp" endspan i-checksum="21129" --></p>
|
||||
<p>© Copyright Beman Dawes, 2005<br>
|
||||
© Copyright Vladimir Prus, 2003</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>
|
||||
@ -35,7 +35,7 @@ Do-list</h1>
|
||||
</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>
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->06 February, 2006<!--webbot bot="Timestamp" endspan i-checksum="40411" --></p>
|
||||
<p>© Copyright Beman Dawes, 2002</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">
|
||||
|
||||
@ -1,163 +0,0 @@
|
||||
<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 exception.hpp Header</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF">
|
||||
|
||||
<h1>
|
||||
<img border="0" src="../../../boost.png" align="center" width="277" height="86">Error
|
||||
Reporting</h1>
|
||||
|
||||
<p><a href="#Introduction">Introduction</a><br>
|
||||
<a href="#Synopsis">Synopsis</a><br>
|
||||
<a href="#Members">Member functions</a><br>
|
||||
<a href="#Non-members">Non-member functions</a><br>
|
||||
<a href="#lookup_error_code">lookup_error_code</a><br>
|
||||
<a href="#system_message">system_message</a><br>
|
||||
<a href="#Acknowledgements">Acknowledgements</a></p>
|
||||
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
|
||||
<p>The <a href="../../../boost/filesystem/path.hpp">boost/filesystem/path.hpp</a> header provides
|
||||
various error reporting facilities, including class template <i>basic_filesystem_error</i>, publicly derived from <i>
|
||||
std::exception</i>. These facilities are used by functions in the Filesystem Library to
|
||||
report operational errors.</p>
|
||||
|
||||
<p>The design evolved based on user requests to ease portability and
|
||||
internationalization. See the Boost <a href="../../../more/error_handling.html">
|
||||
Error and Exception Handling</a> guidelines.</p>
|
||||
|
||||
<h2><a name="Synopsis">Synopsis</a></h2>
|
||||
<pre>namespace boost
|
||||
{
|
||||
namespace filesystem
|
||||
{
|
||||
typedef int <a name="errno_type">errno_type</a>; // determined by C standard; POSIX defers to C standard
|
||||
typedef <i>implementation-defined</i> <a name="system_error_type">system_error_type</a>;
|
||||
|
||||
errno_type <a href="#lookup_error_code">lookup_error_code</a>( system_error_type sys_err_code );
|
||||
|
||||
void <a href="#system_message">system_message</a>( system_error_type sys_err_code, std::string & target );
|
||||
|
||||
template<class Path>
|
||||
class basic_filesystem_error : public std::exception
|
||||
{
|
||||
public:
|
||||
// compiler generates copy constructor and copy assignment
|
||||
|
||||
typedef Path path_type;
|
||||
|
||||
<a href="#Constructors">basic_filesystem_error</a>( const std::string & what, system_error_type se );
|
||||
<a href="#Constructors">basic_filesystem_error</a>( const std::string & what, const path & path1, system_error_type se );
|
||||
<a href="#Constructors">basic_filesystem_error</a>( const std::string & what, const path & path1,
|
||||
const path & path2, system_error_type se );
|
||||
|
||||
~basic_filesystem_error() throw();
|
||||
|
||||
virtual const char * <a href="#what">what</a>() const throw();
|
||||
|
||||
system_error_type <a href="#system_error">system_error</a>() const;
|
||||
const path & <a href="#path1">path1</a>() const;
|
||||
const path & <a href="#path2">path2</a>() const;
|
||||
};
|
||||
|
||||
typedef basic_filesystem_error<path> filesystem_error;
|
||||
typedef basic_filesystem_error<wpath> wfilesystem_error;
|
||||
|
||||
} // namespace filesystem
|
||||
} // namespace boost
|
||||
</pre>
|
||||
|
||||
<p>For POSIX and Windows, <code>system_error_type</code> is <code>int</code>.</p>
|
||||
|
||||
<h2><a name="Members">Member functions</a></h2>
|
||||
|
||||
<h3><a name="Constructors">Constructors</a></h3>
|
||||
<pre> <a href="#Constructors">basic_filesystem_error</a>( const std::string & what, system_error_type se );
|
||||
<a href="#Constructors">basic_filesystem_error</a>( const std::string & what, const path & path1, system_error_type se );
|
||||
<a href="#Constructors">basic_filesystem_error</a>( const std::string & what, const path & path1,
|
||||
const path & path2, system_error_type se );</pre>
|
||||
<blockquote>
|
||||
<p><b>Effects:</b> Constructs a <i>basic_filesystem_error</i> object, initialized
|
||||
from the appropriate arguments.</p>
|
||||
</blockquote>
|
||||
<h3><a name="what">what</a></h3>
|
||||
<blockquote>
|
||||
<p><code>virtual const char * what() const throw();</code></p>
|
||||
<p><b>Returns:</b> A string identifying the error, including path1(),
|
||||
path2(), and related messages. If an error occurs in the preparation of the
|
||||
string, particularly in low-memory situations, an implementation is permitted to
|
||||
return a simpler static string.</p>
|
||||
</blockquote>
|
||||
<h3><a name="system_error">system_error</a></h3>
|
||||
<blockquote>
|
||||
<p><code><a href="#system_error_type">system_error_type</a> system_error() const;</code></p>
|
||||
<p><b>Returns:</b> The <code>se</code> argument to the constructor.</p>
|
||||
</blockquote>
|
||||
|
||||
<h3><a name="path1">path1</a></h3>
|
||||
<blockquote>
|
||||
<pre>const path & path1() const;</pre>
|
||||
|
||||
<p><b>Returns:</b> The <code>path1</code> argument to the constructor, if any,
|
||||
otherwise <code>path()</code>. An implementation is permitted to return an empty
|
||||
path if an exception, for example, std::bad_alloc, occurs during
|
||||
processing.</p>
|
||||
</blockquote>
|
||||
|
||||
<h3><a name="path2">path2</a></h3>
|
||||
<blockquote>
|
||||
<pre>const path & path2() const;</pre>
|
||||
|
||||
<p><b>Returns:</b> The <code>path2</code> argument to the constructor, if any,
|
||||
otherwise <code>path()</code>. An implementation is permitted to return an empty
|
||||
path if an exception, for example, std::bad_alloc, occurs during
|
||||
processing.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2><a name="Non-members">Non-member functions</a></h2>
|
||||
|
||||
<h3><a name="lookup_error_code">lookup_error_code</a></h3>
|
||||
|
||||
<blockquote>
|
||||
<pre><a href="#errno_type">errno_type</a> lookup_error_code( <a href="#system_error_type">system_error_type</a> sys_err_code );</pre>
|
||||
<p><b>Returns:</b> A value
|
||||
corresponding to <code>sys_err_code.</code> Macros for errno_type values are
|
||||
defined in <a href="../../../boost/filesystem/cerrno.hpp"><boost/filesystem/cerrno.hpp></a>,
|
||||
and are described in [<a href="design.htm#POSIX-01">POSIX-01</a>] under
|
||||
<a href="http://www.opengroup.org/onlinepubs/009695399/basedefs/errno.h.html">
|
||||
<errno.h></a>..</p>
|
||||
</blockquote>
|
||||
|
||||
<h3><a name="system_message">system_message</a></h3>
|
||||
|
||||
<blockquote>
|
||||
<pre>void system_message( system_error_type sys_err_code, std::string & target );</pre>
|
||||
<p><b>Effects:</b> Appends an operating system message corresponding to
|
||||
sys_err_code to <code>target</code>.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
|
||||
|
||||
<p>Peter Dimov patiently identified requirements for portability and
|
||||
internationalization of error messages. He also suggested basing the portable
|
||||
error codes on POSIX.</p>
|
||||
<hr>
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->21 June, 2005<!--webbot bot="Timestamp" endspan i-checksum="19912" --></p>
|
||||
|
||||
<p>© Copyright Beman Dawes, 2002</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>
|
||||
59
doc/faq.htm
59
doc/faq.htm
@ -5,7 +5,7 @@
|
||||
<img border="0" src="../../../boost.png" align="center" width="277" height="86">Filesystem
|
||||
FAQ</h1>
|
||||
<p><b>Why base the generic-path string format on POSIX?</b></p>
|
||||
<p><a href="design.htm#POSIX-01">[POSIX-01]</a> is the basis for the most familiar path-string formats, including the
|
||||
<p><a href="design.htm#POSIX-01">[POSIX-01]</a> is an ISO Standard. It is the basis for the most familiar path-string formats, including the
|
||||
URL portion of URI's and the native Windows format. It is ubiquitous and
|
||||
familiar. On many systems, it is very easy to implement because it is
|
||||
either the native operating system format (Unix and Windows) or via a
|
||||
@ -29,7 +29,7 @@ absolute on some systems?) by programmers used to single-rooted filesystems.
|
||||
Using an unfamiliar name for the concept and related functions causes
|
||||
programmers to read the specs rather than just assuming the meaning is known.</p>
|
||||
<p><b>Why not support a concept of specific kinds of file systems, such as posix_file_system or windows_file_system.</b></p>
|
||||
<p>Portability is one of the one or two most important requirements for the
|
||||
<p>Portability is one of the most important requirements for the
|
||||
library. Gaining some advantage by using features specific to particular
|
||||
operating systems is not a requirement. There doesn't appear to be much need for
|
||||
the ability to manipulate, say, a classic Mac OS path while running on an
|
||||
@ -48,50 +48,6 @@ trafficking in paths isn't always natural. </p>
|
||||
style may be strongest for directory iterator value type. (See Jesse Jones' Jan 28,
|
||||
2002, Boost postings). However, as class path has evolved, it seems sufficient
|
||||
even as the directory iterator value type.</p>
|
||||
<p><b>Why aren't directories considered to be files?</b></p>
|
||||
<p>Because
|
||||
directories cannot portably and usefully be opened as files using the C++ Standard Library stdio or fstream
|
||||
I/O facilities. An important additional rationale is that separating the concept
|
||||
of directories and files makes exposition and specification clearer. A
|
||||
particular problem is the naming and description of function arguments.</p>
|
||||
<div align="center">
|
||||
<center>
|
||||
<table border="1" cellpadding="5" cellspacing="0">
|
||||
<tr>
|
||||
<td colspan="3">
|
||||
<p align="center"><b>Meaningful Names for Arguments</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Argument Intent</b></td>
|
||||
<td><b>Meaningful name if<br>
|
||||
directories are files</b></td>
|
||||
<td><b>Meaningful name if<br>
|
||||
directories aren't files</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>A path to either a directory or a non-directory</td>
|
||||
<td align="center"><i>path</i></td>
|
||||
<td align="center"><i>path</i></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>A path to a directory, but not to a non-directory</td>
|
||||
<td align="center"><i>directory_path</i></td>
|
||||
<td align="center"><i>directory_path</i></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>A path to a non-directory, but not a directory</td>
|
||||
<td align="center"><i>non_directory_path</i></td>
|
||||
<td align="center"><i>file_path</i></td>
|
||||
</tr>
|
||||
</table>
|
||||
</center>
|
||||
</div>
|
||||
<p>The problem is that when directories are considered files, <i>
|
||||
non_directory_path</i> as an argument name, and the corresponding "non-directory
|
||||
path" in documentation, is ugly and lengthy, and so is shortened to just <i>path</i>,
|
||||
causing the code and documentation to be confusing if not downright wrong. The
|
||||
names which result from the "directories aren't files" approach are more
|
||||
acceptable and less likely to be used incorrectly. </p>
|
||||
<p><b>Why are the operations.hpp non-member functions so low-level?</b></p>
|
||||
<p>To provide a toolkit from which higher-level functionality can be created.</p>
|
||||
<p>An
|
||||
@ -127,7 +83,8 @@ notification variable?</b></p>
|
||||
<p>Safety. Return codes or error notification variables are often ignored
|
||||
by programmers. Exceptions are much harder to ignore, provided desired
|
||||
default behavior (program termination) if not caught, yet allow error recovery
|
||||
if desired.</p>
|
||||
if desired. Non-throwing versions of functions are provided where experience
|
||||
indicates the need.</p>
|
||||
<p><b>Why are attributes accessed via named functions rather than property maps?</b></p>
|
||||
<p>For commonly used attributes (existence, directory or file, emptiness),
|
||||
simple syntax and guaranteed presence outweigh other considerations. Because
|
||||
@ -144,13 +101,13 @@ about to hand them a loaded gun pointed right at their big toe.</p>
|
||||
a templated type?</b></p>
|
||||
<p>They <u>are</u> supported, starting with version 1.33. See
|
||||
<a href="i18n.html">Internationalization</a>.</p>
|
||||
<p><b>Why isn't more powerful name portability error detection provided, such as
|
||||
deferring checking until a path is actually used?</b></p>
|
||||
<p><b>Why isn't automatic name portability error detection provided?</b></p>
|
||||
<p>A number (at least six) of designs for name validity error
|
||||
detection were evaluated, including at least four complete implementations.
|
||||
While the details for rejection differed, all of the more powerful name validity checking
|
||||
designs distorted other
|
||||
otherwise simple aspects of the library. While name checking can be helpful, it
|
||||
otherwise simple aspects of the library. Even the simple name checking provided
|
||||
in prior library versions was a constant source of user complaints. While name checking can be helpful, it
|
||||
isn't important enough to justify added a lot of additional complexity.</p>
|
||||
<p><b>Why are paths sometimes manipulated by member functions and sometimes by
|
||||
non-member functions?</b></p>
|
||||
@ -166,7 +123,7 @@ canonical form. See <a href="design.htm#symbolic-link-use-case">use case</a>
|
||||
from Walter Landry.</p>
|
||||
<hr>
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->02 August, 2005<!--webbot bot="Timestamp" endspan i-checksum="34600" --></p>
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->06 February, 2006<!--webbot bot="Timestamp" endspan i-checksum="40411" --></p>
|
||||
<p>© Copyright Beman Dawes, 2002</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">
|
||||
|
||||
134
doc/fstream.htm
134
doc/fstream.htm
@ -1,134 +0,0 @@
|
||||
<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 fstream Header</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF">
|
||||
|
||||
<h1>
|
||||
<img border="0" src="../../../boost.png" align="center" width="277" height="86"><a href="../../../boost/filesystem/fstream.hpp">boost/filesystem/fstream.hpp</a></h1>
|
||||
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
|
||||
<p>The C++ Standard Library's <i><fstream></i> header uses <i>const char*</i> to
|
||||
pass arguments representing file names, with that usage occurring seven
|
||||
times.</p>
|
||||
|
||||
<p>The Filesystem Library's <i>fstream.hpp</i> header provides equivalent
|
||||
components, in namespace <i>
|
||||
boost::filesystem</i>, except that the seven functions taking <i>
|
||||
const char*</i> arguments have been replaced by functions with
|
||||
<a href="path.htm#basic_path">basic_path</a> arguments. A
|
||||
<a href="operations.htm#Do-the-right-thing">"do-the-right-thing" rule</a>
|
||||
applies, so that <i>path</i>, <i>wpath</i>, and user-defined <i>basic_path</i>'s
|
||||
work appropriately. For ease of exposition, only the templated form is shown in
|
||||
the following synopsis and documentation.</p>
|
||||
|
||||
<p>The Filesystem Library's <i>fstream.hpp</i> header simply uses the <i><fstream></i>
|
||||
standard library components as base classes, and then redeclares constructors
|
||||
and open functions to take arguments of type <i>const path&</i> instead of <i>
|
||||
const char*</i>.</p>
|
||||
|
||||
<p>For documentation beyond the synopsis, see the
|
||||
<a href="index.htm#tutorial">tutorial</a> and <a href="index.htm#Examples">
|
||||
examples</a>.</p>
|
||||
|
||||
<h2><a name="Synopsis">Synopsis</a></h2>
|
||||
<pre>namespace boost
|
||||
{
|
||||
namespace filesystem
|
||||
{
|
||||
template < class charT, class traits = std::char_traits<charT> >
|
||||
class basic_filebuf : public std::basic_filebuf<charT,traits>
|
||||
{
|
||||
public:
|
||||
virtual ~basic_filebuf() {}
|
||||
|
||||
template<class Path>
|
||||
std::basic_filebuf<charT,traits> * open( const Path & file_ph,
|
||||
std::ios_base::openmode mode );
|
||||
};
|
||||
|
||||
typedef basic_filebuf<char> filebuf;
|
||||
typedef basic_filebuf<wchar_t> wfilebuf;
|
||||
|
||||
template < class charT, class traits = std::char_traits<charT> >
|
||||
class basic_ifstream : public std::basic_ifstream<charT,traits>
|
||||
{
|
||||
public:
|
||||
basic_ifstream() {}
|
||||
|
||||
template<class Path>
|
||||
explicit basic_ifstream( const Path & file_ph,
|
||||
std::ios_base::openmode mode = std::ios_base::in );
|
||||
|
||||
virtual ~basic_ifstream() {}
|
||||
|
||||
template<class Path>
|
||||
void open( const Path & file_ph,
|
||||
std::ios_base::openmode mode = std::ios_base::in );
|
||||
};
|
||||
|
||||
typedef basic_ifstream<char> ifstream;
|
||||
typedef basic_ifstream<wchar_t> wifstream;
|
||||
|
||||
template < class charT, class traits = std::char_traits<charT> >
|
||||
class basic_ofstream : public std::basic_ofstream<charT,traits>
|
||||
{
|
||||
public:
|
||||
basic_ofstream() {}
|
||||
|
||||
template<class Path>
|
||||
explicit basic_ofstream( const Path & file_ph,
|
||||
std::ios_base::openmode mode = std::ios_base::out );
|
||||
|
||||
virtual ~basic_ofstream() {}
|
||||
|
||||
template<class Path>
|
||||
void open( const Path & file_ph,
|
||||
std::ios_base::openmode mode = std::ios_base::out );
|
||||
};
|
||||
|
||||
typedef basic_ofstream<char> ofstream;
|
||||
typedef basic_ofstream<wchar_t> wofstream;
|
||||
|
||||
template < class charT, class traits = std::char_traits<charT> >
|
||||
class basic_fstream : public std::basic_fstream<charT,traits>
|
||||
{
|
||||
public:
|
||||
basic_fstream() {}
|
||||
|
||||
template<class Path>
|
||||
explicit basic_fstream( const Path & file_ph,
|
||||
std::ios_base::openmode mode = std::ios_base::in|std::ios_base::out );
|
||||
|
||||
virtual ~basic_fstream() {}
|
||||
|
||||
template<class Path>
|
||||
void open( const Path & file_ph,
|
||||
std::ios_base::openmode mode = std::ios_base::in|std::ios_base::out );
|
||||
};
|
||||
|
||||
typedef basic_fstream<char> fstream;
|
||||
typedef basic_fstream<wchar_t> wfstream;
|
||||
} // namespace filesystem
|
||||
} // namespace boost
|
||||
</pre>
|
||||
<hr>
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->27 June, 2005<!--webbot bot="Timestamp" endspan i-checksum="19924" --></p>
|
||||
|
||||
<p>© Copyright Beman Dawes, 2002</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>
|
||||
353
doc/index.htm
353
doc/index.htm
@ -18,11 +18,10 @@ Filesystem Library</h1>
|
||||
<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="#Cautions">Cautions</a><br>
|
||||
<a href="#Using_reference_doc">Using the Reference
|
||||
Documentation</a><br>
|
||||
<a href="#Examples">Examples</a><br>
|
||||
<a href="#Implementation">Implementation</a><br>
|
||||
<a href="#narrow-only">Restricting library to narrow
|
||||
character paths</a><br>
|
||||
@ -31,21 +30,25 @@ Filesystem Library</h1>
|
||||
<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="tr2_proposal.html">Reference</a><br>
|
||||
<a href="tr2_proposal.html#TOC">Table of Contents</a><br>
|
||||
|
||||
<a href="tr2_proposal.html#Introduction">TR2 Introduction</a><br>
|
||||
<a href="tr2_proposal.html#Text">Formal reference text</a><br>
|
||||
|
||||
<a href="tr2_proposal.html#frontmatter">Introductory
|
||||
chapter</a><br>
|
||||
|
||||
<a href="tr2_proposal.html#Filesystem-library">Filesystem
|
||||
library chapter</a><br>
|
||||
|
||||
<a href="tr2_proposal.html#Header-filesystem-synopsis">Header
|
||||
<boost/filesystem.hpp> synopsis</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="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>
|
||||
<a href="do-list.htm">Do-list</a><br>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
@ -59,47 +62,35 @@ 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
|
||||
behavior of code is portable. The <a href="tr2_proposal.html#Pathname-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
|
||||
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
|
||||
<p>A <a href="tr2_proposal.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>
|
||||
differs between Boost.Filesystem and the TR2 proposal. See
|
||||
<a href="#Using_reference_doc">Using the Reference Documentation</a>.</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>
|
||||
<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>. Supporting classes
|
||||
and validity checking
|
||||
functions are also provided. See <a href="path.htm">path.hpp documentation</a>.<br>
|
||||
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/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.
|
||||
@ -110,15 +101,6 @@ differs between Boost.Filesystem and the TR2 proposal. </p>
|
||||
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>
|
||||
@ -185,11 +167,11 @@ below is extracted from a real program, slightly modified for clarity:</p>
|
||||
itr != end_itr;
|
||||
++itr )
|
||||
{
|
||||
if ( itr->is_directory() )
|
||||
if ( is_directory(itr->status()) )
|
||||
{
|
||||
if ( find_file( itr->path(), file_name, path_found ) ) return true;
|
||||
}
|
||||
else if ( itr->leaf() == file_name ) // see below
|
||||
else if ( itr->path().leaf() == file_name ) // see below
|
||||
{
|
||||
path_found = itr->path();
|
||||
return true;
|
||||
@ -198,9 +180,10 @@ below is extracted from a real program, slightly modified for clarity:</p>
|
||||
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
|
||||
<p>The expression <i>itr->path().leaf() == file_name</i>, in the line commented <i>//
|
||||
see below</i>, calls the <i>leaf()</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>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
|
||||
@ -210,15 +193,79 @@ 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>
|
||||
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>Sometime after the above tutorial code was added, recursive
|
||||
directory iterations was provided as a convenience function. So nowadays you
|
||||
<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>
|
||||
<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="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="tr2_proposal.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="tr2_proposal.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="Using_reference_doc">Using the Reference Documentation</a></h2>
|
||||
<p>The proposal for adding Boost.Filesystem to the C++ Standard Library's
|
||||
Technical Report 2 is used as the <a href="tr2_proposal.html">Reference
|
||||
Documentation</a>. This eliminates the need to maintain two sets of
|
||||
documentation, but means that the actual Boost.Filesystem library differs from
|
||||
this reference documentation in several ways.</p>
|
||||
<ul>
|
||||
<li>The Boost.Filesystem header is <a href="../../../boost/filesystem.hpp">
|
||||
<code><boost/filesystem.hpp></code></a> rather than <code><filesystem></code>.</li>
|
||||
<li>The namespace is <code>boost::filesystem</code> rather than <code>
|
||||
std::tr2::sys</code>.</li>
|
||||
<li>Several legacy interfaces are provided by Boost.Filesystem that are not
|
||||
part of the TR2 proposal.</li>
|
||||
</ul>
|
||||
<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
|
||||
@ -251,193 +298,9 @@ illustrate what the developer expected to work and not work. See:</p>
|
||||
<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>
|
||||
@ -677,7 +540,7 @@ performance issues.</p>
|
||||
|
||||
<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>
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->06 February, 2006<!--webbot bot="Timestamp" endspan i-checksum="40411" --></p>
|
||||
|
||||
<p>© Copyright Beman Dawes, 2002-2005</p>
|
||||
<p> Use, modification, and distribution are subject to the Boost Software
|
||||
|
||||
@ -1,861 +0,0 @@
|
||||
<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 operations.hpp Header</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#FFFFFF">
|
||||
|
||||
<h1>
|
||||
<img border="0" src="../../../boost.png" align="center" width="277" height="86"><a href="../../../boost/filesystem/operations.hpp">boost/filesystem/operations.hpp</a></h1>
|
||||
|
||||
<p><a href="#Introduction">Introduction</a><br>
|
||||
<a href="#Synopsis">Header synopsis</a><br>
|
||||
<a href="#basic_directory_entry">Class basic_directory_entry</a><br>
|
||||
<a href="#directory_iterator">Class basic_directory_iterator</a><br>
|
||||
<a href="#constructors">Constructors</a><br>
|
||||
<a href="#Non-member_functions">Operations non-member functions</a><br>
|
||||
<a href="#Do-the-right-thing">"Do-the-right-thing" rule</a><br>
|
||||
<a href="#status">status</a><br>
|
||||
<a href="#exists">exists</a><br>
|
||||
<a href="#is_error">is_error</a><br>
|
||||
<a href="#is_directory">is_directory</a><br>
|
||||
<a href="#is_regular">is_regular</a><br>
|
||||
<a href="#is_symlink">is_symlink</a><br>
|
||||
<a href="#is_empty">is_empty</a><br>
|
||||
<a href="#equivalent">equivalent</a><br>
|
||||
<a href="#file_size">file_size</a><br>
|
||||
<a href="#last_write_time">last_write_time</a><br>
|
||||
<a href="#create_directory">create_directory</a><br>
|
||||
<a href="#create_hard_link">create_hard_link</a><br>
|
||||
<a href="#remove">remove</a><br>
|
||||
<a href="#remove_all">remove_all</a><br>
|
||||
<a href="#rename">rename</a><br>
|
||||
<a href="#copy_file">copy_file</a><br>
|
||||
<a href="#initial_path">initial_path</a><br>
|
||||
<a href="#current_path">current_path</a><br>
|
||||
<a href="#complete">complete</a><br>
|
||||
<a href="#system_complete">system_complete</a></p>
|
||||
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
|
||||
<p>The <a href="../../../boost/filesystem/operations.hpp">
|
||||
boost/filesystem/operations.hpp</a> header provides operations on files and
|
||||
directories.</p>
|
||||
|
||||
<p>These operations traffic in paths; see <a href="path.htm">
|
||||
boost/filesystem/path.hpp documentation</a>.</p>
|
||||
|
||||
<p>For file I/O streams, see <a href="fstream.htm">boost/filesystem/fstream.hpp
|
||||
documentation</a>.</p>
|
||||
|
||||
<p>The Filesystem Library's <a href="index.htm#Common_Specifications">Common
|
||||
Specifications</a> apply to all member and non-member functions supplied by this
|
||||
header. </p>
|
||||
|
||||
<h2>Header <a href="../../../boost/filesystem/operations.hpp">boost/filesystem/operations.hpp</a> </h2>
|
||||
|
||||
<h2><a name="Synopsis">Synopsis</a></h2>
|
||||
<pre>namespace boost
|
||||
{
|
||||
namespace filesystem
|
||||
{
|
||||
typedef <i>bitmask-type</i> <a name="status_flag">status_flag</a>s; // see C++ std 17.3.2.1.2 [lib.bitmask.types]
|
||||
|
||||
static const status_flags error_flag;
|
||||
static const status_flags not_found_flag;
|
||||
static const status_flags directory_flag;
|
||||
static const status_flags regular_flag;
|
||||
static const status_flags other_flag;
|
||||
static const status_flags symlink_flag;
|
||||
|
||||
struct <a name="symlink_t">symlink_t</a>{};
|
||||
extern symlink_t symlink;
|
||||
|
||||
// basic_directory_entry
|
||||
|
||||
template<class Path> class basic_directory_entry
|
||||
{
|
||||
public:
|
||||
typedef Path path_type;
|
||||
typedef typename Path::string_type string_type;
|
||||
|
||||
// compiler generated copy-ctor, copy assignment, and destructor apply
|
||||
|
||||
basic_directory_entry() : m_status(0), m_symlink_status(0) {}
|
||||
explicit basic_directory_entry( const path_type & p, status_flags sf=0, status_flags symlink_sf=0 );
|
||||
|
||||
void assign( const path_type & p, status_flags sf=0, status_flags symlink_sf=0 );
|
||||
|
||||
void replace_leaf( const string_type & s, status_flags sf=0, status_flags symlink_sf=0 );
|
||||
|
||||
// conversion simplifies most common use of basic_directory_entry
|
||||
operator const path_type &() const { return m_path; }
|
||||
|
||||
# ifndef BOOST_FILESYSTEM_NO_DEPRECATED
|
||||
// deprecated function preserves common use case in legacy code
|
||||
typename Path::string_type leaf() const;
|
||||
# endif
|
||||
|
||||
const Path & path() const;
|
||||
|
||||
status_flags status( system_error_type * ec=0 ) const;
|
||||
status_flags status( const symlink_t &, system_error_type * ec=0 ) const;
|
||||
|
||||
bool exists() const;
|
||||
bool is_directory() const;
|
||||
bool is_regular() const;
|
||||
bool is_other() const;
|
||||
bool is_symlink() const;
|
||||
|
||||
// for exposition only:
|
||||
private:
|
||||
path_type m_path;
|
||||
mutable status_flags m_status; // stat()-like
|
||||
mutable status_flags m_symlink_status; // lstat()-like
|
||||
};
|
||||
|
||||
typedef basic_directory_entry<path> directory_entry;
|
||||
typedef basic_directory_entry<wpath> wdirectory_entry;
|
||||
|
||||
// basic_directory_iterator
|
||||
|
||||
template<class Path> class <a href="#directory_iterator">basic_directory_iterator</a>
|
||||
: public boost::iterator_facade<
|
||||
basic_directory_iterator<Path>,
|
||||
basic_directory_entry<Path>,
|
||||
boost::single_pass_traversal_tag >
|
||||
{
|
||||
public:
|
||||
typedef Path path_type;
|
||||
|
||||
basic_directory_iterator(); // creates the "end" iterator
|
||||
explicit basic_directory_iterator( const Path & directory_path );
|
||||
};
|
||||
|
||||
typedef basic_directory_iterator<path> directory_iterator;
|
||||
typedef basic_directory_iterator<wpath> wdirectory_iterator;
|
||||
|
||||
// operations functions
|
||||
|
||||
template<class Path> status_flags <a href="#status">status</a>( const Path & ph, system_error_type * ec = 0 );
|
||||
template<class Path> status_flags <a href="#status">status</a>( const Path & ph, const symlink_t &, system_error_type * ec = 0 );
|
||||
|
||||
template<class Path> bool <a href="#exists">exists</a>( const Path & ph );
|
||||
bool exists( status_flags f );
|
||||
bool is_error( status_flags f );
|
||||
template<class Path> bool <a href="#is_directory">is_directory</a>( const <code>Path</code> & ph );
|
||||
bool is_directory( status_flags f );
|
||||
template<class Path> bool <a href="#is_regular">is_regular</a>( const <code>Path</code> & ph );
|
||||
bool is_regular( status_flags f );
|
||||
template<class Path> bool <a href="#is_other">is_other</a>( const <code>Path</code> & ph );
|
||||
bool is_other( status_flags f );
|
||||
template<class Path> bool <a href="#is_symlink">is_symlink</a>( const <code>Path</code> & ph );
|
||||
bool is_symlink( status_flags f );
|
||||
template<class Path> bool <a href="#is_empty">is_empty</a>( const <code>Path</code> & ph );
|
||||
template<class Path> bool <a href="#equivalent">equivalent</a>( const <code>Path</code> & ph1, const <code>Path</code> & ph2 );
|
||||
template<class Path> boost::intmax_t <a href="#file_size">file_size</a>( const <code>Path</code> & ph );
|
||||
template<class Path> std::time_t <a href="#last_write_time">last_write_time</a>( const <code>Path</code> & ph );
|
||||
template<class Path> void <a href="#last_write_time">last_write_time</a>( const <code>Path</code> & ph, std::time_t new_time );
|
||||
template<class Path> bool <a href="#create_directory">create_directory</a>( const <code>Path</code> & directory_ph );
|
||||
template<class Path> void <a href="#create_hard_link">create_hard_link</a>( const Path & existing_file_ph, const Path & new_file_ph );
|
||||
template<class Path> bool <a href="#remove">remove</a>( const <code>Path</code> & ph );
|
||||
template<class Path> unsigned long <a href="#remove_all">remove_all</a>( const <code>Path</code> & ph );
|
||||
template<class Path> void <a href="#rename">rename</a>( const <code>Path</code> & from_path, const <code>Path</code> & to_path );
|
||||
template<class Path> void <a href="#copy_file">copy_file</a>( const <code>Path</code> & source_file, const <code>Path</code> & target_file );
|
||||
template<class Path> <code>Path</code> <a href="#complete">complete</a>( const <code>Path</code> & ph, const <code>Path</code> & base = initial_path<<code>Path></code>() );
|
||||
template<class Path> <code>Path</code> <a href="#system_complete">system_complete</a>( const <code>Path</code> & ph );
|
||||
template<class Path> const<i><b> </b></i>Path<b><i> </i></b>& <a href="#initial_path">initial_path</a>();
|
||||
template<class Path> <code>Path</code> <a href="#current_path">current_path</a>();
|
||||
|
||||
} // namespace filesystem
|
||||
} // namespace boost
|
||||
</pre>
|
||||
|
||||
<h2><a name="basic_directory_entry">Class basic_directory_entry</a></h2>
|
||||
|
||||
<p><b><a name="Performance_note">Performance note</a>:</b> During directory
|
||||
iteration, implementations are
|
||||
permitted but not required to cache a copy of <a href="#status_flag">status information</a>
|
||||
within a directory entry. This attribute information can later be used by member query functions, resulting in
|
||||
three
|
||||
to six times faster operation than for the non-member query functions. Note, however,
|
||||
that attributes cached in directory entries are not updated when the contents of the external file system
|
||||
changes, so the directory entry form of query functions should not be used if stale
|
||||
attributes might pose a problem.</p>
|
||||
|
||||
<h3>path() function</h3>
|
||||
|
||||
<blockquote>
|
||||
<pre>const Path & path() const;</pre>
|
||||
<p><b>Returns:</b> <code>m_path</code>.</p>
|
||||
</blockquote>
|
||||
|
||||
<h3><a name="Other-member-functions">Other member functions</a></h3>
|
||||
|
||||
<p>These member functions have the same behavior as the non-member operations
|
||||
functions of the same name, except that they may rely on cached status
|
||||
information. See <a href="#Performance_note">performance note</a>.</p>
|
||||
|
||||
<h2><a name="directory_iterator">Class basic_directory_iterator</a></h2>
|
||||
|
||||
<p>Class <i>basic_directory_iterator</i> provides a C++ standard conforming input
|
||||
iterator which accesses the contents of a <a href="index.htm#directory">
|
||||
directory</a>. Except as specified below, iteration is performed as if by
|
||||
calling [<a href="design.htm#POSIX-01">POSIX-01</a>] readdir_r() or readdir().</p>
|
||||
|
||||
<p>The value type is <i><a href="path.htm">boost::filesystem::basic_path</a></i>, so
|
||||
dereferencing a <i>basic_directory_iterator</i> yields a <a href="index.htm#path">
|
||||
path</a> to a file or sub-directory contained within the directory represented by
|
||||
the directory-path argument supplied at construction. The path returned by
|
||||
dereferencing a <i>basic_directory_iterator</i> is composed by appending the name of
|
||||
the directory entry to the directory path supplied at construction.</p>
|
||||
|
||||
<p>The order of the path entries returned by dereferencing successive increments
|
||||
of a <i>basic_directory_iterator</i> is unspecified. Thus depending on the ordering
|
||||
provided by a particular implementation will result in non-portable code.</p>
|
||||
|
||||
<p>A directory path returned by dereferencing a <i>basic_directory_iterator</i> is suitable for use as an argument to Boost.Filesystem
|
||||
functions specified as accepting paths or directory paths. A file path returned by dereferencing a <i>basic_directory_iterator</i> is suitable for use as an argument to
|
||||
Boost.Filesystem functions specified as accepting paths or file paths, or C++
|
||||
Standard Library functions specified as taking file names. The leaf of a path
|
||||
returned by dereferencing a <i>basic_directory_iterator</i> will never be <code>".."</code>
|
||||
or <code>"."</code>.</p>
|
||||
|
||||
<p><b><a name="symbolic-link-warning">Warning</a>:</b> Programs performing
|
||||
directory iteration may wish to test, via <a href="#exists">exists()</a>, if the
|
||||
path returned by dereferencing an iterator actually exists. It could be a
|
||||
<a href="index.htm#symbolic-link">symbolic link</a> to a non-existent file or
|
||||
directory. Programs recursively walking directory trees for purposes of removing
|
||||
and renaming entries may wish to avoid following symbolic links, which can be
|
||||
detected with the <a href="#symbolic_link_exists">is_symlink()</a> function.</p>
|
||||
|
||||
<p><b>Warning:</b> If a file or sub-directory is removed from or added to a
|
||||
directory after the construction of a <i>basic_directory_iterator</i> for the
|
||||
directory, it is unspecified whether or not subsequent incrementing of the
|
||||
iterator will ever result in an iterator whose value is the removed or added
|
||||
directory entry.</p>
|
||||
|
||||
<h3><a name="constructors">Constructors</a></h3>
|
||||
<blockquote>
|
||||
|
||||
<p><code>basic_directory_iterator();</code></p>
|
||||
|
||||
<p><b>Effects:</b> Constructs a <i>basic_directory_iterator</i> having the <i>
|
||||
past-the-end</i> value as described in the C++ standard, section 24.1.</p>
|
||||
|
||||
<p><code>explicit basic_directory_iterator( const Path & directory_ph );</code></p>
|
||||
|
||||
<p><b>Effects:</b> Constructs a <i>basic_directory_iterator</i> with a value
|
||||
representing the first path in <i>directory_ph</i>, or if <code>
|
||||
empty(directory_ph)</code>, the <i>past-the-end</i> value.</p>
|
||||
|
||||
<p><b>Throws:</b> if <code>!exists( directory_ph )</code></p>
|
||||
|
||||
<p><b>Note:</b> To iterate over the current directory, write <code>
|
||||
directory_iterator(".")</code> rather than <code>directory_iterator("")</code>.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2>Operations n<a name="Non-member_functions">on-member functions</a></h2>
|
||||
|
||||
<p>
|
||||
The operations non-member functions provide common operations on files and directories.
|
||||
They follow traditional practice of the C, and C++ standard libraries, except
|
||||
that
|
||||
they:</p>
|
||||
|
||||
<ul>
|
||||
<li>Traffic in <i><a href="path.htm">paths</a></i> rather than <code>char*</code>'s, for much
|
||||
enhanced portability.</li>
|
||||
<li>Report errors by throwing exceptions, for safer and better error handling.</li>
|
||||
<li>Tighten specifications slightly, for improved portability.</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
<b>Rationale:</b> Functions which already exist in the C++ Standard Library,
|
||||
such as <i><a href="#remove">remove()</a></i> and <i><a href="#rename">rename()</a></i>,
|
||||
retain the same names and general behavior in the Filesystem Library, to
|
||||
minimize surprises.</p>
|
||||
|
||||
<p>
|
||||
<b><a name="not-precondition-rationale">Rationale</a>:</b> Some errors which might
|
||||
at first glance appear to be preconditions are not
|
||||
specified as such, but instead will throw exceptions. This is
|
||||
because the possibility of <a href="index.htm#Race-condition">race-conditions</a>
|
||||
makes it unreliable to test for preconditions before calling the function. As a
|
||||
design practice, preconditions are not specified when it is not reasonable for a
|
||||
program to test for them before calling the function. </p>
|
||||
|
||||
<p><b>Empty path r<a name="empty_rationale">ationale</a>:</b> Some errors,
|
||||
particularly function arguments of empty paths, are specified both in <i>
|
||||
Precondition</i> and in <i>Throws</i> paragraphs. A non-empty path is specified
|
||||
as a precondition because an empty path is almost certainly an error, the error
|
||||
meets the usual criteria for <i>Preconditions</i> as specified in the C++
|
||||
Standard clause 17, and user pre-detection of the error does not suffer from the
|
||||
<a href="#not-precondition-rationale">precondition race</a> problem described
|
||||
above. The error condition is also specified in the <i>Throws</i> paragraph to
|
||||
ensure that the error results in well-defined rather than implementation-defined
|
||||
behavior, and because existing practice for the equivalent operating system
|
||||
function is usually to treat an empty path as an error. The intended use of the
|
||||
Filesystem Library in portable script-like programs makes undefined behavior particularly
|
||||
unattractive.</p>
|
||||
|
||||
<p>
|
||||
<b>Naming Rationale:</b> See class <i>path</i>
|
||||
<a href="path.htm#Naming_Rationale">Naming Rationale</a>.</p>
|
||||
|
||||
<h3>"<a name="Do-the-right-thing">Do-the-right-thing</a>" rule</h3>
|
||||
|
||||
<p>To allow automatic
|
||||
conversions to function properly for classes <i>path</i> and <i>wpath</i>, as
|
||||
well as to support class template <i>basic_path</i>, several
|
||||
overloads of each non-member function are supplied. The overloads must "do-the-right-thing" using
|
||||
<code><a href="../../utility/enable_if.html">boost::enable_if</a></code> or equivalent techniques, so that the correct
|
||||
overload is selected for calls like <code>exists( "foo" )</code> which
|
||||
depend on automatic conversion to the appropriate basic_path type. To simplify
|
||||
exposition, only the templated version of each non-member function is shown.</p>
|
||||
|
||||
<h3><a name="status">status</a></h3>
|
||||
<blockquote>
|
||||
<pre>template<class Path> <a href="#status_flag">status_flags</a> status( const Path & ph, system_error_type * ec = 0 );
|
||||
template<class Path> <a href="#status_flag">status_flags</a> status( const Path & ph, const <a href="#symlink_t">symlink_t</a> &, system_error_type * ec = 0 );</pre>
|
||||
<p><b>Effects:</b></p>
|
||||
<ul>
|
||||
<li>If <code>ph.empty()</code> or <code>it->empty()</code>:<br>
|
||||
<ul>
|
||||
<li>If ec != 0, set *ec to a system error code indicating "not found".</li>
|
||||
<li>Return <code>not_found_flag</code>.<br>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Determine the attributes of
|
||||
path <code>ph</code> or path <code>*it</code>.<br>
|
||||
<br>
|
||||
For <code>ph</code>, the attributes are always found by querying the
|
||||
operating system. For <code>*it</code>, the implementation is permitted,
|
||||
but not required, to associate a copy of previously obtained attribute
|
||||
information with the iterator.<br>
|
||||
<br>
|
||||
If the <code>symlink_t</code> argument is not present, the attributes are
|
||||
determined as if by <a href="design.htm#POSIX-01">[POSIX-01]</a>
|
||||
stat(). Thus if <code>ph</code> or <code>*it</code> refers to a symbolic link, the link is
|
||||
resolved (that is, deep semantics).<br>
|
||||
<br>
|
||||
If the <code>symlink_t</code> argument is present, the attributes are
|
||||
determined as if by <a href="design.htm#POSIX-01">[POSIX-01]</a> lstat(). Thus if <code>ph</code>
|
||||
or <code>*it</code> refers to a symbolic link, the link is not
|
||||
resolved (that is, shallow semantics).<br>
|
||||
</li>
|
||||
<li>If the attribute determination does not report an error:<br>
|
||||
<ul>
|
||||
<li>If the attributes indicate a symbolic link, as if by
|
||||
<a href="design.htm#POSIX-01">[POSIX-01]</a> S_ISLNK() (also see
|
||||
<a href="i18n.html#Expectations">expectations</a>), return <code>
|
||||
symlink_flag</code>.</li>
|
||||
<li>Set result to 0.</li>
|
||||
<li>If the attributes indicate a directory, as if by
|
||||
<a href="design.htm#POSIX-01">[POSIX-01]</a> S_ISDIR() (also see
|
||||
<a href="i18n.html#Expectations">expectations</a>), <code>result |=
|
||||
directory_flag</code>.</li>
|
||||
<li>If the attributes indicate a file, as if by
|
||||
<a href="design.htm#POSIX-01">[POSIX-01]</a> S_ISREG() (also see
|
||||
<a href="i18n.html#Expectations">expectations</a>), <code>result |=
|
||||
regular_flag</code>.</li>
|
||||
<li>If result is 0, set result to <code>other_flag</code>.</li>
|
||||
<li>Return result.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li>If the attribute determination reports an error:<br>
|
||||
<ul>
|
||||
<li>If ec != 0, set *ec to the error code reported by the operating
|
||||
system.</li>
|
||||
<li>If the query reports an error indicating that <code>ph</code> or <code>
|
||||
*it</code>
|
||||
could <a href="#not_found_remark">not be found</a>, return <code>
|
||||
not_found_flag</code>.</li>
|
||||
<li>Otherwise, return <code>error_flag</code>.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<p><b>Returns:</b> </p>
|
||||
<ul>
|
||||
<li> One of <code>error_flag</code>, <code>not_found_flag</code>, <code>
|
||||
other_flag</code>, or <code>symlink_flag</code>. The <code>symlink_flag</code>
|
||||
is a possibility only when the <code>symlink_t</code> argument is present.</li>
|
||||
<li>Otherwise, one or more of the following, or'ed together: <code>
|
||||
directory_flag</code>,
|
||||
<code>regular_flag</code>. <i>[More status bits may be added in the future.]</i></li>
|
||||
</ul>
|
||||
<p>See <a href="#Performance_note">performance note</a> for subtle
|
||||
differences between behavior of Path and DirItr template signatures.</p>
|
||||
<p><b><a name="not_found_remark">Note</a>:</b> Certain conditions reported
|
||||
by the operating system as errors are treated as <code>
|
||||
not_found_flag</code> rather than <code>
|
||||
error_flag. </code>On POSIX, these are ENOENT and ENOTDIR. On Windows,
|
||||
these are ERROR_FILE_NOT_FOUND, ERROR_PATH_NOT_FOUND, and ERROR_BAD_NETPATH.</p>
|
||||
<p><b>Note:</b> The Microsoft Windows operating system does not currently
|
||||
support symbolic links, so
|
||||
<code>symlink_flag</code> is never returned on that platform. (Short-cut files (.lnk) are a Windows application
|
||||
feature, not an O/S feature.) Windows programmers should still test for symbolic links
|
||||
if applicable, so that programs will continue to work if later Windows versions add the feature, and also so that programs
|
||||
will be portable to systems like POSIX, where symbolic links may be present.</p>
|
||||
</blockquote>
|
||||
|
||||
<h3><a name="exists">exists</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> bool exists( const Path & ph );</code></p>
|
||||
<p><b>Throws:</b> If <code>status(</code>ph<code>) == error_flag</code>.</p>
|
||||
<p><b>Returns:</b> <code>status(ph) != not_found_flag</code></p>
|
||||
<p><code>bool is_exists( status_flags f );</code></p>
|
||||
<p><b><span style="background-color: #FFFFFF">Returns:</span></b><span style="background-color: #FFFFFF"><b>
|
||||
</b>
|
||||
</span><code><span style="background-color: #FFFFFF">f != 0 && ((f &
|
||||
not_found_flag) == 0)</span></code></p>
|
||||
</blockquote>
|
||||
<h3><a name="is_error">is_error</a></h3>
|
||||
<blockquote>
|
||||
<pre><span style="background-color: #FFFFFF">bool is_<a name="exists">error</a>( status_flags f );</span></pre>
|
||||
<p><b><span style="background-color: #FFFFFF">Returns:</span></b><span style="background-color: #FFFFFF"><b>
|
||||
</b><code>(f & error_flag) != 0</code></span></p>
|
||||
</blockquote>
|
||||
<h3><a name="is_directory">is_directory</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> bool is_directory( const Path & ph );</code></p>
|
||||
<p><b>Throws:</b> If <code>status(ph) == error_flag</code>.</p>
|
||||
<p><b>Returns:</b> <code>(status(ph) & directory_flag) != 0</code></p>
|
||||
<pre><span style="background-color: #FFFFFF">bool </span><code><span style="background-color: #FFFFFF">is_directory</span></code><span style="background-color: #FFFFFF">( status_flags f );</span></pre>
|
||||
<p><span style="background-color: #FFFFFF"><b>Returns: </b><code>(f &
|
||||
directory_flag) != 0</code></span></p>
|
||||
</blockquote>
|
||||
<h3><a name="is_regular">is_regular</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> bool is_regular( const Path & ph );</code></p>
|
||||
<p><b>Throws:</b> If <code>status(ph) == error_flag</code>.</p>
|
||||
<p><b>Returns:</b> <code>(status(ph) & regular_flag) != 0</code></p>
|
||||
<pre><span style="background-color: #FFFFFF">bool </span><code><span style="background-color: #FFFFFF">is_regular</span></code><span style="background-color: #FFFFFF">( status_flags f );</span></pre>
|
||||
<p><span style="background-color: #FFFFFF"><b>Returns: </b><code>(f &
|
||||
regular_flag) != 0</code></span></p>
|
||||
</blockquote>
|
||||
<h3><a name="is_other">is_other</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> bool is_other( const Path & ph );</code></p>
|
||||
<p><b>Throws:</b> If <code>status(ph) == error_flag</code>.</p>
|
||||
<p><b>Returns:</b> <code>(status(ph) & other_flag) != 0</code></p>
|
||||
<pre><span style="background-color: #FFFFFF">bool <a name="exists">is_other</a>( status_flags f );</span></pre>
|
||||
<p><span style="background-color: #FFFFFF"><b>Returns:</b> <code>(f &
|
||||
other_flag) != 0</code></span></p>
|
||||
</blockquote>
|
||||
<h3><a name="is_symlink">is_symlink</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> bool is_symlink( const Path & ph );<br>
|
||||
template<class DirItr> bool is_symlink( const DirItr & ph );</code></p>
|
||||
<p>See <a href="#Performance_note">performance note</a> for subtle
|
||||
differences between behavior of Path and DirItr template signatures.</p>
|
||||
<p><b>Throws:</b> If <code>symlink_status(ph) == error_flag</code>.</p>
|
||||
<p><b>Returns:</b> <code>symlink_status(ph) == symlink_flag)</code></p>
|
||||
<pre><span style="background-color: #FFFFFF">bool <a name="exists">is_symlink</a>( status_flags f );</span></pre>
|
||||
<p><span style="background-color: #FFFFFF"><b>Returns: </b><code>(f &
|
||||
symlink_flag) != 0</code></span></p>
|
||||
</blockquote>
|
||||
<h3><a name="is_empty">is_empty</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> bool is_empty( const Path & ph );</code></p>
|
||||
<p><b>Returns:</b> True if the operating system reports the path represented by
|
||||
<i>ph</i> is an empty file or empty directory, else false.</p>
|
||||
<p><b>Throws:</b> if <code>!exists(ph)</code></p>
|
||||
<p>This function determines if the file or directory identified by the
|
||||
contents of <i>ph</i> is empty. To determine if a path string itself is empty,
|
||||
use the <i><a href="path.htm#empty">basic_path::empty()</a></i> function.</p>
|
||||
</blockquote>
|
||||
<h3><a name="equivalent">equivalent</a></h3>
|
||||
<pre><code>template<class Path> </code>bool equivalent( const Path & ph1, const Path & ph2 );</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> <code>false</code> if <code>!exists(ph1) || !exists(ph2)</code>.
|
||||
Otherwise, returns <code>true</code> if ph1 and ph2 resolve to the same file
|
||||
or directory, else <code>false</code>.</p>
|
||||
<p>The criteria used to determine sameness is as if
|
||||
<a href="design.htm#POSIX-01">[POSIX-01]</a> stat() reports identical st_dev, st_ino, st_size, and st_mtime
|
||||
values.</p>
|
||||
<p><b>Note:</b> The POSIX implementation does not protect against
|
||||
<a href="index.htm#Race-condition">race conditions</a>. POSIX requires
|
||||
that <i>"st_dev</i> must be unique within a Local Area Network".</p>
|
||||
<p><b>Note: </b>The Windows implementation protects against <a href="index.htm#Race-condition">race conditions</a>.
|
||||
As a surrogate for <a href="design.htm#POSIX-01">[POSIX-01]</a> stat(), the
|
||||
Windows implementation uses GetFileInformationByHandle(), and considers
|
||||
"same" to be equal values forl dwVolumeSerialNumber,
|
||||
nFileIndexHigh, nFileIndexLow, nFileSizeHigh, nFileSizeLow, ftLastWriteTime.dwLowDateTime, and ftLastWriteTime.dwHighDateTime.
|
||||
Thus for identical media (such as bit-for-bit duplicate CD's, floppies, or memory cards) equivalent() will return <code>true</code>
|
||||
even though the media are physically different. </p>
|
||||
<p><b>Throws:</b> if <code>!exists(ph1) && !exists(ph2)</code></p>
|
||||
<p><b>Warning:</b> This function may be impossible to implement on some
|
||||
operating systems; users may wish to avoid use for code which may be ported to
|
||||
operating systems with limited filesystem support.</p>
|
||||
</blockquote>
|
||||
<h3><a name="file_size">file_size</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> boost::intmax_t file_size( const Path & ph );</code></p>
|
||||
<p><b>Returns:</b> The size of the file in bytes as reported by the operating
|
||||
system.</p>
|
||||
<p><b>Throws:</b> if <code>!is_regular(ph)</code></p>
|
||||
<p><b>Warming:</b> If a compiler does not support <code>maxint_t</code> large
|
||||
enough to represent the operating system's maximum file size, or if the
|
||||
implementation does not know how to query the operating system for large file
|
||||
sizes, the returned value could be incorrect. This is not a problem with modern
|
||||
compilers on modern versions of Linux or Windows. Users on other platforms
|
||||
should build and run the <a href="../example/file_size.cpp">file_size.cpp</a>
|
||||
sample program against a large file to verify correct operation.</p>
|
||||
<p><b>Rationale:</b> Directories are excluded because the complexity of finding
|
||||
the size of a file is typically constant, while finding the size of a directory
|
||||
is typically linear. It was felt this would be surprising. The function is named
|
||||
accordingly. Users needing the size of a directory can trivially provide a user
|
||||
function which iterates over a directory returning a count.</p>
|
||||
</blockquote>
|
||||
<h3><a name="last_write_time">last_write_time</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> std::time_t last_write_time( const Path & ph );</code></p>
|
||||
<p><b>Warning:</b> The times associated with files are subject to many
|
||||
vicissitudes. Each type of file system differs slightly in the details and
|
||||
resolution of how times are recorded. The resolution is as low as one hour on
|
||||
some file systems. It is not uncommon for a program to
|
||||
simultaneously have access to files maintained by FAT, ISO9660, NTFS, and POSIX
|
||||
file systems, and so experience different last_write_time behavior for different
|
||||
files. During program execution, the system clock may be set to a new
|
||||
value by some other, possibly automatic, process. Another thread or process may
|
||||
write to a file, and this may also cause the last write time to change unexpectedly.</p>
|
||||
<p><b>Returns:</b> The time the file was last modified, as reported by the
|
||||
operating system. If the time cannot be determined, returns (std::time_t)(-1).</p>
|
||||
<p>To convert the returned value to UTC or local time, use <code>std::gmtime()</code>
|
||||
or <code>std::localtime()</code> respectively.</p>
|
||||
<p><b>Throws:</b> if <code>!exists(ph)</code></p>
|
||||
<p><code>template<class Path> void last_write_time( const Path & ph, std::time_t new_time );</code></p>
|
||||
<p><b>Effects:</b> Asks the operating system to set the last write time to <code>
|
||||
new_time</code>, or to the current time if <code>new_time==std::time_t()</code>.</p>
|
||||
<p><b>Throws:</b> if <code>!exists(ph)</code></p>
|
||||
<p><b>Rationale:</b> <code>last_write_time(ph)==new_time</code> is not specified
|
||||
as a postcondition because the times may differ somewhat on some operating
|
||||
systems.</p>
|
||||
</blockquote>
|
||||
<h3><a name="create_directory">create_directory</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> bool create_directory( const Path & directory_ph );</code></p>
|
||||
<p><b>Precondition:</b> <code>!directory_ph.empty()</code></p>
|
||||
<p><b>Effects:</b> If the postcondition is not already met, it is established as
|
||||
if by <a href="design.htm#POSIX-01">[POSIX-01]</a> mkdir() with a second
|
||||
argument of S_IRWXU|S_IRWXG|S_IRWXO.</p>
|
||||
<p><b>Returns:</b> The value of <code>!exists( directory_ph )</code> prior to the
|
||||
establishment of the postcondition.</p>
|
||||
<p><b>Postcondition:</b> <code>is_directory(directory_ph)</code></p>
|
||||
<p><b>Throws: </b>if <code>directory_ph.empty() || (exists(directory_ph) && !is_directory(directory_ph)) || !exists(directory_ph/"..")</code>.
|
||||
See <a href="#empty_rationale">empty path rationale</a>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="create_hard_link">create_hard_link</a></h3>
|
||||
<blockquote>
|
||||
<pre>template<class Path> void create_hard_link(
|
||||
const Path & existing_file_ph, const Path & new_file_ph );</pre>
|
||||
<p><b>Precondition:</b> <code>exists(existing_file_ph) && !is_directory(existing_file_ph)<br>
|
||||
&& !exists(new_file_ph) && !is_symlink(new_file_ph)</code></p>
|
||||
<p><b>Effects:</b> The postcondition is established, as if by
|
||||
<a href="design.htm#POSIX-01">[POSIX-01]</a> link().</p>
|
||||
<p><b>Postconditions:</b></p>
|
||||
<ul>
|
||||
<li><code>exists(existing_file_ph) && exists(new_file_ph)<br>
|
||||
&& equivalent( existing_file_ph, new_file_ph )</code></li>
|
||||
<li>The contents of the file <code>existing_file_ph</code> are unchanged.</li>
|
||||
</ul>
|
||||
<p><b>Remarks:</b> As with all Boost.Filesystem functions,
|
||||
<a href="exception.htm">basic_filesystem_error</a> will be thrown if the
|
||||
operation fails. See <a href="index.htm#Common_Specifications">Common
|
||||
Specifications</a>. The exact causes of possible failures vary with the
|
||||
operating system. For example, some file systems do not support hard
|
||||
links at all, even on operating systems with hard link support. Many
|
||||
operating systems do not permit hard links between file systems, and many
|
||||
limit the number of links per file to a fairly small value (1023, on Windows NTFS,
|
||||
for example). See <a href="design.htm#POSIX-01">[POSIX-01]</a> link()
|
||||
specifications for a complete
|
||||
list of POSIX errors which may be encountered.</p>
|
||||
<p><b>Rationale:</b> Hard links to directories are not allowed because they
|
||||
are too non-portable.</p>
|
||||
</blockquote>
|
||||
<h3><a name="remove">remove</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> bool remove( const Path & ph );</code></p>
|
||||
<p><b>Precondition:</b> <code>!ph.empty()</code></p>
|
||||
<p><b>Effects:</b> If the postcondition is not already met, it is established as
|
||||
if by <a href="design.htm#POSIX-01">[POSIX-01]</a> remove().</p>
|
||||
<p><b>Returns:</b> The value of <code>exists( ph )</code> prior to the
|
||||
establishment of the postcondition. </p>
|
||||
<p><b>Postcondition:</b> <code>!exists( ph )</code></p>
|
||||
<p><b>Throws:</b> if<code> ph.empty() || (exists(ph) && is_directory(ph) && !is_empty(ph))</code>.
|
||||
See <a href="#empty_rationale">empty path rationale</a>.</p>
|
||||
<p><b>Note:</b> <a href="index.htm#symbolic-link">Symbolic links</a> are
|
||||
themselves deleted, rather than what they point to being deleted.</p>
|
||||
<p><b>Rationale:</b> Does not throw when <code>!exists( ph )</code> because not
|
||||
throwing:</p>
|
||||
<ul>
|
||||
<li>Works correctly if <code>ph</code> is a dangling symbolic link. </li>
|
||||
<li>Is slightly easier-to-use for many common use cases.</li>
|
||||
<li>Is slightly higher-level because it implies use of postcondition semantics
|
||||
rather than effects semantics, which would be specified in the somewhat
|
||||
lower-level terms of interactions with the operating system.</li>
|
||||
</ul>
|
||||
<p>There is, however, a slight decrease in safety because some errors will slip
|
||||
by which otherwise would have been detected. For example, a misspelled path name
|
||||
could go undetected for a long time.</p>
|
||||
<p>The initial version of the library threw an exception when the path did not exist; it
|
||||
was changed to reflect user complaints.</p>
|
||||
</blockquote>
|
||||
<h3><a name="remove_all">remove_all</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> unsigned long remove_all( const Path & ph );</code></p>
|
||||
<p><b>Precondition:</b> <code>!ph.empty()</code></p>
|
||||
<p><b>Postcondition:</b> <code>!exists( ph ) && !is_symlink( ph )</code></p>
|
||||
<p><b>Returns:</b> The number of files and directories removed.</p>
|
||||
<p><b>Throws:</b> if<code> ph.empty()</code>. See <a href="#empty_rationale">
|
||||
empty path rationale</a>.</p>
|
||||
<p><b>Note:</b> <a href="index.htm#symbolic-link">Symbolic links</a> are
|
||||
themselves deleted, rather than what they point to being deleted.</p>
|
||||
</blockquote>
|
||||
<h3><a name="rename">rename</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> void rename( const Path & old_ph, const Path & new_ph
|
||||
);</code></p>
|
||||
<p><b>Precondition:</b> <code>!old_ph.empty() && !new_ph.empty()</code></p>
|
||||
<p><b>Effects:</b> As if by <a href="design.htm#POSIX-01">[POSIX-01]</a>
|
||||
rename(), changes the name of file or directory <i>old_ph</i>
|
||||
to <i>new_ph</i>. Specifically:</p>
|
||||
<table border="1" cellpadding="5">
|
||||
<tr>
|
||||
<td><b>Source</b></td>
|
||||
<td><b>Target</b></td>
|
||||
<td><b>Result is "as if" these actions occur</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>!exists()</td>
|
||||
<td> </td>
|
||||
<td>Throw <a href="exception.htm">filesystem_error</a>. Note that !exists()
|
||||
covers the old_ph.empty() case. [case 1] </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> </td>
|
||||
<td>new_ph.empty()</td>
|
||||
<td>Throw <a href="exception.htm">filesystem_error</a>. See
|
||||
<a href="#empty_rationale">create_directory() rationale</a>. [case 2] </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> </td>
|
||||
<td>exists()</td>
|
||||
<td>Throw <a href="exception.htm">filesystem_error</a>. [case 3] </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>!is_directory()</td>
|
||||
<td> </td>
|
||||
<td>If !exists( new_ph / ".." ) throw <a href="exception.htm">
|
||||
filesystem_error</a>. [case 4A] <br>
|
||||
The old_ph.leaf() name is changed to
|
||||
new_ph.leaf(). [case 4B] <br>
|
||||
If old_ph / ".." resolves to a different directory than
|
||||
new_ph / "..", the renamed old_ph file is moved there. [case 4C] </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>is_directory()</td>
|
||||
<td> </td>
|
||||
<td>If !exists( new_ph / ".." ) throw <a href="exception.htm">
|
||||
filesystem_error</a>. [case 5A]<br>
|
||||
The old_ph.leaf() name is changed to
|
||||
new_ph.leaf(). [case 5B] <br>
|
||||
If system_complete(old_ph.banch_path()) resolves to a
|
||||
different directory than system_complete(new_ph.branch_path()), the
|
||||
renamed old_ph directory is moved there. [case 5C] </td>
|
||||
</tr>
|
||||
</table>
|
||||
<p><b>Postconditions:</b> <code>!exists(old_ph) && exists(new_ph)</code>,
|
||||
and the <i>old_ph</i> file or directory contents and attributes are otherwise unchanged.</p>
|
||||
<p><b>Throws:</b> See Effects table above. See <a href="#empty_rationale">empty
|
||||
path rationale</a>.</p>
|
||||
<p><b>Rationale:</b> A separate <i>move</i> function is not provided because <i>rename</i> is logically the same operation as <i>move</i>,. The choice of the
|
||||
<i>rename</i> name is based on existing practice in the C, C++, and POSIX
|
||||
libraries. Existence of <i>new_ph</i> is considered an error because that is
|
||||
safer that removing an existing <i>new_ph</i>.</p>
|
||||
<p><b>Note:</b> Some operating systems with
|
||||
<a href="index.htm#multi-root_filesystem">multiple roots</a> do not allow <i>rename</i>
|
||||
operations between roots, and such an attempted <i>rename</i> will throw a <i>
|
||||
<a href="exception.htm">filesystem_error</a></i> exception.. Implementations should not take heroic efforts, such
|
||||
as switching to a copy mode, to make an otherwise failing <i>rename </i>succeed
|
||||
across roots.</p>
|
||||
<p><b>Note:</b> <a href="index.htm#symbolic-link">Symbolic links</a> are
|
||||
themselves renamed, rather than what they point to being renamed.</p>
|
||||
</blockquote>
|
||||
<h3><a name="copy_file">copy_file</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> void copy_file( const Path & old_ph_file, const
|
||||
Path & new_ph_file );</code></p>
|
||||
<p><b>Precondition:</b> <code>!old_ph.empty() && !new_ph.empty()</code></p>
|
||||
<p><b>Effects:</b> Copies the file represented by <i>old_ph_file</i> to <i>
|
||||
new_ph_file</i>.</p>
|
||||
<p><b>Throws:</b> if <code>!exists(old_ph_file) || is_directory(old_ph_file)
|
||||
|| exists(new_ph_file) || new_ph_file.empty() || !exists(to_file_path/".."))</code>.
|
||||
See <a href="#empty_rationale">empty path rationale</a>.</p>
|
||||
<p><b>Note:</b> File attributes are also copied. Specifically, POSIX <i>
|
||||
stat::st_mode</i>, and Windows <i>BY_HANDLE_FILE_INFORMATION::dwFileAttributes</i>. </p>
|
||||
</blockquote>
|
||||
<h3><a name="initial_path">initial_path</a></h3>
|
||||
<blockquote>
|
||||
<p><code>template<class Path> const Path & initial_path();</code></p>
|
||||
<p><b>Effects:</b> The first time called, stores the path returned by
|
||||
<a href="#current_path">current_path()</a>.</p>
|
||||
<p>The preferred implementation would be to call <i>initial_path()</i> during program
|
||||
initialization, before the call to <i>main()</i>. This is, however, not possible
|
||||
with changing the C++ runtime library.</p>
|
||||
<p><b>Returns:</b> A reference to the stored path.</p>
|
||||
<p><b>Rationale:</b> The semantics, in effect, turn a dangerous global variable into
|
||||
a safer global constant. The preferred implementation requires runtime library
|
||||
support, so alternate semantics are supplied for those implementations which
|
||||
cannot change an existing the runtime library.</p>
|
||||
<p><b>Note:</b> It is good practice for a program dependent on <i>
|
||||
initial_path()</i> to call it immediately upon entering<i> main()</i>. That
|
||||
protects against another function altering the current working
|
||||
directory (using a native platform function) before the first call to <i>
|
||||
initial_path()</i>.</p>
|
||||
|
||||
</blockquote>
|
||||
<h3><a name="current_path">current_path</a></h3>
|
||||
<blockquote>
|
||||
<pre><code>template<class Path> </code>Path current_path();</pre>
|
||||
<p><b>Returns:</b> The current path, as if by <a href="design.htm#POSIX-01">[POSIX-01]</a>
|
||||
getcwd().</p>
|
||||
<p><b>Postcondition:</b> <code>current_path().is_complete()</code></p>
|
||||
<p><b>Warning:</b> The current path maintained by the operating system is
|
||||
in-effect a dangerous global variable. It may be changed unexpectedly by a
|
||||
third-party or system library function, or by another thread. For a safer
|
||||
alternative, see <a href="#initial_path">initial_path()</a>.</p>
|
||||
<p><b>Rationale:</b> Although dangerous, the function is useful in dealing
|
||||
with other libraries. The <i>current_path()</i> name was chosen to emphasize
|
||||
that the function returns a complete path, not just a single directory name.</p>
|
||||
</blockquote>
|
||||
<h3><a name="complete">complete</a></h3>
|
||||
|
||||
<blockquote>
|
||||
<p><code>template<class Path> Path complete( const Path & ph, const Path & base = initial_path<Path>() );</code></p>
|
||||
|
||||
<p><b>Precondition:</b> <code>base.is_complete() && (ph.is_complete() || !ph.has_root_name())</code></p>
|
||||
|
||||
<p><b>Effects:</b> Composes a complete path from <code>ph</code> and <code>base</code>,
|
||||
using the following rules:</p>
|
||||
|
||||
<p>For single-root operating systems (POSIX-like systems, for example), if <code>ph.empty()</code>
|
||||
or <code>ph.is_complete()</code>, the composed path is <code>ph</code>,
|
||||
otherwise the composed path is <code>base/ph</code>.</p>
|
||||
|
||||
<p>For <a href="index.htm#multi-root_filesystem">multi-root</a> operating systems (Windows, Classic Mac, many others), the rules are
|
||||
give by this table:</p>
|
||||
<table border="1" cellpadding="5">
|
||||
<tr>
|
||||
<td align="center"> </td>
|
||||
<td align="center"><code>ph.has_root_directory()</code></td>
|
||||
<td align="center"><code>!ph.has_root_directory()</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center"><code>ph.has_root_name()</code></td>
|
||||
<td align="center"><code>ph</code></td>
|
||||
<td align="center"><code>(precondition failure)</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center"><code>!ph.has_root_name()</code></td>
|
||||
<td align="center"><code>base.root_name()<br>
|
||||
/ ph</code></td>
|
||||
<td align="center"><code>base / ph</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
<p><b>Returns:</b> The composed path.</p>
|
||||
|
||||
<p><b>Postcondition:</b> For the returned path, <code>p,</code> <code>p.is_complete()</code>
|
||||
is true.</p>
|
||||
|
||||
<p><b>Throws:</b> On precondition failure. See <a href="#empty_rationale">empty
|
||||
path rationale</a>.</p>
|
||||
|
||||
<p><b><a name="complete_note">Note</a>:</b> When portable behavior is required,
|
||||
use <i>complete()</i>. When operating system dependent behavior is required, use
|
||||
<i>system_complete()</i>.</p>
|
||||
|
||||
<p>Portable behavior is preferred when dealing with paths created internally
|
||||
within a program, particularly where the program should exhibit the same
|
||||
behavior on all operating systems.</p>
|
||||
|
||||
<p>Operating system dependent behavior is preferred when dealing with paths
|
||||
supplied by user input, reported to program users, or which should result in
|
||||
program behavior familiar to and expected by program users. The
|
||||
<a href="../example/simple_ls.cpp">simple_ls.cpp</a> program, for example,
|
||||
operates on a path supplied in the native operating system format, so uses
|
||||
<i>system_complete()</i> to ensure that the path behaves as expected for the
|
||||
particular operating system.</p>
|
||||
|
||||
<p><b>Rationale:</b> The <code>!ph.has_root_name()</code> portion of the
|
||||
precondition disallows the error condition of <code>ph.root_name()</code>
|
||||
being not equivalent to <code>base.root_name()</code>. The restriction is
|
||||
broader that would appear necessary, in that is also prohibits the case where
|
||||
they are equivalent. There is, however, no portable way to express the
|
||||
root_name() equivalence requirement.</p>
|
||||
|
||||
</blockquote>
|
||||
<h3><a name="system_complete">system_complete</a></h3>
|
||||
|
||||
<blockquote>
|
||||
<p><code>template<class Path> Path system_complete( const Path & ph );</code></p>
|
||||
|
||||
<p><b>Precondition:</b> <code>!ph.empty()</code></p>
|
||||
|
||||
<p><b>Effects:</b> Composes a complete path from <code>ph</code>, using the same
|
||||
rules used by the operating system to resolve a path passed as the filename
|
||||
argument to standard library open functions.</p>
|
||||
|
||||
<p>For POSIX-like systems, system_complete( ph ) has the same semantics as <code>
|
||||
complete( ph, current_path() )</code>.</p>
|
||||
|
||||
<p><a name="windows_effects">For Widows</a>, system_complete( ph ) has the same
|
||||
semantics as <code>complete( ph, current_path() )</code> if ph.is_complete() ||
|
||||
!ph.has_root_name() or ph and base have the same root_name().
|
||||
Otherwise it acts like <code>complete( ph, kinky )</code>, where <code>kinky</code>
|
||||
is the current directory for the <code>ph.root_name()</code> drive. This
|
||||
will be the current directory of that drive the last time it was set, and thus
|
||||
may well be <b>residue left over from some prior program</b> run by the command
|
||||
processor! Although these semantics are often useful, they are also very
|
||||
error-prone, and certainly deserve to be called "kinky".</p>
|
||||
|
||||
<p><b>Returns:</b> The composed path.</p>
|
||||
|
||||
<p><b>Postcondition:</b> For the returned path, <code>p,</code> <code>p.is_complete()</code>
|
||||
is true.</p>
|
||||
|
||||
<p><b>Throws:</b> If <code>ph.empty()</code>. See <a href="#empty_rationale">
|
||||
empty path rationale</a>.</p>
|
||||
|
||||
<p><b>Note:</b> See <a href="#complete_note"><i>complete()</i> note</a> for
|
||||
usage suggestions.</p>
|
||||
|
||||
<p><b>Warning:</b> This function relies on a global variable (current_path()),
|
||||
and so tends to be more error-prone than the similar function
|
||||
<a href="#complete">complete()</a>. This function is doubly dangerous on
|
||||
Windows, where under cross-drive conditions it may be relying on a directory set
|
||||
by a prior program run by the command processor.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<hr>
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->01 January, 2006<!--webbot bot="Timestamp" endspan i-checksum="38950" --></p>
|
||||
<p>© Copyright Beman Dawes, 2002</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>
|
||||
1190
doc/path.htm
1190
doc/path.htm
File diff suppressed because it is too large
Load Diff
3435
doc/tr2_proposal.html
Normal file
3435
doc/tr2_proposal.html
Normal file
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user