[fs.op.funcs] - C++17 → C++20

Files changed (1) hide show

tmp/tmpksulby87/{from.md → to.md} +139 -143

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

@@ -2,11 +2,11 @@
 Filesystem operation functions query or modify files, including
 directories, in external storage.
 [*Note 1*: Because hardware failures, network failures, file system
-races ([[fs.def.race]]), and many other kinds of errors occur
 frequently in file system operations, users should be aware that any
 filesystem operation function, no matter how apparently innocuous, may
 encounter an error; see  [[fs.err.report]]. — *end note*]
 #### Absolute <a id="fs.op.absolute">[[fs.op.absolute]]</a>
@@ -15,11 +15,11 @@ encounter an error; see  [[fs.err.report]]. — *end note*]
 path absolute(const path& p);
 path absolute(const path& p, error_code& ec);
 ```
 *Effects:* Composes an absolute path referencing the same file system
-location as `p` according to the operating system ([[fs.conform.os]]).
 *Returns:* The composed path. The signature with argument `ec` returns
 `path()` if an error occurs.
 [*Note 1*: For the returned path, `rp`, `rp.is_absolute()` is `true`
@@ -27,11 +27,11 @@ unless an error occurs. — *end note*]
 *Throws:* As specified in  [[fs.err.report]].
 [*Note 2*: To resolve symlinks, or perform other sanitization which
 might require queries to secondary storage, such as hard disks, consider
-`canonical` ([[fs.op.canonical]]). — *end note*]
 [*Note 3*: Implementations are strongly encouraged to not query
 secondary storage, and not consider `!exists(p)` an
 error. — *end note*]
@@ -41,22 +41,19 @@ simply `current_path()/p`. For Windows-based operating systems,
 `GetFullPathNameW`. — *end example*]
 #### Canonical <a id="fs.op.canonical">[[fs.op.canonical]]</a>
 ``` cpp
-path canonical(const path& p, const path& base = current_path());
 path canonical(const path& p, error_code& ec);
-path canonical(const path& p, const path& base, error_code& ec);
 ```
-*Effects:* Converts `p`, which must exist, to an absolute path that has
-no symbolic link, *dot*, or *dot-dot* elements in its pathname in the
-generic format.
 *Returns:* A path that refers to the same file system object as
-`absolute(p, base)`. For the overload without a `base` argument, `base`
-is `current_path()`. Signatures with argument `ec` return `path()` if an
 error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 *Remarks:* `!exists(p)` is an error.
@@ -68,23 +65,23 @@ void copy(const path& from, const path& to);
 ```
 *Effects:* Equivalent to `copy(from, to, copy_options::none)`.
 ``` cpp
-void copy(const path& from, const path& to, error_code& ec) noexcept;
 ```
 *Effects:* Equivalent to `copy(from, to, copy_options::none, ec)`.
 ``` cpp
 void copy(const path& from, const path& to, copy_options options);
 void copy(const path& from, const path& to, copy_options options,
-          error_code& ec) noexcept;
 ```
-*Requires:* At most one element from each option group
-([[fs.enum.copy.opts]]) is set in `options`.
 *Effects:* Before the first use of `f` and `t`:
 - If
   ``` cpp
@@ -105,17 +102,17 @@ void copy(const path& from, const path& to, copy_options options,
   `auto t = status(to)`.
 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)`, or
-  - `equivalent(from, to)`, or
-  - `is_other(f) || is_other(t)`, or
-  - `is_directory(f) && is_regular_file(t)`.
 - Otherwise, if `is_symlink(f)`, then:
   - If `(options & copy_options::skip_symlinks) != copy_options::none`
     then return.
   - Otherwise if
     ``` cpp
@@ -135,24 +132,36 @@ Effects are then as follows:
     `(options & copy_options::create_hard_links) != copy_options::none`,
     then create a hard link to the source file.
   - Otherwise, if `is_directory(t)`, then
     `copy_file(from, to/from.filename(), options)`.
   - Otherwise, `copy_file(from, to, options)`.
 - Otherwise, if
   ``` cpp
   is_directory(f) &&
   ((options & copy_options::recursive) != copy_options::none ||
    options == copy_options::none)
   ```
   then:
-  - If `!exists(t)`, then `create_directory(to, from)`.
   - Then, iterate over the files in `from`, as if by
     ``` cpp
     for (const directory_entry& x : directory_iterator(from))
-      copy(x.path(), to/x.path().filename(), options | copy_options::unspecified)
     ```
 - Otherwise, for the signature with argument `ec`, `ec.clear()`.
 - Otherwise, no effects.
 *Throws:* As specified in  [[fs.err.report]].
@@ -201,62 +210,61 @@ would result in:
     file3
 ```
 — *end example*]
-#### Copy file <a id="fs.op.copy_file">[[fs.op.copy_file]]</a>
 ``` cpp
 bool copy_file(const path& from, const path& to);
-bool copy_file(const path& from, const path& to, error_code& ec) noexcept;
 ```
 *Returns:* `copy_file(from, to, copy_options::none)` or
 `copy_file(from, to, copy_options::none, ec)`, respectively.
 *Throws:* As specified in  [[fs.err.report]].
 ``` cpp
 bool copy_file(const path& from, const path& to, copy_options options);
 bool copy_file(const path& from, const path& to, copy_options options,
-               error_code& ec) noexcept;
 ```
-*Requires:* At most one element from each option group
-([[fs.enum.copy.opts]]) is set in `options`.
 *Effects:* As follows:
-- Report a file already exists error as specified in  [[fs.err.report]]
- if:
-  - `!is_regular_file(from)`, or
-  - `exists(to)` and `!is_regular_file(to)`, or
-  - `exists(to)` and `equivalent(from, to)`, or
-  - `exists(to)` 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)`, 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
-    `last_write_time` function ([[fs.op.last_write_time]]).
 - Otherwise, no effects.
 *Returns:* `true` if the `from` file was copied, otherwise `false`. The
 signature with argument `ec` returns `false` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 *Complexity:* At most one direct or indirect invocation of `status(to)`.
-#### Copy symlink <a id="fs.op.copy_symlink">[[fs.op.copy_symlink]]</a>
 ``` cpp
 void copy_symlink(const path& existing_symlink, const path& new_symlink);
 void copy_symlink(const path& existing_symlink, const path& new_symlink,
                   error_code& ec) noexcept;
@@ -268,86 +276,78 @@ void copy_symlink(const path& existing_symlink, const path& new_symlink,
 respectively, where in each case *`function`* is `create_symlink` or
 `create_directory_symlink` as appropriate.
 *Throws:* As specified in  [[fs.err.report]].
-#### Create directories <a id="fs.op.create_directories">[[fs.op.create_directories]]</a>
 ``` cpp
 bool create_directories(const path& p);
-bool create_directories(const path& p, error_code& ec) noexcept;
 ```
-*Effects:* Establishes the postcondition by calling `create_directory()`
-for any element of `p` that does not exist.
-*Postconditions:* `is_directory(p)`.
-*Returns:* `true` if a new directory was created, otherwise `false`. The
-signature with argument `ec` returns `false` if an error occurs.
-*Throws:* As specified in  [[fs.err.report]].
-*Complexity:* 𝑂(n) where *n* is the number of elements of `p` that do
 not exist.
-#### Create directory <a id="fs.op.create_directory">[[fs.op.create_directory]]</a>
 ``` cpp
 bool create_directory(const path& p);
 bool create_directory(const path& p, error_code& ec) noexcept;
 ```
-*Effects:* Establishes the postcondition by attempting to create the
-directory `p` resolves to, as if by POSIX `mkdir()` with a second
-argument of `static_cast<int>(perms::all)`. Creation failure because `p`
-resolves to an existing directory shall not be treated as an error.
-*Postconditions:* `is_directory(p)`.
-*Returns:* `true` if a new directory was created, otherwise `false`. The
-signature with argument `ec` returns `false` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 ``` cpp
 bool create_directory(const path& p, const path& existing_p);
 bool create_directory(const path& p, const path& existing_p, error_code& ec) noexcept;
 ```
-*Effects:* Establishes the postcondition by attempting to create the
-directory `p` resolves to, with attributes copied from directory
-`existing_p`. The set of attributes copied is operating system
-dependent. Creation failure because `p` resolves to an existing
-directory shall not be treated as an error.
 [*Note 1*: For POSIX-based operating systems, the attributes are those
 copied by native API `stat(existing_p.c_str(), &attributes_stat)`
 followed by `mkdir(p.c_str(), attributes_stat.st_mode)`. For
 Windows-based operating systems, the attributes are those copied by
 native API
 `CreateDirectoryExW(existing_p.c_str(), p.c_str(), 0)`. — *end note*]
-*Postconditions:* `is_directory(p)`.
-*Returns:* `true` if a new directory was created, otherwise `false`. The
-signature with argument `ec` returns `false` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
-#### Create directory symlink <a id="fs.op.create_dir_symlk">[[fs.op.create_dir_symlk]]</a>
 ``` cpp
 void create_directory_symlink(const path& to, const path& new_symlink);
 void create_directory_symlink(const path& to, const path& new_symlink,
                               error_code& ec) noexcept;
 ```
 *Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
-*Postconditions:* `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. Portable code should use
@@ -357,21 +357,21 @@ that the link is to a directory. Portable code should use
 [*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*]
-#### Create hard link <a id="fs.op.create_hard_lk">[[fs.op.create_hard_lk]]</a>
 ``` cpp
 void create_hard_link(const path& to, const path& new_hard_link);
 void create_hard_link(const path& to, const path& new_hard_link,
                                       error_code& ec) noexcept;
 ```
 *Effects:* Establishes the postcondition, as if by POSIX `link()`.
-*Postconditions:*
 - `exists(to) && exists(new_hard_link) && equivalent(to, new_hard_link)`
 - The contents of the file or directory `to` resolves to are unchanged.
 *Throws:* As specified in  [[fs.err.report]].
@@ -380,31 +380,31 @@ void create_hard_link(const path& to, const path& new_hard_link,
 support them only for regular files. Some file systems (such as the FAT
 file system) do not support hard links regardless of the operating
 system. Some file systems limit the number of links per
 file. — *end note*]
-#### Create symlink <a id="fs.op.create_symlink">[[fs.op.create_symlink]]</a>
 ``` cpp
 void create_symlink(const path& to, const path& new_symlink);
 void create_symlink(const path& to, const path& new_symlink,
                     error_code& ec) noexcept;
 ```
 *Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
-*Postconditions:* `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 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*]
-#### Current path <a id="fs.op.current_path">[[fs.op.current_path]]</a>
 ``` cpp
 path current_path();
 path current_path(error_code& ec);
 ```
@@ -422,22 +422,21 @@ 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. It may be changed unexpectedly by a
-third-party or system library functions, or by another
-thread. — *end note*]
 ``` cpp
 void current_path(const path& p);
 void current_path(const path& p, error_code& ec) noexcept;
 ```
 *Effects:* Establishes the postcondition, as if by POSIX `chdir()`.
-*Postconditions:* `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. It may be changed unexpectedly by a third-party or system
@@ -448,26 +447,22 @@ library functions, or by another thread. — *end note*]
 ``` cpp
 bool equivalent(const path& p1, const path& p2);
 bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
 ```
-Let `s1` and `s2` be `file_status`s, determined as if by `status(p1)`
-and `status(p2)`, respectively.
-*Effects:* Determines `s1` and `s2`. If
-`(!exists(s1) && !exists(s2)) || (is_other(s1) && is_other(s2))` an
-error is reported ([[fs.err.report]]).
-*Returns:* `true`, if `s1 == s2` and `p1` and `p2` resolve to the same
-file system entity, else `false`. The signature with argument `ec`
-returns `false` if an error occurs.
 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.
-This is determined as if by the values of the POSIX `stat` structure,
-obtained as if by `stat()` for the two paths, having equal `st_dev`
-values and equal `st_ino` values.
 *Throws:* As specified in  [[fs.err.report]].
 #### Exists <a id="fs.op.exists">[[fs.op.exists]]</a>
@@ -490,31 +485,33 @@ Let `s` be a `file_status`, determined as if by `status(p)` or
 *Returns:* `exists(s)`.
 *Throws:* As specified in  [[fs.err.report]].
-#### File size <a id="fs.op.file_size">[[fs.op.file_size]]</a>
 ``` cpp
 uintmax_t file_size(const path& p);
 uintmax_t file_size(const path& p, error_code& ec) noexcept;
 ```
 *Returns:*
-- If `!exists(p)` an error is reported ([[fs.err.report]]).
-- Otherwise, 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`
-  structure 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.
 *Throws:* As specified in  [[fs.err.report]].
-#### Hard link count <a id="fs.op.hard_lk_ct">[[fs.op.hard_lk_ct]]</a>
 ``` cpp
 uintmax_t hard_link_count(const path& p);
 uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
 ```
@@ -522,11 +519,11 @@ uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
 *Returns:* The number of hard links for `p`. The signature with argument
 `ec` returns `static_cast<uintmax_t>(-1)` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
-#### Is block file <a id="fs.op.is_block_file">[[fs.op.is_block_file]]</a>
 ``` cpp
 bool is_block_file(file_status s) noexcept;
 ```
@@ -541,11 +538,11 @@ bool is_block_file(const path& p, error_code& ec) noexcept;
 respectively. The signature with argument `ec` returns `false` if an
 error occurs.
 *Throws:* As specified in  [[fs.err.report]].
-#### Is character file <a id="fs.op.is_char_file">[[fs.op.is_char_file]]</a>
 ``` cpp
 bool is_character_file(file_status s) noexcept;
 ```
@@ -560,11 +557,11 @@ bool is_character_file(const path& p, error_code& ec) noexcept;
 `is_character_file(status(p, ec))`, respectively.
 The signature with argument `ec` returns `false` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
-#### Is directory <a id="fs.op.is_directory">[[fs.op.is_directory]]</a>
 ``` cpp
 bool is_directory(file_status s) noexcept;
 ```
@@ -579,15 +576,15 @@ bool is_directory(const path& p, error_code& ec) noexcept;
 respectively. The signature with argument `ec` returns `false` if an
 error occurs.
 *Throws:* As specified in  [[fs.err.report]].
-#### Is empty <a id="fs.op.is_empty">[[fs.op.is_empty]]</a>
 ``` cpp
 bool is_empty(const path& p);
-bool is_empty(const path& p, error_code& ec) noexcept;
 ```
 *Effects:*
 - Determine `file_status s`, as if by `status(p)` or `status(p, ec)`,
@@ -607,11 +604,11 @@ bool is_empty(const path& p, error_code& ec) noexcept;
     occurred.
   - Otherwise, return `sz == 0`.
 *Throws:* As specified in  [[fs.err.report]].
-#### Is fifo <a id="fs.op.is_fifo">[[fs.op.is_fifo]]</a>
 ``` cpp
 bool is_fifo(file_status s) noexcept;
 ```
@@ -626,11 +623,11 @@ bool is_fifo(const path& p, error_code& ec) noexcept;
 respectively. The signature with argument `ec` returns `false` if an
 error occurs.
 *Throws:* As specified in  [[fs.err.report]].
-#### Is other <a id="fs.op.is_other">[[fs.op.is_other]]</a>
 ``` cpp
 bool is_other(file_status s) noexcept;
 ```
@@ -646,11 +643,11 @@ bool is_other(const path& p, error_code& ec) noexcept;
 respectively. The signature with argument `ec` returns `false` if an
 error occurs.
 *Throws:* As specified in  [[fs.err.report]].
-#### Is regular file <a id="fs.op.is_regular_file">[[fs.op.is_regular_file]]</a>
 ``` cpp
 bool is_regular_file(file_status s) noexcept;
 ```
@@ -661,11 +658,11 @@ bool is_regular_file(const path& p);
 ```
 *Returns:* `is_regular_file(status(p))`.
 *Throws:* `filesystem_error` if `status(p)` would throw
-`filesystem_error.`
 ``` cpp
 bool is_regular_file(const path& p, error_code& ec) noexcept;
 ```
@@ -676,11 +673,11 @@ bool is_regular_file(const path& p, error_code& ec) noexcept;
 between cases, call the `status` function directly. — *end note*]
 *Returns:* `is_regular_file(status(p, ec))`. Returns `false` if an error
 occurs.
-#### Is socket <a id="fs.op.is_socket">[[fs.op.is_socket]]</a>
 ``` cpp
 bool is_socket(file_status s) noexcept;
 ```
@@ -695,11 +692,11 @@ bool is_socket(const path& p, error_code& ec) noexcept;
 respectively. The signature with argument `ec` returns `false` if an
 error occurs.
 *Throws:* As specified in  [[fs.err.report]].
-#### Is symlink <a id="fs.op.is_symlink">[[fs.op.is_symlink]]</a>
 ``` cpp
 bool is_symlink(file_status s) noexcept;
 ```
@@ -714,20 +711,20 @@ bool is_symlink(const path& p, error_code& ec) noexcept;
 `is_symlink(symlink_status(p, ec))`, respectively. The signature with
 argument `ec` returns `false` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
-#### Last write time <a id="fs.op.last_write_time">[[fs.op.last_write_time]]</a>
 ``` cpp
 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
 `file_time_type::min()` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 ``` cpp
@@ -751,11 +748,11 @@ granularity. — *end note*]
 void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
 void permissions(const path& p, perms prms, error_code& ec) noexcept;
 void permissions(const path& p, perms prms, perm_options opts, error_code& ec);
 ```
-*Requires:* Exactly one of the `perm_options` constants `replace`,
 `add`, or `remove` is present in `opts`.
 *Remarks:* The second signature behaves as if it had an additional
 parameter `perm_options` `opts` with an argument of
 `perm_options::replace`.
@@ -799,11 +796,11 @@ weakly_canonical(p, ec).lexically_proximate(weakly_canonical(base, ec));
 or `path()` at the first error occurrence, if any.
 *Throws:* As specified in  [[fs.err.report]].
-#### Read symlink <a id="fs.op.read_symlink">[[fs.op.read_symlink]]</a>
 ``` cpp
 path read_symlink(const path& p);
 path read_symlink(const path& p, error_code& ec);
 ```
@@ -859,31 +856,31 @@ bool remove(const path& p, error_code& ec) noexcept;
 as if by POSIX `remove()`.
 [*Note 1*: A symbolic link is itself removed, rather than the file it
 resolves to. — *end note*]
-*Postconditions:* `!exists(symlink_status(p))`.
 *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>
 ``` cpp
 uintmax_t remove_all(const path& p);
-uintmax_t remove_all(const path& p, error_code& ec) noexcept;
 ```
 *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*]
-*Postconditions:* `!exists(symlink_status(p))`.
 *Returns:* The number of files removed. The signature with argument `ec`
 returns `static_cast< uintmax_t>(-1)` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
@@ -912,23 +909,22 @@ A symbolic link is itself renamed, rather than the file it resolves to.
 — *end note*]
 *Throws:* As specified in  [[fs.err.report]].
-#### Resize file <a id="fs.op.resize_file">[[fs.op.resize_file]]</a>
 ``` cpp
 void resize_file(const path& p, uintmax_t new_size);
 void resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
 ```
-*Postconditions:* `file_size(p) == new_size`.
 *Throws:* As specified in  [[fs.err.report]].
-*Remarks:* Achieves its postconditions as if by POSIX `truncate()`.
 #### Space <a id="fs.op.space">[[fs.op.space]]</a>
 ``` cpp
 space_info space(const path& p);
 space_info space(const path& p, error_code& ec) noexcept;
@@ -1027,27 +1023,27 @@ determined as if by converting the `st_mode` member of the obtained
   - Otherwise, if the attributes indicate a fifo or pipe file, as if by
     POSIX `S_ISFIFO`, returns `file_status(file_type::fifo, prms)`.
   - Otherwise, if the attributes indicate a socket, as if by POSIX
     `S_ISSOCK`, returns `file_status(file_type::socket, prms)`.
   - Otherwise, if the attributes indicate an implementation-defined file
-    type ([[fs.enum.file_type]]), returns
     `file_status(file_type::`*`A`*`, prms)`, where *A* is the constant
     for the *implementation-defined* file type.
   - Otherwise, returns `file_status(file_type::unknown, prms)`.
 *Remarks:* If a symbolic link is encountered during pathname resolution,
 pathname resolution continues using the contents of the symbolic link.
-#### Status known <a id="fs.op.status_known">[[fs.op.status_known]]</a>
 ``` cpp
 bool status_known(file_status s) noexcept;
 ```
 *Returns:* `s.type() != file_type::none`.
-#### Symlink status <a id="fs.op.symlink_status">[[fs.op.symlink_status]]</a>
 ``` cpp
 file_status symlink_status(const path& p);
 file_status symlink_status(const path& p, error_code& ec) noexcept;
 ```
@@ -1067,20 +1063,23 @@ indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
 *Remarks:* Pathname resolution terminates if `p` names a symbolic link.
 *Throws:* As specified in  [[fs.err.report]].
-#### Temporary directory path <a id="fs.op.temp_dir_path">[[fs.op.temp_dir_path]]</a>
 ``` cpp
 path temp_directory_path();
 path temp_directory_path(error_code& ec);
 ```
-*Returns:* An unspecifed directory path suitable for temporary files. An
-error shall be reported if `!exists(p) || !is_directory(p)`, where `p`
-is the path to be returned. The signature with argument `ec` returns
 `path()` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 [*Example 1*: For POSIX-based operating systems, an implementation
@@ -1088,34 +1087,31 @@ might return the path supplied by the first environment variable found
 in the list TMPDIR, TMP, TEMP, TEMPDIR, or if none of these are found,
 `"/tmp"`. For Windows-based operating systems, an implementation might
 return the path reported by the Windows `GetTempPath` API
 function. — *end example*]
-#### Weakly canonical <a id="fs.op.weakly_canonical">[[fs.op.weakly_canonical]]</a>
 ``` cpp
 path weakly_canonical(const path& p);
 path weakly_canonical(const path& p, error_code& ec);
 ```
 *Returns:* `p` with symlinks resolved and the result
-normalized ([[fs.def.normal.form]]).
 *Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
 determine existence, return a path composed by `operator/=` from the
-result of calling `canonical()` without a `base` argument and 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.
-*Postconditions:* The returned path is in normal
-form ([[fs.def.normal.form]]).
-*Remarks:* Implementations are encouraged to avoid unnecessary
-normalization such as when `canonical` has already been called on the
-entirety of `p`.
 *Throws:* As specified in  [[fs.err.report]].

 Filesystem operation functions query or modify files, including
 directories, in external storage.
 [*Note 1*: Because hardware failures, network failures, file system
+races [[fs.race.behavior]], and many other kinds of errors occur
 frequently in file system operations, users should be aware that any
 filesystem operation function, no matter how apparently innocuous, may
 encounter an error; see  [[fs.err.report]]. — *end note*]
 #### Absolute <a id="fs.op.absolute">[[fs.op.absolute]]</a>
 path absolute(const path& p);
 path absolute(const path& p, error_code& ec);
 ```
 *Effects:* Composes an absolute path referencing the same file system
+location as `p` according to the operating system [[fs.conform.os]].
 *Returns:* The composed path. The signature with argument `ec` returns
 `path()` if an error occurs.
 [*Note 1*: For the returned path, `rp`, `rp.is_absolute()` is `true`
 *Throws:* As specified in  [[fs.err.report]].
 [*Note 2*: To resolve symlinks, or perform other sanitization which
 might require queries to secondary storage, such as hard disks, consider
+`canonical` [[fs.op.canonical]]. — *end note*]
 [*Note 3*: Implementations are strongly encouraged to not query
 secondary storage, and not consider `!exists(p)` an
 error. — *end note*]
 `GetFullPathNameW`. — *end example*]
 #### Canonical <a id="fs.op.canonical">[[fs.op.canonical]]</a>
 ``` cpp
+path canonical(const path& p);
 path canonical(const path& p, error_code& ec);
 ```
+*Effects:* Converts `p` to an absolute path that has no symbolic link,
+dot, or dot-dot elements in its pathname in the generic format.
 *Returns:* A path that refers to the same file system object as
+`absolute(p)`. The signature with argument `ec` returns `path()` if an
 error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 *Remarks:* `!exists(p)` is an error.
 ```
 *Effects:* Equivalent to `copy(from, to, copy_options::none)`.
 ``` cpp
+void copy(const path& from, const path& to, error_code& ec);
 ```
 *Effects:* Equivalent to `copy(from, to, copy_options::none, ec)`.
 ``` cpp
 void copy(const path& from, const path& to, copy_options options);
 void copy(const path& from, const path& to, copy_options options,
+          error_code& ec);
 ```
+*Preconditions:* At most one element from each option
+group [[fs.enum.copy.opts]] is set in `options`.
 *Effects:* Before the first use of `f` and `t`:
 - If
   ``` cpp
   `auto t = status(to)`.
 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:
   - If `(options & copy_options::skip_symlinks) != copy_options::none`
     then return.
   - Otherwise if
     ``` cpp
     `(options & copy_options::create_hard_links) != copy_options::none`,
     then create a hard link to the source file.
   - Otherwise, if `is_directory(t)`, then
     `copy_file(from, to/from.filename(), options)`.
   - Otherwise, `copy_file(from, to, options)`.
+- Otherwise, if
+  ``` cpp
+  is_directory(f) &&
+  (options & copy_options::create_symlinks) != copy_options::none
+  ```
+  then report an error with an `error_code` argument equal to
+  `make_error_code(errc::is_a_directory)`.
 - Otherwise, if
   ``` cpp
   is_directory(f) &&
   ((options & copy_options::recursive) != copy_options::none ||
    options == copy_options::none)
   ```
   then:
+  - If `exists(t)` is `false`, then `create_directory(to, from)`.
   - Then, iterate over the files in `from`, as if by
     ``` cpp
     for (const directory_entry& x : directory_iterator(from))
+      copy(x.path(), to/x.path().filename(),
+           options | copy_options::in-recursive-copy);
     ```
+    where *`in-recursive-copy`* is a bitmask element of `copy_options`
+    that is not one of the elements in  [[fs.enum.copy.opts]].
 - Otherwise, for the signature with argument `ec`, `ec.clear()`.
 - Otherwise, no effects.
 *Throws:* As specified in  [[fs.err.report]].
     file3
 ```
 — *end example*]
+#### Copy file <a id="fs.op.copy.file">[[fs.op.copy.file]]</a>
 ``` cpp
 bool copy_file(const path& from, const path& to);
+bool copy_file(const path& from, const path& to, error_code& ec);
 ```
 *Returns:* `copy_file(from, to, copy_options::none)` or
 `copy_file(from, to, copy_options::none, ec)`, respectively.
 *Throws:* As specified in  [[fs.err.report]].
 ``` cpp
 bool copy_file(const path& from, const path& to, copy_options options);
 bool copy_file(const path& from, const path& to, copy_options options,
+               error_code& ec);
 ```
+*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
+    `last_write_time` function [[fs.op.last.write.time]].
 - Otherwise, no effects.
 *Returns:* `true` if the `from` file was copied, otherwise `false`. The
 signature with argument `ec` returns `false` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 *Complexity:* At most one direct or indirect invocation of `status(to)`.
+#### Copy symlink <a id="fs.op.copy.symlink">[[fs.op.copy.symlink]]</a>
 ``` cpp
 void copy_symlink(const path& existing_symlink, const path& new_symlink);
 void copy_symlink(const path& existing_symlink, const path& new_symlink,
                   error_code& ec) noexcept;
 respectively, where in each case *`function`* is `create_symlink` or
 `create_directory_symlink` as appropriate.
 *Throws:* As specified in  [[fs.err.report]].
+#### Create directories <a id="fs.op.create.directories">[[fs.op.create.directories]]</a>
 ``` cpp
 bool create_directories(const path& p);
+bool 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`.
+*Throws:* As specified in  [[fs.err.report]].
+*Complexity:* 𝑂(n) where *n* is the number of elements of `p`.
+#### Create directory <a id="fs.op.create.directory">[[fs.op.create.directory]]</a>
 ``` cpp
 bool create_directory(const path& p);
 bool create_directory(const path& p, error_code& ec) noexcept;
 ```
+*Effects:* Creates the directory `p` resolves to, as if by POSIX `mkdir`
+with a second argument of `static_cast<int>(perms::all)`. If `mkdir`
+fails because `p` resolves to an existing directory, no error is
+reported. Otherwise on failure an error is reported.
+*Returns:* `true` if a new directory was created, otherwise `false`.
 *Throws:* As specified in  [[fs.err.report]].
 ``` cpp
 bool create_directory(const path& p, const path& existing_p);
 bool create_directory(const path& p, const path& existing_p, error_code& ec) noexcept;
 ```
+*Effects:* Creates the directory `p` resolves to, with attributes copied
+from directory `existing_p`. The set of attributes copied is operating
+system dependent. If `mkdir` fails because `p` resolves to an existing
+directory, no error is reported. Otherwise on failure an error is
+reported.
 [*Note 1*: For POSIX-based operating systems, the attributes are those
 copied by native API `stat(existing_p.c_str(), &attributes_stat)`
 followed by `mkdir(p.c_str(), attributes_stat.st_mode)`. For
 Windows-based operating systems, the attributes are those copied by
 native API
 `CreateDirectoryExW(existing_p.c_str(), p.c_str(), 0)`. — *end note*]
+*Returns:* `true` if a new directory was created with attributes copied
+from directory `existing_p`, otherwise `false`.
 *Throws:* As specified in  [[fs.err.report]].
+#### Create directory symlink <a id="fs.op.create.dir.symlk">[[fs.op.create.dir.symlk]]</a>
 ``` cpp
 void create_directory_symlink(const path& to, const path& new_symlink);
 void 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. Portable code should use
 [*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*]
+#### Create hard link <a id="fs.op.create.hard.lk">[[fs.op.create.hard.lk]]</a>
 ``` cpp
 void create_hard_link(const path& to, const path& new_hard_link);
 void 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.
 *Throws:* As specified in  [[fs.err.report]].
 support them only for regular files. Some file systems (such as the FAT
 file system) do not support hard links regardless of the operating
 system. Some file systems limit the number of links per
 file. — *end note*]
+#### Create symlink <a id="fs.op.create.symlink">[[fs.op.create.symlink]]</a>
 ``` cpp
 void create_symlink(const path& to, const path& new_symlink);
 void 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]].
 [*Note 1*: 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*]
+#### Current path <a id="fs.op.current.path">[[fs.op.current.path]]</a>
 ``` cpp
 path current_path();
 path current_path(error_code& ec);
 ```
 [*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. It may be changed unexpectedly by third-party
+or system library functions, or by another thread. — *end note*]
 ``` cpp
 void current_path(const path& p);
 void 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. It may be changed unexpectedly by a third-party or system
 ``` cpp
 bool equivalent(const path& p1, const path& p2);
 bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
 ```
+*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.
 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*]
+*Remarks:* `!exists(p1) || !exists(p2)` is an error.
 *Throws:* As specified in  [[fs.err.report]].
 #### Exists <a id="fs.op.exists">[[fs.op.exists]]</a>
 *Returns:* `exists(s)`.
 *Throws:* As specified in  [[fs.err.report]].
+#### File size <a id="fs.op.file.size">[[fs.op.file.size]]</a>
 ``` cpp
 uintmax_t file_size(const path& p);
 uintmax_t file_size(const path& p, error_code& ec) noexcept;
 ```
+*Effects:* If `exists(p)` is `false`, an error is
+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.
 *Throws:* As specified in  [[fs.err.report]].
+#### Hard link count <a id="fs.op.hard.lk.ct">[[fs.op.hard.lk.ct]]</a>
 ``` cpp
 uintmax_t hard_link_count(const path& p);
 uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
 ```
 *Returns:* The number of hard links for `p`. The signature with argument
 `ec` returns `static_cast<uintmax_t>(-1)` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
+#### Is block file <a id="fs.op.is.block.file">[[fs.op.is.block.file]]</a>
 ``` cpp
 bool is_block_file(file_status s) noexcept;
 ```
 respectively. The signature with argument `ec` returns `false` if an
 error occurs.
 *Throws:* As specified in  [[fs.err.report]].
+#### Is character file <a id="fs.op.is.char.file">[[fs.op.is.char.file]]</a>
 ``` cpp
 bool is_character_file(file_status s) noexcept;
 ```
 `is_character_file(status(p, ec))`, respectively.
 The signature with argument `ec` returns `false` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
+#### Is directory <a id="fs.op.is.directory">[[fs.op.is.directory]]</a>
 ``` cpp
 bool is_directory(file_status s) noexcept;
 ```
 respectively. The signature with argument `ec` returns `false` if an
 error occurs.
 *Throws:* As specified in  [[fs.err.report]].
+#### Is empty <a id="fs.op.is.empty">[[fs.op.is.empty]]</a>
 ``` cpp
 bool is_empty(const path& p);
+bool is_empty(const path& p, error_code& ec);
 ```
 *Effects:*
 - Determine `file_status s`, as if by `status(p)` or `status(p, ec)`,
     occurred.
   - Otherwise, return `sz == 0`.
 *Throws:* As specified in  [[fs.err.report]].
+#### Is fifo <a id="fs.op.is.fifo">[[fs.op.is.fifo]]</a>
 ``` cpp
 bool is_fifo(file_status s) noexcept;
 ```
 respectively. The signature with argument `ec` returns `false` if an
 error occurs.
 *Throws:* As specified in  [[fs.err.report]].
+#### Is other <a id="fs.op.is.other">[[fs.op.is.other]]</a>
 ``` cpp
 bool is_other(file_status s) noexcept;
 ```
 respectively. The signature with argument `ec` returns `false` if an
 error occurs.
 *Throws:* As specified in  [[fs.err.report]].
+#### Is regular file <a id="fs.op.is.regular.file">[[fs.op.is.regular.file]]</a>
 ``` cpp
 bool is_regular_file(file_status s) noexcept;
 ```
 ```
 *Returns:* `is_regular_file(status(p))`.
 *Throws:* `filesystem_error` if `status(p)` would throw
+`filesystem_error`.
 ``` cpp
 bool is_regular_file(const path& p, error_code& ec) noexcept;
 ```
 between cases, call the `status` function directly. — *end note*]
 *Returns:* `is_regular_file(status(p, ec))`. Returns `false` if an error
 occurs.
+#### Is socket <a id="fs.op.is.socket">[[fs.op.is.socket]]</a>
 ``` cpp
 bool is_socket(file_status s) noexcept;
 ```
 respectively. The signature with argument `ec` returns `false` if an
 error occurs.
 *Throws:* As specified in  [[fs.err.report]].
+#### Is symlink <a id="fs.op.is.symlink">[[fs.op.is.symlink]]</a>
 ``` cpp
 bool is_symlink(file_status s) noexcept;
 ```
 `is_symlink(symlink_status(p, ec))`, respectively. The signature with
 argument `ec` returns `false` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
+#### Last write time <a id="fs.op.last.write.time">[[fs.op.last.write.time]]</a>
 ``` cpp
 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` 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 permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
 void permissions(const path& p, perms prms, error_code& ec) noexcept;
 void permissions(const path& p, perms prms, perm_options opts, error_code& ec);
 ```
+*Preconditions:* Exactly one of the `perm_options` constants `replace`,
 `add`, or `remove` is present in `opts`.
 *Remarks:* The second signature behaves as if it had an additional
 parameter `perm_options` `opts` with an argument of
 `perm_options::replace`.
 or `path()` at the first error occurrence, if any.
 *Throws:* As specified in  [[fs.err.report]].
+#### Read symlink <a id="fs.op.read.symlink">[[fs.op.read.symlink]]</a>
 ``` cpp
 path read_symlink(const path& p);
 path read_symlink(const path& p, error_code& ec);
 ```
 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>
 ``` cpp
 uintmax_t remove_all(const path& p);
+uintmax_t 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`.
 *Returns:* The number of files removed. The signature with argument `ec`
 returns `static_cast< uintmax_t>(-1)` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 — *end note*]
 *Throws:* As specified in  [[fs.err.report]].
+#### Resize file <a id="fs.op.resize.file">[[fs.op.resize.file]]</a>
 ``` cpp
 void resize_file(const path& p, uintmax_t new_size);
 void 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
 space_info space(const path& p);
 space_info space(const path& p, error_code& ec) noexcept;
   - Otherwise, if the attributes indicate a fifo or pipe file, as if by
     POSIX `S_ISFIFO`, returns `file_status(file_type::fifo, prms)`.
   - Otherwise, if the attributes indicate a socket, as if by POSIX
     `S_ISSOCK`, returns `file_status(file_type::socket, prms)`.
   - Otherwise, if the attributes indicate an implementation-defined file
+    type [[fs.enum.file.type]], returns
     `file_status(file_type::`*`A`*`, prms)`, where *A* is the constant
     for the *implementation-defined* file type.
   - Otherwise, returns `file_status(file_type::unknown, prms)`.
 *Remarks:* If a symbolic link is encountered during pathname resolution,
 pathname resolution continues using the contents of the symbolic link.
+#### Status known <a id="fs.op.status.known">[[fs.op.status.known]]</a>
 ``` cpp
 bool status_known(file_status s) noexcept;
 ```
 *Returns:* `s.type() != file_type::none`.
+#### Symlink status <a id="fs.op.symlink.status">[[fs.op.symlink.status]]</a>
 ``` cpp
 file_status symlink_status(const path& p);
 file_status symlink_status(const path& p, error_code& ec) noexcept;
 ```
 *Remarks:* Pathname resolution terminates if `p` names a symbolic link.
 *Throws:* As specified in  [[fs.err.report]].
+#### Temporary directory path <a id="fs.op.temp.dir.path">[[fs.op.temp.dir.path]]</a>
 ``` cpp
 path temp_directory_path();
 path temp_directory_path(error_code& ec);
 ```
+Let `p` be an unspecified directory path suitable for temporary files.
+*Effects:* If `exists(p)` is `false` or `is_directory(p)` is `false`, an
+error is reported [[fs.err.report]].
+*Returns:* The path `p`. The signature with argument `ec` returns
 `path()` if an error occurs.
 *Throws:* As specified in  [[fs.err.report]].
 [*Example 1*: For POSIX-based operating systems, an implementation
 in the list TMPDIR, TMP, TEMP, TEMPDIR, or if none of these are found,
 `"/tmp"`. For Windows-based operating systems, an implementation might
 return the path reported by the Windows `GetTempPath` API
 function. — *end example*]
+#### Weakly canonical <a id="fs.op.weakly.canonical">[[fs.op.weakly.canonical]]</a>
 ``` cpp
 path weakly_canonical(const path& p);
 path weakly_canonical(const path& p, error_code& ec);
 ```
 *Returns:* `p` with symlinks resolved and the result
+normalized [[fs.path.generic]].
 *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]].
+*Remarks:* Implementations should avoid unnecessary normalization such
+as when `canonical` has already been called on the entirety of `p`.
 *Throws:* As specified in  [[fs.err.report]].

Diff to HTML by rtfpessoa