pub fn canonical(path: &Path) -> Result<PathBuf>Expand description
Resolve path to its canonical location, spelled the way the platform
ordinarily spells it.
This is std::fs::canonicalize everywhere except in what it does with
Windows’ answer. There, canonicalizing returns a verbatim path — the
\\?\ form, which exists so that names the ordinary rules cannot express
are still reachable. Two things follow from keeping that form. It is what
a person is shown, in place of the path they typed. And it is what gets
recorded as the identity of a scanned tree, so a later invocation that
arrives spelled ordinarily names a different tree and finds nothing of
what was recorded.
The prefix is therefore dropped whenever the remainder still names the same file, and kept whenever it does not — because for those paths the verbatim form is not decoration, it is the only spelling that works.
§Errors
Returns whatever std::fs::canonicalize returns: the path has to exist
and every component of it has to be traversable.