| % File src/library/utils/man/normalizePath.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2016 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{normalizePath} |
| \alias{normalizePath} |
| \title{Express File Paths in Canonical Form} |
| \description{ |
| Convert file paths to canonical form for the platform, to display them |
| in a user-understandable form and so that relative and absolute paths can |
| be compared. |
| } |
| \usage{ |
| normalizePath(path, winslash = "\\\\", mustWork = NA) |
| } |
| \arguments{ |
| \item{path}{character vector of file paths.} |
| \item{winslash}{the separator to be used on Windows -- ignored |
| elsewhere. Must be one of \code{c("/", "\\\\")}.} |
| \item{mustWork}{logical: if \code{TRUE} then an error is given if the result |
| cannot be determined; if \code{NA} then a warning.} |
| } |
| \details{ |
| Tilde-expansion (see \code{\link{path.expand}}) is first done on |
| \code{paths}. |
| |
| Where the Unix-alike platform supports it attempts to turn paths into |
| absolute paths in their canonical form (no \samp{./}, \samp{../} nor |
| symbolic links). It relies on the POSIX system function |
| \code{realpath}: if the platform does not have that (we know of no |
| current example) then the result will be an absolute path but might |
| not be canonical. Even where \code{realpath} is used the canonical |
| path need not be unique, for example \emph{via} hard links or |
| multiple mounts. |
| |
| On Windows it converts relative paths to absolute paths, converts |
| short names for path elements to long names and ensures the separator |
| is that specified by \code{winslash}. It will match paths |
| case-insensitively and return the canonical case. |
| UTF-8-encoded paths not valid in the current locale can be used. |
| |
| \code{mustWork = FALSE} is useful for expressing paths for use in |
| messages. |
| } |
| |
| \note{ |
| The canonical form of paths may not be what you expect. For example, |
| on macOS absolute paths such as \file{/tmp} and \file{/var} are |
| symbolic links. On Linux, a path produced by bash process substitution is |
| a symbolic link (such as \file{/proc/fd/63}) to a pipe and there is no |
| canonical form of such path. |
| } |
| |
| \value{ |
| A character vector. |
| |
| If an input is not a real path the result is system-dependent (unless |
| \code{mustWork = TRUE}, when this should be an error). It will be |
| either the corresponding input element or a transformation of it into |
| an absolute path. |
| |
| Converting to an absolute file path can fail for a large number of |
| reasons. The most common are |
| \itemize{ |
| \item One of more components of the file path does not exist. |
| \item A component before the last is not a directory, or there is |
| insufficient permission to read the directory. |
| \item For a relative path, the current directory cannot be |
| determined. |
| \item A symbolic link points to a non-existent place or links form a |
| loop. |
| \item The canonicalized path would be exceed the maximum supported |
| length of a file path. |
| } |
| } |
| |
| #ifdef windows |
| \seealso{ |
| \code{\link{shortPathName}} |
| } |
| #endif |
| |
| \examples{\donttest{# random tempdir |
| cat(normalizePath(c(R.home(), tempdir())), sep = "\n") |
| }} |
| \keyword{ utilities } |