[ Operating System | The ECLiPSe Built-In Predicates | 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.
- 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