[filesystems] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpwnztb6_i/{from.md → to.md} +192 -109

tmp/tmpwnztb6_i/{from.md → to.md} RENAMED Viewed

@@ -326,26 +326,29 @@ namespace std::filesystem {
   path weakly_canonical(const path& p);
   path weakly_canonical(const path& p, error_code& ec);
 }
   // [fs.path.hash], hash support
-namespace std {
   template<class T> struct hash;
   template<> struct hash<filesystem::path>;
 }
 namespace std::ranges {
   template<>
-    inline constexpr bool enable_borrowed_range<filesystem::directory_iterator> = true;
   template<>
-    inline constexpr bool enable_borrowed_range<filesystem::recursive_directory_iterator> = true;
   template<>
-    inline constexpr bool enable_view<filesystem::directory_iterator> = true;
   template<>
-    inline constexpr bool enable_view<filesystem::recursive_directory_iterator> = true;
 }
 ```
 Implementations should ensure that the resolution and range of
 `file_time_type` reflect the operating system dependent resolution and
@@ -435,12 +438,12 @@ Pathnames are formatted according to the generic pathname format grammar
 *Pathname resolution* is the operating system dependent mechanism for
 resolving a pathname to a particular file in a file hierarchy. There may
 be multiple pathnames that resolve to the same file.
-[*Example 1*: POSIX specifies the mechanism in section 4.12, Pathname
-resolution. — *end example*]
 ``` cpp
 namespace std::filesystem {
   class path {
   public:
@@ -523,22 +526,24 @@ namespace std::filesystem {
     template<class EcharT, class traits = char_traits<EcharT>,
              class Allocator = allocator<EcharT>>
       basic_string<EcharT, traits, Allocator>
         string(const Allocator& a = Allocator()) const;
-    std::string    string() const;
     std::wstring   wstring() const;
     std::u8string  u8string() const;
     std::u16string u16string() const;
     std::u32string u32string() const;
     // [fs.path.generic.obs], generic format observers
     template<class EcharT, class traits = char_traits<EcharT>,
              class Allocator = allocator<EcharT>>
       basic_string<EcharT, traits, Allocator>
         generic_string(const Allocator& a = Allocator()) const;
-    std::string    generic_string() const;
     std::wstring   generic_wstring() const;
     std::u8string  generic_u8string() const;
     std::u16string generic_u16string() const;
     std::u32string generic_u32string() const;
@@ -557,11 +562,11 @@ namespace std::filesystem {
     path filename() const;
     path stem() const;
     path extension() const;
     // [fs.path.query], query
- [[nodiscard]] bool empty() const noexcept;
     bool has_root_name() const;
     bool has_root_directory() const;
     bool has_root_path() const;
     bool has_relative_path() const;
     bool has_parent_path() const;
@@ -751,12 +756,12 @@ generic format and is not acceptable to the operating system as a native
 path.
 [*Note 2*: Some operating systems have no unambiguous way to
 distinguish between native format and generic format arguments. This is
 by design as it simplifies use for operating systems that do not require
-disambiguation. An implementation for an operating system where
-disambiguation is required is permitted to distinguish between the
 formats. — *end note*]
 Pathnames are converted as needed between the generic and native formats
 in an operating-system-dependent manner. Let *G(n)* and *N(g)* in a
 mathematical sense be the implementation’s functions that convert
@@ -842,16 +847,16 @@ named `Source` shall be one of:
   \[`source.begin()`, `source.end()`).
 - `basic_string_view<EcharT, traits>`. A function argument
   `const Source&` `source` shall have an effective range
   \[`source.begin()`, `source.end()`).
 - A type meeting the *Cpp17InputIterator* requirements that iterates
-  over a NTCTS. The value type shall be an encoded character type. A
   function argument `const Source&` `source` shall have an effective
   range \[`source`, `end`) where `end` is the first iterator value with
   an element value equal to `iterator_traits<Source>::value_type()`.
 - A character array that after array-to-pointer decay results in a
-  pointer to the start of a NTCTS. The value type shall be an encoded
   character type. A function argument `const Source&` `source` shall
   have an effective range \[`source`, `end`) where `end` is the first
   iterator value with an element value equal to
   `iterator_traits<decay_t<Source>>::value_type()`.
@@ -877,11 +882,11 @@ Arguments of type `Source` shall not be null pointers.
 ``` cpp
 path() noexcept;
 ```
-*Ensures:* `empty() == true`.
 ``` cpp
 path(const path& p);
 path(path&& p) noexcept;
 ```
@@ -1125,11 +1130,11 @@ template<class InputIterator>
 ``` cpp
 void clear() noexcept;
 ```
-*Ensures:* `empty() == true`.
 ``` cpp
 path& make_preferred();
 ```
@@ -1254,24 +1259,22 @@ operator string_type() const;
 ```
 *Returns:* `native()`.
 ``` cpp
-template<class EcharT, class traits = char_traits<EcharT>,
-         class Allocator = allocator<EcharT>>
-  basic_string<EcharT, traits, Allocator>
-    string(const Allocator& a = Allocator()) const;
 ```
 *Returns:* `native()`.
 *Remarks:* All memory allocation, including for the return value, shall
 be performed by `a`. Conversion, if any, is specified by
 [[fs.path.cvt]].
 ``` cpp
-std::string string() const;
 std::wstring wstring() const;
 std::u8string u8string() const;
 std::u16string u16string() const;
 std::u32string u32string() const;
 ```
@@ -1279,10 +1282,20 @@ std::u32string u32string() const;
 *Returns:* `native()`.
 *Remarks:* Conversion, if any, is performed as specified by
 [[fs.path.cvt]].
 ##### Generic format observers <a id="fs.path.generic.obs">[[fs.path.generic.obs]]</a>
 Generic format observer functions return strings formatted according to
 the generic pathname format [[fs.path.generic]]. A single slash (`'/'`)
 character is used as the *directory-separator*.
@@ -1298,34 +1311,42 @@ path("foo\\bar").generic_string()
 returns `"foo/bar"`.
 — *end example*]
 ``` cpp
-template<class EcharT, class traits = char_traits<EcharT>,
-         class Allocator = allocator<EcharT>>
-  basic_string<EcharT, traits, Allocator>
-    generic_string(const Allocator& a = Allocator()) const;
 ```
 *Returns:* The pathname in the generic format.
 *Remarks:* All memory allocation, including for the return value, shall
 be performed by `a`. Conversion, if any, is specified by
 [[fs.path.cvt]].
 ``` cpp
-std::string generic_string() const;
 std::wstring generic_wstring() const;
 std::u8string generic_u8string() const;
 std::u16string generic_u16string() const;
 std::u32string generic_u32string() const;
 ```
 *Returns:* The pathname in the generic format.
 *Remarks:* Conversion, if any, is specified by  [[fs.path.cvt]].
 ##### Compare <a id="fs.path.compare">[[fs.path.compare]]</a>
 ``` cpp
 int compare(const path& p) const noexcept;
 ```
@@ -1456,22 +1477,22 @@ path(".bar").extension();               // yields "" and stem() is ".bar"
 path("..bar").extension();              // yields ".bar" and stem() is "."
 ```
 — *end example*]
-[*Note 3*: The period is included in the return value so that it is
 possible to distinguish between no extension and an empty
 extension. — *end note*]
-[*Note 4*: On non-POSIX operating systems, for a path `p`, it is
 possible that `p.stem() + p.extension() == p.filename()` is `false`,
 even though the generic format pathnames are the same. — *end note*]
 ##### Query <a id="fs.path.query">[[fs.path.query]]</a>
 ``` cpp
-[[nodiscard]] bool empty() const noexcept;
 ```
 *Returns:* `true` if the pathname in the generic format is empty,
 otherwise `false`.
@@ -1575,11 +1596,11 @@ path lexically_relative(const path& base) const;
 - any *filename* in `relative_path()` or `base.relative_path()` can be
   interpreted as a *root-name*,
 returns `path()`.
-[*Note 5*: On a POSIX implementation, no *filename* in a
 *relative-path* is acceptable as a *root-name*. — *end note*]
 Determines the first mismatched element of `*this` and `base` as if by:
 ``` cpp
@@ -1618,28 +1639,28 @@ The above assertions will succeed. On Windows, the returned path’s
 *directory-separator* characters will be backslashes rather than
 slashes, but that does not affect `path` equality.
 — *end example*]
-[*Note 6*: If symlink following semantics are desired, use the
 operational function `relative()`. — *end note*]
-[*Note 7*: If normalization [[fs.path.generic]] is needed to ensure
 consistent matching of elements, apply `lexically_normal()` to `*this`,
 `base`, or both. — *end note*]
 ``` cpp
 path lexically_proximate(const path& base) const;
 ```
 *Returns:* If the value of `lexically_relative(base)` is not an empty
 path, return it. Otherwise return `*this`.
-[*Note 8*: If symlink following semantics are desired, use the
 operational function `proximate()`. — *end note*]
-[*Note 9*: If normalization [[fs.path.generic]] is needed to ensure
 consistent matching of elements, apply `lexically_normal()` to `*this`,
 `base`, or both. — *end note*]
 #### Iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
@@ -1657,13 +1678,13 @@ iterators referring to elements of that object.
 For the elements of the pathname in the generic format, the forward
 traversal order is as follows:
 - The *root-name* element, if present.
-- The *root-directory* element, if present. \[*Note 1*: The generic
-  format is required to ensure lexicographical comparison works
- correctly. — *end note*]
 - Each successive *filename* element, if present.
 - An empty element, if a trailing non-root *directory-separator* is
   present.
 The backward traversal order is the reverse of forward traversal.
@@ -1758,10 +1779,79 @@ friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
 friend path operator/(const path& lhs, const path& rhs);
 ```
 *Effects:* Equivalent to: `return path(lhs) /= rhs;`
 #### Hash support <a id="fs.path.hash">[[fs.path.hash]]</a>
 ``` cpp
 template<> struct hash<filesystem::path>;
 ```
@@ -1804,25 +1894,27 @@ with an error.
 filesystem_error(const string& what_arg, error_code ec);
 ```
 *Ensures:*
-- `code() == ec`,
-- `path1().empty() == true`,
-- `path2().empty() == true`, and
-- `string_view(what()).find(what_arg.c_str())` `!= string_view::npos`.
 ``` cpp
 filesystem_error(const string& what_arg, const path& p1, error_code ec);
 ```
 *Ensures:*
-- `code() == ec`,
 - `path1()` returns a reference to the stored copy of `p1`,
-- `path2().empty() == true`, and
-- `string_view(what()).find(what_arg.c_str())` `!= string_view::npos`.
 ``` cpp
 filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec);
 ```
@@ -1879,11 +1971,11 @@ the meanings listed in [[fs.enum.file.type]]. The values of the
 constants are distinct.
 **Table: Enum class `file_type`** <a id="fs.enum.file.type">[fs.enum.file.type]</a>
 | Constant                           | Meaning                                                                                                                                                                                                                     |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `none`      | The type of the file has not been determined or an error occurred while trying to determine the type.                                                                                                                       |
 | `not_found` | Pseudo-type indicating the file was not found. *The file not being found is not considered an error while determining the type of a file.*                                                                                  |
 | `regular`   | Regular file                                                                                                                                                                                                                |
 | `directory` | Directory file                                                                                                                                                                                                              |
 | `symlink`   | Symbolic link file                                                                                                                                                                                                          |
@@ -1906,11 +1998,11 @@ exposition; implementations shall provide only a single definition.
 Every other constant in the table represents a distinct bitmask element.
 **Table: Enum class `copy_options`** <a id="fs.enum.copy.opts">[fs.enum.copy.opts]</a>
 | Constant                                       | Meaning                                                                                                                                              |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `none`               | (Default) Error; file already exists.                                                                                                                |
 | `skip_existing`      | Do not overwrite existing file, do not report an error.                                                                                              |
 | `overwrite_existing` | Overwrite the existing file.                                                                                                                         |
 | `update_existing`    | Overwrite the existing file if it is older than the replacement file. \ohdrx{2}{Option group controlling `copy` function effects for subdirectories} |
 | `recursive`          | Recursively copy subdirectories and their contents. \ohdrx{2}{Option group controlling `copy` function effects for symbolic links}                   |
@@ -1928,11 +2020,11 @@ specifies bitmask constants used to identify file permissions, with the
 meanings listed in [[fs.enum.perms]].
 **Table: Enum class `perms`** <a id="fs.enum.perms">[fs.enum.perms]</a>
 | Name                              | Value (octal) | POSIX macro | Definition or notes                                                                                              |
-| -------------- | ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
 | `none`         | `0`           |             | There are no permissions set for the file.                                                                       |
 | `owner_read`   | `0400`        | `S_IRUSR`   | Read permission, owner                                                                                           |
 | `owner_write`  | `0200`        | `S_IWUSR`   | Write permission, owner                                                                                          |
 | `owner_exec`   | `0100`        | `S_IXUSR`   | Execute/search permission, owner                                                                                 |
 | `owner_all`    | `0700`        | `S_IRWXU`   | Read, write, execute/search by owner;<br> `owner_read | owner_write | owner_exec`                                |
@@ -1962,11 +2054,11 @@ permissions operations, with the meanings listed in
 `permissions`.
 **Table: Enum class `perm_options`** <a id="fs.enum.perm.opts">[fs.enum.perm.opts]</a>
 | Name                                 | Meaning                                                                                                                                                 |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `replace`  | `permissions` shall replace the file's permission bits with `perm`                                                                                      |
 | `add`      | `permissions` shall replace the file's permission bits with the bitwise \logop{or} of `perm` and the file's current permission bits.                    |
 | `remove`   | `permissions` shall replace the file's permission bits with the bitwise \logop{and} of the complement of `perm` and the file's current permission bits. |
 | `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to.                      |
@@ -1980,11 +2072,11 @@ directory traversal options, with the meanings listed in
 every other constant in the table represents a distinct bitmask element.
 **Table: Enum class `directory_options`** <a id="fs.enum.dir.opts">[fs.enum.dir.opts]</a>
 | Name                                                      | Meaning                                                            |
-| -------------------------- | ------------------------------------------------------------------ |
 | `none`                     | (Default) Skip directory symlinks, permission denied is an error.  |
 | `follow_directory_symlink` | Follow rather than skip directory symlinks.                        |
 | `skip_permission_denied`   | Skip directories that would otherwise result in permission denied. |
@@ -2129,12 +2221,11 @@ namespace std::filesystem {
     template<class charT, class traits>
       friend basic_ostream<charT, traits>&
         operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);
   private:
-    filesystem::path pathobject;        // exposition only
-    friend class directory_iterator;    // exposition only
   };
 }
 ```
 A `directory_entry` object stores a `path` object and may store
@@ -2145,16 +2236,13 @@ Implementations should store such additional file attributes during
 directory iteration if their values are available and storing the values
 would allow the implementation to eliminate file system accesses by
 `directory_entry` observer functions [[fs.op.funcs]]. Such stored file
 attribute values are said to be *cached*.
-[*Note 1*: For purposes of exposition, class `directory_iterator`
-[[fs.class.directory.iterator]] is shown above as a friend of class
-`directory_entry`. Friendship allows the `directory_iterator`
-implementation to cache already available attribute values directly into
-a `directory_entry` object without the cost of an unneeded call to
-`refresh()`. — *end note*]
 [*Example 1*:
 ``` cpp
 using namespace std::filesystem;
@@ -2203,22 +2291,22 @@ directory_entry(const filesystem::path& p, error_code& ec);
 ``` cpp
 void assign(const filesystem::path& p);
 void assign(const filesystem::path& p, error_code& ec);
 ```
-*Effects:* Equivalent to `pathobject = p`, then `refresh()` or
 `refresh(ec)`, respectively. If an error occurs, the values of any
 cached attributes are unspecified.
 *Throws:* As specified in  [[fs.err.report]].
 ``` cpp
 void replace_filename(const filesystem::path& p);
 void replace_filename(const filesystem::path& p, error_code& ec);
 ```
-*Effects:* Equivalent to `pathobject.replace_filename(p)`, then
 `refresh()` or `refresh(ec)`, respectively. If an error occurs, the
 values of any cached attributes are unspecified.
 *Throws:* As specified in  [[fs.err.report]].
@@ -2248,11 +2336,11 @@ Unqualified function names in the *Returns:* elements of the
 ``` cpp
 const filesystem::path& path() const noexcept;
 operator const filesystem::path&() const noexcept;
 ```
-*Returns:* `pathobject`.
 ``` cpp
 bool exists() const;
 bool exists(error_code& ec) const noexcept;
 ```
@@ -2396,17 +2484,17 @@ file_status symlink_status(error_code& ec) const noexcept;
 ``` cpp
 bool operator==(const directory_entry& rhs) const noexcept;
 ```
-*Returns:* `pathobject == rhs.pathobject`.
 ``` cpp
 strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
 ```
-*Returns:* `pathobject <=> rhs.pathobject`.
 #### Inserter <a id="fs.dir.entry.io">[[fs.dir.entry.io]]</a>
 ``` cpp
 template<class charT, class traits>
@@ -2497,13 +2585,11 @@ the values of any cached attributes [[fs.class.directory.entry]] in the
 `directory_entry` element returned by `operator*()`.
 `directory_iterator` member functions shall not directly or indirectly
 call any `directory_entry` `refresh` function.
 [*Note 2*: The exact mechanism for storing cached attribute values is
-not exposed to users. For exposition, class `directory_iterator` is
-shown in [[fs.class.directory.entry]] as a friend of class
-`directory_entry`. — *end note*]
 [*Note 3*: A path obtained by dereferencing a directory iterator might
 not actually exist; it could be a symbolic link to a non-existent file.
 Recursively walking directory trees for purposes of removing and
 renaming entries might invalidate symbolic links that are being
@@ -2835,11 +2921,11 @@ required to be dereferenceable nor to be in the domain of `==`.
 void disable_recursion_pending();
 ```
 *Ensures:* `recursion_pending() == false`.
-[*Note 4*: `disable_recursion_pending``()` is used to prevent unwanted
 recursion into a directory. — *end note*]
 #### Non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
 These functions enable use of `recursive_directory_iterator` with
@@ -2965,11 +3051,11 @@ group [[fs.enum.copy.opts]] is set in `options`.
 Effects are then as follows:
 - If `f.type()` or `t.type()` is an implementation-defined file
   type [[fs.enum.file.type]], then the effects are
   *implementation-defined*.
-- Otherwise, an error is reported as specified in  [[fs.err.report]] if:
   - `exists(f)` is `false`, or
   - `equivalent(from, to)` is `true`, or
   - `is_other(f) || is_other(t)` is `true`, or
   - `is_directory(f) && is_regular_file(t)` is `true`.
 - Otherwise, if `is_symlink(f)`, then:
@@ -3032,21 +3118,21 @@ applicable.
 [*Example 1*:
 Given this directory structure:
-``` cpp
 /dir1
   file1
   file2
   dir2
     file3
 ```
 Calling `copy("/dir1", "/dir3")` would result in:
-``` cpp
 /dir1
   file1
   file2
   dir2
     file3
@@ -3056,11 +3142,11 @@ Calling `copy("/dir1", "/dir3")` would result in:
 ```
 Alternatively, calling `copy("/dir1", "/dir3", copy_options::recursive)`
 would result in:
-``` cpp
 /dir1
   file1
   file2
   dir2
     file3
@@ -3094,22 +3180,22 @@ bool filesystem::copy_file(const path& from, const path& to, copy_options option
 *Preconditions:* At most one element from each option
 group [[fs.enum.copy.opts]] is set in `options`.
 *Effects:* As follows:
-- Report an error as specified in  [[fs.err.report]] if:
   - `is_regular_file(from)` is `false`, or
   - `exists(to)` is `true` and `is_regular_file(to)` is `false`, or
   - `exists(to)` is `true` and `equivalent(from, to)` is `true`, or
   - `exists(to)` is `true` and
     ``` cpp
     (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)` is `false`, or
   - `(options & copy_options::overwrite_existing) != copy_options::none`,
     or
   - `(options & copy_options::update_existing) `` `` != copy_options::none`
     and `from` is more recent than `to`, determined as if by use of the
@@ -3144,11 +3230,11 @@ respectively, where in each case *`function`* is `create_symlink` or
 ``` cpp
 bool filesystem::create_directories(const path& p);
 bool filesystem::create_directories(const path& p, error_code& ec);
 ```
-*Effects:* Calls `create_directory()` for each element of `p` that does
 not exist.
 *Returns:* `true` if a new directory was created for the directory `p`
 resolves to, otherwise `false`.
@@ -3201,21 +3287,21 @@ from directory `existing_p`, otherwise `false`.
 void filesystem::create_directory_symlink(const path& to, const path& new_symlink);
 void filesystem::create_directory_symlink(const path& to, const path& new_symlink,
                                           error_code& ec) noexcept;
 ```
-*Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
 *Ensures:* `new_symlink` resolves to a symbolic link file that contains
 an unspecified representation of `to`.
 *Throws:* As specified in  [[fs.err.report]].
 [*Note 1*: Some operating systems require symlink creation to identify
-that the link is to a directory. Thus, `create_symlink()` (instead of
-`create_directory_symlink()`) cannot be used reliably to create
-directory symlinks. — *end note*]
 [*Note 2*: Some operating systems do not support symbolic links at all
 or support them only for regular files. Some file systems (such as the
 FAT file system) do not support symbolic links regardless of the
 operating system. — *end note*]
@@ -3226,11 +3312,11 @@ operating system. — *end note*]
 void filesystem::create_hard_link(const path& to, const path& new_hard_link);
 void filesystem::create_hard_link(const path& to, const path& new_hard_link,
                                       error_code& ec) noexcept;
 ```
-*Effects:* Establishes the postcondition, as if by POSIX `link()`.
 *Ensures:*
 - `exists(to) && exists(new_hard_link) && equivalent(to, new_hard_link)`
 - The contents of the file or directory `to` resolves to are unchanged.
@@ -3249,11 +3335,11 @@ file. — *end note*]
 void filesystem::create_symlink(const path& to, const path& new_symlink);
 void filesystem::create_symlink(const path& to, const path& new_symlink,
                     error_code& ec) noexcept;
 ```
-*Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
 *Ensures:* `new_symlink` resolves to a symbolic link file that contains
 an unspecified representation of `to`.
 *Throws:* As specified in  [[fs.err.report]].
@@ -3269,39 +3355,35 @@ operating system. — *end note*]
 path filesystem::current_path();
 path filesystem::current_path(error_code& ec);
 ```
 *Returns:* The absolute path of the current working directory, whose
-pathname in the native format is obtained as if by POSIX `getcwd()`. The
 signature with argument `ec` returns `path()` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 *Remarks:* The current working directory is the directory, associated
 with the process, that is used as the starting location in pathname
 resolution for relative paths.
-[*Note 1*: The `current_path()` name was chosen to emphasize that the
-returned value is a path, not just a single directory
-name. — *end note*]
-[*Note 2*: The current path as returned by many operating systems is a
 dangerous global variable and can be changed unexpectedly by third-party
 or system library functions, or by another thread. — *end note*]
 ``` cpp
 void filesystem::current_path(const path& p);
 void filesystem::current_path(const path& p, error_code& ec) noexcept;
 ```
-*Effects:* Establishes the postcondition, as if by POSIX `chdir()`.
 *Ensures:* `equivalent(p, current_path())`.
 *Throws:* As specified in  [[fs.err.report]].
-[*Note 3*: The current path for many operating systems is a dangerous
 global state and can be changed unexpectedly by third-party or system
 library functions, or by another thread. — *end note*]
 #### Equivalent <a id="fs.op.equivalent">[[fs.op.equivalent]]</a>
@@ -3312,11 +3394,11 @@ bool filesystem::equivalent(const path& p1, const path& p2, error_code& ec) noex
 Two paths are considered to resolve to the same file system entity if
 two candidate entities reside on the same device at the same location.
 [*Note 1*: On POSIX platforms, this is determined as if by the values
-of the POSIX `stat` class, obtained as if by `stat()` for the two paths,
 having equal `st_dev` values and equal `st_ino` values. — *end note*]
 *Returns:* `true`, if `p1` and `p2` resolve to the same file system
 entity, otherwise `false`. The signature with argument `ec` returns
 `false` if an error occurs.
@@ -3360,11 +3442,11 @@ reported [[fs.err.report]].
 *Returns:*
 - If `is_regular_file(p)`, the size in bytes of the file `p` resolves
   to, determined as if by the value of the POSIX `stat` class member
-  `st_size` obtained as if by POSIX `stat()`.
 - Otherwise, the result is *implementation-defined*.
 The signature with argument `ec` returns `static_cast<uintmax_t>(-1)` if
 an error occurs.
@@ -3581,11 +3663,11 @@ file_time_type filesystem::last_write_time(const path& p);
 file_time_type filesystem::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` class member `st_mtime` obtained as if
-by POSIX `stat()`. The signature with argument `ec` returns
 `file_time_type::min()` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 ``` cpp
@@ -3593,11 +3675,11 @@ void filesystem::last_write_time(const path& p, file_time_type new_time);
 void filesystem::last_write_time(const path& p, file_time_type new_time,
                      error_code& ec) noexcept;
 ```
 *Effects:* Sets the time of last data modification of the file resolved
-to by `p` to `new_time`, as if by POSIX `futimens()`.
 *Throws:* As specified in  [[fs.err.report]].
 [*Note 1*: A postcondition of `last_write_time(p) == new_time` is not
 specified because it does not necessarily hold for file systems with
@@ -3615,11 +3697,11 @@ void filesystem::permissions(const path& p, perms prms, perm_options opts, error
 `add`, or `remove` is present in `opts`.
 *Effects:* Applies the action specified by `opts` to the file `p`
 resolves to, or to file `p` itself if `p` is a symbolic link and
 `perm_options::nofollow` is set in `opts`. The action is applied as if
-by POSIX `fchmodat()`.
 [*Note 1*: Conceptually permissions are viewed as bits, but the actual
 implementation can use some other mechanism. — *end note*]
 *Throws:* As specified in  [[fs.err.report]].
@@ -3712,19 +3794,20 @@ or `path()` at the first error occurrence, if any.
 bool filesystem::remove(const path& p);
 bool filesystem::remove(const path& p, error_code& ec) noexcept;
 ```
 *Effects:* If `exists(symlink_status(p, ec))`, the file `p` is removed
-as if by POSIX `remove()`.
 [*Note 1*: A symbolic link is itself removed, rather than the file it
 resolves to. — *end note*]
 *Ensures:* `exists(symlink_status(p))` is `false`.
-*Returns:* `false` if `p` did not exist, otherwise `true`. The signature
-with argument `ec` returns `false` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 #### Remove all <a id="fs.op.remove.all">[[fs.op.remove.all]]</a>
@@ -3732,11 +3815,11 @@ with argument `ec` returns `false` if an error occurs.
 uintmax_t filesystem::remove_all(const path& p);
 uintmax_t filesystem::remove_all(const path& p, error_code& ec);
 ```
 *Effects:* Recursively deletes the contents of `p` if it exists, then
-deletes file `p` itself, as if by POSIX `remove()`.
 [*Note 1*: A symbolic link is itself removed, rather than the file it
 resolves to. — *end note*]
 *Ensures:* `exists(symlink_status(p))` is `false`.
@@ -3751,11 +3834,11 @@ returns `static_cast< uintmax_t>(-1)` if an error occurs.
 ``` cpp
 void filesystem::rename(const path& old_p, const path& new_p);
 void filesystem::rename(const path& old_p, const path& new_p, error_code& ec) noexcept;
 ```
-*Effects:* Renames `old_p` to `new_p`, as if by POSIX `rename()`.
 [*Note 1*:
 - If `old_p` and `new_p` resolve to the same existing file, no action is
   taken.
@@ -3778,11 +3861,11 @@ A symbolic link is itself renamed, rather than the file it resolves to.
 void filesystem::resize_file(const path& p, uintmax_t new_size);
 void filesystem::resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
 ```
 *Effects:* Causes the size that would be returned by `file_size(p)` to
-be equal to `new_size`, as if by POSIX `truncate()`.
 *Throws:* As specified in  [[fs.err.report]].
 #### Space <a id="fs.op.space">[[fs.op.space]]</a>
@@ -3811,11 +3894,11 @@ system dependent.
 ``` cpp
 file_status filesystem::status(const path& p);
 ```
-*Effects:* As if:
 ``` cpp
 error_code ec;
 file_status result = status(p, ec);
 if (result.type() == file_type::none)
@@ -3834,17 +3917,17 @@ cause an exception to be thrown. — *end note*]
 ``` cpp
 file_status filesystem::status(const path& p, error_code& ec) noexcept;
 ```
 *Effects:* If possible, determines the attributes of the file `p`
-resolves to, as if by using POSIX `stat()` to obtain a POSIX
 `struct stat`. If, during attribute determination, the underlying file
 system API reports an error, sets `ec` to indicate the specific error
 reported. Otherwise, `ec.clear()`.
 [*Note 2*: This allows users to inspect the specifics of underlying API
-errors even when the value returned by `status()` is not
 `file_status(file_type::none)`. — *end note*]
 Let `prms` denote the result of `(m & perms::mask)`, where `m` is
 determined as if by converting the `st_mode` member of the obtained
 `struct stat` to the type `perms`.
@@ -3907,19 +3990,19 @@ bool filesystem::status_known(file_status s) noexcept;
 ``` cpp
 file_status filesystem::symlink_status(const path& p);
 file_status filesystem::symlink_status(const path& p, error_code& ec) noexcept;
 ```
-*Effects:* Same as `status()`, above, except that the attributes of `p`
-are determined as if by using POSIX `lstat()` to obtain a POSIX
 `struct stat`.
 Let `prms` denote the result of `(m & perms::mask)`, where `m` is
 determined as if by converting the `st_mode` member of the obtained
 `struct stat` to the type `perms`.
-*Returns:* Same as `status()`, above, except that if the attributes
 indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
 `file_status(file_type::symlink, prms)`. The signature with argument
 `ec` returns `file_status(file_type::none)` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
@@ -3957,16 +4040,16 @@ path filesystem::weakly_canonical(const path& p);
 path filesystem::weakly_canonical(const path& p, error_code& ec);
 ```
 *Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
 determine existence, return a path composed by `operator/=` from the
-result of calling `canonical()` with a path argument composed of the
 leading elements of `p` that exist, if any, followed by the elements of
-`p` that do not exist, if any. For the first form, `canonical()` is
-called without an `error_code` argument. For the second form,
-`canonical()` is called with `ec` as an `error_code` argument, and
-`path()` is returned at the first error occurrence, if any.
 *Ensures:* The returned path is in normal form [[fs.path.generic]].
 *Returns:* `p` with symlinks resolved and the result
 normalized [[fs.path.generic]].

   path weakly_canonical(const path& p);
   path weakly_canonical(const path& p, error_code& ec);
 }
+namespace std {
+  // [fs.path.fmtr], formatting support
+  template<class charT> struct formatter<filesystem::path, charT>;
   // [fs.path.hash], hash support
   template<class T> struct hash;
   template<> struct hash<filesystem::path>;
 }
 namespace std::ranges {
   template<>
+    inline constexpr bool \libspec{enable_borrowed_range}{directory_iterator}<filesystem::directory_iterator> = true;
   template<>
+    inline constexpr bool \libspec{enable_borrowed_range}{recursive_directory_iterator}<filesystem::recursive_directory_iterator> = true;
   template<>
+    inline constexpr bool \libspec{enable_view}{directory_iterator}<filesystem::directory_iterator> = true;
   template<>
+    inline constexpr bool \libspec{enable_view}{recursive_directory_iterator}<filesystem::recursive_directory_iterator> = true;
 }
 ```
 Implementations should ensure that the resolution and range of
 `file_time_type` reflect the operating system dependent resolution and
 *Pathname resolution* is the operating system dependent mechanism for
 resolving a pathname to a particular file in a file hierarchy. There may
 be multiple pathnames that resolve to the same file.
+[*Example 1*: For POSIX-based operating systems, this mechanism is
+specified in POSIX, section 4.12, Pathname resolution. — *end example*]
 ``` cpp
 namespace std::filesystem {
   class path {
   public:
     template<class EcharT, class traits = char_traits<EcharT>,
              class Allocator = allocator<EcharT>>
       basic_string<EcharT, traits, Allocator>
         string(const Allocator& a = Allocator()) const;
+    std::string    display_string() const;
+    std::string    system_encoded_string() const;
     std::wstring   wstring() const;
     std::u8string  u8string() const;
     std::u16string u16string() const;
     std::u32string u32string() const;
     // [fs.path.generic.obs], generic format observers
     template<class EcharT, class traits = char_traits<EcharT>,
              class Allocator = allocator<EcharT>>
       basic_string<EcharT, traits, Allocator>
         generic_string(const Allocator& a = Allocator()) const;
+    std::string    generic_display_string() const;
+    std::string    generic_system_encoded_string() const;
     std::wstring   generic_wstring() const;
     std::u8string  generic_u8string() const;
     std::u16string generic_u16string() const;
     std::u32string generic_u32string() const;
     path filename() const;
     path stem() const;
     path extension() const;
     // [fs.path.query], query
+    bool empty() const noexcept;
     bool has_root_name() const;
     bool has_root_directory() const;
     bool has_root_path() const;
     bool has_relative_path() const;
     bool has_parent_path() const;
 path.
 [*Note 2*: Some operating systems have no unambiguous way to
 distinguish between native format and generic format arguments. This is
 by design as it simplifies use for operating systems that do not require
+disambiguation. It is possible that an implementation for an operating
+system where disambiguation is needed distinguishes between the
 formats. — *end note*]
 Pathnames are converted as needed between the generic and native formats
 in an operating-system-dependent manner. Let *G(n)* and *N(g)* in a
 mathematical sense be the implementation’s functions that convert
   \[`source.begin()`, `source.end()`).
 - `basic_string_view<EcharT, traits>`. A function argument
   `const Source&` `source` shall have an effective range
   \[`source.begin()`, `source.end()`).
 - A type meeting the *Cpp17InputIterator* requirements that iterates
+  over an NTCTS. The value type shall be an encoded character type. A
   function argument `const Source&` `source` shall have an effective
   range \[`source`, `end`) where `end` is the first iterator value with
   an element value equal to `iterator_traits<Source>::value_type()`.
 - A character array that after array-to-pointer decay results in a
+  pointer to the start of an NTCTS. The value type shall be an encoded
   character type. A function argument `const Source&` `source` shall
   have an effective range \[`source`, `end`) where `end` is the first
   iterator value with an element value equal to
   `iterator_traits<decay_t<Source>>::value_type()`.
 ``` cpp
 path() noexcept;
 ```
+*Ensures:* `empty()` is `true`.
 ``` cpp
 path(const path& p);
 path(path&& p) noexcept;
 ```
 ``` cpp
 void clear() noexcept;
 ```
+*Ensures:* `empty()` is `true`.
 ``` cpp
 path& make_preferred();
 ```
 ```
 *Returns:* `native()`.
 ``` cpp
+template<class EcharT, class traits = char_traits<EcharT>, class Allocator = allocator<EcharT>>
+  basic_string<EcharT, traits, Allocator> string(const Allocator& a = Allocator()) const;
 ```
 *Returns:* `native()`.
 *Remarks:* All memory allocation, including for the return value, shall
 be performed by `a`. Conversion, if any, is specified by
 [[fs.path.cvt]].
 ``` cpp
+std::string system_encoded_string() const;
 std::wstring wstring() const;
 std::u8string u8string() const;
 std::u16string u16string() const;
 std::u32string u32string() const;
 ```
 *Returns:* `native()`.
 *Remarks:* Conversion, if any, is performed as specified by
 [[fs.path.cvt]].
+``` cpp
+std::string display_string() const;
+```
+*Returns:* `std::format("{}", *this)`.
+[*Note 3*: The returned string is suitable for use with
+formatting [[format.functions]] and print
+functions [[print.fun]]. — *end note*]
 ##### Generic format observers <a id="fs.path.generic.obs">[[fs.path.generic.obs]]</a>
 Generic format observer functions return strings formatted according to
 the generic pathname format [[fs.path.generic]]. A single slash (`'/'`)
 character is used as the *directory-separator*.
 returns `"foo/bar"`.
 — *end example*]
 ``` cpp
+template<class EcharT, class traits = char_traits<EcharT>, class Allocator = allocator<EcharT>>
+  basic_string<EcharT, traits, Allocator> generic_string(const Allocator& a = Allocator()) const;
 ```
 *Returns:* The pathname in the generic format.
 *Remarks:* All memory allocation, including for the return value, shall
 be performed by `a`. Conversion, if any, is specified by
 [[fs.path.cvt]].
 ``` cpp
+std::string generic_system_encoded_string() const;
 std::wstring generic_wstring() const;
 std::u8string generic_u8string() const;
 std::u16string generic_u16string() const;
 std::u32string generic_u32string() const;
 ```
 *Returns:* The pathname in the generic format.
 *Remarks:* Conversion, if any, is specified by  [[fs.path.cvt]].
+``` cpp
+std::string generic_display_string() const;
+```
+*Returns:* `std::format("{:g}", *this)`.
+[*Note 4*: The returned string is suitable for use with
+formatting [[format.functions]] and print
+functions [[print.fun]]. — *end note*]
 ##### Compare <a id="fs.path.compare">[[fs.path.compare]]</a>
 ``` cpp
 int compare(const path& p) const noexcept;
 ```
 path("..bar").extension();              // yields ".bar" and stem() is "."
 ```
 — *end example*]
+[*Note 5*: The period is included in the return value so that it is
 possible to distinguish between no extension and an empty
 extension. — *end note*]
+[*Note 6*: On non-POSIX operating systems, for a path `p`, it is
 possible that `p.stem() + p.extension() == p.filename()` is `false`,
 even though the generic format pathnames are the same. — *end note*]
 ##### Query <a id="fs.path.query">[[fs.path.query]]</a>
 ``` cpp
+bool empty() const noexcept;
 ```
 *Returns:* `true` if the pathname in the generic format is empty,
 otherwise `false`.
 - any *filename* in `relative_path()` or `base.relative_path()` can be
   interpreted as a *root-name*,
 returns `path()`.
+[*Note 7*: On a POSIX implementation, no *filename* in a
 *relative-path* is acceptable as a *root-name*. — *end note*]
 Determines the first mismatched element of `*this` and `base` as if by:
 ``` cpp
 *directory-separator* characters will be backslashes rather than
 slashes, but that does not affect `path` equality.
 — *end example*]
+[*Note 8*: If symlink following semantics are desired, use the
 operational function `relative()`. — *end note*]
+[*Note 9*: If normalization [[fs.path.generic]] is needed to ensure
 consistent matching of elements, apply `lexically_normal()` to `*this`,
 `base`, or both. — *end note*]
 ``` cpp
 path lexically_proximate(const path& base) const;
 ```
 *Returns:* If the value of `lexically_relative(base)` is not an empty
 path, return it. Otherwise return `*this`.
+[*Note 10*: If symlink following semantics are desired, use the
 operational function `proximate()`. — *end note*]
+[*Note 11*: If normalization [[fs.path.generic]] is needed to ensure
 consistent matching of elements, apply `lexically_normal()` to `*this`,
 `base`, or both. — *end note*]
 #### Iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
 For the elements of the pathname in the generic format, the forward
 traversal order is as follows:
 - The *root-name* element, if present.
+- The *root-directory* element, if present. \[*Note 1*: It is possible
+ that the use of the generic format is needed to ensure correct
+ lexicographical comparison. — *end note*]
 - Each successive *filename* element, if present.
 - An empty element, if a trailing non-root *directory-separator* is
   present.
 The backward traversal order is the reverse of forward traversal.
 friend path operator/(const path& lhs, const path& rhs);
 ```
 *Effects:* Equivalent to: `return path(lhs) /= rhs;`
+#### Formatting support <a id="fs.path.fmtr">[[fs.path.fmtr]]</a>
+##### Formatting support overview <a id="fs.path.fmtr.general">[[fs.path.fmtr.general]]</a>
+``` cpp
+namespace std {
+  template<class charT> struct formatter<filesystem::path, charT> {
+    constexpr void set_debug_format();
+    constexpr typename basic_format_parse_context<charT>::iterator
+      parse(basic_format_parse_context<charT>& ctx);
+    template<class FormatContext>
+      typename FormatContext::iterator
+        format(const filesystem::path& path, FormatContext& ctx) const;
+  };
+}
+```
+##### Formatting support functions <a id="fs.path.fmtr.funcs">[[fs.path.fmtr.funcs]]</a>
+Formatting of paths uses formatting specifiers of the form
+``` bnf
+path-format-spec:
+    fill-and-alignₒₚₜ widthₒₚₜ '?'ₒₚₜ 'g'ₒₚₜ
+```
+where the productions *fill-and-align* and *width* are described in
+[[format.string]]. If the `?` option is used then the path is formatted
+as an escaped string [[format.string.escaped]].
+``` cpp
+constexpr void set_debug_format();
+```
+*Effects:* Modifies the state of the `formatter` to be as if the
+*path-format-spec* parsed by the last call to `parse` contained the `?`
+option.
+``` cpp
+constexpr typename basic_format_parse_context<charT>::iterator
+  parse(basic_format_parse_context<charT>& ctx);
+```
+*Effects:* Parses the format specifier as a *path-format-spec* and
+stores the parsed specifiers in `*this`.
+*Returns:* An iterator past the end of the *path-format-spec*.
+``` cpp
+template<class FormatContext>
+  typename FormatContext::iterator
+    format(const filesystem::path& p, FormatContext& ctx) const;
+```
+*Effects:* Let `s` be `p.generic_string<filesystem::path::value_type>()`
+if the `g` option is used, otherwise `p.native()`. Writes `s` into
+`ctx.out()`, adjusted according to the *path-format-spec*. If `charT` is
+`char`, `path::value_type` is `wchar_t`, and the literal encoding is
+UTF-8, then the escaped path is transcoded from the native encoding for
+wide character strings to UTF-8 with maximal subparts of ill-formed
+subsequences substituted with ‘U+fffd‘ replacement character per the
+Unicode Standard, Chapter 3.9 ‘U+fffd‘ Substitution in Conversion. If
+`charT` and `path::value_type` are the same then no transcoding is
+performed. Otherwise, transcoding is *implementation-defined*.
+*Returns:* An iterator past the end of the output range.
 #### Hash support <a id="fs.path.hash">[[fs.path.hash]]</a>
 ``` cpp
 template<> struct hash<filesystem::path>;
 ```
 filesystem_error(const string& what_arg, error_code ec);
 ```
 *Ensures:*
+- `code() == ec` is `true`,
+- `path1().empty()` is `true`,
+- `path2().empty()` is `true`, and
+- `string_view(what()).find(what_arg.c_str())` `!= string_view::npos` is
+  `true`.
 ``` cpp
 filesystem_error(const string& what_arg, const path& p1, error_code ec);
 ```
 *Ensures:*
+- `code() == ec` is `true`,
 - `path1()` returns a reference to the stored copy of `p1`,
+- `path2().empty()` is `true`, and
+- `string_view(what()).find(what_arg.c_str())` `!= string_view::npos` is
+  `true`.
 ``` cpp
 filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec);
 ```
 constants are distinct.
 **Table: Enum class `file_type`** <a id="fs.enum.file.type">[fs.enum.file.type]</a>
 | Constant                           | Meaning                                                                                                                                                                                                                     |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `none`      | The type of the file has not been determined or an error occurred while trying to determine the type.                                                                                                                       |
 | `not_found` | Pseudo-type indicating the file was not found. *The file not being found is not considered an error while determining the type of a file.*                                                                                  |
 | `regular`   | Regular file                                                                                                                                                                                                                |
 | `directory` | Directory file                                                                                                                                                                                                              |
 | `symlink`   | Symbolic link file                                                                                                                                                                                                          |
 Every other constant in the table represents a distinct bitmask element.
 **Table: Enum class `copy_options`** <a id="fs.enum.copy.opts">[fs.enum.copy.opts]</a>
 | Constant                                       | Meaning                                                                                                                                              |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `none`               | (Default) Error; file already exists.                                                                                                                |
 | `skip_existing`      | Do not overwrite existing file, do not report an error.                                                                                              |
 | `overwrite_existing` | Overwrite the existing file.                                                                                                                         |
 | `update_existing`    | Overwrite the existing file if it is older than the replacement file. \ohdrx{2}{Option group controlling `copy` function effects for subdirectories} |
 | `recursive`          | Recursively copy subdirectories and their contents. \ohdrx{2}{Option group controlling `copy` function effects for symbolic links}                   |
 meanings listed in [[fs.enum.perms]].
 **Table: Enum class `perms`** <a id="fs.enum.perms">[fs.enum.perms]</a>
 | Name                              | Value (octal) | POSIX macro | Definition or notes                                                                                              |
+| --------------------------------- | ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
 | `none`         | `0`           |             | There are no permissions set for the file.                                                                       |
 | `owner_read`   | `0400`        | `S_IRUSR`   | Read permission, owner                                                                                           |
 | `owner_write`  | `0200`        | `S_IWUSR`   | Write permission, owner                                                                                          |
 | `owner_exec`   | `0100`        | `S_IXUSR`   | Execute/search permission, owner                                                                                 |
 | `owner_all`    | `0700`        | `S_IRWXU`   | Read, write, execute/search by owner;<br> `owner_read | owner_write | owner_exec`                                |
 `permissions`.
 **Table: Enum class `perm_options`** <a id="fs.enum.perm.opts">[fs.enum.perm.opts]</a>
 | Name                                 | Meaning                                                                                                                                                 |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `replace`  | `permissions` shall replace the file's permission bits with `perm`                                                                                      |
 | `add`      | `permissions` shall replace the file's permission bits with the bitwise \logop{or} of `perm` and the file's current permission bits.                    |
 | `remove`   | `permissions` shall replace the file's permission bits with the bitwise \logop{and} of the complement of `perm` and the file's current permission bits. |
 | `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to.                      |
 every other constant in the table represents a distinct bitmask element.
 **Table: Enum class `directory_options`** <a id="fs.enum.dir.opts">[fs.enum.dir.opts]</a>
 | Name                                                      | Meaning                                                            |
+| --------------------------------------------------------- | ------------------------------------------------------------------ |
 | `none`                     | (Default) Skip directory symlinks, permission denied is an error.  |
 | `follow_directory_symlink` | Follow rather than skip directory symlinks.                        |
 | `skip_permission_denied`   | Skip directories that would otherwise result in permission denied. |
     template<class charT, class traits>
       friend basic_ostream<charT, traits>&
         operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);
   private:
+    filesystem::path path-object;        // exposition only
   };
 }
 ```
 A `directory_entry` object stores a `path` object and may store
 directory iteration if their values are available and storing the values
 would allow the implementation to eliminate file system accesses by
 `directory_entry` observer functions [[fs.op.funcs]]. Such stored file
 attribute values are said to be *cached*.
+[*Note 1*: `directory_iterator` can cache already available attribute
+values directly into a `directory_entry` object without the cost of a
+call to `refresh()`. — *end note*]
 [*Example 1*:
 ``` cpp
 using namespace std::filesystem;
 ``` cpp
 void assign(const filesystem::path& p);
 void assign(const filesystem::path& p, error_code& ec);
 ```
+*Effects:* Equivalent to *`path-object`*` = p`, then `refresh()` or
 `refresh(ec)`, respectively. If an error occurs, the values of any
 cached attributes are unspecified.
 *Throws:* As specified in  [[fs.err.report]].
 ``` cpp
 void replace_filename(const filesystem::path& p);
 void replace_filename(const filesystem::path& p, error_code& ec);
 ```
+*Effects:* Equivalent to *`path-object`*`.replace_filename(p)`, then
 `refresh()` or `refresh(ec)`, respectively. If an error occurs, the
 values of any cached attributes are unspecified.
 *Throws:* As specified in  [[fs.err.report]].
 ``` cpp
 const filesystem::path& path() const noexcept;
 operator const filesystem::path&() const noexcept;
 ```
+*Returns:* *path-object*.
 ``` cpp
 bool exists() const;
 bool exists(error_code& ec) const noexcept;
 ```
 ``` cpp
 bool operator==(const directory_entry& rhs) const noexcept;
 ```
+*Returns:* *`path-object`*` == rhs.`*`path-object`*.
 ``` cpp
 strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
 ```
+*Returns:* *`path-object`*` <=> rhs.`*`path-object`*.
 #### Inserter <a id="fs.dir.entry.io">[[fs.dir.entry.io]]</a>
 ``` cpp
 template<class charT, class traits>
 `directory_entry` element returned by `operator*()`.
 `directory_iterator` member functions shall not directly or indirectly
 call any `directory_entry` `refresh` function.
 [*Note 2*: The exact mechanism for storing cached attribute values is
+not exposed to users. — *end note*]
 [*Note 3*: A path obtained by dereferencing a directory iterator might
 not actually exist; it could be a symbolic link to a non-existent file.
 Recursively walking directory trees for purposes of removing and
 renaming entries might invalidate symbolic links that are being
 void disable_recursion_pending();
 ```
 *Ensures:* `recursion_pending() == false`.
+[*Note 4*: `disable_recursion_pending()` is used to prevent unwanted
 recursion into a directory. — *end note*]
 #### Non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
 These functions enable use of `recursive_directory_iterator` with
 Effects are then as follows:
 - If `f.type()` or `t.type()` is an implementation-defined file
   type [[fs.enum.file.type]], then the effects are
   *implementation-defined*.
+- Otherwise, an error is reported as specified in  [[fs.err.report]] if
   - `exists(f)` is `false`, or
   - `equivalent(from, to)` is `true`, or
   - `is_other(f) || is_other(t)` is `true`, or
   - `is_directory(f) && is_regular_file(t)` is `true`.
 - Otherwise, if `is_symlink(f)`, then:
 [*Example 1*:
 Given this directory structure:
+``` text
 /dir1
   file1
   file2
   dir2
     file3
 ```
 Calling `copy("/dir1", "/dir3")` would result in:
+``` text
 /dir1
   file1
   file2
   dir2
     file3
 ```
 Alternatively, calling `copy("/dir1", "/dir3", copy_options::recursive)`
 would result in:
+``` text
 /dir1
   file1
   file2
   dir2
     file3
 *Preconditions:* At most one element from each option
 group [[fs.enum.copy.opts]] is set in `options`.
 *Effects:* As follows:
+- Report an error as specified in  [[fs.err.report]] if
   - `is_regular_file(from)` is `false`, or
   - `exists(to)` is `true` and `is_regular_file(to)` is `false`, or
   - `exists(to)` is `true` and `equivalent(from, to)` is `true`, or
   - `exists(to)` is `true` and
     ``` cpp
     (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)` is `false`, or
   - `(options & copy_options::overwrite_existing) != copy_options::none`,
     or
   - `(options & copy_options::update_existing) `` `` != copy_options::none`
     and `from` is more recent than `to`, determined as if by use of the
 ``` cpp
 bool filesystem::create_directories(const path& p);
 bool filesystem::create_directories(const path& p, error_code& ec);
 ```
+*Effects:* Calls `create_directory` for each element of `p` that does
 not exist.
 *Returns:* `true` if a new directory was created for the directory `p`
 resolves to, otherwise `false`.
 void filesystem::create_directory_symlink(const path& to, const path& new_symlink);
 void filesystem::create_directory_symlink(const path& to, const path& new_symlink,
                                           error_code& ec) noexcept;
 ```
+*Effects:* Establishes the postcondition, as if by POSIX `symlink`.
 *Ensures:* `new_symlink` resolves to a symbolic link file that contains
 an unspecified representation of `to`.
 *Throws:* As specified in  [[fs.err.report]].
 [*Note 1*: Some operating systems require symlink creation to identify
+that the link is to a directory. Thus, `create_symlink` (instead of
+`create_directory_symlink`) cannot be used reliably to create directory
+symlinks. — *end note*]
 [*Note 2*: Some operating systems do not support symbolic links at all
 or support them only for regular files. Some file systems (such as the
 FAT file system) do not support symbolic links regardless of the
 operating system. — *end note*]
 void filesystem::create_hard_link(const path& to, const path& new_hard_link);
 void filesystem::create_hard_link(const path& to, const path& new_hard_link,
                                       error_code& ec) noexcept;
 ```
+*Effects:* Establishes the postcondition, as if by POSIX `link`.
 *Ensures:*
 - `exists(to) && exists(new_hard_link) && equivalent(to, new_hard_link)`
 - The contents of the file or directory `to` resolves to are unchanged.
 void filesystem::create_symlink(const path& to, const path& new_symlink);
 void filesystem::create_symlink(const path& to, const path& new_symlink,
                     error_code& ec) noexcept;
 ```
+*Effects:* Establishes the postcondition, as if by POSIX `symlink`.
 *Ensures:* `new_symlink` resolves to a symbolic link file that contains
 an unspecified representation of `to`.
 *Throws:* As specified in  [[fs.err.report]].
 path filesystem::current_path();
 path filesystem::current_path(error_code& ec);
 ```
 *Returns:* The absolute path of the current working directory, whose
+pathname in the native format is obtained as if by POSIX `getcwd`. The
 signature with argument `ec` returns `path()` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 *Remarks:* The current working directory is the directory, associated
 with the process, that is used as the starting location in pathname
 resolution for relative paths.
+[*Note 1*: The current path as returned by many operating systems is a
 dangerous global variable and can be changed unexpectedly by third-party
 or system library functions, or by another thread. — *end note*]
 ``` cpp
 void filesystem::current_path(const path& p);
 void filesystem::current_path(const path& p, error_code& ec) noexcept;
 ```
+*Effects:* Establishes the postcondition, as if by POSIX `chdir`.
 *Ensures:* `equivalent(p, current_path())`.
 *Throws:* As specified in  [[fs.err.report]].
+[*Note 2*: The current path for many operating systems is a dangerous
 global state and can be changed unexpectedly by third-party or system
 library functions, or by another thread. — *end note*]
 #### Equivalent <a id="fs.op.equivalent">[[fs.op.equivalent]]</a>
 Two paths are considered to resolve to the same file system entity if
 two candidate entities reside on the same device at the same location.
 [*Note 1*: On POSIX platforms, this is determined as if by the values
+of the POSIX `stat` class, obtained as if by `stat` for the two paths,
 having equal `st_dev` values and equal `st_ino` values. — *end note*]
 *Returns:* `true`, if `p1` and `p2` resolve to the same file system
 entity, otherwise `false`. The signature with argument `ec` returns
 `false` if an error occurs.
 *Returns:*
 - If `is_regular_file(p)`, the size in bytes of the file `p` resolves
   to, determined as if by the value of the POSIX `stat` class member
+  `st_size` obtained as if by POSIX `stat`.
 - Otherwise, the result is *implementation-defined*.
 The signature with argument `ec` returns `static_cast<uintmax_t>(-1)` if
 an error occurs.
 file_time_type filesystem::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` class member `st_mtime` obtained as if
+by POSIX `stat`. The signature with argument `ec` returns
 `file_time_type::min()` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 ``` cpp
 void filesystem::last_write_time(const path& p, file_time_type new_time,
                      error_code& ec) noexcept;
 ```
 *Effects:* Sets the time of last data modification of the file resolved
+to by `p` to `new_time`, as if by POSIX `futimens`.
 *Throws:* As specified in  [[fs.err.report]].
 [*Note 1*: A postcondition of `last_write_time(p) == new_time` is not
 specified because it does not necessarily hold for file systems with
 `add`, or `remove` is present in `opts`.
 *Effects:* Applies the action specified by `opts` to the file `p`
 resolves to, or to file `p` itself if `p` is a symbolic link and
 `perm_options::nofollow` is set in `opts`. The action is applied as if
+by POSIX `fchmodat`.
 [*Note 1*: Conceptually permissions are viewed as bits, but the actual
 implementation can use some other mechanism. — *end note*]
 *Throws:* As specified in  [[fs.err.report]].
 bool filesystem::remove(const path& p);
 bool filesystem::remove(const path& p, error_code& ec) noexcept;
 ```
 *Effects:* If `exists(symlink_status(p, ec))`, the file `p` is removed
+as if by POSIX `remove`.
 [*Note 1*: A symbolic link is itself removed, rather than the file it
 resolves to. — *end note*]
 *Ensures:* `exists(symlink_status(p))` is `false`.
+*Returns:* `true` if a file `p` has been removed and `false` otherwise.
+[*Note 2*: Absence of a file `p` is not an error. — *end note*]
 *Throws:* As specified in  [[fs.err.report]].
 #### Remove all <a id="fs.op.remove.all">[[fs.op.remove.all]]</a>
 uintmax_t filesystem::remove_all(const path& p);
 uintmax_t filesystem::remove_all(const path& p, error_code& ec);
 ```
 *Effects:* Recursively deletes the contents of `p` if it exists, then
+deletes file `p` itself, as if by POSIX `remove`.
 [*Note 1*: A symbolic link is itself removed, rather than the file it
 resolves to. — *end note*]
 *Ensures:* `exists(symlink_status(p))` is `false`.
 ``` cpp
 void filesystem::rename(const path& old_p, const path& new_p);
 void filesystem::rename(const path& old_p, const path& new_p, error_code& ec) noexcept;
 ```
+*Effects:* Renames `old_p` to `new_p`, as if by POSIX `rename`.
 [*Note 1*:
 - If `old_p` and `new_p` resolve to the same existing file, no action is
   taken.
 void filesystem::resize_file(const path& p, uintmax_t new_size);
 void filesystem::resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
 ```
 *Effects:* Causes the size that would be returned by `file_size(p)` to
+be equal to `new_size`, as if by POSIX `truncate`.
 *Throws:* As specified in  [[fs.err.report]].
 #### Space <a id="fs.op.space">[[fs.op.space]]</a>
 ``` cpp
 file_status filesystem::status(const path& p);
 ```
+*Effects:* As if by:
 ``` cpp
 error_code ec;
 file_status result = status(p, ec);
 if (result.type() == file_type::none)
 ``` cpp
 file_status filesystem::status(const path& p, error_code& ec) noexcept;
 ```
 *Effects:* If possible, determines the attributes of the file `p`
+resolves to, as if by using POSIX `stat` to obtain a POSIX
 `struct stat`. If, during attribute determination, the underlying file
 system API reports an error, sets `ec` to indicate the specific error
 reported. Otherwise, `ec.clear()`.
 [*Note 2*: This allows users to inspect the specifics of underlying API
+errors even when the value returned by `status` is not
 `file_status(file_type::none)`. — *end note*]
 Let `prms` denote the result of `(m & perms::mask)`, where `m` is
 determined as if by converting the `st_mode` member of the obtained
 `struct stat` to the type `perms`.
 ``` cpp
 file_status filesystem::symlink_status(const path& p);
 file_status filesystem::symlink_status(const path& p, error_code& ec) noexcept;
 ```
+*Effects:* Same as `status`, above, except that the attributes of `p`
+are determined as if by using POSIX `lstat` to obtain a POSIX
 `struct stat`.
 Let `prms` denote the result of `(m & perms::mask)`, where `m` is
 determined as if by converting the `st_mode` member of the obtained
 `struct stat` to the type `perms`.
+*Returns:* Same as `status`, above, except that if the attributes
 indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
 `file_status(file_type::symlink, prms)`. The signature with argument
 `ec` returns `file_status(file_type::none)` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 path filesystem::weakly_canonical(const path& p, error_code& ec);
 ```
 *Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
 determine existence, return a path composed by `operator/=` from the
+result of calling `canonical` with a path argument composed of the
 leading elements of `p` that exist, if any, followed by the elements of
+`p` that do not exist, if any. For the first form, `canonical` is called
+without an `error_code` argument. For the second form, `canonical` is
+called with `ec` as an `error_code` argument, and `path()` is returned
+at the first error occurrence, if any.
 *Ensures:* The returned path is in normal form [[fs.path.generic]].
 *Returns:* `p` with symlinks resolved and the result
 normalized [[fs.path.generic]].

Diff to HTML by rtfpessoa