Doc. no.	N4097
Date:	2014-07-05
Project:	Programming Language C++
Reply to:	Beman Dawes <bdawes at acm dot org>

File System TS Defect Report List (Revision R2)

Revised 2014-07-05 at 12:07:11 UTC

Reference ISO/IEC TS 18822

Also see:

Table of Contents for all SG3 issues.
Index by Section for all SG3 issues.
Index by Status for all SG3 issues.
Active Issues List
Closed Issues List

This document contains only SG3 issues which have been closed by the File System Study Group (SG3) after being found to be defects in the standard. That is, issues which have a status of DR, TC1, C++11, or Resolved. See the Closed Issues List for issues closed as non-defects. See the Active Issues List for active issues and more information. The introductory material in that document also applies to this document.

Revision History

R2: 2014-07-04 SG-3 File System TS
- Summary:
  - 6 open issues, down by 21.
  - 61 closed issues, up by 26.
  - 67 issues total, up by 5.
- Details:
  - Added the following 5 New issues: 64, 65, 66, 67, 68.
  - Changed the following issue to NAD Future (from New): 54.
  - Changed the following issue to NAD Future (from Open): 11.
  - Changed the following 3 issues to WP (from Review): 25, 27, 57.
  - Changed the following 13 issues to WP (from New): 34, 35, 36, 37, 40, 41, 45, 48, 49, 56, 58, 60, 62.
  - Changed the following 3 issues to WP (from Open): 5, 22, 53.
  - Changed the following issue to NAD Editorial (from New): 59.
  - Changed the following 3 issues to NAD (from New): 38, 42, 61.
  - Changed the following issue to NAD (from Open): 4.

Defect Reports

1. [PDTS] Make namespaces consistent with Library TS policy

Section: X All Status: WP Submitter: FI-5, US-5, GB-3, CH-6 Opened: 2014-01-20 Last modified: 2014-06-27

View all issues with WP status.

Discussion:

The PDTS used a placeholder namespace "tbs" since the Standard Library policy for TS namespaces had not yet been fully articulated.

[2014-02-11 Issaquah: Project editor to make indicated changes to WP, post notice on lib and SG3 reflectors.]

Proposed resolution:

[2014-02-07: Beman Dawes]

Throughout the WP, change namespace "tbs" to "experimental" as described in the Library Fundamentals TS working paper, 1.3 Namespaces and headers [general.namespaces].

2. [PDTS] Tighten specification when there is no reasonable behavior

Section: X 2.1 [fs.conform.9945] Status: WP Submitter: FI-1 Opened: 2014-01-20 Last modified: 2014-06-27

View all other issues in 2.1 [fs.conform.9945].

View all issues with WP status.

Discussion:

It is unfortunate that error reporting for inability to provide reasonable behaviour is completely implementation-defined. This hurts portability in the sense that programmers have no idea how errors will be reported and cannot anticipate anything.

Change "If an implementation cannot provide any reasonable behavior, the implementation shall report an error in an implementation-defined manner." to "If an implementation cannot provide any reasonable behavior, the code using the facilities for which reasonable behaviour cannot be provided shall be ill-formed." and strike the note.

[2014-02-07, Beman Dawes suggests wording]

[2014-02-12, Daniel Kr�gler comments:]

In our code bases we routinely have to target different filesystems, notably POSIX-based and Windows. While on Windows there is no meaning in setting the owner_exec permission, for example, this is required on POSIX systems when the corresponding file should be executable. Still, attempting to invoke this operation should be possible. It would be OK, if we got a defined runtime response to this, such as a specifically defined error code value that could be tested either via the error_code& overload, but it would be IMO unacceptable for end-users to tell them "Well, this code may not compile". I don't think that we can teach people that code written using the filesystem operations might or might not compile. It would be very valuable to have at least a clear indication that implementers are required to give a defined runtime-response if they do believe that this operation cannot be implemented resulting in "reasonable behaviour".

[2014-02-12, Proposed wording updated to reflect LWG/SG-3 discussion in Issaquah.

Since the standardese to carry out the LWG/SG-3 "throw or error code" intent is best achieved by reference to the Error reporting section, a note was added by the project editor. Please review carefully. ]

[2014-02-13 LWG/SG-3 Issaquah: Proposed wording accepted.]

Proposed resolution:

Change 2.1:

If an implementation cannot provide any reasonable behavior, the implementation shall report an error ~~in an implementation-defined manner~~ as specified in § 7 [fs.err.report]. [Note: This allows users to rely on an exception being thrown or an error code being set when an implementation cannot provide any reasonable behavior. — end note] .

3. [PDTS] Filename length needs bullet item

Section: X 4.7 [fs.def.filename] Status: WP Submitter: CH-2 Opened: 2014-01-20 Last modified: 2014-06-27

View all issues with WP status.

Discussion:

Filename lengths are also implementation dependent. This is not the same as FILENAME_MAX that specifies the maximum length of pathnames.

Add a bullet: "Length of filenames."

[2014-02-07, Beman Dawes provides wording]

Proposed resolution:

Change 4.7 [fs.def.filename]:

The name of a file. Filenames dot and dot-dot have special meaning. The following characteristics of filenames are operating system dependent:

The permitted characters. [Example: Some operating systems prohibit the ASCII control characters (0x00-0x1F) in filenames. — end example].
The maximum permitted length.
Filenames that are not permitted.
Filenames that have special meaning.
Case awareness and sensitivity during path resolution.
Special rules that may apply to file types other than regular files, such as directories.

5. [PDTS] Parent of root directory unspecified

Section: X 8.1 [path.generic] Status: WP Submitter: CH-4 Opened: 2014-01-20 Last modified: 2014-07-04

View all issues with WP status.

Discussion:

8.1 [path.generic] says: "The filename dot-dot is treated as a reference to the parent directory." So it must be specified what "/.." and "/../.." refer to.

Add a statement what the parent directory of the root directory is.

[2014-02-07, Beman Dawes suggests wording]

[ 2014-02-11 Issaquah: Implementation defined. See wiki notes for rationale. Beman to provide wording for review next meeting. ]

[ 22 May 2014 Beman provides wording, taken directly from POSIX. See pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_12 ]

Proposed resolution:

Change 8.1 [path.generic]:

The filename dot is treated as a reference to the current directory. The filename dot-dot is treated as a reference to the parent directory. What the filename dot-dot refers to relative to root-directory is implementation-defined. Specific filenames may have special meanings for a particular operating system.

6. [PDTS] Path depth is underspecified

Section: X 4.15 [fs.def.path] Status: WP Submitter: CH-5 Opened: 2014-01-20 Last modified: 2014-05-24

View all issues with WP status.

Discussion:

Path depth is implementation dependent.

Add a paragraph: "The maximum length of the sequence (i.e. the maximum depth) is implementation dependent.

[2014-02-07, Beman Dawes comments]

"implementaton defined" and "operating system dependent" are well defined terms in this TS, but "implementation dependent" is not well defined. The path depth is operating system dependent, so that's the form used in the proposed wording.

[2014-02-07, Beman Dawes provides wording]

Proposed resolution:

Change 4.15 [fs.def.path]:

4.15 path [fs.def.path]

A sequence of elements that identify the location of a file within a filesystem. The elements are the root-name_opt , root-directory_opt , and an optional sequence of filenames.

The maximum number of elements in the sequence is operating system dependent.

7. [PDTS] Unhelpful comment for `struct space_info`

Section: X 6 [fs.filesystem.synopsis], 15.32 [fs.op.space] Status: WP Submitter: GB-4 Opened: 2014-01-20 Last modified: 2014-05-24

View all issues with WP status.

Discussion:

Use of the term a 'non-privileged' process. The comment for available in the struct space_info refers to: free space available to a non-privileged process. This seems quite specific to a POSIX implementation (on Windows, for instance, the equivalent data would be user-specific but not directly related to privilege)

Remove the comment and add a note to 15.32 [fs.op.space]: [Note: the precise meaning of available space is implementation dependent. — end note]

[2014-02-07, Beman Dawes comments]

"implementaton defined" and "operating system dependent" are well defined terms in this TS, but "implementation dependent" is not well defined. The meaning of available is operating system dependent, so that's the form used in the proposed wording.

[2014-02-07, Beman Dawes provides wording]

Proposed resolution:

Change 6 [fs.filesystem.synopsis]:

uintmax_t available; // free space available to a non-privileged process
Add Remarks to 15.32 [fs.op.space]:

Remarks: The value of member space_info::available is operating system dependent. [Note: available may be less than free. — end note]

8. [PDTS] `file_time_type` underspecified

Section: X [fs.filesystem.synopsis] Status: WP Submitter: CH-7 Opened: 2014-01-20 Last modified: 2014-06-27

View all issues with WP status.

Discussion:

Must the file_time_type hold times before 1960 and after 2050?

Specify the requirements to unspecified-trivial-clock for file_time_type.

[2014-02-10, Daniel suggests wording]

[ 2014-02-11 Issaquah: (1)Implementation-defined. See wiki notes for rationale. (2) Leave other additions in place, but insert "the" before "resolution" (3) Strike "unspecified-" from "unspecified-trivial-type" in two places. Beman to provide wording for review next meeting. ]

[2014-02-13 LWG/SG-3 Issaquah: Proposed wording accepted.]

Proposed resolution:

Modify 6 [fs.filesystem.synopsis] as indicated:
```
    typedef chrono::time_point<unspecified-trivial-clock>  file_time_type;
  
```
~~unspecified-~~trivial-clock is an ~~unspecified type provided by the implementation~~ implementation-defined type that satisfies the TrivialClock requirements (~~C++11~~ISO 14882:2011 §20.12.3) and that is capable of representing and measuring file time values. Implementations should ensure that the resolution and range of file_time_type reflect the operating system dependent resolution and range of file time values.

9. [PDTS] Unclear why range-based-for functions return different types

Section: X 6 [fs.filesystem.synopsis] Status: WP Submitter: FI-2 Opened: 2014-01-20 Last modified: 2014-05-24

View all other issues in 6 [fs.filesystem.synopsis].

View all issues with WP status.

Discussion:

It is unclear why the range-for support functions (begin()/end()) for directory_iterator and recursive_directory_iterator return different types for begin() and end(), namely that begin() returns a reference to const and end() returns a value.

[2014-02-07: Beman Dawes provides comments from the Boost implementation:]

  //  begin() and end() are only used by a range-based for statement in the context of
  //  auto - thus the top-level const is stripped - so returning const is harmless and
  //  emphasizes begin() is just a pass through.

[2014-02-08: Daniel responds to Beman]

The difference in return types becomes relevant, when testing whether e.g. directory_iterator would satisfy the Traversable requirements as currently specified in N3763. Expressed in code form these requirements impose that the following assertion holds:

  static_assert(std::is_same<
      decltype(std::range_begin(std::declval<directory_iterator>())),
      decltype(std::range_end(std::declval<directory_iterator>()))
    >::value, "No Traversable type");

Both directory_iterator and recursive_directory_iterator won't satisfy this requirement currently.

[ 2014-02-11 Issaquah: Change begin() argument and return to pass-by-value. See wiki notes for rationale. Beman to provide wording for review next meeting. ]

[2014-02-13 LWG/SG-3 Issaquah: Proposed wording accepted.]

Proposed resolution:

Change 6 [fs.filesystem.synopsis]:

  class directory_iterator;

  // enable directory_iterator range-based for statements
  const directory_iterator& begin(const directory_iterator& iter) noexcept;
  directory_iterator end(const directory_iterator&) noexcept;

  class recursive_directory_iterator;

  // enable recursive_directory_iterator range-based for statements
  const recursive_directory_iterator& begin(const recursive_directory_iterator& iter) noexcept;
  recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;

Change 13.2 [directory_iterator.nonmembers]:

These functions enable use of directory_iterator with C++11 range-based for statements.
```
const directory_iterator& begin(constdirectory_iterator& iter) noexcept;
```
Returns: iter.
```
directory_iterator end(const directory_iterator&) noexcept;
```
Returns: directory_iterator().
Change 14.2 [rec.dir.itr.nonmembers]:

These functions enable use of recursive_directory_iterator with C++11 range-based for statements.
```
const recursive_directory_iterator& begin(constrecursive_directory_iterator& iter) noexcept;
```
Returns: iter.
```
recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
```
Returns: recursive_directory_iterator().

14. [PDTS] Incorrect postconditions for `path` copy/move constructor

Section: X 8.4.1 [path.construct] Status: WP Submitter: GB-7, CH-10 Opened: 2014-01-20 Last modified: 2014-05-24

View all other issues in 8.4.1 [path.construct].

View all issues with WP status.

Discussion:

The postconditions for the copy/move constructor for path are shown as "empty()". This appears to have been incorrectly copied from the default ctor.

Remove the 'postconditions' clause from the copy/move ctor.

[2014-02-07, Beman Dawes suggests wording]

Proposed resolution:

Change 8.4.1 [path.construct]:

      path(const path& p);
      path(path&& p) noexcept;
    
Effects: Constructs an object of class path with pathname having the original value of p.pathname. In the second form, p is left in a valid but unspecified state.

Postconditions: empty().

15. [PDTS] Missing behavior for characters with no representation

Section: X 8.2.2 [path.type.cvt], X 8.4.1 [path.construct] Status: WP Submitter: GB-8 Opened: 2014-01-20 Last modified: 2014-06-27

View all issues with WP status.

Discussion:

No specification for characters with no representation. The example at the end of 8.4.1 refers to "for other native narrow encodings some characters may have no representation" - what happens in such cases?

Suggested action:

Add some definition of the behaviour for characters with no representation.

[2014-02-12 Applied LWG/SG-3 Issaquah wording tweaks to make characters referred to plural.]

[2014-02-08, Beman Dawes provides wording]

Proposed resolution:

Add a paragraph at the end of 8.2.2 [path.type.cvt]:

If the encoding being converted to has no representation for source characters, the resulting converted characters, if any, are unspecified.

16. [PDTS] Append behavior underspecified if target is empty

Section: X 8.4.3 [path.append] Status: WP Submitter: CH-11 Opened: 2014-01-20 Last modified: 2014-06-27

View all issues with WP status.

Discussion:

Is the added separator redundant in p1 /= p2, where p1 is empty? I.e. does the result start with a separator?

Suggested action:

Specify what behaviour is required.

[2014-02-07: Beman Dawes comments]

The second bullet item is supposed to deal with the empty() condition.

[2014-02-12 LWG/SG-3 Issaquah: The text is correct as written, however adding a note will clarify this and address the NB comment.]

Proposed resolution:

Change 8.4.3 [path.append]:

Effects:

Appends path::preferred_separator to pathname unless:

an added separator would be redundant, or

would change an relative path to an absolute path [Note: An empty path is relative. — end note], or

p.empty(), or

*p.native().cbegin() is a directory separator.

Then appends p.native() to pathname.

18. [PDTS] `is_absolute()` return clause confusing

Section: X 8.4.10 [path.query] Status: WP Submitter: FI-7 Opened: 2014-01-20 Last modified: 2014-05-24

View all issues with WP status.

Discussion:

is_absolute says: "Returns: true if the elements of root_path() uniquely identify a file system location, else false." The "uniquely identify a location" seems confusing in presence of symlinks.

Suggested action:

Clarify the returns clause so that there's no confusion about symlinks and 'location'.

[2014-02-10 Beman Dawes provides wording]

Proposed resolution:

Change 8.4.10 path query [path.query]:

bool is_absolute() const;
Returns: true if ~~the elements of root_path() uniquely identify a file system location~~ pathname contains an absolute path (4.1 [fs.def.absolute-path]) , else false.

[Example: path("/").is_absolute() is true for POSIX based operating systems, and false for Windows based operating systems. — end example]

19. [PDTS] Consider using quoted manipulators

Section: X 8.6.1 [path.io] Status: WP Submitter: FI-8 Opened: 2014-01-20 Last modified: 2014-06-27

View all issues with WP status.

Discussion:

"[Note: Pathnames containing spaces require special handling by the user to avoid truncation when read by the extractor. — end note]" sounds like a quoted manipulator as specified in the C++14 draft in [quoted.manip] would be useful.

Consider using quoted manipulators for stream insertion and extraction.

[2014-02-10, Daniel suggests wording]

[2014-02-12 Applied LWG/SG-3 Issaquah wording tweak to use ISO doc number for reference to C++14.]

Proposed resolution:

Change 8.6.1 [path.io] as indicated:
```
template <class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os, const path& p);
```
Effects: os << quoted(p.string<charT, traits>()).
~~[Note: Pathnames containing spaces require special handling by the user to avoid truncation when read by the extractor. — end note]~~
[Note: The quoted function is described in ISO 14882:2014 �27.7.6. — end note]
Returns: os
```
template <class charT, class traits>
basic_istream<charT, traits>&
operator>>(basic_istream<charT, traits>& is, path& p);
```
Effects:
```
basic_string<charT, traits> tmp;
is >> quoted(tmp);
p = tmp;
```

21. [PDTS] `directory_entry operator==` needs clarification

Section: X 12.3 [directory_entry.obs] Status: WP Submitter: GB-12 Opened: 2014-01-20 Last modified: 2014-06-27

View all other issues in 12.3 [directory_entry.obs].

View all issues with WP status.

Discussion:

Since operator== for directory_entry does not check status, it would be worth highlighting that operator== only checks that the paths match.

Suggested action:

Add: [Note: does not include status values — end note]

[2014-02-09, Beman Dawes suggest wording]

[2014-02-13 LWG/SG-3 Issaquah: Proposed wording accepted. Typo /no/not/ fixed per suggestion.]

Proposed resolution:

To 12.3 [directory_entry.obs] operator== add:

[Note: Status members do not participate in determining equality. — end note]

22. [PDTS] `directory_iterator` underspecified

Section: X 13.1 [directory_iterator.members] Status: WP Submitter: CH-13 Opened: 2014-01-20 Last modified: 2014-07-04

View all issues with WP status.

Discussion:

The behaviour of increment is underspecified: What happens if the implementation detects an endless loop (e.g. caused by links)? What happens with automounting and possible race conditions?

More information on this can be found here.

Suggested action:

Specify the required behaviour in these cases.

[2014-02-13 LWG/SG-3 Issaquah: STL will provide wording for next meeting for the endless loop case. The other cases are covered by existing wording in the front matter.]

[17 Jun 2014 At the request of the LWG, Beman provides wording for a note.]

Proposed resolution:

In 14 Class recursive_directory_iterator [class.rec.dir.itr], add:

[Note: If the directory structure being iterated over contains cycles then the end iterator may be unreachable. --end note]

24. [PDTS] Incorrect effects clause for path `copy`

Section: X 15.3 [fs.op.copy] Status: WP Submitter: GB-14 Opened: 2014-01-20 Last modified: 2014-06-27

View all issues with WP status.

Discussion:

Incorrect effects clause for path copy — the effect clause for copy [fs.op.copy] includes "equivalent(f, t)" — there is no equivalent() function defined for variables of this type (file_status)

Suggested action:

Replace with "equivalent(from, to)"

[2014-02-09, Beman Dawes suggests wording]

[2014-02-13 LWG/SG-3 Issaquah: Proposed wording accepted.]

Proposed resolution:

Change 15.3 [fs.op.copy]:

Report an error as specified in Error reporting if:

!exists(f).

equivalent(f, t from, to).

is_other(f) || is_other(t).

is_directory(f) && is_regular_file(t).

25. [PDTS] Copying equivalent paths effects not specified

Section: X 15.4 [fs.op.copy_file] Status: WP Submitter: CH-15 Opened: 2014-01-20 Last modified: 2014-07-04

View all issues with WP status.

Discussion:

Even if to and from are different paths, they may be equivalent.

Specify what happens if (options & copy_options::overwrite_existing) but from and to resolve to the same file.

[2014-02-09, Beman Dawes: Need advice on this issue:]

What do existing implentations do?

Possible resolutions:

Treat it as an error.
Once equivalence is determined, take no further action and return true? false?
Don't bother to detect a file overwriting itself. This will likely result in an error, anyhow.

[2014-02-13 LWG/SG-3 Issaquah: LWG/SG-3 decided to treat equivalence in this case as an error. Beman to provide wording.]

[2014-04-09 Beman provided wording as requested. The Effects were rewritten to increase clarity. Behavior remains unchanged except for treating equivalence as an error.]

[17 Jun 2014 Rapperswil LWG moves to Immediate. Jonathan Wakely will provide editorial changes to improve the presentation of bitmask values.]

Proposed resolution:

Change 15.4 [fs.op.copy_file]:

Precondition: At most one constant from each copy_options option group ([enum.copy_options]) is present in options.

Effects:

If exists(to) && !(options & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options::update_existing)) report a file already exists error as specified in Error reporting (7).

If !exists(to) || (options & copy_options::overwrite_existing) || ((options & copy_options::update_existing) && last_write_time(from) > last_write_time(to)) || !(options & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options::update_existing)) copy the contents and attributes of the file from resolves to the file to resolves to.

Report a file already exists error as specified in Error reporting (7) if:

exists(to) and equivalent(from, to), or

exists(to) and (options & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options::update_existing)) == copy_options::none.

Otherwise copy the contents and attributes of the file from resolves to to the file to resolves to if:

!exists(to), or

exists(to) and (options & copy_options::overwrite_existing) != copy_options::none, or

exists(to) and (options & copy_options::update_existing) != copy_options::none and from is more recent than to, determined as if by use of the last_write_time function.

Otherwise no effects.

Returns: true if the from file was copied, otherwise false. The signature with argument ec return false if an error occurs.

Throws: As specified in Error reporting (7).

Complexity: At most one direct or indirect invocation of status(to).

27. [PDTS] Return value of `uintmax_t` on error?

Section: X 15.14 [fs.op.file_size] Status: WP Submitter: FI-9 Opened: 2014-01-20 Last modified: 2014-07-04

View all issues with WP status.

Discussion:

"The signature with argument ec returns static_cast<uintmax_t>(-1) if an error occurs.", one would expect that both signatures return that if an error occurs?

Clarify the Returns clause, and apply the same for every function that returns an uintmax_t where applicable.

[2014-02-13 LWG/SG-3 Issaquah:]

Discussion when around in circles for a while, until someone suggested the reference to 15.15 was wrong, and that the issue applied to the previous function in the WP, 15.14 File size [fs.op.file_size].

The NB Comment makes much more sense if it applies to file_size(), so the chair was directed to change the reference from 15.15 [fs.op.hard_lk_ct] to 15.14 [fs.op.file_size].

The intent that file_size() is only meaningful for regular_files. Beman to strike the the static_cast, changing it to "Otherwise an error is reported.".

Proposed resolution:

Change 15.14 [fs.op.file_size]:

uintmax_t file_size(const path& p);
uintmax_t file_size(const path& p, error_code& ec) noexcept;

Returns: If !exists(p) && || !is_regular_file(p) an error is reported (7). Otherwise, the size in bytes of the file p resolves to, determined as if by the value of the POSIX stat structure member st_size obtained as if by POSIX stat(). ~~Otherwise, static_cast<uintmax_t>(-1).~~ The signature with argument ec returns static_cast<uintmax_t>(-1) if an error occurs.

Throws: As specified in Error reporting (7).

29. [PDTS] Unclear semantics of `read_symlink` on error

Section: X 15.27 [fs.op.read_symlink] Status: WP Submitter: GB-16 Opened: 2014-01-20 Last modified: 2014-06-27

View all issues with WP status.

Discussion:

Unclear semantics of read_symlink on error: 15.27 [fs.op.read_symlink] has: Returns: If p resolves to a symbolic link, a path object containing the contents of that symbolic link. Otherwise path(). and also [Note: It is an error if p does not resolve to a symbolic link. -- end note]

I do not believe path() can be a valid return for the overload not taking error_code.

Strike "Otherwise path()."

[2014-02-09, Beman Dawes provides wording]

[2014-02-13 LWG/SG-3 Issaquah: Proposed wording accepted.]

Proposed resolution:

Change 15.27 [fs.op.read_symlink]:

Returns: If p resolves to a symbolic link, a path object containing the contents of that symbolic link. ~~Otherwise path().~~ The signature with argument ec returns path() if an error occurs.

Throws: As specified in Error reporting. [Note: It is an error if p does not resolve to a symbolic link. — end note]

32. [PDTS] `system_complete()` example needs clarification

Section: X 15.36 [fs.op.system_complete] Status: WP Submitter: FI-10 Opened: 2014-01-20 Last modified: 2014-06-27

View all issues with WP status.

Discussion:

"[Example: For POSIX based operating systems, system_complete(p) has the same semantics as complete(p, current_path())." What is this complete that is referred here?

Clarify the example.

[2014-02-10 Beman Dawes suggests wording]

[2014-02-13 LWG/SG-3 Issaquah: Proposed wording accepted.]

Proposed resolution:

Change 15.36 [fs.op.system_complete]:

[Example: For POSIX based operating systems, system_complete(p) has the same semantics as completeabsolute(p, current_path()).

33. [PDTS] `unique_path()` is a security vulnerability

Section: X 15.38 [fs.op.unique_path] Status: WP Submitter: CH-19 Opened: 2014-01-20 Last modified: 2014-06-27

View all issues with WP status.

Discussion:

unique_path() is a security vulnerability. As the Linux manual page for the similar function tmpnam() writes in the "BUGS" section: "Never use this function. Use mkstemp(3) or tmpfile(3) instead." mkstemp() and tmpfile() avoid the inherent race condition of unique_path() by returning an open file descriptor or FILE*.

[Beman Dawes comments: 10 Feb 2014:]

There are two issues here:

Confusion over what unique_path does and how it is used. The function is misleadingly named. These issue have arisen in the past, but apparently not been fully corrected. The suggested fix is to (1) rename the function and (2) provide an example of how to use the function safely with fstreams or even C I/O. See below for proposed wording.

Very real security concerns. See issue 54. The security concerns are probably best dealt with in the next File System TS, since a full-blown proposal is needed and will likely take several years to develop.

[ 2014-02-11 Issaquah: Strike the function. ]

[2014-02-12 The following Proposed resolution from CH-19 was moved here to avoid confusion with the final Proposed resolution wording from the WG/SG3.]

Remove this function. Consider providing a function create_unique_directory(). If it fits the scope of the proposed TS, consider providing functions create_unique_file() that returns ifstream, ofstream and iofstream.

[ 2014-02-12 The following Proposed wording was moved here to avoid confusion with the final Proposed resolution wording from the WG/SG3. ]

[2014-02-10 Beman Dawes]

Previous resolution from Beman [SUPERSEDED]:

Change 15.38 [fs.op.unique_path]:
    path unique_pathgenerate_random_filename(const path& model="%%%%-%%%%-%%%%-%%%%");
    path unique_pathgenerate_random_filename(const path& model, error_code& ec);
  
The unique_path generate_random_filename function generates a name suitable for temporary files, including directories. The name is based on a model that uses the percent sign character to specify replacement by a random hexadecimal digit.

[Note: The more bits of randomness in the generated name, the less likelihood of prior existence or being guessed. Each replacement hexadecimal digit in the model adds four bits of randomness. The default model thus provides 64 bits of randomness. --end note]

Returns: A path identical to model, except that each occurrence of the percent sign character is replaced by a random hexadecimal digit character in the range 0-9, a-f. The signature with argument ec returns path() if an error occurs.

Throws: As specified in Error reporting.

Remarks: Implementations are encouraged to obtain the required randomness via a cryptographically secure pseudo-random number generator, such as one provided by the operating system. [Note: Such generators may block until sufficient entropy develops. --end note]

Replace this example with one that opens a std::ofstream:
[Example:
        cout << unique_pathgenerate_random_filename("test-%%%%%%%%%%%.txt") << endl;
      
Typical output would be "test-0db7f2bf57a.txt". Because 11 hexadecimal output characters are specified, 44 bits of randomness are supplied. -- end example]

Proposed resolution:

Remove the two unique_path function signatures from 6 [fs.filesystem.synopsis].

Remove 15.38 [fs.op.unique_path] in its entirety.

[This removes all references the function from the working draft.]

34. [PDTS] `enum class directory_options` has no summary

Section: X 6 [fs.filesystem.synopsis] Status: WP Submitter: P.J. Plauger Opened: 2014-01-30 Last modified: 2014-07-04

View all other issues in 6 [fs.filesystem.synopsis].

View all issues with WP status.

Discussion:

enum class directory_options has no summary.

Proposed resolution:

Change 6 [fs.filesystem.synopsis]:

      enum class directory_options;
      {
      none,
      follow_directory_symlink,
      skip_permission_denied
      };

Add the following sub-section:

10.4 Enum class directory_options [enum.directory_options]

The enum class type directory_options is a bitmask type (C++11 §17.5.2.1.3) that specifies bitmask constants used to identify directory traversal options.

Name Value Meaning

none 0 (Default) Skip directory symlinks, permission denied is error.

follow_directory_symlink 1 Follow rather than skip directory symlinks.

skip_permission_denied 2 Skip directories that would otherwise result in permission denied errors.

35. [PDTS] `directory_options::skip_permission_denied` is not used

Section: X 6 [fs.filesystem.synopsis] Status: WP Submitter: P.J. Plauger Opened: 2014-01-30 Last modified: 2014-07-04

View all other issues in 6 [fs.filesystem.synopsis].

View all issues with WP status.

Discussion:

directory_options::skip_permission_denied is not used.

[2014-04-13 Beman: skip_permissions_denied not being used is a symptom of a more serious problem; two directory_itorator constructors are missing directory_options arguments and a description of how they are used. Proposed wording provided.]

[17 Jun 2014 LWG requests two signatures rather than one with default argument. Beman updates wording.]

Proposed resolution:

Change 13 [class.directory_iterator]:

      directory_iterator() noexcept;
      explicit directory_iterator(const path& p);
      directory_iterator(const path& p, directory_options options);
      directory_iterator(const path& p, error_code& ec) noexcept;
      directory_iterator(const path& p,
      directory_options options, error_code& ec) noexcept;
      directory_iterator(const directory_iterator&) = default;
      directory_iterator(directory_iterator&&) = default;
      ~directory_iterator();

Change 13.1 directory_iterator members [directory_iterator.members]:

      explicit directory_iterator(const path& p);
      directory_iterator(const path& p, directory_options options);
      directory_iterator(const path& p, error_code& ec) noexcept;
      directory_iterator(const path& p,
      directory_options options, error_code& ec) noexcept;
    
Effects: For the directory that p resolves to, constructs an iterator for the first element in a sequence of directory_entry elements representing the files in the directory, if any; otherwise the end iterator.

However, if options & directory_options::skip_permissions_denied != directory_options::none and construction encounters an error indicating that permission to access p is denied, constructs the end iterator and does not report an error.

Change 14 Class recursive_directory_iterator [class.rec.dir.itr] :

      explicit recursive_directory_iterator(const path& p,
      directory_options options = directory_options::none);
      recursive_directory_iterator(const path& p, directory_options options);
      recursive_directory_iterator(const path& p,
      directory_options options, error_code& ec) noexcept;
      recursive_directory_iterator(const path& p, error_code& ec) noexcept;

Change 14.1 recursive_directory_iterator members [rec.dir.itr.members]:

      explicit recursive_directory_iterator(const path& p,
      directory_options options = directory_options::none);
      recursive_directory_iterator(const path& p, directory_options options);
      recursive_directory_iterator(const path& p,
      directory_options options, error_code& ec) noexcept;
      recursive_directory_iterator(const path& p, error_code& ec) noexcept;
    
Effects: Constructs a iterator representing the first entry in the directory p resolves to, if any; otherwise, the end iterator.

However, if options & directory_options::skip_permissions_denied != directory_options::none and construction encounters an error indicating that permission to access p is denied, constructs the end iterator and does not report an error.

Change 14.1 recursive_directory_iterator members [rec.dir.itr.members]:

      recursive_directory_iterator& operator++();
      recursive_directory_iterator& increment(error_code& ec);
    
Requires: *this != recursive_directory_iterator().

Effects: As specified by C++11 § 24.1.1 Input iterators, except that:

If there are no more entries at this depth, then if depth()!= 0 iteration over the parent directory resumes; otherwise *this = recursive_directory_iterator().

Otherwise if recursion_pending() && is_directory(this->status()) && (!is_symlink(this->symlink_status()) || (options() & directory_options::follow_directory_symlink) != 0 directory_options::none) then either directory (*this)->path() is recursively iterated into or, if options() & directory_options::skip_permissions_denied != directory_options::none and an error occurs indicating that permission to access directory (*this)->path() is denied, then directory (*this)->path() is treated as an empty directory and no error is reported .

36. [PDTS] `copy_options::copy_symlinks` is not used

Section: X 10.2 [enum.copy_options] Status: WP Submitter: P.J. Plauger Opened: 2014-01-30 Last modified: 2014-07-04

View all other issues in 10.2 [enum.copy_options].

View all issues with WP status.

Discussion:

copy_options::copy_symlinks is not used (should test it before calling copy_symlinks in copy).

[20 May 2014 Beman Dawes provides proposed wording.]

Proposed resolution:

Change 15.3 Copy [fs.op.copy]:

If is_symlink(f), then:

If options & copy_options::skip_symlinks, then return. Missing != copy_options::none fixed by issue 59

Otherwise if !exists(t) && (options & copy_options::copy_symlinks) != copy_options::none, then copy_symlink(from, to, options).

Otherwise report an error as specified in Error reporting (7) .

37. [PDTS] All functions with `error_code` arguments should be `noexcept`

Section: X 15.2 [fs.op.canonical], X 15.11 [fs.op.current_path], X 15.27 [fs.op.read_symlink], X 15.36 [fs.op.system_complete], X 15.37 [fs.op.temp_dir_path], X 15.38 [fs.op.unique_path], X 8.4 [path.member] Status: WP Submitter: P.J. Plauger Opened: 2014-01-30 Last modified: 2014-07-04

View all issues with WP status.

Discussion:

all functions with error_code arguments should be noexcept (see canonical, current_path, read_symlink, system_complete, temp_directory_path, unique_path, plus member functions).

[2014-02-03: Stephan T. Lavavej comments:]

The declaration and definition of "recursive_directory_iterator& increment(error_code& ec);" should almost certainly be marked noexcept.

[2014-02-08: Daniel comments]

All functions that return a path value such as canonical, current_path, read_symlink, system_complete, temp_directory_path, unique_path, or any member function returning a path value or basic_string value might legally throw an exception, if the allocator of the underlying string complains about insufficient memory. This is an anti-pattern for noexcept, because the exception-specification includes the return statement of a function and given the fact that the language currently does declare RVO as an optional action, we cannot rely on it.

The Standard is currently very careful not to specify functions as noexcept, if this case can happen, see e.g. std::locale::name(). To the contrary, enforcing them to be noexcept, would cause a similar problem as the unconditional noexcept specifier of the value-returning kill_dependency as denoted by LWG 2236.

Basically this requirement conflicts with the section "Adopted Guidelines", second bullet of N3279.

[Beman Dawes 2014-02-27]

Issues 37, 38, 41, and 49 are concerned with signatures which should or should not be noexcept. I will provide unified proposed wording for these issues, possibly in a separate paper.

[21 May 2014 Beman Dawes reviewed all functions with error_code& arguments, and provided proposed wording for the one case found where the above guidelines were not met. This was the case previously identified by Stephan T. Lavavej. ]

Proposed resolution:

Change 14 Class recursive_directory_iterator [class.rec.dir.itr]:

recursive_directory_iterator& increment(error_code& ec) noexcept;

Change 14.1 recursive_directory_iterator members [rec.dir.itr.members]:

recursive_directory_iterator& increment(error_code& ec) noexcept;

40. [PDTS] `class directory_entry` should retain `operator const path&()` from V2

Section: X 12 [class.directory_entry] Status: WP Submitter: P.J. Plauger Opened: 2014-01-30 Last modified: 2014-07-04

View all other issues in 12 [class.directory_entry].

View all issues with WP status.

Discussion:

class directory_entry should retain operator const path&() from V2.

[2014-05-19 Beman Dawes supplied proposed wording.]

[2014-06-02 Beman Dawes provides rationale:]

This conversion operator was removed when status() and symlink_status() were added during the transition from V2 to V3 as it seemed a bit unusual to have a conversion operator for one of the several values held. Users complained as they had found the automatic conversion convenient in the most common directory_entry use case.

[17 Jun 2014 Rapperswil LWG discusses in depth, accepts proposed wording.]

Proposed resolution:

Change 12 Class directory_entry [class.directory_entry]:

// observers
const path&  path() const noexcept;
operator const path&() const noexcept;
file_status  status() const;
file_status  status(error_code& ec) const noexcept;
file_status  symlink_status() const;
file_status  symlink_status(error_code& ec) const noexcept;

Change 12.3 directory_entry observers [directory_entry.obs]:

const path& path() const noexcept;
operator const path&() const noexcept;

Returns: m_path

41. [PDTS] `directory_iterator`, `recursive_directory_iterator`, move construct/assign should be `noexcept`

Section: X 13 [class.directory_iterator], X 14 [class.rec.dir.itr] Status: WP Submitter: P.J. Plauger Opened: 2014-01-30 Last modified: 2014-07-04

View all other issues in 13 [class.directory_iterator].

View all issues with WP status.

Discussion:

class directory_iterator move construct/assign should be noexcept.
class recursive_directory_iterator move construct/assign should be noexcept.

[Beman Dawes 2014-02-27]

Issues 37, 38, 41, and 49 are concerned with signatures which should or should not be noexcept. I will provide unified proposed wording for these issues, possibly in a separate paper.

[Daniel Krügler 2014-02-28]

directory_iterator begin(directory_iterator iter) noexcept;
directory_iterator end(const directory_iterator&) noexcept;

are noexcept, but we have no guarantee that at least the move-constructor is noexcept:

directory_iterator(const directory_iterator&) = default;
directory_iterator(directory_iterator&&) = default;

This means that either the above noexcept specifications are not warranted or that at least the move-constructor of directory_iterator is required to be noexcept.

The same applies to recursive_directory_iterator.

[21 May 2014 Beman Dawes provided proposed resolution wording.]

[18 Jun 2014 "= default" removed per LWG discussion]

Proposed resolution:

Change 13 Class directory_iterator [class.directory_iterator]:

directory_iterator(const directory_iterator& rhs) = default;
directory_iterator(directory_iterator&& rhs) noexcept = default;
...
directory_iterator& operator=(const directory_iterator& rhs) = default;
directory_iterator& operator=(directory_iterator&& rhs) noexcept = default;

To 13.1 directory_iterator members [directory_iterator.members] add:

directory_iterator(const directory_iterator& rhs);
directory_iterator(directory_iterator&& rhs) noexcept;
Effects: Constructs an object of class directory_iterator.

Postconditions: *this has the original value of rhs.
directory_iterator& operator=(const directory_iterator& rhs);
directory_iterator& operator=(directory_iterator&& rhs) noexcept;
Effects: If *this and rhs are the same object, the member has no effect.

Postconditions: *this has the original value of rhs.

Returns: *this.

Change 14 Class recursive_directory_iterator [class.rec.dir.itr]:

recursive_directory_iterator(const recursive_directory_iterator& rhs) = default;
recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept = default;
...
recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs) = default;
recursive_directory_iterator& operator=(recursive_directory_iterator&& rhs) noexcept = default;

To 14.1 recursive_directory_iterator members [rec.dir.itr.members] add:

recursive_directory_iterator(const recursive_directory_iterator& rhs);
Effects: Constructs an object of class recursive_directory_iterator.

Postconditions: this->options() == rhs.options() && this->depth() == rhs.depth() && this->recursion_pending() == rhs.recursion_pending().
recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
Effects: Constructs an object of class recursive_directory_iterator.

Postconditions: this->options(), this->depth(), and this->recursion_pending() return the values that rhs.options(), rhs.depth(), and rhs.recursion_pending(), respectively, had before the function call.
recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs);
Effects: If *this and rhs are the same object, the member has no effect.

Postconditions: this->options() == rhs.options() && this->depth() == rhs.depth() && this->recursion_pending() == rhs.recursion_pending().

Returns: *this.
recursive_directory_iterator& operator=(recursive_directory_iterator&& rhs) noexcept;
Effects: If *this and rhs are the same object, the member has no effect.

Postconditions: this->options(), this->depth(), and this->recursion_pending() return the values that rhs.options(), rhs.depth(), and rhs.recursion_pending(), respectively, had before the function call.

Returns: *this.

44. [PDTS] enum classes `copy_options` and `perms` should be bitmask types

Section: X 10.2 [enum.copy_options], X 10.3 [enum.perms] Status: WP Submitter: P.J. Plauger Opened: 2014-01-30 Last modified: 2014-06-27

View all other issues in 10.2 [enum.copy_options].

View all issues with WP status.

Discussion:

enum classes copy_options and perms should be bitmask types.

[2014-02-08 Daniel comments and suggests wording]

Since both enum types contain enumeration values that denote the value zero, they are currently not allowed to be described as bitmask types. This issue depends on LWG issue 1450, which — if it would be accepted — would allow for applying this concept to these enumeration types.

[2014-02-13 LWG/SG-3 Issaquah: Proposed wording accepted.]

Proposed resolution:

This wording is relative to SG3 working draft and assumes that LWG 1450 has been resolved.

Change [enum.copy_options] as indicated:

~~This enumeration~~The enum class type copy_options is a bitmask type (C++11 §17.5.2.1.3) that specifies bitmask constants used to control the semantics of copy operations. The constants are specified in option groups. […]
Change [enum.perms] as indicated:

~~This enumeration~~The enum class type perms is a bitmask type (C++11 §17.5.2.1.3) that specifies bitmask constants used to identify file permissions.

45. [PDTS] `create_directory` should refer to `perms::all` instead of Posix `S_IRWXU|S_IRWXG|S_IRWXO`

Section: X 15.7 [fs.op.create_directory] Status: WP Submitter: P.J. Plauger Opened: 2014-01-30 Last modified: 2014-07-04

View all issues with WP status.

Discussion:

create_directory should refer to perms::all instead of the Posix S_IRWXU|S_IRWXG|S_IRWXO.

[2014-02-28 Beman provided proposed wording.]

Proposed resolution:

Effects: Establishes the postcondition by attempting to create the directory p resolves to, as if by POSIX mkdir() with a second argument of ~~S_IRWXU|S_IRWXG|S_IRWXO~~ static_cast<int>(perms::all). Creation failure because p resolves to an existing directory shall not be treated as an error.

47. [PDTS] `last_write_time()` uses ill-formed cast

Section: X 15.25 [fs.op.last_write_time] Status: WP Submitter: P.J. Plauger Opened: 2014-01-30 Last modified: 2014-06-27

View all other issues in 15.25 [fs.op.last_write_time].

View all issues with WP status.

Discussion:

In last_write_time, static_cast<file_time_type>(-1) is ill formed, (possibly should be chrono<unspecified-trivial-clock>::from_time_t(-1)).

[2014-02-08 Daniel comments and provides wording]

I agree that the current wording needs to be fixed, but it is unclear to me whether invoking from_time_t (which is only guaranteed to exist for std::chrono::system_clock) with a value of time_t(-1) is a well-defined operation. Reason is that the C Standard makes a difference between a calendar time and the value time_t(-1) as an error indication. But the specification of system_clock::from_time_t only says "A time_point object that represents the same point in time as t […]" and it is not clear whether time_t(-1) can be considered as a "point in time". Instead of relying on such a potentially subtle semantics of the conversion result of time_t(-1) to std::chrono::system_clock::time_point with a further conversion to file_time_type (which in theory could led to overflow or underflow and thus another potential source of undefined behaviour), I suggest to change the current error value of last_write_time to one of the well-define limiting values of file_time_type, e.g. file_time_type::min().

[2014-02-13 LWG/SG-3 Issaquah: Proposed wording accepted.]

Proposed resolution:

This wording is relative to SG3 working draft.

Change the last write time prototype specification, 15.25 [fs.op.last_write_time], as indicated:
```
file_time_type last_write_time(const path& p);
file_time_type last_write_time(const path& p, error_code& ec) noexcept;
```
Returns: The time of last data modification of p, determined as if by the value of the POSIX stat structure member st_mtime obtained as if by POSIX stat(). The signature with argument ec returns static_cast<file_time_type>(-1)file_time_type::min() if an error occurs.

48. [PDTS] `path::template<class charT>string()` conversion rules

Section: X 8.4.6 [path.native.obs] Status: WP Submitter: P.J. Plauger Opened: 2014-01-30 Last modified: 2014-07-04

View all issues with WP status.

Discussion:

path::template<class charT>string() should promise to convert by the same rules as u16string for string<char16_t>, etc. and one-for-one otherwise.

What if charT is signed char (or even float)? I don't see where that choice is disallowed, so we should either disallow it or make it be something that is quasi-sensible.

[2014-02-08 Daniel comments]

There are two relevant places in the wording that seem to clarify what is required here:

Most importantly, 5 [fs.req] says:

Throughout this Technical Specification, char, wchar_t, char16_t, and char32_t are collectively called encoded character types.
Template parameters named charT shall be one of the encoded character types.
[…] [Note: Use of an encoded character type implies an associated encoding. Since signed char and unsigned char have no implied encoding, they are not included as permitted types. — end note]
For both the mentioned string function template and the specific non-template functions (such as u16string()) the same Remarks element exists, that refers to character conversion:

Conversion, if any, is performed as specified by 8.2 [path.cvt].

The first quote excludes arbitrary types such as signed char or float as feasible template arguments. The second quote makes clear that both the function template and the non-template functions do normatively refer to the same wording in 8.2 [path.cvt].

Based on this interpretation of the issue discussion I recommend resolving it as NAD.

In addition to that recommendation I recommend to rename the current usage of the symbol charT in this technical specification, because 5 [fs.req] assigns a very special meaning to the constraints on charT types that does not exist to this extend in the rest of the standard library. A similar approach is used in Clause 22, where a special symbol C is used for constrained character types (C++11 §22.3.1.1.1 [locale.category]):

A template formal parameter with name C represents the set of types containing char, wchar_t, and any other implementation-defined character types that satisfy the requirements for a character on which any of the iostream components can be instantiated.

[2014-02-28 Beman provides proposed resolution wording]

[18 Jun 2014 Beman changes proposed name from C to EcharT in response to tentative vote concern that C was insuficiently informative as a name.]

Proposed resolution:

In the entire Working Paper, except in the synopsis for path inserter and extractor and 8.6.1 path inserter and extractor [path.io], change each instance of "charT" to "EcharT".

For example, in 5 [fs.req]:

Template parameters named ~~charT~~ EcharT shall be one of the encoded character types.

49. [PDTS] `path` and `directory_entry` move ctors should not be `noexcept`

Section: X 8.4.1 [path.construct], X 12 [class.directory_entry] Status: WP Submitter: Stephan T. Lavavej Opened: 2014-02-03 Last modified: 2014-07-04

View all other issues in 8.4.1 [path.construct].

View all issues with WP status.

Discussion:

path's move ctor is marked noexcept, but it contains a basic_string. Similarly, directory_entry's move ctor is marked noexcept, but it contains a path. This is affected by LWG 2319 "basic_string's move constructor should not be noexcept".

[Beman Dawes 2014-02-27]

Issues 37, 38, 41, and 49 are concerned with signatures which should or should not be noexcept. I will provide unified proposed wording for these issues, possibly in a separate paper.

[21 May 2014 Beman Dawes provides wording. See LWG 2319 for rationale. ]

[19 Jun 2014 LWG revises P/R to stay consistent with LWG issues.]

Proposed resolution:

Change 8 Class path [class.path]:

path() noexcept;

Change 8.4.1 path constructors [path.construct]:

path() noexcept;

Change 12 Class directory_entry [class.directory_entry]:

directory_entry() noexcept = default;

50. [PDTS] `path::compare(const string& s)` wrong argument type

Section: X 8 [class.path] Status: WP Submitter: Stephan T. Lavavej Opened: 2014-02-03 Last modified: 2014-06-27

View all other issues in 8 [class.path].

View all issues with WP status.

Discussion:

path has "int compare(const string& s) const;" but it should almost certainly take const string_type&, since the third overload takes const value_type*.

[2014-02-08 Daniel comments and provides wording]

This issue is the same as 43 and resolves that issue as well.

[2014-02-13 LWG/SG-3 Issaquah: Proposed wording accepted.]

Proposed resolution:

This wording is relative to SG3 working draft.

Change class path synopsis, 8 [class.path], as indicated:

// compare
int compare(const path& p) const noexcept;
int compare(const string_type& s) const;
int compare(const value_type* s) const;

Change path compare prototype specification, 8.4.8 [path.compare], as indicated:
```
int compare(const string_type& s) const;
```

52. [PDTS] Better to avoid deriving from `std::iterator`

Section: X 13 [class.directory_iterator], X 14 [class.rec.dir.itr] Status: WP Submitter: Stephan T. Lavavej Opened: 2014-02-03 Last modified: 2014-06-27

View all other issues in 13 [class.directory_iterator].

View all issues with WP status.

Discussion:

Although the Standard has made this mistake almost a dozen times, I recommend not depicting directory_iterator and recursive_directory_iterator as deriving from std::iterator, since that's a binding requirement on implementations. Instead they should be depicted as having the appropriate typedefs, and leave it up to implementers to decide how to provide them. (The difference is observable to users with is_base_of, not that they should be asking that question.)

[2014-02-08 Daniel comments and provides wording]

This issue is basically similar to the kind of solution that had been used to remove the requirement to derive from unary_function and friends as described by N3198 and I'm strongly in favour to follow that spirit here as well. I'd like to add that basically all "newer" iterator types (such as the regex related iterator don't derive from std::iterator either.

Another reason to change the current specification is the fact that it currently says that the member types pointer and reference would be determined to value_type* and value_type& (that is mutable pointers and references), which conflicts with the specification of the return types of the following members:

const directory_entry& operator*() const;
const directory_entry* operator->() const;

The proposed fording fixes this by correcting these typedef to corresponding const access.

The very same objections had been expressed by issue 51 and the below given wording resolves this issue as well.

[2014-02-13 LWG/SG-3 Issaquah: Proposed wording accepted.]

Proposed resolution:

This wording is relative to SG3 working draft.

Change class directory_iterator synopsis, [class.directory_iterator], as indicated:

namespace std { namespace tbd { namespace filesystem {

      class directory_iterator :
        public iterator<input_iterator_tag, directory_entry>
      {
      public:
        typedef directory_entry        value_type;
        typedef ptrdiff_t              difference_type;
        typedef const directory_entry* pointer;
        typedef const directory_entry& reference;
        typedef input_iterator_tag     iterator_category;

        // member functions
        […]
      };

} } }  // namespaces std::tbd::filesystem

Change class recursive_directory_iterator synopsis, [class.rec.dir.itr], as indicated:

namespace std { namespace tbd { namespace filesystem {

      class recursive_directory_iterator :
        public iterator<input_iterator_tag, directory_entry>
      {
      public:
        typedef directory_entry        value_type;
        typedef ptrdiff_t              difference_type;
        typedef const directory_entry* pointer;
        typedef const directory_entry& reference;
        typedef input_iterator_tag     iterator_category;

        // constructors and destructor
        […]
        
        // modifiers
        recursive_directory_iterator& operator=(const recursive_directory_iterator&) = default;
        recursive_directory_iterator& operator=(recursive_directory_iterator&&) = default;
        
        const directory_entry& operator*() const;
        const directory_entry* operator->() const;

        recursive_directory_iterator& operator++();
        recursive_directory_iterator& increment(error_code& ec);

        […]
      };

} } }  // namespaces std::tbd::filesystem

53. [PDTS] `directory_entry` multithreading concerns

Section: X 12 [class.directory_entry] Status: WP Submitter: Stephan T. Lavavej Opened: 2014-02-03 Last modified: 2014-07-04

View all other issues in 12 [class.directory_entry].

View all issues with WP status.

Discussion:

12 [class.directory_entry] depicts directory_entry as having mutable m_status and m_symlink_status data members. This is problematic because of C++11's multithreading guarantees, which say that const member functions are simultaneously callable. As a result, mutable data members must be protected with synchronization, which was probably not considered during this design. The complexity and expense may be acceptable in directory_entry (since it can save filesystem queries, apparently) but it would be very very nice to have a note about this.

[2014-02-13 LWG/SG-3 discussed in Issaquah: Beman and STL will work together to better understand the concerns, and to formulate a solution. This is not a blocking issue for finishing the TS, but is a blocking issue for merging into the IS]

[2014-04-17 Beman provides proposed wording]

[2014-06-19 Rapperswil LWG decides to remove mutable private members. Beman provides wording.]

Proposed resolution:

Change 12 [class.directory_entry] as indicated:

    namespace std { namespace experimental { namespace filesystem { inline namespace v1 {

    class directory_entry
    {
    public:

    // constructors and destructor
    directory_entry() = default;
    directory_entry(const directory_entry&) = default;
    directory_entry(directory_entry&&) noexcept = default;
    explicit directory_entry(const path& p);
    explicit directory_entry(const path& p, file_status st=file_status(),
      file_status symlink_st=file_status());
    ~directory_entry();

    // modifiers
    directory_entry& operator=(const directory_entry&) = default;
    directory_entry& operator=(directory_entry&&) noexcept = default;
    void assign(const path& p);
    void assign(const path& p, file_status st=file_status(),
      file_status symlink_st=file_status());
    void replace_filename(const path& p);
    void replace_filename(const path& p, file_status st=file_status(),
      file_status symlink_st=file_status());

    // observers
    const path&  path() const noexcept;
    file_status  status() const;
    file_status  status(error_code& ec) const noexcept;
    file_status  symlink_status() const;
    file_status  symlink_status(error_code& ec) const noexcept;

    bool operator< (const directory_entry& rhs) const noexcept;
    bool operator==(const directory_entry& rhs) const noexcept;
    bool operator!=(const directory_entry& rhs) const noexcept;
    bool operator<=(const directory_entry& rhs) const noexcept;
    bool operator> (const directory_entry& rhs) const noexcept;
    bool operator>=(const directory_entry& rhs) const noexcept;
    private:
    path                 m_path;           // for exposition only
    mutable file_status  m_status;         // for exposition only; stat()-like
    mutable file_status  m_symlink_status; // for exposition only; lstat()-like
    };

    } } } }  // namespaces std::experimental::filesystem::v1

A directory_entry object stores a path object, ~~a file_status object for non-symbolic link status, and a file_status object for symbolic link status~~. ~~The file_status objects act as value caches.~~

[Note: Because status()on a pathname may be a relatively expensive operation, some operating systems provide status information as a byproduct of directory iteration. Caching such status information can result in significant time savings. Cached and non-cached results may differ in the presence of file system races. —end note]

12.1 `directory_entry` constructors [directory_entry.cons]

Add the description of this constructor in its entirety:

explicit directory_entry(const path& p);

Effects: Constructs an object of type directory_entry
Postcondition: path() == p.

explicit directory_entry(const path& p, file_status st=file_status(),
    file_status symlink_st=file_status());

Strike the description

12.2 `directory_entry` modifiers [directory_entry.mods]

Add the description of this function in its entirety:

void assign(const path& p);

Postcondition: path() == p.

void assign(const path& p, file_status st=file_status(),
  file_status symlink_st=file_status());

Strike the description

Add the description of this function in its entirety:

void replace_filename(const path& p);

Postcondition: path() == x.parent_path() / p where x is the value of path() before the function is called.

void replace_filename(const path& p, file_status st=file_status(),
  file_status symlink_st=file_status());

Strike the description

12.3 `directory_entry` observers [directory_entry.obs]

const path& path() const noexcept;

Returns: m_path

file_status status() const;
file_status status(error_code& ec) const noexcept;

Effects: As if,
if (!status_known(m_status))
{
  if (status_known(m_symlink_status) && !is_symlink(m_symlink_status))
    { m_status = m_symlink_status; }
  else { m_status = status(m_path[, ec]); }
}
Returns: m_status status(path()[, ec]).

Throws: As specified in Error reporting (7).

file_status  symlink_status() const;
file_status  symlink_status(error_code& ec) const noexcept;

Effects: As if,
        if (!status_known(m_symlink_status))
        {
        m_symlink_status = symlink_status(m_path[, ec]);
        }
Returns: m_symlink_status symlink_status(path()[, ec]).

Throws: As specified in Error reporting (7).

bool operator==(const directory_entry& rhs) const noexcept;

Returns: m_path == rhs.m_path.

~~[Note: Status members do not participate in determining equality. — end note]~~

bool operator!=(const directory_entry& rhs) const noexcept;

Returns: m_path != rhs.m_path.

bool operator< (const directory_entry& rhs) const noexcept;

Returns: m_path < rhs.m_path.

bool operator<=(const directory_entry& rhs) const noexcept;

Returns: m_path <= rhs.m_path.

bool operator> (const directory_entry& rhs) const noexcept;

Returns: m_path > rhs.m_path.

bool operator>=(const directory_entry& rhs) const noexcept;

Returns: m_path >= rhs.m_path.

55. [PDTS] Clarify Error reporting

Section: X 7 [fs.err.report] Status: WP Submitter: Beman Dawes Opened: 2014-01-20 Last modified: 2014-06-27

View all issues with WP status.

Discussion:

The proposed change below was suggested in Issaquah as part of the resolution of issue 13 to clarify the Error reporting section. LWG/SG3 liked the change, but since issue 13 was NAD requested that a separate issue be opened.

[2014-02-13 LWG/SG-3 Issaquah: Proposed wording accepted.]

Proposed resolution:

Change 7 [fs.err.report]:

Functions not having an argument of type error_code& report errors as follows, unless otherwise specified:

When a call by the implementation to an operating system or other underlying API results in an error that prevents the function from meeting its specifications, an exception of type filesystem_error shall be thrown. For functions with a single path argument, that argument shall be passed to the filesystem_error constructor with a single path argument. For functions with two path arguments, the first of these arguments shall be passed to the filesystem_error constructor as the path1 argument, and the second shall be passed as the path2 argument. The filesystem_error constructor's error_code argument is set as appropriate for the specific operating system dependent error.

Failure to allocate storage is reported by throwing an exception as described in C++11 § 17.6.4.10.

Destructors throw nothing.

Functions having an argument of type error_code& report errors as follows, unless otherwise specified:

If a call by the implementation to an operating system or other underlying API results in an error that prevents the function from meeting its specifications, the error_code& argument is set as appropriate for the specific operating system dependent error. Otherwise, clear() is called on the error_code& argument.

56. [PDTS] Feature test macro for TS version

Section: X 5 [fs.req] Status: WP Submitter: Clark Nelson Opened: 2014-02-10 Last modified: 2014-07-04

View all issues with WP status.

Discussion:

SD-6: SG10 Feature Test Recommendations recommends that each library header provide feature test macros. For Technical Specifications, the TS itself should specify recommended names for the feature test macros.

[Beman Dawes 2014-02-28 provided the proposed resolution. Thanks to Vicente J. Botet Escriba, Richard Smith, and Clark Nelson for suggestions and corrections.]

Proposed resolution:

Add a new sub-section:

5.2 Feature test macros [fs.req.macros]

This macro allows users to determine which version of this Technical Specification is supported by header <experimental/filesystem>.

Header <experimental/filesystem> shall supply the following macro definition:
#define __cpp_lib_experimental_filesystem     201406
[Note: The value of macro __cpp_lib_experimental_filesystem is yyyymm where yyyy is the year and mm the month when the version of the Technical Specification was completed. — end note]

57. [PDTS] Inappropriate use of "No diagnostic is required"

Section: X 2.1 [fs.conform.9945] Status: WP Submitter: LWG/SG-3 Opened: 2014-02-13 Last modified: 2014-07-04

View all other issues in 2.1 [fs.conform.9945].

View all issues with WP status.

Discussion:

§ 2.1 [fs.conform.9945] specifes "No diagnostic is required" for races. That prescription is used by the standard for the core language; it is not appropriate in library specifications. LWG/SG-3 wishes this be changed to undefined behavior.

[Beman comments: The replacment wording is similar to that used by C++14 17.6.4.10]

Proposed resolution:

Change the following paragraph from § 2.1 [fs.conform.9945]

~~The behavior of functions described in this Technical Specification may differ from their specification in the presence of file system races ([fs.def.race]). No diagnostic is required.~~
Behavior is undefined if calls to functions provided by this Technical Specification introduce a file system race (4.6 [fs.def.race]).

Insert a new sub-section head before the modified paragraph:

2.1 File system race behavior [fs.race.behavior]

58. [PDTS] POSIX `utime()` is obsolescent

Section: X 15.25 [fs.op.last_write_time] Status: WP Submitter: LWG/SG-3 Opened: 2014-02-13 Last modified: 2014-07-04

View all other issues in 15.25 [fs.op.last_write_time].

View all issues with WP status.

Discussion:

POSIX now says: "Since the utimbuf structure only contains time_t variables and is not accurate to fractions of a second, applications should use the utimensat() function instead of the obsolescent utime() function."

Suggested resolution: Rewrite the last_write_time setter description to utilize utimensat() or similar.

[20 May 2014 Beman Dawes supplies proposed wording. He comments:]

POSIX supplies two functions, futimens() and utimensat(), as replacements for utime(). futimens() is appropriate for the current TS. utimensat() will be appropriate for a future File System TS that adds the functionality of the whole family of POSIX *at() functions.

Proposed resolution:

Change 15.25 Last write time [fs.op.last_write_time]:

Effects: Sets the time of last data modification of the file resolved to by p to new_time, as if by POSIX ~~stat() followed by POSIX utime()~~ futimens() .

60. [PDTS] Incorrect Throws specification for `absolute()`

Section: X 15.1 [fs.op.absolute] Status: WP Submitter: Daniel Krügler Opened: 2014-02-28 Last modified: 2014-07-04

View all issues with WP status.

Discussion:

The Throws element [fs.op.absolute] says:

"If base.is_absolute() is true, throws only if memory allocation fails."

We can strike:

"If base.is_absolute() is true," and the wording will still hold. Note that:

None of the involved functions has requirements.

In *every* case potentially memory allocation occurs, even for "return p", so this allocation can fail.

[02-03-2014 Beman Dawes comments and provides P/R]

The Throws element should follow the same form as similar Throws elements in the TS. There isn't enough special about this function to justify special wording and by referencing Error reporting (7) we ensure absolute() follows the overall policy for handling memory allocation failures.

Proposed resolution:

[Change 15.1 [fs.op.absolute]:]

Throws: ~~If base.is_absolute() is true, throws only if memory allocation fails.~~ As specified in Error reporting (7).

62. Allocator requirements unspecified

Section: X 5 Requirements [fs.req] Status: WP Submitter: Daniel Krügler Opened: 2014-05-19 Last modified: 2014-07-04

View all issues with WP status.

Discussion:

The SG3 WP refers in several places to a template parameter named "Allocator" but does not impose requirements on this type.

Proposed resolution:

Add the following to 5 Requirements [fs.req]:

Template parameters named Allocator shall meet the C++ Standard's library Allocator requirements (C++11 §17.6.3.5)

Name	Value	Meaning
`none`	`0`	(Default) Skip directory symlinks, permission denied is error.
`follow_directory_symlink`	`1`	Follow rather than skip directory symlinks.
`skip_permission_denied`	`2`	Skip directories that would otherwise result in permission denied errors.

File System TS Defect Report List (Revision R2)

Revision History

Defect Reports

1. [PDTS] Make namespaces consistent with Library TS policy

2. [PDTS] Tighten specification when there is no reasonable behavior

3. [PDTS] Filename length needs bullet item

5. [PDTS] Parent of root directory unspecified

6. [PDTS] Path depth is underspecified

7. [PDTS] Unhelpful comment for struct space_info

8. [PDTS] file_time_type underspecified

9. [PDTS] Unclear why range-based-for functions return different types

14. [PDTS] Incorrect postconditions for path copy/move constructor

15. [PDTS] Missing behavior for characters with no representation

16. [PDTS] Append behavior underspecified if target is empty

18. [PDTS] is_absolute() return clause confusing

19. [PDTS] Consider using quoted manipulators

21. [PDTS] directory_entry operator== needs clarification

22. [PDTS] directory_iterator underspecified

24. [PDTS] Incorrect effects clause for path copy

25. [PDTS] Copying equivalent paths effects not specified

27. [PDTS] Return value of uintmax_t on error?

29. [PDTS] Unclear semantics of read_symlink on error

32. [PDTS] system_complete() example needs clarification

33. [PDTS] unique_path() is a security vulnerability

34. [PDTS] enum class directory_options has no summary

10.4 Enum class directory_options [enum.directory_options]

35. [PDTS] directory_options::skip_permission_denied is not used

36. [PDTS] copy_options::copy_symlinks is not used

37. [PDTS] All functions with error_code arguments should be noexcept

40. [PDTS] class directory_entry should retain operator const path&() from V2

41. [PDTS] directory_iterator, recursive_directory_iterator, move construct/assign should be noexcept

44. [PDTS] enum classes copy_options and perms should be bitmask types

45. [PDTS] create_directory should refer to perms::all instead of Posix S_IRWXU|S_IRWXG|S_IRWXO

47. [PDTS] last_write_time() uses ill-formed cast

48. [PDTS] path::template<class charT>string() conversion rules

49. [PDTS] path and directory_entry move ctors should not be noexcept

50. [PDTS] path::compare(const string& s) wrong argument type

52. [PDTS] Better to avoid deriving from std::iterator

53. [PDTS] directory_entry multithreading concerns

12.1 directory_entry constructors [directory_entry.cons]

12.2 directory_entry modifiers [directory_entry.mods]

12.3 directory_entry observers [directory_entry.obs]

55. [PDTS] Clarify Error reporting

56. [PDTS] Feature test macro for TS version

57. [PDTS] Inappropriate use of "No diagnostic is required"

58. [PDTS] POSIX utime() is obsolescent

60. [PDTS] Incorrect Throws specification for absolute()

62. Allocator requirements unspecified

7. [PDTS] Unhelpful comment for `struct space_info`

8. [PDTS] `file_time_type` underspecified

14. [PDTS] Incorrect postconditions for `path` copy/move constructor

18. [PDTS] `is_absolute()` return clause confusing

21. [PDTS] `directory_entry operator==` needs clarification

22. [PDTS] `directory_iterator` underspecified

24. [PDTS] Incorrect effects clause for path `copy`

27. [PDTS] Return value of `uintmax_t` on error?

29. [PDTS] Unclear semantics of `read_symlink` on error

32. [PDTS] `system_complete()` example needs clarification

33. [PDTS] `unique_path()` is a security vulnerability

34. [PDTS] `enum class directory_options` has no summary

10.4 Enum class `directory_options` [enum.directory_options]

35. [PDTS] `directory_options::skip_permission_denied` is not used

36. [PDTS] `copy_options::copy_symlinks` is not used

37. [PDTS] All functions with `error_code` arguments should be `noexcept`

40. [PDTS] `class directory_entry` should retain `operator const path&()` from V2

41. [PDTS] `directory_iterator`, `recursive_directory_iterator`, move construct/assign should be `noexcept`

44. [PDTS] enum classes `copy_options` and `perms` should be bitmask types

45. [PDTS] `create_directory` should refer to `perms::all` instead of Posix `S_IRWXU|S_IRWXG|S_IRWXO`

47. [PDTS] `last_write_time()` uses ill-formed cast

48. [PDTS] `path::template<class charT>string()` conversion rules

49. [PDTS] `path` and `directory_entry` move ctors should not be `noexcept`

50. [PDTS] `path::compare(const string& s)` wrong argument type

52. [PDTS] Better to avoid deriving from `std::iterator`

53. [PDTS] `directory_entry` multithreading concerns

12.1 `directory_entry` constructors [directory_entry.cons]

12.2 `directory_entry` modifiers [directory_entry.mods]

12.3 `directory_entry` observers [directory_entry.obs]

58. [PDTS] POSIX `utime()` is obsolescent

60. [PDTS] Incorrect Throws specification for `absolute()`