kpathsea: Searching overview
5.1 Searching overview
======================
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 (⇒Filename database) 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 might very
well 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 not 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
(unless the search explicitly requested all matches). This avoids
possibly-expensive processing of path specifications that are never
needed on a particular run.
On Unix-like systems, if no match is found by any of the above, and
the path element allows checking the filesystem (per the above), a final
check is made for a case-insensitive match. Thus, looking for a name
like './FooBar.TeX' will match a file './foobar.tex', and vice versa.
This is not done on Windows. ⇒Casefolding search.
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 the
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, with a fallback to a
casefolding match if needed and enabled, as described above.
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 any read permission (for
example, a 'lost+found' directory). 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 (⇒File lookup, and
⇒Glyph lookup).
Info Catalog
kpathsea: Path searching
kpathsea: Path sources