[Emacs-diffs] Changes to emacs/lispref/files.texi

[Eli Zaretskii]

Index: emacs/lispref/files.texi
diff -c emacs/lispref/files.texi:1.79 emacs/lispref/files.texi:1.80
*** emacs/lispref/files.texi:1.79       Sat Apr 30 20:30:03 2005
--- emacs/lispref/files.texi    Sat May 21 13:30:24 2005
***************
*** 735,750 ****
  @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.
  
  @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.
  @end menu
  
  @node Testing Accessibility
--- 735,752 ----
  @section Information about Files
  
    The functions described in this section all operate on strings that
! 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,1259 ****
--- 1256,1322 ----
  @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 address@hidden, 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