A search path is a colon-separated list of path elements, which are directory names with a few extra frills. A search path can come from (a combination of) many sources; see below. To look up a file `foo' along a path `.:/dir', Kpathsea checks each element of the path in turn: first `./foo', then `/dir/foo', returning the first match (or possibly all matches).
The "colon" and "slash" mentioned here aren't necessarily `:' and `/' on non-Unix systems. Kpathsea tries to adapt to other operating systems' conventions.
To check a particular path element e, Kpathsea first sees if a
prebuilt database (see section Filename database (ls-R)) applies to e, i.e.,
if the database is in a directory that is a prefix of e. If so,
the path specification is matched against the contents of the database.
If the database does not exist, or does not apply to this path element, or contains no matches, the filesystem is searched (if this was not forbidden by the specification with `!!' and if the file being searched for must exist). Kpathsea constructs the list of directories that correspond to this path element, and then checks in each for the file being searched for. (To help speed future lookups of files in the same directory, the directory in which a file is found is floated to the top of the directory list.)
The "file must exist" condition comes into play with VF files and input files read by the TeX `\openin' command. These files may not exist (consider `cmr10.vf'), and so it would be wrong to search the disk for them. Therefore, if you fail to update `ls-R' when you install a new VF file, it will never be found.
Each path element is checked in turn: first the database, then the disk. If a match is found, the search stops and the result is returned. This avoids possibly-expensive processing of path specifications that are never needed on a particular run. (Unless the search explicitly requested all matches.)
Although the simplest and most common path element is a directory name, Kpathsea supports additional features in search paths: layered default values, environment variable names, config file values, users' home directories, and recursive subdirectory searching. Thus, we say that Kpathsea expands a path element, meaning transforming all thel magic specifications into the basic directory name or names. This process is described in the sections below. It happens in the same order as the sections.
Exception to all of the above: If the filename being searched for is absolute or explicitly relative, i.e., starts with `/' or `./' or `../', Kpathsea simply checks if that file exists.
Ordinarily, if Kpathsea tries to access a file or directory that cannot
be read, it gives a warning. This is so you will be alerted to
directories or files that accidentally lack read permission (for
example, a `lost+found'). If you prefer not to see these warnings,
include the value `readable' in the TEX_HUSH environment
variable or config file value.
This generic path searching algorithm is implemented in `kpathsea/pathsearch.c'. It is employed by a higher-level algorithm when searching for a file of a particular type (see section File lookup, and section Glyph lookup).
Go to the first, previous, next, last section, table of contents.