Go to the previous, next section.
Expansion of a file name means converting a relative file name to an absolute one. Since this is done relative to a default directory, you must specify the default directory name as well as the file name to be expanded. Expansion also simplifies file names by eliminating redundancies such as `./' and `name/../'.
Function: expand-file-name filename &optional directory
This function converts filename to an absolute file name. If
directory is supplied, it is the directory to start with if
filename is relative. (The value of directory should itself
be an absolute, expanded file name; it should not start with `~'.)
Otherwise, the current buffer's value of default-directory is
used. For example:
(expand-file-name "foo")
=> "/xcssun/users/rms/lewis/foo"
(expand-file-name "../foo")
=> "/xcssun/users/rms/foo"
(expand-file-name "foo" "/usr/spool/")
=> "/usr/spool/foo"
(expand-file-name "$HOME/foo")
=> "/xcssun/users/rms/lewis/$HOME/foo"
Filenames containing `.' or `..' are simplified to their canonical form:
(expand-file-name "bar/../foo")
=> "/xcssun/users/rms/lewis/foo"
`~/' is expanded into the user's home directory. A `/' or `~' following a `/' is taken to be the start of an absolute file name that overrides what precedes it, so everything before that `/' or `~' is deleted. For example:
(expand-file-name
"/a1/gnu//usr/local/lib/emacs/etc/MACHINES")
=> "/usr/local/lib/emacs/etc/MACHINES"
(expand-file-name "/a1/gnu/~/foo")
=> "/xcssun/users/rms/foo"
In both cases, `/a1/gnu/' is discarded because an absolute file name follows it.
Note that expand-file-name does not expand environment
variables; that is done only by substitute-in-file-name.
Function: file-relative-name filename directory
This function does the inverse of expansion--it tries to return a relative name which is equivalent to filename when interpreted relative to directory. (If such a relative name would be longer than the absolute name, it returns the absolute name instead.)
(file-relative-name "/foo/bar" "/foo/")
=> "bar")
(file-relative-name "/foo/bar" "/hack/")
=> "/foo/bar")
The value of this buffer-local variable is the default directory for
the current buffer. It is local in every buffer.
expand-file-name uses the default directory when its second
argument is nil.
On Unix systems, the value is always a string ending with a slash.
default-directory
=> "/user/lewis/manual/"
Function: substitute-in-file-name filename
This function replaces environment variables names in filename with the values to which they are set by the operating system. Following standard Unix shell syntax, `$' is the prefix to substitute an environment variable value.
The environment variable name is the series of alphanumeric characters (including underscores) that follow the `$'. If the character following the `$' is a `{', then the variable name is everything up to the matching `}'.
Here we assume that the environment variable HOME, which holds
the user's home directory name, has value `/xcssun/users/rms'.
(substitute-in-file-name "$HOME/foo")
=> "/xcssun/users/rms/foo"
If a `~' or a `/' appears following a `/', after substitution, everything before the following `/' is discarded:
(substitute-in-file-name "bar/~/foo")
=> "~/foo"
(substitute-in-file-name "/usr/local/$HOME/foo")
=> "/xcssun/users/rms/foo"
On VMS, `$' substitution is not done, so this function does nothing on VMS except discard superfluous initial components as shown above.
Go to the previous, next section.