Boost Filesystem FAQ

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 either the native operating system format (Unix and Windows) or via a operating system supplied POSIX library (z/OS, OS/390, and many more.)

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.

Why isn't path a base class with derived directory_path and file_path classes?

Why bother? The behavior of all three classes is essentially identical. Several early versions did require users to identify each path as a file or directory path, and this seemed to increase errors and decrease code readability. There was no apparent upside benefit.

To avoid long-held assumptions (what do you mean, "/foo" isn't 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.

To alert users that the results are inherently non-portable. The names are deliberately ugly to discourage use except where really necessary.

Why not support a concept of specific kinds of file systems, such as posix_file_system or windows_file_system?

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.

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?

Why not supply a 'handle' type, and let the file and directory operations traffic in it?

It isn't clear there is any feasible way to meet the "portable script-style file system operations" requirement with such a system. File systems exist where operations are usually performed on some non-string handle type. The classic Mac OS has been mentioned explicitly as a case where trafficking in paths isn't always natural.

The case for the "handle" (opaque data type to identify a file) 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.

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.

Meaningful Names for Arguments
Argument Intent	Meaningful name if directories are files	Meaningful name if directories aren't files
A path to either a directory or a non-directory	path	path
A path to a directory, but not to a non-directory	directory_path	directory_path
A path to a non-directory, but not a directory	non_directory_path	file_path

The problem is that when directories are considered files, non_directory_path as an argument name, and the corresponding "non-directory path" in documentation, is ugly and lengthy, and so is shortened to just path, 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.

An extended attempt to add convenience functions on top of, or as a replacement for, the low-level functionality failed because there is no widely acceptable set of simple semantics for most convenience functions considered. Attempts to provide alternate semantics, via either run-time options or compile-time polices, became overly complicated in relation to the value delivered, or became contentious. OTOH, the specific functionality needed for several trial applications was very easy for the user to construct from the lower-level toolkit functions. See Failed Attempts.

Yes, but experience with both this library, POSIX, and Windows indicates the utility of certain convenience functions, and that it is possible to provide simple, yet widely acceptable, semantics for them. For example, remove_all.

Safety. The default is to be safe rather than sorry. This is particularly important given the reality that on many computer systems files and directories are globally shared resources, and thus subject to unexpected errors.

Why are errors reported by exception rather than return code or error notification variable?

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.

For a few commonly used attributes (existence, directory or file, emptiness), simple syntax and guaranteed presence outweigh other considerations. Because access to virtually all other attributes is inherently system dependent, property maps are viewed as the best hope for access and modification, but it is better design to provide such functionality in a separate library. (Historical note: even the apparently simple attribute "read-only" turned out to be so system depend as to be disqualified as a "guaranteed presence" operation.)

Global variables are considered harmful [wulf-shaw-73]. 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.

Why aren't there query functions for compound conditions like existing_directory?

After several attempts, named queries for multi-attribute proved a slippery-slope; where do you stop?

Why aren't wide-character names supported? Why not std::wstring or even a templated type?

Wide-character names would provide an illusion of portability where portability does not in fact exist. Behavior would be completely different on operating systems (Windows, for example) that support wide-character names, than on systems which don't (POSIX). Providing functionality that appears to provide portability but in fact delivers only implementation-defined behavior is highly undesirable. Programs would not even be portable between library implementations on the same operating system, let alone portable to different operating systems.

The C++ standards committee Library Working Group discussed this in some detail both on the committee's library reflector and at the Spring, 2002, meeting, and feels that (1) names based on types other than char are extremely non-portable, (2) there are no agreed upon semantics for conversion between wide-character and narrow-character names for file systems which do not support wide-character name, and (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.

[October, 2002 - PJ Plauger has suggested a locale based conversion scheme. Others have indicated support for such an experiment.]

Why are file and directory name portability errors detected automatically when these aren't actually errors in some applications?

For many uses, automatic portability error detection based on the generic path grammar is a sensible default. For cases where some other error check (including no check at all) is preferred for the entire application, functionality is provided to change the default. For cases where some other error check (including no check at all) is preferred for a particular path, the error check can be specified in the path constructor.

The error checking functions call also be explicitly called. That provides yet another way to check for errors.

The design makes error checking easy and automatic for common cases, yet provides explicit control when that is required.

Why isn't more powerful name portability error detection provided, such as deferring checking until a path is actually used?

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 isn't important enough to justify added a lot of additional complexity.

Why are paths sometimes manipulated by member functions and sometimes by non-member functions?

The design rule is that purely lexical operations are supplied as class path member functions, while operations performed by the operating system are provided as free functions.

On operating systems such as POSIX which allow symbolic links to directories, the normalized form of a path can represent a different location than the canonical form. See use case from Walter Landry.