@@ -237,7 +238,7 @@ those features along with suggested replacements.
is_regular(file_status f)
- is_regular_file(file_status f)
+ is_regular_file(file_status f)
@@ -341,7 +342,7 @@ happen. Depending on the user to call initial_path() at the
beginning of main() is too error prone. An equivalent
function can trivially be provided by a user.
-
+
Be able to write portable script-style filesystem operations in modern
- C++.
-
+ C++.
+
Rationale: This is a common programming need. It is both an
embarrassment and a hardship that this is not possible with either the current
C++ or Boost libraries. The need is particularly acute
@@ -53,31 +53,31 @@ of choice..
languages. All operating systems provide some form of API for filesystem
operations, and the POSIX bindings are increasingly available even on
operating systems not normally associated with POSIX, such as the Mac, z/OS,
- or OS/390.
+ or OS/390.
Work within the realities described below.
+
Rationale: This isn't a research project. The need is for something that works on
today's platforms, including some of the embedded operating systems
with limited file systems. Because of the emphasis on portability, such a
library would be much more useful if standardized. That means being able to
work with a much wider range of platforms that just Unix or Windows and their
- clones.
+ clones.
Avoid dangerous programming practices. Particularly, all-too-easy-to-ignore error notifications
- and use of global variables. If a dangerous feature is provided, identify it as such.
-
+ and use of global variables. If a dangerous feature is provided, identify it as such.
+
Rationale: Normally this would be covered by "the usual Boost requirements...",
but it is mentioned explicitly because the equivalent native platform and
scripting language interfaces often depend on all-too-easy-to-ignore error
notifications and global variables like "current
- working directory".
+ working directory".
Structure the library so that it is still useful even if some functionality
does not map well onto a given platform or directory tree. Particularly, much
useful functionality should be portable even to flat
-(non-hierarchical) filesystems.
-
+(non-hierarchical) filesystems.
+
Rationale: Much functionality which does not
require a hierarchical directory structure is still useful on flat-structure
filesystems. There are many systems, particularly embedded systems,
@@ -86,32 +86,32 @@ of choice..
Interface smoothly with current C++ Standard Library input/output
facilities. For example, paths should be
- easy to use in std::basic_fstream constructors.
-
+ easy to use in std::basic_fstream constructors.
+
Rationale: One of the most common uses of file system functionality is to
manipulate paths for eventual use in input/output operations.
- Thus the need to interface smoothly with standard library I/O.
+ Thus the need to interface smoothly with standard library I/O.
Suitable for eventual standardization. The implication of this requirement
is that the interface be close to minimal, and that great care be take
- regarding portability.
-
+ regarding portability.
+
Rationale: The lack of file system operations is a serious hole
in the current standard, with no other known candidates to fill that hole.
Libraries with elaborate interfaces and difficult to port specifications are much less likely to be accepted for
- standardization.
+ standardization.
Encourage, but do not require, portability in path names.
-
+
Encourage, but do not require, portability in path names.
+
Rationale: For paths which originate from user input it is unreasonable to
- require portable path syntax.
+ require portable path syntax.
Avoid giving the illusion of portability where portability in fact does not
- exist.
-
+ exist.
+
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
@@ -122,68 +122,68 @@ of choice..
Some operating systems have a single directory tree root, others have
- multiple roots.
+ multiple roots.
-
Some file systems provide both a long and short form of filenames.
+
Some file systems provide both a long and short form of filenames.
Some file systems have different syntax for file paths and directory
- paths.
+ paths.
Some file systems have different rules for valid file names and valid
- directory names.
+ directory names.
Some file systems (ISO-9660, level 1, for example) use very restricted
- (so-called 8.3) file names.
+ (so-called 8.3) file names.
Some operating systems allow file systems with different
characteristics to be "mounted" within a directory tree. Thus an
ISO-9660 or Windows
- file system may end up as a sub-tree of a POSIX directory tree.
+ file system may end up as a sub-tree of a POSIX directory tree.
Wide-character versions of directory and file operations are available on some operating
- systems, and not available on others.
+ systems, and not available on others.
There is no law that says directory hierarchies have to be specified in
- terms of left-to-right decent from the root.
+ terms of left-to-right decent from the root.
Some file systems have a concept of file "version number" or "generation
- number". Some don't.
+ number". Some don't.
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:
-
- DISK$SCRATCH:[GEORGE.PROJECT1.DAT]BIG_DATA_FILE.NTP;5
-
- The general OpenVMS format is:
-
+ might look something like this:
+
+ DISK$SCRATCH:[GEORGE.PROJECT1.DAT]BIG_DATA_FILE.NTP;5
+
+ The general OpenVMS format is:
+
- Device:[directories.dot.separated]filename.extension;version_number
+ Device:[directories.dot.separated]filename.extension;version_number
For common file systems, determining if two descriptors are for same
entity is extremely difficult or impossible. For example, the concept of
equality can be different for each portion of a path - some portions may be
case or locale sensitive, others not. Case sensitivity is a property of the
pathname itself, and not the platform. Determining collating sequence is even
- worse.
+ worse.
Race-conditions may occur. Directory trees, directories, files, and file attributes are in effect shared between all threads, processes, and computers which have access to the
filesystem. That may well include computers on the other side of the
world or in orbit around the world. This implies that file system operations
- may fail in unexpected ways. For example:
-
+ may fail in unexpected ways. For example:
+ assert( exists("foo") == exists("foo") );
- // may fail!
+ // may fail!
assert( is_directory("foo") == is_directory("foo");
- // may fail!
-
+ // may fail!
+
In the first example, the file may have been deleted between calls to
exists(). In the second example, the file may have been deleted and then
- replaced by a directory of the same name between the calls to is_directory().
+ replaced by a directory of the same name between the calls to is_directory().
Even though an application may be portable, it still will have to traffic
in system specific paths occasionally; user provided input is a common
- example.
+ example.
Symbolic links cause canonical and
normal form of some paths to represent different files or directories. For
@@ -315,7 +315,7 @@ Page,
Available from each of the organizations involved in its creation. For
example, read online or download from
- www.unix.org/single_unix_specification/. The ISO JTC1/SC22/WG15 - POSIX
+ www.unix.org/single_unix_specification/. The ISO JTC1/SC22/WG15 - POSIX
homepage is
www.open-std.org/jtc1/sc22/WG15/
@@ -338,7 +338,7 @@ Variable Considered Harmful, ACM SIGPLAN Notices, 8, 2, 1973, pp. 23-34
-
+
Use, modification, and distribution are subject to the Boost Software
diff --git a/doc/do_list.html b/doc/do_list.html
index 6f4d4f4..431dbd2 100644
--- a/doc/do_list.html
+++ b/doc/do_list.html
@@ -1,10 +1,10 @@
