www.delorie.com/gnu/docs/octave/kpathsea_77.html

search

	Buy GNU books!

Kpathsea: A library for path searching

5.2 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 (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.)

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 (see section 3.2.1 Config files).

3. Set debugging options. See section 2.6.3 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/.