2 @setfilename kpathsea.info
3 @settitle Kpathsea: A library for path searching
6 @set month-year July 2008
9 This file documents the Kpathsea library for path searching.
11 Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
12 2004, 2005, 2007, 2008 Karl Berry & Olaf Weber.
14 Permission is granted to make and distribute verbatim copies of this
15 manual provided the copyright notice and this permission notice are
16 preserved on all copies.
19 Permission is granted to process this file through TeX and print the
20 results, provided the printed document carries a copying permission
21 notice identical to this one except for the removal of this paragraph
22 (this paragraph not being relevant to the printed manual).
25 Permission is granted to copy and distribute modified versions of this
26 manual under the conditions for verbatim copying, provided that the
27 entire resulting derived work is distributed under the terms of a
28 permission notice identical to this one.
30 Permission is granted to copy and distribute translations of this manual
31 into another language, under the above conditions for modified versions,
32 except that this permission notice may be stated in a translation
33 approved by the Free Software Foundation.
36 @c Define new indices for commands, filenames, and options.
41 @c Put everything in one index (arbitrarily chosen to be the concept index).
53 * Kpathsea: (kpathsea). File lookup along search paths.
54 * kpsewhich: (kpathsea)Invoking kpsewhich. TeX file searching.
55 * mktexfmt: (kpathsea)mktex scripts. Format (fmt/base/mem) generation.
56 * mktexlsr: (kpathsea)Filename database. Update ls-R.
57 * mktexmf: (kpathsea)mktex scripts. MF source generation.
58 * mktexpk: (kpathsea)mktex scripts. PK bitmap generation.
59 * mktextex: (kpathsea)mktex scripts. TeX source generation.
60 * mktextfm: (kpathsea)mktex scripts. TeX font metric generation.
65 @title Kpathsea library
66 @subtitle for version @value{version}
67 @subtitle @value{month-year}
68 @author Karl Berry (@email{kb@@mail.tug.org})
69 @author Olaf Weber (@email{infovore@@xs4all.nl})
72 @vskip 0pt plus 1filll
84 This manual documents how to install and use the Kpathsea library for
85 filename lookup. It corresponds to version @value{version},
86 released in @value{month-year}.
89 * Introduction:: Overview.
90 * Installation:: Compilation, installation, and bug reporting.
92 * Path searching:: How filename lookups work.
93 * TeX support:: Special support for TeX-related file lookups.
95 * Programming:: How to use Kpathsea features in your program.
97 * Index:: General index.
103 @chapter Introduction
106 @cindex fundamental purpose of Kpathsea
108 This manual corresponds to version @value{version} of the Kpathsea
109 library, released in @value{month-year}.
111 The library's fundamental purpose is to return a filename from a list of
112 directories specified by the user, similar to what shells do when
113 looking up program names to execute.
115 @cindex programs using the library
116 The following software, all of which we maintain, uses this library:
119 @item Dviljk (see the @samp{dvilj} man page)
120 @item Dvipsk (@pxref{Top, , Introduction, dvips, Dvips: A DVI driver})
121 @item GNU font utilities (@pxref{Top, , Introduction, fontu, GNU font
123 @item Web2c (@pxref{Top, , Introduction, web2c, Web2c: A @TeX{}
125 @item Xdvik (see the @samp{xdvi} man page)
128 @noindent Other software that we do not maintain also uses it.
130 @cindex interface, not frozen
131 @cindex comments, making
132 @cindex suggestions, making
133 We are still actively maintaining the library (and probably always will
134 be, despite our hopes). If you have comments or suggestions, please send
135 them to us (@pxref{Reporting bugs}).
137 @cindex conditions for use
138 @cindex license for using the library
139 @cindex GNU General Public License
140 We distribute the library under the GNU Library General Public License
141 (LGPL). In short, this means if you write a program using the library,
142 you must (offer to) distribute the source to the library, along with any
143 changes you have made, and allow anyone to modify the library source and
144 distribute their modifications. It does not mean you have to distribute
145 the source to your program, although we hope you will. See the files
146 @file{GPL} and @file{LGPL} for the text of the GNU licenses.
148 @cindex @TeX{} Users Group
149 If you know enough about @TeX{} to be reading this manual, then you (or
150 your institution) should consider joining the @TeX{} Users Group (if
151 you're already a member, great!). TUG produces the periodical
152 @cite{TUGboat}, sponsors an annual meeting and publishes the
153 proceedings, and arranges courses on @TeX{} for all levels of users
154 throughout the world. Anyway, here is the address:
156 @flindex tug@@tug.org
160 Portland OR 97208-2311
162 phone: +1 503 223-9994
164 email: @email{tug@@tug.org}
175 @cindex history of Kpathsea
177 @cindex Knuth, Donald E.
178 (This section is for those people who are curious about how the library
179 came about.) (If you like to read historical accounts of software, we
180 urge you to seek out the GNU Autoconf manual and the ``Errors of
181 @TeX{}'' paper by Don Knuth, published in @cite{Software---Practice and
182 Experience} 19(7), July 1989.)
189 @pindex pxp @r{Pascal preprocessor}
190 @pindex pc @r{Pascal compiler}
191 [Karl writes.] My first ChangeLog entry for Web2c seems to be February
192 1990, but I may have done some work before then. In any case, Tim
193 Morgan and I were jointly maintaining it for a time. (I should mention
194 here that Tim had made Web2c into a real distribution long before I had
195 ever used it or even heard of it, and Tom Rokicki did the original
196 implementation. I was using @code{pxp} and @code{pc} on VAX 11/750's
197 and the hot new Sun 2 machines.)
199 It must have been later in 1990 and 1991 that I started working on
200 @cite{@TeX{} for the Impatient}. Dvips, Xdvi, Web2c, and the GNU
201 fontutils (which I was also writing at the time) all used different
202 environment variables, and, more importantly, had different bugs in
203 their path searching. This became extremely painful, as I was stressing
204 everything to the limit working on the book. I also desperately wanted
205 to implement subdirectory searching, since I couldn't stand putting
206 everything in one big directory, and also couldn't stand having to
207 explicitly specify @file{cm}, @file{pandora}, @dots{} in a path.
210 In the first incarnation, I just hacked separately on each
211 program---that was the original subdirectory searching code in both Xdvi
212 and Dvips, though I think Paul Vojta has completely rewritten Xdvi's
213 support by now. That is, I tried to go with the flow in each program,
214 rather than changing the program's calling sequences to conform to
217 Then, as bugs inevitably appeared, I found I was fixing the same thing
218 three times (Web2c and fontutils were always sharing code, since I
219 maintained those---there was no Dvipsk or Xdvik or Dviljk at this
220 point). After a while, I finally started sharing source files. They
221 weren't yet a library, though. I just kept things up to date with shell
222 scripts. (I was developing on a 386 running ISC 2.2 at the time, and so
223 didn't have symbolic links. An awful experience.)
225 @cindex MacKenzie, David
226 The ChangeLogs for Xdvik and Dvipsk record initial releases of those
227 distributions in May and June 1992. I think it was because I was tired
228 of the different configuration strategies of each program, not so much
229 because of the path searching. (Autoconf was being developed by David
230 MacKenzie and others, and I was adapting it to @TeX{} and friends.)
233 I started to make a separate library that other programs could link with
234 on my birthday in April 1993, according to the ChangeLog. I don't
235 remember exactly why I finally took the time to make it a separate
236 library; a conversation with david zuhn that initiated it. Just seemed
239 @cindex Walsh, Norman
240 @cindex Neumann, Gustaf
241 Dviljk got started in March 1994 after I bought a Laserjet 4. (Kpathsea
242 work got suspended while Norm Walsh and I, with Gustaf Neumann's help,
243 implemented a way for @TeX{} to get at all those neat builtin LJ4 fonts
244 @dots{} such a treat to have something to typeset in besides Palatino!)
246 By spring of 1995, I had implemented just about all the path-searching
247 features in Kpathsea that I plan to, driven beyond my initial goals by
248 Thomas Esser and others. I then started to integrate Web2c with
249 Kpathsea. After the release of a stable Web2c, I hope to be able to stop
250 development, and turn most of my attention back to making fonts for GNU.
251 (Always assuming Micros**t hasn't completely obliterated Unix by then,
252 or that software patents haven't stopped software development by anybody
253 smaller than a company with a million-dollar-a-year legal budget. Which
254 is actually what I think is likely to happen, but that's another
258 [Olaf writes.] At the end of 1997, UNIX is still alive and kicking,
259 individuals still develop software, and Web2c development still
260 continues. Karl had been looking for some time for someone to take up
261 part of the burden, and I volunteered.
264 @include install.texi
266 @include unixtex.texi
271 @chapter Path searching
273 @cindex path searching
275 This chapter describes the generic path searching mechanism Kpathsea
276 provides. For information about searching for particular file types
277 (e.g., @TeX{} fonts), see the next chapter.
280 * Searching overview:: Basic scheme for searching.
281 * Path sources:: Where search paths can be defined.
282 * Path expansion:: Special constructs in search paths.
283 * Filename database:: Using an externally-built list to search.
284 * Invoking kpsewhich:: Standalone path lookup.
288 @node Searching overview
289 @section Searching overview
291 @cindex searching overview
292 @cindex path searching, overview
293 @cindex overview of path searching
295 @cindex search path, defined
296 A @dfn{search path} is a colon-separated list of @dfn{path elements},
297 which are directory names with a few extra frills. A search path can
298 come from (a combination of) many sources; see below. To look up a file
299 @samp{foo} along a path @samp{.:/dir}, Kpathsea checks each element of
300 the path in turn: first @file{./foo}, then @file{/dir/foo}, returning
301 the first match (or possibly all matches).
303 @cindex magic characters
304 @kindex : @r{may not be :}
305 @kindex / @r{may not be /}
306 The ``colon'' and ``slash'' mentioned here aren't necessarily @samp{:}
307 and @samp{/} on non-Unix systems. Kpathsea tries to adapt to other
308 operating systems' conventions.
310 @cindex database search
311 @cindex searching the database
312 To check a particular path element @var{e}, Kpathsea first sees if a
313 prebuilt database (@pxref{Filename database}) applies to @var{e}, i.e.,
314 if the database is in a directory that is a prefix of @var{e}. If so,
315 the path specification is matched against the contents of the database.
317 @cindex floating directories
318 @cindex filesystem search
320 @cindex searching the disk
321 If the database does not exist, or does not apply to this path element,
322 or contains no matches, the filesystem is searched (if this was not
323 forbidden by the specification with @samp{!!} and if the file being
324 searched for must exist). Kpathsea constructs the list of directories
325 that correspond to this path element, and then checks in each for the
326 file being searched for. (To help speed future lookups of files in the
327 same directory, the directory in which a file is found is floated to the
328 top of the directory list.)
331 @cindex VF files, not found
334 The ``file must exist'' condition comes into play with VF files and
335 input files read by the @TeX{} @samp{\openin} command. These files
336 might very well not exist (consider @file{cmr10.vf}), and so it would
337 be wrong to search the disk for them. Therefore, if you fail to
338 update @file{ls-R} when you install a new VF file, it will not be
341 Each path element is checked in turn: first the database, then the disk.
342 If a match is found, the search stops and the result is returned. This
343 avoids possibly-expensive processing of path specifications that are
344 never needed on a particular run. (Unless the search explicitly
345 requested all matches.)
347 @cindex expansion, path element
348 Although the simplest and most common path element is a directory name,
349 Kpathsea supports additional features in search paths: layered default
350 values, environment variable names, config file values, users' home
351 directories, and recursive subdirectory searching. Thus, we say that
352 Kpathsea @dfn{expands} a path element, meaning transforming all the
353 magic specifications into the basic directory name or names. This
354 process is described in the sections below. It happens in the same
355 order as the sections.
357 @cindex absolute filenames
358 @cindex relative filenames
359 @cindex explicitly relative filenames
360 @cindex filenames, absolute or explicitly relative
361 Exception to all of the above: If the filename being searched for is
362 absolute or explicitly relative, i.e., starts with @samp{/} or @samp{./}
363 or @samp{../}, Kpathsea simply checks if that file exists.
365 @cindex permission denied
366 @cindex unreadable files
367 @cindex access warnings
368 @cindex warnings, file access
369 @flindex lost+found @r{directory}
371 Ordinarily, if Kpathsea tries to access a file or directory that
372 cannot be read, it gives a warning. This is so you will be alerted to
373 directories or files that accidentally lack any read permission (for
374 example, a @file{lost+found} directory). If you prefer not to see
375 these warnings, include the value @samp{readable} in the
376 @code{TEX_HUSH} environment variable or config file value.
378 This generic path searching algorithm is implemented in
379 @file{kpathsea/pathsearch.c}. It is employed by a higher-level
380 algorithm when searching for a file of a particular type (@pxref{File
381 lookup}, and @ref{Glyph lookup}).
385 @section Path sources
388 @cindex sources for search paths
390 A search path can come from many sources. In the order in which
395 @cindex environment variable, source for path
396 A user-set environment variable, e.g., @code{TEXINPUTS}.
397 Environment variables with an underscore and the program name appended
398 override; for example, @code{TEXINPUTS_latex} overrides @code{TEXINPUTS}
399 if the program being run is named @samp{latex}.
402 A program-specific configuration file, e.g., an @samp{S /a:/b} line in
403 Dvips' @file{config.ps} (@pxref{Config files,,, dvips, Dvips}).
406 @cindex configuration file, source for path
407 @cindex Kpathsea config file, source for path
408 @flindex texmf.cnf@r{, source for path}
409 A line in a Kpathsea configuration file @file{texmf.cnf}, e.g.,
410 @samp{TEXINPUTS=/c:/d} (see below).
413 @cindex compilation value, source for path
414 The compile-time default (specified in @file{kpathsea/paths.h}).
417 You can see each of these values for a given search path by using the
418 debugging options (@pxref{Debugging}).
420 These sources may be combined via default expansion (@pxref{Default
424 * Config files:: Kpathsea's runtime config files (texmf.cnf).
429 @subsection Config files
432 @flindex texmf.cnf@r{, definition for}
434 @cindex runtime configuration files
436 As mentioned above, Kpathsea reads @dfn{runtime configuration files}
437 named @file{texmf.cnf} for search path and other definitions. The
438 search path used to look for these configuration files is named
439 @code{TEXMFCNF}, and is constructed in the usual way, as described
440 above, except that configuration files cannot be used to define the
441 path, naturally; also, an @file{ls-R} database is not used to search for
444 Kpathsea reads @emph{all} @file{texmf.cnf} files in the search path, not
445 just the first one found; definitions in earlier files override those in
446 later files. Thus, if the search path is @samp{.:$TEXMF}, values from
447 @file{./texmf.cnf} override those from @file{$TEXMF/texmf.cnf}.
449 @vindex KPATHSEA_WARNING
450 @cindex warning, about missing @file{texmf.cnf}
451 @cindex @file{texmf.cnf} missing, warning about
452 If Kpathsea cannot find any @file{texmf.cnf} file, it reports a
453 warning including all the directories it checked. If you don't want
454 to see this warning, set the environment variable
455 @env{KPATHSEA_WARNING} to the single character @samp{0} (zero, not
458 While (or instead of) reading this description, you may find it helpful
459 to look at the distributed @file{texmf.cnf}, which uses or at least
460 mentions most features. The format of @file{texmf.cnf} files follows:
464 @cindex comments, in @file{texmf.cnf}
465 Comments start with @samp{%} and continue to the end of the line.
468 @cindex blank lines, in @file{texmf.cnf}
469 Blank lines are ignored.
472 @cindex backslash-newline
473 @cindex continuation character
474 @cindex whitespace, not ignored on continuation lines
475 @kindex \@r{, line continuation in @file{texmf.cnf}}
476 A @samp{\} at the end of a line acts as a continuation character, i.e.,
477 the next line is appended. Whitespace at the beginning of continuation
478 lines is not ignored.
480 @item Each remaining line must look like
483 @var{variable} @r{[}. @var{progname}@r{]} @r{[}=@r{]} @var{value}
486 @noindent where the @samp{=} and surrounding whitespace is optional.
489 @cindex identifiers, characters valid in
490 The @var{variable} name may contain any character other than whitespace,
491 @samp{=}, or @samp{.}, but sticking to @samp{A-Za-z_} is safest.
493 @item If @samp{.@var{progname}} is present, the definition only
494 applies if the program that is running is named (i.e., the last
495 component of @code{argv[0]} is) @var{progname} or
496 @file{@var{progname}.exe}. This allows different flavors of @TeX{} to
497 have different search paths, for example.
500 @cindex right-hand side of variable assignments
501 @var{value} may contain any characters except @samp{%} and @samp{@@}.
502 (These restrictions are only necessary because of the processing done on
503 @file{texmf.cnf} at build time, so you can stick those characters in
504 after installation if you have to.) The @samp{$@var{var}.@var{prog}}
505 feature is not available on the right-hand side; instead, you must use
506 an additional variable (see below for example). A @samp{;} in
507 @var{value} is translated to @samp{:} if running under Unix; this is
508 useful to write a single @file{texmf.cnf} which can be used under both
511 @item All definitions are read before anything is expanded, so you can
512 use variables before they are defined (like Make, unlike most other
516 @noindent Here is a configuration file fragment illustrating most of
520 % TeX input files -- i.e., anything to be found by \input or \openin ...
521 latex209_inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex//
522 latex2e_inputs = .:$TEXMF/tex/latex//:$TEXMF/tex//
523 TEXINPUTS = .:$TEXMF/tex//
524 TEXINPUTS.latex209 = $latex209_inputs
525 TEXINPUTS.latex2e = $latex2e_inputs
526 TEXINPUTS.latex = $latex2e_inputs
529 @cindex shell scripts as configuration files
530 @cindex configuration files as shell scripts.
531 Although this format has obvious similarities to Bourne shell
532 scripts---change the comment character to @code{#}, disallow spaces
533 around the @code{=}, and get rid of the @code{.@var{name}} convention,
534 and it could be run through the shell. But there seemed little
535 advantage to doing this, since all the information would have to passed
536 back to Kpathsea and parsed there anyway, since the @code{sh} process
537 couldn't affect its parent's environment.
540 The implementation of all this is in @file{kpathsea/cnf.c}.
544 @section Path expansion
546 @cindex path expansion
547 @cindex expansion, search path
549 Kpathsea recognizes certain special characters and constructions in
550 search paths, similar to that in shells. As a general example:
551 @samp{~$USER/@{foo,bar@}//baz} expands to all subdirectories under
552 directories @file{foo} and @file{bar} in @t{$USER}'s home directory that
553 contain a directory or file @file{baz}. These expansions are explained
554 in the sections below.
557 * Default expansion:: a: or :a or a::b expands to a default.
558 * Variable expansion:: $foo and $@{foo@} expand to environment values.
559 * Tilde expansion:: ~ and ~user expand to home directories.
560 * Brace expansion:: a@{foo,bar@}b expands to afoob abarb.
561 * KPSE_DOT expansion:: . is replaced with $KPSE_DOT if it is defined.
562 * Subdirectory expansion:: a// and a//b recursively expand to subdirs.
566 @node Default expansion
567 @subsection Default expansion
569 @kindex :: @r{expansion}
570 @cindex doubled colons
571 @cindex leading colons
572 @cindex trailing colons
574 @cindex default expansion
575 @cindex expansion, default
577 If the highest-priority search path (@pxref{Path sources}) contains an
578 @dfn{extra colon} (i.e., leading, trailing, or doubled), Kpathsea
579 inserts at that point the next-highest-priority search path that is
580 defined. If that inserted path has an extra colon, the same happens
581 with the next-highest. (An extra colon in the compile-time default
582 value has unpredictable results, so installers beware.)
584 For example, given an environment variable setting
587 setenv TEXINPUTS /home/karl:
590 @noindent and a @code{TEXINPUTS} value from @file{texmf.cnf} of
596 @noindent then the final value used for searching will be:
599 /home/karl:.:$TEXMF//tex
602 Put another way, default expansion works on ``formats'' (search
603 paths), and not directly on environment variables. Example, showing
604 the trailing @samp{:} ignored in the first case and expanded in the second:
607 $ env TTFONTS=/tmp: kpsewhich --expand-path '$TTFONTS'
609 $ env TTFONTS=/tmp: kpsewhich --show-path=.ttf
610 /tmp:.:/home/olaf/texmf/fonts/truetype//:...
613 Since Kpathsea looks for multiple configuration files, it would be
614 natural to expect that (for example) an extra colon in
615 @file{./texmf.cnf} would expand to the path in @file{$TEXMF/texmf.cnf}.
616 Or, with Dvips' configuration files, that an extra colon in
617 @file{config.$PRINTER} would expand to the path in @file{config.ps}.
618 This doesn't happen. It's not clear this would be desirable in all
619 cases, and trying to devise a way to specify the path to which the extra
620 colon should expand seemed truly baroque.
621 @cindex Bach, Johann Sebastian
623 Technicality: Since it would be useless to insert the default value in
624 more than one place, Kpathsea changes only one extra @samp{:} and leaves
625 any others in place (they will eventually be ignored). Kpathsea checks
626 first for a leading @samp{:}, then a trailing @samp{:}, then a doubled
630 You can trace this by debugging ``paths'' (@pxref{Debugging}).
631 Default expansion is implemented in the source file
632 @file{kpathsea/kdefault.c}.
635 @node Variable expansion
636 @subsection Variable expansion
638 @kindex $ @r{expansion}
639 @cindex environment variables in paths
640 @cindex variable expansion
641 @cindex expansion, variable
642 @flindex texmf.cnf@r{, and variable expansion}
644 @samp{$foo} or @samp{$@{foo@}} in a path element is replaced by (1) the
645 value of an environment variable @samp{foo} (if defined); (2) the value
646 of @samp{foo} from @file{texmf.cnf} (if defined); (3) the empty string.
648 If the character after the @samp{$} is alphanumeric or @samp{_}, the
649 variable name consists of all consecutive such characters. If the
650 character after the @samp{$} is a @samp{@{}, the variable name consists
651 of everything up to the next @samp{@}} (braces may not be nested around
652 variable names). Otherwise, Kpathsea gives a warning and ignores the
653 @samp{$} and its following character.
655 @cindex quoting variable values
656 @cindex shell variables
657 You must quote the @t{$}'s and braces as necessary for your shell.
658 @emph{Shell} variable values cannot be seen by Kpathsea, i.e., ones
659 defined by @code{set} in C shells and without @code{export} in Bourne
664 setenv tex /home/texmf
665 setenv TEXINPUTS .:$tex:$@{tex@}prev
667 @noindent the final @code{TEXINPUTS} path is the three directories:
669 .:/home/texmf:/home/texmfprev
672 The @samp{.@var{progname}} suffix on variables and
673 @samp{_@var{progname}} on environment variable names are not implemented
674 for general variable expansions. These are only recognized when search
675 paths are initialized (@pxref{Path sources}).
678 Variable expansion is implemented in the source file
679 @file{kpathsea/variable.c}.
682 @node Tilde expansion
683 @subsection Tilde expansion
685 @kindex ~ @r{expansion}
686 @cindex home directories in paths
687 @cindex tilde expansion
688 @cindex expansion, tilde
690 @vindex HOME@r{, as ~ expansion}
691 @vindex USERPROFILE@r{, as ~ expansion}
692 A leading @samp{~} in a path element is replaced by the value of the
693 environment variable @code{HOME}, or @file{.} if @code{HOME} is not
694 set. On Windows, the environment variable @code{USERPROFILE} is
695 checked instead of @code{HOME}.
697 A leading @samp{~@var{user}} in a path element is replaced by
698 @var{user}'s home directory from the system @file{passwd} database.
702 setenv TEXINPUTS ~/mymacros:
705 @noindent will prepend a directory @file{mymacros} in your home
706 directory to the default path.
708 @cindex @t{root} user
709 @cindex trailing @samp{/} in home directory
710 @kindex /@r{, trailing in home directory}
711 As a special case, if a home directory ends in @samp{/}, the trailing
712 slash is dropped, to avoid inadvertently creating a @samp{//} construct
713 in the path. For example, if the home directory of the user @samp{root}
714 is @samp{/}, the path element @samp{~root/mymacros} expands to just
715 @samp{/mymacros}, not @samp{//mymacros}.
718 Tilde expansion is implemented in the source file @file{kpathsea/tilde.c}.
721 @node Brace expansion
722 @subsection Brace expansion
724 @kindex @{ @r{expansion}
725 @cindex brace expansion
727 @samp{x@{@var{a},@var{b}@}y} expands to @samp{x@var{a}y:x@var{b}y}.
734 @noindent expands to @samp{foo/1/baz:foo/2/baz}. @samp{:} is the path
735 separator on the current system; e.g., on a DOS system, it's @samp{;}.
737 Braces can be nested; for example, @samp{x@{A,B@{1,2@}@}y} expands to
738 @samp{xAy:xB1y:xB2y}.
740 Multiple non-nested braces are expanded from right to left; for example,
741 @samp{x@{A,B@}@{1,2@}y} expands to @samp{x@{A,B@}1y:x@{A,B@}2y}, which
742 expands to @samp{xA1y:xB1y:xA2y:xB2y}.
744 @cindex multiple @TeX{} hierarchies
745 This feature can be used to implement multiple @TeX{} hierarchies, by
746 assigning a brace list to @code{$TEXMF}, as mentioned in
749 You can also use the path separator in stead of the comma. The last
750 example could have been written @samp{x@{A:B@}@{1:2@}y}.
754 Brace expansion is implemented in the source file
755 @file{kpathsea/expand.c}. It is a modification of the Bash sources, and
756 is thus covered by the GNU General Public License, rather than the
757 Library General Public License that covers the rest of Kpathsea.
760 @node KPSE_DOT expansion
761 @subsection @code{KPSE_DOT} expansion
763 @kindex KPSE_DOT @r{expansion}
765 When @code{KPSE_DOT} is defined in the environment, it names a directory
766 that should be considered the current directory for the purpose of
767 looking up files in the search paths. This feature is needed by the
768 @samp{mktex@dots{}} scripts @ref{mktex scripts}, because these
769 change the working directory. You should not ever define it yourself.
772 @node Subdirectory expansion
773 @subsection Subdirectory expansion
776 @cindex subdirectory searching
777 @cindex expansion, subdirectory
779 @cindex alphabetical order, not
780 Two or more consecutive slashes in a path element following a directory
781 @var{d} is replaced by all subdirectories of @var{d}: first those
782 subdirectories directly under @var{d}, then the subsubdirectories under
783 those, and so on. At each level, the order in which the directories are
784 searched is unspecified. (It's ``directory order'', and definitely not
787 If you specify any filename components after the @samp{//}, only
788 subdirectories which match those components are included. For example,
789 @samp{/a//b} would expand into directories @file{/a/1/b}, @file{/a/2/b},
790 @file{/a/1/1/b}, and so on, but not @file{/a/b/c} or @file{/a/1}.
792 You can include multiple @samp{//} constructs in the path.
794 @samp{//} at the beginning of a path is ignored; you didn't really want
795 to search every directory on the system, did you?
797 @cindex trick for detecting leaf directories
798 @cindex leaf directory trick
799 @cindex Farwell, Matthew
800 @cindex MacKenzie, David
801 I should mention one related implementation trick, which I took from GNU
802 find. Matthew Farwell suggested it, and David MacKenzie implemented it.
805 The trick is that in every real Unix implementation (as opposed to the
806 POSIX specification), a directory which contains no subdirectories will
807 have exactly two links (namely, one for @file{.} and one for @file{..}).
808 That is to say, the @code{st_nlink} field in the @samp{stat} structure
809 will be two. Thus, we don't have to stat everything in the bottom-level
810 (leaf) directories---we can just check @code{st_nlink}, notice it's two,
813 But if you have a directory that contains a single subdirectory and 500
814 regular files, @code{st_nlink} will be 3, and Kpathsea has to stat every
815 one of those 501 entries. Therein lies slowness.
818 You can disable the trick by undefining @code{UNIX_ST_LINK} in
819 @file{kpathsea/config.h}. (It is undefined by default except under Unix.)
822 Unfortunately, in some cases files in leaf directories are
823 @code{stat}'d: if the path specification is, say,
824 @samp{$TEXMF/fonts//pk//}, then files in a subdirectory
825 @samp{@dots{}/pk}, even if it is a leaf, are checked. The reason cannot
826 be explained without reference to the implementation, so read
827 @file{kpathsea/elt-dirs.c} (search for @samp{may descend}) if you are
828 curious. And if you can find a way to @emph{solve} the problem, please
832 Subdirectory expansion is implemented in the source file
833 @file{kpathsea/elt-dirs.c}.
836 @node Filename database
837 @section Filename database (@code{ls-R})
839 @cindex filename database
840 @cindex database, for filenames
841 @cindex externally-built filename database
843 Kpathsea goes to some lengths to minimize disk accesses for searches
844 (@pxref{Subdirectory expansion}). Nevertheless, in practice searching
845 each possible directory in typical @TeX{} installations takes an
846 excessively long time.
848 Therefore, Kpathsea can use an externally-built @dfn{filename
849 database} file named @file{ls-R} that maps files to directories, thus
850 avoiding the need to exhaustively search the disk.
852 A second database file @file{aliases} allows you to give additional
853 names to the files listed in @file{ls-R}. This can be helpful to adapt
854 to ``8.3'' filename conventions in source files.
856 The @file{ls-R} and @file{aliases} features are implemented in the
857 source file @file{kpathsea/db.c}.
860 * ls-R:: The main filename database.
861 * Filename aliases:: Aliases for those names.
862 * Database format:: Syntax details of the database file.
867 @subsection @file{ls-R}
869 @flindex ls-R @r{database file}
872 As mentioned above, you must name the main filename database
873 @file{ls-R}. You can put one at the root of each @TeX{} installation
874 hierarchy you wish to search (@code{$TEXMF} by default); most sites have
875 only one hierarchy. Kpathsea looks for @file{ls-R} files along the
876 @code{TEXMFDBS} path, so that should presumably match the list of
879 The recommended way to create and maintain @samp{ls-R} is to run the
880 @code{mktexlsr} script, which is installed in @samp{$(bindir)}
881 (@file{/usr/local/bin} by default). That script goes to some trouble to
882 follow symbolic links as necessary, etc. It's also invoked by the
883 distributed @samp{mktex@dots{}} scripts.
885 @flindex ls-R@r{, simplest build}
886 At its simplest, though, you can build @file{ls-R} with the command
888 cd @var{/your/texmf/root} && ls -LAR ./ >ls-R
893 @flindex /etc/profile @r{and aliases}
894 presuming your @code{ls} produces the right output format (see the
895 section below). GNU @code{ls}, for example, outputs in this format.
896 Also presuming your @code{ls} hasn't been aliased in a system file
897 (e.g., @file{/etc/profile}) to something problematic, e.g., @samp{ls
898 --color=tty}. In that case, you will have to disable the alias before
899 generating @file{ls-R}. For the precise definition of the file format,
900 see @ref{Database format}.
902 Regardless of whether you use the supplied script or your own, you will
903 almost certainly want to invoke it via @code{cron}, so when you make
904 changes in the installed files (say if you install a new La@TeX{}
905 package), @file{ls-R} will be automatically updated.
907 @opindex -A @r{option to @code{ls}}
910 @flindex . @r{directories, ignored}
911 @flindex .tex @r{file, included in @file{ls-R}}
912 The @samp{-A} option to @code{ls} includes files beginning with @samp{.}
913 (except for @file{.} and @file{..}), such as the file @file{.tex}
914 included with the La@TeX{} tools package. (On the other hand,
915 @emph{directories} whose names begin with @samp{.} are always ignored.)
917 @cindex symbolic links, and @file{ls-R}
918 @opindex -L @r{option to @code{ls}}
919 If your system does not support symbolic links, omit the @samp{-L}.
921 @cindex automounter, and @file{ls-R}
922 @cindex NFS and @file{ls-R}
923 @code{ls -LAR @var{/your/texmf/root}} will also work. But using
924 @samp{./} avoids embedding absolute pathnames, so the hierarchy can be
925 easily transported. It also avoids possible trouble with automounters
926 or other network filesystem conventions.
928 @cindex warning about unusable @file{ls-R}
929 @cindex unusable @file{ls-R} warning
930 Kpathsea warns you if it finds an @file{ls-R} file, but the file does
931 not contain any usable entries. The usual culprit is running plain
932 @samp{ls -R} instead of @samp{ls -LR ./} or @samp{ls -R
933 @var{/your/texmf/root}}. Another possibility is some system directory
934 name starting with a @samp{.} (perhaps if you are using AFS); Kpathsea
935 ignores everything under such directories.
937 @kindex !! @r{in path specifications}
938 @cindex disk searching, avoiding
939 Because the database may be out-of-date for a particular run, if a file
940 is not found in the database, by default Kpathsea goes ahead and
941 searches the disk. If a particular path element begins with @samp{!!},
942 however, @emph{only} the database will be searched for that element,
943 never the disk. If the database does not exist, nothing will be
944 searched. Because this can surprise users (``I see the font
945 @file{foo.tfm} when I do an @code{ls}; why can't Dvips find it?''), it
946 is not in any of the default search paths.
949 @node Filename aliases
950 @subsection Filename aliases
952 @cindex filename aliases
953 @cindex aliases, for filenames
955 In some circumstances, you may wish to find a file under several names.
956 For example, suppose a @TeX{} document was created using a DOS system
957 and tries to read @file{longtabl.sty}. But now it's being run on a Unix
958 system, and the file has its original name, @file{longtable.sty}. The
959 file won't be found. You need to give the actual file
960 @file{longtable.sty} an alias @samp{longtabl.sty}.
962 @c As another example, suppose you are creating a @TeX{} distribution on a
963 @c CD-ROM or a DOS system; then the file @file{mf.base} gets stored as
964 @c @file{mf.bas}. But Metafont on Unix wants to find @file{mf.base}. Here
965 @c you need to give the actual file @file{mf.bas} an alias @samp{mf.base}.
967 You can handle this by creating a file @file{aliases} as a companion to
968 the @file{ls-R} for the hierarchy containing the file in question. (You
969 must have an @file{ls-R} for the alias feature to work.)
971 The format of @file{aliases} is simple: two whitespace-separated words
972 per line; the first is the real name @file{longtable.sty}, and second is
973 the alias (@file{longtabl.sty}). These must be base filenames, with no
974 directory components. @file{longtable.sty} must be in the sibling
977 Also, blank lines and lines starting with @samp{%} or @samp{#} are
978 ignored in @file{aliases}, to allow for comments.
980 If a real file @file{longtabl.sty} exists, it is used regardless of any
984 @node Database format
985 @subsection Database format
987 @cindex format of external database
988 @cindex database, format of
990 The ``database'' read by Kpathsea is a line-oriented file of plain
991 text. The format is that generated by GNU (and most other) @code{ls}
992 programs given the @samp{-R} option, as follows.
996 Blank lines are ignored.
999 If a line begins with @samp{/} or @samp{./} or @samp{../} and ends with
1000 a colon, it's the name of a directory. (@samp{../} lines aren't useful,
1001 however, and should not be generated.)
1004 All other lines define entries in the most recently seen directory.
1005 @t{/}'s in such lines will produce possibly-strange results.
1008 Files with no preceding directory line are ignored.
1011 For example, here's the first few lines of @file{ls-R} (which totals
1012 about 30K bytes) on my system:
1036 @node Invoking kpsewhich
1037 @section @code{kpsewhich}: Standalone path searching
1040 @cindex path searching, standalone
1041 @cindex standalone path searching
1043 The Kpsewhich program exercises the path searching functionality
1044 independent of any particular application. This can also be useful as a
1045 sort of @code{find} program to locate files in your @TeX{} hierarchies,
1046 perhaps in administrative scripts. It is used heavily in the
1047 distributed @samp{mktex@dots{}} scripts.
1051 kpsewhich @var{option}@dots{} @var{filename}@dots{}
1054 The options and filename(s) to look up can be intermixed.
1055 Options can start with either @samp{-} or @samp{--}, and any unambiguous
1056 abbreviation is accepted.
1059 * Path searching options:: Changing the mode, resolution, etc.
1060 * Specially-recognized files:: Default formats for texmf.cnf, etc.
1061 * Auxiliary tasks:: Path and variable expansion.
1062 * Standard options:: --help and --version.
1066 @node Path searching options
1067 @subsection Path searching options
1069 @cindex path searching options
1071 Kpsewhich looks up each non-option argument on the command line as a
1072 filename, and returns the first file found.
1074 Various options alter the path searching behavior:
1079 @cindex all matches, finding
1080 Report all matches found, one per line. By default, if there is more
1081 than one match, just one will be reported (chosen effectively at random).
1083 @item --dpi=@var{num}
1084 @opindex --dpi=@var{num}
1085 @opindex -D @var{num}
1086 @cindex resolution, setting
1087 Set the resolution to @var{num}; this only affects @samp{gf} and
1088 @samp{pk} lookups. @samp{-D} is a synonym, for compatibility with
1089 Dvips. Default is 600.
1091 @item --engine=@var{name}
1092 @opindex --engine=@var{name}
1094 Set the engine name to @var{name}. By default it is not set. The
1095 engine name is used in some search paths to allow files with the same
1096 name but used by different engines to coexist.
1098 In particular, since the memory dump files
1099 (@file{.fmt}/@file{.base}/@file{.mem}) are now stored in
1100 subdirectories named for the engine (@file{tex}, @file{pdftex},
1101 @file{xetex}, etc.), you must specify an engine name in order to find
1102 them. For example, @file{cont-en.fmt} typically exists for both
1103 @file{pdftex} and @file{xetex}. With the default path settings, you
1104 can use @samp{--engine=/} to look for any dump file, regardless of
1105 engine; if a dump file exists for more than one engine, it's
1106 indeterminate which one is returned. (The @samp{/} ends up specifying
1107 a normal recursive search along the path where the dumps are stored,
1108 namely @samp{$TEXMF/web2c@{/$engine,@}}.)
1110 @item --format=@var{name}
1111 @opindex --format=@var{name}
1112 Set the format for lookup to @var{name}. By default, the format is
1113 guessed from the filename, with @samp{tex} being used if nothing else
1114 fits. The recognized filename extensions (including any leading
1115 @samp{.}) are also allowable @var{name}s.
1117 All formats also have a name, which is the only way to specify formats
1118 with no associated suffix. For example, for Dvips configuration files
1119 you can use @samp{--format="dvips config"}. (The quotes are for the
1122 Here's the current list of recognized names and the associated suffixes.
1123 @xref{Supported file formats}, for more information on each of these.
1149 graphic/figure: .eps .epsi
1151 TeX system documentation
1154 PostScript header/font: .pro
1157 type1 fonts: .pfa .pfb
1161 truetype fonts: .ttf .ttc
1178 This option and @samp{--path} are mutually exclusive.
1181 @opindex --interactive
1182 @cindex interactive query
1183 After processing the command line, read additional filenames to look up
1184 from standard input.
1186 @item -mktex=@var{filetype}
1187 @itemx -no-mktex=@var{filetype}
1188 @opindex -mktex=@var{filetype}
1189 @opindex -no-mktex=@var{filetype}
1190 Turn on or off the @samp{mktex} script associated with @var{filetype}.
1191 The only values that make sense for @var{filetype} are @samp{pk},
1192 @samp{mf}, @samp{tex}, and @samp{tfm}. By default, all are off in
1193 Kpsewhich. @xref{mktex scripts}.
1195 @item --mode=@var{string}
1196 @opindex --mode=@var{string}
1197 Set the mode name to @var{string}; this also only affects @samp{gf} and
1198 @samp{pk} lookups. No default: any mode will be found. @xref{mktex
1202 @opindex --must-exist
1203 Do everything possible to find the files, notably including searching
1204 the disk. By default, only the @file{ls-R} database is checked, in the
1205 interest of efficiency.
1207 @item --path=@var{string}
1208 @opindex --path=@var{string}
1209 Search along the path @var{string} (colon-separated as usual), instead
1210 of guessing the search path from the filename. @samp{//} and all the
1211 usual expansions are supported (@pxref{Path expansion}). This option
1212 and @samp{--format} are mutually exclusive. To output the complete
1213 directory expansion of a path, instead of doing a one-shot lookup, see
1214 @samp{--expand-path} and @samp{--show-path} in the following section.
1216 @item --progname=@var{name}
1217 @opindex --progname=@var{name}
1218 Set the program name to @var{name}; default is @samp{kpsewhich}. This
1219 can affect the search paths via the @samp{.@var{prognam}} feature in
1220 configuration files (@pxref{Config files}).
1222 @item --subdir=@var{string}
1223 @opindex --subdir=@var{string}
1224 Report only those matches whose directory part @emph{ends} with
1225 @var{string} (compared literally, except case is ignored on a
1226 case-insensitive operating system). For example, suppose there are
1227 two matches for a given name:
1231 @result{} /some/where/foo.sty
1232 /another/place/foo.sty
1236 Then we can narrow the result to what we are interested in with
1240 kpsewhich --subdir=where foo.sty
1241 @result{} /some/where/foo.sty
1243 kpsewhich --subdir=place foo.sty
1244 @result{} /another/place/foo.sty
1248 The string to match must be at the end of the directory part of the
1249 match, and it is taken literally, with no pattern matching:
1252 kpsewhich --subdir=another foo.sty
1257 The string to match may cross directory components:
1260 kpsewhich --subdir=some/where foo.sty
1261 @result{} /some/where/foo.sty
1265 @option{--subdir} implies @option{--all}; if there is more than one
1266 match, they will all be reported (in our example, both @samp{where}
1267 and @samp{place} end in @samp{e}):
1270 kpsewhich --subdir=e
1271 @result{} /some/where/foo.sty
1272 /another/place/foo.sty
1276 Because of the above rules, the presence of a leading @samp{/} is
1277 important, since it ``anchors'' the match to a full component name:
1280 kpsewhich --subdir=/lace foo.sty
1285 However, a trailing @samp{/} is immaterial (and ignored), since the
1286 match always takes place at the end of the directory part:
1289 kpsewhich --subdir=lace/ foo.sty
1290 @result{} /another/place/foo.sty
1294 The purpose of these rules is to make it convenient to find results
1295 only within a particular area of the tree. For instance, a given
1296 script named @file{foo.lua} might exist within both
1297 @file{texmf-dist/scripts/pkg1/} and @file{texmf-dist/scripts/pkg2/}.
1298 By specifying, say, @samp{--subdir=/pkg1}, you can be sure of getting
1299 the one you are interested in.
1301 We only match at the end because a site might happen to install @TeX{}
1302 in @file{/some/coincidental/pkg1/path/}, and we wouldn't want
1303 @file{texmf-dist/scripts/pkg2/} to match that when searching for
1309 @node Specially-recognized files
1310 @subsection Specially-recognized files for @command{kpsewhich}
1312 @command{kpsewhich} recognizes a few special filenames on the command
1313 line and defaults to using the `known' file formats for them, merely
1314 to save the time and trouble of specifying the format. This is only a
1315 feature of @command{kpsewhich}; when using the Kpathsea library
1316 itself, none of these special filenames are recognized, and it's still
1317 up to the caller to specify the desired format.
1319 Here is the list of special filenames to @command{kpsewhich}, along
1320 with their corresponding format:
1328 @flindex dvipdfmx.cfg
1330 @samp{other text files}
1332 @flindex fmtutil.cnf
1336 @flindex glyphlist.txt
1344 @flindex pdfglyphlist.txt
1345 @item pdfglyphlist.txt
1349 @flindex pdftexconfig.tex
1351 @samp{pdftex config} (although @file{pdftex.cfg} is not used any more;
1352 look for the file @file{pdftexconfig.tex} instead.)
1360 A user-specified format will override the above defaults.
1363 Another useful configuration file in this regard is @file{tcfmgr.map},
1364 found in @file{texmf/texconfig/tcfmgr.map}, which records various
1365 information about the above configuration files (among others).
1368 @node Auxiliary tasks
1369 @subsection Auxiliary tasks
1371 @cindex auxiliary tasks
1373 Kpsewhich provides some additional features not strictly related to path
1378 @opindex --debug=@var{num}
1379 @samp{--debug=@var{num}} sets the debugging options to @var{num}.
1383 @opindex --var-value=@var{variable}
1384 @samp{--var-value=@var{variable}} outputs the value of @var{variable},
1385 expanding @samp{$} (@pxref{Variable expansion} and @samp{~} (@pxref{Tilde
1386 expansion}) constructs, but not performing other expansions.
1389 @opindex --expand-braces=@var{string}
1390 @samp{--expand-braces=@var{string}} outputs the variable and brace
1391 expansion of @var{string}. @xref{Path expansion}.
1394 @opindex --expand-var=@var{string}
1395 @samp{--expand-var=@var{string}} outputs the variable and tilde
1396 expansion of @var{string}. For example, the @samp{mktex@dots{}}
1397 scripts run @samp{kpsewhich --expand-var='$TEXMF'} to find the root of
1398 the @TeX{} system hierarchy. @xref{Path expansion}.
1401 @opindex --expand-path=@var{string}
1402 @samp{--expand-path=@var{string}} outputs the complete expansion of
1403 @var{string}, with each element separated by the usual path separator
1404 on the current system (@samp{;} on Windows, @samp{:} otherwise).
1405 This may be useful to construct a custom search path for a format not
1406 otherwise supported. To retrieve the search path for a format that is
1407 already supported, see @samp{--show-path}, next.
1409 Nonexistent directories are culled from the output:
1412 $ kpsewhich --expand-path '/tmp'
1414 $ kpsewhich --expand-path '/nonesuch'
1418 For one-shot uses of an arbitrary (not built in to Kpathsea) path, see
1419 @samp{--path} in the previous section.
1422 @opindex --show-path=@var{name}
1423 @samp{--show-path=@var{name}} shows the path that would be used for file
1424 lookups of file type @var{name}. Either a filename extension
1425 (@samp{pk}, @samp{.vf}, etc.) or an integer can be used, just as with
1426 @samp{--format}, described in the previous section.
1431 @node Standard options
1432 @subsection Standard options
1434 @cindex standard options
1436 Kpsewhich accepts the standard GNU options:
1441 @samp{--help} prints a help message on standard output and exits.
1445 @samp{--version} prints the Kpathsea version number and exits.
1450 @chapter @TeX{} support
1452 @cindex @TeX{} support
1454 Although the basic features in Kpathsea can be used for any type of path
1455 searching, it came about (like all libraries) with a specific
1456 application in mind: I wrote Kpathsea specifically for @TeX{} system
1457 programs. I had been struggling with the programs I was using (Dvips,
1458 Xdvi, and @TeX{} itself) having slightly different notions of how to
1459 specify paths; and debugging was painful, since no code was shared.
1461 Therefore, Kpathsea provides some @TeX{}-specific formats and features.
1462 Indeed, many of the supposedly generic path searching features were
1463 provided because they seemed useful in that con@TeX{}t (font lookup,
1466 Kpathsea provides a standard way to search for files of any of the
1467 supported file types; glyph fonts are a bit different than all the rest.
1468 Searches are based solely on filenames, not file contents---if a GF
1469 file is named @file{cmr10.600pk}, it will be found as a PK file.
1472 * Supported file formats:: File types Kpathsea knows about.
1473 * File lookup:: Searching for most kinds of files.
1474 * Glyph lookup:: Searching for bitmap fonts.
1475 * Suppressing warnings:: Avoiding warnings via TEX_HUSH.
1479 @node Supported file formats
1480 @section Supported file formats
1482 @cindex supported file formats
1483 @cindex file formats, supported
1485 @cindex environment variables for @TeX{}
1486 @cindex @TeX{} environment variables
1488 Kpathsea has support for a number of file types. Each file type has a
1489 list of environment and config file variables that are checked to define
1490 the search path, and most have a default suffix that plays a role in
1491 finding files (see the next section). Some also define additional
1492 suffixes, and/or a program to be run to create missing files on the fly.
1494 @cindex program-varying paths
1495 Since environment variables containing periods, such as
1496 @samp{TEXINPUTS.latex}, are not allowed on some systems, Kpathsea looks
1497 for environment variables with an underscore, e.g.,
1498 @samp{TEXINPUTS_latex} (@pxref{Config files}).
1500 The following table lists the above information.
1506 (Adobe font metrics, @pxref{Metric files,,, dvips, Dvips})
1514 (Metafont memory dump, @pxref{Memory dumps,,, web2c, Web2c})
1515 @code{MFBASES}, @code{TEXMFINI};
1516 suffix @samp{.base}.
1522 (Bib@TeX{} bibliography source, @pxref{bibtex invocation,,, web2c, Web2c})
1523 @code{BIBINPUTS}, @code{TEXBIB};
1529 (Bib@TeX{} style file, @pxref{Basic BibTeX style files,, Basic Bib@TeX{}
1530 style files, web2c, Web2c})
1537 (character map files)
1539 suffix @samp{.cmap}.
1544 (Runtime configuration files, @pxref{Config files})
1554 suffixes @samp{.w}, @samp{.web};
1555 additional suffix @samp{.ch}.
1559 @flindex config.ps@r{, search path for}
1560 (Dvips @samp{config.*} files, such as @file{config.ps}, @pxref{Config
1561 files,,, dvips, Dvips})
1575 (@TeX{} memory dump, @pxref{Memory dumps,,, web2c, Web2c})
1576 @code{TEXFORMATS}, @code{TEXMFINI};
1584 (generic font bitmap, @pxref{Glyph files,,, dvips, Dvips})
1585 @code{@var{program}FONTS}, @code{GFFONTS}, @code{GLYPHFONTS}, @code{TEXFONTS};
1588 @item graphic/figure
1593 (Encapsulated PostScript figures, @pxref{PostScript figures,,, dvips, Dvips})
1594 @code{TEXPICTS}, @code{TEXINPUTS};
1595 additional suffixes: @samp{.eps}, @samp{.epsi}.
1599 @vindex TEXINDEXSTYLE
1601 (makeindex style files)
1602 @code{TEXINDEXSTYLE}, @code{INDEXSTYLE};
1608 (ligature definition files)
1615 (Filename databases, @pxref{Filename database})
1621 (Fontmaps, @pxref{Fontmap})
1629 (MetaPost memory dump, @pxref{Memory dumps,,, web2c, Web2c})
1630 @code{MPMEMS}, @code{TEXMFINI};
1633 @item @r{MetaPost support}
1635 (MetaPost support files, used by DMP; @pxref{dmp invocation,,, web2c, Web2c})
1641 (Metafont source, @pxref{mf invocation,,, web2c, Web2c})
1644 dynamic creation program: @code{mktexmf}.
1649 (Metafont program strings, @pxref{pooltype invocation,,, web2c, Web2c})
1650 @code{MFPOOL}, @code{TEXMFINI};
1651 suffix @samp{.pool}.
1656 (@code{MFT} style file, @pxref{mft invocation,,, web2c, Web2c})
1662 (font-related files that don't fit the other categories)
1668 (MetaPost source, @pxref{mpost invocation,,, web2c, Web2c})
1675 (MetaPost program strings, @pxref{pooltype invocation,,, web2c, Web2c})
1676 @code{MPPOOL}, @code{TEXMFINI};
1677 suffix @samp{.pool}.
1682 (Omega compiled process files)
1683 @code{OCPINPUTS}; @*
1685 dynamic creation program: @code{MakeOmegaOCP}.
1690 (Omega font metrics)
1691 @code{OFMFONTS}, @code{TEXFONTS}; @*
1692 suffixes @samp{.ofm}, @samp{.tfm};
1693 dynamic creation program: @code{MakeOmegaOFM}.
1695 @item opentype fonts
1696 @vindex OPENTYPEFONTS
1698 @code{OPENTYPEFONTS}.
1702 (Omega property lists)
1703 @code{OPLFONTS}, @code{TEXFONTS};
1709 (Omega translation process files)
1716 (Omega virtual fonts)
1717 @code{OVFFONTS}, @code{TEXFONTS};
1723 (Omega virtual property lists)
1724 @code{OVPFONTS}, @code{TEXFONTS};
1728 @vindex PDFTEXCONFIG
1729 (PDF@TeX{}-specific configuration files)
1730 @code{PDFTEXCONFIG}.
1738 (packed bitmap fonts, @pxref{Glyph files,,, dvips, Dvips})
1739 @code{@var{PROGRAM}FONTS} (@var{program} being @samp{XDVI}, etc.),
1740 @code{PKFONTS}, @code{TEXPKS}, @code{GLYPHFONTS}, @code{TEXFONTS};
1742 dynamic creation program: @code{mktexpk}.
1744 @item PostScript header
1746 @vindex TEXPSHEADERS
1748 (downloadable PostScript, @pxref{Header files,,, dvips, Dvips})
1749 @code{TEXPSHEADERS}, @code{PSHEADERS};
1750 additional suffix @samp{.pro}.
1752 @item subfont definition files
1755 (subfont definition files)
1762 (@TeX{} source, @pxref{tex invocation,,, web2c, Web2c})
1765 additional suffixes: none, because such a list cannot be complete;
1766 dynamic creation program: @code{mktextex}.
1768 @item TeX system documentation
1771 (Documentation files for the @TeX{} system)
1774 @item TeX system sources
1775 @flindex source files
1777 (Source files for the @TeX{} system)
1781 @vindex TEXMFSCRIPTS
1782 (Architecture-independent executables distributed in the texmf tree)
1783 @code{TEXMFSCRIPTS}.
1788 (@TeX{} program strings, @pxref{pooltype invocation,,, web2c, Web2c})
1789 @code{TEXPOOL}, @code{TEXMFINI};
1790 suffix @samp{.pool}.
1796 (@TeX{} font metrics, @pxref{Metric files,,, dvips, Dvips})
1797 @code{TFMFONTS}, @code{TEXFONTS};
1799 dynamic creation program: @code{mktextfm}.
1803 (Troff fonts, used by DMP; @pxref{DMP invocation,,, web2c, Web2c})
1806 @item truetype fonts
1810 (TrueType outline fonts) @code{TTFONTS}; suffixes @samp{.ttf},
1818 @vindex TEXPSHEADERS
1819 @vindex DVIPSHEADERS
1820 (Type 1 PostScript outline fonts, @pxref{Glyph files,,, dvips, Dvips})
1821 @code{T1FONTS}, @code{T1INPUTS}, @code{TEXPSHEADERS}, @code{DVIPSHEADERS};
1822 suffixes @samp{.pfa}, @samp{.pfb}.
1826 (Type 42 PostScript outline fonts) @code{T42FONTS}.
1832 (virtual fonts, @pxref{Virtual fonts,,, dvips, Dvips})
1833 @code{VFFONTS}, @code{TEXFONTS};
1842 additional suffix @samp{.ch}.
1846 (files specific to the web2c implementation)
1850 There are two special cases, because the paths and environment variables
1851 always depend on the name of the program: the variable name is
1852 constructed by converting the program name to upper case, and then
1853 appending @samp{INPUTS}. Assuming the program is called @samp{foo},
1854 this gives us the following table.
1857 @item other text files
1859 (text files used by @samp{foo})
1862 @item other binary files
1864 (binary files used by @samp{foo})
1868 If an environment variable by these names are set, the corresponding
1869 @file{texmf.cnf} definition won't be looked at (unless, as usual, the
1870 environment variable value has an extra @samp{:}). @xref{Default
1873 For the font variables, the intent is that:
1876 @code{TEXFONTS} is the default for everything.
1879 @code{GLYPHFONTS} is the default for bitmap (or, more precisely,
1883 Each font format has a variable of its own.
1888 Each program has its own font override path as well; e.g.,
1889 @code{DVIPSFONTS} for Dvipsk. Again, this is for bitmaps, not metrics.
1895 @section File lookup
1898 @cindex searching for files
1899 @cindex @TeX{} file lookup
1901 This section describes how Kpathsea searches for most files (bitmap font
1902 searches are the exception, as described in the next section).
1904 Here is the search strategy for a file @var{name}:
1908 If the file format defines default suffixes, and the suffix of
1909 @var{name} name is not already a known suffix for that format, try the
1910 name with each default appended, and use alternative names found in
1911 the fontmaps if necessary. Example: given @samp{foo.bar}, look for
1915 Search for @var{name}, and if necessary for alternative names found in
1916 the fontmaps. Example: given @samp{foo.bar}, we also look for
1920 If the file format defines a program to invoke to create missing files,
1921 run it (@pxref{mktex scripts}).
1924 @cindex extensions, filename
1925 @cindex suffixes, filename
1926 @vindex try_std_extension_first
1927 The order in which we search for ``suffixed'' name (item@tie{}1) or
1928 the ``as-is'' name (item@tie{}2) is controlled by the
1929 @file{try_std_extension_first} configuration value. The default set
1930 in @file{texmf.cnf} is true, since common suffixes are already
1931 recognized: @samp{babel.sty} will only look for @samp{babel.sty}, not
1932 @samp{babel.sty.tex}, regardless of this setting.
1934 When the suffix is unknown (e.g., @samp{foo.bar}), both names are
1935 always tried; the difference is the order in which they are tried.
1937 @file{try_std_extension_first} only affects names being looked up
1938 which *already* have an extension. A name without an extension (e.g.,
1939 @samp{tex story}) will always have an extension added first.
1942 @findex kpse_find_file
1943 This algorithm is implemented in the routine @code{kpse_find_file} in
1944 @file{kpathsea/tex-file.c}. You can watch it in action with the
1945 debugging options (@pxref{Debugging}).
1949 @section Glyph lookup
1951 @cindex glyph lookup
1952 @cindex searching for glyphs
1953 @cindex @TeX{} glyph lookup
1955 This section describes how Kpathsea searches for a bitmap font in GF or
1956 PK format (or either) given a font name (e.g., @samp{cmr10}) and a
1957 resolution (e.g., 600).
1959 Here is an outline of the search strategy (details in the sections
1960 below) for a file @var{name} at resolution @var{dpi}. The search stops
1961 at the first successful lookup.
1965 Look for an existing file @var{name}.@var{dpi}@var{format} in the
1966 specified format(s).
1968 @item If @var{name} is an alias for a file @var{f} in the fontmap
1969 file @file{texfonts.map}, look for @var{f}.@var{dpi}.
1971 @item Run an external program (typically named @samp{mktexpk}) to
1972 generate the font (@pxref{mktex scripts})
1974 @item Look for @var{fallback}.@var{dpi}, where @var{fallback} is some
1975 last-resort font (typically @samp{cmr10}).
1978 @flindex tex-glyph.c
1979 @findex kpse_find_glyph_format
1980 This is implemented in @code{kpse_find_glyph_format} in
1981 @file{kpathsea/tex-glyph.c}.
1984 * Basic glyph lookup:: Features common to all glyph lookups.
1985 * Fontmap:: Aliases for fonts.
1986 * Fallback font:: Resolutions and fonts of last resort.
1990 @node Basic glyph lookup
1991 @subsection Basic glyph lookup
1993 @cindex basic glyph lookup
1994 @cindex common features in glyph lookup
1996 When Kpathsea looks for a bitmap font @var{name} at resolution @var{dpi}
1997 in a format @var{format}, it first checks each directory in the search
1998 path for a file @samp{@var{name}.@var{dpi}@var{format}}; for example,
1999 @samp{cmr10.600pk}. Kpathsea looks for a PK file first, then a GF file.
2001 If that fails, Kpathsea looks for
2002 @samp{dpi@var{dpi}/@var{name}.@var{format}}; for example,
2003 @samp{dpi600/cmr10.pk}. This is how fonts are typically stored on
2004 filesystems (such as DOS) that permit only three-character extensions.
2006 @cindex tolerance for glyph lookup
2007 @cindex glyph lookup bitmap tolerance
2008 @findex KPSE_BITMAP_TOLERANCE
2009 If that fails, Kpathsea looks for a font with a close-enough @var{dpi}.
2010 ``Close enough'' is defined by the macro @code{KPSE_BITMAP_TOLERANCE} in
2011 @file{kpathsea/tex-glyph.h} to be @code{@var{dpi} / 500 + 1}. This is
2012 slightly more than the 0.2% minimum allowed by the DVI standard
2013 (@url{@var{CTAN:}/dviware/driv-standard/level-0}).
2019 @cindex fontmap files
2020 @cindex font alias files
2021 @cindex aliases for fonts
2023 @flindex texfonts.map
2024 If a bitmap font or metric file is not found with the original name (see
2025 the previous section), Kpathsea looks through any @dfn{fontmap} files
2026 for an @dfn{alias} for the original font name. These files are named
2027 @file{texfonts.map} and searched for along the @code{TEXFONTMAPS}
2028 environment/config file variable. All @file{texfonts.map} files that
2029 are found are read; earlier definitions override later ones.
2031 This feature is intended to help in two respects:
2036 @cindex fontnames, arbitrary length
2037 An alias name is limited in length only by available memory, not by your
2038 filesystem. Therefore, if you want to ask for @samp{Times-Roman}
2039 instead of @file{ptmr}, you can (you get @samp{ptmr8r}).
2042 @cindex circle fonts
2044 A few fonts have historically had multiple names: specifically,
2045 La@TeX{}'s ``circle font'' has variously been known as @file{circle10},
2046 @file{lcircle10}, and @file{lcirc10}. Aliases can make all the names
2047 equivalent, so that it no longer matters what the name of the installed
2048 file is; @TeX{} documents will find their favorite name.
2052 The format of fontmap files is straightforward:
2055 @cindex comments, in fontmap files
2056 @item Comments start with @samp{%} and continue to the end of the line.
2057 @cindex whitespace, in fontmap files
2058 @item Blank lines are ignored.
2059 @item Each nonblank line is broken up into a series of @dfn{words}:
2060 a sequence of non-whitespace characters.
2061 @findex include @r{fontmap directive}
2062 @item If the first word is @samp{include}, the second word is used as
2063 a filename, and it is searched for and read.
2064 @item Otherwise, the first word on each line is the true filename;
2065 @item the second word is the alias;
2066 @item subsequent words are ignored.
2069 If an alias has an extension, it matches only those files with that
2070 extension; otherwise, it matches anything with the same root, regardless
2071 of extension. For example, an alias @samp{foo.tfm} matches only when
2072 @file{foo.tfm} is being searched for; but an alias @samp{foo} matches
2073 @file{foo.vf}, @file{foo.600pk}, etc.
2075 As an example, here is an excerpt from the @file{texfonts.map} in the
2076 Web2c distribution. It makes the circle fonts equivalent and includes
2077 automatically generated maps for most PostScript fonts available from
2078 various font suppliers.
2090 include bitstrea.map
2094 Fontmaps are implemented in the file @file{kpathsea/fontmap.c}.
2095 The Fontname distribution has much more information on font naming
2096 (@pxref{Introduction,,, fontname, Filenames for @TeX{} fonts}).
2100 @subsection Fallback font
2102 @cindex fallback font
2103 @cindex fallback resolutions
2104 @cindex font of last resort
2105 @cindex resolutions, last-resort
2106 @cindex last-resort font
2112 @vindex default_texsizes
2113 If a bitmap font cannot be found or created at the requested size,
2114 Kpathsea looks for the font at a set of @dfn{fallback resolutions}. You
2115 specify these resolutions as a colon-separated list (like search paths).
2116 Kpathsea looks first for a program-specific environment variable (e.g.,
2117 @code{DVIPSSIZES} for Dvipsk), then the environment variable
2118 @code{TEXSIZES}, then a default specified at compilation time (the Make
2119 variable @code{default_texsizes}). You can set this list to be empty if
2120 you prefer to find fonts at their stated size or not at all.
2122 @flindex cmr10@r{, as fallback font}
2123 @vindex kpse_fallback_font
2124 Finally, if the font cannot be found even at the fallback resolutions,
2125 Kpathsea looks for a fallback font, typically @file{cmr10}. Programs
2126 must enable this feature by assigning to the global variable
2127 @code{kpse_fallback_font} or calling @code{kpse_init_prog}
2128 (@pxref{Calling sequence}); the default is no fallback font.
2131 @node Suppressing warnings
2132 @section Suppressing warnings
2134 @cindex warnings, suppressing
2135 @cindex suppressing warnings
2138 Kpathsea provides a way to suppress selected usually-harmless warnings;
2139 this is useful at large sites where most users are not administrators,
2140 and thus the warnings are merely a source of confusion, not a help. To
2141 do this, you set the environment variable or configuration file value
2142 @code{TEX_HUSH} to a colon-separated list of values. Here are the
2147 Suppress everything possible.
2150 @cindex mismatched checksum warnings
2151 Suppress mismatched font checksum warnings.
2154 @cindex missing character warnings
2155 Suppress warnings when a character is missing from a font that a DVI or
2156 VF file tries to typeset.
2159 Don't suppress any warnings.
2162 @cindex unreadable file warnings
2163 Suppress warnings about attempts to access a file whose permissions
2164 render it unreadable.
2167 @cindex unknown special warnings
2168 @findex \special@r{, suppressing warnings about}
2169 Suppresses warnings about an unimplemented or unparsable
2170 @samp{\special} command.
2173 @noindent @file{tex-hush.c} defines the function that checks the
2174 variable value. Each driver implements its own checks where
2179 @chapter Programming
2181 This chapter is for programmers who wish to use Kpathsea.
2182 @xref{Introduction}, for the conditions under which you may do so.
2185 * Overview: Programming overview. Introduction.
2186 * Calling sequence:: Specifics of what to call.
2187 * Program-specific files:: How to handle these.
2188 * Config: Programming with config files. Getting info from texmf.cnf.
2192 @node Programming overview
2193 @section Programming overview
2195 @cindex programming overview
2196 @cindex overview of programming with Kpathsea
2198 Aside from this manual, your best source of information is the source to
2199 the programs I've modified to use Kpathsea (@pxref{Introduction}). Of
2200 those, Dviljk is probably the simplest, and hence a good place to start.
2201 Xdvik adds VF support and the complication of X resources. Dvipsk adds
2202 the complication of its own config files. Web2c is source code I also
2203 maintain, so it uses Kpathsea rather straightforwardly, but is of course
2204 complicated by the Web to C translation. Finally, Kpsewhich is a small
2205 utility program whose sole purpose is to exercise the main
2206 path-searching functionality.
2208 @flindex pathsearch.h
2210 @flindex tex-glyph.h
2212 Beyond these examples, the @file{.h} files in the Kpathsea source
2213 describe the interfaces and functionality (and of course the @file{.c}
2214 files define the actual routines, which are the ultimate documentation).
2215 @file{pathsearch.h} declares the basic searching routine.
2216 @file{tex-file.h} and @file{tex-glyph.h} define the interfaces for
2217 looking up particular kinds of files. In view of the way the headers
2218 depend on each other, it is recommended to use @code{#include
2219 <kpathsea/kpathsea.h>}, which includes every Kpathsea header.
2223 If you want to include only specific headers, you should still consider
2224 including @file{kpathsea/config.h} before including any other Kpathsea
2225 header, as it provides symbols used in the other headers. Note that
2226 @file{kpathsea/config.h} includes @file{kpathsea/c-auto.h}, which is
2227 generated by Autoconf.
2229 @cindex file types, registering new
2230 The library provides no way for an external program to register new file
2231 types: @file{tex-file.[ch]} must be modified to do this. For example,
2232 Kpathsea has support for looking up Dvips config files, even though no
2233 program other than Dvips will likely ever want to do so. I felt this
2234 was acceptable, since along with new file types should also come new
2235 defaults in @file{texmf.cnf} (and its descendant @file{paths.h}), since
2236 it's simplest for users if they can modify one configuration file for
2239 Kpathsea does not parse any formats itself; it barely opens any files.
2240 Its primary purpose is to return filenames. The GNU font utilities does
2241 contain libraries to read TFM, GF, and PK files, as do the programs
2245 @node Calling sequence
2246 @section Calling sequence
2248 @cindex programming with Kpathsea
2249 @cindex calling sequence
2251 The typical way to use Kpathsea in your program goes something like this:
2256 @findex kpse_set_program_name
2258 Call @code{kpse_set_program_name} with @code{argv[0]} as the first
2259 argument; the second argument is a string or @code{NULL}. The second
2260 argument is used by Kpathsea as the program name for the
2261 @code{.@var{program}} feature of config files (@pxref{Config files}).
2262 If the second argument is @code{NULL}, the value of the first argument
2263 is used. This function must be called before any other use of the
2266 @vindex program_invocation_name
2267 @vindex program_invocation_short_name
2268 @vindex kpse_program_name
2269 @cindex error message macros
2270 @code{kpse_set_program_name} always sets the global variables
2271 @code{program_invocation_name} and @code{program_invocation_short_name}.
2272 These variables are used in the error message macros defined in
2273 @file{kpathsea/lib.h}. It sets the global variable
2274 @code{kpse_program_name} to the program name it uses.
2276 @vindex KPATHSEA_DEBUG
2277 It also initializes debugging options based on the environment
2278 variable @code{KPATHSEA_DEBUG} (if that is set).
2282 @cindex SELFAUTOPARENT
2283 @cindex symlinks, resolving
2284 @cindex expanding symlinks
2285 Finally, it sets the variables @code{SELFAUTOLOC}, @code{SELFAUTODIR}
2286 and @code{SELFAUTOPARENT} to the location, parent and grandparent
2287 directory of the executable, removing @file{.} and @file{..} path
2288 elements and resolving symbolic links. These are used in the default
2289 configuration file to allow people to invoke TeX from anywhere. You
2290 can use @samp{kpsewhich --expand-var=\$SELFAUTOLOC}, etc., to see the
2294 @findex kpse_set_progname
2296 The @code{kpse_set_progname} is deprecated. A call to
2297 @code{kpse_set_progname} with @code{argv[0]} is equivalent to a call of
2298 @code{kpse_set_program_name} with first argument @code{argv[0]} and
2299 second argument @code{NULL}. The function is deprecated because it
2300 cannot ensure that the @code{.@var{program}} feature of config files
2301 will always work (@pxref{Config files}).
2304 @vindex kpathsea_debug @r{variable}
2305 @cindex debugging options, in Kpathsea-using program
2306 Set debugging options. @xref{Debugging}. If your program doesn't have a
2307 debugging option already, you can define one and set
2308 @code{kpathsea_debug} to the number that the user supplies (as in Dviljk
2309 and Web2c), or you can just omit this altogether (people can always set
2310 @code{KPATHSEA_DEBUG}). If you do have runtime debugging already, you
2311 need to merge Kpathsea's options with yours (as in Dvipsk and Xdvik).
2314 @vindex client_path @r{in @code{kpse_format_info}}
2315 @vindex kpse_format_info
2317 @cindex config files, for Kpathsea-using programs
2318 If your program has its own configuration files that can define search
2319 paths, you should assign those paths to the @code{client_path} member in
2320 the appropriate element of the @code{kpse_format_info} array. (This
2321 array is indexed by file type; see @file{tex-file.h}.) See
2322 @file{resident.c} in Dvipsk for an example.
2325 @findex kpse_init_prog
2327 Call @code{kpse_init_prog} (see @file{proginit.c}). It's useful for the
2328 DVI drivers, at least, but for other programs it may be simpler to
2329 extract the parts of it that actually apply. This does not initialize
2330 any paths, it just looks for (and sets) certain environment variables
2331 and other random information. (A search path is always initialized at
2332 the first call to find a file of that type; this eliminates much useless
2333 work, e.g., initializing the Bib@TeX{} search paths in a DVI driver.)
2337 @findex kpse_find_file
2338 The routine to actually find a file of type @var{format} is
2339 @code{kpse_find_@var{format}}, defined in @file{tex-file.h}. These are
2340 macros that expand to a call to @file{kpse_find_file}. You can call,
2341 say, @code{kpse_find_tfm} after doing only the first of the
2342 initialization steps above---Kpathsea automatically reads the
2343 @file{texmf.cnf} generic config files, looks for environment variables,
2344 and does expansions at the first lookup.
2347 To find PK and/or GF bitmap fonts, the routines are @code{kpse_find_pk},
2348 @code{kpse_find_gf} and @code{kpse_find_glyph}, defined in
2349 @file{tex-glyph.h}. These return a structure in addition to the
2350 resultant filename, because fonts can be found in so many ways. See the
2351 documentation in the source.
2354 @findex kpse_open_file
2355 To actually open a file, not just return a filename, call
2356 @code{kpse_open_file}. This function takes the name to look up and a
2357 Kpathsea file format as arguments, and returns the usual @code{FILE *}.
2358 It always assumes the file must exist, and thus will search the disk if
2359 necessary (unless the search path specified @samp{!!}, etc.). In other
2360 words, if you are looking up a VF or some other file that need not
2361 exist, don't use this.
2365 @cindex hash table routines
2366 @cindex memory allocation routines
2367 @cindex string routines
2368 @cindex reading arbitrary-length lines
2369 @cindex input lines, reading
2370 @cindex lines, reading arbitrary-length
2371 Kpathsea also provides many utility routines. Some are generic: hash
2372 tables, memory allocation, string concatenation and copying, string
2373 lists, reading input lines of arbitrary length, etc. Others are
2374 filename-related: default path, tilde, and variable expansion,
2375 @code{stat} calls, etc. (Perhaps someday I'll move the former to a
2379 @pindex autoconf@r{, recommended}
2380 The @file{c-*.h} header files can also help your program adapt to many
2381 different systems. You will almost certainly want to use Autoconf for
2382 configuring your software if you use Kpathsea; I strongly recommend
2383 using Autoconf regardless. It is available from
2384 @url{ftp://prep.ai.mit.edu/pub/gnu/}.
2387 @node Program-specific files
2388 @section Program-specific files
2390 Many programs will need to find some configuration files. Kpathsea
2391 contains some support to make it easy to place them in their own
2392 directories. The Standard @TeX{} directory structure (@pxref{Top,,
2393 Introduction, tds, A Directory Structure for @TeX{} files}), specifies
2394 that such files should go into a subdirectory named after the program,
2395 like @samp{texmf/ttf2pk}.
2397 Two special formats, @samp{kpse_program_text_format} and
2398 @samp{kpse_program_binary_format} exist, which use
2399 @code{.:$TEXMF/@var{program}//} as their compiled-in search path. To
2400 override this default, you can use the variable
2401 @code{@var{PROGRAM}INPUTS} in the environment and/or @samp{texmf.cnf}.
2402 That is to say, the name of the variable is constructed by converting
2403 the name of the program to upper case, and appending @code{INPUTS}.
2405 The only difference between these two formats is whether
2406 @code{kpse_open_file} will open the files it finds in text or binary
2410 @node Programming with config files
2411 @section Programming with config files
2413 @cindex programming with config files
2414 @cindex config files, programming with
2416 You can (and probably should) use the same @code{texmf.cnf}
2417 configuration file that Kpathsea uses for your program. This helps
2418 installers by keeping all configuration in one place.
2420 @findex kpse_var_value
2422 @vindex shell_escape@r{, example for code}
2423 To retrieve a value @var{var} from config files, the best way is to call
2424 @code{kpse_var_value} on the string @code{@var{var}}. This will look
2425 first for an environment variable @var{var}, then a config file value.
2426 The result will be the value found or @samp{NULL}. This function is
2427 declared in @file{kpathsea/variable.h}. For an example, see the
2428 @code{shell_escape} code in @file{web2c/lib/texmfmp.c}.
2430 The routine to do variable expansion in the context of a search path (as
2431 opposed to simply retrieving a value) is @code{kpse_var_expand}, also
2432 declared in @file{kpathsea/variable.h}. It's generally only necessary
2433 to set the search path structure components as explained in the previous
2434 section, rather than using this yourself.
2436 @findex kpse_cnf_get
2438 If for some reason you want to retrieve a value @emph{only} from a
2439 config file, not automatically looking for a corresponding environment
2440 variable, call @code{kpse_cnf_get} (declared in @file{kpathsea/cnf.h})
2441 with the string @var{var}.
2443 No initialization calls are needed.