2 @setfilename kpathsea.info
3 @settitle Kpathsea: A library for path searching
6 @set month-year May 2015
9 This file documents the Kpathsea library for path searching.
11 Copyright @copyright{} 1996--2015 Karl Berry & Olaf Weber.
13 Permission is granted to make and distribute verbatim copies of this
14 manual provided the copyright notice and this permission notice are
15 preserved on all copies.
18 Permission is granted to process this file through TeX and print the
19 results, provided the printed document carries a copying permission
20 notice identical to this one except for the removal of this paragraph
21 (this paragraph not being relevant to the printed manual).
24 Permission is granted to copy and distribute modified versions of this
25 manual under the conditions for verbatim copying, provided that the
26 entire resulting derived work is distributed under the terms of a
27 permission notice identical to this one.
29 Permission is granted to copy and distribute translations of this manual
30 into another language, under the above conditions for modified versions,
31 except that this permission notice may be stated in a translation
32 approved by the @TeX{} Users Group.
35 @c Define new indices for commands, filenames, and options.
40 @c Put everything in one index (arbitrarily chosen to be the concept index).
52 * Kpathsea: (kpathsea). File lookup along search paths.
53 * kpsewhich: (kpathsea)Invoking kpsewhich. TeX file searching.
54 * mktexfmt: (kpathsea)mktex scripts. Format (fmt/base/mem) generation.
55 * mktexlsr: (kpathsea)Filename database. Update ls-R.
56 * mktexmf: (kpathsea)mktex scripts. MF source generation.
57 * mktexpk: (kpathsea)mktex scripts. PK bitmap generation.
58 * mktextex: (kpathsea)mktex scripts. TeX source generation.
59 * mktextfm: (kpathsea)mktex scripts. TeX font metric generation.
64 @title Kpathsea library
65 @subtitle for version @value{version}
66 @subtitle @value{month-year}
69 @author Taco Hoekwater
70 @author @url{http://tug.org/kpathsea}
73 @vskip 0pt plus 1filll
85 This manual documents the Kpathsea library for path searching. It
86 corresponds to version @value{version}, released in
90 * Introduction:: Overview and history.
92 * unixtex.ftp:: Obtaining @TeX{} software.
93 * Security:: Who can write what files, etc.
94 * TeX directory structure:: Managing the horde of @TeX{} input files.
96 * Path searching:: How filename lookups work.
97 * TeX support:: Special support for TeX-related file lookups.
99 * Programming:: How to use Kpathsea features in your program.
101 * Reporting bugs:: Where and how to report bugs.
102 * Index:: General index.
108 @chapter Introduction
111 @cindex fundamental purpose of Kpathsea
113 This manual corresponds to version @value{version} of the Kpathsea
114 library, released in @value{month-year}.
116 The library's fundamental purpose is to return a filename from a list of
117 directories specified by the user, similar to what shells do when
118 looking up program names to execute.
120 @cindex programs using the library
121 The following software, all of which is maintained in parallel, uses
125 @item Dviljk (see the @samp{dvilj} man page)
126 @item Dvipsk (@pxref{,,,dvips, Dvips: A DVI driver})
127 @item GNU font utilities (@pxref{,,,fontu, GNU font utilities})
128 @item Web2c (@pxref{,,,web2c, Web2c: A @TeX{} implementation})
129 @item Xdvik (see the @samp{xdvi} man page)
132 @noindent Other software that we do not maintain also uses it.
134 Kpathsea is now maintained as part of the @TeX{} Live distribution
135 (@url{http://tug.org/texlive}). For information on configuration,
136 building, installing, and more, @pxref{,,,tlbuild, Building @TeX{}
139 @cindex interface, not frozen
140 @cindex comments, making
141 @cindex suggestions, making
142 The library is still actively maintained. If you have comments or
143 suggestions, please send along (@pxref{Reporting bugs}).
145 @cindex conditions for use
146 @cindex license for using the library
147 @cindex GNU General Public License
148 The Kpathsea library is distributed under the GNU Library General
149 Public License (LGPL). In short, this means if you write a program
150 using the library, you must (offer to) distribute the source to the
151 library, along with any changes you have made, and allow anyone to
152 modify the library source and distribute their modifications. It does
153 not mean you have to distribute the source to your program, although
154 we hope you will. See accompanying files for the text of the GNU
155 licenses, or @url{http://www.gnu.org/licenses}.
157 @cindex @TeX{} Users Group
158 If you know enough about @TeX{} to be reading this manual, then you (or
159 your institution) should consider joining the @TeX{} Users Group (if
160 you're already a member, thanks!). TUG produces the periodical
161 @cite{TUGboat}, sponsors an annual meeting and publishes the
162 proceedings, and arranges courses on @TeX{} for all levels of users
163 throughout the world. See @url{http://tug.org} for information.
173 @cindex history of Kpathsea
175 @cindex Knuth, Donald E.
176 This section is for those people who are curious about how the library
177 came about. If you like to read historical accounts of software, we
178 urge you to seek out the GNU Autoconf manual and the ``Errors of
179 @TeX{}'' paper by Don Knuth, published in his book @cite{Digital
180 Typography}, among other places.
187 @pindex pxp @r{Pascal preprocessor}
188 @pindex pc @r{Pascal compiler}
189 [Karl writes.] My first ChangeLog entry for Web2c seems to be
190 February 1990, but I may have done some work before then. In any
191 case, Tim Morgan and I were jointly maintaining it for a time. (I
192 should mention here that Tim had made Web2c into a real distribution
193 long before I had ever used it or even heard of it, and Tom Rokicki
194 did the original implementation. When I started, I was using
195 @code{pxp} and @code{pc} on VAX 11/750's and the hot new Sun 2
198 It must have been later in 1990 and 1991 that I started working on
199 @cite{@TeX{} for the Impatient}. Dvips, Xdvi, Web2c, and the GNU
200 fontutils (which I was also writing at the time) all used different
201 environment variables, and, more importantly, had different bugs in
202 their path searching. This became extremely painful, as I was stressing
203 everything to the limit working on the book. I also desperately wanted
204 to implement subdirectory searching, since I couldn't stand putting
205 everything in one big directory, and also couldn't stand having to
206 explicitly specify @file{cm}, @file{pandora}, @dots{} in a path.
209 In the first incarnation, I just hacked separately on each
210 program---that was the original subdirectory searching code in both
211 Xdvi and Dvips. That is, I tried to go with the flow in each program,
212 rather than changing the program's calling sequences to conform to new
215 Then, as bugs inevitably appeared, I found I was fixing the same thing
216 three times (Web2c and fontutils were already sharing code, since I
217 maintained both of those---there was no Dvipsk or Xdvik or Dviljk at
218 this point). After a while, I finally started sharing source files.
219 They weren't yet a library, though. I just kept things up to date
220 with shell scripts. (I was developing on a 386 running ISC 2.2 at the
221 time, and so didn't have symbolic links. An awful experience.)
223 @cindex MacKenzie, David
224 The ChangeLogs for Xdvik and Dvipsk record initial releases of those
225 distributions in May and June 1992. I think it was because I was tired
226 of the different configuration strategies of each program, not so much
227 because of the path searching. Autoconf was being developed by David
228 MacKenzie and others, and I was adapting it to @TeX{} and friends.
231 I started to make a separate library that other programs could link with
232 on my birthday in April 1993, according to the ChangeLog. I don't
233 remember exactly why I finally took the time to make it a separate
234 library; a conversation with david zuhn initiated it. Just seemed
237 @cindex Walsh, Norman
238 @cindex Neumann, Gustaf
239 Dviljk got started in March 1994 after I bought a Laserjet 4. (Kpathsea
240 work got suspended while Norm Walsh and I, with Gustaf Neumann's help,
241 implemented a way for @TeX{} to get at all those neat builtin LJ4 fonts
242 @dots{} such a treat to have something to typeset in besides Palatino!)
244 By spring of 1995, I had implemented just about all the path-searching
245 features in Kpathsea that I plan to, driven beyond my initial goals by
246 Thomas Esser and others. I then started to integrate Web2c with
247 Kpathsea. After the release of a stable Web2c, I hope to be able to stop
248 development, and turn most of my attention back to making fonts for GNU.
249 (Always assuming Micros**t hasn't completely obliterated Unix by then,
250 or that software patents haven't stopped software development by anybody
251 smaller than a company with a million-dollar-a-year legal budget. Which
252 is actually what I think is likely to happen, but that's another
256 [Olaf writes.] At the end of 1997, Unix is still alive and kicking,
257 individuals still develop software, and Web2c development still
258 continues. Karl had been looking for some time for someone to take up
259 part of the burden, and I volunteered.
261 @cindex Hoekwater, Taco
262 @cindex Breitenlohner, Peter
263 [Karl writes again.] Indeed, time goes on. As of 2006 or so, Olaf's
264 available time for Kpathsea became rather reduced, and I started
265 taking overall care of it again, although I did not do any significant
266 new development. In 2009, Taco Hoekwater made a major rearrangement
267 to make the library suitable for use within the MetaPost library
268 (@pxref{Programming overview}). Also, for some years now, Peter
269 Breitenlohner has made many improvements to the infrastructure and
270 kept up-to-date with respect to the overall @TeX{} Live build, where
271 Kpathsea is now maintained.
274 @c emacs-page separate file so we can easily generate unixtex.ftp.
275 @include unixtex.texi
281 @cindex security considerations
283 None of the programs in the @TeX{} system require any special system
284 privileges, so there's no first-level security concern of people gaining
285 illegitimate root access.
287 @cindex trojan horse attack
288 @flindex .rhosts@r{, writable by @TeX{}}
289 A @TeX{} document, however, can write to arbitrary files, e.g.,
290 @file{~/.rhosts}, and thus an unwitting user who runs @TeX{} on a random
291 document is vulnerable to a trojan horse attack. This loophole is
292 closed by default, but you can be permissive if you so desire in
293 @file{texmf.cnf}. @xref{tex invocation,,, web2c, Web2c}. MetaPost has
296 Dvips, Xdvi, and @TeX{} can also execute shell commands under some
297 circumstances. To disable this, see the @samp{-R} option in @ref{Option
298 details,,, dvips, Dvips}, the xdvi man page, and @ref{tex
299 invocation,,, web2c, Web2c}, respectively.
301 @cindex local cache of fonts
302 @cindex cache of fonts, local
303 Another security issue arises because it's very useful---almost
304 necessary---to make arbitrary fonts on user demand with @code{mktexpk}
305 and friends. Where do these files get installed? By default, the
306 @code{mktexpk} distributed with Kpathsea assumes a world-writable
307 @file{/var/tmp} directory; this is a simple and convenient approach, but
308 it may not suit your situation because it means that a local cache of
309 fonts is created on every machine.
311 @cindex globally writable directories
312 To avoid this duplication, many people consider a shared, globally
313 writable font tree desirable, in spite of the potential security
314 problems. To do this you should change the value of @code{VARTEXFONTS}
315 in @file{texmf.cnf} to refer to some globally known directory.
316 @xref{mktex configuration}.
318 @cindex append-only directories and @code{mktexpk}
319 The first restriction you can apply is to make newly-created directories
320 under @file{texmf} be append-only with an option in @file{mktex.cnf}.
321 @xref{mktex configuration}.
323 @cindex group-writable directories
324 @cindex setgid scripts
325 Another approach is to establish a group (or user) for @TeX{} files,
326 make the @file{texmf} tree writable only to that group (or user), and
327 make @code{mktexpk} et al.@: setgid to that group (or setuid to that
328 user). Then users must invoke the scripts to install things. (If
329 you're worried about the inevitable security holes in scripts, then you
330 could write a C wrapper to exec the script.)
332 @cindex file permissions
333 @cindex permissions, file
334 The @file{mktex@dots{}} scripts install files with the same read and
335 write permissions as the directory they are installed in. The
336 executable, sgid, suid, and sticky bits are always cleared.
338 @cindex directory permissions
339 @cindex permissions, directory
340 Any directories created by the @file{mktex@dots{}} scripts have the
341 same permissions as their parent directory, unless the
342 @code{appendonlydir} feature is used, in which case the sticky bit is
346 @node TeX directory structure
347 @chapter @TeX{} directory structure
350 @cindex @TeX{} directory structure
351 @cindex directory structure, for @TeX{} files
352 @cindex skeleton @TeX{} directory
355 This section describes the default installation hierarchy of the
356 distribution. It conforms to both the GNU coding standards and the
357 @TeX{} directory structure (TDS) standard. For rationale and further
358 explanation, please see those documents. The GNU document is
359 available from @url{http://www.gnu.org/prep/standards}. The TDS
360 document is available from @url{http://www.mirror.ctan.org/tds}
361 (@pxref{unixtex.ftp}).
363 In short, here is a skeleton of the default directory structure,
364 extracted from the TDS document:
367 @var{prefix}/ @r{installation root (@file{/usr/local} by default)}
370 include/ @r{C header files}
371 info/ @r{GNU info files}
372 lib/ @r{libraries (@file{libkpathsea.*})}
373 share/ @r{architecture-independent files}
375 bibtex/ @r{Bib@TeX{} input files}
376 bib/ @r{Bib@TeX{} databases}
377 base/ @r{base distribution (e.g., @samp{xampl.bib})}
378 misc/ @r{single-file databases}
379 @var{pkg}/ @r{name of a package}
380 bst/ @r{Bib@TeX{} style files}
381 base/ @r{base distribution (e.g., @samp{plain.bst}, @samp{acm.bst})}
382 misc/ @r{single-file styles}
383 @var{pkg}/ @r{name of a package}
384 doc/ @r{additional documentation}
385 dvips/ @r{@samp{.pro}, @samp{.ps}, @samp{psfonts.map}}
386 fonts/ @r{font-related files}
387 @var{type}/ @r{file type (e.g., @samp{tfm}, @samp{pk})}
388 @var{mode}/ @r{type of output device (types @samp{pk} and @samp{gf} only)}
389 @var{supplier}/ @r{name of a font supplier (e.g., @samp{public})}
390 @var{typeface}/ @r{name of a typeface (e.g., @samp{cm})}
391 dpi@var{nnn}/ @r{font resolution (types @samp{pk} and @samp{gf} only)}
392 metafont/ @r{Metafont (non-font) input files}
393 base/ @r{base distribution (e.g., @samp{plain.mf})}
394 misc/ @r{single-file packages (e.g., @samp{modes.mf})}
395 @var{pkg}/ @r{name of a package (e.g., @samp{mfpic})}
396 metapost/ @r{MetaPost input files}
397 base/ @r{base distribution (e.g., @samp{plain.mp})}
398 misc/ @r{single-file packages}
399 @var{pkg}/ @r{name of a package}
400 support/ @r{support files for MetaPost-related utilities (e.g., @samp{trfonts.map})}
401 mft/ @r{@samp{MFT} inputs (e.g., @samp{plain.mft})}
402 tex/ @r{@TeX{} input files}
403 @var{format}/ @r{name of a format (e.g., @samp{plain})}
404 base/ @r{base distribution for @var{format} (e.g., @samp{plain.tex})}
405 misc/ @r{single-file packages (e.g., @samp{webmac.tex})}
406 local/ @r{local additions to or local configuration files for @var{format}}
407 @var{pkg}/ @r{name of a package (e.g., @samp{graphics}, @samp{mfnfss})}
408 generic/ @r{format-independent packages}
409 hyphen/ @r{hyphenation patterns (e.g., @samp{hyphen.tex})}
410 images/ @r{image input files (e.g., Encapsulated PostScript)}
411 misc/ @r{single-file format-independent packages (e.g., @samp{null.tex}).}
412 @var{pkg}/ @r{name of a package (e.g., @samp{babel})}
413 web2c/ @r{implementation-dependent files (@file{.pool}, @file{.fmt}, @file{texmf.cnf}, etc.)}
416 Some concrete examples for most file types:
420 /usr/local/man/man1/xdvi.1
421 /usr/local/info/kpathsea.info
422 /usr/local/lib/libkpathsea.a
423 /usr/local/share/texmf/bibtex/bst/base/plain.bst
424 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk
425 /usr/local/share/texmf/fonts/source/public/pandora/pnr10.mf
426 /usr/local/share/texmf/fonts/tfm/public/cm/cmr10.tfm
427 /usr/local/share/texmf/fonts/type1/adobe/utopia/putr.pfa
428 /usr/local/share/texmf/metafont/base/plain.mf
429 /usr/local/share/texmf/metapost/base/plain.mp
430 /usr/local/share/texmf/tex/plain/base/plain.tex
431 /usr/local/share/texmf/tex/generic/hyphen/hyphen.tex
432 /usr/local/share/texmf/web2c/tex.pool
433 /usr/local/share/texmf/web2c/tex.fmt
434 /usr/local/share/texmf/web2c/texmf.cnf
439 @chapter Path searching
441 @cindex path searching
443 This chapter describes the generic path searching mechanism Kpathsea
444 provides. For information about searching for particular file types
445 (e.g., @TeX{} fonts), see the next chapter.
448 * Searching overview:: Basic scheme for searching.
449 * Path sources:: Where search paths can be defined.
450 * Path expansion:: Special constructs in search paths.
451 * Filename database:: Using an externally-built list to search.
452 * Invoking kpsewhich:: Standalone path lookup.
456 @node Searching overview
457 @section Searching overview
459 @cindex searching overview
460 @cindex path searching, overview
461 @cindex overview of path searching
463 @cindex search path, defined
464 A @dfn{search path} is a colon-separated list of @dfn{path elements},
465 which are directory names with a few extra frills. A search path can
466 come from (a combination of) many sources; see below. To look up a file
467 @samp{foo} along a path @samp{.:/dir}, Kpathsea checks each element of
468 the path in turn: first @file{./foo}, then @file{/dir/foo}, returning
469 the first match (or possibly all matches).
471 @cindex magic characters
472 @kindex : @r{may not be :}
473 @kindex / @r{may not be /}
474 The ``colon'' and ``slash'' mentioned here aren't necessarily @samp{:}
475 and @samp{/} on non-Unix systems. Kpathsea tries to adapt to other
476 operating systems' conventions.
478 @cindex database search
479 @cindex searching the database
480 To check a particular path element @var{e}, Kpathsea first sees if a
481 prebuilt database (@pxref{Filename database}) applies to @var{e}, i.e.,
482 if the database is in a directory that is a prefix of @var{e}. If so,
483 the path specification is matched against the contents of the database.
485 @cindex floating directories
486 @cindex filesystem search
488 @cindex searching the disk
489 If the database does not exist, or does not apply to this path element,
490 or contains no matches, the filesystem is searched (if this was not
491 forbidden by the specification with @samp{!!} and if the file being
492 searched for must exist). Kpathsea constructs the list of directories
493 that correspond to this path element, and then checks in each for the
494 file being searched for. (To help speed future lookups of files in the
495 same directory, the directory in which a file is found is floated to the
496 top of the directory list.)
499 @cindex VF files, not found
502 The ``file must exist'' condition comes into play with VF files and
503 input files read by the @TeX{} @samp{\openin} command. These files
504 might very well not exist (consider @file{cmr10.vf}), and so it would
505 be wrong to search the disk for them. Therefore, if you fail to
506 update @file{ls-R} when you install a new VF file, it will not be
509 Each path element is checked in turn: first the database, then the disk.
510 If a match is found, the search stops and the result is returned. This
511 avoids possibly-expensive processing of path specifications that are
512 never needed on a particular run. (Unless the search explicitly
513 requested all matches.)
515 @cindex expansion, path element
516 Although the simplest and most common path element is a directory name,
517 Kpathsea supports additional features in search paths: layered default
518 values, environment variable names, config file values, users' home
519 directories, and recursive subdirectory searching. Thus, we say that
520 Kpathsea @dfn{expands} a path element, meaning transforming all the
521 magic specifications into the basic directory name or names. This
522 process is described in the sections below. It happens in the same
523 order as the sections.
525 @cindex absolute filenames
526 @cindex relative filenames
527 @cindex explicitly relative filenames
528 @cindex filenames, absolute or explicitly relative
529 Exception to all of the above: If the filename being searched for is
530 absolute or explicitly relative, i.e., starts with @samp{/} or @samp{./}
531 or @samp{../}, Kpathsea simply checks if that file exists.
533 @cindex permission denied
534 @cindex unreadable files
535 @cindex access warnings
536 @cindex warnings, file access
537 @flindex lost+found @r{directory}
539 Ordinarily, if Kpathsea tries to access a file or directory that
540 cannot be read, it gives a warning. This is so you will be alerted to
541 directories or files that accidentally lack any read permission (for
542 example, a @file{lost+found} directory). If you prefer not to see
543 these warnings, include the value @samp{readable} in the
544 @code{TEX_HUSH} environment variable or config file value.
546 This generic path searching algorithm is implemented in
547 @file{kpathsea/pathsearch.c}. It is employed by a higher-level
548 algorithm when searching for a file of a particular type (@pxref{File
549 lookup}, and @ref{Glyph lookup}).
553 @section Path sources
556 @cindex sources for search paths
558 A search path can come from many sources. In the order in which
563 @cindex environment variable, source for path
564 A user-set environment variable, e.g., @code{TEXINPUTS}.
565 Environment variables with an underscore and the program name appended
566 override; for example, @code{TEXINPUTS_latex} overrides @code{TEXINPUTS}
567 if the program being run is named @samp{latex}.
570 A program-specific configuration file, e.g., an @samp{S /a:/b} line in
571 Dvips' @file{config.ps} (@pxref{Config files,,, dvips, Dvips}).
574 @cindex configuration file, source for path
575 @cindex Kpathsea config file, source for path
576 @flindex texmf.cnf@r{, source for path}
577 A line in a Kpathsea configuration file @file{texmf.cnf}, e.g.,
578 @samp{TEXINPUTS=/c:/d} (see below).
581 @cindex compilation value, source for path
582 The compile-time default (specified in @file{kpathsea/paths.h}).
585 You can see each of these values for a given search path by using the
586 debugging options (@pxref{Debugging}).
588 These sources may be combined via default expansion (@pxref{Default
592 * Config files:: Kpathsea's runtime config files (texmf.cnf).
597 @subsection Config files
600 @flindex texmf.cnf@r{, definition for}
602 @cindex runtime configuration files
604 As mentioned above, Kpathsea reads @dfn{runtime configuration files}
605 named @file{texmf.cnf} for search path and other definitions. The
606 search path used to look for these configuration files is named
607 @code{TEXMFCNF}, and is constructed in the usual way, as described
608 above, except that configuration files cannot be used to define the
609 path, naturally; also, an @file{ls-R} database is not used to search for
612 Kpathsea reads @emph{all} @file{texmf.cnf} files in the search path, not
613 just the first one found; definitions in earlier files override those in
614 later files. Thus, if the search path is @samp{.:$TEXMF}, values from
615 @file{./texmf.cnf} override those from @file{$TEXMF/texmf.cnf}.
617 @vindex KPATHSEA_WARNING
618 @cindex warning, about missing @file{texmf.cnf}
619 @cindex @file{texmf.cnf} missing, warning about
620 If Kpathsea cannot find any @file{texmf.cnf} file, it reports a
621 warning including all the directories it checked. If you don't want
622 to see this warning, set the environment variable
623 @env{KPATHSEA_WARNING} to the single character @samp{0} (zero, not
626 While (or instead of) reading this description, you may find it helpful
627 to look at the distributed @file{texmf.cnf}, which uses or at least
628 mentions most features. The format of @file{texmf.cnf} files follows:
632 @cindex comments, in @file{texmf.cnf}
633 Comments start with @samp{%}, either at the beginning of a line or
634 preceded by whitespace, and continue to the end of the line. That is,
635 as with most shells, a @samp{%} in the ``middle'' of a value does not
636 start a comment. Examples:
640 var = a%b % but the value of var will be "a%b".
644 @cindex blank lines, in @file{texmf.cnf}
645 Blank lines are ignored.
648 @cindex backslash-newline
649 @cindex continuation character
650 @cindex whitespace, not ignored on continuation lines
651 @kindex \@r{, line continuation in @file{texmf.cnf}}
652 A @samp{\} at the end of a line acts as a continuation character, i.e.,
653 the next line is appended. Whitespace at the beginning of continuation
654 lines is not ignored.
656 @item Each remaining line must look like
659 @var{variable} @r{[}. @var{progname}@r{]} @r{[}=@r{]} @var{value}
662 @noindent where the @samp{=} and surrounding whitespace is optional.
665 @cindex identifiers, characters valid in
666 The @var{variable} name may contain any character other than whitespace,
667 @samp{=}, or @samp{.}, but sticking to @samp{A-Za-z_} is safest.
669 @item If @samp{.@var{progname}} is present, the definition only
670 applies if the program that is running is named (i.e., the last
671 component of @code{argv[0]} is) @var{progname} or
672 @file{@var{progname}.@{exe,bat,cmd,...@}}. Most notably, this allows
673 different flavors of @TeX{} to have different search paths.
676 @cindex right-hand side of variable assignments
677 @var{value} may contain any characters except @samp{%} and @samp{@@}.
678 (These restrictions are only necessary because of the processing done
679 on @file{texmf.cnf} at build time, so you can stick those characters
680 in after installation if you have to.) The
681 @samp{$@var{var}.@var{prog}} feature is not available on the
682 right-hand side; instead, you must use an additional variable (see
683 below for example). A @samp{;} in @var{value} is translated to
684 @samp{:} if running under Unix; this is useful to write a single
685 @file{texmf.cnf} which can be used under both Unix and Windows.
687 @item All definitions are read before anything is expanded, so you can
688 use variables before they are defined (like Make, unlike most other
692 @noindent Here is a configuration file fragment illustrating most of
696 % TeX input files -- i.e., anything to be found by \input or \openin ...
697 latex209_inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex//
698 latex2e_inputs = .:$TEXMF/tex/latex//:$TEXMF/tex//
699 TEXINPUTS = .:$TEXMF/tex//
700 TEXINPUTS.latex209 = $latex209_inputs
701 TEXINPUTS.latex2e = $latex2e_inputs
702 TEXINPUTS.latex = $latex2e_inputs
705 @cindex shell scripts as configuration files
706 @cindex configuration files as shell scripts.
707 This format has obvious similarities to Bourne shell scripts---change
708 the comment character to @code{#}, disallow spaces around the
709 @code{=}, and get rid of the @code{.@var{name}} convention, and it
710 could be run through the shell. However, there seemed little
711 advantage in this, since all the information would have to passed back
712 to Kpathsea and parsed there anyway, since the @code{sh} process
713 couldn't affect its parent's environment.
716 The implementation of all this is in @file{kpathsea/cnf.c}.
720 @section Path expansion
722 @cindex path expansion
723 @cindex expansion, search path
725 Kpathsea recognizes certain special characters and constructions in
726 search paths, similar to that in shells. As a general example:
727 @samp{~$USER/@{foo,bar@}//baz} expands to all subdirectories under
728 directories @file{foo} and @file{bar} in @t{$USER}'s home directory that
729 contain a directory or file @file{baz}. These expansions are explained
730 in the sections below.
733 * Default expansion:: a: or :a or a::b expands to a default.
734 * Variable expansion:: $foo and $@{foo@} expand to environment values.
735 * Tilde expansion:: ~ and ~user expand to home directories.
736 * Brace expansion:: a@{foo,bar@}b expands to afoob abarb.
737 * KPSE_DOT expansion:: . is replaced with $KPSE_DOT if it is defined.
738 * Subdirectory expansion:: a// and a//b recursively expand to subdirs.
742 @node Default expansion
743 @subsection Default expansion
745 @kindex :: @r{expansion}
746 @cindex doubled colons
747 @cindex leading colons
748 @cindex trailing colons
750 @cindex default expansion
751 @cindex expansion, default
753 If the highest-priority search path (@pxref{Path sources}) contains an
754 @dfn{extra colon} (i.e., leading, trailing, or doubled), Kpathsea
755 inserts at that point the next-highest-priority search path that is
756 defined. If that inserted path has an extra colon, the same happens
757 with the next-highest. (An extra colon in the compile-time default
758 value has unpredictable results, so installers beware.)
760 For example, given an environment variable setting
763 setenv TEXINPUTS /home/karl:
766 @noindent and a @code{TEXINPUTS} value from @file{texmf.cnf} of
772 @noindent then the final value used for searching will be:
775 /home/karl:.:$TEXMF//tex
778 Put another way, default expansion works on ``formats'' (search
779 paths), and not directly on environment variables. Example, showing
780 the trailing @samp{:} ignored in the first case and expanded in the second:
783 $ env TTFONTS=/tmp: kpsewhich --expand-path '$TTFONTS'
785 $ env TTFONTS=/tmp: kpsewhich --show-path=.ttf
786 /tmp:.:/home/olaf/texmf/fonts/truetype//:...
789 Since Kpathsea looks for multiple configuration files, it would be
790 natural to expect that (for example) an extra colon in
791 @file{./texmf.cnf} would expand to the path in @file{$TEXMF/texmf.cnf}.
792 Or, with Dvips' configuration files, that an extra colon in
793 @file{config.$PRINTER} would expand to the path in @file{config.ps}.
794 This doesn't happen. It's not clear this would be desirable in all
795 cases, and trying to devise a way to specify the path to which the extra
796 colon should expand seemed truly baroque.
797 @cindex Bach, Johann Sebastian
799 Technicality: Since it would be useless to insert the default value in
800 more than one place, Kpathsea changes only one extra @samp{:} and leaves
801 any others in place (they will eventually be ignored). Kpathsea checks
802 first for a leading @samp{:}, then a trailing @samp{:}, then a doubled
806 You can trace this by debugging ``paths'' (@pxref{Debugging}).
807 Default expansion is implemented in the source file
808 @file{kpathsea/kdefault.c}.
811 @node Variable expansion
812 @subsection Variable expansion
814 @kindex $ @r{expansion}
815 @cindex environment variables in paths
816 @cindex variable expansion
817 @cindex expansion, variable
818 @flindex texmf.cnf@r{, and variable expansion}
820 @samp{$foo} or @samp{$@{foo@}} in a path element is replaced by (1) the
821 value of an environment variable @samp{foo} (if defined); (2) the value
822 of @samp{foo} from @file{texmf.cnf} (if defined); (3) the empty string.
824 If the character after the @samp{$} is alphanumeric or @samp{_}, the
825 variable name consists of all consecutive such characters. If the
826 character after the @samp{$} is a @samp{@{}, the variable name consists
827 of everything up to the next @samp{@}} (braces may not be nested around
828 variable names). Otherwise, Kpathsea gives a warning and ignores the
829 @samp{$} and its following character.
831 @cindex quoting variable values
832 @cindex shell variables
833 You must quote the @t{$}'s and braces as necessary for your shell.
834 @emph{Shell} variable values cannot be seen by Kpathsea, i.e., ones
835 defined by @code{set} in C shells and without @code{export} in Bourne
840 setenv tex /home/texmf
841 setenv TEXINPUTS .:$tex:$@{tex@}prev
843 @noindent the final @code{TEXINPUTS} path is the three directories:
845 .:/home/texmf:/home/texmfprev
848 The @samp{.@var{progname}} suffix on variables and
849 @samp{_@var{progname}} on environment variable names are not implemented
850 for general variable expansions. These are only recognized when search
851 paths are initialized (@pxref{Path sources}).
854 Variable expansion is implemented in the source file
855 @file{kpathsea/variable.c}.
858 @node Tilde expansion
859 @subsection Tilde expansion
861 @kindex ~ @r{expansion}
862 @cindex home directories in paths
863 @cindex tilde expansion
864 @cindex expansion, tilde
866 @vindex HOME@r{, as ~ expansion}
867 @vindex USERPROFILE@r{, as ~ expansion}
868 A leading @samp{~} in a path element is replaced by the value of the
869 environment variable @code{HOME}, or @file{.} if @code{HOME} is not
870 set. On Windows, the environment variable @code{USERPROFILE} is
871 checked instead of @code{HOME}.
873 A leading @samp{~@var{user}} in a path element is replaced by
874 @var{user}'s home directory from the system @file{passwd} database.
878 setenv TEXINPUTS ~/mymacros:
881 @noindent will prepend a directory @file{mymacros} in your home
882 directory to the default path.
884 @cindex @t{root} user
885 @cindex trailing @samp{/} in home directory
886 @kindex /@r{, trailing in home directory}
887 As a special case, if a home directory ends in @samp{/}, the trailing
888 slash is dropped, to avoid inadvertently creating a @samp{//} construct
889 in the path. For example, if the home directory of the user @samp{root}
890 is @samp{/}, the path element @samp{~root/mymacros} expands to just
891 @samp{/mymacros}, not @samp{//mymacros}.
894 Tilde expansion is implemented in the source file @file{kpathsea/tilde.c}.
897 @node Brace expansion
898 @subsection Brace expansion
900 @kindex @{ @r{expansion}
901 @cindex brace expansion
903 @samp{x@{@var{a},@var{b}@}y} expands to @samp{x@var{a}y:x@var{b}y}.
910 @noindent expands to @samp{foo/1/baz:foo/2/baz}. @samp{:} is the path
911 separator on the current system; e.g., on a DOS system, it's @samp{;}.
913 Braces can be nested; for example, @samp{x@{A,B@{1,2@}@}y} expands to
914 @samp{xAy:xB1y:xB2y}.
916 Multiple non-nested braces are expanded from right to left; for example,
917 @samp{x@{A,B@}@{1,2@}y} expands to @samp{x@{A,B@}1y:x@{A,B@}2y}, which
918 expands to @samp{xA1y:xB1y:xA2y:xB2y}.
920 @cindex multiple @TeX{} hierarchies
921 This feature can be used to implement multiple @TeX{} hierarchies, by
922 assigning a brace list to @code{$TEXMF}, as mentioned in
925 You can also use the path separator instead of the comma. The last
926 example could have been written @samp{x@{A:B@}@{1:2@}y}.
930 Brace expansion is implemented in the source file
931 @file{kpathsea/expand.c}.
934 @node KPSE_DOT expansion
935 @subsection @code{KPSE_DOT} expansion
937 @kindex KPSE_DOT @r{expansion}
939 When @code{KPSE_DOT} is defined in the environment, it names a directory
940 that should be considered the current directory for the purpose of
941 looking up files in the search paths. This feature is needed by the
942 @samp{mktex@dots{}} scripts @ref{mktex scripts}, because these
943 change the working directory. You should not ever define it yourself.
946 @node Subdirectory expansion
947 @subsection Subdirectory expansion
950 @cindex subdirectory searching
951 @cindex expansion, subdirectory
953 @cindex alphabetical order, not
954 Two or more consecutive slashes in a path element following a directory
955 @var{d} is replaced by all subdirectories of @var{d}: first those
956 subdirectories directly under @var{d}, then the subsubdirectories under
957 those, and so on. At each level, the order in which the directories are
958 searched is unspecified. (It's ``directory order'', and definitely not
961 If you specify any filename components after the @samp{//}, only
962 subdirectories which match those components are included. For example,
963 @samp{/a//b} would expand into directories @file{/a/1/b}, @file{/a/2/b},
964 @file{/a/1/1/b}, and so on, but not @file{/a/b/c} or @file{/a/1}.
966 You can include multiple @samp{//} constructs in the path.
968 @samp{//} at the beginning of a path is ignored; you didn't really want
969 to search every directory on the system, did you?
971 @cindex trick for detecting leaf directories
972 @cindex leaf directory trick
973 @cindex Farwell, Matthew
974 @cindex MacKenzie, David
975 I should mention one related implementation trick, which I took from GNU
976 find. Matthew Farwell suggested it, and David MacKenzie implemented it.
979 The trick is that in every real Unix implementation (as opposed to the
980 POSIX specification), a directory which contains no subdirectories will
981 have exactly two links (namely, one for @file{.} and one for @file{..}).
982 That is to say, the @code{st_nlink} field in the @samp{stat} structure
983 will be two. Thus, we don't have to stat everything in the bottom-level
984 (leaf) directories---we can just check @code{st_nlink}, notice it's two,
987 But if you have a directory that contains a single subdirectory and 500
988 regular files, @code{st_nlink} will be 3, and Kpathsea has to stat every
989 one of those 501 entries. Therein lies slowness.
991 @vindex ST_NLINK_TRICK
992 You can disable the trick by undefining @code{ST_NLINK_TRICK} in
993 @file{kpathsea/config.h}. (It is undefined by default except under Unix.)
996 Unfortunately, in some cases files in leaf directories are
997 @code{stat}'d: if the path specification is, say,
998 @samp{$TEXMF/fonts//pk//}, then files in a subdirectory
999 @samp{@dots{}/pk}, even if it is a leaf, are checked. The reason cannot
1000 be explained without reference to the implementation, so read
1001 @file{kpathsea/elt-dirs.c} (search for @samp{may descend}) if you are
1002 curious. And if you can find a way to @emph{solve} the problem, please
1006 Subdirectory expansion is implemented in the source file
1007 @file{kpathsea/elt-dirs.c}.
1010 @node Filename database
1011 @section Filename database (@code{ls-R})
1013 @cindex filename database
1014 @cindex database, for filenames
1015 @cindex externally-built filename database
1017 Kpathsea goes to some lengths to minimize disk accesses for searches
1018 (@pxref{Subdirectory expansion}). Nevertheless, in practice searching
1019 each possible directory in typical @TeX{} installations takes an
1020 excessively long time.
1022 Therefore, Kpathsea can use an externally-built @dfn{filename
1023 database} file named @file{ls-R} that maps files to directories, thus
1024 avoiding the need to exhaustively search the disk.
1026 A second database file @file{aliases} allows you to give additional
1027 names to the files listed in @file{ls-R}. This can be helpful to adapt
1028 to ``8.3'' filename conventions in source files.
1030 The @file{ls-R} and @file{aliases} features are implemented in the
1031 source file @file{kpathsea/db.c}.
1034 * ls-R:: The main filename database.
1035 * Filename aliases:: Aliases for those names.
1036 * Database format:: Syntax details of the database file.
1041 @subsection @file{ls-R}
1043 @flindex ls-R @r{database file}
1046 As mentioned above, you must name the main filename database
1047 @file{ls-R}. You can put one at the root of each @TeX{} installation
1048 hierarchy you wish to search (@code{$TEXMF} by default); most sites have
1049 only one hierarchy. Kpathsea looks for @file{ls-R} files along the
1050 @code{TEXMFDBS} path, so that should presumably match the list of
1053 The recommended way to create and maintain @samp{ls-R} is to run the
1054 @code{mktexlsr} script, which is installed in @samp{$(bindir)}
1055 (@file{/usr/local/bin} by default). That script goes to some trouble to
1056 follow symbolic links as necessary, etc. It's also invoked by the
1057 distributed @samp{mktex@dots{}} scripts.
1059 @flindex ls-R@r{, simplest build}
1060 At its simplest, though, you can build @file{ls-R} with the command
1062 cd @var{/your/texmf/root} && ls -LAR ./ >ls-R
1066 @opindex --color=tty
1067 @flindex /etc/profile @r{and aliases}
1068 presuming your @code{ls} produces the right output format (see the
1069 section below). GNU @code{ls}, for example, outputs in this format.
1070 Also presuming your @code{ls} hasn't been aliased in a system file
1071 (e.g., @file{/etc/profile}) to something problematic, e.g., @samp{ls
1072 --color=tty}. In that case, you will have to disable the alias before
1073 generating @file{ls-R}. For the precise definition of the file format,
1074 see @ref{Database format}.
1076 Regardless of whether you use the supplied script or your own, you will
1077 almost certainly want to invoke it via @code{cron}, so when you make
1078 changes in the installed files (say if you install a new La@TeX{}
1079 package), @file{ls-R} will be automatically updated.
1081 @opindex -A @r{option to @code{ls}}
1083 @flindex . @r{files}
1084 @flindex . @r{directories, ignored}
1085 @flindex .tex @r{file, included in @file{ls-R}}
1086 The @samp{-A} option to @code{ls} includes files beginning with @samp{.}
1087 (except for @file{.} and @file{..}), such as the file @file{.tex}
1088 included with the La@TeX{} tools package. (On the other hand,
1089 @emph{directories} whose names begin with @samp{.} are always ignored.)
1091 @cindex symbolic links, and @file{ls-R}
1092 @opindex -L @r{option to @code{ls}}
1093 If your system does not support symbolic links, omit the @samp{-L}.
1095 @cindex automounter, and @file{ls-R}
1096 @cindex NFS and @file{ls-R}
1097 @code{ls -LAR @var{/your/texmf/root}} will also work. But using
1098 @samp{./} avoids embedding absolute pathnames, so the hierarchy can be
1099 easily transported. It also avoids possible trouble with automounters
1100 or other network filesystem conventions.
1102 @cindex warning about unusable @file{ls-R}
1103 @cindex unusable @file{ls-R} warning
1104 Kpathsea warns you if it finds an @file{ls-R} file, but the file does
1105 not contain any usable entries. The usual culprit is running plain
1106 @samp{ls -R} instead of @samp{ls -LR ./} or @samp{ls -R
1107 @var{/your/texmf/root}}. Another possibility is some system directory
1108 name starting with a @samp{.} (perhaps if you are using AFS); Kpathsea
1109 ignores everything under such directories.
1111 @kindex !! @r{in path specifications}
1112 @cindex disk searching, avoiding
1113 Because the database may be out-of-date for a particular run, if a file
1114 is not found in the database, by default Kpathsea goes ahead and
1115 searches the disk. If a particular path element begins with @samp{!!},
1116 however, @emph{only} the database will be searched for that element,
1117 never the disk. If the database does not exist, nothing will be
1118 searched. Because this can surprise users (``I see the font
1119 @file{foo.tfm} when I do an @code{ls}; why can't Dvips find it?''), it
1120 is not in any of the default search paths.
1123 @node Filename aliases
1124 @subsection Filename aliases
1126 @cindex filename aliases
1127 @cindex aliases, for filenames
1129 In some circumstances, you may wish to find a file under several names.
1130 For example, suppose a @TeX{} document was created using a DOS system
1131 and tries to read @file{longtabl.sty}. But now it's being run on a Unix
1132 system, and the file has its original name, @file{longtable.sty}. The
1133 file won't be found. You need to give the actual file
1134 @file{longtable.sty} an alias @samp{longtabl.sty}.
1136 @c As another example, suppose you are creating a @TeX{} distribution on a
1137 @c CD-ROM or a DOS system; then the file @file{mf.base} gets stored as
1138 @c @file{mf.bas}. But Metafont on Unix wants to find @file{mf.base}. Here
1139 @c you need to give the actual file @file{mf.bas} an alias @samp{mf.base}.
1141 You can handle this by creating a file @file{aliases} as a companion to
1142 the @file{ls-R} for the hierarchy containing the file in question. (You
1143 must have an @file{ls-R} for the alias feature to work.)
1145 The format of @file{aliases} is simple: two whitespace-separated words
1146 per line; the first is the real name @file{longtable.sty}, and second is
1147 the alias (@file{longtabl.sty}). These must be base filenames, with no
1148 directory components. @file{longtable.sty} must be in the sibling
1151 Also, blank lines and lines starting with @samp{%} or @samp{#} are
1152 ignored in @file{aliases}, to allow for comments.
1154 If a real file @file{longtabl.sty} exists, it is used regardless of any
1158 @node Database format
1159 @subsection Database format
1161 @cindex format of external database
1162 @cindex database, format of
1164 The ``database'' read by Kpathsea is a line-oriented file of plain
1165 text. The format is that generated by GNU (and most other) @code{ls}
1166 programs given the @samp{-R} option, as follows.
1170 Blank lines are ignored.
1173 If a line begins with @samp{/} or @samp{./} or @samp{../} and ends with
1174 a colon, it's the name of a directory. (@samp{../} lines aren't useful,
1175 however, and should not be generated.)
1178 All other lines define entries in the most recently seen directory.
1179 @t{/}'s in such lines will produce possibly-strange results.
1182 Files with no preceding directory line are ignored.
1185 For example, here's the first few lines of @file{ls-R} (which totals
1186 about 30K bytes) on my system:
1210 @node Invoking kpsewhich
1211 @section @code{kpsewhich}: Standalone path searching
1214 @cindex path searching, standalone
1215 @cindex standalone path searching
1217 The Kpsewhich program exercises the path searching functionality
1218 independent of any particular application. This can also be useful as a
1219 sort of @code{find} program to locate files in your @TeX{} hierarchies,
1220 perhaps in administrative scripts. It is used heavily in the
1221 distributed @samp{mktex@dots{}} scripts.
1226 kpsewhich @var{option}@dots{} @var{filename}@dots{}
1229 The options and filename(s) to look up can be intermixed.
1230 Options can start with either @samp{-} or @samp{--}, and any unambiguous
1231 abbreviation is accepted.
1234 * Path searching options:: Changing the mode, resolution, etc.
1235 * Specially-recognized files:: Default formats for texmf.cnf, etc.
1236 * Auxiliary tasks:: Path and variable expansion, etc.
1237 * Standard options:: @samp{--help} and @samp{--version}.
1241 @node Path searching options
1242 @subsection Path searching options
1244 @cindex path searching options
1246 Kpsewhich looks up each non-option argument on the command line as a
1247 filename, and returns the first file found.
1249 Various options alter the path searching behavior:
1254 @cindex all matches, finding
1255 Report all matches found, one per line. By default, if there is more
1256 than one match, just one will be reported (chosen effectively at random).
1258 @item --dpi=@var{num}
1259 @opindex --dpi=@var{num}
1260 @opindex -D @var{num}
1261 @cindex resolution, setting
1262 Set the resolution to @var{num}; this only affects @samp{gf} and
1263 @samp{pk} lookups. @samp{-D} is a synonym, for compatibility with
1264 Dvips. Default is 600.
1266 @item --engine=@var{name}
1267 @opindex --engine=@var{name}
1269 Set the engine name to @var{name}. By default it is not set. The
1270 engine name is used in some search paths to allow files with the same
1271 name but used by different engines to coexist.
1273 In particular, since the memory dump files
1274 (@file{.fmt}/@file{.base}/@file{.mem}) are now stored in
1275 subdirectories named for the engine (@file{tex}, @file{pdftex},
1276 @file{xetex}, etc.), you must specify an engine name in order to find
1277 them. For example, @file{cont-en.fmt} typically exists for both
1278 @file{pdftex} and @file{xetex}. With the default path settings, you
1279 can use @samp{--engine=/} to look for any dump file, regardless of
1280 engine; if a dump file exists for more than one engine, it's
1281 indeterminate which one is returned. (The @samp{/} ends up specifying
1282 a normal recursive search along the path where the dumps are stored,
1283 namely @samp{$TEXMF/web2c@{/$engine,@}}.)
1285 @item --format=@var{name}
1286 @opindex --format=@var{name}
1287 Set the format for lookup to @var{name}. By default, the format is
1288 guessed from the filename, with @samp{tex} being used if nothing else
1289 fits. The recognized filename extensions (including any leading
1290 @samp{.}) are also allowable @var{name}s.
1292 All formats also have a name, which is the only way to specify formats
1293 with no associated suffix. For example, for Dvips configuration files
1294 you can use @samp{--format="dvips config"}. (The quotes are for the
1297 Here's the current list of recognized names and the associated suffixes.
1298 @xref{Supported file formats}, for more information on each of these.
1300 The strings in parentheses are abbreviations recognized only by
1301 @code{kpsewhich} (not the underlying library calls). They are
1302 provided when it would otherwise require an argument containing a
1303 space to specify the format, to simplify quoting of calls from shells.
1308 bitmap font (bitmapfont):
1324 MetaPost support (mpsupport):
1331 graphic/figure: .eps .epsi
1332 tex: .tex .sty .cls .fd .aux .bbl .def .clo .ldf
1333 TeX system documentation (doc):
1335 TeX system sources (source): .dtx .ins
1336 PostScript header: .pro
1337 Troff fonts (trofffont):
1338 type1 fonts: .pfa .pfb
1340 dvips config (dvipsconfig):
1342 truetype fonts: .ttf .ttc .TTF .TTC .dfont
1343 type42 fonts: .t42 .T42
1344 web2c files (web2c):
1345 other text files (othertext):
1346 other binary files (otherbin):
1347 misc fonts (miscfont):
1352 subfont definition files: .sfd
1353 opentype fonts: .otf
1354 pdftex config (pdftexconfig):
1357 lua: .lua .luatex .luc .luctex .texlua .texluc .tlu
1358 font feature files: .fea
1359 cid maps: .cid .cidmap
1367 This option and @samp{--path} are mutually exclusive.
1370 @opindex --interactive
1371 @cindex interactive query
1372 After processing the command line, read additional filenames to look up
1373 from standard input.
1375 @item --mktex=@var{filetype}
1376 @itemx --no-mktex=@var{filetype}
1377 @opindex --mktex=@var{filetype}
1378 @opindex --no-mktex=@var{filetype}
1379 Turn on or off the @samp{mktex} script associated with @var{filetype}.
1380 Usual values for @var{filetype} are @samp{pk}, @samp{mf}, @samp{tex},
1381 and @samp{tfm}. By default, all are off in Kpsewhich, even if they
1382 are enabled for @TeX{}. This option implies setting
1383 @code{--must-exist}. @xref{mktex scripts}.
1385 @item --mode=@var{string}
1386 @opindex --mode=@var{string}
1387 Set the mode name to @var{string}; this also only affects @samp{gf} and
1388 @samp{pk} lookups. No default: any mode will be found. @xref{mktex
1392 @opindex --must-exist
1393 Do everything possible to find the files, notably including searching
1394 the disk and running the @samp{mktex} scripts. By default, only the
1395 @file{ls-R} database is checked, in the interest of efficiency.
1397 @item --path=@var{string}
1398 @opindex --path=@var{string}
1399 Search along the path @var{string} (colon-separated as usual), instead
1400 of guessing the search path from the filename. @samp{//} and all the
1401 usual expansions are supported (@pxref{Path expansion}). This option
1402 and @samp{--format} are mutually exclusive. To output the complete
1403 directory expansion of a path, instead of doing a one-shot lookup, see
1404 @samp{--expand-path} and @samp{--show-path} in the following section.
1406 @item --progname=@var{name}
1407 @opindex --progname=@var{name}
1408 Set the program name to @var{name}; default is @samp{kpsewhich}. This
1409 can affect the search paths via the @samp{.@var{prognam}} feature in
1410 configuration files (@pxref{Config files}).
1412 @item --subdir=@var{string}
1413 @opindex --subdir=@var{string}
1414 Report only those matches whose directory part @emph{ends} with
1415 @var{string} (compared literally, except case is ignored on a
1416 case-insensitive operating system). For example, suppose there are
1417 two matches for a given name:
1421 @result{} /some/where/foo.sty
1422 /another/place/foo.sty
1426 Then we can narrow the result to what we are interested in with
1430 kpsewhich --subdir=where foo.sty
1431 @result{} /some/where/foo.sty
1433 kpsewhich --subdir=place foo.sty
1434 @result{} /another/place/foo.sty
1438 The string to match must be at the end of the directory part of the
1439 match, and it is taken literally, with no pattern matching:
1442 kpsewhich --subdir=another foo.sty
1447 The string to match may cross directory components:
1450 kpsewhich --subdir=some/where foo.sty
1451 @result{} /some/where/foo.sty
1455 @option{--subdir} implies @option{--all}; if there is more than one
1456 match, they will all be reported (in our example, both @samp{where}
1457 and @samp{place} end in @samp{e}):
1460 kpsewhich --subdir=e
1461 @result{} /some/where/foo.sty
1462 /another/place/foo.sty
1466 Because of the above rules, the presence of a leading @samp{/} is
1467 important, since it ``anchors'' the match to a full component name:
1470 kpsewhich --subdir=/lace foo.sty
1475 However, a trailing @samp{/} is immaterial (and ignored), since the
1476 match always takes place at the end of the directory part:
1479 kpsewhich --subdir=lace/ foo.sty
1480 @result{} /another/place/foo.sty
1484 The purpose of these rules is to make it convenient to find results
1485 only within a particular area of the tree. For instance, a given
1486 script named @file{foo.lua} might exist within both
1487 @file{texmf-dist/scripts/pkg1/} and @file{texmf-dist/scripts/pkg2/}.
1488 By specifying, say, @samp{--subdir=/pkg1}, you can be sure of getting
1489 the one you are interested in.
1491 We only match at the end because a site might happen to install @TeX{}
1492 in @file{/some/coincidental/pkg1/path/}, and we wouldn't want to match
1493 @file{texmf-dist/scripts/pkg2/} that when searching for @samp{/pkg1}.
1498 @node Specially-recognized files
1499 @subsection Specially-recognized files for @command{kpsewhich}
1501 @command{kpsewhich} recognizes a few special filenames on the command
1502 line and defaults to using the `known' file formats for them, merely
1503 to save the time and trouble of specifying the format. This is only a
1504 feature of @command{kpsewhich}; when using the Kpathsea library
1505 itself, none of these special filenames are recognized, and it's still
1506 up to the caller to specify the desired format.
1508 Here is the list of special filenames to @command{kpsewhich}, along
1509 with their corresponding format:
1517 @flindex dvipdfmx.cfg
1519 @samp{other text files}
1521 @flindex fmtutil.cnf
1525 @flindex glyphlist.txt
1533 @flindex pdfglyphlist.txt
1534 @item pdfglyphlist.txt
1538 @flindex pdftexconfig.tex
1540 @samp{pdftex config} (although @file{pdftex.cfg} is not used any more;
1541 look for the file @file{pdftexconfig.tex} instead.)
1549 @samp{other text files}
1553 A user-specified format will override the above defaults.
1556 Another useful configuration file in this regard is @file{tcfmgr.map},
1557 found in @file{texmf/texconfig/tcfmgr.map}, which records various
1558 information about the above configuration files (among others).
1561 @node Auxiliary tasks
1562 @subsection Auxiliary tasks
1564 @cindex auxiliary tasks
1566 Kpsewhich provides some features in addition to path lookup as such:
1569 @item --debug=@var{num}
1570 @opindex --debug=@var{num}
1571 Set debugging options to @var{num}. @xref{Debugging}.
1573 @item --expand-braces=@var{string}
1574 @opindex --expand-braces=@var{string}
1575 Output variable and brace expansion of @var{string}. @xref{Path
1578 @item --expand-path=@var{string}
1579 @opindex --expand-path=@var{string}
1580 Output the complete expansion of @var{string}, with each element
1581 separated by the usual path separator on the current system (@samp{;}
1582 on Windows, @samp{:} otherwise). This may be useful to construct a
1583 custom search path for a format not otherwise supported. To retrieve
1584 the search path for a format that is already supported, see
1587 Nonexistent directories are culled from the output:
1590 $ kpsewhich --expand-path '/tmp'
1592 $ kpsewhich --expand-path '/nonesuch'
1596 For one-shot uses of an arbitrary (not built in to Kpathsea) path, see
1597 @samp{--path} (@pxref{Path searching options})
1599 @item --expand-var=@var{string}
1600 @opindex --expand-var=@var{string}
1601 Output the variable and tilde expansion of @var{string}
1602 the @samp{mktex@dots{}} scripts run @samp{kpsewhich
1603 --expand-var='$TEXMF'} to find the root of the @TeX{} system
1604 hierarchy. @xref{Path expansion}.
1606 @item --help-formats
1607 @opindex --help-formats
1608 Output information about each supported format (@pxref{Supported file
1609 formats}), including the names and abbreviations, variables
1610 looked for, and the original path.
1612 @item --safe-in-name=@var{name}
1613 @itemx --safe-out-name=@var{name}
1614 @opindex --safe-in-name=@var{name}
1615 @opindex --safe-out-name=@var{name}
1616 Exit successfully if @var{name} is safe to open for reading or
1617 writing, respectively, else unsuccessfully. No output is written.
1618 These tests take account of the related Kpathsea configuration
1619 settings (@pxref{Calling sequence}).
1621 @item --show-path=@var{name}
1622 @opindex --show-path=@var{name}
1623 Show the path that would be used for file lookups of file type
1624 @var{name}. Either a filename extension (@samp{pk}, @samp{.vf}, etc.)
1625 or an integer can be used, just as with @samp{--format}, described in
1626 the previous section.
1628 @item --var-value=@var{variable}
1629 @opindex --var-value=@var{variable}
1630 Outputs the value of @var{variable} (a simple identifier like
1631 @samp{TEXMF}, with no @samp{$} or other constructs), expanding
1632 @samp{$} (@pxref{Variable expansion} and @samp{~} (@pxref{Tilde
1633 expansion}) constructs, but not performing other expansions.
1638 @node Standard options
1639 @subsection Standard options
1641 @cindex standard options
1643 Kpsewhich accepts the standard GNU options:
1648 @samp{--help} prints a help message on standard output and exits
1653 @samp{--version} prints the Kpathsea version number and exits successfully.
1658 @chapter @TeX{} support
1660 @cindex @TeX{} support
1662 Although the basic features in Kpathsea can be used for any type of path
1663 searching, it came about (like all libraries) with a specific
1664 application in mind: I wrote Kpathsea specifically for @TeX{} system
1665 programs. I had been struggling with the programs I was using (Dvips,
1666 Xdvi, and @TeX{} itself) having slightly different notions of how to
1667 specify paths; and debugging was painful, since no code was shared.
1669 Therefore, Kpathsea provides some @TeX{}-specific formats and features.
1670 Indeed, many of the supposedly generic path searching features were
1671 provided because they seemed useful in that con@TeX{}t (font lookup,
1674 Kpathsea provides a standard way to search for files of any of the
1675 supported file types; glyph fonts are a bit different than all the rest.
1676 Searches are based solely on filenames, not file contents---if a GF
1677 file is named @file{cmr10.600pk}, it will be found as a PK file.
1680 * Supported file formats:: File types Kpathsea knows about.
1681 * File lookup:: Searching for most kinds of files.
1682 * Glyph lookup:: Searching for bitmap fonts.
1683 * Suppressing warnings:: Avoiding warnings via TEX_HUSH.
1684 * mktex scripts:: Generating files at runtime.
1688 @node Supported file formats
1689 @section Supported file formats
1691 @cindex supported file formats
1692 @cindex file formats, supported
1694 @cindex environment variables for @TeX{}
1695 @cindex @TeX{} environment variables
1697 Kpathsea has support for a number of file types. Each file type has a
1698 list of environment and config file variables that are checked to define
1699 the search path, and most have a default suffix that plays a role in
1700 finding files (see the next section). Some also define additional
1701 suffixes, and/or a program to be run to create missing files on the fly.
1703 @cindex program-varying paths
1704 Since environment variables containing periods, such as
1705 @samp{TEXINPUTS.latex}, are not allowed on some systems, Kpathsea looks
1706 for environment variables with an underscore, e.g.,
1707 @samp{TEXINPUTS_latex} (@pxref{Config files}).
1709 The following table lists the above information. You can also get the
1710 list by giving the @samp{--help-formats} option to @code{kpsewhich}
1711 (@pxref{Auxiliary tasks}).
1717 (Adobe font metrics, @pxref{Metric files,,, dvips, Dvips})
1725 (Metafont memory dump, @pxref{Memory dumps,,, web2c, Web2c})
1726 @code{MFBASES}, @code{TEXMFINI};
1727 suffix @samp{.base}.
1733 (Bib@TeX{} bibliography source, @pxref{bibtex invocation,,, web2c, Web2c})
1734 @code{BIBINPUTS}, @code{TEXBIB};
1739 @vindex BLTXMLINPUTS
1740 (Bib@LaTeX{}ML bibliography files for Biber, @url{http://ctan.org/pkg/biber})
1742 suffix @samp{.bltxml}.
1747 (Bib@TeX{} style, @pxref{Basic BibTeX style files,, Basic Bib@TeX{}
1748 style files, web2c, Web2c})
1756 (dynamic libraries for Lua, @url{http://ctan.org/pkg/luatex})
1758 suffixes @samp{.dll} and @samp{.so}.
1763 (character map files)
1765 suffix @samp{.cmap}.
1770 (Runtime configuration files, @pxref{Config files})
1780 suffixes @samp{.w}, @samp{.web};
1781 additional suffix @samp{.ch}.
1785 @flindex config.ps@r{, search path for}
1786 (Dvips @samp{config.*} files, such as @file{config.ps}, @pxref{Config
1787 files,,, dvips, Dvips})
1801 (@TeX{} memory dump, @pxref{Memory dumps,,, web2c, Web2c})
1802 @code{TEXFORMATS}, @code{TEXMFINI};
1812 @item font feature files
1814 @vindex FONTFEATURES
1815 (primarily for OpenType font features)
1824 (generic font bitmap, @pxref{Glyph files,,, dvips, Dvips})
1825 @code{@var{program}FONTS}, @code{GFFONTS}, @code{GLYPHFONTS}, @code{TEXFONTS};
1828 @item graphic/figure
1833 (Encapsulated PostScript figures, @pxref{PostScript figures,,, dvips, Dvips})
1834 @code{TEXPICTS}, @code{TEXINPUTS};
1835 additional suffixes: @samp{.eps}, @samp{.epsi}.
1839 @vindex TEXINDEXSTYLE
1841 (makeindex style files)
1842 @code{TEXINDEXSTYLE}, @code{INDEXSTYLE};
1848 (ligature definition files)
1855 (Filename databases, @pxref{Filename database})
1861 (Fontmaps, @pxref{Fontmap})
1869 (MetaPost memory dump, @pxref{Memory dumps,,, web2c, Web2c})
1870 @code{MPMEMS}, @code{TEXMFINI};
1873 @item @r{MetaPost support}
1875 (MetaPost support files, used by DMP; @pxref{dmp invocation,,, web2c, Web2c})
1881 (Metafont source, @pxref{mf invocation,,, web2c, Web2c})
1884 dynamic creation program: @code{mktexmf}.
1889 (Metafont program strings, @pxref{pooltype invocation,,, web2c, Web2c})
1890 @code{MFPOOL}, @code{TEXMFINI};
1891 suffix @samp{.pool}.
1896 (@code{MFT} style file, @pxref{mft invocation,,, web2c, Web2c})
1902 (font-related files that don't fit the other categories)
1910 (MlBib@TeX{} bibliography source)
1911 @code{MLBIBINPUTS}, @code{BIBINPUTS}, @code{TEXBIB};
1912 suffixes @samp{.mlbib}, @samp{.mlbib}.
1919 @code{MLBSTINPUTS}, @code{BSTINPUTS};
1920 suffixes @samp{.mlbst}, @samp{.bst}.
1925 (MetaPost source, @pxref{mpost invocation,,, web2c, Web2c})
1932 (MetaPost program strings, @pxref{pooltype invocation,,, web2c, Web2c})
1933 @code{MPPOOL}, @code{TEXMFINI};
1934 suffix @samp{.pool}.
1939 (Omega compiled process files)
1940 @code{OCPINPUTS}; @*
1942 dynamic creation program: @code{MakeOmegaOCP}.
1947 (Omega font metrics)
1948 @code{OFMFONTS}, @code{TEXFONTS}; @*
1949 suffixes @samp{.ofm}, @samp{.tfm};
1950 dynamic creation program: @code{MakeOmegaOFM}.
1952 @item opentype fonts
1953 @vindex OPENTYPEFONTS
1955 @code{OPENTYPEFONTS}.
1959 (Omega property lists)
1960 @code{OPLFONTS}, @code{TEXFONTS};
1966 (Omega translation process files)
1973 (Omega virtual fonts)
1974 @code{OVFFONTS}, @code{TEXFONTS};
1980 (Omega virtual property lists)
1981 @code{OVPFONTS}, @code{TEXFONTS};
1985 @vindex PDFTEXCONFIG
1986 (PDF@TeX{}-specific configuration files)
1987 @code{PDFTEXCONFIG}.
1995 (packed bitmap fonts, @pxref{Glyph files,,, dvips, Dvips})
1996 @code{@var{PROGRAM}FONTS} (@var{program} being @samp{XDVI}, etc.),
1997 @code{PKFONTS}, @code{TEXPKS}, @code{GLYPHFONTS}, @code{TEXFONTS};
1999 dynamic creation program: @code{mktexpk}.
2001 @item PostScript header
2003 @vindex TEXPSHEADERS
2005 (downloadable PostScript, @pxref{Header files,,, dvips, Dvips})
2006 @code{TEXPSHEADERS}, @code{PSHEADERS};
2007 additional suffix @samp{.pro}.
2012 (RIS bibliography files, primarily for Biber, @url{http://ctan.org/pkg/biber})
2016 @item subfont definition files
2019 (subfont definition files)
2026 (@TeX{} source, @pxref{tex invocation,,, web2c, Web2c})
2029 additional suffixes: none, because such a list cannot be complete;
2030 dynamic creation program: @code{mktextex}.
2032 @item TeX system documentation
2035 (Documentation files for the @TeX{} system)
2038 @item TeX system sources
2039 @flindex source files
2041 (Source files for the @TeX{} system)
2045 @vindex TEXMFSCRIPTS
2046 (Architecture-independent executables distributed in the texmf trees)
2047 @code{TEXMFSCRIPTS}.
2052 (@TeX{} program strings, @pxref{pooltype invocation,,, web2c, Web2c})
2053 @code{TEXPOOL}, @code{TEXMFINI};
2054 suffix @samp{.pool}.
2060 (@TeX{} font metrics, @pxref{Metric files,,, dvips, Dvips})
2061 @code{TFMFONTS}, @code{TEXFONTS};
2063 dynamic creation program: @code{mktextfm}.
2067 (Troff fonts, used by DMP; @pxref{DMP invocation,,, web2c, Web2c})
2070 @item truetype fonts
2074 (TrueType outline fonts) @code{TTFONTS}; suffixes @samp{.ttf} and
2075 @samp{.TTF}, @samp{.ttc} and @samp{.TTC}, @samp{.dfont}.
2082 @vindex TEXPSHEADERS
2083 @vindex DVIPSHEADERS
2084 (Type 1 PostScript outline fonts, @pxref{Glyph files,,, dvips, Dvips})
2085 @code{T1FONTS}, @code{T1INPUTS}, @code{TEXPSHEADERS}, @code{DVIPSHEADERS};
2086 suffixes @samp{.pfa}, @samp{.pfb}.
2090 (Type 42 PostScript outline fonts) @code{T42FONTS}.
2096 (virtual fonts, @pxref{Virtual fonts,,, dvips, Dvips})
2097 @code{VFFONTS}, @code{TEXFONTS};
2106 additional suffix @samp{.ch}.
2110 (files specific to the web2c implementation)
2114 There are two special cases, because the paths and environment variables
2115 always depend on the name of the program: the variable name is
2116 constructed by converting the program name to upper case, and then
2117 appending @samp{INPUTS}. Assuming the program is called @samp{foo},
2118 this gives us the following table.
2121 @item other text files
2123 (text files used by @samp{foo})
2126 @item other binary files
2128 (binary files used by @samp{foo})
2132 If an environment variable by these names are set, the corresponding
2133 @file{texmf.cnf} definition won't be looked at (unless, as usual, the
2134 environment variable value has an extra @samp{:}). @xref{Default
2137 For the font variables, the intent is that:
2140 @code{TEXFONTS} is the default for everything.
2143 @code{GLYPHFONTS} is the default for bitmap (or, more precisely,
2147 Each font format has a variable of its own.
2152 Each program has its own font override path as well; e.g.,
2153 @code{DVIPSFONTS} for Dvipsk. Again, this is for bitmaps, not metrics.
2159 @section File lookup
2162 @cindex searching for files
2163 @cindex @TeX{} file lookup
2165 This section describes how Kpathsea searches for most files (bitmap font
2166 searches are the exception, as described in the next section).
2168 Here is the search strategy for a file @var{name}:
2172 If the file format defines default suffixes, and the suffix of
2173 @var{name} name is not already a known suffix for that format, try the
2174 name with each default appended, and use alternative names found in
2175 the fontmaps if necessary. Example: given @samp{foo.bar}, look for
2179 Search for @var{name}, and if necessary for alternative names found in
2180 the fontmaps. Example: given @samp{foo.bar}, we also look for
2184 If the file format defines a program to invoke to create missing files,
2185 run it (@pxref{mktex scripts}).
2188 @cindex extensions, filename
2189 @cindex suffixes, filename
2190 @vindex try_std_extension_first
2191 The order in which we search for ``suffixed'' name (item@tie{}1) or
2192 the ``as-is'' name (item@tie{}2) is controlled by the
2193 @file{try_std_extension_first} configuration value. The default set
2194 in @file{texmf.cnf} is true, since common suffixes are already
2195 recognized: @samp{babel.sty} will only look for @samp{babel.sty}, not
2196 @samp{babel.sty.tex}, regardless of this setting.
2198 When the suffix is unknown (e.g., @samp{foo.bar}), both names are
2199 always tried; the difference is the order in which they are tried.
2201 @file{try_std_extension_first} only affects names being looked up
2202 which *already* have an extension. A name without an extension (e.g.,
2203 @samp{tex story}) will always have an extension added first.
2206 @findex kpathsea_find_file
2207 This algorithm is implemented in the function
2208 @code{kpathsea_find_file} in the source file
2209 @file{kpathsea/tex-file.c}. You can watch it in action with the
2210 debugging options (@pxref{Debugging}).
2214 @section Glyph lookup
2216 @cindex glyph lookup
2217 @cindex searching for glyphs
2218 @cindex @TeX{} glyph lookup
2220 This section describes how Kpathsea searches for a bitmap font in GF or
2221 PK format (or either) given a font name (e.g., @samp{cmr10}) and a
2222 resolution (e.g., 600).
2224 Here is an outline of the search strategy (details in the sections
2225 below) for a file @var{name} at resolution @var{dpi}. The search stops
2226 at the first successful lookup.
2230 Look for an existing file @var{name}.@var{dpi}@var{format} in the
2231 specified format(s).
2233 @item If @var{name} is an alias for a file @var{f} in the fontmap
2234 file @file{texfonts.map}, look for @var{f}.@var{dpi}.
2236 @item Run an external program (typically named @samp{mktexpk}) to
2237 generate the font (@pxref{mktex scripts})
2239 @item Look for @var{fallback}.@var{dpi}, where @var{fallback} is some
2240 last-resort font (typically @samp{cmr10}).
2243 @flindex tex-glyph.c
2244 @findex kpathsea_find_glyph
2245 This is implemented in @code{kpathsea_find_glyph} in
2246 @file{kpathsea/tex-glyph.c}.
2249 * Basic glyph lookup:: Features common to all glyph lookups.
2250 * Fontmap:: Aliases for fonts.
2251 * Fallback font:: Resolutions and fonts of last resort.
2255 @node Basic glyph lookup
2256 @subsection Basic glyph lookup
2258 @cindex basic glyph lookup
2259 @cindex common features in glyph lookup
2261 When Kpathsea looks for a bitmap font @var{name} at resolution @var{dpi}
2262 in a format @var{format}, it first checks each directory in the search
2263 path for a file @samp{@var{name}.@var{dpi}@var{format}}; for example,
2264 @samp{cmr10.600pk}. Kpathsea looks for a PK file first, then a GF file.
2266 If that fails, Kpathsea looks for
2267 @samp{dpi@var{dpi}/@var{name}.@var{format}}; for example,
2268 @samp{dpi600/cmr10.pk}. This is how fonts are typically stored on
2269 filesystems (such as DOS) that permit only three-character extensions.
2271 @cindex tolerance for glyph lookup
2272 @cindex glyph lookup bitmap tolerance
2273 @findex KPSE_BITMAP_TOLERANCE
2274 If that fails, Kpathsea looks for a font with a close-enough @var{dpi}.
2275 ``Close enough'' is defined by the macro @code{KPSE_BITMAP_TOLERANCE} in
2276 @file{kpathsea/tex-glyph.h} to be @code{@var{dpi} / 500 + 1}. This is
2277 slightly more than the 0.2% minimum allowed by the DVI standard
2278 (@url{@var{CTAN:}/dviware/driv-standard/level-0}).
2284 @cindex fontmap files
2285 @cindex font alias files
2286 @cindex aliases for fonts
2288 @flindex texfonts.map
2289 If a bitmap font or metric file is not found with the original name (see
2290 the previous section), Kpathsea looks through any @dfn{fontmap} files
2291 for an @dfn{alias} for the original font name. These files are named
2292 @file{texfonts.map} and searched for along the @code{TEXFONTMAPS}
2293 environment/config file variable. All @file{texfonts.map} files that
2294 are found are read; earlier definitions override later ones.
2296 This feature is intended to help in two respects:
2301 @cindex fontnames, arbitrary length
2302 An alias name is limited in length only by available memory, not by your
2303 filesystem. Therefore, if you want to ask for @samp{Times-Roman}
2304 instead of @file{ptmr}, you can (you get @samp{ptmr8r}).
2307 @cindex circle fonts
2309 A few fonts have historically had multiple names: specifically,
2310 La@TeX{}'s ``circle font'' has variously been known as @file{circle10},
2311 @file{lcircle10}, and @file{lcirc10}. Aliases can make all the names
2312 equivalent, so that it no longer matters what the name of the installed
2313 file is; @TeX{} documents will find their favorite name.
2317 The format of fontmap files is straightforward:
2320 @cindex comments, in fontmap files
2321 @item Comments start with @samp{%} and continue to the end of the line.
2322 @cindex whitespace, in fontmap files
2323 @item Blank lines are ignored.
2324 @item Each nonblank line is broken up into a series of @dfn{words}:
2325 a sequence of non-whitespace characters.
2326 @findex include @r{fontmap directive}
2327 @item If the first word is @samp{include}, the second word is used as
2328 a filename, and it is searched for and read.
2329 @item Otherwise, the first word on each line is the true filename;
2330 @item the second word is the alias;
2331 @item subsequent words are ignored.
2334 If an alias has an extension, it matches only those files with that
2335 extension; otherwise, it matches anything with the same root, regardless
2336 of extension. For example, an alias @samp{foo.tfm} matches only when
2337 @file{foo.tfm} is being searched for; but an alias @samp{foo} matches
2338 @file{foo.vf}, @file{foo.600pk}, etc.
2340 As an example, here is an excerpt from the @file{texfonts.map} in the
2341 Web2c distribution. It makes the old and new names of the @LaTeX{}
2342 circle fonts equivalent.
2354 Fontmaps are implemented in the file @file{kpathsea/fontmap.c}.
2355 The Fontname distribution has much more information on font naming
2356 (@pxref{,,,fontname, Filenames for @TeX{} fonts}).
2360 @subsection Fallback font
2362 @cindex fallback font
2363 @cindex fallback resolutions
2364 @cindex font of last resort
2365 @cindex resolutions, last-resort
2366 @cindex last-resort font
2372 @vindex default_texsizes
2373 If a bitmap font cannot be found or created at the requested size,
2374 Kpathsea looks for the font at a set of @dfn{fallback resolutions}. You
2375 specify these resolutions as a colon-separated list (like search paths).
2376 Kpathsea looks first for a program-specific environment variable (e.g.,
2377 @code{DVIPSSIZES} for Dvipsk), then the environment variable
2378 @code{TEXSIZES}, then a default specified at compilation time (the Make
2379 variable @code{default_texsizes}). You can set this list to be empty if
2380 you prefer to find fonts at their stated size or not at all.
2382 @flindex cmr10@r{, as fallback font}
2383 @findex kpathsea_init_prog
2384 Finally, if the font cannot be found even at the fallback resolutions,
2385 Kpathsea looks for a fallback font, typically @file{cmr10}. Programs
2386 must enable this feature by calling @code{kpathsea_init_prog}
2387 (@pxref{Calling sequence}); the default is no fallback font.
2390 @node Suppressing warnings
2391 @section Suppressing warnings
2393 @cindex warnings, suppressing
2394 @cindex suppressing warnings
2397 Kpathsea provides a way to suppress selected usually-harmless warnings;
2398 this is useful at large sites where most users are not administrators,
2399 and thus the warnings are merely a source of confusion, not a help. To
2400 do this, you set the environment variable or configuration file value
2401 @code{TEX_HUSH} to a colon-separated list of values. Here are the
2406 Suppress everything possible.
2409 @cindex mismatched checksum warnings
2410 Suppress mismatched font checksum warnings.
2413 @cindex missing character warnings
2414 Suppress warnings when a character is missing from a font that a DVI or
2415 VF file tries to typeset.
2418 Don't suppress any warnings.
2421 @cindex unreadable file warnings
2422 Suppress warnings about attempts to access a file whose permissions
2423 render it unreadable.
2426 @cindex unknown special warnings
2427 @findex \special@r{, suppressing warnings about}
2428 Suppresses warnings about an unimplemented or unparsable
2429 @samp{\special} command.
2432 @noindent @file{tex-hush.c} defines the function that checks the
2433 variable value. Each driver implements its own checks where
2438 @section @file{mktex} scripts
2440 @cindex @file{mktex} scripts
2441 @cindex scripts for file creation
2443 @cindex font set, infinite
2444 @cindex dynamic creation of files
2445 @cindex Sauter fonts, and dynamic source creation
2446 @cindex EC fonts, and dynamic source creation
2447 If Kpathsea cannot otherwise find a file, for some file types it is
2448 configured by default to invoke an external program to create it
2449 dynamically (@pxref{mktex configuration}). These are collectively
2450 known as @dfn{@code{mktex} scripts}, since most of them are named
2453 For example, this is useful for fonts (bitmaps, TFM's, and
2454 arbitrarily-sizable Metafont sources such as the Sauter and EC fonts),
2455 since any given document can use fonts never before referenced.
2456 Building all fonts in advance is therefore impractical, if not
2459 It is also useful for the @TeX{} @samp{.fmt} (and Metafont
2460 @samp{.base} and Metapost @samp{.mem} files, @pxref{Memory
2461 dumps,,,Web2c,web2c}), where pre-generating every format consumes a
2462 lot of both time and space.
2464 The script is passed the name of the file to create and possibly other
2465 arguments, as explained below. It must echo the full pathname of the
2466 file it created (and nothing else) to standard output; it can write
2467 diagnostics to standard error.
2470 * config: mktex configuration.
2471 * names: mktex script names.
2472 * args: mktex script arguments.
2476 @node mktex configuration
2477 @subsection @file{mktex} configuration
2479 @cindex @file{mktex} script configuration
2480 @cindex configuration of @file{mktex} scripts
2481 @cindex enabling @file{mktex} scripts
2482 @cindex disabling @file{mktex} scripts
2484 The list of file types and program names that can run an external
2485 program to create missing files is listed in the next section. In the
2486 absence of @code{configure} options specifying otherwise, everything
2487 but @file{mktextex} will be enabled by default. The @code{configure}
2488 options to change the defaults are:
2490 @cindex @code{configure} options for @file{mktex} scripts
2491 @opindex --without-mktexfmt-default
2492 @opindex --without-mktexmf-default
2493 @opindex --without-mktexocp-default
2494 @opindex --without-mktexofm-default
2495 @opindex --without-mktexpk-default
2496 @opindex --without-mktextfm-default
2497 @opindex --with-mktextex-default
2499 --without-mktexfmt-default
2500 --without-mktexmf-default
2501 --without-mktexocp-default
2502 --without-mktexofm-default
2503 --without-mktexpk-default
2504 --without-mktextfm-default
2505 --with-mktextex-default
2508 The @code{configure} setting is overridden if the environment variable
2509 or configuration file value named for the script is set; e.g.,
2510 @file{MKTEXPK} (@pxref{mktex script arguments}).
2512 @flindex fmtutils.cnf
2513 @code{mktexfmt} reads a file @file{fmtutil.cnf}, typically located in
2514 @file{texmf/web2c/} to glean its configuration information. The rest
2515 of the files and features in this section are primarily intended for
2516 the font generation scripts.
2520 @cindex site overrides for @code{mktex@dots{}}
2521 As distributed, all the scripts source a file
2522 @file{texmf/web2c/mktex.cnf} if it exists, so you can override various
2524 See @file{mktex.opt}, for instance, which defines the default mode,
2525 resolution, some special directory names, etc. If you prefer not to
2526 change the distributed scripts, you can simply create @file{mktex.cnf}
2527 with the appropriate definitions (you do not need to create it if you
2528 have nothing to put in it). @file{mktex.cnf} has no special syntax;
2529 it's an arbitrary Bourne shell script. The distribution contains a
2530 sample @file{mktex.cnf} for you to copy and modify as you please (it
2531 is not installed anywhere).
2535 In addition, you can configure a number of features with the
2536 @code{MT_FEATURES} variable, which you can define:
2540 in @file{mktex.opt}, as just mentioned;
2543 by editing the file @file{mktex.opt}, either before @samp{make
2544 install} (in the source hierarchy) or after (in the installed
2548 or in the environment.
2551 If none of the options below are enabled, @code{mktexpk},
2552 @code{mktextfm}, and @code{mktexmf} follow the following procedure to
2553 decide where fonts should be installed. Find the tree where the font's
2554 sources are, and test the permissions of the @samp{fonts} directory of
2555 that tree to determine whether it is writable. If it is, put the files
2556 in the tree in appropriate locations. If it isn't writable, see whether
2557 the tree is a system tree (named in @code{SYSTEXMF}). If so, the
2558 @code{VARTEXFONTS} tree is used. In all other cases the working
2561 The @samp{appendonlydir} option is enabled by default.
2565 @cindex directories, making append-only
2567 Tell @code{mktexdir} to create directories append-only, i.e., set
2568 their sticky bit (@pxref{Mode Structure,,, coreutils, GNU Core
2569 Utilities}). This feature is silently ignored on non-Unix platforms
2570 (e.g. Windows/NT and MS-DOS) which don't support similar functionality.
2571 This feature is enabled by default.
2574 @cindex 8.3 filenames, using
2575 @cindex DOS compatible names
2576 @flindex dpi@var{nnn} directories
2577 Use 8.3 names; e.g., @file{dpi600/cmr10.pk} instead of
2578 @file{cmr10.600pk}. Note that this feature only affects filenames that
2579 would otherwise clash with other TeX-related filenames; @file{mktex}
2580 scripts do nothing about filenames which exceed the 8+3 MS-DOS limits
2581 but remain unique when truncated (by the OS) to these limits, and nether
2582 do the scripts care about possible clashes with files which aren't
2583 related with TeX. For example, @file{cmr10.600pk} would clash with
2584 @file{cmr10.600gf} and is therefore changed when @samp{dosnames} is in
2585 effect, but @file{mf.pool} and @file{mp.base} don't clash with any
2586 TeX-related files and are therefore unchanged.
2588 This feature is turned on by default on MS-DOS. If you do not wish
2589 @samp{dosnames} to be set on an MS-DOS platform, you need to set the
2590 @code{MT_FEATURES} environment variable to a value that doesn't include
2591 @samp{dosnames}. You can also change the default setting by editing
2592 @file{mktex.opt}, but only if you use the @file{mktex} shell scripts;
2593 the emulation programs don't consult @file{mktex.opt}.
2598 Instead of deriving the location of a font in the destination tree from
2599 the location of the sources, the aliases and directory names from the
2600 Fontname distribution are used. (@pxref{Top,, Introduction, fontname,
2604 @cindex metafont driver files
2605 Let mktexpk and mktextfm create metafont driver files in a temporary
2606 directory. These will be used for just one metafont run and not
2607 installed permanently.
2610 @cindex mode directory, omitting
2611 Omit the directory level for the mode name; this is fine as long as
2612 you generate fonts for only one mode.
2615 @cindex supplier directory, omitting
2616 Omit the font supplier name directory level.
2619 @cindex typeface directory, omitting
2620 Omit the font typeface name directory level.
2623 @cindex supplier directory, omitting
2624 @cindex typeface directory, omitting
2625 Omit the font supplier and typeface name directory levels. This feature
2626 is deprecated in favour of @samp{stripsupplier} and @samp{striptypeface}.
2629 @flindex /var/tmp/texfonts
2631 @cindex Linux File System Standard
2632 When this option is enabled, fonts that would otherwise be written in
2633 system texmf tree go to the @code{VARTEXFONTS} tree instead. The
2634 default value in @file{kpathsea/Makefile.in} is
2635 @file{/var/tmp/texfonts}. The @cite{Linux File System Standard}
2636 recommends @file{/var/tex/fonts}.
2638 @vindex USE_VARTEXFONTS
2639 The @samp{varfonts} setting in @code{MT_FEATURES} is overridden by the
2640 @code{USE_VARTEXFONTS} environment variable: if set to @samp{1}, the
2641 feature is enabled, and if set to @samp{0}, the feature is disabled.
2645 Force generated files that would go into a system tree (as defined by
2646 @code{SYSTEXMF}) into @code{TEXMFVAR}. Starting with te@TeX{}-3.0, the
2647 variable @code{TEXMFVAR} is always set. The @samp{varfonts} feature takes
2648 precedence if also set.
2650 @vindex USE_TEXMFVAR
2651 The @samp{texmfvar} setting in @code{MT_FEATURES} is overridden by the
2652 @code{USE_TEXMFVAR} environment variable: if set to @samp{1}, the
2653 feature is enabled, and if set to @samp{0}, the feature is disabled.
2657 @node mktex script names
2658 @subsection @file{mktex} script names
2660 @cindex @file{mktex} script names
2661 @cindex names for @file{mktex} scripts
2663 The following table shows the default name of the script for each
2664 of the file types which support runtime generation.
2670 (@samp{.fmt}, @samp{.base}, @samp{.mem}) @TeX{}/Metafont/MetaPost
2671 formats. This script is also named @command{fmtutil}, and reads
2672 @file{fmtutil.cnf} for configuration information.
2676 (@samp{.mf}) Metafont input files.
2680 (@samp{.ocp}) Omega compiled process files.
2684 (@samp{.ofm}) Omega font metric files.
2688 (@samp{pk}) Glyph fonts.
2692 (@samp{.tex}) @TeX{} input files (disabled by default).
2696 (@samp{.tfm}) TFM files.
2702 @noindent These names can be overridden by an environment variable specific
2703 to the program---for example, @code{DVIPSMAKEPK} for Dvipsk.
2705 @comment next two paragraphs are repeated in dvips.texi
2706 @flindex missfont.log
2707 @cindex failed @code{mktex@dots{}} script invocation
2708 If a @code{mktex@dots{}} script fails, the invocation is appended to a
2709 file @file{missfont.log} (by default) in the current directory. You can
2710 then execute the log file to create the missing files after fixing the
2714 @vindex MISSFONT_LOG
2715 If the current directory is not writable and the environment variable or
2716 configuration file value @code{TEXMFOUTPUT} is set, its value is
2717 used. Otherwise, nothing is written. The name @samp{missfont.log} is
2718 overridden by the @code{MISSFONT_LOG} environment variable or
2719 configuration file value.
2722 @node mktex script arguments
2723 @subsection @file{mktex} script arguments
2725 @cindex arguments to @file{mktex}
2727 The first argument to a @file{mktex} script is always the name
2728 of the file to be created.
2730 In the default @file{mktexpk} implementation, additional arguments may
2734 @item --dpi @var{num}
2735 Sets the resolution of the generated font to @var{num}.
2736 @item --mfmode @var{name}
2737 Sets the Metafont mode to @var{name}.
2738 @item --bdpi @var{num}
2739 Sets the ``base dpi'' for the font. This must match the mode being
2741 @item --mag @var{string}
2742 A ``magstep'' string suitable for the Metafont @code{mag} variable.
2743 This must match the combination of @var{bdpi} and @var{dpi} being used.
2744 @item --destdir @var{string}
2745 A directory name. If the directory is absolute, it is used as-is.
2746 Otherwise, it is appended to the root destination directory set in the
2753 @chapter Programming
2755 This chapter is for programmers who wish to use Kpathsea.
2756 @xref{Introduction}, for the conditions under which you may do so.
2759 * Overview: Programming overview. Introduction.
2760 * Calling sequence:: Specifics of what to call.
2761 * Program-specific files:: How to handle these.
2762 * Config: Programming with config files. Getting info from texmf.cnf.
2766 @node Programming overview
2767 @section Programming overview
2769 @cindex programming overview
2770 @cindex overview of programming with Kpathsea
2772 Aside from this manual, your best source of information is the source
2773 to the programs that use Kpathsea (@pxref{Introduction}). Of those,
2774 Dviljk is probably the simplest, and hence a good place to start.
2775 Xdvik adds VF support and the complication of X resources. Dvipsk
2776 adds the complication of its own config files. Web2c is source code I
2777 also maintain, so it uses Kpathsea rather straightforwardly, but is of
2778 course complicated by the Web to C translation. Finally, Kpsewhich is
2779 a small utility program whose sole purpose is to exercise the main
2780 path-searching functionality.
2782 @cindex re-entrant API
2783 @cindex API, re-entrant
2784 When looking at these program sources, you should know that previous
2785 versions of the library had a different programming interface, to
2786 support re-entrancy. In that interface the library function names
2787 were prefixed with @code{kpse_} instead of @code{kpathsea_}, and they
2788 did not need an instance variable as first argument. This change was
2789 made in 2009. Some of the programs mentioned above may still be using
2790 the previous interface.
2792 @flindex pathsearch.h
2794 @flindex tex-glyph.h
2796 Beyond these examples, the @file{.h} files in the Kpathsea source
2797 describe the interfaces and functionality (and of course the @file{.c}
2798 files define the actual routines, which are the ultimate documentation).
2799 @file{pathsearch.h} declares the basic searching routine.
2800 @file{tex-file.h} and @file{tex-glyph.h} define the interfaces for
2801 looking up particular kinds of files. In view of the way the headers
2802 depend on each other, it is recommended to use @code{#include
2803 <kpathsea/kpathsea.h>}, which includes every Kpathsea header.
2807 If you want to include only specific headers, you should still consider
2808 including @file{kpathsea/config.h} before including any other Kpathsea
2809 header, as it provides symbols used in the other headers. Note that
2810 @file{kpathsea/config.h} includes @file{kpathsea/c-auto.h}, which is
2811 generated by Autoconf.
2813 @cindex file types, registering new
2814 The library provides no way for an external program to register new file
2815 types: @file{tex-file.[ch]} must be modified to do this. For example,
2816 Kpathsea has support for looking up Dvips config files, even though no
2817 program other than Dvips will likely ever want to do so. I felt this
2818 was acceptable, since along with new file types should also come new
2819 defaults in @file{texmf.cnf} (and its descendant @file{paths.h}), since
2820 it's simplest for users if they can modify one configuration file for
2823 Kpathsea does not parse any formats itself; it barely opens any files.
2824 Its primary purpose is to return filenames. The GNU font utilities does
2825 contain libraries to read TFM, GF, and PK files, as do the programs
2829 @node Calling sequence
2830 @section Calling sequence
2832 @cindex programming with Kpathsea
2833 @cindex calling sequence
2835 The typical way to use Kpathsea in your program goes something like this:
2840 @findex kpathsea_new
2841 Call @code{kpathsea_new} to create a new library instance. This variable
2842 must be passed as the first argument to all the following library functions.
2843 The rest of this manual will be using @code{kpse} as a placeholder for
2844 the name of this variable.
2847 @findex kpathsea_set_program_name
2849 Call @code{kpathsea_set_program_name} with @code{argv[0]} as the second
2850 argument; the third argument is a string or @code{NULL}. The third
2851 argument is used by Kpathsea as the program name for the
2852 @code{.@var{program}} feature of config files (@pxref{Config files}).
2853 If the third argument is @code{NULL}, the value of the second argument
2854 is used. This function must be called before any other use of the
2857 @vindex kpse->invocation_name
2858 @vindex kpse->invocation_short_name
2859 @vindex kpse->program_name
2860 @cindex error message macros
2861 @code{kpathsea_set_program_name} always sets the variables
2862 @code{kpse->invocation_name} and @code{kpse->invocation_short_name}.
2863 These variables are used in the error message macros defined in
2864 @file{kpathsea/lib.h}. It sets the variable
2865 @code{kpse->program_name} to the program name it uses.
2867 @vindex KPATHSEA_DEBUG
2868 It also initializes debugging options based on the environment
2869 variable @code{KPATHSEA_DEBUG} (if that is set).
2873 @cindex SELFAUTOPARENT
2874 @cindex symlinks, resolving
2875 @cindex expanding symlinks
2876 Finally, it sets the environment variables @code{SELFAUTOLOC}, @code{SELFAUTODIR}
2877 and @code{SELFAUTOPARENT} to the location, parent and grandparent
2878 directory of the executable, removing @file{.} and @file{..} path
2879 elements and resolving symbolic links. These are used in the default
2880 configuration file to allow people to invoke TeX from anywhere. You
2881 can use @samp{kpsewhich --expand-var=\$SELFAUTOLOC}, etc., to see the
2885 @vindex kpse->debug @r{variable}
2886 @cindex debugging options, in Kpathsea-using program
2887 Set debugging options. @xref{Debugging}. If your program doesn't have a
2888 debugging option already, you can define one and set
2889 @code{kpse->debug} to the number that the user supplies (as in Dviljk
2890 and Web2c), or you can just omit this altogether (people can always set
2891 @code{KPATHSEA_DEBUG}). If you do have runtime debugging already, you
2892 need to merge Kpathsea's options with yours (as in Dvipsk and Xdvik).
2895 @vindex client_path @r{in @code{kpse->format_info}}
2896 @vindex kpse->format_info
2898 @cindex config files, for Kpathsea-using programs
2899 If your program has its own configuration files that can define search
2900 paths, you should assign those paths to the @code{client_path} member in
2901 the appropriate element of the @code{kpse->format_info} array. (This
2902 array is indexed by file type; see @file{tex-file.h}.) See
2903 @file{resident.c} in Dvipsk for an example.
2906 @findex kpathsea_init_prog
2908 Call @code{kpathsea_init_prog} (see @file{proginit.c}). It's useful for the
2909 DVI drivers, at least, but for other programs it may be simpler to
2910 extract the parts of it that actually apply. This does not initialize
2911 any paths, it just looks for (and sets) certain environment variables
2912 and other random information. (A search path is always initialized at
2913 the first call to find a file of that type; this eliminates much useless
2914 work, e.g., initializing the Bib@TeX{} search paths in a DVI driver.)
2917 @findex kpathsea_find_file
2918 The routine to actually find a file of type @var{format} is
2919 @file{kpathsea_find_file}. You can call
2920 @code{kpathsea_find_file} after doing only the first and second of the
2921 initialization steps above---Kpathsea automatically reads the
2922 @file{texmf.cnf} generic config files, looks for environment variables,
2923 and does expansions at the first lookup.
2926 To find PK and/or GF bitmap fonts, the routine
2927 is @code{kpathsea_find_glyph}, defined in
2928 @file{tex-glyph.h}. This returns a structure in addition to the
2929 resultant filename, because fonts can be found in so many ways. See the
2930 documentation in the source.
2933 @findex kpathsea_open_file
2934 To actually open a file, not just return a filename, call
2935 @code{kpathsea_open_file}. This function takes the name to look up and a
2936 Kpathsea file format as arguments, and returns the usual @code{FILE *}.
2937 It always assumes the file must exist, and thus will search the disk if
2938 necessary (unless the search path specified @samp{!!}, etc.). In other
2939 words, if you are looking up a VF or some other file that need not
2940 exist, don't use this.
2943 @findex kpathsea_out_name_ok
2944 @TeX{} can write output files, via the @code{\openout} primitive; this opens
2945 a security hole vulnerable to Trojan horse attack: an unwitting user could
2946 run a @TeX{} program that overwrites, say, @file{~/.rhosts}. Analogous
2947 security holes exist for many other programs. To alleviate this, there is a
2948 configuration variable @code{openout_any}, which selects one of three levels
2949 of security. When it is set to @samp{a} (for ``any''), no restrictions are
2950 imposed. When it is set to @samp{r} (for ``restricted''), filenames
2951 beginning with @samp{.} are disallowed (except @file{.tex} because @LaTeX{}
2952 needs it). When it is set to @samp{p} (for ``paranoid'') additional
2953 restrictions are imposed: an absolute filename must refer to a file in (a
2954 subdirectory) of @code{TEXMFOUTPUT}, and any attempt to go up a directory
2955 level is forbidden (that is, paths may not contain a @samp{..} component).
2956 The paranoid setting is the default. (For backwards compatibility, @samp{y}
2957 and @samp{1} are synonyms of @samp{a}, while @samp{n} and @samp{0} are
2958 synonyms for @samp{r}.) The function @code{kpathsea_out_name_ok}, with a
2959 filename as second argument, returns @code{true} if that filename is
2960 acceptable to be opend for output or @code{false} otherwise.
2963 @findex kpathsea_in_name_ok
2964 Similarly, the function @code{kpathsea_in_name_ok}, with a filename as
2965 second argument, returns @code{true} if that filename is acceptable to be
2966 opend for input or @code{false} otherwise, depending on the value of the
2967 configuration variable @code{openin_any} (with @samp{a} as default).
2970 @findex kpathsea_finish
2971 To close the kpathsea library instance you are using, call
2972 @code{kpathsea_finish}. This function closes any open log files and
2973 frees the memory used by the instance.
2977 @cindex hash table routines
2978 @cindex memory allocation routines
2979 @cindex string routines
2980 @cindex reading arbitrary-length lines
2981 @cindex input lines, reading
2982 @cindex lines, reading arbitrary-length
2983 Kpathsea also provides many utility routines. Some are generic: hash
2984 tables, memory allocation, string concatenation and copying, string
2985 lists, reading input lines of arbitrary length, etc. Others are
2986 filename-related: default path, tilde, and variable expansion,
2987 @code{stat} calls, etc. (Perhaps someday I'll move the former to a
2991 @pindex autoconf@r{, recommended}
2992 The @file{c-*.h} header files can also help your program adapt to many
2993 different systems. You will almost certainly want to use Autoconf and
2994 probably Automake for configuring and building your software if you use
2995 Kpathsea; I strongly recommend using Autoconf and Automake regardless.
2996 They are available from @url{http://www.gnu.org/software}.
2999 @node Program-specific files
3000 @section Program-specific files
3002 Many programs will need to find some configuration files. Kpathsea
3003 contains some support to make it easy to place them in their own
3004 directories. The Standard @TeX{} directory structure (@pxref{Top,,
3005 Introduction, tds, A Directory Structure for @TeX{} files}), specifies
3006 that such files should go into a subdirectory named after the program,
3007 like @samp{texmf/ttf2pk}.
3009 Two formats, @samp{kpse_program_text_format} and
3010 @samp{kpse_program_binary_format}, use @code{.:$TEXMF/@var{program}//}
3011 as their compiled-in search path. To override this default, you can
3012 use the variable @code{@var{PROGRAM}INPUTS} in the environment and/or
3013 @samp{texmf.cnf}. That is to say, the name of the variable is
3014 constructed by converting the name of the program to upper case, and
3015 appending @code{INPUTS}.
3017 The only difference between these two formats is whether
3018 @code{kpathsea_open_file} will open the files it finds in text or binary
3022 @node Programming with config files
3023 @section Programming with config files
3025 @cindex programming with config files
3026 @cindex config files, programming with
3028 You can (and probably should) use the same @code{texmf.cnf}
3029 configuration file that Kpathsea uses for your program. This helps
3030 installers by keeping all configuration in one place.
3032 @findex kpathsea_var_value
3034 @vindex shell_escape@r{, example for code}
3035 To retrieve a value @var{var} from config files, the best way is to call
3036 @code{kpathsea_var_value} on the string @code{@var{var}}. This will look
3037 first for an environment variable @var{var}, then a config file value.
3038 The result will be the value found or @samp{NULL}. This function is
3039 declared in @file{kpathsea/variable.h}. For an example, see the
3040 @code{shell_escape} code in @file{web2c/lib/texmfmp.c}.
3042 The routine to do variable expansion in the context of a search path (as
3043 opposed to simply retrieving a value) is @code{kpathsea_var_expand}, also
3044 declared in @file{kpathsea/variable.h}. It's generally only necessary
3045 to set the search path structure components as explained in the previous
3046 section, rather than using this yourself.
3048 @findex kpathsea_cnf_get
3050 If for some reason you want to retrieve a value @emph{only} from a
3051 config file, not automatically looking for a corresponding environment
3052 variable, call @code{kpathsea_cnf_get} (declared in @file{kpathsea/cnf.h})
3053 with the string @var{var}.
3055 No initialization calls are needed.
3058 @node Reporting bugs
3059 @chapter Reporting bugs
3061 @cindex reporting bugs
3062 @cindex bugs, reporting
3064 @flindex tex-k@@tug.org @r{(bug address)}
3066 If you have problems or suggestions, please report them to
3067 @email{tex-k@@tug.org} using the bug checklist below.
3069 Please report bugs in the documentation; not only factual errors or
3070 inconsistent behavior, but unclear or incomplete explanations, typos,
3071 wrong fonts, @dots{}
3074 * Bug checklist:: What to include in a good bug report.
3075 * Mailing lists:: Joining the bugs or announcements mailing lists.
3076 * Debugging:: Analyzing runtime problems.
3077 * Logging:: Recording searches.
3078 * Common problems:: When things go wrong.
3083 @section Bug checklist
3085 @cindex checklist for bug reports
3086 @cindex bug checklist
3088 Before reporting a bug, please check below to be sure it isn't already
3089 known (@pxref{Common problems}).
3091 Bug reports should be sent via electronic mail to
3092 @email{tex-k@@tug.org}.
3094 The general principle is that a good bug report includes all the
3095 information necessary for reproduction. Therefore, to enable
3096 investigation, your report should include the following:
3100 @cindex version numbers, determining
3101 The version number(s) of the program(s) involved, and of Kpathsea
3102 itself. You can get the former by giving a sole option @samp{--version}
3103 to the program, and the latter by running @samp{kpsewhich --version}.
3104 The @file{NEWS} and @file{ChangeLog} files also contain the version
3109 The hardware, operating system (including version), compiler, and
3110 @code{make} program you are using (the output of @code{uname -a} is a
3111 start on the first two, though incomplete).
3115 Any options you gave to @code{configure}. This is recorded in the
3116 @file{config.status} files.
3118 @cindex configuration bugs
3119 @flindex config.status
3120 If you are reporting a bug in @samp{configure} itself, it's probably
3121 system-dependent, and it will be unlikely the maintainers can do
3122 anything useful if you merely report that thus-and-such is broken.
3123 Therefore, you need to do some additional work: for some bugs, you can
3124 look in the file @file{config.log} where the test that failed should
3125 appear, along with the compiler invocation and source program in
3126 question. You can then compile it yourself by hand, and discover why
3127 the test failed. Other @samp{configure} bugs do not involve the
3128 compiler; in that case, the only recourse is to inspect the
3129 @code{configure} shell script itself, or the Autoconf macros that
3130 generated @code{configure}.
3133 The log of all debugging output, if the bug is in path searching. You
3134 can get this by setting the environment variable @code{KPATHSEA_DEBUG}
3135 to @samp{-1} before running the program. Please look at the log
3136 yourself to make sure the behavior is really a bug before reporting it;
3137 perhaps ``old'' environment variable settings are causing files not to
3138 be found, for example.
3141 The contents of any input files necessary to reproduce the bug. For
3142 bugs in DVI-reading programs, for example, this generally means a DVI
3143 file (and any EPS or other files it uses)---@TeX{} source files are
3144 helpful, but the DVI file is required, because that's the actual
3148 @cindex context diff
3149 @cindex sending patches
3150 @flindex ChangeLog @r{entry}
3151 If you are sending a patch (do so if you can!), please do so in the form
3152 of a context diff (@samp{diff -c}) against the original distribution
3153 source. Any other form of diff is either not as complete or harder for
3154 me to understand. Please also include a @file{ChangeLog} entry.
3159 @cindex crashes, reporting
3160 @cindex core dumps, reporting
3161 @cindex null pointers, dereferencing
3162 @pindex gdb@r{, recommended}
3163 If the bug involved is an actual crash (i.e., core dump), it is easy
3164 and useful to include a stack trace from a debugger (I recommend the
3165 GNU debugger GDB (@url{http://www.gnu.org/software/gdb}). If the
3166 cause is apparent (a @code{NULL} value being dereferenced, for
3167 example), please send the details along. If the program involved is
3168 @TeX{} or Metafont, and the crash is happening at apparently-sound
3169 code, however, the bug may well be in the compiler, rather than in the
3170 program or the library (@pxref{TeX or Metafont failing,, @TeX{} or
3174 Any additional information that will be helpful in reproducing,
3175 diagnosing, or fixing the bug.
3180 @section Mailing lists
3182 @cindex mailing lists
3183 @cindex bug mailing list
3184 @cindex announcement mailing list
3186 @flindex tex-k@@tug.org
3187 Web2c and Kpathsea in general are discussed on the mailing list
3188 @email{tex-k@@tug.org}. You can subscribe and peruse the archives on
3189 the web @url{http://lists.tug.org/tex-k}.
3191 You do not need to join to submit a report, nor will it affect whether
3192 you get a response. Be aware that large data files are sometimes
3193 included in bug reports. If this is a problem for you, do not join
3196 If you are looking for general @TeX{} help, such as how to install a
3197 full @TeX{} system or how to use @LaTeX{}, please see
3198 @url{http://tug.org/begin.html}.
3205 @cindex runtime debugging
3206 @cindex options for debugging
3210 Kpathsea provides a number of runtime debugging options, detailed below
3211 by their names and corresponding numeric values. When the files you
3212 expect aren't being found, the thing to do is enable these options and
3215 You can set these with some runtime argument (e.g., @samp{-d}) to the
3216 program; in that case, you should use the numeric values described in
3217 the program's documentation (which, for Dvipsk and Xdvik, are different
3218 than those below). It's best to give the @samp{-d} (or whatever) option
3219 first, for maximal output. Dvipsk and Xdvik have additional
3220 program-specific debugging options as well.
3222 @vindex KPATHSEA_DEBUG
3224 You can also set the environment variable @code{KPATHSEA_DEBUG}; in this
3225 case, you should use the numbers below. If you run the program under a
3226 debugger and set the instance variable @code{kpse->debug}, also use the numbers
3229 @kindex -1 @r{debugging value}
3230 In any case, by far the simplest value to use is @samp{-1}, which will
3231 turn on all debugging output. This is usually better than guessing
3232 which particular values will yield the output you need.
3234 @cindex debugging output
3235 @cindex standard error and debugging output
3236 Debugging output always goes to standard error, so you can redirect it
3237 easily. For example, in Bourne-compatible shells:
3239 dvips -d -1 @dots{} 2>/tmp/debug
3242 @cindex Kpsewhich, and debugging
3243 It is sometimes helpful to run the standalone Kpsewhich utility
3244 (@pxref{Invoking kpsewhich}), instead of the original program.
3246 @cindex numeric debugging values
3247 In any case, you cannot use the names below; you must always use
3248 somebody's numbers. (Sorry.) To set more than one option, just sum
3249 the corresponding numbers.
3252 @item KPSE_DEBUG_STAT @r{(1)}
3253 Report @samp{stat}(2) calls. This is useful for verifying that your
3254 directory structure is not forcing Kpathsea to do many additional file
3255 tests (@pxref{Slow path searching}, and @pxref{Subdirectory
3256 expansion}). If you are using an up-to-date @file{ls-R} database
3257 (@pxref{Filename database}), this should produce no output unless a
3258 nonexistent file that must exist is searched for.
3260 @item KPSE_DEBUG_HASH @r{(2)}
3261 Report lookups in all hash tables: @file{ls-R} and @file{aliases}
3262 (@pxref{Filename database}); font aliases (@pxref{Fontmap}); and config
3263 file values (@pxref{Config files}). Useful when expected values are not
3264 being found, e.g.., file searches are looking at the disk instead of
3267 @item KPSE_DEBUG_FOPEN @r{(4)}
3268 @findex fopen@r{, redefined}
3269 Report file openings and closings. Especially useful when your system's
3270 file table is full, for seeing which files have been opened but never
3271 closed. In case you want to set breakpoints in a debugger: this works by
3272 redefining @samp{fopen} (@samp{fclose}) to be @samp{kpse_fopen_trace}
3273 (@samp{kpse_fclose_trace}).
3275 @item KPSE_DEBUG_PATHS @r{(8)}
3276 @tindex kpse_format_info_type
3277 Report general path information for each file type Kpathsea is asked to
3278 search. This is useful when you are trying to track down how a
3279 particular path got defined---from @file{texmf.cnf}, @file{config.ps},
3280 an environment variable, the compile-time default, etc. This is the
3281 contents of the @code{kpse_format_info_type} structure defined in
3284 @item KPSE_DEBUG_EXPAND @r{(16)}
3285 Report the directory list corresponding to each path element Kpathsea
3286 searches. This is only relevant when Kpathsea searches the disk, since
3287 @file{ls-R} searches don't look through directory lists in this way.
3289 @item KPSE_DEBUG_SEARCH @r{(32)}
3290 Report on each file search: the name of the file searched for, the path
3291 searched in, whether or not the file must exist (when drivers search for
3292 @file{cmr10.vf}, it need not exist), and whether or not we are
3293 collecting all occurrences of the file in the path (as with, e.g.,
3294 @file{texmf.cnf} and @file{texfonts.map}), or just the first (as with
3295 most lookups). This can help you correlate what Kpathsea is doing with
3296 what is in your input file.
3298 @item KPSE_DEBUG_VARS @r{(64)}
3299 Report the value of each variable Kpathsea looks up. This is useful for
3300 verifying that variables do indeed obtain their correct values.
3302 @item GSFTOPK_DEBUG @r{(128)}
3303 Activates debugging printout specific to @code{gsftopk} program.
3305 @item MAKETEX_DEBUG @r{(512)}
3306 If you use the optional @code{mktex} programs instead of the
3307 traditional shell scripts, this will report the name of the site file
3308 (@file{mktex.cnf} by default) which is read, directories created by
3309 @code{mktexdir}, the full path of the @file{ls-R} database built by
3310 @code{mktexlsr}, font map searches, @code{MT_FEATURES} in effect,
3311 parameters from @code{mktexnam}, filenames added by
3312 @code{mktexupd}, and some subsidiary commands run by the programs.
3314 @item MAKETEX_FINE_DEBUG @r{(1024)}
3315 When the optional @code{mktex} programs are used, this will print
3316 additional debugging info from functions internal to these programs.
3319 @cindex @samp{kdebug:}
3320 @vindex hash_summary_only @r{variable for debugging}
3321 @cindex hash table buckets, printing
3322 Debugging output from Kpathsea is always written to standard error, and
3323 begins with the string @samp{kdebug:}. (Except for hash table buckets,
3324 which just start with the number, but you can only get that output
3325 running under a debugger. See comments at the @code{hash_summary_only}
3326 variable in @file{kpathsea/db.c}.)
3334 @cindex logging successful searches
3335 @cindex recording successful searches
3336 @cindex usage patterns, finding
3337 @cindex disk usage, reducing
3338 Kpathsea can record the time and filename found for each successful
3339 search. This may be useful in finding good candidates for deletion when
3340 your filesystem is full, or in discovering usage patterns
3344 To do this, define the environment or config file variable
3345 @code{TEXMFLOG}. The value is the name of the file to append the
3346 information to. The file is created if it doesn't exist, and appended
3349 @cindex epoch, seconds since
3350 @findex time @r{system call}
3351 Each successful search turns into one line in the log file: two words
3352 separated by a space. The first word is the time of the search, as the
3353 integer number of seconds since ``the epoch'', i.e., UTC midnight 1
3354 January 1970 (more precisely, the result of the @code{time} system
3355 call). The second word is the filename.
3357 For example, after @code{setenv TEXMFLOG /tmp/log}, running Dvips on
3358 @file{story.dvi} appends the following lines:
3361 774455887 /usr/local/share/texmf/dvips/config.ps
3362 774455887 /usr/local/share/texmf/dvips/psfonts.map
3363 774455888 /usr/local/share/texmf/dvips/texc.pro
3364 774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk
3365 774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk
3366 774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk
3367 774455889 /usr/local/share/texmf/dvips/texc.pro
3370 @cindex privacy, semblance of
3371 @noindent Only filenames that are absolute are recorded, to preserve
3372 some semblance of privacy.
3374 In addition to this Kpathsea-specific logging, @command{pdftex}
3375 provides an option @option{-recorder} to write the names of all files
3376 accessed during a run to the file @file{@var{basefile}.fls}.
3378 Finally, most systems provide a general tool to output each system
3379 call, thus including opening and closing files. It might be named
3380 @command{strace}, @command{truss}, @command{struss}, or something
3384 @node Common problems
3385 @section Common problems
3387 @cindex common problems
3388 @cindex problems, common
3389 @cindex FAQ, Kpathsea
3391 Here are some common problems with configuration, compilation, linking,
3395 * Unable to find files:: If your program can't find fonts (or whatever).
3396 * Slow path searching:: If it takes forever to find anything.
3397 * Unable to generate fonts:: If mktexpk fails.
3398 * TeX or Metafont failing:: Likely compiler bugs.
3401 @node Unable to find files
3402 @subsection Unable to find files
3404 @cindex unable to find files
3405 @cindex files, unable to find
3407 If a program complains it cannot find fonts (or other input files), any
3408 of several things might be wrong. In any case, you may find the
3409 debugging options helpful. @xref{Debugging}.
3413 Perhaps you simply haven't installed all the necessary files; the basic
3414 fonts and input files are distributed separately from the programs.
3418 @flindex /etc/profile
3419 @cindex environment variables, old
3420 You have (perhaps unknowingly) told Kpathsea to use search paths that
3421 don't reflect where the files actually are. One common cause is having
3422 environment variables set from a previous installation, thus overriding
3423 what you carefully set in @file{texmf.cnf} (@pxref{Supported file
3424 formats}). System @file{/etc/profile} or other files such may be the
3428 @cindex symbolic links not found
3429 @cindex leaf directories wrongly guessed
3430 Your files reside in a directory that is only pointed to via a symbolic
3431 link, in a leaf directory and is not listed in @file{ls-R}.
3433 Unfortunately, Kpathsea's subdirectory searching has an irremediable
3434 deficiency: If a directory @var{d} being searched for subdirectories
3435 contains plain files and symbolic links to other directories, but no
3436 true subdirectories, @var{d} will be considered a leaf directory, i.e.,
3437 the symbolic links will not be followed. @xref{Subdirectory expansion}.
3439 You can work around this problem by creating an empty dummy subdirectory
3440 in @var{d}. Then @var{d} will no longer be a leaf, and the symlinks will
3443 The directory immediately followed by the @samp{//} in the path
3444 specification, however, is always searched for subdirectories, even if
3445 it is a leaf. Presumably you would not have asked for the directory to
3446 be searched for subdirectories if you didn't want it to be.
3449 If the fonts (or whatever) don't already exist, @code{mktexpk} (or
3450 @code{mktexmf} or @code{mktextfm}) will try to create them. If
3451 these rather complicated shell scripts fail, you'll eventually get an
3452 error message saying something like @samp{Can't find font
3453 @var{fontname}}. The best solution is to fix (or at least report) the
3454 bug in @code{mktexpk}; the workaround is to generate the necessary
3455 fonts by hand with Metafont, or to grab them from a CTAN site
3456 (@pxref{unixtex.ftp}).
3459 There is a bug in the library. @xref{Reporting bugs}.
3463 @node Slow path searching
3464 @subsection Slow path searching
3466 @cindex excessive startup time
3467 @cindex slow startup time
3468 @cindex startup time, excessive
3470 If your program takes an excessively long time to find fonts or other
3471 input files, but does eventually succeed, here are some possible culprits:
3475 Most likely, you just have a lot of directories to search, and that
3476 takes a noticeable time. The solution is to create and maintain a
3477 separate @file{ls-R} file that lists all the files in your main @TeX{}
3478 hierarchy. @xref{Filename database}. Kpathsea always uses @file{ls-R}
3479 if it's present; there's no need to recompile or reconfigure any of the
3483 Your recursively-searched directories (e.g.,
3484 @file{/usr/local/share/texmf/fonts//}), contain a mixture of files and
3485 directories. This prevents Kpathsea from using a useful optimization
3486 (@pxref{Subdirectory expansion}).
3488 It is best to have only directories (and perhaps a @file{README}) in the
3489 upper levels of the directory structure, and it's very important to have
3490 @emph{only} files, and no subdirectories, in the leaf directories where
3491 the dozens of TFM, PK, or whatever files reside.
3494 In any case, you may find the debugging options helpful in determining
3495 precisely when the disk or network is being pounded. @xref{Debugging}.
3498 @node Unable to generate fonts
3499 @subsection Unable to generate fonts
3501 @cindex unable to generate fonts
3502 @cindex font generation failures
3504 Metafont outputs fonts in bitmap format, tuned for a particular
3505 device at a particular resolution, in order to allow for the
3506 highest-possible quality of output. Some DVI-to-whatever programs,
3507 such as Dvips, try to generate these on the fly when they are needed,
3508 but this generation may fail in several cases.
3510 @cindex @code{mktexpk} can't guess mode
3511 If @code{mktexpk} runs, but fails with this error:
3513 mktexpk: Can't guess mode for @var{nnn} dpi devices.
3514 mktexpk: Use a config file to specify the mode, or update me.
3516 you need to ensure the resolution and mode match; just
3517 specifying the resolution, as in @code{-D 360}, is not enough.
3519 You can specify the mode name with the @code{-mode} option on the
3520 Dvips command line, or in a Dvips configuration file (@pxref{Config
3521 files,,, dvips, Dvips}), such as @file{config.ps} in your document
3522 directory, @file{~/.dvipsrc} in your home directory, or in a system
3523 directory (again named @file{config.ps}). (Other drivers use other
3526 For example, if you need 360@dmn{dpi} fonts, you could include this in
3527 a configuration file:
3533 @cindex Metafont using the wrong device
3534 @cindex device, wrong
3535 If Metafont runs, but generates fonts at the wrong resolution or for
3536 the wrong device, most likely @code{mktexpk}'s built-in guess for the
3537 mode is wrong, and you should override it as above.
3539 See @url{http://ctan.org/pkg/modes} for a list of resolutions and mode
3540 names for most devices (additional submissions are welcome).
3544 @cindex Metafont making too-large fonts
3546 @cindex online Metafont display, spurious
3547 If Metafont runs but generates fonts at a resolution of 2602@dmn{dpi}
3548 (and prints out the name of each character as well as just a character
3549 number, and maybe tries to display the characters), then your Metafont
3550 base file probably hasn't been made properly. (It's using the default
3551 @code{proof} mode, instead of an actual device mode.) To make a proper
3552 @file{plain.base}, assuming the local mode definitions are contained in
3553 a file @file{modes.mf}, run the following command (assuming Unix):
3556 inimf "plain; input modes; dump"
3561 Then copy the @file{plain.base} file from the current directory to where
3562 the base files are stored on your system
3563 (@file{/usr/local/share/texmf/web2c} by default), and make a link
3564 (either hard or soft) from @file{plain.base} to @file{mf.base} in that
3566 @xref{inimf invocation,,, web2c, Web2c}.
3568 @cindex Metafont installation
3569 If @code{mf} is a command not found at all by @code{mktexpk}, then you
3570 need to install Metafont (@pxref{unixtex.ftp}).
3573 @node TeX or Metafont failing
3574 @subsection @TeX{} or Metafont failing
3576 @cindex @TeX{} failures
3577 @cindex Metafont failures
3578 @cindex compiler bugs
3579 If @TeX{} or Metafont get a segmentation fault or otherwise fail while
3580 running a normal input file, the problem is usually a compiler bug
3581 (unlikely as that may sound). Even if the trip and trap tests are
3582 passed, problems may lurk. Optimization occasionally causes trouble in
3583 programs other than @TeX{} and Metafont themselves, too.
3585 Insufficient swap space may also cause core dumps or other erratic
3588 @cindex optimization caveat
3589 For a workaround, if you enabled any optimization flags, it's best to
3590 omit optimization entirely. In any case, the way to find the facts is
3591 to run the program under the debugger and see where it's failing.
3593 @cindex GNU C compiler bugs
3594 @cindex system C compiler bugs
3595 Also, if you have trouble with a system C compiler, I advise trying the
3596 GNU C compiler. And vice versa, unfortunately; but in that case I also
3597 recommend reporting a bug to the GCC mailing list; see @ref{Bugs,,, gcc,
3598 Using and Porting GNU CC}.
3600 @cindex compiler bugs, finding
3601 To report compiler bugs effectively requires perseverance and
3602 perspicacity: you must find the miscompiled line, and that usually
3603 involves delving backwards in time from the point of error, checking
3604 through @TeX{}'s (or whatever program's) data structures. Things are
3605 not helped by all-too-common bugs in the debugger itself. Good luck.