This chapter is for programmers who wish to use Kpathsea. See section 1. Introduction, for the conditions under which you may do so.
Aside from this manual, your best source of information is the source to the programs I've modified to use Kpathsea (see section 1. Introduction). Of those, Dviljk is probably the simplest, and hence a good place to start. 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. Finally, Kpsewhich is a small utility program whose sole purpose is to exercise the main path-searching functionality.
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. You may wish to use
#include <kpathsea/kpathsea.h>, which includes every Kpathsea header.
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.
The typical way to use Kpathsea in your program goes something like this:
kpse_set_program_name with argv[0] as the first
argument; the second argument is a string or NULL. The second
argument is used by Kpathsea as the program name for the
.program feature of config files (see section 3.2.1 Config files).
If the second argument is NULL, the value of the first argument
is used. This function must be called before any other use of the
Kpathsea library.
If necessary, kpse_set_program_name sets the global variables
program_invocation_name and program_invocation_short_name.
These variables are used in the error message macros defined in
`kpathsea/lib.h'. It sets the global variable
kpse_program_name to the program name it uses. It also
initializes debugging options based on the environment variable
KPATHSEA_DEBUG (if that is set). Finally, it sets the variables
SELFAUTOLOC, SELFAUTODIR and SELFAUTOPARENT to the
location, parent and grandparent directory of the executable, removing
`.' and `..' path elements and resolving symbolic links.
These are used in the default configuration file to allow people to
invoke TeX from anywhere, specifically from a mounted CD-ROM. (You can
use `--expand-var=\$SELFAUTOLOC', etc., to see the values finds.)
kpse_set_progname is deprecated. A call to
kpse_set_progname with argv[0] is equivalent to a call of
kpse_set_program_name with first argument argv[0] and
second argument NULL. The function is deprecated because it
cannot ensure that the .program feature of config files
will always work (see section 3.2.1 Config files).
kpathsea_debug to the number that the user supplies (as in Dviljk
and Web2c), or you can just omit this altogether (people can always set
KPATHSEA_DEBUG). If you do have runtime debugging already, you
need to merge Kpathsea's options with yours (as in Dvipsk and Xdvik).
client_path member in
the appropriate element of the kpse_format_info array. (This
array is indexed by file type; see `tex-file.h'.) See
`resident.c' in Dvipsk for an example.
kpse_init_prog (see `proginit.c'). It's useful for the
DVI drivers, at least, but for other programs it may be simpler to
extract the parts of it that actually apply. This does not initialize
any paths, it just looks for (and sets) certain environment variables
and other random information. (A search path is always initialized at
the first call to find a file of that type; this eliminates much useless
work, e.g., initializing the BibTeX search paths in a DVI driver.)
kpse_find_format, defined in `tex-file.h'. These are
macros that expand to a call to `kpse_find_file'. You can call,
say, kpse_find_tfm after doing only the first of the
initialization steps above--Kpathsea automatically reads the
`texmf.cnf' generic config files, looks for environment variables,
and does expansions at the first lookup.
kpse_find_pk,
kpse_find_gf and kpse_find_glyph, defined in
`tex-glyph.h'. These return a structure in addition to the
resultant filename, because fonts can be found in so many ways. See the
documentation in the source.
kpse_open_file. This function takes the name to look up and a
Kpathsea file format as arguments, and returns the usual FILE *.
It always assumes the file must exist, and thus will search the disk if
necessary (unless the search path specified `!!', etc.). In other
words, if you are looking up a VF or some other file that need not
exist, don't use this.
Kpathsea also provides many utility routines. Some are generic: hash
tables, memory allocation, string concatenation and copying, string
lists, reading input lines of arbitrary length, etc. Others are
filename-related: default path, tilde, and variable expansion,
stat calls, etc. (Perhaps someday I'll move the former to a
separate library.)
The `c-*.h' header files can also help your program adapt to many different systems. You will almost certainly want to use Autoconf for configuring your software if you use Kpathsea; I strongly recommend using Autoconf regardless. It is available from ftp://prep.ai.mit.edu/pub/gnu/.
Many programs will need to find some configuration files. Kpathsea contains some support to make it easy to place them in their own directories. The Standard TeX directory structure (see section `Introduction' in A Directory Structure for TeX files), specifies that such files should go into a subdirectory named after the program, like `texmf/ttf2pk'.
Two special formats, `kpse_program_text_format' and
`kpse_program_binary_format' exist, which use
.:$TEXMF/program// as their compiled-in search path. To
override this default, you can use the variable
PROGRAMINPUTS in the environment and/or `texmf.cnf'.
That is to say, the name of the variable is constructed by converting
the name of the program to upper case, and appending INPUTS.
The only difference between these two formats is whether
kpse_open_file will open the files it finds in text or binary
mode.
You can (and probably should) use the same texmf.cnf
configuration file that Kpathsea uses for your program. This helps
installers by keeping all configuration in one place.
To retrieve a value var from config files, the best way is to call
kpse_var_value on the string var. This will look
first for an environment variable var, then a config file value.
The result will be the value found or `NULL'. This function is
declared in `kpathsea/variable.h'. For an example, see the
shell_escape code in `web2c/lib/texmfmp.c'.
The routine to do variable expansion in the context of a search path (as
opposed to simply retrieving a value) is kpse_var_expand, also
declared in `kpathsea/variable.h'. It's generally only necessary
to set the search path structure components as explained in the previous
section, rather than using this yourself.
If for some reason you want to retrieve a value only from a
config file, not automatically looking for a corresponding environment
variable, call kpse_cnf_get (declared in `kpathsea/cnf.h')
with the string var.
No initialization calls are needed.
Go to the first, previous, next, last section, table of contents.