GNU Info

(kpathsea.info)Calling sequence

---

Next: Program-specific files Prev: Programming overview Up: Programming

---

Enter node , (file) or (file)node

Calling sequence
================

  The typical way to use Kpathsea in your program goes something like
this:

  1. Call `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 (Note: 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.)

  2. The `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 (Note: Config files).

  3. Set debugging options. Note: Debugging.  If your program doesn't
     have a debugging option already, you can define one and set
     `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).

  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 `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.)

  6. The routine to actually find a file of type FORMAT is
     `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.

  7. To find PK and/or GF bitmap fonts, the routines are `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.

  8. To actually open a file, not just return a filename, call
     `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/>.