|Project:||Programming Language C++|
|Reply-to:||Beman Dawes <bdawes at acm dot org>|
This paper proposes a filesystem library component suitable for a C++ Standard Library Technical Specification or for the C++ Standard Library. The proposed library is based on Version 3 of the Boost Filesystem Library (see www.boost.org/libs/filesystem). Preliminary wording is provided. A TODO list identifies remaining work to be done.
Material in this document high-lighted in yellow is known to be incomplete, incorrect, or otherwise require further refinement.
D????=12-???? , Filesystem Library Proposal (Revision 3). Changes include:
N3365=12-0055, Filesystem Library Proposal (Revision 2). Changes include:
std::tbd::filesystemper issue 1 discussion in Kona.
N3335=12-0025, Filesystem Library for C++11/TR2 (Revision 1). Changes include:
filesas an experiment. Made this issue number 1 so the LWG can pass judgment.
N3239 = 11-0009, Filesystem Library Update for TR2 (Preliminary), reflected changes made to the Boost library version 3 since the previously accepted committee paper:
pathhandles all aspects of internationalization, replacing the previous template and its
wpathinstantiations. Character types
char32_tare supported. This is a major simplification of the path abstraction, particularly for functions that take path arguments. This change was based on a suggestion by Peter Dimov.
error_codeis now uniform throughout the operations functions.
N1975 = 06-0045, Filesystem Library Proposal for TR2 (Revision 3), was adopted by the committee in April, 2006, at the Berlin meeting. Shortly afterward the Library Working Group set aside work on TR2 to concentrate on C++0x.
The motivation and scope for a filesystem library were described in N1975, and are not repeated here. A minor scope reduction is that an addition to the current C++ runtime library is no longer needed.
Boost Filesystem Version 3 introduced a single path type that interoperates well with both
basic_string and user defined string types. Thus the following Design
alternatives paragraph is no long applicable:
Single path type which can at runtime accept narrow or wide character pathnames. Although certainly interesting, and possibly superior, such a design would not interoperate well with the current Standard Library's compile-time typed
basic_string. A new runtime polymorphic string class would be the best place to experiment with this concept, not a path class.
char32_tsupport to verify the specification for these is correct.
Sourceis not specified as actually implemented. Expose
copy_directoryneed to be reviewed, revised, tested, peer reviewed.
chrono system_clock::time_point, per LWG discussion in Kona.
Gray-shaded italic text is commentary on the proposal. It is not to be added to the working paper.
This clause describes components that perform operations on file systems and their components, such as paths, regular files, and directories.
ISO/IEC 9945 contains provisions which, through reference in this text, constitute provisions of this clause. At the time of publication, the editions indicated were valid. All standards are subject to revision, and parties to agreements based on this clause are encouraged to investigate the possibility of applying the most recent editions of the standard indicated below. Members of IEC and ISO maintain registers of currently valid International Standards.
ISO/IEC 9945:2003 is also IEEE Std 1003.1-2001, and The Open Group Base Specifications, Issue 6, and is also known as The Single Unix® Specification, Version 3. It is available from each of those organizations, and may be read online or downloaded from www.unix.org/single_unix_specification/
End of new Clause.
The N3335 proposal places the library in namespace
Rationale for a sub-namespace is that the library uses several names that don't
seem appropriate for namespace
tr2 since full standardization would
then put the names into
std. The function names
rename are of particular concern because these functions differ
in behavior from current standard library functions with those names. It also
doesn't seem desirable to preempt names like
Kona: Strong support for
filesystem as the library's
namespace. Strong support for a technical specification namespace that alerts uses that
contents are likely to change if and when they later get moved into the
No decision yet on a TR namespace;
tbs being used as
a placeholder. Thus the full namespace is changed to
const codecvt_type&arguments Status: Open
Users sometimes need to do path conversions that use something other than the
imbued codecvt facet. The need is particularly acute in multi-threaded
applications where changing the imbued facet would introduce a data race. That
said, providing an optional
const codecvt_type& argument for every
function where the need might possibly arise is excessive because its use is so
rare and it adds considerable interface clutter.
Remove all existing class path
Beman to pursue separate encoding conversion functionality, per Thursday N3336 "Adapting standard library strings and IO to a Unicode World" discussion. See Kona wiki.
If a separate encoding conversion facility isn't possible, then some form of minimal class path encoding conversion facility will be needed. But..., the LWG would like to see use cases and clearer explanation of motivation before deciding on specifics, and be very sure that there is no way to achieve with existing std library functionality, albeit with some loss of efficiency.
In Bloomington there was discussion of "implicit cast to implicit cast to native OS type to inter operate with existing iostream library and native functions instead of modifying fstream".
Kona: The Dinkumware/Microsoft implementation has added an implicit conversion to the string type, eliminating any need to modify fstream. (Discussion: might be safer to make the implicit conversion protected, then make fstream classes friends).
Action: Beman to investigate, test, as avoiding modification of existing header and classes is much desired.
The issue title pretty much says it all.
Kona: Return plain strings. Remove the permission for implementations to return const refs, since uses are not in performace critical code and subtle portability bugs may occur.
Action: Beman to apply to proposed wording.
Version 3: Resolution applied.
Question raised by Pablo in Bloomington.
Beman suggests NAD, Future. I've done some work on this, including looking at systems like OpenVMS that have an escape mechanism to handle otherwise unrepresentable characters. There was a comment to that effect in N3239. I believe it should be deferred to some future release since (1) it is complex enough that I'd like to see actual implementation and use experience (presumably via Boost), and (2) I can't recall a user ever requesting such a feature.
Kona: No consensus for change, since there doesn't appear to be any compelling use case.
Question raised by a committee member in private email.
Kona: Much discussion.
Action: Alisdair to write paper, based on a real implementation, so that it is possible to assess the impact on interface, performance, etc.
Post-Kona: Alisdair will defer paper until after TR.
path currently is specified to used the Boost detail
quoted stream manipulator. A path object is inserted delimited by quotes,
and extracted accordingly, ensuring that paths containing spaces are
round-tripped correctly. Quotes in the path itself are escaped, and io
state is saved and restored.
Since the standard can't specify behavior in terms of something in Boost, we
have to change the specification. Since the
manipulator is a handy little component, the issue is raised as to whether it
should go in TR2.
Kona: Specify the path inserter and extractor to have the desired behavior without reference to how it is achieved. (If someone wants to propose a quoted manipulator, that's a separate proposal for a different TR.)
Action: Beman to apply to proposed wording.
Version 3: Resolution applied.
There are minor problems with the name of the
Change the name of the
rename() function to
$endid $id backmatter= $endid