GNU Info

(kpathsea.info)Searching overview

---

Next: Path sources Up: Path searching

---

Enter node , (file) or (file)node

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 (Note: 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 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 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.

  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 (Note: File lookup,
and Note: Glyph lookup).