GNU Info

(kpathsea.info)Debugging

---

Next: Logging Prev: Mailing lists Up: Reporting bugs

---

Enter node , (file) or (file)node

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
(Note: Invoking kpsewhich), 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.

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

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

`KPSE_DEBUG_FOPEN (4)'
     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').

`KPSE_DEBUG_PATHS (8)'
     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'.

`KPSE_DEBUG_EXPAND (16)'
     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.

`KPSE_DEBUG_SEARCH (32)'
     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.

`KPSE_DEBUG_VARS (64)'
     Report the value of each variable Kpathsea looks up.  This is
     useful for verifying that variables do indeed obtain their correct
     values.

`GSFTOPK_DEBUG (128)'
     Activates debugging printout specific to `gsftopk' program.

`MAKETEX_DEBUG (512)'
     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.

`MAKETEX_FINE_DEBUG (1024)'
     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'.)