--- /dev/null
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/files.info
+@node Files, Backups and Auto-Saving, Documentation, Top
+@chapter Files
+
+ In XEmacs, you can find, create, view, save, and otherwise work with
+files and file directories. This chapter describes most of the
+file-related functions of XEmacs 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 using @code{expand-file-name}, so that
+@file{~} is handled correctly, as are relative file names (including
+@samp{../}). These functions don't recognize environment variable
+substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
+
+@menu
+* Visiting Files:: Reading files into Emacs buffers for editing.
+* Saving Buffers:: Writing changed buffers back into files.
+* Reading from Files:: Reading files into buffers without visiting.
+* 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 File Attributes:: 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.
+* Partial Files:: Treating a section of a buffer as a file.
+* Format Conversion:: Conversion to and from various file formats.
+* Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
+@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 XEmacs 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
+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.
+
+The body of the @code{find-file} function is very simple and looks
+like this:
+
+@example
+(switch-to-buffer (find-file-noselect filename))
+@end example
+
+@noindent
+(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
+
+When @code{find-file} is called interactively, it prompts for
+@var{filename} in the minibuffer.
+@end deffn
+
+@defun find-file-noselect filename &optional nowarn
+This function is the guts of all the file-visiting functions. It finds
+or creates a buffer visiting the file @var{filename}, and returns it.
+It uses an existing buffer if there is one, and otherwise creates a new
+buffer and reads the file into it. You may make the buffer current or
+display it in a window if you wish, but this function does not do so.
+
+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, then this function asks
+the user whether to reread the changed file. If the user says
+@samp{yes}, any changes previously made in the buffer are lost.
+
+If @code{find-file-noselect} 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.
+
+@c XEmacs feature
+If @var{nowarn} is non-@code{nil}, various warnings that XEmacs normally
+gives (e.g. if another buffer is already visiting @var{filename} but
+@var{filename} has been removed from disk since that buffer was created)
+are suppressed.
+
+The @code{find-file-noselect} function 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-hooks}.
+
+The @code{find-file-noselect} function returns the buffer that is
+visiting the file @var{filename}.
+
+@example
+@group
+(find-file-noselect "/etc/fstab")
+ @result{} #<buffer fstab>
+@end group
+@end example
+@end defun
+
+@deffn Command find-file-other-window filename
+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
+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 &optional other-window-p
+This command visits @var{filename} in View mode, and displays it in a
+recursive edit, returning to the previous buffer when done. View mode
+is a mode that allows you to skim rapidly through the file but does not
+let you modify it. 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}.
+
+With non-@code{nil} prefix arg @var{other-window-p}, visit @var{filename}
+in another window.
+@end deffn
+
+@defvar find-file-hooks
+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 works just like a normal hook, but we think that renaming
+it would not be advisable.
+@end defvar
+
+@defvar find-file-not-found-hooks
+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 they may not all be called.
+@end defvar
+
+@node Subroutines of Visiting
+@subsection Subroutines of Visiting
+
+ The @code{find-file-noselect} function uses the
+@code{create-file-buffer} and @code{after-find-file} functions as
+subroutines. Sometimes it is useful to call them directly.
+
+@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
+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.
+
+@c XEmacs feature
+If @var{noauto} is non-@code{nil}, then this function does not turn
+on auto-save mode; otherwise, it does.
+
+The last thing @code{after-find-file} does is call all the functions
+in @code{find-file-hooks}.
+@end defun
+
+@node Saving Buffers
+@section Saving Buffers
+
+ When you edit a file in XEmacs, 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.
+@end itemize
+@end deffn
+
+@deffn Command save-some-buffers &optional save-silently-p exiting
+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{exiting} argument, if non-@code{nil}, requests this
+function to offer also to save certain other buffers that are not
+visiting files. These are buffers that have a non-@code{nil} local
+value of @code{buffer-offer-save}. (A user who says yes to saving one
+of these is asked to specify a file name to use.) The
+@code{save-buffers-kill-emacs} function passes a non-@code{nil} value
+for this argument.
+@end deffn
+
+@defvar buffer-offer-save
+When this variable is non-@code{nil} in a buffer, XEmacs offers to save
+the buffer on exit even if the buffer is not visiting a file. The
+variable is automatically local in all buffers. Normally, Mail mode
+(used for editing outgoing mail) sets this to @code{t}.
+@end defvar
+
+@deffn Command write-file filename
+This function writes the current buffer into file @var{filename}, makes
+the buffer visit that file, and marks it not modified. Then it renames
+the buffer based on @var{filename}, appending a string like @samp{<2>}
+if necessary to make a unique buffer name. It does most of this work by
+calling @code{set-visited-file-name} and @code{save-buffer}.
+@end deffn
+
+@defvar write-file-hooks
+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-hooks} 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 to set the mode bits of the file that
+you write. This is what @code{save-buffer} normally does.
+
+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 local-write-file-hooks
+This works just like @code{write-file-hooks}, but it is intended
+to be made local to particular buffers. It's not a good idea to make
+@code{write-file-hooks} local to a buffer---use this variable instead.
+
+The variable is marked as a permanent local, so that changing the major
+mode does not alter a buffer-local value. This is convenient for
+packages that read ``file'' contents in special ways, and set up hooks
+to save the data in a corresponding way.
+@end defvar
+
+@c Emacs 19 feature
+@defvar write-contents-hooks
+This works just like @code{write-file-hooks}, but it is intended for
+hooks that pertain to the contents of the file, as opposed to hooks that
+pertain to where the file came from. Such hooks are usually set up by
+major modes, as buffer-local bindings for this variable. Switching to a
+new major mode always resets this variable.
+@end defvar
+
+@c Emacs 19 feature
+@defvar after-save-hook
+This normal hook runs after a buffer has been saved in its visited file.
+@end defvar
+
+@defvar 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 set this variable non-@code{nil} locally in particular
+buffers.
+@end defvar
+
+@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
+
+@node Reading from Files
+@section 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 start 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. @xref{Format Conversion}. It also calls the functions in
+the list @code{after-insert-file-functions}; see @ref{Saving
+Properties}.
+
+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{start} 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.
+@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
+@section 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. If that
+file exists it is overwritten. 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.
+@end deffn
+
+@deffn Command write-region start end filename &optional append visit
+This function writes the region delimited by @var{start} and @var{end}
+in the current buffer into the file specified by @var{filename}.
+
+@c Emacs 19 feature
+If @var{start} is a string, then @code{write-region} writes or appends
+that string, rather than text from the buffer.
+
+If @var{append} is non-@code{nil}, then the specified text is appended
+to the existing file contents (if any).
+
+If @var{visit} is @code{t}, then XEmacs 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 function @code{write-region} converts the data which it writes to
+the appropriate file formats specified by @code{buffer-file-format}.
+@xref{Format Conversion}. It also calls the functions in the list
+@code{write-region-annotate-functions}; see @ref{Saving Properties}.
+
+Normally, @code{write-region} displays a message @samp{Wrote file
+@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
+
+@node File Locks
+@section File Locks
+@cindex file locks
+
+ When two users edit the same file at the same time, they are likely to
+interfere with each other. XEmacs tries to prevent this situation from
+arising by recording a @dfn{file lock} when a file is being modified.
+XEmacs can then detect the first attempt to modify a buffer visiting a
+file that is locked by another XEmacs process, and ask the user what to do.
+
+ File locks do not work properly when multiple machines can share
+file systems, such as with NFS. Perhaps a better file locking system
+will be implemented in the future. When file locks do not work, it is
+possible for two users to make changes simultaneously, but XEmacs can
+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}.
+
+@c Not optional in FSF Emacs 19
+@defun file-locked-p &optional filename
+ This function returns @code{nil} if the file @var{filename} is not
+locked by this XEmacs process. It returns @code{t} if it is locked by
+this XEmacs, and it returns the name of the user who has locked it if it
+is locked by someone else.
+
+@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.
+@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.
+@end defun
+
+@defun ask-user-about-lock filename other-user
+This function is called when the user tries to modify @var{filename},
+but it is locked by another user named @var{other-user}. The value it
+returns determines what happens 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{filename} @var{other-user}
+@end example
+
+@noindent
+where @var{filename} is the name of the file and @var{other-user} is the
+name of the user who has locked the file.
+@end itemize
+
+ The default definition of this function asks the user to choose what
+to do. If you wish, you can replace the @code{ask-user-about-lock}
+function with your own version that decides in another way. The code
+for its usual definition is in @file{userlock.el}.
+@end defun
+
+@node Information about Files
+@section Information about Files
+
+ The functions described in this section all operate on strings that
+designate file names. 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.
+@end menu
+
+@node Testing Accessibility
+@subsection Testing Accessibility
+@cindex accessibility of a file
+@cindex file accessibility
+
+ These functions test for permission to access a file in specific ways.
+
+@defun file-exists-p filename
+This function returns @code{t} if a file named @var{filename} appears
+to exist. This does not mean you can necessarily read the file, only
+that you can find out its attributes. (On Unix, this is true if the
+file exists and you have execute permission on the containing
+directories, regardless of the protection of the file itself.)
+
+If the file does not exist, or if fascist access control policies
+prevent you from finding the attributes of the file, this function
+returns @code{nil}.
+@end defun
+
+@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. 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 or the file name of a
+directory.
+
+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 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.
+@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{filename2} does not exist,
+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
+@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 file name to which it is linked. This may be the
+name of a text file, a directory, or even another symbolic link, or it
+may be a nonexistent file name.
+
+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
+
+@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, symbolic link, 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 until none remain, then expanding to get rid of @samp{.}
+and @samp{..} as components. Strictly speaking, a file need not have a
+unique truename; the number of distinct truenames a file has is equal to
+the number of hard links to the file. However, truenames are useful
+because they eliminate symbolic links as a cause of name variation.
+
+@defun file-truename filename &optional default
+The function @code{file-truename} returns the true name of the file
+@var{filename}. This is the name that you get by following symbolic
+links until none remain.
+
+@c XEmacs allows relative filenames
+If the filename is relative, @var{default} is the directory to start
+with. If @var{default} is @code{nil} or missing, the current buffer's
+value of @code{default-directory} is used.
+@end defun
+
+ @xref{Buffer File Name}, for related information.
+
+@node File Attributes
+@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 @sc{suid} bit
+is set for both others and group, and that the sticky bit is set.
+
+@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
+
+@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
+This function returns a list of attributes of file @var{filename}. If
+the specified file cannot be opened, it returns @code{nil}.
+
+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 File Attributes}).
+
+@item
+The file's @sc{uid}.
+
+@item
+The file's @sc{gid}.
+
+@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).
+
+@item
+The time of last status change as a list of two integers (as above).
+
+@item
+The size of the file in bytes.
+
+@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 @sc{gid} would change if file were
+deleted and recreated; @code{nil} otherwise.
+
+@item
+The file's inode number.
+
+@item
+The file system number of the file system that the file is in. 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")
+ @result{} (nil
+ 1
+ 2235
+ 75
+ (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 2235
+is owned by the user with @sc{uid} 2235.
+
+@item 75
+is in the group with @sc{gid} 75.
+
+@item (8489 20284)
+was last accessed on Aug 19 00:09. Use @code{format-time-string} to
+! convert this number into a time string. @xref{Time Conversion}.
+
+@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 characters long.
+
+@item "-rw-rw-rw-"
+has a mode of read and write access for the owner, group, and world.
+
+@item nil
+would retain the same @sc{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 Changing File Attributes
+@section Changing File Names and Attributes
+@cindex renaming files
+@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 arguments @var{newname} and
+@var{ok-if-already-exists}, if a file by the name of @var{newname}
+already exists, the actions taken depend on the value of
+@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. This is
+what happens when the function is invoked interactively.
+
+@item
+Replace the old file without confirmation if @var{ok-if-already-exists}
+is any other value.
+@end itemize
+
+@deffn Command add-name-to-file filename newname &optional ok-if-already-exists
+@cindex file with multiple names
+@cindex file hard link
+This function gives the file named @var{filename} the additional name
+@var{newname}. This means that @var{newname} becomes a new ``hard
+link'' to @var{filename}. Both these arguments must be strings.
+
+In the first part of the following example, we list two files,
+@file{foo} and @file{foo3}.
+
+@example
+@group
+% ls -l fo*
+-rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
+-rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
+@end group
+@end example
+
+Then we evaluate the form @code{(add-name-to-file "~/lewis/foo"
+"~/lewis/foo2")}. Again we list the files. This shows two names,
+@file{foo} and @file{foo2}.
+
+@example
+@group
+(add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
+ @result{} nil
+@end group
+
+@group
+% ls -l fo*
+-rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
+-rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
+-rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
+@end group
+@end example
+
+@c !!! Check whether this set of examples is consistent. --rjc 15mar92
+ Finally, we evaluate the following:
+
+@example
+(add-name-to-file "~/lewis/foo" "~/lewis/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 "~/lewis/foo1" "~/lewis/foo3")
+ @result{} nil
+@end group
+
+@group
+% ls -l fo*
+-rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
+-rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
+-rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
+@end group
+@end example
+
+This function is meaningless on non-Unix systems, where multiple names
+for one file are not allowed.
+
+ 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.
+
+In an interactive call, this function prompts for @var{filename} and
+@var{newname} in the minibuffer; also, it requests confirmation if
+@var{newname} already exists.
+@end deffn
+
+@deffn Command copy-file filename newname &optional ok-if-already-exists time
+This command copies the file @var{filename} to @var{newname}. An
+error is signaled if @var{filename} does not exist.
+
+If @var{time} is non-@code{nil}, then this functions gives the new
+file the same last-modified time that the old one has. (This works on
+only some operating systems.)
+
+In an interactive call, this function prompts for @var{filename} and
+@var{newname} in the minibuffer; also, it requests confirmation if
+@var{newname} already exists.
+@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, a file is deletable if
+its directory is writable.)
+
+See also @code{delete-directory} in @ref{Create/Delete Dirs}.
+@end deffn
+
+@deffn Command make-symbolic-link filename newname &optional ok-if-already-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}}.
+
+In an interactive call, this function prompts for @var{filename} and
+@var{newname} in the minibuffer; also, it requests confirmation if
+@var{newname} already exists.
+@end deffn
+
+@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.
+@end defun
+
+@c Emacs 19 feature
+@defun set-default-file-modes mode
+This function sets the default file protection for new files created by
+XEmacs and its subprocesses. Every file created with XEmacs initially has
+this protection. On Unix, the default protection is the bitwise
+complement of the ``umask'' value.
+
+The argument @var{mode} must be an integer. Only the low 9 bits of
+@var{mode} are used.
+
+Saving a modified version of an existing file does not count as creating
+the file; it does not change the file's mode, and does not use the
+default file protection.
+@end defun
+
+@defun default-file-modes
+This function returns the current default protection value.
+@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 @samp{.com},
+@samp{.bat} or @samp{.exe}. This is reflected in the values returned
+by @code{file-modes} and @code{file-attributes}.
+
+@node File Names
+@section File Names
+@cindex file names
+
+ Files are generally referred to by their names, in XEmacs as elsewhere.
+File names in XEmacs are represented as strings. The functions that
+operate on a file all expect a file name argument.
+
+ In addition to operating on files themselves, XEmacs Lisp programs
+often need to operate on the 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, these functions understand MS-DOS file-name syntax as well as
+Unix syntax. This is so that all the standard Lisp libraries can specify
+file names in Unix syntax and work properly on all systems without
+change. Similarly for other operating systems.
+
+@menu
+* File Name Components:: The directory part of a file name, and the rest.
+* Directory Names:: A directory's name as a directory
+ is different from its name as a file.
+* Relative File Names:: Some file names are relative to a current directory.
+* 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.
+* User Name Completion:: Finding the completions for a given user name.
+@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, XEmacs 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 Unix, the directory part is everything up to and including the last
+slash; the nondirectory part is the rest.
+
+ For some purposes, the nondirectory part is further subdivided into
+the name proper and the @dfn{version number}. On Unix, only backup
+files have version numbers in their names.
+
+@defun file-name-directory filename
+ This function returns the directory part of @var{filename} (or
+@code{nil} if @var{filename} does not include a directory part). On
+Unix, the function returns a string ending in a slash.
+
+@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
+@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
+@end example
+@end defun
+
+@defun file-name-sans-versions filename &optional keep-backup-version
+ This function returns @var{filename} without any file version numbers,
+backup version numbers, or trailing tildes.
+
+@c XEmacs feature?
+If @var{keep-backup-version} is non-@code{nil}, we do not remove backup
+version numbers, only true file version numbers.
+
+@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
+@end example
+@end defun
+
+@defun file-name-sans-extension filename
+This function returns @var{filename} minus its ``extension,'' if any.
+The extension, in a file name, is the part that starts with the last
+@samp{.} in the last name component. For example,
+
+@example
+(file-name-sans-extension "foo.lose.c")
+ @result{} "foo.lose"
+(file-name-sans-extension "big.hack/foo")
+ @result{} "big.hack/foo"
+@end example
+@end defun
+
+@node Directory Names
+@subsection Directory Names
+@cindex directory name
+@cindex file name of directory
+
+ A @dfn{directory name} is the name of a directory. A directory is a
+kind of file, and 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 Unix, this is simple: a
+directory name ends in a slash, whereas the directory's name as a file
+lacks that slash.
+
+ The difference between a directory name and its name as a file is
+subtle but crucial. When an XEmacs variable or function argument is
+described as being a directory name, a file name of a directory is not
+acceptable.
+
+ 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{~}, 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. In
+Unix, this means appending a slash to the string.
+
+@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
+Unix, this means removing a final slash from the string.
+
+@example
+@group
+(directory-file-name "~lewis/")
+ @result{} "~lewis"
+@end group
+@end example
+@end defun
+
+@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, XEmacs shows users the
+abbreviation instead.
+
+ If you wish to convert a directory name to its abbreviation, use this
+function:
+
+@defun abbreviate-file-name filename &optional hack-homedir
+This function applies abbreviations from @code{directory-abbrev-alist}
+to its argument, and substitutes @samp{~} for the user's home
+directory.
+
+@c XEmacs feature?
+If @var{hack-homedir} is non-@code{nil}, then this also substitutes
+@samp{~} for the user's home directory.
+
+@end defun
+
+@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 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
+
+@c To convert a directory name to its abbreviation, use this
+@c function:
+@c
+@c @defun abbreviate-file-name dirname
+@c This function applies abbreviations from @code{directory-abbrev-alist}
+@c to its argument, and substitutes @samp{~} for the user's home
+@c directory.
+@c @end defun
+
+@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, an absolute file name starts with a slash or a
+tilde (@samp{~}), and a relative one does not.
+
+@defun file-name-absolute-p filename
+This function returns @code{t} if file @var{filename} is an absolute
+file name, @code{nil} otherwise.
+
+@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
+
+@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 directory to start with if
+@var{filename} is relative. (The value of @var{directory} should itself
+be an absolute directory 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
+
+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
+
+@samp{~/} at the beginning is expanded into the user's home directory.
+A @samp{/} or @samp{~} following a @samp{/}.
+
+Note that @code{expand-file-name} does @emph{not} expand environment
+variables; only @code{substitute-in-file-name} does that.
+@end defun
+
+@c Emacs 19 feature
+@defun file-relative-name filename &optional directory
+This function does the inverse of expansion---it tries to return a
+relative name that is equivalent to @var{filename} when interpreted
+relative to @var{directory}.
+
+@c XEmacs feature?
+If @var{directory} is @code{nil} or omitted, the value of
+@code{default-directory} is used.
+
+@example
+(file-relative-name "/foo/bar" "/foo/")
+ @result{} "bar")
+(file-relative-name "/foo/bar" "/hack/")
+ @result{} "../foo/bar")
+@end example
+@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 local in every buffer.
+
+@code{expand-file-name} uses the default directory when its second
+argument is @code{nil}.
+
+On Unix systems, 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
+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.
+
+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{@}}.
+
+@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
+
+@c If a @samp{~} or a @samp{/} appears following a @samp{/}, after
+@c substitution, everything before the following @samp{/} is discarded:
+
+After substitution, a @samp{/} or @samp{~} following a @samp{/} is taken
+to be the start of an absolute file name that overrides what precedes
+it, so everything before that @samp{/} or @samp{~} is deleted. For
+example:
+
+@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"
+@end group
+@end example
+@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-name (expand-file-name @var{name-of-application} (temp-directory)))
+@end example
+
+@noindent
+Here we use @code{(temp-directory)} to specify a directory for temporary
+files---under Unix, it will normally evaluate to @file{"/tmp/"}. The
+job of @code{make-temp-name} is to prevent two different users or two
+different processes from trying to use the same name.
+
+@defun temp-directory
+This function returns the name of the directory to use for temporary
+files. Under Unix, this will be the value of @code{TMPDIR}, defaulting
+to @file{/tmp}. On Windows, this will be obtained from the @code{TEMP}
+or @code{TMP} environment variables, defaulting to @file{/}.
+
+Note that the @code{temp-directory} function does not exist under FSF
+Emacs.
+@end defun
+
+@defun make-temp-name prefix
+This function generates a temporary file name starting with
+@var{prefix}. The Emacs process number forms part of the result, so
+there is no danger of generating a name being used by another process.
+
+@example
+@group
+(make-temp-name "/tmp/foo")
+ @result{} "/tmp/fooGaAQjC"
+@end group
+@end example
+
+In addition, this function makes an attempt to choose a name that does
+not specify an existing file. To make this work, @var{prefix} should be
+an absolute file name.
+
+To avoid confusion, each Lisp application should preferably use a unique
+@var{prefix} to @code{make-temp-name}.
+@end defun
+
+@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 other completion functions, see @ref{Completion}.
+
+@defun file-name-all-completions partial-filename directory
+This function returns a list of all possible completions for files
+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. The current buffer's default directory is
+prepended to @var{directory}, if @var{directory} is not absolute.
+
+File names which end with any member of @code{completion-ignored-extensions}
+are not considered as possible completions for @var{partial-filename} unless
+there is no other possible completion. @code{completion-ignored-extensions}
+is not applied to the names of directories.
+
+In the following example, suppose that the current default directory,
+@file{~rms/lewis}, 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 partial-filename directory
+This function completes the file name @var{partial-filename} in directory
+@var{directory}. It returns the longest prefix common to all file names
+in directory @var{directory} that start with @var{partial-filename}.
+
+If only one match exists and @var{partial-filename} matches it exactly, the
+function returns @code{t}. The function returns @code{nil} if directory
+@var{directory} contains no name starting with @var{partial-filename}.
+
+File names which end with any member of @code{completion-ignored-extensions}
+are not considered as possible completions for @var{partial-filename} unless
+there is no other possible completion. @code{completion-ignored-extensions}
+is not applied to the names of directories.
+
+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 or when a buffer showing all
+possible completions is displayed.@refill
+
+A typical value might look like this:
+
+@example
+@group
+completion-ignored-extensions
+ @result{} (".o" ".elc" "~" ".dvi")
+@end group
+@end example
+@end defopt
+
+@node User Name Completion
+@subsection User Name Completion
+@cindex user name completion subroutines
+@cindex completion, user name
+
+ This section describes low-level subroutines for completing a user
+name. For other completion functions, see @ref{Completion}.
+
+@defun user-name-all-completions partial-username
+This function returns a list of all possible completions for a user name
+starting with @var{partial-username}. The order of the completions is
+unpredictable and conveys no useful information.
+
+The argument @var{partial-username} must be a partial user name
+containing no tilde character and no slash.
+@end defun
+
+@defun user-name-completion partial-username
+This function completes a user name from @var{partial-username}. It
+returns the longest prefix common to all user names that start with
+@var{partial-username}.
+
+If only one match exists and @var{partial-username} matches it exactly,
+the function returns @code{t}. The function returns @code{nil} if no
+user name starting with @var{partial-username} exists.
+@end defun
+
+@defun user-name-completion-1 partial-username
+This function completes the partial user name @var{partial-username},
+like @code{user-name-completion}, differing only in the return value.
+This function returns the cons of the completion returned by
+@code{user-name-completion}, and a boolean indicating whether that
+completion was unique.
+@end defun
+
+
+@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.
+
+ XEmacs 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 value of switches passed to the @code{ls} command.
+
+@defun directory-files directory &optional full-name match-regexp nosort files-only
+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 just the names relative to
+the specified directory.
+
+If @var{match-regexp} is non-@code{nil}, this function returns only
+those file names that contain that regular expression---the other file
+names are discarded from the list.
+
+@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.
+
+@c XEmacs feature
+If @var{files-only} is the symbol @code{t}, then only the ``files'' in
+the directory will be returned; subdirectories will be excluded. If
+@var{files-only} is not @code{nil} and not @code{t}, then only the
+subdirectories will be returned. Otherwise, if @var{files-only} is
+@code{nil} (the default) then both files and subdirectories will be
+returned.
+
+@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
+
+@ignore @c Not in XEmacs
+@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}.
+@end defun
+@end ignore
+
+@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.
+
+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 @var{file} is a
+directory and switches do not contain @samp{-d}, so that the listing
+should show the full contents of the directory. (The @samp{-d} option
+to @code{ls} says to describe a directory itself rather than its
+contents.)
+
+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.
+@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}.
+@end defvar
+
+@node Create/Delete Dirs
+@section Creating and Deleting Directories
+@c Emacs 19 features
+
+ Most XEmacs 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.
+
+@deffn Command make-directory dirname &optional parents
+This function creates a directory named @var{dirname}. Interactively,
+the default choice of directory to create is the current default
+directory for file names. That is useful when you have visited a file
+in a nonexistent directory.
+
+@c XEmacs feature
+Non-interactively, optional argument @var{parents} says whether to
+create parent directories if they don't exist. (Interactively, this
+always happens.)
+@end deffn
+
+@deffn Command 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} in that case.
+@end deffn
+
+@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}. 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
+XEmacs 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 XEmacs 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;
+the remaining arguments are the arguments that were passed to that
+operation. (The first of these arguments is typically 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
+
+Here are the operations that a magic file name handler gets to handle:
+
+@noindent
+@code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
+@code{delete-file},@*
+@code{diff-latest-backup-file},
+@code{directory-file-name},
+@code{directory-files},
+@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-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-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
+@code{file-truename}, @code{file-writable-p},
+@code{get-file-buffer},
+@code{insert-directory},
+@code{insert-file-contents}, @code{load}, @code{make-directory},
+@code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
+@code{set-visited-file-modtime}, @code{unhandled-file-name-directory},
+@code{verify-visited-file-modtime}, @code{write-region}.
+
+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.
+
+@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 filename &optional operation
+This function returns the handler function for file name @var{filename}, 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. The operation is needed
+for comparison with @code{inhibit-file-name-operation}.
+@end defun
+
+@defun file-local-copy filename
+This function copies file @var{filename} to an ordinary non-magic file,
+if it isn't one already.
+
+If @var{filename} specifies a ``magic'' file name, which programs
+outside Emacs cannot directly read or write, this copies the contents to
+an ordinary file and returns that file's name.
+
+If @var{filename} is an ordinary file name, not magic, then this function
+does nothing and returns @code{nil}.
+@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.
+Otherwise, it asks the handler what to do.
+
+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 Partial Files
+@section Partial Files
+@cindex partial files
+
+@menu
+* Intro to Partial Files::
+* Creating a Partial File::
+* Detached Partial Files::
+@end menu
+
+@node Intro to Partial Files
+@subsection Intro to Partial Files
+
+A @dfn{partial file} is a section of a buffer (called the @dfn{master
+buffer}) that is placed in its own buffer and treated as its own file.
+Changes made to the partial file are not reflected in the master buffer
+until the partial file is ``saved'' using the standard buffer save
+commands. Partial files can be ``reverted'' (from the master buffer)
+just like normal files. When a file part is active on a master buffer,
+that section of the master buffer is marked as read-only. Two file
+parts on the same master buffer are not allowed to overlap. Partial
+file buffers are indicated by the words @samp{File Part} in the
+modeline.
+
+The master buffer knows about all the partial files that are active on
+it, and thus killing or reverting the master buffer will be handled
+properly. When the master buffer is saved, if there are any unsaved
+partial files active on it then the user will be given the opportunity
+to first save these files.
+
+When a partial file buffer is first modified, the master buffer is
+automatically marked as modified so that saving the master buffer will
+work correctly.
+
+@node Creating a Partial File
+@subsection Creating a Partial File
+
+@deffn Command make-file-part &optional start end name buffer
+Make a file part on buffer @var{buffer} out of the region. Call it
+@var{name}. This command creates a new buffer containing the contents
+of the region and marks the buffer as referring to the specified buffer,
+called the @dfn{master buffer}. When the file-part buffer is saved, its
+changes are integrated back into the master buffer. When the master
+buffer is deleted, all file parts are deleted with it.
+
+When called from a function, expects four arguments, @var{start},
+@var{end}, @var{name}, and @var{buffer}, all of which are optional and
+default to the beginning of @var{buffer}, the end of @var{buffer}, a
+name generated from @var{buffer}'s name, and the current buffer,
+respectively.
+@end deffn
+
+@node Detached Partial Files
+@subsection Detached Partial Files
+
+Every partial file has an extent in the master buffer associated with it
+(called the @dfn{master extent}), marking where in the master buffer the
+partial file begins and ends. If the text in master buffer that is
+contained by the extent is deleted, then the extent becomes
+``detached'', meaning that it no longer refers to a specific region of
+the master buffer. This can happen either when the text is deleted
+directly or when the master buffer is reverted. Neither of these should
+happen in normal usage because the master buffer should generally not be
+edited directly.
+
+Before doing any operation that references a partial file's master
+extent, XEmacs checks to make sure that the extent is not detached. If
+this is the case, XEmacs warns the user of this and the master extent is
+deleted out of the master buffer, disconnecting the file part. The file
+part's filename is cleared and thus must be explicitly specified if the
+detached file part is to be saved.
+
+@node Format Conversion
+@section File Format Conversion
+
+@cindex file format conversion
+@cindex encoding file formats
+@cindex decoding file formats
+ The variable @code{format-alist} defines a list of @dfn{file formats},
+which describe textual representations used in files for the data (text,
+text-properties, and possibly other information) in an Emacs buffer.
+Emacs performs format conversion if appropriate when reading and writing
+files.
+
+@defvar format-alist
+This list contains one format definition for each defined file format.
+@end defvar
+
+@cindex format definition
+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
+
+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 function to call to decode data in this format (to convert file data into
+the usual Emacs data representation).
+
+The @var{from-fn} is called with two args, @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 function to call to encode data in this format (to convert
+the usual Emacs data representation into this format).
+
+The @var{to-fn} is called with two args, @var{begin} and @var{end},
+which specify the part of the buffer it should convert. 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
+A mode function to call after visiting a file converted from this
+format.
+@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 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
+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.
+@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 start end
+This command inserts the contents of file @var{file}, converting it
+according to format @var{format}. If @var{start} 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 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}; but it is used instead of
+@code{buffer-file-format} for writing auto-save files. This variable
+is always local in all buffers.
+@end defvar
+
+@node Files and MS-DOS
+@section Files and MS-DOS
+@cindex MS-DOS file types
+@cindex file types on MS-DOS
+@cindex text files and binary files
+@cindex binary files and text files
+
+ Emacs on MS-DOS makes a distinction between text files and binary
+files. This is necessary because ordinary text files on MS-DOS use a
+two character sequence between lines: carriage-return and linefeed
+(@sc{crlf}). Emacs expects just a newline character (a linefeed) between
+lines. When Emacs reads or writes a text file on MS-DOS, it needs to
+convert the line separators. This means it needs to know which files
+are text files and which are binary. It makes this decision when
+visiting a file, and records the decision in the variable
+@code{buffer-file-type} for use when the file is saved.
+
+ @xref{MS-DOS Subprocesses}, for a related feature for subprocesses.
+
+@defvar buffer-file-type
+This variable, automatically local in each buffer, records the file type
+of the buffer's visited file. The value is @code{nil} for text,
+@code{t} for binary.
+@end defvar
+
+@defun find-buffer-file-type filename
+This function determines whether file @var{filename} is a text file
+or a binary file. It returns @code{nil} for text, @code{t} for binary.
+@end defun
+
+@defopt file-name-buffer-file-type-alist
+This variable holds an alist for distinguishing text files from binary
+files. Each element has the form (@var{regexp} . @var{type}), where
+@var{regexp} is matched against the file name, and @var{type} may be is
+@code{nil} for text, @code{t} for binary, or a function to call to
+compute which. If it is a function, then it is called with a single
+argument (the file name) and should return @code{t} or @code{nil}.
+@end defopt
+
+@defopt default-buffer-file-type
+This variable specifies the default file type for files whose names
+don't indicate anything in particular. Its value should be @code{nil}
+for text, or @code{t} for binary.
+@end defopt
+
+@deffn Command find-file-text filename
+Like @code{find-file}, but treat the file as text regardless of its name.
+@end deffn
+
+@deffn Command find-file-binary filename
+Like @code{find-file}, but treat the file as binary regardless of its
+name.
+@end deffn
projects / chise / xemacs-chise.git- / blobdiff