comparison lispref/files.texi @ 26696:ef5e7bbe6f19

Current version from /gd/gnu/elisp.

26695:778a88ba7c10

names.  A file name is actually a string.  Most of these functions
expand file name arguments by calling @code{expand-file-name}, so that
@file{~} is handled correctly, as are relative file names (including
@samp{../}).  These functions don't recognize environment variable
substitutions such as @samp{$HOME}.  @xref{File Name Expansion}.

@menu
* Visiting Files::           Reading files into Emacs buffers for editing.
* Saving Buffers::           Writing changed buffers back into files.
* Reading from Files::       Reading files into buffers without visiting.

This function is used by @code{find-file-noselect}.
It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
@end defun

@defun after-find-file &optional error warn
This function sets the buffer major mode, and parses local variables
(@pxref{Auto Major Mode}).  It is called by @code{find-file-noselect}
and by the default revert function (@pxref{Reverting}).

@cindex new file message

@samp{(New file)}.  For more serious errors, the caller should usually not
call @code{after-find-file}.

If @var{warn} is non-@code{nil}, then this function issues a warning
if an auto-save file exists and is more recent than the visited file.

The last thing @code{after-find-file} does is call all the functions
in the list @code{find-file-hooks}.
@end defun

saving one of these is asked to specify a file name to use.)  The
@code{save-buffers-kill-emacs} function passes a non-@code{nil} value
for this argument.
@end deffn

@deffn Command write-file filename
This function writes the current buffer into file @var{filename}, makes
the buffer visit that file, and marks it not modified.  Then it renames
the buffer based on @var{filename}, appending a string like @samp{<2>}
if necessary to make a unique buffer name.  It does most of this work by
calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
@code{save-buffer}.
@end deffn

  Saving a buffer runs several hooks.  It also performs format
conversion (@pxref{Format Conversion}), and may save text properties in
``annotations'' (@pxref{Saving Properties}).

An error is signaled if @var{filename} specifies a nonwritable file,
or a nonexistent file in a directory where files cannot be created.
@end deffn

@deffn Command write-region start end filename &optional append visit mustbenew
This function writes the region delimited by @var{start} and @var{end}
in the current buffer into the file specified by @var{filename}.

@c Emacs 19 feature
If @var{start} is a string, then @code{write-region} writes or appends

@var{visit} is used in the echo area message and also for file locking;
@var{visit} is stored in @code{buffer-file-name}.  This feature is used
to implement @code{file-precious-flag}; don't use it yourself unless you
really know what you're doing.

The function @code{write-region} converts the data which it writes to
the appropriate file formats specified by @code{buffer-file-format}.
@xref{Format Conversion}.  It also calls the functions in the list
@code{write-region-annotate-functions}; see @ref{Saving Properties}.

@cindex file accessibility

  These functions test for permission to access a file in specific ways.

@defun file-exists-p filename
This function returns @code{t} if a file named @var{filename} appears
to exist.  This does not mean you can necessarily read the file, only
that you can find out its attributes.  (On Unix, this is true if the
file exists and you have execute permission on the containing
directories, regardless of the protection of the file itself.)

If the file does not exist, or if fascist access control policies
prevent you from finding the attributes of the file, this function
returns @code{nil}.

@end defun

@c Emacs 19 feature
@defun file-executable-p filename
This function returns @code{t} if a file named @var{filename} exists and
you can execute it.  It returns @code{nil} otherwise.  On Unix, if the
file is a directory, execute permission means you can check the
existence and attributes of files inside the directory, and open those
files if their modes permit.
@end defun

@defun file-writable-p filename
This function returns @code{t} if the file @var{filename} can be written
or created by you, and @code{nil} otherwise.  A file is writable if the

@subsection Truenames
@cindex truename (of file)

@c Emacs 19 features
  The @dfn{truename} of a file is the name that you get by following
symbolic links until none remain, then simplifying away @samp{.}@: and
@samp{..}@: appearing as components.  Strictly speaking, a file need not
have a unique truename; the number of distinct truenames a file has is
equal to the number of hard links to the file.  However, truenames are
useful because they eliminate symbolic links as a cause of name
variation.

@defun file-truename filename
The function @code{file-truename} returns the true name of the file
@var{filename}.  This is the name that you get by following symbolic
links until none remain.  The argument must be an absolute file name.
@end defun

  @xref{Buffer File Name}, for related information.

@node File Attributes
@comment  node-name,  next,  previous,  up

@pindex rm
This command deletes the file @var{filename}, like the shell command
@samp{rm @var{filename}}.  If the file has multiple names, it continues
to exist under the other names.

A suitable kind of @code{file-error} error is signaled if the file
does not exist, or is not deletable.  (On Unix, a file is deletable if
its directory is writable.)

See also @code{delete-directory} in @ref{Create/Delete Dirs}.
@end deffn

@deffn Command make-symbolic-link filename newname  &optional ok-if-exists

@c Emacs 19 feature
@defun set-default-file-modes mode
This function sets the default file protection for new files created by
Emacs and its subprocesses.  Every file created with Emacs initially has
this protection.  On Unix, the default protection is the bitwise
complement of the ``umask'' value.

The argument @var{mode} must be an integer.  On most systems, only the
low 9 bits of @var{mode} are meaningful.

Saving a modified version of an existing file does not count as creating

     @result{} "FOO.TMP"
@end group
@end example
@end defun

@defun file-name-sans-versions filename
This function returns @var{filename} with any file version numbers,
backup version numbers, or trailing tildes deleted.

@example
@group
(file-name-sans-versions "~rms/foo.~1~")
     @result{} "~rms/foo"

  All the directories in the file system form a tree starting at the
root directory.  A file name can specify all the directory names
starting from the root of the tree; then it is called an @dfn{absolute}
file name.  Or it can specify the position of the file in the tree
relative to a default directory; then it is called a @dfn{relative}
file name.  On Unix, an absolute file name starts with a slash or a
tilde (@samp{~}), and a relative one does not.  On MS-DOS and
MS-Windows, an absolute file name starts with a slash or a backslash, or
with a drive specification @samp{@var{x}:/}, where @var{x} is the
@dfn{drive letter}. The rules on VMS are complicated.

@defun file-name-absolute-p filename
This function returns @code{t} if file @var{filename} is an absolute
file name, @code{nil} otherwise.  On VMS, this function understands both
Unix syntax and VMS syntax.

Note that @code{expand-file-name} does @emph{not} expand environment
variables; only @code{substitute-in-file-name} does that.
@end defun

@c Emacs 19 feature
@defun file-relative-name filename directory
This function does the inverse of expansion---it tries to return a
relative name that is equivalent to @var{filename} when interpreted
relative to @var{directory}.

On some operating systems, an absolute file name begins with a device
name.  On such systems, @var{filename} has no relative equivalent based
on @var{directory} if they start with two different device names.  In
this case, @code{file-relative-name} returns @var{filename} in absolute

  Most Emacs Lisp file-manipulation functions get errors when used on
files that are directories.  For example, you cannot delete a directory
with @code{delete-file}.  These special functions exist to create and
delete directories.

@defun make-directory dirname
This function creates a directory named @var{dirname}.
@end defun

@defun delete-directory dirname
This function deletes the directory named @var{dirname}.  The function
@code{delete-file} does not work for files that are directories; you

26696:ef5e7bbe6f19

names.  A file name is actually a string.  Most of these functions
expand file name arguments by calling @code{expand-file-name}, so that
@file{~} is handled correctly, as are relative file names (including
@samp{../}).  These functions don't recognize environment variable
substitutions such as @samp{$HOME}.  @xref{File Name Expansion}.

  When file I/O functions signal Lisp errors, they usually use the
condition @code{file-error} (@pxref{Handling Errors}).  The error
message is in most cases obtained from the operating system, according
to locale @code{system-message-locale}, and decoded using coding system
@code{locale-coding-system} (@pxref{Locales}).

@menu
* Visiting Files::           Reading files into Emacs buffers for editing.
* Saving Buffers::           Writing changed buffers back into files.
* Reading from Files::       Reading files into buffers without visiting.

This function is used by @code{find-file-noselect}.
It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
@end defun

@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
This function sets the buffer major mode, and parses local variables
(@pxref{Auto Major Mode}).  It is called by @code{find-file-noselect}
and by the default revert function (@pxref{Reverting}).

@cindex new file message

@samp{(New file)}.  For more serious errors, the caller should usually not
call @code{after-find-file}.

If @var{warn} is non-@code{nil}, then this function issues a warning
if an auto-save file exists and is more recent than the visited file.

If @var{noauto} is non-@code{nil}, that says not to enable or disable
Auto-Save mode.  The mode remains enabled if it was enabled before.

If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
means this call was from @code{revert-buffer}.  This has no direct
effect, but some mode functions and hook functions check the value
of this variable.

If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
major mode, don't process local variables specifications in the file,
and don't run @code{find-file-hooks}.  This feature is used by
@code{revert-buffer} in some cases.

The last thing @code{after-find-file} does is call all the functions
in the list @code{find-file-hooks}.
@end defun

saving one of these is asked to specify a file name to use.)  The
@code{save-buffers-kill-emacs} function passes a non-@code{nil} value
for this argument.
@end deffn

@deffn Command write-file filename &optional confirm
This function writes the current buffer into file @var{filename}, makes
the buffer visit that file, and marks it not modified.  Then it renames
the buffer based on @var{filename}, appending a string like @samp{<2>}
if necessary to make a unique buffer name.  It does most of this work by
calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
@code{save-buffer}.

If @var{confirm} is non-@code{nil}, that means to ask for confirmation
before overwriting an existing file.
@end deffn

  Saving a buffer runs several hooks.  It also performs format
conversion (@pxref{Format Conversion}), and may save text properties in
``annotations'' (@pxref{Saving Properties}).

An error is signaled if @var{filename} specifies a nonwritable file,
or a nonexistent file in a directory where files cannot be created.
@end deffn

@deffn Command write-region start end filename &optional append visit lockname mustbenew
This function writes the region delimited by @var{start} and @var{end}
in the current buffer into the file specified by @var{filename}.

@c Emacs 19 feature
If @var{start} is a string, then @code{write-region} writes or appends

@var{visit} is used in the echo area message and also for file locking;
@var{visit} is stored in @code{buffer-file-name}.  This feature is used
to implement @code{file-precious-flag}; don't use it yourself unless you
really know what you're doing.

The optional argument @var{lockname}, if non-@code{nil}, specifies the
file name to use for purposes of locking and unlocking, overriding
@var{filename} and @var{visit} for that purpose.

The function @code{write-region} converts the data which it writes to
the appropriate file formats specified by @code{buffer-file-format}.
@xref{Format Conversion}.  It also calls the functions in the list
@code{write-region-annotate-functions}; see @ref{Saving Properties}.

@cindex file accessibility

  These functions test for permission to access a file in specific ways.

@defun file-exists-p filename
This function returns @code{t} if a file named @var{filename} appears to
exist.  This does not mean you can necessarily read the file, only that
you can find out its attributes.  (On Unix and GNU/Linux, this is true
if the file exists and you have execute permission on the containing
directories, regardless of the protection of the file itself.)

If the file does not exist, or if fascist access control policies
prevent you from finding the attributes of the file, this function
returns @code{nil}.

@end defun

@c Emacs 19 feature
@defun file-executable-p filename
This function returns @code{t} if a file named @var{filename} exists and
you can execute it.  It returns @code{nil} otherwise.  On Unix and
GNU/Linux, if the file is a directory, execute permission means you can
check the existence and attributes of files inside the directory, and
open those files if their modes permit.
@end defun

@defun file-writable-p filename
This function returns @code{t} if the file @var{filename} can be written
or created by you, and @code{nil} otherwise.  A file is writable if the

@subsection Truenames
@cindex truename (of file)

@c Emacs 19 features
  The @dfn{truename} of a file is the name that you get by following
symbolic links at all levels until none remain, then simplifying away
@samp{.}@: and @samp{..}@: appearing as name components.  This results
in a sort of canonical name for the file.  A file does not always have a
unique truename; the number of distinct truenames a file has is equal to
the number of hard links to the file.  However, truenames are useful
because they eliminate symbolic links as a cause of name variation.

@defun file-truename filename
The function @code{file-truename} returns the truename of the file
@var{filename}.  The argument must be an absolute file name.
@end defun

@defun file-chase-links filename
This function follows symbolic links, starting with @var{filename},
until it finds a file name which is not the name of a symbolic link.
Then it returns that file name.
@end defun

  To illustrate the difference between @code{file-chase-links} and
@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
the directory @file{/home/foo}, and @file{/home/foo/hello} is an
ordinary file (or at least, not a symbolic link) or nonexistent.  Then
we would have:

@example
(file-chase-links "/usr/foo/hello")
     ;; @r{This does not follow the links in the parent directories.}
     @result{} "/usr/foo/hello"
(file-truename "/usr/foo/hello")
     ;; @r{Assuming that @file{/home} is not a symbolic link.}
     @result{} "/home/foo/hello"
@end example

  @xref{Buffer File Name}, for related information.

@node File Attributes
@comment  node-name,  next,  previous,  up

@pindex rm
This command deletes the file @var{filename}, like the shell command
@samp{rm @var{filename}}.  If the file has multiple names, it continues
to exist under the other names.

A suitable kind of @code{file-error} error is signaled if the file does
not exist, or is not deletable.  (On Unix and GNU/Linux, a file is
deletable if its directory is writable.)

See also @code{delete-directory} in @ref{Create/Delete Dirs}.
@end deffn

@deffn Command make-symbolic-link filename newname  &optional ok-if-exists

@c Emacs 19 feature
@defun set-default-file-modes mode
This function sets the default file protection for new files created by
Emacs and its subprocesses.  Every file created with Emacs initially has
this protection.  On Unix and GNU/Linux, the default protection is the
bitwise complement of the ``umask'' value.

The argument @var{mode} must be an integer.  On most systems, only the
low 9 bits of @var{mode} are meaningful.

Saving a modified version of an existing file does not count as creating

     @result{} "FOO.TMP"
@end group
@end example
@end defun

@defun file-name-sans-versions filename &optional keep-backup-version
This function returns @var{filename} with any file version numbers,
backup version numbers, or trailing tildes discarded.

If @var{keep-backup-version} is non-@code{nil}, then true file version
numbers understood as such by the file system are discarded from the
return value, but backup version numbers are kept.

@example
@group
(file-name-sans-versions "~rms/foo.~1~")
     @result{} "~rms/foo"

  All the directories in the file system form a tree starting at the
root directory.  A file name can specify all the directory names
starting from the root of the tree; then it is called an @dfn{absolute}
file name.  Or it can specify the position of the file in the tree
relative to a default directory; then it is called a @dfn{relative} file
name.  On Unix and GNU/Linux, an absolute file name starts with a slash
or a tilde (@samp{~}), and a relative one does not.  On MS-DOS and
MS-Windows, an absolute file name starts with a slash or a backslash, or
with a drive specification @samp{@var{x}:/}, where @var{x} is the
@dfn{drive letter}.  The rules on VMS are complicated.

@defun file-name-absolute-p filename
This function returns @code{t} if file @var{filename} is an absolute
file name, @code{nil} otherwise.  On VMS, this function understands both
Unix syntax and VMS syntax.

Note that @code{expand-file-name} does @emph{not} expand environment
variables; only @code{substitute-in-file-name} does that.
@end defun

@c Emacs 19 feature
@defun file-relative-name filename &optional directory
This function does the inverse of expansion---it tries to return a
relative name that is equivalent to @var{filename} when interpreted
relative to @var{directory}.  If @var{directory} is omitted or
@code{nil}, it defaults to the current buffer's default directory.

On some operating systems, an absolute file name begins with a device
name.  On such systems, @var{filename} has no relative equivalent based
on @var{directory} if they start with two different device names.  In
this case, @code{file-relative-name} returns @var{filename} in absolute

  Most Emacs Lisp file-manipulation functions get errors when used on
files that are directories.  For example, you cannot delete a directory
with @code{delete-file}.  These special functions exist to create and
delete directories.

@defun make-directory dirname &optional parents
This function creates a directory named @var{dirname}.
If @var{parents} is non-@code{nil}, that means to create
the parent directories first, if they don't already exist.
@end defun

@defun delete-directory dirname
This function deletes the directory named @var{dirname}.  The function
@code{delete-file} does not work for files that are directories; you