kpathsea: Programming overview
7.1 Programming overview
========================
Aside from this manual, your best source of information is the source to
the programs that use Kpathsea (⇒Introduction). First, Kpsewhich
is a small utility program whose sole purpose is to exercise the main
path-searching functionality. Of the drivers, Dviljk is probably the
simplest full application program. Xdvik adds VF support and the
complication of X resources. Dvipsk adds the complication of its own
config files. Web2c is source code I also maintain, so it uses Kpathsea
rather straightforwardly, but is of course complicated by the Web to C
translation.
When looking at these program sources, you should know that previous
versions of the library had a different programming interface; the
current interface supports re-entrancy. Historically, the library
function names were prefixed with 'kpse_' instead of 'kpathsea_', and
they did not need an instance variable as first argument. This change
was made in 2009. The old functions will never disappear, and can
reliably continue to be used when they suffice, as they do for the
programs above. The main application using the re-entrant API is the
MetaPost library used by MetaPost and LuaTeX.
Beyond these examples, the '.h' files in the Kpathsea source describe
the interfaces and functionality (and of course the '.c' files define
the actual routines, which are the ultimate documentation).
'pathsearch.h' declares the basic searching routine. 'tex-file.h' and
'tex-glyph.h' define the interfaces for looking up particular kinds of
files. In view of the way the headers depend on each other, it is
recommended to use '#include <kpathsea/kpathsea.h>', which includes
every Kpathsea header.
If you want to include only specific headers, you should still
consider including 'kpathsea/config.h' before including any other
Kpathsea header, as it provides symbols used in the other headers. Note
that 'kpathsea/config.h' includes 'kpathsea/c-auto.h', which is
generated by Autoconf.
The library provides no way for an external program to register new
file types: 'tex-file.[ch]' must be modified to do this. For example,
Kpathsea has support for looking up Dvips config files, even though no
program other than Dvips will likely ever want to do so. I felt this
was acceptable, since along with new file types should also come new
defaults in 'texmf.cnf' (and its descendant 'paths.h'), since it's
simplest for users if they can modify one configuration file for all
kinds of paths.
Kpathsea does not parse any formats itself; it barely opens any
files. Its primary purpose is to return filenames. The GNU font
utilities does contain libraries to read TFM, GF, and PK files, as do
the programs above, of course.
Info Catalog
kpathsea: Programming
kpathsea: Calling sequence