www.delorie.com/gnu/docs/octave/kpathsea_36.html   search  
Buy GNU books!

Kpathsea: A library for path searching

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.6.3 Debugging

Kpathsea provides a number of runtime debugging options, detailed below by their names and corresponding numeric values. When the files you expect aren't being found, the thing to do is enable these options and examine the output.

You can set these with some runtime argument (e.g., `-d') to the program; in that case, you should use the numeric values described in the program's documentation (which, for Dvipsk and Xdvik, are different than those below). It's best to give the `-d' (or whatever) option first, for maximal output. Dvipsk and Xdvik have additional program-specific debugging options as well.

You can also set the environment variable KPATHSEA_DEBUG; in this case, you should use the numbers below. If you run the program under a debugger and set the variable kpathsea_debug, also use the numbers below.

In any case, by far the simplest value to use is `-1', which will turn on all debugging output. This is usually better than guessing which particular values will yield the output you need.

Debugging output always goes to standard error, so you can redirect it easily. For example, in Bourne-compatible shells:
dvips -d -1 ... 2>/tmp/debug

It is sometimes helpful to run the standalone Kpsewhich utility (see section 3.5 kpsewhich: Standalone path searching), instead of the original program.

In any case, you can not use the names below; you must always use somebody's numbers. (Sorry.) To set more than one option, just sum the corresponding numbers.

Report `stat'(2) calls. This is useful for verifying that your directory structure is not forcing Kpathsea to do many additional file tests (see section Slow path searching, and see section 3.3.6 Subdirectory expansion). If you are using an up-to-date `ls-R' database (see section 3.4 Filename database (ls-R)), this should produce no output unless a nonexistent file that must exist is searched for.

Report lookups in all hash tables: `ls-R' and `aliases' (see section 3.4 Filename database (ls-R)); font aliases (see section 4.3.2 Fontmap); and config file values (see section 3.2.1 Config files). Useful when expected values are not being found, e.g.., file searches are looking at the disk instead of using `ls-R'.

Report file openings and closings. Especially useful when your system's file table is full, for seeing which files have been opened but never closed. In case you want to set breakpoints in a debugger: this works by redefining `fopen' (`fclose') to be `kpse_fopen_trace' (`kpse_fclose_trace').

Report general path information for each file type Kpathsea is asked to search. This is useful when you are trying to track down how a particular path got defined--from `texmf.cnf', `config.ps', an environment variable, the compile-time default, etc. This is the contents of the kpse_format_info_type structure defined in `tex-file.h'.

Report the directory list corresponding to each path element Kpathsea searches. This is only relevant when Kpathsea searches the disk, since `ls-R' searches don't look through directory lists in this way.

Report on each file search: the name of the file searched for, the path searched in, whether or not the file must exist (when drivers search for `cmr10.vf', it need not exist), and whether or not we are collecting all occurrences of the file in the path (as with, e.g., `texmf.cnf' and `texfonts.map'), or just the first (as with most lookups). This can help you correlate what Kpathsea is doing with what is in your input file.

Report the value of each variable Kpathsea looks up. This is useful for verifying that variables do indeed obtain their correct values.

Activates debugging printout specific to gsftopk program.

If you use the optional mktex programs instead of the traditional shell scripts, this will report the name of the site file (`mktex.cnf' by default) which is read, directories created by mktexdir, the full path of the `ls-R' database built by mktexlsr, font map searches, MT_FEATURES in effect, parameters from mktexnam, filenames added by mktexupd, and some subsidiary commands run by the programs.

When the optional mktex programs are used, this will print additional debugging info from functions internal to these programs.

Debugging output from Kpathsea is always written to standard error, and begins with the string `kdebug:'. (Except for hash table buckets, which just start with the number, but you can only get that output running under a debugger. See comments at the hash_summary_only variable in `kpathsea/db.c'.)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003