std::filesystem::canonical,std::filesystem::weakly_canonical(3)

NAME
std::filesystem::canonical,std::filesystem::weakly_canonical - std::filesystem::canonical,std::filesystem::weakly_canonical

Synopsis
   Defined in header <filesystem>
   path canonical( const std::filesystem::path& p ); (1) (since C++17)
   path canonical( const std::filesystem::path& p, (2) (since C++17)
                   std::error_code& ec );
   path weakly_canonical( const std::filesystem::path& p ); (3) (since C++17)
   path weakly_canonical( const std::filesystem::path& p, (4) (since C++17)
                        std::error_code& ec );
   1,2) Converts path p to a canonical absolute path, i.e. an absolute path that has no
   dot, dot-dot elements or symbolic links in its generic format representation. If p
   is not an absolute path, the function behaves as if it is first made absolute by
   std::filesystem::absolute(p). The path p must exist.
   3,4) Returns a path composed by operator/= from the result of calling canonical()
   with a path argument composed of the leading elements of p that exist (as determined
   by status(p) or status(p, ec)), if any, followed by the elements of p that do not
   exist. The resulting path is in normal form.

Parameters
   p - a path which may be absolute or relative; for canonical it must be an existing
        path
   ec - error code to store error status to

Return value
   1,2) An absolute path that resolves to the same file as
   std::filesystem::absolute(p).
   3,4) A normal path of the form canonical(x)/y, where x is a path composed of the
   longest leading sequence of elements in p that exist, and y is a path composed of
   the remaining trailing non-existent elements of p.

Exceptions
   Any overload not marked noexcept may throw std::bad_alloc if memory allocation
   fails.
   1,3) Throws std::filesystem::filesystem_error on underlying OS API errors,
   constructed with p as the first path argument and the OS error code as the error
   code argument.
   2,4) Sets a std::error_code& parameter to the OS API error code if an OS API call
   fails, and executes ec.clear() if no errors occur.

Notes
   The function canonical() is modeled after the POSIX realpath.
   The function weakly_canonical() was introduced to simplify operational semantics of
   relative().

Example
// Run this code
 #include <filesystem>
 #include <iostream>
 int main()
 {
     /* set up sandbox directories:
      a
      └── b
          ├── c1
          │ └── d <== current path
          └── c2
              └── e
     */
     auto old = std::filesystem::current_path();
     auto tmp = std::filesystem::temp_directory_path();
     std::filesystem::current_path(tmp);
     auto d1 = tmp / "a/b/c1/d";
     auto d2 = tmp / "a/b/c2/e";
     std::filesystem::create_directories(d1);
     std::filesystem::create_directories(d2);
     std::filesystem::current_path(d1);
     auto p1 = std::filesystem::path("../../c2/./e");
     auto p2 = std::filesystem::path("../no-such-file");
     std::cout << "Current path is "
               << std::filesystem::current_path() << '\n'
               << "Canonical path for " << p1 << " is "
               << std::filesystem::canonical(p1) << '\n'
               << "Weakly canonical path for " << p2 << " is "
               << std::filesystem::weakly_canonical(p2) << '\n';
     try
     {
         [[maybe_unused]] auto x_x = std::filesystem::canonical(p2);
         // NOT REACHED
     }
     catch (const std::exception& ex)
     {
         std::cout << "Canonical path for " << p2 << " threw exception:\n"
                   << ex.what() << '\n';
     }
     // cleanup
     std::filesystem::current_path(old);
     const auto count = std::filesystem::remove_all(tmp / "a");
     std::cout << "Deleted " << count << " files or directories.\n";
 }

Possible output:
 Current path is "/tmp/a/b/c1/d"
 Canonical path for "../../c2/./e" is "/tmp/a/b/c2/e"
 Weakly canonical path for "../no-such-file" is "/tmp/a/b/c1/no-such-file"
 Canonical path for "../no-such-file" threw exception:
 filesystem error: in canonical: No such file or directory [../no-such-file] [/tmp/a/b/c1/d]
 Deleted 6 files or directories.
   Defect reports
   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.
      DR Applied to Behavior as published Correct behavior
   LWG 2956 C++17 canonical has a spurious base parameter removed

See also
   path represents a path
   (C++17) (class)
   absolute composes an absolute path
   (C++17) (function)
   relative composes a relative path
   proximate (function)
   (C++17)