Back to index

tetex-bin  3.0
pathsearch.h
Go to the documentation of this file.
00001 /* pathsearch.h: mostly-generic path searching.
00002 
00003 Copyright (C) 1993, 94, 96, 97 Karl Berry.
00004 Copyright (C) 2000 Olaf Weber.
00005 
00006 This library is free software; you can redistribute it and/or
00007 modify it under the terms of the GNU Library General Public
00008 License as published by the Free Software Foundation; either
00009 version 2 of the License, or (at your option) any later version.
00010 
00011 This library is distributed in the hope that it will be useful,
00012 but WITHOUT ANY WARRANTY; without even the implied warranty of
00013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00014 Library General Public License for more details.
00015 
00016 You should have received a copy of the GNU Library General Public
00017 License along with this library; if not, write to the Free Software
00018 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
00019 
00020 #ifndef KPATHSEA_PATHSEARCH_H
00021 #define KPATHSEA_PATHSEARCH_H
00022 
00023 #include <kpathsea/c-proto.h>
00024 #include <kpathsea/str-llist.h>
00025 #include <kpathsea/types.h>
00026 
00027 /* If PATH is non-null, return its first element (as defined by
00028    IS_ENV_SEP).  If it's NULL, return the next element in the previous
00029    path, a la strtok.  Leading, trailing, or doubled colons result in
00030    the empty string.  When at the end of PATH, return NULL.  In any
00031    case, return a pointer to an area that may be overwritten on
00032    subsequent calls.  */
00033 extern KPSEDLL string kpse_path_element P1H(const_string path);
00034 
00035 /* Like `kpse_path_element', but for filename components (using
00036    IS_DIR_SEP).  Uses same area as `kpse_path_element'.  */
00037 extern string kpse_filename_component P1H(const_string path);
00038 
00039 /*
00040   This function may rewrite its argument to avoid bugs when calling
00041   stat() or equivalent under Win32.  Also, it returns the index after
00042   which the program should start to look for expandable constructs. */
00043 extern unsigned kpse_normalize_path P1H(string elt);
00044 
00045 /* Given a path element ELT, return a pointer to a NULL-terminated list
00046    of the corresponding (existing) directory or directories, with
00047    trailing slashes, or NULL.  If ELT is the empty string, check the
00048    current working directory.
00049    
00050    It's up to the caller to expand ELT.  This is because this routine is
00051    most likely only useful to be called from `kpse_path_search', which
00052    has already assumed expansion has been done.  */
00053 extern KPSEDLL str_llist_type *kpse_element_dirs P1H(string elt);
00054 
00055 
00056 /* Call `kpse_expand' on NAME.  If the result is an absolute or
00057    explicitly relative filename, check whether it is a readable
00058    (regular) file.
00059    
00060    Otherwise, look in each of the directories specified in PATH (also do
00061    tilde and variable expansion on elements in PATH), using a prebuilt
00062    db (see db.h) if it's relevant for a given path element.
00063    
00064    If the prebuilt db doesn't exist, or if MUST_EXIST is true and NAME
00065    isn't found in the prebuilt db, look on the filesystem.  (I.e., if
00066    MUST_EXIST is false, and NAME isn't found in the db, do *not* look on
00067    the filesystem.)
00068    
00069    The caller must expand PATH. This is because it makes more sense to
00070    do this once, in advance, instead of for every search using it.
00071    
00072    In any case, return the complete filename if found, otherwise NULL.  */
00073 extern KPSEDLL string kpse_path_search P3H(const_string path,
00074                                            const_string name,
00075                                            boolean must_exist);
00076 
00077 /* Like kpse_path_search, except we're given a list of names. */
00078 extern KPSEDLL string kpse_path_search_list P3H(const_string path,
00079                                                 const_string* names,
00080                                                 boolean must_exist);
00081 
00082 /* Like `kpse_path_search' with MUST_EXIST true, but return a list of
00083    all the filenames (or NULL if none), instead of taking the first.  */
00084 extern KPSEDLL string *kpse_all_path_search P2H(const_string path,
00085                                                 const_string name);
00086 
00087 /* Like `kpse_path_search_list' with MUST_EXIST true, but return a list of
00088    all the filenames (or NULL if none), instead of taking the first.  */
00089 extern KPSEDLL string *kpse_all_path_search_list P2H(const_string path,
00090                                                      const_string* names);
00091 
00092 #endif /* not KPATHSEA_PATHSEARCH_H */
00093