source/texk/kpathsea/pathsearch.h

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