@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 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
@cindex locate files
@cindex find files
- Sometimes, you need to find a file that could reside in one of the
-standard 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
+ 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 several alternative file name extensions, in addition to
-looking in every standard directory where the file could be found.
-Emacs provides a function for such a generalized search for a file.
+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 the file whose name is @var{filename} in
-a list of directories given by @var{path}. If it finds the file, it
-returns its full @dfn{absolute file name} (@pxref{Relative File
-Names}); if the file is not found, the function returns @code{nil}.
+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. If
-@var{suffixes} is @code{nil}, it's equivalent to passing a list with a
-single element that is an empty string @code{""}.
-
-Typical values of @var{path} are @code{exec-path} (@pxref{Subprocess
+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}) and @code{load-suffixes} (@pxref{Library
+Search, 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. Use @code{("/")} to disable the path search (e.g., if
-@var{filename} already includes the leading directories), but still
-try the extensions in @var{suffixes}.
-
-Typical values of @var{suffixes} are @code{exec-suffixes}
-(@pxref{Subprocess Creation, exec-suffixes}) and @code{load-suffixes}
-(@pxref{Library Search, load-suffixes}).
+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
@code{exec-suffixes}.
@end defun
-
@node Changing Files
@section Changing File Names and Attributes
@cindex renaming files
@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},
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
HCoop / bpt / emacs.git / blobdiff