canonical_path_name(+Path, -CanonicalPath)

Path

A pathname (atom or string)

CanonicalPath

Canonical pathname for Path

Description

• An absolute path is returned. If a relative path is supplied, the path is prefixed with the current working directory. On Windows, a drive name is prefixed, if necessary.
• Leading '~' and environment variables (such as '$HOME') are substituted by the appropriate value. If this substitution is not possible (e.g. if the environment variable does not exist), nothing is changed.
• 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 and Mac OS X, 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 denotes an existing directory, the canonical path is terminated with a '/'.

Not all components of Path need to exist. The removal of aliasing is performed only on the part of the path that does exist.

The type of the returned CanonicalPath is the same as the type of 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