changeset 83994:4cc2cd3910a9

Move to ../doc/lispref
author Glenn Morris <rgm@gnu.org>
date Thu, 06 Sep 2007 04:11:08 +0000
parents ddd0056dfc65
children b6f46efff288
files lispref/files.texi
diffstat 1 files changed, 0 insertions(+), 3108 deletions(-) [+]
line wrap: on
line diff
--- a/lispref/files.texi	Thu Sep 06 04:11:02 2007 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,3108 +0,0 @@
-@c -*-texinfo-*-
-@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/files
-@node Files, Backups and Auto-Saving, Documentation, Top
-@comment  node-name,  next,  previous,  up
-@chapter Files
-
-  In Emacs, you can find, create, view, save, and otherwise work with
-files and file directories.  This chapter describes most of the
-file-related functions of Emacs Lisp, but a few others are described in
-@ref{Buffers}, and those related to backups and auto-saving are
-described in @ref{Backups and Auto-Saving}.
-
-  Many of the file functions take one or more arguments that are file
-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.
-* Writing to Files::         Writing new files from parts of buffers.
-* File Locks::               Locking and unlocking files, to prevent
-                               simultaneous editing by two people.
-* Information about Files::  Testing existence, accessibility, size of files.
-* Changing Files::           Renaming files, changing protection, etc.
-* File Names::               Decomposing and expanding file names.
-* Contents of Directories::  Getting a list of the files in a directory.
-* Create/Delete Dirs::	     Creating and Deleting Directories.
-* Magic File Names::	     Defining "magic" special handling
-			       for certain file names.
-* Format Conversion::        Conversion to and from various file formats.
-@end menu
-
-@node Visiting Files
-@section Visiting Files
-@cindex finding files
-@cindex visiting files
-
-  Visiting a file means reading a file into a buffer.  Once this is
-done, we say that the buffer is @dfn{visiting} that file, and call the
-file ``the visited file'' of the buffer.
-
-  A file and a buffer are two different things.  A file is information
-recorded permanently in the computer (unless you delete it).  A buffer,
-on the other hand, is information inside of Emacs that will vanish at
-the end of the editing session (or when you kill the buffer).  Usually,
-a buffer contains information that you have copied from a file; then we
-say the buffer is visiting that file.  The copy in the buffer is what
-you modify with editing commands.  Such changes to the buffer do not
-change the file; therefore, to make the changes permanent, you must
-@dfn{save} the buffer, which means copying the altered buffer contents
-back into the file.
-
-  In spite of the distinction between files and buffers, people often
-refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
-``I am editing a file,'' rather than, ``I am editing a buffer that I
-will soon save as a file of the same name.''  Humans do not usually need
-to make the distinction explicit.  When dealing with a computer program,
-however, it is good to keep the distinction in mind.
-
-@menu
-* Visiting Functions::         The usual interface functions for visiting.
-* Subroutines of Visiting::    Lower-level subroutines that they use.
-@end menu
-
-@node Visiting Functions
-@subsection Functions for Visiting Files
-
-  This section describes the functions normally used to visit files.
-For historical reasons, these functions have names starting with
-@samp{find-} rather than @samp{visit-}.  @xref{Buffer File Name}, for
-functions and variables that access the visited file name of a buffer or
-that find an existing buffer by its visited file name.
-
-  In a Lisp program, if you want to look at the contents of a file but
-not alter it, the fastest way is to use @code{insert-file-contents} in a
-temporary buffer.  Visiting the file is not necessary and takes longer.
-@xref{Reading from Files}.
-
-@deffn Command find-file filename &optional wildcards
-This command selects a buffer visiting the file @var{filename},
-using an existing buffer if there is one, and otherwise creating a
-new buffer and reading the file into it.  It also returns that buffer.
-
-Aside from some technical details, the body of the @code{find-file}
-function is basically equivalent to:
-
-@smallexample
-(switch-to-buffer (find-file-noselect filename nil nil wildcards))
-@end smallexample
-
-@noindent
-(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
-
-If @var{wildcards} is non-@code{nil}, which is always true in an
-interactive call, then @code{find-file} expands wildcard characters in
-@var{filename} and visits all the matching files.
-
-When @code{find-file} is called interactively, it prompts for
-@var{filename} in the minibuffer.
-@end deffn
-
-@defun find-file-noselect filename &optional nowarn rawfile wildcards
-This function is the guts of all the file-visiting functions.  It
-returns a buffer visiting the file @var{filename}.  You may make the
-buffer current or display it in a window if you wish, but this
-function does not do so.
-
-The function returns an existing buffer if there is one; otherwise it
-creates a new buffer and reads the file into it.  When
-@code{find-file-noselect} uses an existing buffer, it first verifies
-that the file has not changed since it was last visited or saved in
-that buffer.  If the file has changed, this function asks the user
-whether to reread the changed file.  If the user says @samp{yes}, any
-edits previously made in the buffer are lost.
-
-Reading the file involves decoding the file's contents (@pxref{Coding
-Systems}), including end-of-line conversion, and format conversion
-(@pxref{Format Conversion}).  If @var{wildcards} is non-@code{nil},
-then @code{find-file-noselect} expands wildcard characters in
-@var{filename} and visits all the matching files.
-
-This function displays warning or advisory messages in various peculiar
-cases, unless the optional argument @var{nowarn} is non-@code{nil}.  For
-example, if it needs to create a buffer, and there is no file named
-@var{filename}, it displays the message @samp{(New file)} in the echo
-area, and leaves the buffer empty.
-
-The @code{find-file-noselect} function normally calls
-@code{after-find-file} after reading the file (@pxref{Subroutines of
-Visiting}).  That function sets the buffer major mode, parses local
-variables, warns the user if there exists an auto-save file more recent
-than the file just visited, and finishes by running the functions in
-@code{find-file-hook}.
-
-If the optional argument @var{rawfile} is non-@code{nil}, then
-@code{after-find-file} is not called, and the
-@code{find-file-not-found-functions} are not run in case of failure.
-What's more, a non-@code{nil} @var{rawfile} value suppresses coding
-system conversion and format conversion.
-
-The @code{find-file-noselect} function usually returns the buffer that
-is visiting the file @var{filename}.  But, if wildcards are actually
-used and expanded, it returns a list of buffers that are visiting the
-various files.
-
-@example
-@group
-(find-file-noselect "/etc/fstab")
-     @result{} #<buffer fstab>
-@end group
-@end example
-@end defun
-
-@deffn Command find-file-other-window filename &optional wildcards
-This command selects a buffer visiting the file @var{filename}, but
-does so in a window other than the selected window.  It may use another
-existing window or split a window; see @ref{Displaying Buffers}.
-
-When this command is called interactively, it prompts for
-@var{filename}.
-@end deffn
-
-@deffn Command find-file-read-only filename &optional wildcards
-This command selects a buffer visiting the file @var{filename}, like
-@code{find-file}, but it marks the buffer as read-only.  @xref{Read Only
-Buffers}, for related functions and variables.
-
-When this command is called interactively, it prompts for
-@var{filename}.
-@end deffn
-
-@deffn Command view-file filename
-This command visits @var{filename} using View mode, returning to the
-previous buffer when you exit View mode.  View mode is a minor mode that
-provides commands to skim rapidly through the file, but does not let you
-modify the text.  Entering View mode runs the normal hook
-@code{view-mode-hook}.  @xref{Hooks}.
-
-When @code{view-file} is called interactively, it prompts for
-@var{filename}.
-@end deffn
-
-@defopt find-file-wildcards
-If this variable is non-@code{nil}, then the various @code{find-file}
-commands check for wildcard characters and visit all the files that
-match them (when invoked interactively or when their @var{wildcards}
-argument is non-@code{nil}).  If this option is @code{nil}, then
-the @code{find-file} commands ignore their @var{wildcards} argument
-and never treat wildcard characters specially.
-@end defopt
-
-@defvar find-file-hook
-The value of this variable is a list of functions to be called after a
-file is visited.  The file's local-variables specification (if any) will
-have been processed before the hooks are run.  The buffer visiting the
-file is current when the hook functions are run.
-
-This variable is a normal hook.  @xref{Hooks}.
-@end defvar
-
-@defvar find-file-not-found-functions
-The value of this variable is a list of functions to be called when
-@code{find-file} or @code{find-file-noselect} is passed a nonexistent
-file name.  @code{find-file-noselect} calls these functions as soon as
-it detects a nonexistent file.  It calls them in the order of the list,
-until one of them returns non-@code{nil}.  @code{buffer-file-name} is
-already set up.
-
-This is not a normal hook because the values of the functions are
-used, and in many cases only some of the functions are called.
-@end defvar
-
-@node Subroutines of Visiting
-@comment  node-name,  next,  previous,  up
-@subsection Subroutines of Visiting
-
-  The @code{find-file-noselect} function uses two important subroutines
-which are sometimes useful in user Lisp code: @code{create-file-buffer}
-and @code{after-find-file}.  This section explains how to use them.
-
-@defun create-file-buffer filename
-This function creates a suitably named buffer for visiting
-@var{filename}, and returns it.  It uses @var{filename} (sans directory)
-as the name if that name is free; otherwise, it appends a string such as
-@samp{<2>} to get an unused name.  See also @ref{Creating Buffers}.
-
-@strong{Please note:} @code{create-file-buffer} does @emph{not}
-associate the new buffer with a file and does not select the buffer.
-It also does not use the default major mode.
-
-@example
-@group
-(create-file-buffer "foo")
-     @result{} #<buffer foo>
-@end group
-@group
-(create-file-buffer "foo")
-     @result{} #<buffer foo<2>>
-@end group
-@group
-(create-file-buffer "foo")
-     @result{} #<buffer foo<3>>
-@end group
-@end example
-
-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
-@cindex file open error
-If reading the file got an error because the file does not exist, but
-its directory does exist, the caller should pass a non-@code{nil} value
-for @var{error}.  In that case, @code{after-find-file} issues a warning:
-@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-hook}.  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-hook}.
-@end defun
-
-@node Saving Buffers
-@section Saving Buffers
-@cindex saving buffers
-
-  When you edit a file in Emacs, you are actually working on a buffer
-that is visiting that file---that is, the contents of the file are
-copied into the buffer and the copy is what you edit.  Changes to the
-buffer do not change the file until you @dfn{save} the buffer, which
-means copying the contents of the buffer into the file.
-
-@deffn Command save-buffer &optional backup-option
-This function saves the contents of the current buffer in its visited
-file if the buffer has been modified since it was last visited or saved.
-Otherwise it does nothing.
-
-@code{save-buffer} is responsible for making backup files.  Normally,
-@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
-file only if this is the first save since visiting the file.  Other
-values for @var{backup-option} request the making of backup files in
-other circumstances:
-
-@itemize @bullet
-@item
-With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
-@code{save-buffer} function marks this version of the file to be
-backed up when the buffer is next saved.
-
-@item
-With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
-@code{save-buffer} function unconditionally backs up the previous
-version of the file before saving it.
-
-@item
-With an argument of 0, unconditionally do @emph{not} make any backup file.
-@end itemize
-@end deffn
-
-@deffn Command save-some-buffers &optional save-silently-p pred
-@anchor{Definition of save-some-buffers}
-This command saves some modified file-visiting buffers.  Normally it
-asks the user about each buffer.  But if @var{save-silently-p} is
-non-@code{nil}, it saves all the file-visiting buffers without querying
-the user.
-
-The optional @var{pred} argument controls which buffers to ask about
-(or to save silently if @var{save-silently-p} is non-@code{nil}).
-If it is @code{nil}, that means to ask only about file-visiting buffers.
-If it is @code{t}, that means also offer to save certain other non-file
-buffers---those that have a non-@code{nil} buffer-local value of
-@code{buffer-offer-save} (@pxref{Killing Buffers}).  A user who says
-@samp{yes} to saving a non-file buffer is asked to specify the file
-name to use.  The @code{save-buffers-kill-emacs} function passes the
-value @code{t} for @var{pred}.
-
-If @var{pred} is neither @code{t} nor @code{nil}, then it should be
-a function of no arguments.  It will be called in each buffer to decide
-whether to offer to save that buffer.  If it returns a non-@code{nil}
-value in a certain buffer, that means do offer to save that buffer.
-@end deffn
-
-@deffn Command write-file filename &optional confirm
-@anchor{Definition of write-file}
-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.  Interactively, confirmation is
-required, unless the user supplies a prefix argument.
-
-If @var{filename} is an existing directory, or a symbolic link to one,
-@code{write-file} uses the name of the visited file, in directory
-@var{filename}.  If the buffer is not visiting a file, it uses the
-buffer name instead.
-@end deffn
-
-  Saving a buffer runs several hooks.  It also performs format
-conversion (@pxref{Format Conversion}).
-
-@defvar write-file-functions
-The value of this variable is a list of functions to be called before
-writing out a buffer to its visited file.  If one of them returns
-non-@code{nil}, the file is considered already written and the rest of
-the functions are not called, nor is the usual code for writing the file
-executed.
-
-If a function in @code{write-file-functions} returns non-@code{nil}, it
-is responsible for making a backup file (if that is appropriate).
-To do so, execute the following code:
-
-@example
-(or buffer-backed-up (backup-buffer))
-@end example
-
-You might wish to save the file modes value returned by
-@code{backup-buffer} and use that (if non-@code{nil}) to set the mode
-bits of the file that you write.  This is what @code{save-buffer}
-normally does. @xref{Making Backups,, Making Backup Files}.
-
-The hook functions in @code{write-file-functions} are also responsible
-for encoding the data (if desired): they must choose a suitable coding
-system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
-perform the encoding (@pxref{Explicit Encoding}), and set
-@code{last-coding-system-used} to the coding system that was used
-(@pxref{Encoding and I/O}).
-
-If you set this hook locally in a buffer, it is assumed to be
-associated with the file or the way the contents of the buffer were
-obtained.  Thus the variable is marked as a permanent local, so that
-changing the major mode does not alter a buffer-local value.  On the
-other hand, calling @code{set-visited-file-name} will reset it.
-If this is not what you want, you might like to use
-@code{write-contents-functions} instead.
-
-Even though this is not a normal hook, you can use @code{add-hook} and
-@code{remove-hook} to manipulate the list.  @xref{Hooks}.
-@end defvar
-
-@c Emacs 19 feature
-@defvar write-contents-functions
-This works just like @code{write-file-functions}, but it is intended
-for hooks that pertain to the buffer's contents, not to the particular
-visited file or its location.  Such hooks are usually set up by major
-modes, as buffer-local bindings for this variable.  This variable
-automatically becomes buffer-local whenever it is set; switching to a
-new major mode always resets this variable, but calling
-@code{set-visited-file-name} does not.
-
-If any of the functions in this hook returns non-@code{nil}, the file
-is considered already written and the rest are not called and neither
-are the functions in @code{write-file-functions}.
-@end defvar
-
-@defopt before-save-hook
-This normal hook runs before a buffer is saved in its visited file,
-regardless of whether that is done normally or by one of the hooks
-described above.  For instance, the @file{copyright.el} program uses
-this hook to make sure the file you are saving has the current year in
-its copyright notice.
-@end defopt
-
-@c Emacs 19 feature
-@defopt after-save-hook
-This normal hook runs after a buffer has been saved in its visited file.
-One use of this hook is in Fast Lock mode; it uses this hook to save the
-highlighting information in a cache file.
-@end defopt
-
-@defopt file-precious-flag
-If this variable is non-@code{nil}, then @code{save-buffer} protects
-against I/O errors while saving by writing the new file to a temporary
-name instead of the name it is supposed to have, and then renaming it to
-the intended name after it is clear there are no errors.  This procedure
-prevents problems such as a lack of disk space from resulting in an
-invalid file.
-
-As a side effect, backups are necessarily made by copying.  @xref{Rename
-or Copy}.  Yet, at the same time, saving a precious file always breaks
-all hard links between the file you save and other file names.
-
-Some modes give this variable a non-@code{nil} buffer-local value
-in particular buffers.
-@end defopt
-
-@defopt require-final-newline
-This variable determines whether files may be written out that do
-@emph{not} end with a newline.  If the value of the variable is
-@code{t}, then @code{save-buffer} silently adds a newline at the end of
-the file whenever the buffer being saved does not already end in one.
-If the value of the variable is non-@code{nil}, but not @code{t}, then
-@code{save-buffer} asks the user whether to add a newline each time the
-case arises.
-
-If the value of the variable is @code{nil}, then @code{save-buffer}
-doesn't add newlines at all.  @code{nil} is the default value, but a few
-major modes set it to @code{t} in particular buffers.
-@end defopt
-
-  See also the function @code{set-visited-file-name} (@pxref{Buffer File
-Name}).
-
-@node Reading from Files
-@comment  node-name,  next,  previous,  up
-@section Reading from Files
-@cindex reading from files
-
-  You can copy a file from the disk and insert it into a buffer
-using the @code{insert-file-contents} function.  Don't use the user-level
-command @code{insert-file} in a Lisp program, as that sets the mark.
-
-@defun insert-file-contents filename &optional visit beg end replace
-This function inserts the contents of file @var{filename} into the
-current buffer after point.  It returns a list of the absolute file name
-and the length of the data inserted.  An error is signaled if
-@var{filename} is not the name of a file that can be read.
-
-The function @code{insert-file-contents} checks the file contents
-against the defined file formats, and converts the file contents if
-appropriate and also calls the functions in
-the list @code{after-insert-file-functions}.  @xref{Format Conversion}.
-Normally, one of the functions in the
-@code{after-insert-file-functions} list determines the coding system
-(@pxref{Coding Systems}) used for decoding the file's contents,
-including end-of-line conversion.
-
-If @var{visit} is non-@code{nil}, this function additionally marks the
-buffer as unmodified and sets up various fields in the buffer so that it
-is visiting the file @var{filename}: these include the buffer's visited
-file name and its last save file modtime.  This feature is used by
-@code{find-file-noselect} and you probably should not use it yourself.
-
-If @var{beg} and @var{end} are non-@code{nil}, they should be integers
-specifying the portion of the file to insert.  In this case, @var{visit}
-must be @code{nil}.  For example,
-
-@example
-(insert-file-contents filename nil 0 500)
-@end example
-
-@noindent
-inserts the first 500 characters of a file.
-
-If the argument @var{replace} is non-@code{nil}, it means to replace the
-contents of the buffer (actually, just the accessible portion) with the
-contents of the file.  This is better than simply deleting the buffer
-contents and inserting the whole file, because (1) it preserves some
-marker positions and (2) it puts less data in the undo list.
-
-It is possible to read a special file (such as a FIFO or an I/O device)
-with @code{insert-file-contents}, as long as @var{replace} and
-@var{visit} are @code{nil}.
-@end defun
-
-@defun insert-file-contents-literally filename &optional visit beg end replace
-This function works like @code{insert-file-contents} except that it does
-not do format decoding (@pxref{Format Conversion}), does not do
-character code conversion (@pxref{Coding Systems}), does not run
-@code{find-file-hook}, does not perform automatic uncompression, and so
-on.
-@end defun
-
-If you want to pass a file name to another process so that another
-program can read the file, use the function @code{file-local-copy}; see
-@ref{Magic File Names}.
-
-@node Writing to Files
-@comment  node-name,  next,  previous,  up
-@section Writing to Files
-@cindex writing to files
-
-  You can write the contents of a buffer, or part of a buffer, directly
-to a file on disk using the @code{append-to-file} and
-@code{write-region} functions.  Don't use these functions to write to
-files that are being visited; that could cause confusion in the
-mechanisms for visiting.
-
-@deffn Command append-to-file start end filename
-This function appends the contents of the region delimited by
-@var{start} and @var{end} in the current buffer to the end of file
-@var{filename}.  If that file does not exist, it is created.  This
-function returns @code{nil}.
-
-An error is signaled if @var{filename} specifies a nonwritable file,
-or a nonexistent file in a directory where files cannot be created.
-
-When called from Lisp, this function is completely equivalent to:
-
-@example
-(write-region start end filename t)
-@end example
-@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}.
-
-If @var{start} is @code{nil}, then the command writes the entire buffer
-contents (@emph{not} just the accessible portion) to the file and
-ignores @var{end}.
-
-@c Emacs 19 feature
-If @var{start} is a string, then @code{write-region} writes or appends
-that string, rather than text from the buffer.  @var{end} is ignored in
-this case.
-
-If @var{append} is non-@code{nil}, then the specified text is appended
-to the existing file contents (if any).  If @var{append} is an
-integer, @code{write-region} seeks to that byte offset from the start
-of the file and writes the data from there.
-
-If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
-for confirmation if @var{filename} names an existing file.  If
-@var{mustbenew} is the symbol @code{excl}, then @code{write-region}
-does not ask for confirmation, but instead it signals an error
-@code{file-already-exists} if the file already exists.
-
-The test for an existing file, when @var{mustbenew} is @code{excl}, uses
-a special system feature.  At least for files on a local disk, there is
-no chance that some other program could create a file of the same name
-before Emacs does, without Emacs's noticing.
-
-If @var{visit} is @code{t}, then Emacs establishes an association
-between the buffer and the file: the buffer is then visiting that file.
-It also sets the last file modification time for the current buffer to
-@var{filename}'s modtime, and marks the buffer as not modified.  This
-feature is used by @code{save-buffer}, but you probably should not use
-it yourself.
-
-@c Emacs 19 feature
-If @var{visit} is a string, it specifies the file name to visit.  This
-way, you can write the data to one file (@var{filename}) while recording
-the buffer as visiting another file (@var{visit}).  The argument
-@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}
-and also calls the functions in the list
-@code{write-region-annotate-functions}.
-@xref{Format Conversion}.
-
-Normally, @code{write-region} displays the message @samp{Wrote
-@var{filename}} in the echo area.  If @var{visit} is neither @code{t}
-nor @code{nil} nor a string, then this message is inhibited.  This
-feature is useful for programs that use files for internal purposes,
-files that the user does not need to know about.
-@end deffn
-
-@defmac with-temp-file file body@dots{}
-@anchor{Definition of with-temp-file}
-The @code{with-temp-file} macro evaluates the @var{body} forms with a
-temporary buffer as the current buffer; then, at the end, it writes the
-buffer contents into file @var{file}.  It kills the temporary buffer
-when finished, restoring the buffer that was current before the
-@code{with-temp-file} form.  Then it returns the value of the last form
-in @var{body}.
-
-The current buffer is restored even in case of an abnormal exit via
-@code{throw} or error (@pxref{Nonlocal Exits}).
-
-See also @code{with-temp-buffer} in @ref{Definition of
-with-temp-buffer,, The Current Buffer}.
-@end defmac
-
-@node File Locks
-@section File Locks
-@cindex file locks
-@cindex lock file
-
-  When two users edit the same file at the same time, they are likely
-to interfere with each other.  Emacs tries to prevent this situation
-from arising by recording a @dfn{file lock} when a file is being
-modified.  (File locks are not implemented on Microsoft systems.)
-Emacs can then detect the first attempt to modify a buffer visiting a
-file that is locked by another Emacs job, and ask the user what to do.
-The file lock is really a file, a symbolic link with a special name,
-stored in the same directory as the file you are editing.
-
-  When you access files using NFS, there may be a small probability that
-you and another user will both lock the same file ``simultaneously.''
-If this happens, it is possible for the two users to make changes
-simultaneously, but Emacs will still warn the user who saves second.
-Also, the detection of modification of a buffer visiting a file changed
-on disk catches some cases of simultaneous editing; see
-@ref{Modification Time}.
-
-@defun file-locked-p filename
-This function returns @code{nil} if the file @var{filename} is not
-locked.  It returns @code{t} if it is locked by this Emacs process, and
-it returns the name of the user who has locked it if it is locked by
-some other job.
-
-@example
-@group
-(file-locked-p "foo")
-     @result{} nil
-@end group
-@end example
-@end defun
-
-@defun lock-buffer &optional filename
-This function locks the file @var{filename}, if the current buffer is
-modified.  The argument @var{filename} defaults to the current buffer's
-visited file.  Nothing is done if the current buffer is not visiting a
-file, or is not modified, or if the system does not support locking.
-@end defun
-
-@defun unlock-buffer
-This function unlocks the file being visited in the current buffer,
-if the buffer is modified.  If the buffer is not modified, then
-the file should not be locked, so this function does nothing.  It also
-does nothing if the current buffer is not visiting a file, or if the
-system does not support locking.
-@end defun
-
-  File locking is not supported on some systems.  On systems that do not
-support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
-@code{file-locked-p} do nothing and return @code{nil}.
-
-@defun ask-user-about-lock file other-user
-This function is called when the user tries to modify @var{file}, but it
-is locked by another user named @var{other-user}.  The default
-definition of this function asks the user to say what to do.  The value
-this function returns determines what Emacs does next:
-
-@itemize @bullet
-@item
-A value of @code{t} says to grab the lock on the file.  Then
-this user may edit the file and @var{other-user} loses the lock.
-
-@item
-A value of @code{nil} says to ignore the lock and let this
-user edit the file anyway.
-
-@item
-@kindex file-locked
-This function may instead signal a @code{file-locked} error, in which
-case the change that the user was about to make does not take place.
-
-The error message for this error looks like this:
-
-@example
-@error{} File is locked: @var{file} @var{other-user}
-@end example
-
-@noindent
-where @code{file} is the name of the file and @var{other-user} is the
-name of the user who has locked the file.
-@end itemize
-
-If you wish, you can replace the @code{ask-user-about-lock} function
-with your own version that makes the decision in another way.  The code
-for its usual definition is in @file{userlock.el}.
-@end defun
-
-@node Information about Files
-@section Information about Files
-@cindex file, information about
-
-  The functions described in this section all operate on strings that
-designate file names.  With a few exceptions, all the functions have
-names that begin with the word @samp{file}.  These functions all
-return information about actual files or directories, so their
-arguments must all exist as actual files or directories unless
-otherwise noted.
-
-@menu
-* Testing Accessibility::   Is a given file readable?  Writable?
-* Kinds of Files::          Is it a directory?  A symbolic link?
-* Truenames::		    Eliminating symbolic links from a file name.
-* File Attributes::         How large is it?  Any other names?  Etc.
-* Locating Files::          How to find a file in standard places.
-@end menu
-
-@node Testing Accessibility
-@comment  node-name,  next,  previous,  up
-@subsection Testing Accessibility
-@cindex accessibility of a file
-@cindex file accessibility
-
-  These functions test for permission to access a file in specific
-ways.  Unless explicitly stated otherwise, they recursively follow
-symbolic links for their file name arguments, at all levels (at the
-level of the file itself and at all levels of parent directories).
-
-@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}.
-
-Directories are files, so @code{file-exists-p} returns @code{t} when
-given a directory name.  However, symbolic links are treated
-specially; @code{file-exists-p} returns @code{t} for a symbolic link
-name only if the target file exists.
-@end defun
-
-@defun file-readable-p filename
-This function returns @code{t} if a file named @var{filename} exists
-and you can read it.  It returns @code{nil} otherwise.
-
-@example
-@group
-(file-readable-p "files.texi")
-     @result{} t
-@end group
-@group
-(file-exists-p "/usr/spool/mqueue")
-     @result{} t
-@end group
-@group
-(file-readable-p "/usr/spool/mqueue")
-     @result{} nil
-@end group
-@end example
-@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
-file exists and you can write it.  It is creatable if it does not exist,
-but the specified directory does exist and you can write in that
-directory.
-
-In the third example below, @file{foo} is not writable because the
-parent directory does not exist, even though the user could create such
-a directory.
-
-@example
-@group
-(file-writable-p "~/foo")
-     @result{} t
-@end group
-@group
-(file-writable-p "/foo")
-     @result{} nil
-@end group
-@group
-(file-writable-p "~/no-such-dir/foo")
-     @result{} nil
-@end group
-@end example
-@end defun
-
-@c Emacs 19 feature
-@defun file-accessible-directory-p dirname
-This function returns @code{t} if you have permission to open existing
-files in the directory whose name as a file is @var{dirname};
-otherwise (or if there is no such directory), it returns @code{nil}.
-The value of @var{dirname} may be either a directory name (such as
-@file{/foo/}) or the file name of a file which is a directory
-(such as @file{/foo}, without the final slash).
-
-Example: after the following,
-
-@example
-(file-accessible-directory-p "/foo")
-     @result{} nil
-@end example
-
-@noindent
-we can deduce that any attempt to read a file in @file{/foo/} will
-give an error.
-@end defun
-
-@defun access-file filename string
-This function opens file @var{filename} for reading, then closes it and
-returns @code{nil}.  However, if the open fails, it signals an error
-using @var{string} as the error message text.
-@end defun
-
-@defun file-ownership-preserved-p filename
-This function returns @code{t} if deleting the file @var{filename} and
-then creating it anew would keep the file's owner unchanged.  It also
-returns @code{t} for nonexistent files.
-
-If @var{filename} is a symbolic link, then, unlike the other functions
-discussed here, @code{file-ownership-preserved-p} does @emph{not}
-replace @var{filename} with its target.  However, it does recursively
-follow symbolic links at all levels of parent directories.
-@end defun
-
-@defun file-newer-than-file-p filename1 filename2
-@cindex file age
-@cindex file modification time
-This function returns @code{t} if the file @var{filename1} is
-newer than file @var{filename2}.  If @var{filename1} does not
-exist, it returns @code{nil}.  If @var{filename1} does exist, but
-@var{filename2} does not, it returns @code{t}.
-
-In the following example, assume that the file @file{aug-19} was written
-on the 19th, @file{aug-20} was written on the 20th, and the file
-@file{no-file} doesn't exist at all.
-
-@example
-@group
-(file-newer-than-file-p "aug-19" "aug-20")
-     @result{} nil
-@end group
-@group
-(file-newer-than-file-p "aug-20" "aug-19")
-     @result{} t
-@end group
-@group
-(file-newer-than-file-p "aug-19" "no-file")
-     @result{} t
-@end group
-@group
-(file-newer-than-file-p "no-file" "aug-19")
-     @result{} nil
-@end group
-@end example
-
-You can use @code{file-attributes} to get a file's last modification
-time as a list of two numbers.  @xref{File Attributes}.
-@end defun
-
-@node Kinds of Files
-@comment  node-name,  next,  previous,  up
-@subsection Distinguishing Kinds of Files
-
-  This section describes how to distinguish various kinds of files, such
-as directories, symbolic links, and ordinary files.
-
-@defun file-symlink-p filename
-@cindex file symbolic links
-If the file @var{filename} is a symbolic link, the
-@code{file-symlink-p} function returns the (non-recursive) link target
-as a string.  (Determining the file name that the link points to from
-the target is nontrivial.)  First, this function recursively follows
-symbolic links at all levels of parent directories.
-
-If the file @var{filename} is not a symbolic link (or there is no such file),
-@code{file-symlink-p} returns @code{nil}.
-
-@example
-@group
-(file-symlink-p "foo")
-     @result{} nil
-@end group
-@group
-(file-symlink-p "sym-link")
-     @result{} "foo"
-@end group
-@group
-(file-symlink-p "sym-link2")
-     @result{} "sym-link"
-@end group
-@group
-(file-symlink-p "/bin")
-     @result{} "/pub/bin"
-@end group
-@end example
-
-@c !!! file-symlink-p: should show output of ls -l for comparison
-@end defun
-
-The next two functions recursively follow symbolic links at
-all levels for @var{filename}.
-
-@defun file-directory-p filename
-This function returns @code{t} if @var{filename} is the name of an
-existing directory, @code{nil} otherwise.
-
-@example
-@group
-(file-directory-p "~rms")
-     @result{} t
-@end group
-@group
-(file-directory-p "~rms/lewis/files.texi")
-     @result{} nil
-@end group
-@group
-(file-directory-p "~rms/lewis/no-such-file")
-     @result{} nil
-@end group
-@group
-(file-directory-p "$HOME")
-     @result{} nil
-@end group
-@group
-(file-directory-p
- (substitute-in-file-name "$HOME"))
-     @result{} t
-@end group
-@end example
-@end defun
-
-@defun file-regular-p filename
-This function returns @code{t} if the file @var{filename} exists and is
-a regular file (not a directory, named pipe, terminal, or
-other I/O device).
-@end defun
-
-@node Truenames
-@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.
-
-This function does not expand environment variables.  Only
-@code{substitute-in-file-name} does that.  @xref{Definition of
-substitute-in-file-name}.
-
-If you may need to follow symbolic links preceding @samp{..}@:
-appearing as a name component, you should make sure to call
-@code{file-truename} without prior direct or indirect calls to
-@code{expand-file-name}, as otherwise the file name component
-immediately preceding @samp{..} will be ``simplified away'' before
-@code{file-truename} is called.  To eliminate the need for a call to
-@code{expand-file-name}, @code{file-truename} handles @samp{~} in the
-same way that @code{expand-file-name} does.  @xref{File Name
-Expansion,, Functions that Expand Filenames}.
-@end defun
-
-@defun file-chase-links filename &optional limit
-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.  This function does @emph{not} follow
-symbolic links at the level of parent directories.
-
-If you specify a number for @var{limit}, then after chasing through
-that many links, the function just returns what it has even if that is
-still a symbolic link.
-@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
-@subsection Other Information about Files
-
-  This section describes the functions for getting detailed information
-about a file, other than its contents.  This information includes the
-mode bits that control access permission, the owner and group numbers,
-the number of names, the inode number, the size, and the times of access
-and modification.
-
-@defun file-modes filename
-@cindex permission
-@cindex file attributes
-This function returns the mode bits of @var{filename}, as an integer.
-The mode bits are also called the file permissions, and they specify
-access control in the usual Unix fashion.  If the low-order bit is 1,
-then the file is executable by all users, if the second-lowest-order bit
-is 1, then the file is writable by all users, etc.
-
-The highest value returnable is 4095 (7777 octal), meaning that
-everyone has read, write, and execute permission, that the @acronym{SUID} bit
-is set for both others and group, and that the sticky bit is set.
-
-If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
-
-This function recursively follows symbolic links at all levels.
-
-@example
-@group
-(file-modes "~/junk/diffs")
-     @result{} 492               ; @r{Decimal integer.}
-@end group
-@group
-(format "%o" 492)
-     @result{} "754"             ; @r{Convert to octal.}
-@end group
-
-@group
-(set-file-modes "~/junk/diffs" 438)
-     @result{} nil
-@end group
-
-@group
-(format "%o" 438)
-     @result{} "666"             ; @r{Convert to octal.}
-@end group
-
-@group
-% ls -l diffs
-  -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
-@end group
-@end example
-@end defun
-
-If the @var{filename} argument to the next two functions is a symbolic
-link, then these function do @emph{not} replace it with its target.
-However, they both recursively follow symbolic links at all levels of
-parent directories.
-
-@defun file-nlinks filename
-This functions returns the number of names (i.e., hard links) that
-file @var{filename} has.  If the file does not exist, then this function
-returns @code{nil}.  Note that symbolic links have no effect on this
-function, because they are not considered to be names of the files they
-link to.
-
-@example
-@group
-% ls -l foo*
--rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
--rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1
-@end group
-
-@group
-(file-nlinks "foo")
-     @result{} 2
-@end group
-@group
-(file-nlinks "doesnt-exist")
-     @result{} nil
-@end group
-@end example
-@end defun
-
-@defun file-attributes filename &optional id-format
-@anchor{Definition of file-attributes}
-This function returns a list of attributes of file @var{filename}.  If
-the specified file cannot be opened, it returns @code{nil}.
-The optional parameter @var{id-format} specifies the preferred format
-of attributes @acronym{UID} and @acronym{GID} (see below)---the
-valid values are @code{'string} and @code{'integer}.  The latter is
-the default, but we plan to change that, so you should specify a
-non-@code{nil} value for @var{id-format} if you use the returned
-@acronym{UID} or @acronym{GID}.
-
-The elements of the list, in order, are:
-
-@enumerate 0
-@item
-@code{t} for a directory, a string for a symbolic link (the name
-linked to), or @code{nil} for a text file.
-
-@c Wordy so as to prevent an overfull hbox.  --rjc 15mar92
-@item
-The number of names the file has.  Alternate names, also known as hard
-links, can be created by using the @code{add-name-to-file} function
-(@pxref{Changing Files}).
-
-@item
-The file's @acronym{UID}, normally as a string.  However, if it does
-not correspond to a named user, the value is an integer or a floating
-point number.
-
-@item
-The file's @acronym{GID}, likewise.
-
-@item
-The time of last access, as a list of two integers.
-The first integer has the high-order 16 bits of time,
-the second has the low 16 bits.  (This is similar to the
-value of @code{current-time}; see @ref{Time of Day}.)
-
-@item
-The time of last modification as a list of two integers (as above).
-@cindex modification time of file
-
-@item
-The time of last status change as a list of two integers (as above).
-
-@item
-The size of the file in bytes.  If the size is too large to fit in a
-Lisp integer, this is a floating point number.
-
-@item
-The file's modes, as a string of ten letters or dashes,
-as in @samp{ls -l}.
-
-@item
-@code{t} if the file's @acronym{GID} would change if file were
-deleted and recreated; @code{nil} otherwise.
-
-@item
-The file's inode number.  If possible, this is an integer.  If the inode
-number is too large to be represented as an integer in Emacs Lisp, then
-the value has the form @code{(@var{high} . @var{low})}, where @var{low}
-holds the low 16 bits.
-
-@item
-The file system number of the file system that the file is in.
-Depending on the magnitude of the value, this can be either an integer
-or a cons cell, in the same manner as the inode number.  This element
-and the file's inode number together give enough information to
-distinguish any two files on the system---no two files can have the same
-values for both of these numbers.
-@end enumerate
-
-For example, here are the file attributes for @file{files.texi}:
-
-@example
-@group
-(file-attributes "files.texi" 'string)
-     @result{}  (nil 1 "lh" "users"
-          (8489 20284)
-          (8489 20284)
-          (8489 20285)
-          14906 "-rw-rw-rw-"
-          nil 129500 -32252)
-@end group
-@end example
-
-@noindent
-and here is how the result is interpreted:
-
-@table @code
-@item nil
-is neither a directory nor a symbolic link.
-
-@item 1
-has only one name (the name @file{files.texi} in the current default
-directory).
-
-@item "lh"
-is owned by the user with name "lh".
-
-@item "users"
-is in the group with name "users".
-
-@item (8489 20284)
-was last accessed on Aug 19 00:09.
-
-@item (8489 20284)
-was last modified on Aug 19 00:09.
-
-@item (8489 20285)
-last had its inode changed on Aug 19 00:09.
-
-@item 14906
-is 14906 bytes long.  (It may not contain 14906 characters, though,
-if some of the bytes belong to multibyte sequences.)
-
-@item "-rw-rw-rw-"
-has a mode of read and write access for the owner, group, and world.
-
-@item nil
-would retain the same @acronym{GID} if it were recreated.
-
-@item 129500
-has an inode number of 129500.
-@item -32252
-is on file system number -32252.
-@end table
-@end defun
-
-@node Locating Files
-@subsection How to Locate Files in Standard Places
-@cindex locate file in path
-@cindex find file in path
-
-  This section explains how to search for a file in a list of
-directories (a @dfn{path}).  One example is when you need to look for
-a program's executable file, e.g., to find out whether a given program
-is installed on the user's system.  Another example is the search for
-Lisp libraries (@pxref{Library Search}).  Such searches generally need
-to try various possible file name extensions, in addition to various
-possible directories.  Emacs provides a function for such a
-generalized search for a file.
-
-@defun locate-file filename path &optional suffixes predicate
-This function searches for a file whose name is @var{filename} in a
-list of directories given by @var{path}, trying the suffixes in
-@var{suffixes}.  If it finds such a file, it returns the full
-@dfn{absolute file name} of the file (@pxref{Relative File Names});
-otherwise it returns @code{nil}.
-
-The optional argument @var{suffixes} gives the list of file-name
-suffixes to append to @var{filename} when searching.
-@code{locate-file} tries each possible directory with each of these
-suffixes.  If @var{suffixes} is @code{nil}, or @code{("")}, then there
-are no suffixes, and @var{filename} is used only as-is.  Typical
-values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
-Creation, exec-suffixes}), @code{load-suffixes},
-@code{load-file-rep-suffixes} and the return value of the function
-@code{get-load-suffixes} (@pxref{Load Suffixes}).
-
-Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
-Creation, exec-path}) when looking for executable programs or
-@code{load-path} (@pxref{Library Search, load-path}) when looking for
-Lisp files.  If @var{filename} is absolute, @var{path} has no effect,
-but the suffixes in @var{suffixes} are still tried.
-
-The optional argument @var{predicate}, if non-@code{nil}, specifies
-the predicate function to use for testing whether a candidate file is
-suitable.  The predicate function is passed the candidate file name as
-its single argument.  If @var{predicate} is @code{nil} or unspecified,
-@code{locate-file} uses @code{file-readable-p} as the default
-predicate.  Useful non-default predicates include
-@code{file-executable-p}, @code{file-directory-p}, and other
-predicates described in @ref{Kinds of Files}.
-
-For compatibility, @var{predicate} can also be one of the symbols
-@code{executable}, @code{readable}, @code{writable}, @code{exists}, or
-a list of one or more of these symbols.
-@end defun
-
-@defun executable-find program
-This function searches for the executable file of the named
-@var{program} and returns the full absolute name of the executable,
-including its file-name extensions, if any.  It returns @code{nil} if
-the file is not found.  The functions searches in all the directories
-in @code{exec-path} and tries all the file-name extensions in
-@code{exec-suffixes}.
-@end defun
-
-@node Changing Files
-@section Changing File Names and Attributes
-@c @cindex renaming files  Duplicates rename-file
-@cindex copying files
-@cindex deleting files
-@cindex linking files
-@cindex setting modes of files
-
-  The functions in this section rename, copy, delete, link, and set the
-modes of files.
-
-  In the functions that have an argument @var{newname}, if a file by the
-name of @var{newname} already exists, the actions taken depend on the
-value of the argument @var{ok-if-already-exists}:
-
-@itemize @bullet
-@item
-Signal a @code{file-already-exists} error if
-@var{ok-if-already-exists} is @code{nil}.
-
-@item
-Request confirmation if @var{ok-if-already-exists} is a number.
-
-@item
-Replace the old file without confirmation if @var{ok-if-already-exists}
-is any other value.
-@end itemize
-
-The next four commands all recursively follow symbolic links at all
-levels of parent directories for their first argument, but, if that
-argument is itself a symbolic link, then only @code{copy-file}
-replaces it with its (recursive) target.
-
-@deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
-@cindex file with multiple names
-@cindex file hard link
-This function gives the file named @var{oldname} the additional name
-@var{newname}.  This means that @var{newname} becomes a new ``hard
-link'' to @var{oldname}.
-
-In the first part of the following example, we list two files,
-@file{foo} and @file{foo3}.
-
-@example
-@group
-% ls -li fo*
-81908 -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
-84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
-@end group
-@end example
-
-Now we create a hard link, by calling @code{add-name-to-file}, then list
-the files again.  This shows two names for one file, @file{foo} and
-@file{foo2}.
-
-@example
-@group
-(add-name-to-file "foo" "foo2")
-     @result{} nil
-@end group
-
-@group
-% ls -li fo*
-81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
-81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
-84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
-@end group
-@end example
-
-Finally, we evaluate the following:
-
-@example
-(add-name-to-file "foo" "foo3" t)
-@end example
-
-@noindent
-and list the files again.  Now there are three names
-for one file: @file{foo}, @file{foo2}, and @file{foo3}.  The old
-contents of @file{foo3} are lost.
-
-@example
-@group
-(add-name-to-file "foo1" "foo3")
-     @result{} nil
-@end group
-
-@group
-% ls -li fo*
-81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
-81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
-81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
-@end group
-@end example
-
-This function is meaningless on operating systems where multiple names
-for one file are not allowed.  Some systems implement multiple names
-by copying the file instead.
-
-See also @code{file-nlinks} in @ref{File Attributes}.
-@end deffn
-
-@deffn Command rename-file filename newname &optional ok-if-already-exists
-This command renames the file @var{filename} as @var{newname}.
-
-If @var{filename} has additional names aside from @var{filename}, it
-continues to have those names.  In fact, adding the name @var{newname}
-with @code{add-name-to-file} and then deleting @var{filename} has the
-same effect as renaming, aside from momentary intermediate states.
-@end deffn
-
-@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
-This command copies the file @var{oldname} to @var{newname}.  An
-error is signaled if @var{oldname} does not exist.  If @var{newname}
-names a directory, it copies @var{oldname} into that directory,
-preserving its final name component.
-
-If @var{time} is non-@code{nil}, then this function gives the new file
-the same last-modified time that the old one has.  (This works on only
-some operating systems.)  If setting the time gets an error,
-@code{copy-file} signals a @code{file-date-error} error.  In an
-interactive call, a prefix argument specifies a non-@code{nil} value
-for @var{time}.
-
-This function copies the file modes, too.
-
-If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
-system decide the user and group ownership of the new file (this is
-usually set to the user running Emacs).  If @var{preserve-uid-gid} is
-non-@code{nil}, we attempt to copy the user and group ownership of the
-file.  This works only on some operating systems, and only if you have
-the correct permissions to do so.
-@end deffn
-
-@deffn Command make-symbolic-link filename newname  &optional ok-if-exists
-@pindex ln
-@kindex file-already-exists
-This command makes a symbolic link to @var{filename}, named
-@var{newname}.  This is like the shell command @samp{ln -s
-@var{filename} @var{newname}}.
-
-This function is not available on systems that don't support symbolic
-links.
-@end deffn
-
-@deffn Command delete-file filename
-@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.)
-
-If @var{filename} is a symbolic link, @code{delete-file} does not
-replace it with its target, but it does follow symbolic links at all
-levels of parent directories.
-
-See also @code{delete-directory} in @ref{Create/Delete Dirs}.
-@end deffn
-
-@defun define-logical-name varname string
-This function defines the logical name @var{varname} to have the value
-@var{string}.  It is available only on VMS.
-@end defun
-
-@defun set-file-modes filename mode
-This function sets mode bits of @var{filename} to @var{mode} (which
-must be an integer).  Only the low 12 bits of @var{mode} are used.
-This function recursively follows symbolic links at all levels for
-@var{filename}.
-@end defun
-
-@c Emacs 19 feature
-@defun set-default-file-modes mode
-@cindex umask
-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, or a subset of it (@code{write-region} will not give a
-file execute permission even if the default file protection allows
-execute permission).  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.  You can use the Lisp construct
-for octal character codes to enter @var{mode}; for example,
-
-@example
-(set-default-file-modes ?\644)
-@end example
-
-Saving a modified version of an existing file does not count as creating
-the file; it preserves the existing file's mode, whatever that is.  So
-the default file protection has no effect.
-@end defun
-
-@defun default-file-modes
-This function returns the current default protection value.
-@end defun
-
-@defun set-file-times filename &optional time
-This function sets the access and modification times of @var{filename}
-to @var{time}.  The return value is @code{t} if the times are successfully
-set, otherwise it is @code{nil}.  @var{time} defaults to the current
-time and must be in the format returned by @code{current-time}
-(@pxref{Time of Day}).
-@end defun
-
-@cindex MS-DOS and file modes
-@cindex file modes and MS-DOS
-  On MS-DOS, there is no such thing as an ``executable'' file mode bit.
-So Emacs considers a file executable if its name ends in one of the
-standard executable extensions, such as @file{.com}, @file{.bat},
-@file{.exe}, and some others.  Files that begin with the Unix-standard
-@samp{#!} signature, such as shell and Perl scripts, are also considered
-as executable files.  This is reflected in the values returned by
-@code{file-modes} and @code{file-attributes}.  Directories are also
-reported with executable bit set, for compatibility with Unix.
-
-@node File Names
-@section File Names
-@cindex file names
-
-  Files are generally referred to by their names, in Emacs as elsewhere.
-File names in Emacs are represented as strings.  The functions that
-operate on a file all expect a file name argument.
-
-  In addition to operating on files themselves, Emacs Lisp programs
-often need to operate on file names; i.e., to take them apart and to use
-part of a name to construct related file names.  This section describes
-how to manipulate file names.
-
-  The functions in this section do not actually access files, so they
-can operate on file names that do not refer to an existing file or
-directory.
-
-  On MS-DOS and MS-Windows, these functions (like the function that
-actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
-where backslashes separate the components, as well as Unix syntax; but
-they always return Unix syntax.  On VMS, these functions (and the ones
-that operate on files) understand both VMS file-name syntax and Unix
-syntax.  This enables Lisp programs to specify file names in Unix syntax
-and work properly on all systems without change.
-
-@menu
-* File Name Components::  The directory part of a file name, and the rest.
-* Relative File Names::   Some file names are relative to a current directory.
-* Directory Names::       A directory's name as a directory
-                            is different from its name as a file.
-* File Name Expansion::   Converting relative file names to absolute ones.
-* Unique File Names::     Generating names for temporary files.
-* File Name Completion::  Finding the completions for a given file name.
-* Standard File Names::   If your package uses a fixed file name,
-                            how to handle various operating systems simply.
-@end menu
-
-@node File Name Components
-@subsection File Name Components
-@cindex directory part (of file name)
-@cindex nondirectory part (of file name)
-@cindex version number (in file name)
-
-  The operating system groups files into directories.  To specify a
-file, you must specify the directory and the file's name within that
-directory.  Therefore, Emacs considers a file name as having two main
-parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
-(or @dfn{file name within the directory}).  Either part may be empty.
-Concatenating these two parts reproduces the original file name.
-
-  On most systems, the directory part is everything up to and including
-the last slash (backslash is also allowed in input on MS-DOS or
-MS-Windows); the nondirectory part is the rest.  The rules in VMS syntax
-are complicated.
-
-  For some purposes, the nondirectory part is further subdivided into
-the name proper and the @dfn{version number}.  On most systems, only
-backup files have version numbers in their names.  On VMS, every file
-has a version number, but most of the time the file name actually used
-in Emacs omits the version number, so that version numbers in Emacs are
-found mostly in directory lists.
-
-@defun file-name-directory filename
-This function returns the directory part of @var{filename}, as a
-directory name (@pxref{Directory Names}), or @code{nil} if
-@var{filename} does not include a directory part.
-
-On GNU and Unix systems, a string returned by this function always
-ends in a slash.  On MS-DOS it can also end in a colon.  On VMS, it
-returns a string ending in one of the three characters @samp{:},
-@samp{]}, or @samp{>}.
-
-@example
-@group
-(file-name-directory "lewis/foo")  ; @r{Unix example}
-     @result{} "lewis/"
-@end group
-@group
-(file-name-directory "foo")        ; @r{Unix example}
-     @result{} nil
-@end group
-@group
-(file-name-directory "[X]FOO.TMP") ; @r{VMS example}
-     @result{} "[X]"
-@end group
-@end example
-@end defun
-
-@defun file-name-nondirectory filename
-This function returns the nondirectory part of @var{filename}.
-
-@example
-@group
-(file-name-nondirectory "lewis/foo")
-     @result{} "foo"
-@end group
-@group
-(file-name-nondirectory "foo")
-     @result{} "foo"
-@end group
-@group
-(file-name-nondirectory "lewis/")
-     @result{} ""
-@end group
-@group
-;; @r{The following example is accurate only on VMS.}
-(file-name-nondirectory "[X]FOO.TMP")
-     @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"
-@end group
-@group
-(file-name-sans-versions "~rms/foo~")
-     @result{} "~rms/foo"
-@end group
-@group
-(file-name-sans-versions "~rms/foo")
-     @result{} "~rms/foo"
-@end group
-@group
-;; @r{The following example applies to VMS only.}
-(file-name-sans-versions "foo;23")
-     @result{} "foo"
-@end group
-@end example
-@end defun
-
-@defun file-name-extension filename &optional period
-This function returns @var{filename}'s final ``extension,'' if any,
-after applying @code{file-name-sans-versions} to remove any
-version/backup part.  The extension, in a file name, is the part that
-starts with the last @samp{.} in the last name component (minus
-any version/backup part).
-
-This function returns @code{nil} for extensionless file names such as
-@file{foo}.  It returns @code{""} for null extensions, as in
-@file{foo.}.  If the last component of a file name begins with a
-@samp{.}, that @samp{.}  doesn't count as the beginning of an
-extension.  Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
-@samp{.emacs}.
-
-If @var{period} is non-@code{nil}, then the returned value includes
-the period that delimits the extension, and if @var{filename} has no
-extension, the value is @code{""}.
-@end defun
-
-@defun file-name-sans-extension filename
-This function returns @var{filename} minus its extension, if any.  The
-version/backup part, if present, is only removed if the file has an
-extension.  For example,
-
-@example
-(file-name-sans-extension "foo.lose.c")
-     @result{} "foo.lose"
-(file-name-sans-extension "big.hack/foo")
-     @result{} "big.hack/foo"
-(file-name-sans-extension "/my/home/.emacs")
-     @result{} "/my/home/.emacs"
-(file-name-sans-extension "/my/home/.emacs.el")
-     @result{} "/my/home/.emacs"
-(file-name-sans-extension "~/foo.el.~3~")
-     @result{} "~/foo"
-(file-name-sans-extension "~/foo.~3~")
-     @result{} "~/foo.~3~"
-@end example
-
-Note that the @samp{.~3~} in the two last examples is the backup part,
-not an extension.
-@end defun
-
-@ignore
-Andrew Innes says that this
-
-@c @defvar directory-sep-char
-This variable holds the character that Emacs normally uses to separate
-file name components.  The default value is @code{?/}, but on MS-Windows
-you can set it to @code{?\\}; then the functions that transform file names
-use backslashes in their output.
-
-File names using backslashes work as input to Lisp primitives even on
-MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
-value of @code{?/}.
-@end defvar
-@end ignore
-
-@node Relative File Names
-@subsection Absolute and Relative File Names
-@cindex absolute file name
-@cindex relative file name
-
-  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.
-
-@example
-@group
-(file-name-absolute-p "~rms/foo")
-     @result{} t
-@end group
-@group
-(file-name-absolute-p "rms/foo")
-     @result{} nil
-@end group
-@group
-(file-name-absolute-p "/user/rms/foo")
-     @result{} t
-@end group
-@end example
-@end defun
-
-  Given a possibly relative file name, you can convert it to an
-absolute name using @code{expand-file-name} (@pxref{File Name
-Expansion}).  This function converts absolute file names to relative
-names:
-
-@defun file-relative-name filename &optional directory
-This function tries to return a relative name that is equivalent to
-@var{filename}, assuming the result will be interpreted relative to
-@var{directory} (an absolute directory name or directory file name).
-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
-form.
-
-@example
-(file-relative-name "/foo/bar" "/foo/")
-     @result{} "bar"
-(file-relative-name "/foo/bar" "/hack/")
-     @result{} "../foo/bar"
-@end example
-@end defun
-
-@node Directory Names
-@comment  node-name,  next,  previous,  up
-@subsection Directory Names
-@cindex directory name
-@cindex file name of directory
-
-  A @dfn{directory name} is the name of a directory.  A directory is
-actually a kind of file, so it has a file name, which is related to
-the directory name but not identical to it.  (This is not quite the
-same as the usual Unix terminology.)  These two different names for
-the same entity are related by a syntactic transformation.  On GNU and
-Unix systems, this is simple: a directory name ends in a slash,
-whereas the directory's name as a file lacks that slash.  On MS-DOS and
-VMS, the relationship is more complicated.
-
-  The difference between a directory name and its name as a file is
-subtle but crucial.  When an Emacs variable or function argument is
-described as being a directory name, a file name of a directory is not
-acceptable.  When @code{file-name-directory} returns a string, that is
-always a directory name.
-
-  The following two functions convert between directory names and file
-names.  They do nothing special with environment variable substitutions
-such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
-
-@defun file-name-as-directory filename
-This function returns a string representing @var{filename} in a form
-that the operating system will interpret as the name of a directory.  On
-most systems, this means appending a slash to the string (if it does not
-already end in one).  On VMS, the function converts a string of the form
-@file{[X]Y.DIR.1} to the form @file{[X.Y]}.
-
-@example
-@group
-(file-name-as-directory "~rms/lewis")
-     @result{} "~rms/lewis/"
-@end group
-@end example
-@end defun
-
-@defun directory-file-name dirname
-This function returns a string representing @var{dirname} in a form that
-the operating system will interpret as the name of a file.  On most
-systems, this means removing the final slash (or backslash) from the
-string.  On VMS, the function converts a string of the form @file{[X.Y]}
-to @file{[X]Y.DIR.1}.
-
-@example
-@group
-(directory-file-name "~lewis/")
-     @result{} "~lewis"
-@end group
-@end example
-@end defun
-
-  Given a directory name, you can combine it with a relative file name
-using @code{concat}:
-
-@example
-(concat @var{dirname} @var{relfile})
-@end example
-
-@noindent
-Be sure to verify that the file name is relative before doing that.
-If you use an absolute file name, the results could be syntactically
-invalid or refer to the wrong file.
-
-  If you want to use a directory file name in making such a
-combination, you must first convert it to a directory name using
-@code{file-name-as-directory}:
-
-@example
-(concat (file-name-as-directory @var{dirfile}) @var{relfile})
-@end example
-
-@noindent
-Don't try concatenating a slash by hand, as in
-
-@example
-;;; @r{Wrong!}
-(concat @var{dirfile} "/" @var{relfile})
-@end example
-
-@noindent
-because this is not portable.  Always use
-@code{file-name-as-directory}.
-
-@cindex directory name abbreviation
-  Directory name abbreviations are useful for directories that are
-normally accessed through symbolic links.  Sometimes the users recognize
-primarily the link's name as ``the name'' of the directory, and find it
-annoying to see the directory's ``real'' name.  If you define the link
-name as an abbreviation for the ``real'' name, Emacs shows users the
-abbreviation instead.
-
-@defvar directory-abbrev-alist
-The variable @code{directory-abbrev-alist} contains an alist of
-abbreviations to use for file directories.  Each element has the form
-@code{(@var{from} . @var{to})}, and says to replace @var{from} with
-@var{to} when it appears in a directory name.  The @var{from} string is
-actually a regular expression; it should always start with @samp{^}.
-The @var{to} string should be an ordinary absolute directory name.  Do
-not use @samp{~} to stand for a home directory in that string.  The
-function @code{abbreviate-file-name} performs these substitutions.
-
-You can set this variable in @file{site-init.el} to describe the
-abbreviations appropriate for your site.
-
-Here's an example, from a system on which file system @file{/home/fsf}
-and so on are normally accessed through symbolic links named @file{/fsf}
-and so on.
-
-@example
-(("^/home/fsf" . "/fsf")
- ("^/home/gp" . "/gp")
- ("^/home/gd" . "/gd"))
-@end example
-@end defvar
-
-  To convert a directory name to its abbreviation, use this
-function:
-
-@defun abbreviate-file-name filename
-@anchor{Definition of abbreviate-file-name}
-This function applies abbreviations from @code{directory-abbrev-alist}
-to its argument, and substitutes @samp{~} for the user's home
-directory.  You can use it for directory names and for file names,
-because it recognizes abbreviations even as part of the name.
-@end defun
-
-@node File Name Expansion
-@subsection Functions that Expand Filenames
-@cindex expansion of file names
-
-  @dfn{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 @file{./} and @file{@var{name}/../}.
-
-@defun expand-file-name filename &optional directory
-This function converts @var{filename} to an absolute file name.  If
-@var{directory} is supplied, it is the default directory to start with
-if @var{filename} is relative.  (The value of @var{directory} should
-itself be an absolute directory name or directory file name; it may
-start with @samp{~}.)  Otherwise, the current buffer's value of
-@code{default-directory} is used.  For example:
-
-@example
-@group
-(expand-file-name "foo")
-     @result{} "/xcssun/users/rms/lewis/foo"
-@end group
-@group
-(expand-file-name "../foo")
-     @result{} "/xcssun/users/rms/foo"
-@end group
-@group
-(expand-file-name "foo" "/usr/spool/")
-     @result{} "/usr/spool/foo"
-@end group
-@group
-(expand-file-name "$HOME/foo")
-     @result{} "/xcssun/users/rms/lewis/$HOME/foo"
-@end group
-@end example
-
-If the part of the combined file name before the first slash is
-@samp{~}, it expands to the value of the @env{HOME} environment
-variable (usually your home directory).  If the part before the first
-slash is @samp{~@var{user}} and if @var{user} is a valid login name,
-it expands to @var{user}'s home directory.
-
-Filenames containing @samp{.} or @samp{..} are simplified to their
-canonical form:
-
-@example
-@group
-(expand-file-name "bar/../foo")
-     @result{} "/xcssun/users/rms/lewis/foo"
-@end group
-@end example
-
-In some cases, a leading @samp{..} component can remain in the output:
-
-@example
-@group
-(expand-file-name "../home" "/")
-     @result{} "/../home"
-@end group
-@end example
-
-@noindent
-This is for the sake of filesystems that have the concept of a
-``superroot'' above the root directory @file{/}.  On other filesystems,
-@file{/../} is interpreted exactly the same as @file{/}.
-
-Note that @code{expand-file-name} does @emph{not} expand environment
-variables; only @code{substitute-in-file-name} does that.
-
-Note also that @code{expand-file-name} does not follow symbolic links
-at any level.  This results in a difference between the way
-@code{file-truename} and @code{expand-file-name} treat @samp{..}.
-Assuming that @samp{/tmp/bar} is a symbolic link to the directory
-@samp{/tmp/foo/bar} we get:
-
-@example
-@group
-(file-truename "/tmp/bar/../myfile")
-     @result{} "/tmp/foo/myfile"
-@end group
-@group
-(expand-file-name "/tmp/bar/../myfile")
-     @result{} "/tmp/myfile"
-@end group
-@end example
-
-If you may need to follow symbolic links preceding @samp{..}, you
-should make sure to call @code{file-truename} without prior direct or
-indirect calls to @code{expand-file-name}.  @xref{Truenames}.
-@end defun
-
-@defvar default-directory
-The value of this buffer-local variable is the default directory for the
-current buffer.  It should be an absolute directory name; it may start
-with @samp{~}.  This variable is buffer-local in every buffer.
-
-@code{expand-file-name} uses the default directory when its second
-argument is @code{nil}.
-
-Aside from VMS, the value is always a string ending with a slash.
-
-@example
-@group
-default-directory
-     @result{} "/user/lewis/manual/"
-@end group
-@end example
-@end defvar
-
-@defun substitute-in-file-name filename
-@anchor{Definition of substitute-in-file-name}
-This function replaces environment variable references in
-@var{filename} with the environment variable values.  Following
-standard Unix shell syntax, @samp{$} is the prefix to substitute an
-environment variable value.  If the input contains @samp{$$}, that is
-converted to @samp{$}; this gives the user a way to ``quote'' a
-@samp{$}.
-
-The environment variable name is the series of alphanumeric characters
-(including underscores) that follow the @samp{$}.  If the character following
-the @samp{$} is a @samp{@{}, then the variable name is everything up to the
-matching @samp{@}}.
-
-Calling @code{substitute-in-file-name} on output produced by
-@code{substitute-in-file-name} tends to give incorrect results.  For
-instance, use of @samp{$$} to quote a single @samp{$} won't work
-properly, and @samp{$} in an environment variable's value could lead
-to repeated substitution.  Therefore, programs that call this function
-and put the output where it will be passed to this function need to
-double all @samp{$} characters to prevent subsequent incorrect
-results.
-
-@c Wordy to avoid overfull hbox.  --rjc 15mar92
-Here we assume that the environment variable @code{HOME}, which holds
-the user's home directory name, has value @samp{/xcssun/users/rms}.
-
-@example
-@group
-(substitute-in-file-name "$HOME/foo")
-     @result{} "/xcssun/users/rms/foo"
-@end group
-@end example
-
-After substitution, if a @samp{~} or a @samp{/} appears immediately
-after another @samp{/}, the function discards everything before it (up
-through the immediately preceding @samp{/}).
-
-@example
-@group
-(substitute-in-file-name "bar/~/foo")
-     @result{} "~/foo"
-@end group
-@group
-(substitute-in-file-name "/usr/local/$HOME/foo")
-     @result{} "/xcssun/users/rms/foo"
-     ;; @r{@file{/usr/local/} has been discarded.}
-@end group
-@end example
-
-On VMS, @samp{$} substitution is not done, so this function does nothing
-on VMS except discard superfluous initial components as shown above.
-@end defun
-
-@node Unique File Names
-@subsection Generating Unique File Names
-
-  Some programs need to write temporary files.  Here is the usual way to
-construct a name for such a file:
-
-@example
-(make-temp-file @var{name-of-application})
-@end example
-
-@noindent
-The job of @code{make-temp-file} is to prevent two different users or
-two different jobs from trying to use the exact same file name.
-
-@defun make-temp-file prefix &optional dir-flag suffix
-This function creates a temporary file and returns its name.  Emacs
-creates the temporary file's name by adding to @var{prefix} some
-random characters that are different in each Emacs job.  The result is
-guaranteed to be a newly created empty file.  On MS-DOS, this function
-can truncate the @var{string} prefix to fit into the 8+3 file-name
-limits.  If @var{prefix} is a relative file name, it is expanded
-against @code{temporary-file-directory}.
-
-@example
-@group
-(make-temp-file "foo")
-     @result{} "/tmp/foo232J6v"
-@end group
-@end example
-
-When @code{make-temp-file} returns, the file has been created and is
-empty.  At that point, you should write the intended contents into the
-file.
-
-If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
-empty directory instead of an empty file.  It returns the file name,
-not the directory name, of that directory.  @xref{Directory Names}.
-
-If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
-the end of the file name.
-
-To prevent conflicts among different libraries running in the same
-Emacs, each Lisp program that uses @code{make-temp-file} should have its
-own @var{prefix}.  The number added to the end of @var{prefix}
-distinguishes between the same application running in different Emacs
-jobs.  Additional added characters permit a large number of distinct
-names even in one Emacs job.
-@end defun
-
-  The default directory for temporary files is controlled by the
-variable @code{temporary-file-directory}.  This variable gives the user
-a uniform way to specify the directory for all temporary files.  Some
-programs use @code{small-temporary-file-directory} instead, if that is
-non-@code{nil}.  To use it, you should expand the prefix against
-the proper directory before calling @code{make-temp-file}.
-
-  In older Emacs versions where @code{make-temp-file} does not exist,
-you should use @code{make-temp-name} instead:
-
-@example
-(make-temp-name
- (expand-file-name @var{name-of-application}
-                   temporary-file-directory))
-@end example
-
-@defun make-temp-name string
-This function generates a string that can be used as a unique file
-name.  The name starts with @var{string}, and has several random
-characters appended to it, which are different in each Emacs job.  It
-is like @code{make-temp-file} except that it just constructs a name,
-and does not create a file.  Another difference is that @var{string}
-should be an absolute file name.  On MS-DOS, this function can
-truncate the @var{string} prefix to fit into the 8+3 file-name limits.
-@end defun
-
-@defvar temporary-file-directory
-@cindex @code{TMPDIR} environment variable
-@cindex @code{TMP} environment variable
-@cindex @code{TEMP} environment variable
-This variable specifies the directory name for creating temporary files.
-Its value should be a directory name (@pxref{Directory Names}), but it
-is good for Lisp programs to cope if the value is a directory's file
-name instead.  Using the value as the second argument to
-@code{expand-file-name} is a good way to achieve that.
-
-The default value is determined in a reasonable way for your operating
-system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
-environment variables, with a fall-back to a system-dependent name if
-none of these variables is defined.
-
-Even if you do not use @code{make-temp-file} to create the temporary
-file, you should still use this variable to decide which directory to
-put the file in.  However, if you expect the file to be small, you
-should use @code{small-temporary-file-directory} first if that is
-non-@code{nil}.
-@end defvar
-
-@defvar small-temporary-file-directory
-This variable specifies the directory name for
-creating certain temporary files, which are likely to be small.
-
-If you want to write a temporary file which is likely to be small, you
-should compute the directory like this:
-
-@example
-(make-temp-file
-  (expand-file-name @var{prefix}
-                    (or small-temporary-file-directory
-                        temporary-file-directory)))
-@end example
-@end defvar
-
-@node File Name Completion
-@subsection File Name Completion
-@cindex file name completion subroutines
-@cindex completion, file name
-
-  This section describes low-level subroutines for completing a file
-name.  For higher level functions, see @ref{Reading File Names}.
-
-@defun file-name-all-completions partial-filename directory
-This function returns a list of all possible completions for a file
-whose name starts with @var{partial-filename} in directory
-@var{directory}.  The order of the completions is the order of the files
-in the directory, which is unpredictable and conveys no useful
-information.
-
-The argument @var{partial-filename} must be a file name containing no
-directory part and no slash (or backslash on some systems).  The current
-buffer's default directory is prepended to @var{directory}, if
-@var{directory} is not absolute.
-
-In the following example, suppose that @file{~rms/lewis} is the current
-default directory, and has five files whose names begin with @samp{f}:
-@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
-@file{file.c.~2~}.@refill
-
-@example
-@group
-(file-name-all-completions "f" "")
-     @result{} ("foo" "file~" "file.c.~2~"
-                "file.c.~1~" "file.c")
-@end group
-
-@group
-(file-name-all-completions "fo" "")
-     @result{} ("foo")
-@end group
-@end example
-@end defun
-
-@defun file-name-completion filename directory &optional predicate
-This function completes the file name @var{filename} in directory
-@var{directory}.  It returns the longest prefix common to all file names
-in directory @var{directory} that start with @var{filename}.  If
-@var{predicate} is non-@code{nil} then it ignores possible completions
-that don't satisfy @var{predicate}, after calling that function
-with one argument, the expanded absolute file name.
-
-If only one match exists and @var{filename} matches it exactly, the
-function returns @code{t}.  The function returns @code{nil} if directory
-@var{directory} contains no name starting with @var{filename}.
-
-In the following example, suppose that the current default directory
-has five files whose names begin with @samp{f}: @file{foo},
-@file{file~}, @file{file.c}, @file{file.c.~1~}, and
-@file{file.c.~2~}.@refill
-
-@example
-@group
-(file-name-completion "fi" "")
-     @result{} "file"
-@end group
-
-@group
-(file-name-completion "file.c.~1" "")
-     @result{} "file.c.~1~"
-@end group
-
-@group
-(file-name-completion "file.c.~1~" "")
-     @result{} t
-@end group
-
-@group
-(file-name-completion "file.c.~3" "")
-     @result{} nil
-@end group
-@end example
-@end defun
-
-@defopt completion-ignored-extensions
-@code{file-name-completion} usually ignores file names that end in any
-string in this list.  It does not ignore them when all the possible
-completions end in one of these suffixes.  This variable has no effect
-on @code{file-name-all-completions}.@refill
-
-A typical value might look like this:
-
-@example
-@group
-completion-ignored-extensions
-     @result{} (".o" ".elc" "~" ".dvi")
-@end group
-@end example
-
-If an element of @code{completion-ignored-extensions} ends in a slash
-@samp{/}, it signals a directory.  The elements which do @emph{not} end
-in a slash will never match a directory; thus, the above value will not
-filter out a directory named @file{foo.elc}.
-@end defopt
-
-@node Standard File Names
-@subsection Standard File Names
-
-  Most of the file names used in Lisp programs are entered by the user.
-But occasionally a Lisp program needs to specify a standard file name
-for a particular use---typically, to hold customization information
-about each user.  For example, abbrev definitions are stored (by
-default) in the file @file{~/.abbrev_defs}; the @code{completion}
-package stores completions in the file @file{~/.completions}.  These are
-two of the many standard file names used by parts of Emacs for certain
-purposes.
-
-  Various operating systems have their own conventions for valid file
-names and for which file names to use for user profile data.  A Lisp
-program which reads a file using a standard file name ought to use, on
-each type of system, a file name suitable for that system.  The function
-@code{convert-standard-filename} makes this easy to do.
-
-@defun convert-standard-filename filename
-This function alters the file name @var{filename} to fit the conventions
-of the operating system in use, and returns the result as a new string.
-@end defun
-
-  The recommended way to specify a standard file name in a Lisp program
-is to choose a name which fits the conventions of GNU and Unix systems,
-usually with a nondirectory part that starts with a period, and pass it
-to @code{convert-standard-filename} instead of using it directly.  Here
-is an example from the @code{completion} package:
-
-@example
-(defvar save-completions-file-name
-        (convert-standard-filename "~/.completions")
-  "*The file name to save completions to.")
-@end example
-
-  On GNU and Unix systems, and on some other systems as well,
-@code{convert-standard-filename} returns its argument unchanged.  On
-some other systems, it alters the name to fit the system's conventions.
-
-  For example, on MS-DOS the alterations made by this function include
-converting a leading @samp{.}  to @samp{_}, converting a @samp{_} in the
-middle of the name to @samp{.} if there is no other @samp{.}, inserting
-a @samp{.} after eight characters if there is none, and truncating to
-three characters after the @samp{.}.  (It makes other changes as well.)
-Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
-@file{.completions} becomes @file{_complet.ion}.
-
-@node Contents of Directories
-@section Contents of Directories
-@cindex directory-oriented functions
-@cindex file names in directory
-
-  A directory is a kind of file that contains other files entered under
-various names.  Directories are a feature of the file system.
-
-  Emacs can list the names of the files in a directory as a Lisp list,
-or display the names in a buffer using the @code{ls} shell command.  In
-the latter case, it can optionally display information about each file,
-depending on the options passed to the @code{ls} command.
-
-@defun directory-files directory &optional full-name match-regexp nosort
-This function returns a list of the names of the files in the directory
-@var{directory}.  By default, the list is in alphabetical order.
-
-If @var{full-name} is non-@code{nil}, the function returns the files'
-absolute file names.  Otherwise, it returns the names relative to
-the specified directory.
-
-If @var{match-regexp} is non-@code{nil}, this function returns only
-those file names that contain a match for that regular expression---the
-other file names are excluded from the list.  On case-insensitive
-filesystems, the regular expression matching is case-insensitive.
-
-@c Emacs 19 feature
-If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
-the list, so you get the file names in no particular order.  Use this if
-you want the utmost possible speed and don't care what order the files
-are processed in.  If the order of processing is visible to the user,
-then the user will probably be happier if you do sort the names.
-
-@example
-@group
-(directory-files "~lewis")
-     @result{} ("#foo#" "#foo.el#" "." ".."
-         "dired-mods.el" "files.texi"
-         "files.texi.~1~")
-@end group
-@end example
-
-An error is signaled if @var{directory} is not the name of a directory
-that can be read.
-@end defun
-
-@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
-This is similar to @code{directory-files} in deciding which files
-to report on and how to report their names.  However, instead
-of returning a list of file names, it returns for each file a
-list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
-is what @code{file-attributes} would return for that file.
-The optional argument @var{id-format} has the same meaning as the
-corresponding argument to @code{file-attributes} (@pxref{Definition
-of file-attributes}).
-@end defun
-
-@defun file-name-all-versions file dirname
-This function returns a list of all versions of the file named
-@var{file} in directory @var{dirname}.  It is only available on VMS.
-@end defun
-
-@defun file-expand-wildcards pattern &optional full
-This function expands the wildcard pattern @var{pattern}, returning
-a list of file names that match it.
-
-If @var{pattern} is written as an absolute file name,
-the values are absolute also.
-
-If @var{pattern} is written as a relative file name, it is interpreted
-relative to the current default directory.  The file names returned are
-normally also relative to the current default directory.  However, if
-@var{full} is non-@code{nil}, they are absolute.
-@end defun
-
-@defun insert-directory file switches &optional wildcard full-directory-p
-This function inserts (in the current buffer) a directory listing for
-directory @var{file}, formatted with @code{ls} according to
-@var{switches}.  It leaves point after the inserted text.
-@var{switches} may be a string of options, or a list of strings
-representing individual options.
-
-The argument @var{file} may be either a directory name or a file
-specification including wildcard characters.  If @var{wildcard} is
-non-@code{nil}, that means treat @var{file} as a file specification with
-wildcards.
-
-If @var{full-directory-p} is non-@code{nil}, that means the directory
-listing is expected to show the full contents of a directory.  You
-should specify @code{t} when @var{file} is a directory and switches do
-not contain @samp{-d}.  (The @samp{-d} option to @code{ls} says to
-describe a directory itself as a file, rather than showing its
-contents.)
-
-On most systems, this function works by running a directory listing
-program whose name is in the variable @code{insert-directory-program}.
-If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
-@code{shell-file-name}, to expand the wildcards.
-
-MS-DOS and MS-Windows systems usually lack the standard Unix program
-@code{ls}, so this function emulates the standard Unix program @code{ls}
-with Lisp code.
-
-As a technical detail, when @var{switches} contains the long
-@samp{--dired} option, @code{insert-directory} treats it specially,
-for the sake of dired.  However, the normally equivalent short
-@samp{-D} option is just passed on to @code{insert-directory-program},
-as any other option.
-@end defun
-
-@defvar insert-directory-program
-This variable's value is the program to run to generate a directory listing
-for the function @code{insert-directory}.  It is ignored on systems
-which generate the listing with Lisp code.
-@end defvar
-
-@node Create/Delete Dirs
-@section Creating and Deleting Directories
-@cindex creating and deleting directories
-@c Emacs 19 features
-
-  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}, as is always the case in an
-interactive call, 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
-must use @code{delete-directory} for them.  If the directory contains
-any files, @code{delete-directory} signals an error.
-
-This function only follows symbolic links at the level of parent
-directories.
-@end defun
-
-@node Magic File Names
-@section Making Certain File Names ``Magic''
-@cindex magic file names
-
-@c Emacs 19 feature
-  You can implement special handling for certain file names.  This is
-called making those names @dfn{magic}.  The principal use for this
-feature is in implementing remote file names (@pxref{Remote Files,,
-Remote Files, emacs, The GNU Emacs Manual}).
-
-  To define a kind of magic file name, you must supply a regular
-expression to define the class of names (all those that match the
-regular expression), plus a handler that implements all the primitive
-Emacs file operations for file names that do match.
-
-  The variable @code{file-name-handler-alist} holds a list of handlers,
-together with regular expressions that determine when to apply each
-handler.  Each element has this form:
-
-@example
-(@var{regexp} . @var{handler})
-@end example
-
-@noindent
-All the Emacs primitives for file access and file name transformation
-check the given file name against @code{file-name-handler-alist}.  If
-the file name matches @var{regexp}, the primitives handle that file by
-calling @var{handler}.
-
-  The first argument given to @var{handler} is the name of the
-primitive, as a symbol; the remaining arguments are the arguments that
-were passed to that primitive.  (The first of these arguments is most
-often the file name itself.)  For example, if you do this:
-
-@example
-(file-exists-p @var{filename})
-@end example
-
-@noindent
-and @var{filename} has handler @var{handler}, then @var{handler} is
-called like this:
-
-@example
-(funcall @var{handler} 'file-exists-p @var{filename})
-@end example
-
-  When a function takes two or more arguments that must be file names,
-it checks each of those names for a handler.  For example, if you do
-this:
-
-@example
-(expand-file-name @var{filename} @var{dirname})
-@end example
-
-@noindent
-then it checks for a handler for @var{filename} and then for a handler
-for @var{dirname}.  In either case, the @var{handler} is called like
-this:
-
-@example
-(funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
-@end example
-
-@noindent
-The @var{handler} then needs to figure out whether to handle
-@var{filename} or @var{dirname}.
-
-  If the specified file name matches more than one handler, the one
-whose match starts last in the file name gets precedence.  This rule
-is chosen so that handlers for jobs such as uncompression are handled
-first, before handlers for jobs such as remote file access.
-
-  Here are the operations that a magic file name handler gets to handle:
-
-@ifnottex
-@noindent
-@code{access-file}, @code{add-name-to-file},
-@code{byte-compiler-base-file-name},@*
-@code{copy-file}, @code{delete-directory},
-@code{delete-file},
-@code{diff-latest-backup-file},
-@code{directory-file-name},
-@code{directory-files},
-@code{directory-files-and-attributes},
-@code{dired-compress-file}, @code{dired-uncache},@*
-@code{expand-file-name},
-@code{file-accessible-directory-p},
-@code{file-attributes},
-@code{file-directory-p},
-@code{file-executable-p}, @code{file-exists-p},
-@code{file-local-copy}, @code{file-remote-p},
-@code{file-modes}, @code{file-name-all-completions},
-@code{file-name-as-directory},
-@code{file-name-completion},
-@code{file-name-directory},
-@code{file-name-nondirectory},
-@code{file-name-sans-versions}, @code{file-newer-than-file-p},
-@code{file-ownership-preserved-p},
-@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
-@code{file-truename}, @code{file-writable-p},
-@code{find-backup-file-name},
-@code{find-file-noselect},@*
-@code{get-file-buffer},
-@code{insert-directory},
-@code{insert-file-contents},@*
-@code{load},
-@code{make-auto-save-file-name},
-@code{make-directory},
-@code{make-directory-internal},
-@code{make-symbolic-link},@*
-@code{process-file},
-@code{rename-file}, @code{set-file-modes}, @code{set-file-times},
-@code{set-visited-file-modtime}, @code{shell-command},
-@code{start-file-process},
-@code{substitute-in-file-name},@*
-@code{unhandled-file-name-directory},
-@code{vc-registered},
-@code{verify-visited-file-modtime},@*
-@code{write-region}.
-@end ifnottex
-@iftex
-@noindent
-@flushleft
-@code{access-file}, @code{add-name-to-file},
-@code{byte-com@discretionary{}{}{}piler-base-file-name},
-@code{copy-file}, @code{delete-directory},
-@code{delete-file},
-@code{diff-latest-backup-file},
-@code{directory-file-name},
-@code{directory-files},
-@code{directory-files-and-at@discretionary{}{}{}tributes},
-@code{dired-compress-file}, @code{dired-uncache},
-@code{expand-file-name},
-@code{file-accessible-direc@discretionary{}{}{}tory-p},
-@code{file-attributes},
-@code{file-direct@discretionary{}{}{}ory-p},
-@code{file-executable-p}, @code{file-exists-p},
-@code{file-local-copy}, @code{file-remote-p},
-@code{file-modes}, @code{file-name-all-completions},
-@code{file-name-as-directory},
-@code{file-name-completion},
-@code{file-name-directory},
-@code{file-name-nondirec@discretionary{}{}{}tory},
-@code{file-name-sans-versions}, @code{file-newer-than-file-p},
-@code{file-ownership-pre@discretionary{}{}{}served-p},
-@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
-@code{file-truename}, @code{file-writable-p},
-@code{find-backup-file-name},
-@code{find-file-noselect},
-@code{get-file-buffer},
-@code{insert-directory},
-@code{insert-file-contents},
-@code{load}, @code{make-direc@discretionary{}{}{}tory},
-@code{make-direc@discretionary{}{}{}tory-internal},
-@code{make-symbolic-link},
-@code{process-file},
-@code{rename-file}, @code{set-file-modes},
-@code{set-visited-file-modtime}, @code{shell-command},
-@code{start-file-process},
-@code{substitute-in-file-name},
-@code{unhandled-file-name-directory},
-@code{vc-regis@discretionary{}{}{}tered},
-@code{verify-visited-file-modtime},
-@code{write-region}.
-@end flushleft
-@end iftex
-
-  Handlers for @code{insert-file-contents} typically need to clear the
-buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
-@var{visit} argument is non-@code{nil}.  This also has the effect of
-unlocking the buffer if it is locked.
-
-  The handler function must handle all of the above operations, and
-possibly others to be added in the future.  It need not implement all
-these operations itself---when it has nothing special to do for a
-certain operation, it can reinvoke the primitive, to handle the
-operation ``in the usual way.''  It should always reinvoke the primitive
-for an operation it does not recognize.  Here's one way to do this:
-
-@smallexample
-(defun my-file-handler (operation &rest args)
-  ;; @r{First check for the specific operations}
-  ;; @r{that we have special handling for.}
-  (cond ((eq operation 'insert-file-contents) @dots{})
-        ((eq operation 'write-region) @dots{})
-        @dots{}
-        ;; @r{Handle any operation we don't know about.}
-        (t (let ((inhibit-file-name-handlers
-                  (cons 'my-file-handler
-                        (and (eq inhibit-file-name-operation operation)
-                             inhibit-file-name-handlers)))
-                 (inhibit-file-name-operation operation))
-             (apply operation args)))))
-@end smallexample
-
-  When a handler function decides to call the ordinary Emacs primitive for
-the operation at hand, it needs to prevent the primitive from calling
-the same handler once again, thus leading to an infinite recursion.  The
-example above shows how to do this, with the variables
-@code{inhibit-file-name-handlers} and
-@code{inhibit-file-name-operation}.  Be careful to use them exactly as
-shown above; the details are crucial for proper behavior in the case of
-multiple handlers, and for operations that have two file names that may
-each have handlers.
-
-@kindex safe-magic (@r{property})
-  Handlers that don't really do anything special for actual access to the
-file---such as the ones that implement completion of host names for
-remote file names---should have a non-@code{nil} @code{safe-magic}
-property.  For instance, Emacs normally ``protects'' directory names
-it finds in @code{PATH} from becoming magic, if they look like magic
-file names, by prefixing them with @samp{/:}.  But if the handler that
-would be used for them has a non-@code{nil} @code{safe-magic}
-property, the @samp{/:} is not added.
-
-@kindex operations (@r{property})
-  A file name handler can have an @code{operations} property to
-declare which operations it handles in a nontrivial way.  If this
-property has a non-@code{nil} value, it should be a list of
-operations; then only those operations will call the handler.  This
-avoids inefficiency, but its main purpose is for autoloaded handler
-functions, so that they won't be loaded except when they have real
-work to do.
-
-  Simply deferring all operations to the usual primitives does not
-work.  For instance, if the file name handler applies to
-@code{file-exists-p}, then it must handle @code{load} itself, because
-the usual @code{load} code won't work properly in that case.  However,
-if the handler uses the @code{operations} property to say it doesn't
-handle @code{file-exists-p}, then it need not handle @code{load}
-nontrivially.
-
-@defvar inhibit-file-name-handlers
-This variable holds a list of handlers whose use is presently inhibited
-for a certain operation.
-@end defvar
-
-@defvar inhibit-file-name-operation
-The operation for which certain handlers are presently inhibited.
-@end defvar
-
-@defun find-file-name-handler file operation
-This function returns the handler function for file name @var{file},
-or @code{nil} if there is none.  The argument @var{operation} should
-be the operation to be performed on the file---the value you will pass
-to the handler as its first argument when you call it.  If
-@var{operation} equals @code{inhibit-file-name-operation}, or if it is
-not found in the @code{operations} property of the handler, this
-function returns @code{nil}.
-@end defun
-
-@defun file-local-copy filename
-This function copies file @var{filename} to an ordinary non-magic file
-on the local machine, if it isn't on the local machine already.  Magic
-file names should handle the @code{file-local-copy} operation if they
-refer to files on other machines.  A magic file name that is used for
-other purposes than remote file access should not handle
-@code{file-local-copy}; then this function will treat the file as
-local.
-
-If @var{filename} is local, whether magic or not, this function does
-nothing and returns @code{nil}.  Otherwise it returns the file name
-of the local copy file.
-@end defun
-
-@defun file-remote-p filename &optional identification connected
-This function tests whether @var{filename} is a remote file.  If
-@var{filename} is local (not remote), the return value is @code{nil}.
-If @var{filename} is indeed remote, the return value is a string that
-identifies the remote system.
-
-This identifier string can include a host name and a user name, as
-well as characters designating the method used to access the remote
-system.  For example, the remote identifier string for the filename
-@code{/sudo::/some/file} is @code{/sudo:root@@localhost:}.
-
-If @code{file-remote-p} returns the same identifier for two different
-filenames, that means they are stored on the same file system and can
-be accessed locally with respect to each other.  This means, for
-example, that it is possible to start a remote process accessing both
-files at the same time.  Implementors of file handlers need to ensure
-this principle is valid.
-
-@var{identification} specifies which part of the identifier shall be
-returned as string.  @var{identification} can be the symbol
-@code{method}, @code{user} or @code{host}; any other value is handled
-like @code{nil} and means to return the complete identifier string.
-In the example above, the remote @code{user} identifier string would
-be @code{root}.
-
-If @var{connected} is non-@code{nil}, this function returns @code{nil}
-even if @var{filename} is remote, if Emacs has no network connection
-to its host.  This is useful when you want to avoid the delay of
-making connections when they don't exist.
-@end defun
-
-@defun unhandled-file-name-directory filename
-This function returns the name of a directory that is not magic.  It
-uses the directory part of @var{filename} if that is not magic.  For a
-magic file name, it invokes the file name handler, which therefore
-decides what value to return.
-
-This is useful for running a subprocess; every subprocess must have a
-non-magic directory to serve as its current directory, and this function
-is a good way to come up with one.
-@end defun
-
-@node Format Conversion
-@section File Format Conversion
-
-@cindex file format conversion
-@cindex encoding file formats
-@cindex decoding file formats
-@cindex text properties in files
-@cindex saving text properties
-  Emacs performs several steps to convert the data in a buffer (text,
-text properties, and possibly other information) to and from a
-representation suitable for storing into a file.  This section describes
-the fundamental functions that perform this @dfn{format conversion},
-namely @code{insert-file-contents} for reading a file into a buffer,
-and @code{write-region} for writing a buffer into a file.
-
-@menu
-* Overview: Format Conversion Overview.     @code{insert-file-contents} and @code{write-region}
-* Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}.
-* Piecemeal: Format Conversion Piecemeal.   Specifying non-paired conversion.
-@end menu
-
-@node Format Conversion Overview
-@subsection Overview
-@noindent
-The function @code{insert-file-contents}:
-
-@itemize
-@item initially, inserts bytes from the file into the buffer;
-@item decodes bytes to characters as appropriate;
-@item processes formats as defined by entries in @code{format-alist}; and
-@item calls functions in @code{after-insert-file-functions}.
-@end itemize
-
-@noindent
-The function @code{write-region}:
-
-@itemize
-@item initially, calls functions in @code{write-region-annotate-functions};
-@item processes formats as defined by entries in @code{format-alist};
-@item encodes characters to bytes as appropriate; and
-@item modifies the file with the bytes.
-@end itemize
-
-  This shows the symmetry of the lowest-level operations; reading and
-writing handle things in opposite order.  The rest of this section
-describes the two facilities surrounding the three variables named
-above, as well as some related functions.  @ref{Coding Systems}, for
-details on character encoding and decoding.
-
-@node Format Conversion Round-Trip
-@subsection Round-Trip Specification
-
-  The most general of the two facilities is controlled by the variable
-@code{format-alist}, a list of @dfn{file format} specifications, which
-describe textual representations used in files for the data in an Emacs
-buffer.  The descriptions for reading and writing are paired, which is
-why we call this ``round-trip'' specification
-(@pxref{Format Conversion Piecemeal}, for non-paired specification).
-
-@defvar format-alist
-This list contains one format definition for each defined file format.
-Each format definition is a list of this form:
-
-@example
-(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
-@end example
-@end defvar
-
-@cindex format definition
-@noindent
-Here is what the elements in a format definition mean:
-
-@table @var
-@item name
-The name of this format.
-
-@item doc-string
-A documentation string for the format.
-
-@item regexp
-A regular expression which is used to recognize files represented in
-this format.
-
-@item from-fn
-A shell command or function to decode data in this format (to convert
-file data into the usual Emacs data representation).
-
-A shell command is represented as a string; Emacs runs the command as a
-filter to perform the conversion.
-
-If @var{from-fn} is a function, it is called with two arguments, @var{begin}
-and @var{end}, which specify the part of the buffer it should convert.
-It should convert the text by editing it in place.  Since this can
-change the length of the text, @var{from-fn} should return the modified
-end position.
-
-One responsibility of @var{from-fn} is to make sure that the beginning
-of the file no longer matches @var{regexp}.  Otherwise it is likely to
-get called again.
-
-@item to-fn
-A shell command or function to encode data in this format---that is, to
-convert the usual Emacs data representation into this format.
-
-If @var{to-fn} is a string, it is a shell command; Emacs runs the
-command as a filter to perform the conversion.
-
-If @var{to-fn} is a function, it is called with three arguments:
-@var{begin} and @var{end}, which specify the part of the buffer it
-should convert, and @var{buffer}, which specifies which buffer.  There
-are two ways it can do the conversion:
-
-@itemize @bullet
-@item
-By editing the buffer in place.  In this case, @var{to-fn} should
-return the end-position of the range of text, as modified.
-
-@item
-By returning a list of annotations.  This is a list of elements of the
-form @code{(@var{position} . @var{string})}, where @var{position} is an
-integer specifying the relative position in the text to be written, and
-@var{string} is the annotation to add there.  The list must be sorted in
-order of position when @var{to-fn} returns it.
-
-When @code{write-region} actually writes the text from the buffer to the
-file, it intermixes the specified annotations at the corresponding
-positions.  All this takes place without modifying the buffer.
-@end itemize
-
-@item modify
-A flag, @code{t} if the encoding function modifies the buffer, and
-@code{nil} if it works by returning a list of annotations.
-
-@item mode-fn
-A minor-mode function to call after visiting a file converted from this
-format.  The function is called with one argument, the integer 1;
-that tells a minor-mode function to enable the mode.
-@end table
-
-The function @code{insert-file-contents} automatically recognizes file
-formats when it reads the specified file.  It checks the text of the
-beginning of the file against the regular expressions of the format
-definitions, and if it finds a match, it calls the decoding function for
-that format.  Then it checks all the known formats over again.
-It keeps checking them until none of them is applicable.
-
-Visiting a file, with @code{find-file-noselect} or the commands that use
-it, performs conversion likewise (because it calls
-@code{insert-file-contents}); it also calls the mode function for each
-format that it decodes.  It stores a list of the format names in the
-buffer-local variable @code{buffer-file-format}.
-
-@defvar buffer-file-format
-This variable states the format of the visited file.  More precisely,
-this is a list of the file format names that were decoded in the course
-of visiting the current buffer's file.  It is always buffer-local in all
-buffers.
-@end defvar
-
-When @code{write-region} writes data into a file, it first calls the
-encoding functions for the formats listed in @code{buffer-file-format},
-in the order of appearance in the list.
-
-@deffn Command format-write-file file format &optional confirm
-This command writes the current buffer contents into the file
-@var{file} in format @var{format}, and makes that format the default
-for future saves of the buffer.  The argument @var{format} is a list
-of format names.  Except for the @var{format} argument, this command
-is similar to @code{write-file}.  In particular, @var{confirm} has the
-same meaning and interactive treatment as the corresponding argument
-to @code{write-file}.  @xref{Definition of write-file}.
-@end deffn
-
-@deffn Command format-find-file file format
-This command finds the file @var{file}, converting it according to
-format @var{format}.  It also makes @var{format} the default if the
-buffer is saved later.
-
-The argument @var{format} is a list of format names.  If @var{format} is
-@code{nil}, no conversion takes place.  Interactively, typing just
-@key{RET} for @var{format} specifies @code{nil}.
-@end deffn
-
-@deffn Command format-insert-file file format &optional beg end
-This command inserts the contents of file @var{file}, converting it
-according to format @var{format}.  If @var{beg} and @var{end} are
-non-@code{nil}, they specify which part of the file to read, as in
-@code{insert-file-contents} (@pxref{Reading from Files}).
-
-The return value is like what @code{insert-file-contents} returns: a
-list of the absolute file name and the length of the data inserted
-(after conversion).
-
-The argument @var{format} is a list of format names.  If @var{format} is
-@code{nil}, no conversion takes place.  Interactively, typing just
-@key{RET} for @var{format} specifies @code{nil}.
-@end deffn
-
-@defvar buffer-auto-save-file-format
-This variable specifies the format to use for auto-saving.  Its value is
-a list of format names, just like the value of
-@code{buffer-file-format}; however, it is used instead of
-@code{buffer-file-format} for writing auto-save files.  If the value
-is @code{t}, the default, auto-saving uses the same format as a
-regular save in the same buffer.  This variable is always buffer-local
-in all buffers.
-@end defvar
-
-@node Format Conversion Piecemeal
-@subsection Piecemeal Specification
-
-  In contrast to the round-trip specification described in the previous
-subsection (@pxref{Format Conversion Round-Trip}), you can use the variables
-@code{after-insert-file-functions} and @code{write-region-annotate-functions}
-to separately control the respective reading and writing conversions.
-
-  Conversion starts with one representation and produces another
-representation.  When there is only one conversion to do, there is no
-conflict about what to start with.  However, when there are multiple
-conversions involved, conflict may arise when two conversions need to
-start with the same data.
-
-  This situation is best understood in the context of converting text
-properties during @code{write-region}.  For example, the character at
-position 42 in a buffer is @samp{X} with a text property @code{foo}.  If
-the conversion for @code{foo} is done by inserting into the buffer, say,
-@samp{FOO:}, then that changes the character at position 42 from
-@samp{X} to @samp{F}.  The next conversion will start with the wrong
-data straight away.
-
-  To avoid conflict, cooperative conversions do not modify the buffer,
-but instead specify @dfn{annotations}, a list of elements of the form
-@code{(@var{position} . @var{string})}, sorted in order of increasing
-@var{position}.
-
-  If there is more than one conversion, @code{write-region} merges their
-annotations destructively into one sorted list.  Later, when the text
-from the buffer is actually written to the file, it intermixes the
-specified annotations at the corresponding positions.  All this takes
-place without modifying the buffer.
-
-@c ??? What about ``overriding'' conversions like those allowed
-@c ??? for `write-region-annotate-functions', below?  --ttn
-
-  In contrast, when reading, the annotations intermixed with the text
-are handled immediately.  @code{insert-file-contents} sets point to the
-beginning of some text to be converted, then calls the conversion
-functions with the length of that text.  These functions should always
-return with point at the beginning of the inserted text.  This approach
-makes sense for reading because annotations removed by the first
-converter can't be mistakenly processed by a later converter.
-
-  Each conversion function should scan for the annotations it
-recognizes, remove the annotation, modify the buffer text (to set a text
-property, for example), and return the updated length of the text, as it
-stands after those changes.  The value returned by one function becomes
-the argument to the next function.
-
-@defvar write-region-annotate-functions
-A list of functions for @code{write-region} to call.  Each function in
-the list is called with two arguments: the start and end of the region
-to be written.  These functions should not alter the contents of the
-buffer.  Instead, they should return annotations.
-
-@c ??? Following adapted from comment in `build_annotations' (fileio.c).
-@c ??? Perhaps this is intended for internal use only?
-@c ??? Someone who understands this, please reword it. --ttn
-As a special case, if a function returns with a different buffer
-current, Emacs takes it to mean the current buffer contains altered text
-to be output, and discards all previous annotations because they should
-have been dealt with by this function.
-@end defvar
-
-@defvar after-insert-file-functions
-Each function in this list is called by @code{insert-file-contents}
-with one argument, the number of characters inserted, and with point
-at the beginning of the inserted text.  Each function should leave
-point unchanged, and return the new character count describing the
-inserted text as modified by the function.
-@c ??? The docstring mentions a handler from `file-name-handler-alist'
-@c     "intercepting" `insert-file-contents'.  Hmmm.  --ttn
-@end defvar
-
-  We invite users to write Lisp programs to store and retrieve text
-properties in files, using these hooks, and thus to experiment with
-various data formats and find good ones.  Eventually we hope users
-will produce good, general extensions we can install in Emacs.
-
-  We suggest not trying to handle arbitrary Lisp objects as text property
-names or values---because a program that general is probably difficult
-to write, and slow.  Instead, choose a set of possible data types that
-are reasonably flexible, and not too hard to encode.
-
-@ignore
-   arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
-@end ignore