std::experi...::canonical(3)

💖 NAME 💖

From the C++ Standard Libary manual, bestie: std::experimental::filesystem::canonical — std::experimental::filesystem::canonical. The name is the name, and it's iconic. 💅

✨ Synopsis ✨

Okay so this is the filesystem TS flavor, defined in the header:

Defined in header <experimental/filesystem>

path canonical( const path& p, const path& base = current_path() ); (1) (filesystem TS)
path canonical( const path& p, error_code& ec );                    (2) (filesystem TS)
path canonical( const path& p, const path& base, error_code& ec );  (3) (filesystem TS)

🦋 Description 🦋

Converts path p to a canonical absolute path, i.e. an absolute path that has no dot, dot-dot elements or symbolic links.

If p is not an absolute path, the function behaves as if it is first made absolute by absolute(p, base) or absolute(p) for (2).

The path p must exist. Like, actually exist. No fake paths, bestie. 🫶

🎀 Parameters 🎀

• p — a path which may be absolute or relative to base, and which must be an existing path
• base — base path to be used in case p is relative
• ec — error code to store error status to

🌸 Return value 🌸

An absolute path that resolves to the same file as absolute(p, base) (or absolute(p) for (2)).

🔥 Exceptions 🔥

The overload that does not take an error_code& parameter throws filesystem_error on underlying OS API errors, constructed with p as the first argument, base as the second argument, and the OS error code as the error code argument. std::bad_alloc may be thrown if memory allocation fails.

The overload taking an 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. This overload has noexcept specification: noexcept.

This function is modeled after the POSIX realpath.

🌈 Example 🌈

// Run this code

#include <experimental/filesystem>
#include <iostream>
namespace fs = std::experimental::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"

👀 See also 👀

• path — represents a path (class)
• absolute — composes an absolute path
• system_complete — converts a path to an absolute path replicating OS-specific behavior (function)

🏷️ Categories 🏷️

• Noindexed pages
• unconditionally noexcept

🙈 Hidden categories 🙈

• Pages with unreviewed unconditional noexcept template
• Pages with unreviewed noexcept template

---

Cute sign-off time 🎀: source/version/date tea is http://cppreference.com · 2024.06.10 · std::experi...::canonical(3). That's the footer, bestie — periodt. 💅