2
@setfilename kpathsea.info
3
@settitle Kpathsea: A library for path searching
6
@set month-year January 2007
8
@c Define new indices for commands, filenames, and options.
13
@c Put everything in one index (arbitrarily chosen to be the concept index).
25
* Kpathsea: (kpathsea). File lookup along search paths.
26
* kpsewhich: (kpathsea)Invoking kpsewhich. TeX file searching.
27
* mktexmf: (kpathsea)mktex scripts. MF source generation.
28
* mktexpk: (kpathsea)mktex scripts. PK bitmap generation.
29
* mktextex: (kpathsea)mktex scripts. TeX source generation.
30
* mktextfm: (kpathsea)mktex scripts. TeX font metric generation.
31
* mktexlsr: (kpathsea)Filename database. Update ls-R.
35
This file documents the Kpathsea library for path searching.
37
Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
38
2004, 2005, 2007 Karl Berry & Olaf Weber.
40
Permission is granted to make and distribute verbatim copies of this
41
manual provided the copyright notice and this permission notice are
42
preserved on all copies.
45
Permission is granted to process this file through TeX and print the
46
results, provided the printed document carries a copying permission
47
notice identical to this one except for the removal of this paragraph
48
(this paragraph not being relevant to the printed manual).
51
Permission is granted to copy and distribute modified versions of this
52
manual under the conditions for verbatim copying, provided that the
53
entire resulting derived work is distributed under the terms of a
54
permission notice identical to this one.
56
Permission is granted to copy and distribute translations of this manual
57
into another language, under the above conditions for modified versions,
58
except that this permission notice may be stated in a translation
59
approved by the Free Software Foundation.
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
81
This manual documents how to install and use the Kpathsea library for
82
filename lookup. It corresponds to version @value{version},
83
released in @value{month-year}.
86
* Introduction:: Overview.
87
* Installation:: Compilation, installation, and bug reporting.
89
* Path searching:: How filename lookups work.
90
* TeX support:: Special support for TeX-related file lookups.
92
* Programming:: How to use Kpathsea features in your program.
94
* Index:: General index.
100
@chapter Introduction
103
@cindex fundamental purpose of Kpathsea
105
This manual corresponds to version @value{version} of the Kpathsea
106
library, released in @value{month-year}.
108
The library's fundamental purpose is to return a filename from a list of
109
directories specified by the user, similar to what shells do when
110
looking up program names to execute.
112
@cindex programs using the library
113
The following software, all of which we maintain, uses this library:
116
@item Dviljk (see the @samp{dvilj} man page)
117
@item Dvipsk (@pxref{Top, , Introduction, dvips, Dvips: A DVI driver})
118
@item GNU font utilities (@pxref{Top, , Introduction, fontu, GNU font
120
@item Web2c (@pxref{Top, , Introduction, web2c, Web2c: A @TeX{}
122
@item Xdvik (see the @samp{xdvi} man page)
125
@noindent Other software that we do not maintain also uses it.
127
@cindex interface, not frozen
128
@cindex comments, making
129
@cindex suggestions, making
130
We are still actively maintaining the library (and probably always will
131
be, despite our hopes). If you have comments or suggestions, please send
132
them to us (@pxref{Reporting bugs}).
134
@cindex conditions for use
135
@cindex license for using the library
136
@cindex GNU General Public License
137
We distribute the library under the GNU Library General Public License
138
(LGPL). In short, this means if you write a program using the library,
139
you must (offer to) distribute the source to the library, along with any
140
changes you have made, and allow anyone to modify the library source and
141
distribute their modifications. It does not mean you have to distribute
142
the source to your program, although we hope you will. See the files
143
@file{GPL} and @file{LGPL} for the text of the GNU licenses.
145
@cindex @TeX{} Users Group
146
If you know enough about @TeX{} to be reading this manual, then you (or
147
your institution) should consider joining the @TeX{} Users Group (if
148
you're already a member, great!). TUG produces the periodical
149
@cite{TUGboat}, sponsors an annual meeting and publishes the
150
proceedings, and arranges courses on @TeX{} for all levels of users
151
throughout the world. Anyway, here is the address:
153
@flindex tug@@tug.org
157
Portland OR 97208-2311
159
phone: +1 503 223-9994
161
email: @email{tug@@tug.org}
172
@cindex history of Kpathsea
174
@cindex Knuth, Donald E.
175
(This section is for those people who are curious about how the library
176
came about.) (If you like to read historical accounts of software, we
177
urge you to seek out the GNU Autoconf manual and the ``Errors of
178
@TeX{}'' paper by Don Knuth, published in @cite{Software---Practice and
179
Experience} 19(7), July 1989.)
186
@pindex pxp @r{Pascal preprocessor}
187
@pindex pc @r{Pascal compiler}
188
[Karl writes.] My first ChangeLog entry for Web2c seems to be February
189
1990, but I may have done some work before then. In any case, Tim
190
Morgan and I were jointly maintaining it for a time. (I should mention
191
here that Tim had made Web2c into a real distribution long before I had
192
ever used it or even heard of it, and Tom Rokicki did the original
193
implementation. I was using @code{pxp} and @code{pc} on VAX 11/750's
194
and the hot new Sun 2 machines.)
196
It must have been later in 1990 and 1991 that I started working on
197
@cite{@TeX{} for the Impatient}. Dvips, Xdvi, Web2c, and the GNU
198
fontutils (which I was also writing at the time) all used different
199
environment variables, and, more importantly, had different bugs in
200
their path searching. This became extremely painful, as I was stressing
201
everything to the limit working on the book. I also desperately wanted
202
to implement subdirectory searching, since I couldn't stand putting
203
everything in one big directory, and also couldn't stand having to
204
explicitly specify @file{cm}, @file{pandora}, @dots{} in a path.
207
In the first incarnation, I just hacked separately on each
208
program---that was the original subdirectory searching code in both Xdvi
209
and Dvips, though I think Paul Vojta has completely rewritten Xdvi's
210
support by now. That is, I tried to go with the flow in each program,
211
rather than changing the program's calling sequences to conform to
214
Then, as bugs inevitably appeared, I found I was fixing the same thing
215
three times (Web2c and fontutils were always sharing code, since I
216
maintained those---there was no Dvipsk or Xdvik or Dviljk at this
217
point). After a while, I finally started sharing source files. They
218
weren't yet a library, though. I just kept things up to date with shell
219
scripts. (I was developing on a 386 running ISC 2.2 at the time, and so
220
didn't have symbolic links. An awful experience.)
222
@cindex MacKenzie, David
223
The ChangeLogs for Xdvik and Dvipsk record initial releases of those
224
distributions in May and June 1992. I think it was because I was tired
225
of the different configuration strategies of each program, not so much
226
because of the path searching. (Autoconf was being developed by David
227
MacKenzie and others, and I was adapting it to @TeX{} and friends.)
230
I started to make a separate library that other programs could link with
231
on my birthday in April 1993, according to the ChangeLog. I don't
232
remember exactly why I finally took the time to make it a separate
233
library; a conversation with david zuhn that initiated it. Just seemed
236
@cindex Walsh, Norman
237
@cindex Neumann, Gustaf
238
Dviljk got started in March 1994 after I bought a Laserjet 4. (Kpathsea
239
work got suspended while Norm Walsh and I, with Gustaf Neumann's help,
240
implemented a way for @TeX{} to get at all those neat builtin LJ4 fonts
241
@dots{} such a treat to have something to typeset in besides Palatino!)
243
By spring of 1995, I had implemented just about all the path-searching
244
features in Kpathsea that I plan to, driven beyond my initial goals by
245
Thomas Esser and others. I then started to integrate Web2c with
246
Kpathsea. After the release of a stable Web2c, I hope to be able to stop
247
development, and turn most of my attention back to making fonts for GNU.
248
(Always assuming Micros**t hasn't completely obliterated Unix by then,
249
or that software patents haven't stopped software development by anybody
250
smaller than a company with a million-dollar-a-year legal budget. Which
251
is actually what I think is likely to happen, but that's another
255
[Olaf writes.] At the end of 1997, UNIX is still alive and kicking,
256
individuals still develop software, and Web2c development still
257
continues. Karl had been looking for some time for someone to take up
258
part of the burden, and I volunteered.
261
@include install.texi
263
@include unixtex.texi
268
@chapter Path searching
270
@cindex path searching
272
This chapter describes the generic path searching mechanism Kpathsea
273
provides. For information about searching for particular file types
274
(e.g., @TeX{} fonts), see the next chapter.
277
* Searching overview:: Basic scheme for searching.
278
* Path sources:: Where search paths can be defined.
279
* Path expansion:: Special constructs in search paths.
280
* Filename database:: Using an externally-built list to search.
281
* Invoking kpsewhich:: Standalone path lookup.
285
@node Searching overview
286
@section Searching overview
288
@cindex searching overview
289
@cindex path searching, overview
290
@cindex overview of path searching
292
@cindex search path, defined
293
A @dfn{search path} is a colon-separated list of @dfn{path elements},
294
which are directory names with a few extra frills. A search path can
295
come from (a combination of) many sources; see below. To look up a file
296
@samp{foo} along a path @samp{.:/dir}, Kpathsea checks each element of
297
the path in turn: first @file{./foo}, then @file{/dir/foo}, returning
298
the first match (or possibly all matches).
300
@cindex magic characters
301
@kindex : @r{may not be :}
302
@kindex / @r{may not be /}
303
The ``colon'' and ``slash'' mentioned here aren't necessarily @samp{:}
304
and @samp{/} on non-Unix systems. Kpathsea tries to adapt to other
305
operating systems' conventions.
307
@cindex database search
308
@cindex searching the database
309
To check a particular path element @var{e}, Kpathsea first sees if a
310
prebuilt database (@pxref{Filename database}) applies to @var{e}, i.e.,
311
if the database is in a directory that is a prefix of @var{e}. If so,
312
the path specification is matched against the contents of the database.
314
@cindex floating directories
315
@cindex filesystem search
317
@cindex searching the disk
318
If the database does not exist, or does not apply to this path element,
319
or contains no matches, the filesystem is searched (if this was not
320
forbidden by the specification with @samp{!!} and if the file being
321
searched for must exist). Kpathsea constructs the list of directories
322
that correspond to this path element, and then checks in each for the
323
file being searched for. (To help speed future lookups of files in the
324
same directory, the directory in which a file is found is floated to the
325
top of the directory list.)
328
@cindex VF files, not found
331
The ``file must exist'' condition comes into play with VF files and
332
input files read by the @TeX{} @samp{\openin} command. These files may
333
not exist (consider @file{cmr10.vf}), and so it would be wrong to search
334
the disk for them. Therefore, if you fail to update @file{ls-R} when
335
you install a new VF file, it will never be found.
337
Each path element is checked in turn: first the database, then the disk.
338
If a match is found, the search stops and the result is returned. This
339
avoids possibly-expensive processing of path specifications that are
340
never needed on a particular run. (Unless the search explicitly
341
requested all matches.)
343
@cindex expansion, path element
344
Although the simplest and most common path element is a directory name,
345
Kpathsea supports additional features in search paths: layered default
346
values, environment variable names, config file values, users' home
347
directories, and recursive subdirectory searching. Thus, we say that
348
Kpathsea @dfn{expands} a path element, meaning transforming all the
349
magic specifications into the basic directory name or names. This
350
process is described in the sections below. It happens in the same
351
order as the sections.
353
@cindex absolute filenames
354
@cindex relative filenames
355
@cindex explicitly relative filenames
356
@cindex filenames, absolute or explicitly relative
357
Exception to all of the above: If the filename being searched for is
358
absolute or explicitly relative, i.e., starts with @samp{/} or @samp{./}
359
or @samp{../}, Kpathsea simply checks if that file exists.
361
@cindex permission denied
362
@cindex unreadable files
363
@cindex access warnings
364
@cindex warnings, file access
365
@flindex lost+found @r{directory}
367
Ordinarily, if Kpathsea tries to access a file or directory that cannot
368
be read, it gives a warning. This is so you will be alerted to
369
directories or files that accidentally lack read permission (for
370
example, a @file{lost+found}). If you prefer not to see these warnings,
371
include the value @samp{readable} in the @code{TEX_HUSH} environment
372
variable or config file value.
374
This generic path searching algorithm is implemented in
375
@file{kpathsea/pathsearch.c}. It is employed by a higher-level
376
algorithm when searching for a file of a particular type (@pxref{File
377
lookup}, and @ref{Glyph lookup}).
381
@section Path sources
384
@cindex sources for search paths
386
A search path can come from many sources. In the order in which
391
@cindex environment variable, source for path
392
A user-set environment variable, e.g., @code{TEXINPUTS}.
393
Environment variables with an underscore and the program name appended
394
override; for example, @code{TEXINPUTS_latex} overrides @code{TEXINPUTS}
395
if the program being run is named @samp{latex}.
398
A program-specific configuration file, e.g., an @samp{S /a:/b} line in
399
Dvips' @file{config.ps} (@pxref{Config files,,, dvips, Dvips}).
402
@cindex configuration file, source for path
403
@cindex Kpathsea config file, source for path
404
@flindex texmf.cnf@r{, source for path}
405
A line in a Kpathsea configuration file @file{texmf.cnf}, e.g.,
406
@samp{TEXINPUTS=/c:/d} (see below).
409
@cindex compilation value, source for path
410
The compile-time default (specified in @file{kpathsea/paths.h}).
413
You can see each of these values for a given search path by using the
414
debugging options (@pxref{Debugging}).
416
These sources may be combined via default expansion (@pxref{Default
420
* Config files:: Kpathsea's runtime config files (texmf.cnf).
425
@subsection Config files
428
@flindex texmf.cnf@r{, definition for}
430
@cindex runtime configuration files
432
As mentioned above, Kpathsea reads @dfn{runtime configuration files}
433
named @file{texmf.cnf} for search path and other definitions. The
434
search path used to look for these configuration files is named
435
@code{TEXMFCNF}, and is constructed in the usual way, as described
436
above, except that configuration files cannot be used to define the
437
path, naturally; also, an @file{ls-R} database is not used to search for
440
Kpathsea reads @emph{all} @file{texmf.cnf} files in the search path, not
441
just the first one found; definitions in earlier files override those in
442
later files. Thus, if the search path is @samp{.:$TEXMF}, values from
443
@file{./texmf.cnf} override those from @file{$TEXMF/texmf.cnf}.
445
While (or instead of) reading this description, you may find it helpful
446
to look at the distributed @file{texmf.cnf}, which uses or at least
447
mentions most features. The format of @file{texmf.cnf} files follows:
451
@cindex comments, in @file{texmf.cnf}
452
Comments start with @samp{%} and continue to the end of the line.
455
@cindex blank lines, in @file{texmf.cnf}
456
Blank lines are ignored.
459
@cindex backslash-newline
460
@cindex continuation character
461
@cindex whitespace, not ignored on continuation lines
462
@kindex \@r{, line continuation in @file{texmf.cnf}}
463
A @samp{\} at the end of a line acts as a continuation character, i.e.,
464
the next line is appended. Whitespace at the beginning of continuation
465
lines is not ignored.
467
@item Each remaining line must look like
470
@var{variable} @r{[}. @var{progname}@r{]} @r{[}=@r{]} @var{value}
473
@noindent where the @samp{=} and surrounding whitespace is optional.
476
@cindex identifiers, characters valid in
477
The @var{variable} name may contain any character other than whitespace,
478
@samp{=}, or @samp{.}, but sticking to @samp{A-Za-z_} is safest.
480
@item If @samp{.@var{progname}} is present, the definition only
481
applies if the program that is running is named (i.e., the last
482
component of @code{argv[0]} is) @var{progname} or
483
@file{@var{progname}.exe}. This allows different flavors of @TeX{} to
484
have different search paths, for example.
487
@cindex right-hand side of variable assignments
488
@var{value} may contain any characters except @samp{%} and @samp{@@}.
489
(These restrictions are only necessary because of the processing done on
490
@file{texmf.cnf} at build time, so you can stick those characters in
491
after installation if you have to.) The @samp{$@var{var}.@var{prog}}
492
feature is not available on the right-hand side; instead, you must use
493
an additional variable (see below for example). A @samp{;} in
494
@var{value} is translated to @samp{:} if running under Unix; this is
495
useful to write a single @file{texmf.cnf} which can be used under both
498
@item All definitions are read before anything is expanded, so you can
499
use variables before they are defined (like Make, unlike most other
503
@noindent Here is a configuration file fragment illustrating most of
507
% TeX input files -- i.e., anything to be found by \input or \openin ...
508
latex209_inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex//
509
latex2e_inputs = .:$TEXMF/tex/latex//:$TEXMF/tex//
510
TEXINPUTS = .:$TEXMF/tex//
511
TEXINPUTS.latex209 = $latex209_inputs
512
TEXINPUTS.latex2e = $latex2e_inputs
513
TEXINPUTS.latex = $latex2e_inputs
516
@cindex shell scripts as configuration files
517
@cindex configuration files as shell scripts.
518
Although this format has obvious similarities to Bourne shell
519
scripts---change the comment character to @code{#}, disallow spaces
520
around the @code{=}, and get rid of the @code{.@var{name}} convention,
521
and it could be run through the shell. But there seemed little
522
advantage to doing this, since all the information would have to passed
523
back to Kpathsea and parsed there anyway, since the @code{sh} process
524
couldn't affect its parent's environment.
527
The implementation of all this is in @file{kpathsea/cnf.c}.
531
@section Path expansion
533
@cindex path expansion
534
@cindex expansion, search path
536
Kpathsea recognizes certain special characters and constructions in
537
search paths, similar to that in shells. As a general example:
538
@samp{~$USER/@{foo,bar@}//baz} expands to all subdirectories under
539
directories @file{foo} and @file{bar} in @t{$USER}'s home directory that
540
contain a directory or file @file{baz}. These expansions are explained
541
in the sections below.
544
* Default expansion:: a: or :a or a::b expands to a default.
545
* Variable expansion:: $foo and $@{foo@} expand to environment values.
546
* Tilde expansion:: ~ and ~user expand to home directories.
547
* Brace expansion:: a@{foo,bar@}b expands to afoob abarb.
548
* KPSE_DOT expansion:: . is replaced with $KPSE_DOT if it is defined.
549
* Subdirectory expansion:: a// and a//b recursively expand to subdirs.
553
@node Default expansion
554
@subsection Default expansion
556
@kindex :: @r{expansion}
557
@cindex doubled colons
558
@cindex leading colons
559
@cindex trailing colons
561
@cindex default expansion
562
@cindex expansion, default
564
If the highest-priority search path (@pxref{Path sources}) contains an
565
@dfn{extra colon} (i.e., leading, trailing, or doubled), Kpathsea
566
inserts at that point the next-highest-priority search path that is
567
defined. If that inserted path has an extra colon, the same happens
568
with the next-highest. (An extra colon in the compile-time default
569
value has unpredictable results, so installers beware.)
571
For example, given an environment variable setting
574
setenv TEXINPUTS /home/karl:
577
@noindent and a @code{TEXINPUTS} value from @file{texmf.cnf} of
583
@noindent then the final value used for searching will be:
586
/home/karl:.:$TEXMF//tex
589
Put another way, default expansion works on ``formats'' (search
590
paths), and not directly on environment variables. Example, showing
591
the trailing @samp{:} ignored in the first case and expanded in the second:
594
$ env TTFONTS=/tmp: kpsewhich --expand-path '$TTFONTS'
596
$ env TTFONTS=/tmp: kpsewhich --show-path=.ttf
597
/tmp:.:/home/olaf/texmf/fonts/truetype//:...
600
Since Kpathsea looks for multiple configuration files, it would be
601
natural to expect that (for example) an extra colon in
602
@file{./texmf.cnf} would expand to the path in @file{$TEXMF/texmf.cnf}.
603
Or, with Dvips' configuration files, that an extra colon in
604
@file{config.$PRINTER} would expand to the path in @file{config.ps}.
605
This doesn't happen. It's not clear this would be desirable in all
606
cases, and trying to devise a way to specify the path to which the extra
607
colon should expand seemed truly baroque.
608
@cindex Bach, Johann Sebastian
610
Technicality: Since it would be useless to insert the default value in
611
more than one place, Kpathsea changes only one extra @samp{:} and leaves
612
any others in place (they will eventually be ignored). Kpathsea checks
613
first for a leading @samp{:}, then a trailing @samp{:}, then a doubled
617
You can trace this by debugging ``paths'' (@pxref{Debugging}).
618
Default expansion is implemented in the source file
619
@file{kpathsea/kdefault.c}.
622
@node Variable expansion
623
@subsection Variable expansion
625
@kindex $ @r{expansion}
626
@cindex environment variables in paths
627
@cindex variable expansion
628
@cindex expansion, variable
629
@flindex texmf.cnf@r{, and variable expansion}
631
@samp{$foo} or @samp{$@{foo@}} in a path element is replaced by (1) the
632
value of an environment variable @samp{foo} (if defined); (2) the value
633
of @samp{foo} from @file{texmf.cnf} (if defined); (3) the empty string.
635
If the character after the @samp{$} is alphanumeric or @samp{_}, the
636
variable name consists of all consecutive such characters. If the
637
character after the @samp{$} is a @samp{@{}, the variable name consists
638
of everything up to the next @samp{@}} (braces may not be nested around
639
variable names). Otherwise, Kpathsea gives a warning and ignores the
640
@samp{$} and its following character.
642
@cindex quoting variable values
643
@cindex shell variables
644
You must quote the @t{$}'s and braces as necessary for your shell.
645
@emph{Shell} variable values cannot be seen by Kpathsea, i.e., ones
646
defined by @code{set} in C shells and without @code{export} in Bourne
651
setenv tex /home/texmf
652
setenv TEXINPUTS .:$tex:$@{tex@}prev
654
@noindent the final @code{TEXINPUTS} path is the three directories:
656
.:/home/texmf:/home/texmfprev
659
The @samp{.@var{progname}} suffix on variables and
660
@samp{_@var{progname}} on environment variable names are not implemented
661
for general variable expansions. These are only recognized when search
662
paths are initialized (@pxref{Path sources}).
665
Variable expansion is implemented in the source file
666
@file{kpathsea/variable.c}.
669
@node Tilde expansion
670
@subsection Tilde expansion
672
@kindex ~ @r{expansion}
673
@cindex home directories in paths
674
@cindex tilde expansion
675
@cindex expansion, tilde
677
@vindex HOME@r{, as ~ expansion}
678
A leading @samp{~} in a path element is replaced by the value of the
679
environment variable @code{HOME}, or @file{.} if @code{HOME} is not set.
681
A leading @samp{~@var{user}} in a path element is replaced by
682
@var{user}'s home directory from the system @file{passwd} database.
686
setenv TEXINPUTS ~/mymacros:
689
@noindent will prepend a directory @file{mymacros} in your home
690
directory to the default path.
692
@cindex @t{root} user
693
@cindex trailing @samp{/} in home directory
694
@kindex /@r{, trailing in home directory}
695
As a special case, if a home directory ends in @samp{/}, the trailing
696
slash is dropped, to avoid inadvertently creating a @samp{//} construct
697
in the path. For example, if the home directory of the user @samp{root}
698
is @samp{/}, the path element @samp{~root/mymacros} expands to just
699
@samp{/mymacros}, not @samp{//mymacros}.
702
Tilde expansion is implemented in the source file @file{kpathsea/tilde.c}.
705
@node Brace expansion
706
@subsection Brace expansion
708
@kindex @{ @r{expansion}
709
@cindex brace expansion
711
@samp{x@{@var{a},@var{b}@}y} expands to @samp{x@var{a}y:x@var{b}y}.
718
@noindent expands to @samp{foo/1/baz:foo/2/baz}. @samp{:} is the path
719
separator on the current system; e.g., on a DOS system, it's @samp{;}.
721
Braces can be nested; for example, @samp{x@{A,B@{1,2@}@}y} expands to
722
@samp{xAy:xB1y:xB2y}.
724
Multiple non-nested braces are expanded from right to left; for example,
725
@samp{x@{A,B@}@{1,2@}y} expands to @samp{x@{A,B@}1y:x@{A,B@}2y}, which
726
expands to @samp{xA1y:xB1y:xA2y:xB2y}.
728
@cindex multiple @TeX{} hierarchies
729
This feature can be used to implement multiple @TeX{} hierarchies, by
730
assigning a brace list to @code{$TEXMF}, as mentioned in
733
You can also use the path separator in stead of the comma. The last
734
example could have been written @samp{x@{A:B@}@{1:2@}y}.
738
Brace expansion is implemented in the source file
739
@file{kpathsea/expand.c}. It is a modification of the Bash sources, and
740
is thus covered by the GNU General Public License, rather than the
741
Library General Public License that covers the rest of Kpathsea.
744
@node KPSE_DOT expansion
745
@subsection @code{KPSE_DOT} expansion
747
@kindex KPSE_DOT @r{expansion}
749
When @code{KPSE_DOT} is defined in the environment, it names a directory
750
that should be considered the current directory for the purpose of
751
looking up files in the search paths. This feature is needed by the
752
@samp{mktex@dots{}} scripts @ref{mktex scripts}, because these
753
change the working directory. You should not ever define it yourself.
756
@node Subdirectory expansion
757
@subsection Subdirectory expansion
760
@cindex subdirectory searching
761
@cindex expansion, subdirectory
763
@cindex alphabetical order, not
764
Two or more consecutive slashes in a path element following a directory
765
@var{d} is replaced by all subdirectories of @var{d}: first those
766
subdirectories directly under @var{d}, then the subsubdirectories under
767
those, and so on. At each level, the order in which the directories are
768
searched is unspecified. (It's ``directory order'', and definitely not
771
If you specify any filename components after the @samp{//}, only
772
subdirectories which match those components are included. For example,
773
@samp{/a//b} would expand into directories @file{/a/1/b}, @file{/a/2/b},
774
@file{/a/1/1/b}, and so on, but not @file{/a/b/c} or @file{/a/1}.
776
You can include multiple @samp{//} constructs in the path.
778
@samp{//} at the beginning of a path is ignored; you didn't really want
779
to search every directory on the system, did you?
781
@cindex trick for detecting leaf directories
782
@cindex leaf directory trick
783
@cindex Farwell, Matthew
784
@cindex MacKenzie, David
785
I should mention one related implementation trick, which I took from GNU
786
find. Matthew Farwell suggested it, and David MacKenzie implemented it.
789
The trick is that in every real Unix implementation (as opposed to the
790
POSIX specification), a directory which contains no subdirectories will
791
have exactly two links (namely, one for @file{.} and one for @file{..}).
792
That is to say, the @code{st_nlink} field in the @samp{stat} structure
793
will be two. Thus, we don't have to stat everything in the bottom-level
794
(leaf) directories---we can just check @code{st_nlink}, notice it's two,
797
But if you have a directory that contains a single subdirectory and 500
798
regular files, @code{st_nlink} will be 3, and Kpathsea has to stat every
799
one of those 501 entries. Therein lies slowness.
802
You can disable the trick by undefining @code{UNIX_ST_LINK} in
803
@file{kpathsea/config.h}. (It is undefined by default except under Unix.)
806
Unfortunately, in some cases files in leaf directories are
807
@code{stat}'d: if the path specification is, say,
808
@samp{$TEXMF/fonts//pk//}, then files in a subdirectory
809
@samp{@dots{}/pk}, even if it is a leaf, are checked. The reason cannot
810
be explained without reference to the implementation, so read
811
@file{kpathsea/elt-dirs.c} (search for @samp{may descend}) if you are
812
curious. And if you can find a way to @emph{solve} the problem, please
816
Subdirectory expansion is implemented in the source file
817
@file{kpathsea/elt-dirs.c}.
820
@node Filename database
821
@section Filename database (@code{ls-R})
823
@cindex filename database
824
@cindex database, for filenames
825
@cindex externally-built filename database
827
Kpathsea goes to some lengths to minimize disk accesses for searches
828
(@pxref{Subdirectory expansion}). Nevertheless, at installations with
829
enough directories, searching each possible directory for a given file
830
can take an excessively long time (depending on the speed of the disk,
831
whether it's NFS-mounted, how patient you are, etc.).
833
In practice, a font tree containing the standard PostScript and PCL
834
fonts is large enough for searching to be noticeably slow on typical
835
systems these days. Therefore, Kpathsea can use an externally-built
836
``database'' file named @file{ls-R} that maps files to directories, thus
837
avoiding the need to exhaustively search the disk.
839
A second database file @file{aliases} allows you to give additional
840
names to the files listed in @file{ls-R}. This can be helpful to adapt
841
to ``8.3'' filename conventions in source files.
843
The @file{ls-R} and @file{aliases} features are implemented in the
844
source file @file{kpathsea/db.c}.
847
* ls-R:: The main filename database.
848
* Filename aliases:: Aliases for those names.
849
* Database format:: Syntax details of the database file.
854
@subsection @file{ls-R}
856
@flindex ls-R @r{database file}
859
As mentioned above, you must name the main filename database
860
@file{ls-R}. You can put one at the root of each @TeX{} installation
861
hierarchy you wish to search (@code{$TEXMF} by default); most sites have
862
only one hierarchy. Kpathsea looks for @file{ls-R} files along the
863
@code{TEXMFDBS} path, so that should presumably match the list of
866
The recommended way to create and maintain @samp{ls-R} is to run the
867
@code{mktexlsr} script, which is installed in @samp{$(bindir)}
868
(@file{/usr/local/bin} by default). That script goes to some trouble to
869
follow symbolic links as necessary, etc. It's also invoked by the
870
distributed @samp{mktex@dots{}} scripts.
872
@flindex ls-R@r{, simplest build}
873
At its simplest, though, you can build @file{ls-R} with the command
875
cd @var{/your/texmf/root} && ls -LAR ./ >ls-R
880
@flindex /etc/profile @r{and aliases}
881
presuming your @code{ls} produces the right output format (see the
882
section below). GNU @code{ls}, for example, outputs in this format.
883
Also presuming your @code{ls} hasn't been aliased in a system file
884
(e.g., @file{/etc/profile}) to something problematic, e.g., @samp{ls
885
--color=tty}. In that case, you will have to disable the alias before
886
generating @file{ls-R}. For the precise definition of the file format,
887
see @ref{Database format}.
889
Regardless of whether you use the supplied script or your own, you will
890
almost certainly want to invoke it via @code{cron}, so when you make
891
changes in the installed files (say if you install a new La@TeX{}
892
package), @file{ls-R} will be automatically updated.
894
@opindex -A @r{option to @code{ls}}
897
@flindex . @r{directories, ignored}
898
@flindex .tex @r{file, included in @file{ls-R}}
899
The @samp{-A} option to @code{ls} includes files beginning with @samp{.}
900
(except for @file{.} and @file{..}), such as the file @file{.tex}
901
included with the La@TeX{} tools package. (On the other hand,
902
@emph{directories} whose names begin with @samp{.} are always ignored.)
904
@cindex symbolic links, and @file{ls-R}
905
@opindex -L @r{option to @code{ls}}
906
If your system does not support symbolic links, omit the @samp{-L}.
908
@cindex automounter, and @file{ls-R}
909
@cindex NFS and @file{ls-R}
910
@code{ls -LAR @var{/your/texmf/root}} will also work. But using
911
@samp{./} avoids embedding absolute pathnames, so the hierarchy can be
912
easily transported. It also avoids possible trouble with automounters
913
or other network filesystem conventions.
915
@cindex warning about unusable @file{ls-R}
916
@cindex unusable @file{ls-R} warning
917
Kpathsea warns you if it finds an @file{ls-R} file, but the file does
918
not contain any usable entries. The usual culprit is running plain
919
@samp{ls -R} instead of @samp{ls -LR ./} or @samp{ls -R
920
@var{/your/texmf/root}}. Another possibility is some system directory
921
name starting with a @samp{.} (perhaps if you are using AFS); Kpathsea
922
ignores everything under such directories.
924
@kindex !! @r{in path specifications}
925
@cindex disk searching, avoiding
926
Because the database may be out-of-date for a particular run, if a file
927
is not found in the database, by default Kpathsea goes ahead and
928
searches the disk. If a particular path element begins with @samp{!!},
929
however, @emph{only} the database will be searched for that element,
930
never the disk. If the database does not exist, nothing will be
931
searched. Because this can surprise users (``I see the font
932
@file{foo.tfm} when I do an @code{ls}; why can't Dvips find it?''), it
933
is not in any of the default search paths.
936
@node Filename aliases
937
@subsection Filename aliases
939
@cindex filename aliases
940
@cindex aliases, for filenames
942
In some circumstances, you may wish to find a file under several names.
943
For example, suppose a @TeX{} document was created using a DOS system
944
and tries to read @file{longtabl.sty}. But now it's being run on a Unix
945
system, and the file has its original name, @file{longtable.sty}. The
946
file won't be found. You need to give the actual file
947
@file{longtable.sty} an alias @samp{longtabl.sty}.
949
@c As another example, suppose you are creating a @TeX{} distribution on a
950
@c CD-ROM or a DOS system; then the file @file{mf.base} gets stored as
951
@c @file{mf.bas}. But Metafont on Unix wants to find @file{mf.base}. Here
952
@c you need to give the actual file @file{mf.bas} an alias @samp{mf.base}.
954
You can handle this by creating a file @file{aliases} as a companion to
955
the @file{ls-R} for the hierarchy containing the file in question. (You
956
must have an @file{ls-R} for the alias feature to work.)
958
The format of @file{aliases} is simple: two whitespace-separated words
959
per line; the first is the real name @file{longtable.sty}, and second is
960
the alias (@file{longtabl.sty}). These must be base filenames, with no
961
directory components. @file{longtable.sty} must be in the sibling
964
Also, blank lines and lines starting with @samp{%} or @samp{#} are
965
ignored in @file{aliases}, to allow for comments.
967
If a real file @file{longtabl.sty} exists, it is used regardless of any
971
@node Database format
972
@subsection Database format
974
@cindex format of external database
975
@cindex database, format of
977
The ``database'' read by Kpathsea is a line-oriented file of plain
978
text. The format is that generated by GNU (and most other) @code{ls}
979
programs given the @samp{-R} option, as follows.
983
Blank lines are ignored.
986
If a line begins with @samp{/} or @samp{./} or @samp{../} and ends with
987
a colon, it's the name of a directory. (@samp{../} lines aren't useful,
988
however, and should not be generated.)
991
All other lines define entries in the most recently seen directory.
992
@t{/}'s in such lines will produce possibly-strange results.
995
Files with no preceding directory line are ignored.
998
For example, here's the first few lines of @file{ls-R} (which totals
999
about 30K bytes) on my system:
1023
@node Invoking kpsewhich
1024
@section @code{kpsewhich}: Standalone path searching
1027
@cindex path searching, standalone
1028
@cindex standalone path searching
1030
The Kpsewhich program exercises the path searching functionality
1031
independent of any particular application. This can also be useful as a
1032
sort of @code{find} program to locate files in your @TeX{} hierarchies,
1033
perhaps in administrative scripts. It is used heavily in the
1034
distributed @samp{mktex@dots{}} scripts.
1038
kpsewhich @var{option}@dots{} @var{filename}@dots{}
1041
The options and filename(s) to look up can be intermixed.
1042
Options can start with either @samp{-} or @samp{--}, and any unambiguous
1043
abbreviation is accepted.
1046
* Path searching options:: Changing the mode, resolution, etc.
1047
* Auxiliary tasks:: Path and variable expansion.
1048
* Standard options:: --help and --version.
1052
@node Path searching options
1053
@subsection Path searching options
1055
@cindex path searching options
1057
Kpsewhich looks up each non-option argument on the command line as a
1058
filename, and returns the first file found. There is no option to
1059
return all the files with a particular name (you can run the Unix
1060
@samp{find} utility for that, @pxref{Invoking find,,, findutils, GNU
1063
Various options alter the path searching behavior:
1066
@item --dpi=@var{num}
1067
@opindex --dpi=@var{num}
1068
@opindex -D @var{num}
1069
@cindex resolution, setting
1070
Set the resolution to @var{num}; this only affects @samp{gf} and
1071
@samp{pk} lookups. @samp{-D} is a synonym, for compatibility with
1072
Dvips. Default is 600.
1074
@item --engine=@var{name}
1075
@opindex --engine=@var{name}
1077
Set the engine name to @var{name}. By default it is not set. The
1078
engine name is used in some search paths to allow files with the same
1079
name but used by different engines to coexist.
1081
@item --format=@var{name}
1082
@opindex --format=@var{name}
1083
Set the format for lookup to @var{name}. By default, the format is
1084
guessed from the filename, with @samp{tex} being used if nothing else
1085
fits. The recognized filename extensions (including any leading
1086
@samp{.}) are also allowable @var{name}s.
1088
All formats also have a name, which is the only way to specify formats
1089
with no associated suffix. For example, for Dvips configuration files
1090
you can use @samp{--format="dvips config"}. (The quotes are for the
1093
Here's the current list of recognized names and the associated suffixes.
1094
@xref{Supported file formats}, for more information on each of these.
1120
graphic/figure: .eps .epsi
1122
TeX system documentation
1125
PostScript header/font: .pro
1128
type1 fonts: .pfa .pfb
1132
truetype fonts: .ttf .ttc
1149
This option and @samp{--path} are mutually exclusive.
1152
@opindex --interactive
1153
@cindex interactive query
1154
After processing the command line, read additional filenames to look up
1155
from standard input.
1157
@item -mktex=@var{filetype}
1158
@itemx -no-mktex=@var{filetype}
1159
@opindex -mktex=@var{filetype}
1160
@opindex -no-mktex=@var{filetype}
1161
Turn on or off the @samp{mktex} script associated with @var{filetype}.
1162
The only values that make sense for @var{filetype} are @samp{pk},
1163
@samp{mf}, @samp{tex}, and @samp{tfm}. By default, all are off in
1164
Kpsewhich. @xref{mktex scripts}.
1166
@item --mode=@var{string}
1167
@opindex --mode=@var{string}
1168
Set the mode name to @var{string}; this also only affects @samp{gf} and
1169
@samp{pk} lookups. No default: any mode will be found. @xref{mktex
1173
@opindex --must-exist
1174
Do everything possible to find the files, notably including searching
1175
the disk. By default, only the @file{ls-R} database is checked, in the
1176
interest of efficiency.
1178
@item --path=@var{string}
1179
@opindex --path=@var{string}
1180
Search along the path @var{string} (colon-separated as usual), instead
1181
of guessing the search path from the filename. @samp{//} and all the
1182
usual expansions are supported (@pxref{Path expansion}). This option
1183
and @samp{--format} are mutually exclusive. To output the complete
1184
directory expansion of a path, instead of doing a one-shot lookup, see
1185
@samp{--expand-path} in the following section.
1187
@item --progname=@var{name}
1188
@opindex --progname=@var{name}
1189
Set the program name to @var{name}; default is @samp{kpsewhich}. This
1190
can affect the search paths via the @samp{.@var{prognam}} feature in
1191
configuration files (@pxref{Config files}).
1195
@node Auxiliary tasks
1196
@subsection Auxiliary tasks
1198
@cindex auxiliary tasks
1200
Kpsewhich provides some additional features not strictly related to path
1205
@opindex --debug=@var{num}
1206
@samp{--debug=@var{num}} sets the debugging options to @var{num}.
1210
@opindex --var-value=@var{variable}
1211
@samp{--var-value=@var{variable}} output the value of @var{variable}.
1214
@opindex --expand-braces=@var{string}
1215
@samp{--expand-braces=@var{string}} outputs the variable and brace
1216
expansion of @var{string}. @xref{Path expansion}.
1219
@opindex --expand-var=@var{string}
1220
@samp{--expand-var=@var{string}} outputs the variable expansion of
1221
@var{string}. For example, the @samp{mktex@dots{}} scripts run
1222
@samp{kpsewhich --expand-var='$TEXMF'} to find the root of the @TeX{} system
1223
hierarchy. @xref{Path expansion}.
1226
@opindex --expand-path=@var{string}
1227
@samp{--expand-path=@var{string}} outputs the complete expansion of
1228
@var{string} as a colon-separated path. This is useful to construct a
1229
search path for a program that doesn't accept recursive subdirectory
1230
specifications. Nonexistent directories are culled from the output:
1233
$ kpsewhich --expand-path '/tmp'
1235
$ kpsewhich --expand-path '/nonesuch'
1239
For one-shot uses of an arbitrary (not built in to Kpathsea) path, see
1240
@samp{--path} in the previous section.
1243
@opindex --show-path=@var{name}
1244
@samp{--show-path=@var{name}} shows the path that would be used for file
1245
lookups of file type @var{name}. Either a filename extension
1246
(@samp{pk}, @samp{.vf}, etc.) or an integer can be used, just as with
1247
@samp{--format}, described in the previous section.
1251
@node Standard options
1252
@subsection Standard options
1254
@cindex standard options
1256
Kpsewhich accepts the standard GNU options:
1261
@samp{--help} prints a help message on standard output and exits.
1265
@samp{--version} prints the Kpathsea version number and exits.
1270
@chapter @TeX{} support
1272
@cindex @TeX{} support
1274
Although the basic features in Kpathsea can be used for any type of path
1275
searching, it came about (like all libraries) with a specific
1276
application in mind: I wrote Kpathsea specifically for @TeX{} system
1277
programs. I had been struggling with the programs I was using (Dvips,
1278
Xdvi, and @TeX{} itself) having slightly different notions of how to
1279
specify paths; and debugging was painful, since no code was shared.
1281
Therefore, Kpathsea provides some @TeX{}-specific formats and features.
1282
Indeed, many of the supposedly generic path searching features were
1283
provided because they seemed useful in that con@TeX{}t (font lookup,
1286
Kpathsea provides a standard way to search for files of any of the
1287
supported file types; glyph fonts are a bit different than all the rest.
1288
Searches are based solely on filenames, not file contents---if a GF
1289
file is named @file{cmr10.600pk}, it will be found as a PK file.
1292
* Supported file formats:: File types Kpathsea knows about.
1293
* File lookup:: Searching for most kinds of files.
1294
* Glyph lookup:: Searching for bitmap fonts.
1295
* Suppressing warnings:: Avoiding warnings via TEX_HUSH.
1299
@node Supported file formats
1300
@section Supported file formats
1302
@cindex supported file formats
1303
@cindex file formats, supported
1305
@cindex environment variables for @TeX{}
1306
@cindex @TeX{} environment variables
1308
Kpathsea has support for a number of file types. Each file type has a
1309
list of environment and config file variables that are checked to define
1310
the search path, and most have a default suffix that plays a role in
1311
finding files (see the next section). Some also define additional
1312
suffixes, and/or a program to be run to create missing files on the fly.
1314
@cindex program-varying paths
1315
Since environment variables containing periods, such as
1316
@samp{TEXINPUTS.latex}, are not allowed on some systems, Kpathsea looks
1317
for environment variables with an underscore, e.g.,
1318
@samp{TEXINPUTS_latex} (@pxref{Config files}).
1320
The following table lists the above information.
1326
(Adobe font metrics, @pxref{Metric files,,, dvips, Dvips})
1334
(Metafont memory dump, @pxref{Memory dumps,,, web2c, Web2c})
1335
@code{MFBASES}, @code{TEXMFINI};
1336
suffix @samp{.base}.
1342
(Bib@TeX{} bibliography source, @pxref{bibtex invocation,,, web2c, Web2c})
1343
@code{BIBINPUTS}, @code{TEXBIB};
1349
(Bib@TeX{} style file, @pxref{Basic BibTeX style files,, Basic Bib@TeX{}
1350
style files, web2c, Web2c})
1357
(character map files)
1359
suffix @samp{.cmap}.
1364
(Runtime configuration files, @pxref{Config files})
1374
suffixes @samp{.w}, @samp{.web};
1375
additional suffix @samp{.ch}.
1379
@flindex config.ps@r{, search path for}
1380
(Dvips @samp{config.*} files, such as @file{config.ps}, @pxref{Config
1381
files,,, dvips, Dvips})
1395
(@TeX{} memory dump, @pxref{Memory dumps,,, web2c, Web2c})
1396
@code{TEXFORMATS}, @code{TEXMFINI};
1404
(generic font bitmap, @pxref{Glyph files,,, dvips, Dvips})
1405
@code{@var{program}FONTS}, @code{GFFONTS}, @code{GLYPHFONTS}, @code{TEXFONTS};
1408
@item graphic/figure
1413
(Encapsulated PostScript figures, @pxref{PostScript figures,,, dvips, Dvips})
1414
@code{TEXPICTS}, @code{TEXINPUTS};
1415
additional suffixes: @samp{.eps}, @samp{.epsi}.
1419
@vindex TEXINDEXSTYLE
1421
(makeindex style files)
1422
@code{TEXINDEXSTYLE}, @code{INDEXSTYLE};
1428
(ligature definition files)
1435
(Filename databases, @pxref{Filename database})
1441
(Fontmaps, @pxref{Fontmap})
1449
(MetaPost memory dump, @pxref{Memory dumps,,, web2c, Web2c})
1450
@code{MPMEMS}, @code{TEXMFINI};
1453
@item @r{MetaPost support}
1455
(MetaPost support files, used by DMP; @pxref{dmp invocation,,, web2c, Web2c})
1461
(Metafont source, @pxref{mf invocation,,, web2c, Web2c})
1464
dynamic creation program: @code{mktexmf}.
1469
(Metafont program strings, @pxref{pooltype invocation,,, web2c, Web2c})
1470
@code{MFPOOL}, @code{TEXMFINI};
1471
suffix @samp{.pool}.
1476
(@code{MFT} style file, @pxref{mft invocation,,, web2c, Web2c})
1482
(font-related files that don't fit the other categories)
1488
(MetaPost source, @pxref{mpost invocation,,, web2c, Web2c})
1495
(MetaPost program strings, @pxref{pooltype invocation,,, web2c, Web2c})
1496
@code{MPPOOL}, @code{TEXMFINI};
1497
suffix @samp{.pool}.
1502
(Omega compiled process files)
1503
@code{OCPINPUTS}; @*
1505
dynamic creation program: @code{MakeOmegaOCP}.
1510
(Omega font metrics)
1511
@code{OFMFONTS}, @code{TEXFONTS}; @*
1512
suffixes @samp{.ofm}, @samp{.tfm};
1513
dynamic creation program: @code{MakeOmegaOFM}.
1515
@item opentype fonts
1516
@vindex OPENTYPEFONTS
1518
@code{OPENTYPEFONTS}.
1522
(Omega property lists)
1523
@code{OPLFONTS}, @code{TEXFONTS};
1529
(Omega translation process files)
1536
(Omega virtual fonts)
1537
@code{OVFFONTS}, @code{TEXFONTS};
1543
(Omega virtual property lists)
1544
@code{OVPFONTS}, @code{TEXFONTS};
1548
@vindex PDFTEXCONFIG
1549
(PDF@TeX{}-specific configuration files)
1550
@code{PDFTEXCONFIG}.
1558
(packed bitmap fonts, @pxref{Glyph files,,, dvips, Dvips})
1559
@code{@var{PROGRAM}FONTS} (@var{program} being @samp{XDVI}, etc.),
1560
@code{PKFONTS}, @code{TEXPKS}, @code{GLYPHFONTS}, @code{TEXFONTS};
1562
dynamic creation program: @code{mktexpk}.
1564
@item PostScript header
1566
@vindex TEXPSHEADERS
1568
(downloadable PostScript, @pxref{Header files,,, dvips, Dvips})
1569
@code{TEXPSHEADERS}, @code{PSHEADERS};
1570
additional suffix @samp{.pro}.
1572
@item subfont definition files
1575
(subfont definition files)
1582
(@TeX{} source, @pxref{tex invocation,,, web2c, Web2c})
1585
additional suffixes: none, because such a list cannot be complete;
1586
dynamic creation program: @code{mktextex}.
1588
@item TeX system documentation
1591
(Documentation files for the @TeX{} system)
1594
@item TeX system sources
1595
@flindex source files
1597
(Source files for the @TeX{} system)
1601
@vindex TEXMFSCRIPTS
1602
(Architecture-independent executables distributed in the texmf tree)
1603
@code{TEXMFSCRIPTS}.
1608
(@TeX{} program strings, @pxref{pooltype invocation,,, web2c, Web2c})
1609
@code{TEXPOOL}, @code{TEXMFINI};
1610
suffix @samp{.pool}.
1616
(@TeX{} font metrics, @pxref{Metric files,,, dvips, Dvips})
1617
@code{TFMFONTS}, @code{TEXFONTS};
1619
dynamic creation program: @code{mktextfm}.
1623
(Troff fonts, used by DMP; @pxref{DMP invocation,,, web2c, Web2c})
1626
@item truetype fonts
1630
(TrueType outline fonts) @code{TTFONTS}; suffixes @samp{.ttf},
1638
@vindex TEXPSHEADERS
1639
@vindex DVIPSHEADERS
1640
(Type 1 PostScript outline fonts, @pxref{Glyph files,,, dvips, Dvips})
1641
@code{T1FONTS}, @code{T1INPUTS}, @code{TEXPSHEADERS}, @code{DVIPSHEADERS};
1642
suffixes @samp{.pfa}, @samp{.pfb}.
1646
(Type 42 PostScript outline fonts) @code{T42FONTS}.
1652
(virtual fonts, @pxref{Virtual fonts,,, dvips, Dvips})
1653
@code{VFFONTS}, @code{TEXFONTS};
1662
additional suffix @samp{.ch}.
1666
(files specific to the web2c implementation)
1670
There are two special cases, because the paths and environment variables
1671
always depend on the name of the program: the variable name is
1672
constructed by converting the program name to upper case, and then
1673
appending @samp{INPUTS}. Assuming the program is called @samp{foo},
1674
this gives us the following table.
1677
@item other text files
1679
(text files used by @samp{foo})
1682
@item other binary files
1684
(binary files used by @samp{foo})
1688
If an environment variable by these names are set, the corresponding
1689
@file{texmf.cnf} definition won't be looked at (unless, as usual, the
1690
environment variable value has an extra @samp{:}). @xref{Default
1693
For the font variables, the intent is that:
1696
@code{TEXFONTS} is the default for everything.
1699
@code{GLYPHFONTS} is the default for bitmap (or, more precisely,
1703
Each font format has a variable of its own.
1708
Each program has its own font override path as well; e.g.,
1709
@code{DVIPSFONTS} for Dvipsk. Again, this is for bitmaps, not metrics.
1715
@section File lookup
1718
@cindex searching for files
1719
@cindex @TeX{} file lookup
1721
This section describes how Kpathsea searches for most files (bitmap font
1722
searches are the exception, as described in the next section).
1724
Here is the search strategy for a file @var{name}:
1727
If the file format defines default suffixes, and the suffix of
1728
@var{name} name is not already a known suffix for that format, try the
1729
name with each default appended, and use alternative names found in the
1730
fontmaps if necessary. We postpone searching the disk as long as
1731
possible. Example: given @samp{foo.sty}, look for @samp{foo.sty.tex}
1732
before @samp{foo.sty}. This is unfortunate, but allows us to find
1733
@samp{foo.bar.tex} before @samp{foo.bar} if both exist and we were given
1737
Search for @var{name}, and if necessary for alternative names found in
1738
the fontmaps. Again we avoid searching the disk if possible. Example:
1739
given @samp{foo}, we look for @samp{foo}.
1742
If the file format defines a program to invoke to create missing files,
1743
run it (@pxref{mktex scripts}).
1747
@findex kpse_find_file
1748
This is implemented in the routine @code{kpse_find_file} in
1749
@file{kpathsea/tex-file.c}. You can watch it in action with the
1750
debugging options (@pxref{Debugging}).
1754
@section Glyph lookup
1756
@cindex glyph lookup
1757
@cindex searching for glyphs
1758
@cindex @TeX{} glyph lookup
1760
This section describes how Kpathsea searches for a bitmap font in GF or
1761
PK format (or either) given a font name (e.g., @samp{cmr10}) and a
1762
resolution (e.g., 600).
1764
Here is an outline of the search strategy (details in the sections
1765
below) for a file @var{name} at resolution @var{dpi}. The search stops
1766
at the first successful lookup.
1770
Look for an existing file @var{name}.@var{dpi}@var{format} in the
1771
specified format(s).
1773
@item If @var{name} is an alias for a file @var{f} in the fontmap
1774
file @file{texfonts.map}, look for @var{f}.@var{dpi}.
1776
@item Run an external program (typically named @samp{mktexpk}) to
1777
generate the font (@pxref{mktex scripts})
1779
@item Look for @var{fallback}.@var{dpi}, where @var{fallback} is some
1780
last-resort font (typically @samp{cmr10}).
1783
@flindex tex-glyph.c
1784
@findex kpse_find_glyph_format
1785
This is implemented in @code{kpse_find_glyph_format} in
1786
@file{kpathsea/tex-glyph.c}.
1789
* Basic glyph lookup:: Features common to all glyph lookups.
1790
* Fontmap:: Aliases for fonts.
1791
* Fallback font:: Resolutions and fonts of last resort.
1795
@node Basic glyph lookup
1796
@subsection Basic glyph lookup
1798
@cindex basic glyph lookup
1799
@cindex common features in glyph lookup
1801
When Kpathsea looks for a bitmap font @var{name} at resolution @var{dpi}
1802
in a format @var{format}, it first checks each directory in the search
1803
path for a file @samp{@var{name}.@var{dpi}@var{format}}; for example,
1804
@samp{cmr10.600pk}. Kpathsea looks for a PK file first, then a GF file.
1806
If that fails, Kpathsea looks for
1807
@samp{dpi@var{dpi}/@var{name}.@var{format}}; for example,
1808
@samp{dpi600/cmr10.pk}. This is how fonts are typically stored on
1809
filesystems (such as DOS) that permit only three-character extensions.
1811
@cindex tolerance for glyph lookup
1812
@cindex glyph lookup bitmap tolerance
1813
@findex KPSE_BITMAP_TOLERANCE
1814
If that fails, Kpathsea looks for a font with a close-enough @var{dpi}.
1815
``Close enough'' is defined by the macro @code{KPSE_BITMAP_TOLERANCE} in
1816
@file{kpathsea/tex-glyph.h} to be @code{@var{dpi} / 500 + 1}. This is
1817
slightly more than the 0.2% minimum allowed by the DVI standard
1818
(@url{@var{CTAN:}/dviware/driv-standard/level-0}).
1824
@cindex fontmap files
1825
@cindex font alias files
1826
@cindex aliases for fonts
1828
@flindex texfonts.map
1829
If a bitmap font or metric file is not found with the original name (see
1830
the previous section), Kpathsea looks through any @dfn{fontmap} files
1831
for an @dfn{alias} for the original font name. These files are named
1832
@file{texfonts.map} and searched for along the @code{TEXFONTMAPS}
1833
environment/config file variable. All @file{texfonts.map} files that
1834
are found are read; earlier definitions override later ones.
1836
This feature is intended to help in two respects:
1841
@cindex fontnames, arbitrary length
1842
An alias name is limited in length only by available memory, not by your
1843
filesystem. Therefore, if you want to ask for @samp{Times-Roman}
1844
instead of @file{ptmr}, you can (you get @samp{ptmr8r}).
1847
@cindex circle fonts
1849
A few fonts have historically had multiple names: specifically,
1850
La@TeX{}'s ``circle font'' has variously been known as @file{circle10},
1851
@file{lcircle10}, and @file{lcirc10}. Aliases can make all the names
1852
equivalent, so that it no longer matters what the name of the installed
1853
file is; @TeX{} documents will find their favorite name.
1857
The format of fontmap files is straightforward:
1860
@cindex comments, in fontmap files
1861
@item Comments start with @samp{%} and continue to the end of the line.
1862
@cindex whitespace, in fontmap files
1863
@item Blank lines are ignored.
1864
@item Each nonblank line is broken up into a series of @dfn{words}:
1865
a sequence of non-whitespace characters.
1866
@findex include @r{fontmap directive}
1867
@item If the first word is @samp{include}, the second word is used as
1868
a filename, and it is searched for and read.
1869
@item Otherwise, the first word on each line is the true filename;
1870
@item the second word is the alias;
1871
@item subsequent words are ignored.
1874
If an alias has an extension, it matches only those files with that
1875
extension; otherwise, it matches anything with the same root, regardless
1876
of extension. For example, an alias @samp{foo.tfm} matches only when
1877
@file{foo.tfm} is being searched for; but an alias @samp{foo} matches
1878
@file{foo.vf}, @file{foo.600pk}, etc.
1880
As an example, here is an excerpt from the @file{texfonts.map} in the
1881
Web2c distribution. It makes the circle fonts equivalent and includes
1882
automatically generated maps for most PostScript fonts available from
1883
various font suppliers.
1895
include bitstrea.map
1899
Fontmaps are implemented in the file @file{kpathsea/fontmap.c}.
1900
The Fontname distribution has much more information on font naming
1901
(@pxref{Introduction,,, fontname, Filenames for @TeX{} fonts}).
1905
@subsection Fallback font
1907
@cindex fallback font
1908
@cindex fallback resolutions
1909
@cindex font of last resort
1910
@cindex resolutions, last-resort
1911
@cindex last-resort font
1917
@vindex default_texsizes
1918
If a bitmap font cannot be found or created at the requested size,
1919
Kpathsea looks for the font at a set of @dfn{fallback resolutions}. You
1920
specify these resolutions as a colon-separated list (like search paths).
1921
Kpathsea looks first for a program-specific environment variable (e.g.,
1922
@code{DVIPSSIZES} for Dvipsk), then the environment variable
1923
@code{TEXSIZES}, then a default specified at compilation time (the Make
1924
variable @code{default_texsizes}). You can set this list to be empty if
1925
you prefer to find fonts at their stated size or not at all.
1927
@flindex cmr10@r{, as fallback font}
1928
@vindex kpse_fallback_font
1929
Finally, if the font cannot be found even at the fallback resolutions,
1930
Kpathsea looks for a fallback font, typically @file{cmr10}. Programs
1931
must enable this feature by assigning to the global variable
1932
@code{kpse_fallback_font} or calling @code{kpse_init_prog}
1933
(@pxref{Calling sequence}); the default is no fallback font.
1936
@node Suppressing warnings
1937
@section Suppressing warnings
1939
@cindex warnings, suppressing
1940
@cindex suppressing warnings
1943
Kpathsea provides a way to suppress selected usually-harmless warnings;
1944
this is useful at large sites where most users are not administrators,
1945
and thus the warnings are merely a source of confusion, not a help. To
1946
do this, you set the environment variable or configuration file value
1947
@code{TEX_HUSH} to a colon-separated list of values. Here are the
1952
Suppress everything possible.
1955
@cindex mismatched checksum warnings
1956
Suppress mismatched font checksum warnings.
1959
@cindex missing character warnings
1960
Suppress warnings when a character is missing from a font that a DVI or
1961
VF file tries to typeset.
1964
Don't suppress any warnings.
1967
@cindex unreadable file warnings
1968
Suppress warnings about attempts to access a file whose permissions
1969
render it unreadable.
1972
@cindex unknown special warnings
1973
@findex \special@r{, suppressing warnings about}
1974
Suppresses warnings about an unimplemented or unparsable
1975
@samp{\special} command.
1978
@noindent @file{tex-hush.c} defines the function that checks the
1979
variable value. Each driver implements its own checks where
1984
@chapter Programming
1986
This chapter is for programmers who wish to use Kpathsea.
1987
@xref{Introduction}, for the conditions under which you may do so.
1990
* Overview: Programming overview. Introduction.
1991
* Calling sequence:: Specifics of what to call.
1992
* Program-specific files:: How to handle these.
1993
* Config: Programming with config files. Getting info from texmf.cnf.
1997
@node Programming overview
1998
@section Programming overview
2000
@cindex programming overview
2001
@cindex overview of programming with Kpathsea
2003
Aside from this manual, your best source of information is the source to
2004
the programs I've modified to use Kpathsea (@pxref{Introduction}). Of
2005
those, Dviljk is probably the simplest, and hence a good place to start.
2006
Xdvik adds VF support and the complication of X resources. Dvipsk adds
2007
the complication of its own config files. Web2c is source code I also
2008
maintain, so it uses Kpathsea rather straightforwardly, but is of course
2009
complicated by the Web to C translation. Finally, Kpsewhich is a small
2010
utility program whose sole purpose is to exercise the main
2011
path-searching functionality.
2013
@flindex pathsearch.h
2015
@flindex tex-glyph.h
2017
Beyond these examples, the @file{.h} files in the Kpathsea source
2018
describe the interfaces and functionality (and of course the @file{.c}
2019
files define the actual routines, which are the ultimate documentation).
2020
@file{pathsearch.h} declares the basic searching routine.
2021
@file{tex-file.h} and @file{tex-glyph.h} define the interfaces for
2022
looking up particular kinds of files. In view of the way the headers
2023
depend on each other, it is recommended to use @code{#include
2024
<kpathsea/kpathsea.h>}, which includes every Kpathsea header.
2028
If you want to include only specific headers, you should still consider
2029
including @file{kpathsea/config.h} before including any other Kpathsea
2030
header, as it provides symbols used in the other headers. Note that
2031
@file{kpathsea/config.h} includes @file{kpathsea/c-auto.h}, which is
2032
generated by Autoconf.
2034
@cindex file types, registering new
2035
The library provides no way for an external program to register new file
2036
types: @file{tex-file.[ch]} must be modified to do this. For example,
2037
Kpathsea has support for looking up Dvips config files, even though no
2038
program other than Dvips will likely ever want to do so. I felt this
2039
was acceptable, since along with new file types should also come new
2040
defaults in @file{texmf.cnf} (and its descendant @file{paths.h}), since
2041
it's simplest for users if they can modify one configuration file for
2044
Kpathsea does not parse any formats itself; it barely opens any files.
2045
Its primary purpose is to return filenames. The GNU font utilities does
2046
contain libraries to read TFM, GF, and PK files, as do the programs
2050
@node Calling sequence
2051
@section Calling sequence
2053
@cindex programming with Kpathsea
2054
@cindex calling sequence
2056
The typical way to use Kpathsea in your program goes something like this:
2061
@findex kpse_set_program_name
2063
Call @code{kpse_set_program_name} with @code{argv[0]} as the first
2064
argument; the second argument is a string or @code{NULL}. The second
2065
argument is used by Kpathsea as the program name for the
2066
@code{.@var{program}} feature of config files (@pxref{Config files}).
2067
If the second argument is @code{NULL}, the value of the first argument
2068
is used. This function must be called before any other use of the
2071
@vindex program_invocation_name
2072
@vindex program_invocation_short_name
2073
@vindex kpse_program_name
2074
@vindex KPATHSEA_DEBUG
2077
@cindex SELFAUTOPARENT
2078
@cindex error message macros
2079
@cindex symlinks, resolving
2080
@cindex expanding symlinks
2081
If necessary, @code{kpse_set_program_name} sets the global variables
2082
@code{program_invocation_name} and @code{program_invocation_short_name}.
2083
These variables are used in the error message macros defined in
2084
@file{kpathsea/lib.h}. It sets the global variable
2085
@code{kpse_program_name} to the program name it uses. It also
2086
initializes debugging options based on the environment variable
2087
@code{KPATHSEA_DEBUG} (if that is set). Finally, it sets the variables
2088
@code{SELFAUTOLOC}, @code{SELFAUTODIR} and @code{SELFAUTOPARENT} to the
2089
location, parent and grandparent directory of the executable, removing
2090
@file{.} and @file{..} path elements and resolving symbolic links.
2091
These are used in the default configuration file to allow people to
2092
invoke TeX from anywhere, specifically from a mounted CD-ROM. (You can
2093
use @samp{--expand-var=\$SELFAUTOLOC}, etc., to see the values finds.)
2096
@findex kpse_set_progname
2098
The @code{kpse_set_progname} is deprecated. A call to
2099
@code{kpse_set_progname} with @code{argv[0]} is equivalent to a call of
2100
@code{kpse_set_program_name} with first argument @code{argv[0]} and
2101
second argument @code{NULL}. The function is deprecated because it
2102
cannot ensure that the @code{.@var{program}} feature of config files
2103
will always work (@pxref{Config files}).
2106
@vindex kpathsea_debug @r{variable}
2107
@cindex debugging options, in Kpathsea-using program
2108
Set debugging options. @xref{Debugging}. If your program doesn't have a
2109
debugging option already, you can define one and set
2110
@code{kpathsea_debug} to the number that the user supplies (as in Dviljk
2111
and Web2c), or you can just omit this altogether (people can always set
2112
@code{KPATHSEA_DEBUG}). If you do have runtime debugging already, you
2113
need to merge Kpathsea's options with yours (as in Dvipsk and Xdvik).
2116
@vindex client_path @r{in @code{kpse_format_info}}
2117
@vindex kpse_format_info
2119
@cindex config files, for Kpathsea-using programs
2120
If your program has its own configuration files that can define search
2121
paths, you should assign those paths to the @code{client_path} member in
2122
the appropriate element of the @code{kpse_format_info} array. (This
2123
array is indexed by file type; see @file{tex-file.h}.) See
2124
@file{resident.c} in Dvipsk for an example.
2127
@findex kpse_init_prog
2129
Call @code{kpse_init_prog} (see @file{proginit.c}). It's useful for the
2130
DVI drivers, at least, but for other programs it may be simpler to
2131
extract the parts of it that actually apply. This does not initialize
2132
any paths, it just looks for (and sets) certain environment variables
2133
and other random information. (A search path is always initialized at
2134
the first call to find a file of that type; this eliminates much useless
2135
work, e.g., initializing the Bib@TeX{} search paths in a DVI driver.)
2139
@findex kpse_find_file
2140
The routine to actually find a file of type @var{format} is
2141
@code{kpse_find_@var{format}}, defined in @file{tex-file.h}. These are
2142
macros that expand to a call to @file{kpse_find_file}. You can call,
2143
say, @code{kpse_find_tfm} after doing only the first of the
2144
initialization steps above---Kpathsea automatically reads the
2145
@file{texmf.cnf} generic config files, looks for environment variables,
2146
and does expansions at the first lookup.
2149
To find PK and/or GF bitmap fonts, the routines are @code{kpse_find_pk},
2150
@code{kpse_find_gf} and @code{kpse_find_glyph}, defined in
2151
@file{tex-glyph.h}. These return a structure in addition to the
2152
resultant filename, because fonts can be found in so many ways. See the
2153
documentation in the source.
2156
@findex kpse_open_file
2157
To actually open a file, not just return a filename, call
2158
@code{kpse_open_file}. This function takes the name to look up and a
2159
Kpathsea file format as arguments, and returns the usual @code{FILE *}.
2160
It always assumes the file must exist, and thus will search the disk if
2161
necessary (unless the search path specified @samp{!!}, etc.). In other
2162
words, if you are looking up a VF or some other file that need not
2163
exist, don't use this.
2167
@cindex hash table routines
2168
@cindex memory allocation routines
2169
@cindex string routines
2170
@cindex reading arbitrary-length lines
2171
@cindex input lines, reading
2172
@cindex lines, reading arbitrary-length
2173
Kpathsea also provides many utility routines. Some are generic: hash
2174
tables, memory allocation, string concatenation and copying, string
2175
lists, reading input lines of arbitrary length, etc. Others are
2176
filename-related: default path, tilde, and variable expansion,
2177
@code{stat} calls, etc. (Perhaps someday I'll move the former to a
2181
@pindex autoconf@r{, recommended}
2182
The @file{c-*.h} header files can also help your program adapt to many
2183
different systems. You will almost certainly want to use Autoconf for
2184
configuring your software if you use Kpathsea; I strongly recommend
2185
using Autoconf regardless. It is available from
2186
@url{ftp://prep.ai.mit.edu/pub/gnu/}.
2189
@node Program-specific files
2190
@section Program-specific files
2192
Many programs will need to find some configuration files. Kpathsea
2193
contains some support to make it easy to place them in their own
2194
directories. The Standard @TeX{} directory structure (@pxref{Top,,
2195
Introduction, tds, A Directory Structure for @TeX{} files}), specifies
2196
that such files should go into a subdirectory named after the program,
2197
like @samp{texmf/ttf2pk}.
2199
Two special formats, @samp{kpse_program_text_format} and
2200
@samp{kpse_program_binary_format} exist, which use
2201
@code{.:$TEXMF/@var{program}//} as their compiled-in search path. To
2202
override this default, you can use the variable
2203
@code{@var{PROGRAM}INPUTS} in the environment and/or @samp{texmf.cnf}.
2204
That is to say, the name of the variable is constructed by converting
2205
the name of the program to upper case, and appending @code{INPUTS}.
2207
The only difference between these two formats is whether
2208
@code{kpse_open_file} will open the files it finds in text or binary
2212
@node Programming with config files
2213
@section Programming with config files
2215
@cindex programming with config files
2216
@cindex config files, programming with
2218
You can (and probably should) use the same @code{texmf.cnf}
2219
configuration file that Kpathsea uses for your program. This helps
2220
installers by keeping all configuration in one place.
2222
@findex kpse_var_value
2224
@vindex shell_escape@r{, example for code}
2225
To retrieve a value @var{var} from config files, the best way is to call
2226
@code{kpse_var_value} on the string @code{@var{var}}. This will look
2227
first for an environment variable @var{var}, then a config file value.
2228
The result will be the value found or @samp{NULL}. This function is
2229
declared in @file{kpathsea/variable.h}. For an example, see the
2230
@code{shell_escape} code in @file{web2c/lib/texmfmp.c}.
2232
The routine to do variable expansion in the context of a search path (as
2233
opposed to simply retrieving a value) is @code{kpse_var_expand}, also
2234
declared in @file{kpathsea/variable.h}. It's generally only necessary
2235
to set the search path structure components as explained in the previous
2236
section, rather than using this yourself.
2238
@findex kpse_cnf_get
2240
If for some reason you want to retrieve a value @emph{only} from a
2241
config file, not automatically looking for a corresponding environment
2242
variable, call @code{kpse_cnf_get} (declared in @file{kpathsea/cnf.h})
2243
with the string @var{var}.
2245
No initialization calls are needed.
added
removed
src/texk/kpathsea/kpathsea.texi
