kpathsea: Calling sequence
7.2 Calling sequence
====================
The typical way to use Kpathsea in your program goes something like
this:
1. Call 'kpathsea_new' to create a new library instance. This
variable must be passed as the first argument to all the following
library functions. The rest of this manual will be using 'kpse' as
a placeholder for the name of this variable.
2. Call 'kpathsea_set_program_name' with 'argv[0]' as the second
argument; the third argument is a string or 'NULL'. The third
argument is used by Kpathsea as the program name for the '.PROGRAM'
feature of config files (⇒Config files). If the third
argument is 'NULL', the value of the second argument is used. This
function must be called before any other use of the Kpathsea
library.
'kpathsea_set_program_name' always sets the variables
'kpse->invocation_name' and 'kpse->invocation_short_name'. These
variables are used in the error message macros defined in
'kpathsea/lib.h'. It sets the 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 environment 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. You can use 'kpsewhich --expand-var=\$SELFAUTOLOC',
etc., to see the values.
3. Set debugging options. ⇒Debugging. If your program doesn't
have a debugging option already, you can define one and set
'kpse->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).
4. If your program has its own configuration files that can define
search paths, you should assign those paths to the '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.
5. Call 'kpathsea_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.)
6. The routine to actually find a file of type FORMAT is
'kpathsea_find_file'. You can call 'kpathsea_find_file' after
doing only the first and second 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.
7. To find PK and/or GF bitmap fonts, the routine is
'kpathsea_find_glyph', defined in 'tex-glyph.h'. This returns a
structure in addition to the resultant filename, because fonts can
be found in so many ways. See the documentation in the source.
8. To actually open a file, not just return a filename, call
'kpathsea_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.
9. TeX can write output files, via the '\openout' primitive; this
opens a security hole vulnerable to Trojan horse attack: an
unwitting user could run a TeX program that overwrites, say,
'~/.rhosts'. Analogous security holes exist for many other
programs. To alleviate this, there is a configuration variable
'openout_any', which selects one of three levels of security. When
it is set to 'a' (for "any"), no restrictions are imposed. When it
is set to 'r' (for "restricted"), filenames beginning with '.' are
disallowed (except '.tex' because LaTeX needs it). When it is set
to 'p' (for "paranoid") additional restrictions are imposed: an
absolute filename must refer to a file in (a subdirectory) of
'TEXMFOUTPUT', and any attempt to go up a directory level is
forbidden (that is, paths may not contain a '..' component). The
paranoid setting is the default. (For backwards compatibility, 'y'
and '1' are synonyms of 'a', while 'n' and '0' are synonyms for
'r'.) The function 'kpathsea_out_name_ok', with a filename as
second argument, returns 'true' if that filename is acceptable to
be opend for output or 'false' otherwise.
10. Similarly, the function 'kpathsea_in_name_ok', with a filename as
second argument, returns 'true' if that filename is acceptable to
be opend for input or 'false' otherwise, depending on the value of
the configuration variable 'openin_any' (with 'a' as default).
11. To close the kpathsea library instance you are using, call
'kpathsea_finish'. This function closes any open log files and
frees the memory used by the instance.
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 and
probably Automake for configuring and building your software if you use
Kpathsea; I strongly recommend using Autoconf and Automake regardless.
They are available from <https://gnu.org/software>.
Info Catalog
kpathsea: Programming overview
kpathsea: Programming
kpathsea: Program-specific files