@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/files
@node Files, Backups and Auto-Saving, Documentation, Top
Aside from some technical details, the body of the @code{find-file}
function is basically equivalent to:
-@example
+@smallexample
(switch-to-buffer (find-file-noselect filename nil nil wildcards))
-@end example
+@end smallexample
@noindent
(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
@end deffn
@defun find-file-noselect filename &optional nowarn rawfile wildcards
-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.
-
-If @var{wildcards} is non-@code{nil},
-then @code{find-file-noselect} expands wildcard
-characters in @var{filename} and visits all the matching files.
-
-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.
+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
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 (@pxref{Coding Systems}) and format conversion (@pxref{Format
-Conversion}).
+@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
@var{filename}.
@end deffn
-@tindex find-file-wildcards
@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
@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
@end itemize
@end deffn
-@anchor{Definition of save-some-buffers}
@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
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}. (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}.
+@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
value in a certain buffer, that means do offer to save that buffer.
@end deffn
-@anchor{Definition of write-file}
@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>}
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 (@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}).
+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
@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 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. If any of the
-functions in this hook returns non-@code{nil}, @code{write-file-functions}
-is not run.
-
-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.
+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
@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
the list @code{after-insert-file-functions}; see @ref{Saving
Properties}. 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.
+(@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
@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
this case.
If @var{append} is non-@code{nil}, then the specified text is appended
-to the existing file contents (if any). Starting in Emacs 21, if
-@var{append} is an integer, then @code{write-region} seeks to that byte
-offset from the start of the file and writes the data from there.
+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.
-Starting in Emacs 21, 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.
+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
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}
-@defmac with-temp-file file body...
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
@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.
+ 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''.
+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
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.
+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.
+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
@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. 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.
+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
@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
-file which is a directory.
+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,
@end example
@end defun
-@anchor{Definition of file-attributes}
@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
(@pxref{Changing Files}).
@item
-The file's @acronym{UID} as a string or an integer. If a string
-value cannot be looked up, the integer value is returned.
+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.
+The file's @acronym{GID}, likewise.
@item
The time of last access, as a list of two integers.
@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).
@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
-@cindex renaming files
+@c @cindex renaming files Duplicates rename-file
@cindex copying files
@cindex deleting files
@cindex linking files
same effect as renaming, aside from momentary intermediate states.
@end deffn
-@deffn Command copy-file oldname newname &optional ok-if-exists time
+@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,
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.
+@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.
-In an interactive call, a prefix argument specifies a non-@code{nil}
-value for @var{time}.
+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
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.
@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 MSDOS it can also end in a colon. On VMS, it
+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{>}.
@end defun
@defun file-name-extension filename &optional period
-This function returns @var{filename}'s final ``extension'', if any,
+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
Andrew Innes says that this
@c @defvar directory-sep-char
-@c @tindex 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
@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
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 MSDOS and
+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
To convert a directory name to its abbreviation, use this
function:
-@anchor{Definition of abbreviate-file-name}
@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,
be expanded. Expansion also simplifies file names by eliminating
redundancies such as @file{./} and @file{@var{name}/../}.
-In the next two functions, the @var{directory} argument can be either
-a directory name or a directory file name. @xref{Directory Names}.
-
@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; it may start with @samp{~}.)
-Otherwise, the current buffer's value of @code{default-directory} is
-used. For example:
+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
@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.
indirect calls to @code{expand-file-name}. @xref{Truenames}.
@end defun
-@c Emacs 19 feature
-@defun file-relative-name filename &optional directory
-This function does the inverse of expansion---it tries to return a
-relative name that is equivalent to @var{filename} when interpreted
-relative to @var{directory}. If @var{directory} is omitted or
-@code{nil}, it defaults to the current buffer's default directory.
-
-On some operating systems, an absolute file name begins with a device
-name. On such systems, @var{filename} has no relative equivalent based
-on @var{directory} if they start with two different device names. In
-this case, @code{file-relative-name} returns @var{filename} in absolute
-form.
-
-@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
@end example
@end defvar
-@anchor{Definition of substitute-in-file-name}
@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
@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, starting in Emacs 21:
+construct a name for such a file:
@example
(make-temp-file @var{name-of-application})
two different jobs from trying to use the exact same file name.
@defun make-temp-file prefix &optional dir-flag suffix
-@tindex make-temp-file
-This function creates a temporary file and returns its name.
-The name starts with @var{prefix}; it also contains a number that is
-different in each Emacs job. If @var{prefix} is a relative file name,
-it is expanded against @code{temporary-file-directory}.
+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
@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 contains a number that is
-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.
+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
non-@code{nil}.
@end defvar
-@tindex small-temporary-file-directory
@defvar small-temporary-file-directory
-This variable (new in Emacs 21) specifies the directory name for
+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
@cindex completion, file name
This section describes low-level subroutines for completing a file
-name. For other completion functions, see @ref{Completion}.
+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
@end example
@end defun
-@defun file-name-completion filename directory
+@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}.
+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
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.
+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
@var{file} in directory @var{dirname}. It is only available on VMS.
@end defun
-@tindex file-expand-wildcards
@defun file-expand-wildcards pattern &optional full
This function expands the wildcard pattern @var{pattern}, returning
a list of file names that match it.
@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
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
+ 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:
(funcall @var{handler} 'file-exists-p @var{filename})
@end example
-When a function takes two or more arguments that must be file names,
+ 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:
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
+ 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:
+ Here are the operations that a magic file name handler gets to handle:
@ifnottex
@noindent
@code{file-attributes},
@code{file-directory-p},
@code{file-executable-p}, @code{file-exists-p},
-@code{file-local-copy},
+@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{get-file-buffer},
@code{insert-directory},
@code{insert-file-contents},@*
-@code{load}, @code{make-directory},
+@code{load},
+@code{make-auto-save-file-name},
+@code{make-directory},
@code{make-directory-internal},
@code{make-symbolic-link},@*
-@code{rename-file}, @code{set-file-modes},
+@code{rename-file}, @code{set-file-modes}, @code{set-file-times},
@code{set-visited-file-modtime}, @code{shell-command},
@code{substitute-in-file-name},@*
@code{unhandled-file-name-directory},
@code{file-attributes},
@code{file-direct@discretionary{}{}{}ory-p},
@code{file-executable-p}, @code{file-exists-p},
-@code{file-local-copy},
+@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},
@end flushleft
@end iftex
-Handlers for @code{insert-file-contents} typically need to clear the
+ 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
+ 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
+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
(apply operation args)))))
@end smallexample
-When a handler function decides to call the ordinary Emacs primitive for
+ 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
each have handlers.
@kindex safe-magic (@r{property})
-Handlers that don't really do anything special for actual access to the
+ 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
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
@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. The operation is needed
-for comparison with @code{inhibit-file-name-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
@end defun
@defun file-remote-p filename
-This function returns @code{t} if @var{filename} is a remote file---that is,
-a magic file name that handles @code{file-local-copy}.
+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{/ssh:user@@host:/some/file} is @code{/ssh:user@@host:}.
+
+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.
@end defun
@defun unhandled-file-name-directory filename
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 two arguments, @var{begin}
-and @var{end}, which specify the part of the buffer it should convert.
-There are two ways it can do 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
@key{RET} for @var{format} specifies @code{nil}.
@end deffn
-@defvar auto-save-file-format
+@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