Info Catalog elisp: Extended Attributes elisp: Information about Files

elisp: Locating Files

 
 24.6.6 Locating Files in Standard Places
 ----------------------------------------
 
 This section explains how to search for a file in a list of directories
 (a “path”), or for an executable file in the standard list of executable
 file directories.
 
    To search for a user-specific configuration file, Standard File
 Names, for the ‘locate-user-emacs-file’ function.
 
  -- Function: locate-file filename path &optional suffixes predicate
      This function searches for a file whose name is FILENAME in a list
      of directories given by PATH, trying the suffixes in SUFFIXES.  If
      it finds such a file, it returns the file’s absolute file name
      (Relative File Names); otherwise it returns ‘nil’.
 
      The optional argument SUFFIXES gives the list of file-name suffixes
      to append to FILENAME when searching.  ‘locate-file’ tries each
      possible directory with each of these suffixes.  If SUFFIXES is
      ‘nil’, or ‘("")’, then there are no suffixes, and FILENAME is used
      only as-is.  Typical values of SUFFIXES are ‘exec-suffixes’ (
      Subprocess Creation), ‘load-suffixes’, ‘load-file-rep-suffixes’
      and the return value of the function ‘get-load-suffixes’ (
      Load Suffixes).
 
      Typical values for PATH are ‘exec-path’ (Subprocess
      Creation) when looking for executable programs, or ‘load-path’
      (Library Search) when looking for Lisp files.  If FILENAME
      is absolute, PATH has no effect, but the suffixes in SUFFIXES are
      still tried.
 
      The optional argument PREDICATE, if non-‘nil’, specifies a
      predicate function for testing whether a candidate file is
      suitable.  The predicate is passed the candidate file name as its
      single argument.  If PREDICATE is ‘nil’ or omitted, ‘locate-file’
      uses ‘file-readable-p’ as the predicate.  Kinds of Files,
      for other useful predicates, e.g., ‘file-executable-p’ and
      ‘file-directory-p’.
 
      For compatibility, PREDICATE can also be one of the symbols
      ‘executable’, ‘readable’, ‘writable’, ‘exists’, or a list of one or
      more of these symbols.
 
  -- Function: executable-find program
      This function searches for the executable file of the named PROGRAM
      and returns the absolute file name of the executable, including its
      file-name extensions, if any.  It returns ‘nil’ if the file is not
      found.  The functions searches in all the directories in
      ‘exec-path’, and tries all the file-name extensions in
      ‘exec-suffixes’ (Subprocess Creation).
 

Info Catalog elisp: Extended Attributes elisp: Information about Files