[ Operating System | Reference Manual | Alphabetic Index ]
canonical_path_name(+Path, -CanonicalPath)
Expand a path name into the full `canonical' form.
- Path
- A pathname (atom or string)
- CanonicalPath
- Canonical pathname for Path
Description
This predicate expands a given pathname, and converts it into the
`canonical' form of the pathname. The following are done to the path:
- A full path is returned. If a relative path is supplied, the
path is prefixed with the current working directory
- leading '~' and environment variables (such as '$HOME') are
substituted by the appropriate value. If this substitution is not
possible (e.g. if the envrionment variable does not exist), the
original path is returned unchanged.
- special sequences such as '.', '..', extra '/' are appropriately
removed/replaced.
- the non-aliased path is returned, i.e. any symbolic links are
replaced by the non-symbolic linked version of the path. On Windows,
where different cases of letters in path names are allowed but ignored
(so e.g. "foo" and "Foo" are aliases), the `normalised' version of the
name, using the letter cases when each file/directory was created, is
returned (not supported in older versions of Windows before 2000).
- if the path is a directory, a terminating '/' is always returned.
Path does not need to exist, and only the removal of aliasing is
performed on the part of the path that does exist.
CanonicalPath is always the same type as Path (string or atom). If Path
is empty, it is replaced by the current working directory.
The predicates canonical_path_name/2 and existing_file/4 are intended
as replacement for absolute_file_name/2 in previous releases. The
functionality of completing an incomplete name and returning an
absolute path of absolute_file_name/2 has been separated. The following
approximately implements the old absolute_file_name/2:
absolute_file_name(Rel, Abs) :-
(Rel == user ->
Abs == user % treat user specially
; get_flag(prolog_suffix, Sufs),
(existing_file(Rel, Sufs, [], ExtRel) -> true ; ExtRel = Rel),
canonical_path_name(ExtRel, Abs)
).
Modes and Determinism
- canonical_path_name(+, -) is det
Exceptions
- (5) type error
- Path is not a string or atom.
Examples
[eclipse]: canonical_path_name("file", Full). %cwd is /homes/tom
Full = "/homes/tom/file"
yes
[eclipse]: canonical_path_name(file, Full).
Full = '/homes/tom/file'
yes
[eclipse]: canonical_path_name("~/file", Full).
Full = "/homes/tom/file"
yes
[eclipse]: canonical_path_name('file/..', Full).
Full = '/homes/tom/'
[eclipse]: canonical_path_name('/users/tom', Full).
% /users/tom is a symbolic link for /homes/tom
Full = '/homes/tom/'
See Also
existing_file / 4, os_file_name / 2, pathname / 4