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)