@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, 2002, 2003,
+@c 2004, 2005, 2006 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
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
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
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
files that the user does not need to know about.
@end deffn
-@defmac with-temp-file file body...
+@defmac with-temp-file file body@dots{}
@anchor{Definition of with-temp-file}
The @code{with-temp-file} macro evaluates the @var{body} forms with a
temporary buffer as the current buffer; then, at the end, it writes the
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
@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.
+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
@end table
@end defun
+@node Locating Files
+@subsection How to Locate Files in Standard Places
+@cindex locate files
+@cindex find files
+
+ This section explains how to search for a file in a list of
+directories. 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
+
+@cindex find executable program
+@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
same effect as renaming, aside from momentary intermediate states.
@end deffn
-@deffn Command copy-file oldname newname &optional ok-if-exists time mustbenew
+@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}.
-
-The argument @var{mustbenew} controls whether an existing file can be
-overwritten. It works like the similarly-named argument of
-@code{write-region} (@pxref{Writing to Files, mustbenew}).
+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
@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
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
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
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. 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
non-@code{nil}.
@end defvar
-@tindex small-temporary-file-directory
@defvar small-temporary-file-directory
This variable specifies the directory name for
creating certain temporary files, which are likely to be small.
@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.
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.
@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{set-file-times},
@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.
+
@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
If @var{filename} is indeed remote, the return value is a string that
identifies the remote system.
-This identifier string may include a host name, a user name, and
-characters designating the method used to access the remote system.
-For example, the remote identifier string for the filename
+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