std::filesystem::canonical, std::filesystem::weakly_canonical

Defined in header `<filesystem>`
path canonical( const std::filesystem::path& p );	(1)	(since C++17)
path canonical( const std::filesystem::path& p, std::error_code& ec );	(2)	(since C++17)
path weakly_canonical(const std::filesystem::path& p);	(3)	(since C++17)
path weakly_canonical(const std::filesystem::path& p, std::error_code& ec);	(4)	(since C++17)

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, if any. The resulting path is in normal form.

Parameters

p	-	a path which may be absolute or relative, and which 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

The overload that does not take a std::error_code& parameter throws filesystem_error on underlying OS API errors, constructed with p as the first argument and the OS error code as the error code argument. std::bad_alloc may be thrown if memory allocation fails. The overload taking a std::error_code& parameter sets it 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().

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

Example

Run this code

#include <iostream>
#include <filesystem>
namespace fs = std::filesystem;
int main()
{
    fs::path p = fs::path("..") / ".." / "AppData";
    std::cout << "Current path is " << fs::current_path() << '\n'
              << "Canonical path for " << p << " is " << fs::canonical(p) << '\n';
}

Possible output:

Current path is "C:\Users\abcdef\AppData\Local\Temp"
Canonical path for "..\..\AppData" is "C:/Users\abcdef\AppData"

Language
Standard library headers
Concepts
Utilities library
Strings library
Containers library
Algorithms library
Iterators library
Numerics library
Input/output library
Localizations library
Regular expressions library (C++11)
Atomic operations library (C++11)
Thread support library (C++11)
Filesystem library (C++17)
Technical Specifications

path (C++17)	represents a path (class)
absolute (C++17)	composes an absolute path (function)
relativeproximate (C++17)	composes a relative path (function)