@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}.)
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
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...
+@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
@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. 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,
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
@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
@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 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
+@deffn Command copy-file oldname newname &optional ok-if-exists time mustbenew
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,
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}).
@end deffn
@deffn Command make-symbolic-link filename newname &optional ok-if-exists
@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
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
@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})
@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
@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
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
(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