Menu
▾
▴
[Cpptool-cvs] rfta/deplib/boostcvs/libs/filesystem/doc design.htm,1.1.1.1,1.2 do-list.htm,1.1.1.1,1.2 exception.htm,1.1.1.1,1.2 faq.htm,1.1.1.1,1.2 index.htm,1.1.1.1,1.2 operations.htm,1.1.1.1,1.2 path.htm,1.1.1.1,1.2
Update of /cvsroot/cpptool/rfta/deplib/boostcvs/libs/filesystem/doc
In directory sc8-pr-cvs1:/tmp/cvs-serv17363/deplib/boostcvs/libs/filesystem/doc
Modified Files:
design.htm do-list.htm exception.htm faq.htm index.htm
operations.htm path.htm
Log Message:
* upgraded to the official boost 1.30
Index: design.htm
===================================================================
RCS file: /cvsroot/cpptool/rfta/deplib/boostcvs/libs/filesystem/doc/design.htm,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** design.htm 23 Oct 2002 20:22:45 -0000 1.1.1.1
--- design.htm 1 Apr 2003 08:25:45 -0000 1.2
***************
*** 19,23 ****
<a href="#Realities">Realities</a><br>
<a href="#Rationale">Rationale</a><br>
! <a href="#Abandoned Designs">Abandoned Designs</a><br>
<a href="#References">References</a></p>
--- 19,23 ----
<a href="#Realities">Realities</a><br>
<a href="#Rationale">Rationale</a><br>
! <a href="#Abandoned_Designs">Abandoned_Designs</a><br>
<a href="#References">References</a></p>
***************
*** 112,119 ****
exist.<br>
<br>
! Rationale: Defining important behavior unspecified or "implementation defined" does a
great disservice to programmers using a library because it makes it appear
that code relying on the behavior is portable, when in fact there is nothing
! at all portable about it. The only case where such under-specification is acceptable is when both users and implementors know from
other sources exactly what behavior is required, yet for some reason it isn't
possible to specify it exactly.</li>
--- 112,119 ----
exist.<br>
<br>
! Rationale: Leaving important behavior unspecified or "implementation defined" does a
great disservice to programmers using a library because it makes it appear
that code relying on the behavior is portable, when in fact there is nothing
! portable about it. The only case where such under-specification is acceptable is when both users and implementors know from
other sources exactly what behavior is required, yet for some reason it isn't
possible to specify it exactly.</li>
***************
*** 121,125 ****
<h2><a name="Realities">Realities</a></h2>
<ul>
! <li>Some file systems are single rooted, others are multi-rooted.<br>
</li>
<li>Some file systems provide both a long and short form of filenames.<br>
--- 121,126 ----
<h2><a name="Realities">Realities</a></h2>
<ul>
! <li>Some operating systems have a single directory tree root, others have
! multiple roots.<br>
</li>
<li>Some file systems provide both a long and short form of filenames.<br>
***************
*** 134,138 ****
(so-called 8.3) file names.<br>
</li>
! <li>Some file systems allow other file systems with different
characteristics to be "mounted" within a directory tree. Thus a
ISO-9660 or Windows
--- 135,139 ----
(so-called 8.3) file names.<br>
</li>
! <li>Some operating systems allow file systems with different
characteristics to be "mounted" within a directory tree. Thus a
ISO-9660 or Windows
***************
*** 148,152 ****
number". Some don't.<br>
</li>
! <li>Not all file systems use single character separators in path names. Some use
paired notations. A typical fully-specified OpenVMS filename
might look something like this:<br>
--- 149,153 ----
number". Some don't.<br>
</li>
! <li>Not all operating systems use single character separators in path names. Some use
paired notations. A typical fully-specified OpenVMS filename
might look something like this:<br>
***************
*** 198,202 ****
<p>Several key insights went into the <i>path</i> class design:</p>
<ul>
! <li>Decoupling the input formats, internal conceptual (<i>vector<string></i>
or other sequence)
model, and output formats.</li>
--- 199,203 ----
<p>Several key insights went into the <i>path</i> class design:</p>
<ul>
! <li>Decoupling of the input formats, internal conceptual (<i>vector<string></i>
or other sequence)
model, and output formats.</li>
***************
*** 205,208 ****
--- 206,212 ----
<li>Providing several output formats solved another set of previously
intractable problems.</li>
+ <li>Several non-obvious functions (particularly decomposition and composition)
+ are required to support portable code. (Peter Dimov, Thomas Witt, Glen
+ Knowles, others.)</li>
</ul>
***************
*** 213,217 ****
answers to that question, the Filesystem Library alerts programmers of the need
to ask it in the first place.</p>
! <h2><a name="Abandoned Designs">Abandoned Designs</a></h2>
<h3>operations.hpp</h3>
<p>Dietmar Kühl's original dir_it design and implementation supported
--- 217,221 ----
answers to that question, the Filesystem Library alerts programmers of the need
to ask it in the first place.</p>
! <h2><a name="Abandoned_Designs">Abandoned Designs</a></h2>
<h3>operations.hpp</h3>
<p>Dietmar Kühl's original dir_it design and implementation supported
***************
*** 219,223 ****
discussions among Library Working Group members failed to identify portable
semantics for wide-character names on systems not providing native support. See
! <a href="faq.htm#wide-character names">FAQ</a>.</p>
<p>Previous iterations of the interface design used explicitly named functions providing a
large number of convenience operations, with no compile-time or run-time
--- 223,227 ----
discussions among Library Working Group members failed to identify portable
semantics for wide-character names on systems not providing native support. See
! <a href="faq.htm#wide-character_names">FAQ</a>.</p>
<p>Previous iterations of the interface design used explicitly named functions providing a
large number of convenience operations, with no compile-time or run-time
***************
*** 234,241 ****
permissive, prune, recurse, and other options, plus predicate, and possibly
other, filtering features) were abandoned because the details became both
! complex and contentious. What is left is a toolkit of low-level operations from
! which the user can create more complex convenience operations, plus a very small
! number of convenience functions which were found to be useful enough to justify
! inclusion.</p>
<h3>path.hpp</h3>
--- 238,246 ----
permissive, prune, recurse, and other options, plus predicate, and possibly
other, filtering features) were abandoned because the details became both
! complex and contentious.</p>
!
! <p>What is left is a toolkit of low-level operations from which the user can
! create more complex convenience operations, plus a very small number of
! convenience functions which were found to be useful enough to justify inclusion.</p>
<h3>path.hpp</h3>
***************
*** 274,281 ****
<p>[<a name="ISO-9660">ISO-9660</a>] International Standards Organization, 1988.</p>
! <p>[<a name="POSIX-01">POSIX-01</a>] Open Group, <i>IEEE Std 1003.1-2001 [AKA
! POSIX]</i>, 2001,
! <a href="http://www.opengroup.org/onlinepubs/007904975/toc.htm">
! http://www.opengroup.org/onlinepubs/007904975/toc.htm</a></p>
<p>[<a name="Wulf-Shaw-73">Wulf-Shaw-73</a>] William Wulf, Mary Shaw, <i>Global
--- 279,292 ----
<p>[<a name="ISO-9660">ISO-9660</a>] International Standards Organization, 1988.</p>
! <p>[<a name="MSDN">MSDN</a>] Microsoft Platform SDK for Windows, Storage Start
! Page,
! <a href="http://msdn.microsoft.com/library/en-us/fileio/base/storage_start_page.asp">
! http://msdn.microsoft.com/library/en-us/fileio/base/storage_start_page.asp</a></p>
!
! <p>[<a name="POSIX-01">POSIX-01</a>] IEEE Std 1003.1-2001/ISO/IEC 9945:2002 ,
! <a href="http://www.unix-systems.org/version3/">
! http://www.unix-systems.org/version3/</a>. The ISO JTC1/SC22/WG15 - POSIX
! homepage is <a href="http://std.dkuug.dk/JTC1/SC22/WG15/">
! http://std.dkuug.dk/JTC1/SC22/WG15/</a>.</p>
<p>[<a name="Wulf-Shaw-73">Wulf-Shaw-73</a>] William Wulf, Mary Shaw, <i>Global
***************
*** 285,289 ****
<p>© Copyright Beman Dawes, 2002</p>
<p>Revised
! <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->13 September, 2002<!--webbot bot="Timestamp" endspan i-checksum="39336" --></p>
</body>
--- 296,300 ----
<p>© Copyright Beman Dawes, 2002</p>
<p>Revised
! <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->28 January, 2003<!--webbot bot="Timestamp" endspan i-checksum="38582" --></p>
</body>
Index: do-list.htm
===================================================================
RCS file: /cvsroot/cpptool/rfta/deplib/boostcvs/libs/filesystem/doc/do-list.htm,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** do-list.htm 23 Oct 2002 20:22:45 -0000 1.1.1.1
--- do-list.htm 1 Apr 2003 08:25:45 -0000 1.2
***************
*** 4,31 ****
Do-list</h1>
<ul>
! <li>Finish the probe program, and ask Boost people to run it on various O/S's.<br>
</li>
! <li>Finish portability guide and checking functions. Get opinions on default, Boost, and other error checks. POSIX?
! Windows? Mac? ISO 6990?<br>
</li>
! <li>Cyclic paths:</li>
</ul>
- <blockquote>
- <ul>
- <li>General requirements.</li>
- <li>Add cycle-breaking code if needed.</li>
- <li>Add test case to make sure functions like <i>remove_all</i> don't loop.</li>
- </ul>
- </blockquote>
<ul>
! <li>As a lexical concept, parent-directory is portable unless it escapes to
! the operating system. But do all operating recognize such a concept in a path?
! I doubt it. Maybe there should be a checking function that verifies that
! generic_path() contains no <code>".."</code>.<br>
</li>
- <li>Once the review is complete, ask for help porting to the Mac, etc.</li>
</ul>
<hr>
<p>© Copyright Beman Dawes, 2002</p>
<p>Revised
! <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->13 September, 2002<!--webbot bot="Timestamp" endspan i-checksum="39336" --></p>
\ No newline at end of file
--- 4,46 ----
Do-list</h1>
<ul>
! <li>Windows: Some files seem to be poisoned to the point where you can't even
! do is_directory() on them without an access error. For example, pagefile.sys. Should directory_iterator ignore these files?<br>
</li>
! <li>Windows: //share style paths need more analysis and test cases for system_complete()
! and complete(). Also, path_test cases at line 410 need review, correction.<br>
</li>
! <li>Replace filesystem_error impl with shared_ptr. (Dave Abrahams).<br>
! </li>
! <li>Consider changing who()
! interface (and ctors to const char *).<br>
! </li>
! <li>Add a path::swap member function guaranteed not to throw. (Geurt Vos).<br>
! </li>
! <li>Windows: What happens when a directory_itorator encounters a
! wide-character filename? Write a test case.</li>
</ul>
<ul>
! <li>Add "." current directory to generic path? Add test cases one
! way or the other. Change simple_ls accordingly.<br>
! </li>
! <li>Ask for help porting to other operating systems, such as the Mac, etc.</li>
! </ul>
! <ul>
! <li>Finish the probe program, and ask Boost people to run it on various O/S's.<br>
! </li>
! <li>Finish portability guide and checking functions. Get opinions on default, Boost, and other error checks. POSIX?
! Windows? Mac? ISO 6990? Document the checking functions.<br>
! </li>
! <li>Operations_test line 171 - why only check iterator tag? Why not
! Assignable, etc?<br>
! </li>
! <li>The wrapped fstream functions which return the type of the stream (*this)
! would have to be overridden to get the wrapped type (boost::filesystem::ifstream
! rather than std::ifstream, for example). But does it matter? Does anyone care?
! Will any programs fail?<br>
</li>
</ul>
<hr>
<p>© Copyright Beman Dawes, 2002</p>
<p>Revised
! <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->17 March, 2003<!--webbot bot="Timestamp" endspan i-checksum="28843" --></p>
\ No newline at end of file
Index: exception.htm
===================================================================
RCS file: /cvsroot/cpptool/rfta/deplib/boostcvs/libs/filesystem/doc/exception.htm,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** exception.htm 23 Oct 2002 20:22:45 -0000 1.1.1.1
--- exception.htm 1 Apr 2003 08:25:45 -0000 1.2
***************
*** 14,17 ****
--- 14,22 ----
<img border="0" src="../../../c++boost.gif" align="center" width="277" height="86"><a href="../../../boost/filesystem/exception.hpp">boost/filesystem/exception.hpp</a></h1>
+ <p><a href="#Introduction">Introduction</a><br>
+ <a href="#Synopsis">Synopsis</a><br>
+ <a href="#Members">Member functions</a><br>
+ <a href="#Acknowledgements">Acknowledgements</a></p>
+
<h2><a name="Introduction">Introduction</a></h2>
***************
*** 20,29 ****
report operational errors.</p>
! <p>There isn't any HTML documentation available yet. The header itself, <a href="../../../boost/filesystem/exception.hpp">boost/filesystem/exception.hpp</a>,
! contains comments as to the specifications for important member functions.</p>
<hr>
<p>© Copyright Beman Dawes, 2002</p>
<p>Revised
! <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->11 July, 2002<!--webbot bot="Timestamp" endspan i-checksum="21079" --></p>
</body>
--- 25,164 ----
report operational errors.</p>
! <p>The design evolved based on user requests to ease portability and
! internationalization.</p>
!
! <h2><a name="Synopsis">Synopsis</a></h2>
! <pre>namespace boost
! {
! namespace filesystem
! {
! enum <a name="error_code">error_code</a>
! {
! no_error = 0,
! system_error, // system generated error; if possible, is translated
! // to one of the more specific errors below.
! other_error, // library generated error
! security_error, // includes access rights, permissions failures
! read_only_error,
! io_error,
! path_error,
! not_found_error,
! not_directory_error,
! busy_error, // implies trying again might succeed
! already_exists_error,
! not_empty_error,
! is_directory_error,
! out_of_space_error,
! out_of_memory_error,
! out_of_resource_error
! };
!
! class filesystem_error : public std::runtime_error
! {
! public:
!
! <a href="#Constructors">filesystem_error</a>( const std::string & who,
! const std::string & message );
!
! <a href="#Constructors">filesystem_error</a>( const std::string & who,
! const path & path1, const std::string & message );
!
! <a href="#Constructors">filesystem_error</a>( const std::string & who,
! const path & path1, <i>sys_err</i> sys_err_code );
!
! <a href="#Constructors">filesystem_error</a>( const std::string & who,
! const path & path1, const path & path2,
! <i>sys_err</i> sys_err_code );
!
! ~filesystem_error() throw();
!
! <i>sys_err</i> <a href="#native_error">native_error</a>() const;
! error_code <a href="#error">error</a>() const;
! const std::string & <a href="#who">who</a>() const;
! const path & <a href="#path1">path1</a>() const;
! const path & <a href="#path2">path2</a>() const;
! };
! } // namespace filesystem
! } // namespace boost
! </pre>
!
! <p>For POSIX and Windows, <i><code>sys_err</code></i> is <code>int</code>. For
! other operating systems, it is implementation defined.</p>
!
! <h2><a name="Members">Member functions</a></h2>
!
! <h3><a name="Constructors">Constructors</a></h3>
! <blockquote>
! <pre>filesystem_error( const std::string & who,
! const std::string & message );
!
! filesystem_error( const std::string & who,
! const path & path1, const std::string & message );
!
! filesystem_error( const std::string & who,
! const path & path1, int sys_err_code );
!
! filesystem_error( const std::string & who,
! const path & path1, const path & path2,
! int sys_err_code );</pre>
! <p><b>Precondition:</b> The <code>who</code> argument is in the form, as
! appropriate:</p>
! <ul>
! <li>boost::filesystem::class-name::function-name for errors from public
! member functions</li>
! <li>boost::filesystem::class-name for errors not identified with a
! particular member function.</li>
! <li>boost::filesystem::function-name for errors from non-member functions.</li>
! </ul>
! <p>These forms are explicitly specified to ensure portability of user programs
! between library implementations. </p>
! <p><b>Effects:</b> Constructs a <i>filesystem_error</i> object.</p>
! </blockquote>
! <h3><a name="native_error">native_error</a></h3>
! <blockquote>
! <p><i><code>sys_err</code></i><code> native_error() const;</code></p>
! <p><b>Returns:</b> The <code>sys_err_code</code> argument to the constructor,
! if any. Otherwise, 0.</p>
! </blockquote>
! <h3><a name="error">error</a></h3>
! <blockquote>
! <pre>error_code error() const;</pre>
! <p><b>Returns:</b> <code>native_error()</code> translated to <code>
! <a href="#error_code">error_code</a></code>. The translation is
! implementation-defined. For the POSIX and Windows implementations, see
! <a href="../src/exception.cpp">libs/filesystem/src/exception.cpp</a>.</p>
! </blockquote>
!
! <h3><a name="who">who</a></h3>
! <blockquote>
! <pre>const std::string & who() const;</pre>
!
! <p><b>Returns:</b> The <code>who</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>.</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>.</p>
! </blockquote>
!
! <h2><a name="Acknowledgements">Acknowledgements</a></h2>
!
! <p>Peter Dimov patently identified requirements for portability and
! internationalization of error messages. </p>
<hr>
<p>© Copyright Beman Dawes, 2002</p>
<p>Revised
! <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->02 January, 2003<!--webbot bot="Timestamp" endspan i-checksum="38568" --></p>
</body>
Index: faq.htm
===================================================================
RCS file: /cvsroot/cpptool/rfta/deplib/boostcvs/libs/filesystem/doc/faq.htm,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** faq.htm 23 Oct 2002 20:22:46 -0000 1.1.1.1
--- faq.htm 1 Apr 2003 08:25:46 -0000 1.2
***************
*** 5,16 ****
<img border="0" src="../../../c++boost.gif" align="center" width="277" height="86">Filesystem
FAQ</h1>
! <p><b>Why not use a URI (Universal Resource Identifier) based path?</b></p>
! <p>URI's would promise more than the Filesystem Library can actually deliver,
! since URI's extend far beyond what most operating systems consider a file or a
! directory. Thus for the primary "portable script-style file system
! operations" requirement of the Filesystem Library, full URI's appear to be over-specification.</p>
! <p><b>Why base the generic-path string format on POSIX?<br>
! <br>
! </b>POSIX 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
--- 5,10 ----
<img border="0" src="../../../c++boost.gif" align="center" width="277" height="86">Filesystem
FAQ</h1>
! <p><b>Why base the generic-path string format on POSIX?</b></p>
! <p>POSIX 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
***************
*** 18,21 ****
--- 12,20 ----
operating system supplied
POSIX library (z/OS, OS/390, and many more.)</p>
+ <p><b>Why not use a full URI (Universal Resource Identifier) based path?</b></p>
+ <p>URI's would promise more than the Filesystem Library can actually deliver,
+ since URI's extend far beyond what most operating systems consider a file or a
+ directory. Thus for the primary "portable script-style file system
+ operations" requirement of the Filesystem Library, full URI's appear to be over-specification.</p>
<p><b>Why isn't <i>path</i> a base class with derived <i>directory_path</i> and
<i>file_path</i> classes?</b></p>
***************
*** 24,35 ****
directory path, and this seemed to increase errors and decrease code
readability. There was no apparent upside benefit. </p>
! <p><b>Why not support a concept of specific kinds 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
! library. Gaining some advantage by using features specific to particular
! operating systems is not a requirement.</p>
<p>Furthermore, concepts like "posix_file_system"
are very slippery. What happens when a NTFS or ISO 9660 file system is mounted
! in directory on a machine running the POSIX operating system, for example?</p>
<p><b>Why not supply a 'handle' type, and let the file and directory operations
traffic in it?</b></p>
--- 23,44 ----
directory path, and this seemed to increase errors and decrease code
readability. There was no apparent upside benefit. </p>
! <p><b>Why do some function names have a "native_" prefix?</b></p>
! <p>To alert users that the results are inherently non-portable. The names are
! deliberately ugly to discourage use except where really necessary.</p>
! <p><b>Why doesn't path supply operator== and other comparison operators?</b></p>
! <p>There is no way to know if two <i>path</i> objects actually represent the
! same path. For example, <i>path("/foo")</i> and <i>path("../foo")</i> may
! represent the same path, even though they are textually different. If exact
! textual comparison is desired, <i>
! path::string()'s</i> can be used.</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
! 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
! OpenVMS machine.</p>
<p>Furthermore, concepts like "posix_file_system"
are very slippery. What happens when a NTFS or ISO 9660 file system is mounted
! in directory on a machine running a POSIX-like operating system, for example?</p>
<p><b>Why not supply a 'handle' type, and let the file and directory operations
traffic in it?</b></p>
***************
*** 122,130 ****
<p>Global variables are considered harmful [<a href="design.htm#Wulf-Shaw-73">wulf-shaw-73</a>].
While we can't prevent people from shooting themselves in the foot, we aren't
! about to hand them the gun.</p>
<p><b>Why aren't there query functions for compound conditions like existing_directory?</b></p>
<p>After several attempts, named queries for multi-attribute proved a
slippery-slope; where do you stop?</p>
! <p><b>Why aren't <a name="wide-character names">wide-character names</a> supported? Why not std::wstring or even
a templated type?</b></p>
<p>Wide-character names would provide an illusion of portability where
--- 131,139 ----
<p>Global variables are considered harmful [<a href="design.htm#Wulf-Shaw-73">wulf-shaw-73</a>].
While we can't prevent people from shooting themselves in the foot, we aren't
! about to hand them a loaded gun pointed right at their big toe.</p>
<p><b>Why aren't there query functions for compound conditions like existing_directory?</b></p>
<p>After several attempts, named queries for multi-attribute proved a
slippery-slope; where do you stop?</p>
! <p><b>Why aren't <a name="wide-character_names">wide-character names</a> supported? Why not std::wstring or even
a templated type?</b></p>
<p>Wide-character names would provide an illusion of portability where
***************
*** 142,145 ****
--- 151,156 ----
(3) even the committee members most interested in wide-character names are
unsure that they are a good idea in the context of a portable library.</p>
+ <p>[October, 2002 - PJ Plauger has suggested a locale based conversion
+ scheme. Others have indicated support for such an experiment.]</p>
<p><b>Why aren't file and directory name portability errors detected automatically,
rather than by separate function calls?</b></p>
***************
*** 152,178 ****
<p>A number (at least six) of designs for automatic name validity error
detection were evaluated, including at least four complete implementations.
! While the details for rejection differed, they all tended to distort the
otherwise simple design of the rest of the library.</p>
! <p><b>Why doesn't the generic path grammar include syntax for portably
! specifying the root directory?</b></p>
! <p>The concept of "root directory" appears to be inherently non-portable.
! For example, "/" means one thing on POSIX (an absolute path the single
! filesystem root), and another on Windows (a relative path to the root of the
! current drive). It goes rapidly downhill from there; on the classic Mac
! OS, root names can be ambiguous!</p>
! <p><b>Why isn't there a path::is_absolute() or similar function?</b></p>
! <p>Because useful semantics are not obvious. On some operating systems a path is clearly either absolute or
! relative, but on others the distinction isn't clear. For example, on Windows consider these
! paths:</p>
! <ul>
! <li>"/foo" is not strictly an absolute path since it is relative to the
! current drive, yet appending it to another path as if it were relative clearly
! isn't correct.</li>
! <li>"c:foo" is relative to the current working directory on drive "c:",
! yet it can't be treated like other relative paths in that it can't be appended
! to an absolute path.</li>
! </ul>
<hr>
<p>© Copyright Beman Dawes, 2002</p>
<p>Revised
! <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->12 September, 2002<!--webbot bot="Timestamp" endspan i-checksum="39334" --></p>
\ No newline at end of file
--- 163,176 ----
<p>A number (at least six) of designs for automatic name validity error
detection were evaluated, including at least four complete implementations.
! While the details for rejection differed, all automatic name validity checking
! designs tended to distort the
otherwise simple design of the rest of the library.</p>
! <p><b>Why are paths sometimes manipulated by member functions and sometimes by
! non-member functions?</b></p>
! <p>The design rule is that purely lexical operations are supplied as member
! functions, while operations performed by the operating system are provided as
! free functions.</p>
<hr>
<p>© Copyright Beman Dawes, 2002</p>
<p>Revised
! <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->28 January, 2003<!--webbot bot="Timestamp" endspan i-checksum="38582" --></p>
\ No newline at end of file
Index: index.htm
===================================================================
RCS file: /cvsroot/cpptool/rfta/deplib/boostcvs/libs/filesystem/doc/index.htm,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** index.htm 23 Oct 2002 20:22:47 -0000 1.1.1.1
--- index.htm 1 Apr 2003 08:25:46 -0000 1.2
***************
*** 22,27 ****
<a href="#Definitions">Definitions</a><br>
!
! <a href="#Requirements">Requirements</a><br>
<a href="#Race-condition">Race-condition danger</a><br>
<a href="#Acknowledgements">Acknowledgements</a></td>
--- 22,26 ----
<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="#Acknowledgements">Acknowledgements</a></td>
***************
*** 34,37 ****
--- 33,38 ----
<a href="fstream.htm"><b><i>fstream.hpp</i></b> documentation</a><br>
<a href="exception.htm"><b><i>exception.hpp</i></b> documentation</a><br>
+ <a href="convenience.htm"><b><i>convenience.hpp</i></b>
+ documentation</a><br>
<a href="do-list.htm">Do-list</a></td>
</tr>
***************
*** 46,75 ****
design</a> encourages, but does not require, safe and portable filesystem usage.</p>
! <p>Filesystem Library components are supplied by several headers, all in
directory boost/filesystem:</p>
<ul>
! <li>Header <i>path.hpp</i> provides class <i>path, </i>a portable mechanism for representing
<a href="#path">paths</a> in C++ programs. Validity checking
functions are also provided. See <a href="path.htm">path.hpp documentation</a>.<br>
</li>
! <li>Header <i>operations.hpp</i> provides functions operating on files and directories,
and includes class <i>directory_iterator</i>. See <a href="operations.htm">
operations.hpp documentation</a>.<br>
</li>
! <li>Header <i>fstream.hpp</i> provides the same components as the C++ Standard
Library's <i>fstream</i> header, except
that files are identified by <i>path</i> objects rather that <i>char *</i>'s.
See <a href="fstream.htm">fstream.hpp documentation</a>.<br>
</li>
! <li>Header <i>exception.hpp</i> provides class <i>filesystem_error</i>. See
<a href="exception.htm">exception.hpp documentation</a>.<br>
</li>
! <li>Experimental header <i>
! <a href="../../../boost/filesystem/recursive_directory_iterator.hpp">
! recursive_directory_iterator.hpp</a></i> provides an undocumented directory
! iterator which recurses into any sub-directories encountered. It will be
! incorporated into the Filesystem Library if user feedback is favorable.</li>
</ul>
<h2>Two-minute <a name="tutorial">tutorial</a></h2>
<p>First some preliminaries:</p>
--- 47,86 ----
design</a> encourages, but does not require, safe and portable filesystem usage.</p>
! <p>The Filesystem Library supplies several headers, all in
directory boost/filesystem:</p>
<ul>
! <li>Header <i><a href="../../../boost/filesystem/path.hpp">path.hpp</a></i> provides class <i>path, </i>a portable mechanism for representing
<a href="#path">paths</a> in C++ programs. Validity checking
functions are also provided. See <a href="path.htm">path.hpp documentation</a>.<br>
</li>
! <li>Header <i><a href="../../../boost/filesystem/operations.hpp">operations.hpp</a></i> provides functions operating on files and directories,
and includes class <i>directory_iterator</i>. See <a href="operations.htm">
operations.hpp documentation</a>.<br>
</li>
! <li>Header <i><a href="../../../boost/filesystem/fstream.hpp">fstream.hpp</a></i> provides the same components as the C++ Standard
Library's <i>fstream</i> header, except
that files are identified by <i>path</i> objects rather that <i>char *</i>'s.
See <a href="fstream.htm">fstream.hpp documentation</a>.<br>
</li>
! <li>Header <i><a href="../../../boost/filesystem/exception.hpp">exception.hpp</a></i> provides class <i>filesystem_error</i>. See
<a href="exception.htm">exception.hpp documentation</a>.<br>
</li>
! <li>Header <a href="../../../boost/filesystem/convenience.hpp">convenience.hpp</a>
! provides convenience functions that combine lower-level functions in useful
! ways. See <a href="convenience.htm">convenience.hpp documentation</a>.</li>
</ul>
+ <p>The object-library source files (<a href="../src/convenience.cpp">convenience.cpp</a>,
+ <a href="../src/exception.cpp">exception.cpp</a>,
+ <a href="../src/operations_posix_windows.cpp">operations_posix_windows.cpp</a>,
+ and <a href="../src/path_posix_windows.cpp">path_posix_windows.cpp</a>) are
+ supplied in directory libs/filesystem/src. These source files implement the
+ library for POSIX or Windows compatible operating systems; no implementation is
+ supplied for other operating systems. Note that many operating systems not
+ normally thought of as POSIX or Windows systems, such as mainframe legacy
+ operating systems or embedded operating systems, support POSIX compatible file
+ systems which will work with the Filesystem Library.</p>
+ <p>The object-library can be built with a <a href="../build/Jamfile">Jamfile</a>
+ supplied in directory libs/filesystem/build.</p>
<h2>Two-minute <a name="tutorial">tutorial</a></h2>
<p>First some preliminaries:</p>
***************
*** 77,81 ****
<pre>#include "boost/filesystem/operations.hpp" // includes boost/filesystem/path.hpp
#include "boost/filesystem/fstream.hpp" // ditto
! #include <iostream> // for cout
namespace fs = boost::filesystem;</pre>
</blockquote>
--- 88,92 ----
<pre>#include "boost/filesystem/operations.hpp" // includes boost/filesystem/path.hpp
#include "boost/filesystem/fstream.hpp" // ditto
! #include <iostream> // for std::cout
namespace fs = boost::filesystem;</pre>
</blockquote>
***************
*** 104,121 ****
</blockquote>
<p>Additional class path constructors provide for an operating system dependent
! format, useful for with user provided input:</p>
<blockquote>
<pre>int main( int argc, char * argv[] ) {
! fs::path arg_path( argv[1], fs::system_specific );</pre>
</blockquote>
! <p>To make class <i>path</i> objects easy to use in expressions, <i>operator<<</i>
appends paths:</p>
<blockquote>
! <pre>fs::ifstream file1( arg_path << "foo/bar" );
! fs::ifstream file2( arg_path << "foo" << "bar" );</pre>
</blockquote>
! <p>Note that expressions <i>arg_path << "foo/bar"</i> and <i>arg_path << "foo"
! << "bar"</i> yield equivalent results.</p>
! <p><a href="operations.htm#Class directory_iterator">Class <i>directory_iterator</i></a>
is an important component of the library. It provides input iterators over the
contents of a directory, with the value type being class <i>path</i>.</p>
--- 115,132 ----
</blockquote>
<p>Additional class path constructors provide for an operating system dependent
! format, useful for user provided input:</p>
<blockquote>
<pre>int main( int argc, char * argv[] ) {
! fs::path arg_path( argv[1], fs::native ); // native means use O/S path format</pre>
</blockquote>
! <p>To make class <i>path</i> objects easy to use in expressions, <i>operator/</i>
appends paths:</p>
<blockquote>
! <pre>fs::ifstream file1( arg_path / "foo/bar" );
! fs::ifstream file2( arg_path / "foo" / "bar" );</pre>
</blockquote>
! <p>Note that expressions <i>arg_path / "foo/bar"</i> and <i>arg_path / "foo"
! / "bar"</i> yield identical results.</p>
! <p><a href="operations.htm#directory_iterator">Class <i>directory_iterator</i></a>
is an important component of the library. It provides input iterators over the
contents of a directory, with the value type being class <i>path</i>.</p>
***************
*** 162,169 ****
script-like, programs using the Filesystem Library!</p>
<h2><a name="Examples">Examples</a></h2>
! <p>Until a custom-made example is available, see
! <a href="../example/compiler_status.cpp">compiler_status.cpp</a>, an actual
! program which uses the library.</p>
! <p>Test programs are also sometimes useful in understanding a library, as they
illustrate what the developer expected to work and not work. See:</p>
<ul>
--- 173,200 ----
script-like, programs using the Filesystem Library!</p>
<h2><a name="Examples">Examples</a></h2>
! <h3>simple_ls.cpp</h3>
! <p>The example program <a href="../example/simple_ls.cpp">simple_ls.cpp</a> is
! given a path as a command line argument. Since the command line argument may be
! a relative path, the complete path is determined so that messages displayed
! can be more precise.</p>
! <p>The program checks to see if the path exists; if not a message is printed.</p>
! <p>If the path identifies a directory, the directory is iterated through,
! printing the name of the entries found, and an indication if they are
! directories. A count of directories and files is updated, and then printed after
! the iteration is complete.</p>
! <p>If the path is for a file, a message indicating that is printed.</p>
! <p>Try compiling and executing <a href="../example/simple_ls.cpp">simple_ls.cpp</a>
! to see how it works on your system. Try various path arguments to see what
! happens.</p>
! <h3>Other examples</h3>
! <p>The programs used to generate the Boost regression test status tables use the
! Filesystem Library extensively. See:</p>
! <ul>
! <li><a href="../../../tools/regression/process_jam_log.cpp">
! process_jam_log.cpp</a></li>
! <li><a href="../../../tools/regression/compiler_status.cpp">
! compiler_status.cpp</a></li>
! </ul>
! <p>Test programs are sometimes useful in understanding a library, as they
illustrate what the developer expected to work and not work. See:</p>
<ul>
***************
*** 176,186 ****
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.</p>
! <p><b><a name="path">path</a> </b>- A possibly empty sequence of names. 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 root 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
--- 207,217 ----
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.</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
***************
*** 190,194 ****
<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="name">name</a></b> - A file or directory name, without any
--- 221,225 ----
<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="name">name</a></b> - A file or directory name, without any
***************
*** 197,216 ****
operating systems, files and directories may have more than one valid name, such
as a short-form name and a long-form name.</p>
! <h2><a name="Requirements">Requirements</a></h2>
! <p>Unless otherwise specified, all Filesystem Library functions are required to
! throw a <i><a href="exception.htm">filesystem_error</a></i> exception if the
! implementation cannot successfully complete operations required to meet the
! function's specifications. Such exceptions are in addition to any exceptions
! specified in the function's "Throws" paragraph.</p>
! <p>Filesystem Library functions are permitted to call C++ Standard Library
! functions, so <i>std::bad_alloc</i> exceptions may also be thrown, unless
! otherwise specified.</p>
! <p>There is no rollback guarantee; a Filesystem Library function which throws an
! exception may leave the external file system in an altered state.</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 which have access to the filesystem. As an
! example of the difficulties this can cause, consider that the following asserts
may fail:</p>
<blockquote>
--- 228,288 ----
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, 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 the 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 referenced counted or non-reference counted.
! Non-reference counted links are sometimes called symbolic links or shortcuts.</p>
! <h2><a name="Common_Specifications">Common Specifications</a></h2>
! <p>Unless otherwise specified, all Filesystem Library member and non-member
! functions have the following common specifications:</p>
! <p><b>May throw exceptions</b> - Filesystem Library functions may throw <i><a href="exception.htm">filesystem_error</a></i>
! exceptions if they cannot successfully complete their operational
! specifications. Function 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><b>Exceptions thrown via <a href="../../utility/throw_exception.html">
! boost::throw_exception()</a></b> - 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><b>Links follow operating system rules</b>- <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">filesystem_error</a></i>
! exceptions if a link is cyclic or has other problems.</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>Rationale: Follows existing practice (POSIX, Windows, etc.).</p>
! <p><b>No atomic-operation or rollback guarantee</b> - 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 possible.</p>
! <p>Rationale: Implementors shouldn't be required to provide guarantees which are
! impossible to meet on some operating systems. Implementors should be given
! normative encouragement to provide those guarantees when possible.</p>
! <p><b>Graceful degradation</b> - 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 or throw an exception at runtime.</p>
! <p>Rationale: Implementations on less-powerful operating systems should provide
! useful functionality if possible, but should not be required to simulate
! features not present in the underlying operating system.</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>
***************
*** 247,279 ****
<li><a href="../test/fstream_test.cpp">fstream_test.cpp</a></li>
</ul>
! <p>As of September, 2002, these tests succeed for the following compilers on Windows:</p>
<ul>
! <li>Borland 5.5.1</li>
<li>GCC 3.1 (using POSIX implementation, but excluding wide-character fstream tests)</li>
<li>Intel 6.0</li>
! <li>Metrowerks 8.2</li>
<li>Microsoft 7.0</li>
<li>Microsoft 6.0 except fstream_test failed.</li>
</ul>
! <p>As of September, 2002, some limited use has been successful on Linux using
! GCC and IBM/AIX using Visual Age C++.</p>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
! <p>The Filesystem Library was designed and implemented by Beman Dawes, except
! for the <i>directory_iterator</i> and <i>filesystem_error</i> classes which were
! based on prior work from Dietmar Kühl, as modified by Jan Langer.</p>
<p>Key <a href="design.htm#Requirements">design requirements</a> and
! <a href="design.htm#Realities">design realities</a> were developed during extensive discussions on the Boost mailing list,
! followed by comments on the actual implementation. Participants included
! (in more-or-less chronological order) Beman Dawes, Jan Langer, Darin Adler, Michiel
! Salters, Jani Kajala, Jason Stewart, Carl Daniel, David Abrahams, Bill Kempf,
! Jonathan Caves, George Heintzelman, Ken Hagen, Eric Jensen, Joel de Guzman, Jim
! Hyslop, John Maddock, Matt Austern, Peter Dimov, Davlet Panech, Dylan Nicholson, Tom Harris,
! Giovanni Bajo, Baptiste Lepilleur, Thomas Witt, Keith Burton, Mattias Flodin,
! Daniel Frey, Vladimir Prus, Toon Knapen.</p>
!
! <p>Specific improvements for a preliminary design document came from Dan Nuffer and Jeff
! Garland.</p>
!
<p>A lengthy discussion on the C++ committee's library reflector illuminated the "illusion
of portability" problem, particularly in postings by JP Plauger and Pete Becker.</p>
--- 319,430 ----
<li><a href="../test/fstream_test.cpp">fstream_test.cpp</a></li>
</ul>
! <p>As of December, 2002, these tests succeed for the following compilers on Windows:</p>
<ul>
! <li>Borland 5.6</li>
<li>GCC 3.1 (using POSIX implementation, but excluding wide-character fstream tests)</li>
<li>Intel 6.0</li>
! <li>Metrowerks 8.3</li>
<li>Microsoft 7.0</li>
<li>Microsoft 6.0 except fstream_test failed.</li>
</ul>
! <p>As of December, 2002, limited use has been successful on Linux using GCC and IBM/AIX using Visual Age C++.</p>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
! <p>The Filesystem Library was designed and implemented by Beman Dawes. The <i>directory_iterator</i> and <i>filesystem_error</i> classes were
! based on prior work from Dietmar Kühl, as modified by Jan Langer. Thomas Witt
! was a particular help in later stages of development.</p>
<p>Key <a href="design.htm#Requirements">design requirements</a> and
! <a href="design.htm#Realities">design realities</a> were developed during
! extensive discussions on the Boost mailing list, followed by comments on the
! initial implementation. Numerous helpful comments were then received during the
! Formal Review.<p>Participants included
! Aaron Brashears,
! Alan Bellingham,
! Aleksey Gurtovoy,
! Alex Rosenberg,
! Alisdair Meredith,
! Andy Glew,
! Anthony Williams,
! Baptiste Lepilleur,
! Beman Dawes,
! Bill Kempf,
! Bill Seymour,
! Carl Daniel,
! Chris Little,
! Chuck Allison,
! Craig Henderson,
! Dan Nuffer,
! Dan'l Miller,
! Daniel Frey,
! Darin Adler,
! David Abrahams,
! David Held,
! Davlet Panech,
! Dietmar Kuehl,
! Douglas Gregor,
! Dylan Nicholson,
! Ed Brey,
! Eric Jensen,
! Eric Woodruff,
! Fedder Skovgaard,
! Gary Powell,
! Gennaro Prota,
! Geoff Leyland,
! George Heintzelman,
! Giovanni Bajo,
! Glen Knowles,
! Hillel Sims,
! Howard Hinnant,
! Jaap Suter,
! James Dennett,
! Jan Langer,
! Jani Kajala,
! Jason Stewart,
! Jeff Garland,
! Jens Maurer,
! Jesse Jones,
! Jim Hyslop,
! Joel de Guzman,
! Joel Young,
! John Levon,
! John Maddock,
! John Williston,
! Jonathan Caves,
! Jonathan Biggar,
! Jurko,
! Justus Schwartz,
! Keith Burton,
! Ken Hagen,
! Kostya Altukhov,
! Mark Rodgers,
! Martin Schuerch,
! Matt Austern,
! Matthias Troyer,
! Mattias Flodin,
! Michiel Salters,
! Mickael Pointier,
! Misha Bergal,
! Neal Becker,
! Noel Yap,
! Parksie,
! Patrick Hartling, Pavel Vozenilek,
! Pete Becker,
! Peter Dimov,
! Rainer Deyke,
! Rene Rivera,
! Rob Lievaart,
! Rob Stewart,
! Ron Garcia,
! Ross Smith,
! Sashan,
! Steve Robbins,
! Thomas Witt,
! Tom Harris,
! Toon Knapen,
! Victor Wagner,
! Vincent Finn,
! Vladimir Prus, and
! Yitzhak Sapir
!
<p>A lengthy discussion on the C++ committee's library reflector illuminated the "illusion
of portability" problem, particularly in postings by JP Plauger and Pete Becker.</p>
***************
*** 282,286 ****
<p>© Copyright Beman Dawes, 2002</p>
<p>Revised
! <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->13 September, 2002<!--webbot bot="Timestamp" endspan i-checksum="39336" --></p>
</body>
--- 433,437 ----
<p>© Copyright Beman Dawes, 2002</p>
<p>Revised
! <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->16 March, 2003<!--webbot bot="Timestamp" endspan i-checksum="28841" --></p>
</body>
Index: operations.htm
===================================================================
RCS file: /cvsroot/cpptool/rfta/deplib/boostcvs/libs/filesystem/doc/operations.htm,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** operations.htm 23 Oct 2002 20:22:49 -0000 1.1.1.1
--- operations.htm 1 Apr 2003 08:25:48 -0000 1.2
***************
*** 16,24 ****
<p><a href="#Introduction">Introduction</a><br>
<a href="#Synopsis">Header synopsis</a><br>
! <a href="#Class directory_iterator">Class directory_iterator</a><br>
<a href="#constructors">Constructors</a><br>
<a href="#destructor">Destructor</a><br>
! <a href="#other functions">Other functions</a><br>
! <a href="#Non-member functions">Non-member functions</a><br>
<a href="#exists">exists</a><br>
<a href="#is_directory">is_directory</a><br>
--- 16,24 ----
<p><a href="#Introduction">Introduction</a><br>
<a href="#Synopsis">Header synopsis</a><br>
! <a href="#directory_iterator">Class directory_iterator</a><br>
<a href="#constructors">Constructors</a><br>
<a href="#destructor">Destructor</a><br>
! <a href="#Other_functions">Other_functions</a><br>
! <a href="#Non-member_functions">Operations functions</a><br>
<a href="#exists">exists</a><br>
<a href="#is_directory">is_directory</a><br>
***************
*** 29,33 ****
<a href="#rename">rename</a><br>
<a href="#copy_file">copy_file</a><br>
! <a href="#initial_directory">initial_directory</a></p>
<h2><a name="Introduction">Introduction</a></h2>
--- 29,35 ----
<a href="#rename">rename</a><br>
<a href="#copy_file">copy_file</a><br>
! <a href="#initial_directory">initial_directory</a><br>
! <a href="#complete">complete</a><br>
! <a href="#system_complete">system_complete</a></p>
<h2><a name="Introduction">Introduction</a></h2>
***************
*** 43,49 ****
documentation</a>.</p>
! <p>As with all Filesystem Library components, errors may result in <i>
! <a href="exception.htm">filesystem_error</a></i> or <i>std::bad_alloc</i>
! exceptions being thrown. See <a href="index.htm#Requirements">Requirements</a>.</p>
<h2>Header <a href="../../../boost/filesystem/operations.hpp">boost/filesystem/operations.hpp</a>
--- 45,51 ----
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>
***************
*** 75,86 ****
void <a href="#create_directory">create_directory</a>( const path & directory_ph );
! void <a href="#remove">remove</a>( const path & ph );
unsigned long <a href="#remove_all">remove_all</a>( const path & ph );
void <a href="#rename">rename</a>( const path & from_path,
const path & to_path );
! void <a href="#copy_file">copy_file</a>( const path & from_file_ph,
! const path & to_file_ph );
! const path & <a href="#initial_directory">initial_directory</a>();
} // namespace filesystem
--- 77,92 ----
void <a href="#create_directory">create_directory</a>( const path & directory_ph );
! bool <a href="#remove">remove</a>( const path & ph );
unsigned long <a href="#remove_all">remove_all</a>( const path & ph );
void <a href="#rename">rename</a>( const path & from_path,
const path & to_path );
! void <a href="#copy_file">copy_file</a>( const path & source_file,
! const path & target_file );
! const path & <a href="#initial_path">initial_path</a>();
! path <a href="#current_path">current_path</a>();
! path <a href="#complete">complete</a>( const path & ph,
! const path & base = initial_path() );
! path <a href="#system_complete">system_complete</a>( const path & ph );
} // namespace filesystem
***************
*** 88,99 ****
</pre>
! <h2><a name="Class directory_iterator">Class directory_iterator</a></h2>
<p>Class <i>directory_iterator</i> provides a C++ standard conforming input
! iterator which accesses the contents of a <a href="reference.htm#directory">
directory</a>. </p>
<p>The value type is <i><a href="path.htm">boost::filesystem::path</a></i>, so
! dereferencing a <i>directory_iterator</i> yields a <a href="reference.htm#path">
path</a> to a file or directory contained within the directory represented by
the directory-path argument supplied at construction. The path returned by
--- 94,105 ----
</pre>
! <h2><a name="directory_iterator">Class directory_iterator</a></h2>
<p>Class <i>directory_iterator</i> provides a C++ standard conforming input
! iterator which accesses the contents of a <a href="index.htm#directory">
directory</a>. </p>
<p>The value type is <i><a href="path.htm">boost::filesystem::path</a></i>, so
! dereferencing a <i>directory_iterator</i> yields a <a href="index.htm#path">
path</a> to a file or directory contained within the directory represented by
the directory-path argument supplied at construction. The path returned by
***************
*** 133,139 ****
representing the first path in <i>directory_ph</i>, or if <code>
empty(directory_ph)</code>, the <i>past-the-end</i> value.</p>
</blockquote>
! <h3><a name="other functions">Other functions</a></h3>
<p>Class <i>directory_iterator</i> also supplies all the other functions
--- 139,150 ----
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(current_path())</code> rather than <code>directory_iterator("")</code>.</p>
</blockquote>
! <h3><a name="Other_functions">Other functions</a></h3>
<p>Class <i>directory_iterator</i> also supplies all the other functions
***************
*** 141,145 ****
<i>operator++</i>, and <i>operator*</i>.</p>
! <h2><a name="Non-member functions">Non-member functions</a></h2>
<p>
--- 152,156 ----
<i>operator++</i>, and <i>operator*</i>.</p>
! <h2><a name="Non-member_functions">Non-member functions</a></h2>
<p>
***************
*** 163,178 ****
<p>
! <b>Rationale:</b> Errors which might appear to be preconditions are not
! specified as such, but instead are specified to 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 should always be testable by a program, so that
! violations can be avoided. It is not always possible or desirable to abstract
! away the fact that the library is implemented by calls to the operating system,
! and this is one of those cases.</p>
<p>
<b>Naming Rationale:</b> See class <i>path</i>
! <a href="path.htm#Naming Rationale">Naming Rationale</a>.</p>
<h3><a name="exists">exists</a></h3>
--- 174,202 ----
<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 suffe...
[truncated message content] |
