procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

(Locating Files): New subsection. Describe locate-file and executable-find.

Browse source
This commit is contained in:
Eli Zaretskii 2005-05-21 13:30:24 +00:00
parent a2c9aee6a0
commit f42ea19f63
1 changed files with 67 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

71
lispref/files.texi
View file

@ -735,16 +735,18 @@ for its usual definition is in @file{userlock.el}.
@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
@ -1254,6 +1256,67 @@ is on file system number -32252.
@end table
@end defun
@node Locating Files
@subsection How to Locate Files in Standard Places
@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
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.
@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}.
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
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}).
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