git.oblomov.eu Git - mplib/blob - src/texk/kpathsea/pathsearch.h

   1 /* pathsearch.h: mostly-generic path searching.
   2
   3    Copyright 1993, 1994, 1996, 1997, 2007, 2008 Karl Berry.
   4    Copyright 1999-2005 Olaf Weber.
   5
   6    This library is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Lesser General Public
   8    License as published by the Free Software Foundation; either
   9    version 2.1 of the License, or (at your option) any later version.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public License
  17    along with this library; if not, see <http://www.gnu.org/licenses/>.  */
  18
  19 #ifndef KPATHSEA_PATHSEARCH_H
  20 #define KPATHSEA_PATHSEARCH_H
  21
  22 #include <kpathsea/c-proto.h>
  23 #include <kpathsea/str-llist.h>
  24 #include <kpathsea/types.h>
  25
  26 /* If PATH is non-null, return its first element (as defined by
  27    IS_ENV_SEP).  If it's NULL, return the next element in the previous
  28    path, a la strtok.  Leading, trailing, or doubled colons result in
  29    the empty string.  When at the end of PATH, return NULL.  In any
  30    case, return a pointer to an area that may be overwritten on
  31    subsequent calls.  */
  32 extern KPSEDLL string kpse_path_element P1H(const_string path);
  33
  34 /* Like `kpse_path_element', but for filename components (using
  35    IS_DIR_SEP).  Uses same area as `kpse_path_element'.  */
  36 extern string kpse_filename_component P1H(const_string path);
  37
  38 /*
  39   This function may rewrite its argument to avoid bugs when calling
  40   stat() or equivalent under Win32.  Also, it returns the index after
  41   which the program should start to look for expandable constructs. */
  42 extern unsigned kpse_normalize_path P1H(string elt);
  43
  44 /* Given a path element ELT, return a pointer to a NULL-terminated list
  45    of the corresponding (existing) directory or directories, with
  46    trailing slashes, or NULL.  If ELT is the empty string, check the
  47    current working directory.
  48
  49    It's up to the caller to expand ELT.  This is because this routine is
  50    most likely only useful to be called from `kpse_path_search', which
  51    has already assumed expansion has been done.  */
  52 extern KPSEDLL str_llist_type *kpse_element_dirs P1H(string elt);
  53
  54
  55 /* Call `kpse_expand' on NAME.  If the result is an absolute or
  56    explicitly relative filename, check whether it is a readable
  57    (regular) file.
  58
  59    Otherwise, look in each of the directories specified in PATH (also do
  60    tilde and variable expansion on elements in PATH), using a prebuilt
  61    db (see db.h) if it's relevant for a given path element.
  62
  63    If the prebuilt db doesn't exist, or if MUST_EXIST is true and NAME
  64    isn't found in the prebuilt db, look on the filesystem.  (I.e., if
  65    MUST_EXIST is false, and NAME isn't found in the db, do *not* look on
  66    the filesystem.)
  67
  68    The caller must expand PATH. This is because it makes more sense to
  69    do this once, in advance, instead of for every search.
  70
  71    In any case, return a matching filename if found, otherwise NULL.
  72    If more than one file matches, which one gets returned is
  73    unspecified.  */
  74 extern KPSEDLL string kpse_path_search
  75   P3H(const_string path, const_string name, boolean must_exist);
  76
  77 /* Like `kpse_path_search', except look for a list of NAMES.  */
  78 extern KPSEDLL string kpse_path_search_list
  79   P3H(const_string path, const_string* names, boolean must_exist);
  80
  81 /* Like `kpse_path_search' with MUST_EXIST true, but always return all
  82    matches in a NULL-terminated list.  */
  83 extern KPSEDLL string *kpse_all_path_search
  84   P2H(const_string path, const_string name);
  85
  86 /* Search for any of the NAMES in PATH, and allow specifying both
  87    MUST_EXIST and ALL.  */
  88 extern KPSEDLL string *kpse_path_search_list_generic
  89   P4H(const_string path, const_string* names, boolean must_exist, boolean all);
  90
  91 /* Search for any of NAMES, with MUST_EXIST and ALL true.  */
  92 extern KPSEDLL string *kpse_all_path_search_list
  93   P2H(const_string path, const_string* names);
  94
  95 /* The naming of all these functions is rather scattered and
  96    inconsistent, but they grew over time, and we don't want to change
  97    the meaning of existing names.  */
  98 #endif /* not KPATHSEA_PATHSEARCH_H */