$id frontmatter=
Document number: N3335=12-0025
Date: 2012-01-13
Project: Programming Language C++, Library Working Group
Reply-to: Beman Dawes <bdawes at acm dot org>

Filesystem Library for C++11/TR2 (Revision 1)

This paper proposes that the filesystem library component of C++ Standard Library Technical Report 2 be 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.

Revision history

N3335=12-0025, Filesystem Library for C++11/TR2 (Revision 1). Changes include:

N3239 = 11-0009, Filesystem Library Update for TR2 (Preliminary), reflected changes made to the Boost library version 3 since the previously accepted committee paper:

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.

Motivation and Scope

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.

TODO

$endid $id wording_prefix=

Proposed Wording

Gray-shaded italic text is commentary on the proposal. It is not to be added to the TR.

Add the following to the Technical Report's front matter:

The following standard contains provisions which, through reference in this text, constitute provisions of this Technical Report. At the time of publication, the editions indicated were valid. All standards are subject to revision, and parties to agreements based on this Technical Report 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, with the indicated corrections, is hereinafter called POSIX.

Footnote 1: POSIX® is a registered trademark of The IEEE.

Footnote 2: UNIX® is a registered trademark of The Open Group.

Add the following to the Technical Report as a new Clause:

Filesystem Library

$endid $id wording_suffix=

End of new Clause.

Modify File streams [fstreams] as follows:

To class basic_filebuf public members add:

basic_filebuf<charT,traits>* open(const path& p, std::ios_base::openmode mode);

To class basic_ifstream public members add:

explicit basic_ifstream(const path& p, std::ios_base::openmode mode=std::ios_base::in)
void open(const path& p, std::ios_base::openmode mode=std::ios_base::in);

To class basic_ofstream public members add:

explicit basic_ofstream(const path& p, std::ios_base::openmode mode=std::ios_base::out);
void open(const path& p, std::ios_base::openmode mode=std::ios_base::out);

To class basic_fstream public members add:

explicit basic_fstream(const path& p,
  std::ios_base::openmode mode=std::ios_base::in | std::ios_base::out);
void open(const path& p,
  std::ios_base::openmode mode=std::ios_base::in | std::ios_base::out);

End of proposed wording.


Issues List


Issue 1: What is the appropriate namespace?

Discussion

The proposal places the library in namespace std::tr2::$SUBNAMESPACE;. 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 remove and 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 equivalent and status.

The Boost Filesystem library used namespace boost::filesystem, but that always seemed a bit too long.

Proposed resolution

Status quo. Leave in namespace std::tr2::$SUBNAMESPACE;.


Issue 2: Excessive use of const codecvt_type& arguments

Discussion

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.

Proposed resolution

Remove all existing class path const codecvt_type& arguments.

Add an additional non-member function:

unspecified-iterator-type convert(const path& p, const codecvt_type& codecvt);

Returns: An unspecified iterator type whose value type is path::value_type. The returned iterator points to the beginning of a sequence equivalent to p.native() with encoding as specified by codecvt.


Issue 3: Possible "implicit cast to native type"?

Discussion

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".

Beman comments: I wasn't in Bloomington and am not sure of the context of the above. N3239 inadvertently included the Boost docs for <fstream> rather than suggested <fstream> changes for TR2, and that may have caused some confusion. Or maybe I'm just missing something from the wiki notes. Some further discussions are needed to better define the issue.

Proposed resolution


Issue 4: Given move semantics, it is best not to return const strings.

Discussion

The issue title pretty much says it all.

Proposed resolution

As part of the C++11 refinements to the interface, review returns of const strings and change to plain strings where appropriate.


Issue 5: Is there a way to handle characters that are illegal for particular OS?

Discussion

Question raised by Pablo in Bloomington.

Proposed resolution

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.


Issue 6: Could allocator support be class path?

Discussion

Question raised by a committee member in private email.

Comment from Beman: How would allocator support work, given that class path is not a template?

Proposed resolution


$endid $id backmatter= $endid