[fs.op.funcs] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpi7_xfnpv/{from.md → to.md} +40 -43

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

@@ -106,11 +106,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:
@@ -173,21 +173,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
@@ -197,11 +197,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
@@ -235,22 +235,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
@@ -285,11 +285,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`.
@@ -342,21 +342,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*]
@@ -367,11 +367,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.
@@ -390,11 +390,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]].
@@ -410,39 +410,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>
@@ -453,11 +449,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.
@@ -501,11 +497,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.
@@ -722,11 +718,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
@@ -734,11 +730,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
@@ -756,11 +752,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]].
@@ -853,19 +849,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>
@@ -873,11 +870,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`.
@@ -892,11 +889,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.
@@ -919,11 +916,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>
@@ -952,11 +949,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)
@@ -975,17 +972,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`.
@@ -1048,19 +1045,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]].
@@ -1098,16 +1095,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]].

 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