This chapter is for programmers who wish to use Kpathsea. See section 1. Introduction, for the conditions under which you may do so. (If you do this, I'd appreciate a note, just to satisfy my curiousity.)
Aside from this manual, your best source of information is the source to the programs I've modified to use Kpathsea (also listed in the 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.
Beyond these of examples of use, 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.
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 obviously no program other than Dvips will 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 best for users if they can modify one configuration file for all kinds of paths.
Kpathsea does not open any files or parse any formats itself. Its purpose is only to return filenames. The GNU font utilities source does contain libraries to read TFM, GF, and PK files.
The typical way to use Kpathsea in your program goes something like this:
kpse_set_progname
with argv[0]
; This is the only
initialization that is mandatory to take full advantage of
Kpathsea--specifically, for the .program
feature of config
files (see section 4.2.1 Config files).
kpse_set_progname
sets the global variables
program_invocation_name
and program_invocation_short_name
.
It also initializes debugging flags based on the environment variable
KPATHSEA_DEBUG
, if that is set. set.
The GNU C library provides these two global variables itself; in this
case, the call to kpse_set_program
does nothing. But you (as a
software author) most likely do not want to force people installing your
program to have glibc.
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 will read the generic config file
`texmf.cmf', look for environment variables, and do the expansions
at the first lookup.
Kpathsea also provides many utility routines. Some are generic: hash
tables, memory allocation, string concatenation and copying, string
lists, reading input lines of unlimited 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. You can get it by ftp from `prep.ai.mit.edu' in `pub/gnu/autoconf-*.tar.gz', or from any of its mirrors.
You can use the same texmf.cnf
configuration file as Kpathsea for
your program. This will help installers do all configuration in one place.
To retrieve a value var, the best way is to call
kpse_var_expand
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 the empty string. This
function is declared in `kpathsea/variable.h'.
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.