diff options
Diffstat (limited to 'Build/source/texk/kpathsea/doc/kpathsea.texi')
-rw-r--r-- | Build/source/texk/kpathsea/doc/kpathsea.texi | 3931 |
1 files changed, 3931 insertions, 0 deletions
diff --git a/Build/source/texk/kpathsea/doc/kpathsea.texi b/Build/source/texk/kpathsea/doc/kpathsea.texi new file mode 100644 index 00000000000..00ff64eefbe --- /dev/null +++ b/Build/source/texk/kpathsea/doc/kpathsea.texi @@ -0,0 +1,3931 @@ +\input texinfo +@setfilename kpathsea.info +@settitle Kpathsea: A library for path searching + +@set version 6.3.3 +@set month-year February 2021 + +@copying +This file documents the Kpathsea library for path searching. + +Copyright @copyright{} 1996--2021 Karl Berry & Olaf Weber. + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +approved by the @TeX{} Users Group. +@end copying + +@c Define new indices for commands, filenames, and options. +@defcodeindex cm +@defcodeindex fl +@defcodeindex op + +@c Put everything in one index (arbitrarily chosen to be the concept index). +@syncodeindex cm cp +@syncodeindex fl cp +@syncodeindex fn cp +@syncodeindex ky cp +@syncodeindex op cp +@syncodeindex pg cp +@syncodeindex tp cp +@syncodeindex vr cp + +@dircategory TeX +@direntry +* Kpathsea: (kpathsea). File lookup along search paths. +* kpsewhich: (kpathsea)Invoking kpsewhich. TeX file searching. +* mktexfmt: (kpathsea)mktex scripts. Format (fmt/base/mem) generation. +* mktexlsr: (kpathsea)Filename database. Update ls-R. +* mktexmf: (kpathsea)mktex scripts. MF source generation. +* mktexpk: (kpathsea)mktex scripts. PK bitmap generation. +* mktextex: (kpathsea)mktex scripts. TeX source generation. +* mktextfm: (kpathsea)mktex scripts. TeX font metric generation. +@end direntry + + +@titlepage +@title Kpathsea library +@subtitle for version @value{version} +@subtitle @value{month-year} +@author Karl Berry +@author Olaf Weber +@author Taco Hoekwater +@author @url{https://tug.org/kpathsea} + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + + +@contents + + +@ifnottex +@node Top +@top Kpathsea library + +This manual documents the Kpathsea library for path searching. It +corresponds to version @value{version}, released in +@value{month-year}. + +@menu +* Introduction:: Overview and history. + +* unixtex.ftp:: Obtaining @TeX{} software. +* Security:: Who can write what files, etc. +* TeX directory structure:: Managing the horde of @TeX{} input files. + +* Path searching:: How filename lookups work. +* TeX support:: Special support for TeX-related file lookups. + +* Programming:: How to use Kpathsea features in your program. + +* Reporting bugs:: Where and how to report bugs. +* Index:: General index. +@end menu +@end ifnottex + + +@node Introduction +@chapter Introduction + +@cindex introduction +@cindex fundamental purpose of Kpathsea + +This manual corresponds to version @value{version} of the Kpathsea +library, released in @value{month-year}. + +The library's fundamental purpose is to return a filename from a list of +directories specified by the user, similar to what shells do when +looking up program names to execute. + +@cindex programs using the library +The following software, all of which is maintained in parallel, uses +this library: + +@itemize @bullet +@item Dviljk (see the @samp{dvilj} man page) +@item Dvipsk (@pxref{,,,dvips, Dvips: A DVI driver}) +@item GNU font utilities (@pxref{,,,fontu, GNU font utilities}) +@item Web2c (@pxref{,,,web2c, Web2c: A @TeX{} implementation}) +@item Xdvik (see the @samp{xdvi} man page) +@end itemize + +@noindent Other software that we do not maintain also uses it. + +Kpathsea is now maintained as part of the @TeX{} Live distribution +(@url{https://tug.org/texlive}), which includes several more +Kpathsea-using programs. For information on configuration, building, +installing, and more, @pxref{,,,tlbuild, Building @TeX{} Live}. + +@cindex interface, not frozen +@cindex comments, making +@cindex suggestions, making +The library is still actively maintained. If you have comments or +suggestions, please send along (@pxref{Reporting bugs}). + +@cindex conditions for use +@cindex license for using the library +@cindex GNU General Public License +The Kpathsea library is distributed under the GNU Library General +Public License (LGPL), version@tie{}2.1 or (at your option) any later +version. In short, this means if you write a program using the +library, you must (offer to) distribute the source to the library, +along with any changes you have made, and allow anyone to modify the +library source and distribute their modifications. It does not mean +you have to distribute the source to your program using the library, +although we hope you will. See accompanying files for the text of the +GNU licenses, or @url{https://gnu.org/licenses}. + +@cindex @TeX{} Users Group +If you know enough about @TeX{} to be reading this manual, then you (or +your institution) should consider joining the @TeX{} Users Group (if +you're already a member, thanks!). TUG produces the periodical +@cite{TUGboat}, sponsors an annual meeting and publishes the +proceedings, and arranges courses on @TeX{} for all levels of users +throughout the world. See @url{https://tug.org} for information. + +@menu +* History:: +@end menu + + +@node History +@section History + +@cindex history of Kpathsea + +@cindex Knuth, Donald E. +This section is for those people who are curious about how the library +came about. If you like to read historical accounts of software, we +urge you to seek out the GNU Autoconf manual and the ``Errors of +@TeX{}'' paper by Don Knuth, published in his book @cite{Digital +Typography}, among other places. + +@cindex Morgan, Tim +@cindex Rokicki, Tom +@cindex Berry, Karl +@cindex VAX 11/750 +@cindex Sun 2 +@pindex pxp @r{Pascal preprocessor} +@pindex pc @r{Pascal compiler} +[Karl writes.] My first ChangeLog entry for Web2c seems to be +February 1990, but I may have done some work before then. In any +case, Tim Morgan and I were jointly maintaining it for a time. (I +should mention here that Tim had made Web2c into a real distribution +long before I had ever used it or even heard of it, and Tom Rokicki +did the original implementation. When I started, I was using +@code{pxp} and @code{pc} on VAX 11/750's and the hot new Sun 2 +machines.) + +It must have been later in 1990 and 1991 that I started working on +@cite{@TeX{} for the Impatient}. Dvips, Xdvi, Web2c, and the GNU +fontutils (which I was also writing at the time) all used different +environment variables, and, more importantly, had different bugs in +their path searching. This became extremely painful, as I was stressing +everything to the limit working on the book. I also desperately wanted +to implement subdirectory searching, since I couldn't stand putting +everything in one big directory, and also couldn't stand having to +explicitly specify @file{cm}, @file{pandora}, @dots{} in a path. + +@cindex Vojta, Paul +In the first incarnation, I just hacked separately on each +program---that was the original subdirectory searching code in both +Xdvi and Dvips. That is, I tried to go with the flow in each program, +rather than changing the program's calling sequences to conform to new +routines. + +Then, as bugs inevitably appeared, I found I was fixing the same thing +three times (Web2c and fontutils were already sharing code, since I +maintained both of those---there was no Dvipsk or Xdvik or Dviljk at +this point). After a while, I finally started sharing source files. +They weren't yet a library, though. I just kept things up to date +with shell scripts. (I was developing on a 386 running ISC 2.2 at the +time, and so didn't have symbolic links. An awful experience.) + +@cindex MacKenzie, David +The ChangeLogs for Xdvik and Dvipsk record initial releases of those +distributions in May and June 1992. I think it was because I was tired +of the different configuration strategies of each program, not so much +because of the path searching. Autoconf was being developed by David +MacKenzie and others, and I was adapting it to @TeX{} and friends. + +@cindex zuhn, david +I started to make a separate library that other programs could link with +on my birthday in April 1993, according to the ChangeLog. I don't +remember exactly why I finally took the time to make it a separate +library; a conversation with david zuhn initiated it. Just seemed +like it was time. + +@cindex Walsh, Norman +@cindex Neumann, Gustaf +Dviljk got started in March 1994 after I bought a Laserjet 4. (Kpathsea +work got suspended while Norm Walsh and I, with Gustaf Neumann's help, +implemented a way for @TeX{} to get at all those neat builtin LJ4 fonts +@dots{} such a treat to have something to typeset in besides Palatino!) + +By spring of 1995, I had implemented just about all the path-searching +features in Kpathsea that I plan to, driven beyond my initial goals by +Thomas Esser and others. I then started to integrate Web2c with +Kpathsea. After the release of a stable Web2c, I hope to be able to stop +development, and turn most of my attention back to making fonts for GNU. +(Always assuming Micros**t hasn't completely obliterated Unix by then, +or that software patents haven't stopped software development by anybody +smaller than a company with a million-dollar-a-year legal budget. Which +is actually what I think is likely to happen, but that's another +story@dots{}) + +@cindex Weber, Olaf +[Olaf writes.] At the end of 1997, Unix is still alive and kicking, +individuals still develop software, and Web2c development still +continues. Karl had been looking for some time for someone to take up +part of the burden, and I volunteered. + +@cindex Hoekwater, Taco +@cindex Breitenlohner, Peter +[Karl writes again.] Indeed, time goes on. As of 2006 or so, Olaf's +available time for Kpathsea was reduced, and I started taking overall +care of it again, although I did not do any significant new +development. In 2009, Taco Hoekwater implemented a major +rearrangement to make the library suitable for use within the MetaPost +library (@pxref{Programming overview}). Also, for some years now, +Peter Breitenlohner has made many improvements to the infrastructure +and kept it up-to-date with respect to the overall @TeX{} Live build, +where Kpathsea is now maintained. + + +@c emacs-page separate file so we can easily generate unixtex.ftp. +@include unixtex.texi + + +@node Security +@chapter Security + +@cindex security considerations + +None of the programs in the @TeX{} system require any special system +privileges, so there's no first-level security concern of people gaining +illegitimate root access. + +@cindex trojan horse attack +@flindex .rhosts@r{, writable by @TeX{}} +A @TeX{} document, however, can write to arbitrary files, e.g., +@file{~/.rhosts}, and thus an unwitting user who runs @TeX{} on a random +document is vulnerable to a trojan horse attack. This loophole is +closed by default, but you can be permissive if you so desire in +@file{texmf.cnf}. @xref{tex invocation,,, web2c, Web2c}. MetaPost has +the same issue. + +Dvips, Xdvi, and @TeX{} can also execute shell commands under some +circumstances. To disable this, see the @samp{-R} option in @ref{Option +details,,, dvips, Dvips}, the xdvi man page, and @ref{tex +invocation,,, web2c, Web2c}, respectively. + +@cindex local cache of fonts +@cindex cache of fonts, local +Another security issue arises because it's very useful---almost +necessary---to make arbitrary fonts on user demand with @code{mktexpk} +and friends. Where do these files get installed? By default, the +@code{mktexpk} distributed with Kpathsea assumes a world-writable +@file{/var/tmp} directory; this is a simple and convenient approach, but +it may not suit your situation because it means that a local cache of +fonts is created on every machine. + +@cindex globally writable directories +To avoid this duplication, many people consider a shared, globally +writable font tree desirable, in spite of the potential security +problems. To do this you should change the value of @code{VARTEXFONTS} +in @file{texmf.cnf} to refer to some globally known directory. +@xref{mktex configuration}. + +@cindex append-only directories and @code{mktexpk} +The first restriction you can apply is to make newly-created directories +under @file{texmf} be append-only with an option in @file{mktex.cnf}. +@xref{mktex configuration}. + +@cindex group-writable directories +@cindex setgid scripts +Another approach is to establish a group (or user) for @TeX{} files, +make the @file{texmf} tree writable only to that group (or user), and +make @code{mktexpk} et al.@: setgid to that group (or setuid to that +user). Then users must invoke the scripts to install things. (If +you're worried about the inevitable security holes in scripts, then you +could write a C wrapper to exec the script.) + +@cindex file permissions +@cindex permissions, file +The @file{mktex@dots{}} scripts install files with the same read and +write permissions as the directory they are installed in. The +executable, sgid, suid, and sticky bits are always cleared. + +@cindex directory permissions +@cindex permissions, directory +Any directories created by the @file{mktex@dots{}} scripts have the +same permissions as their parent directory, unless the +@code{appendonlydir} feature is used, in which case the sticky bit is +always set. + + +@node TeX directory structure +@chapter @TeX{} directory structure + +@vindex TEXMF +@cindex @TeX{} directory structure +@cindex directory structure, for @TeX{} files +@cindex skeleton @TeX{} directory +@cindex TDS + +This section describes the default installation hierarchy of the +distribution. It conforms to both the GNU coding standards and the +@TeX{} directory structure (TDS) standard. For rationale and further +explanation, please see those documents. The GNU document is +available from @url{https://gnu.org/prep/standards}. The TDS +document is available from @url{http://mirror.ctan.org/tds} +(@pxref{unixtex.ftp}). + +In short, here is a skeleton of the default directory structure, +extracted from the TDS document: + +@example +@var{prefix}/ @r{installation root (@file{/usr/local} by default)} + bin/ @r{executables} + man/ @r{man pages} + include/ @r{C header files} + info/ @r{GNU info files} + lib/ @r{libraries (@file{libkpathsea.*})} + share/ @r{architecture-independent files} + texmf/ @r{TDS root} + bibtex/ @r{Bib@TeX{} input files} + bib/ @r{Bib@TeX{} databases} + base/ @r{base distribution (e.g., @samp{xampl.bib})} + misc/ @r{single-file databases} + @var{pkg}/ @r{name of a package} + bst/ @r{Bib@TeX{} style files} + base/ @r{base distribution (e.g., @samp{plain.bst}, @samp{acm.bst})} + misc/ @r{single-file styles} + @var{pkg}/ @r{name of a package} + doc/ @r{additional documentation} + dvips/ @r{@samp{.pro}, @samp{.ps}, @samp{psfonts.map}} + fonts/ @r{font-related files} + @var{type}/ @r{file type (e.g., @samp{tfm}, @samp{pk})} + @var{mode}/ @r{type of output device (types @samp{pk} and @samp{gf} only)} + @var{supplier}/ @r{name of a font supplier (e.g., @samp{public})} + @var{typeface}/ @r{name of a typeface (e.g., @samp{cm})} + dpi@var{nnn}/ @r{font resolution (types @samp{pk} and @samp{gf} only)} + metafont/ @r{Metafont (non-font) input files} + base/ @r{base distribution (e.g., @samp{plain.mf})} + misc/ @r{single-file packages (e.g., @samp{modes.mf})} + @var{pkg}/ @r{name of a package (e.g., @samp{mfpic})} + metapost/ @r{MetaPost input files} + base/ @r{base distribution (e.g., @samp{plain.mp})} + misc/ @r{single-file packages} + @var{pkg}/ @r{name of a package} + support/ @r{support files for MetaPost-related utilities (e.g., @samp{trfonts.map})} + mft/ @r{@samp{MFT} inputs (e.g., @samp{plain.mft})} + tex/ @r{@TeX{} input files} + @var{format}/ @r{name of a format (e.g., @samp{plain})} + base/ @r{base distribution for @var{format} (e.g., @samp{plain.tex})} + misc/ @r{single-file packages (e.g., @samp{webmac.tex})} + local/ @r{local additions to or local configuration files for @var{format}} + @var{pkg}/ @r{name of a package (e.g., @samp{graphics}, @samp{mfnfss})} + generic/ @r{format-independent packages} + hyphen/ @r{hyphenation patterns (e.g., @samp{hyphen.tex})} + images/ @r{image input files (e.g., Encapsulated PostScript)} + misc/ @r{single-file format-independent packages (e.g., @samp{null.tex}).} + @var{pkg}/ @r{name of a package (e.g., @samp{babel})} + web2c/ @r{implementation-dependent files (@file{.pool}, @file{.fmt}, @file{texmf.cnf}, etc.)} +@end example + +Some concrete examples for most file types: + +@example +/usr/local/bin/tex +/usr/local/man/man1/xdvi.1 +/usr/local/info/kpathsea.info +/usr/local/lib/libkpathsea.a +/usr/local/share/texmf/bibtex/bst/base/plain.bst +/usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk +/usr/local/share/texmf/fonts/source/public/pandora/pnr10.mf +/usr/local/share/texmf/fonts/tfm/public/cm/cmr10.tfm +/usr/local/share/texmf/fonts/type1/adobe/utopia/putr.pfa +/usr/local/share/texmf/metafont/base/plain.mf +/usr/local/share/texmf/metapost/base/plain.mp +/usr/local/share/texmf/tex/plain/base/plain.tex +/usr/local/share/texmf/tex/generic/hyphen/hyphen.tex +/usr/local/share/texmf/web2c/tex.pool +/usr/local/share/texmf/web2c/tex.fmt +/usr/local/share/texmf/web2c/texmf.cnf +@end example + + +@node Path searching +@chapter Path searching + +@cindex path searching + +This chapter describes the generic path searching mechanism Kpathsea +provides. For information about searching for particular file types +(e.g., @TeX{} fonts), see the next chapter. + +@cindex translations, of path searching description +This section, with minor differences, has been translated into several +other languages (Chinese, Spanish, Russian, Japanese, French, German, +@dots{}) as part of the @TeX{} Live guide; see +@url{https://tug.org/texlive/doc.html} for links. + +@menu +* Searching overview:: Basic scheme for searching. +* Path sources:: Where search paths can be defined. +* Path expansion:: Special constructs in search paths. +* Casefolding search:: Fallback to case-insensitive search. +* Filename database:: Using an externally-built list to search. +* Invoking kpsewhich:: Standalone path lookup. +@end menu + + +@node Searching overview +@section Searching overview + +@cindex searching overview +@cindex path searching, overview +@cindex overview of path searching + +@cindex search path, defined +A @dfn{search path} is a colon-separated list of @dfn{path elements}, +which are directory names with a few extra frills. A search path can +come from (a combination of) many sources; see below. To look up a file +@samp{foo} along a path @samp{.:/dir}, Kpathsea checks each element of +the path in turn: first @file{./foo}, then @file{/dir/foo}, returning +the first match (or possibly all matches). + +@cindex magic characters +@kindex : @r{may not be :} +@kindex / @r{may not be /} +The ``colon'' and ``slash'' mentioned here aren't necessarily @samp{:} +and @samp{/} on non-Unix systems. Kpathsea tries to adapt to other +operating systems' conventions. + +@cindex database search +@cindex searching the database +To check a particular path element @var{e}, Kpathsea first sees if a +prebuilt database (@pxref{Filename database}) applies to @var{e}, i.e., +if the database is in a directory that is a prefix of @var{e}. If so, +the path specification is matched against the contents of the database. + +@cindex floating directories +@cindex filesystem search +@cindex disk search +@cindex searching the disk +If the database does not exist, or does not apply to this path element, +or contains no matches, the filesystem is searched (if this was not +forbidden by the specification with @samp{!!} and if the file being +searched for must exist). Kpathsea constructs the list of directories +that correspond to this path element, and then checks in each for the +file being searched for. (To help speed future lookups of files in the +same directory, the directory in which a file is found is floated to the +top of the directory list.) + +@cindex must exist +@cindex VF files, not found +@flindex cmr10.vf +@findex \openin +The ``file must exist'' condition comes into play with VF files and +input files read by the @TeX{} @samp{\openin} command. These files +might very well not exist (consider @file{cmr10.vf}), and so it would +be wrong to search the disk for them. Therefore, if you fail to +update @file{ls-R} when you install a new VF file, it will not be +found. + +Each path element is checked in turn: first the database, then the +disk. If a match is found, the search stops and the result is +returned (unless the search explicitly requested all matches). This +avoids possibly-expensive processing of path specifications that are +never needed on a particular run. + +On Unix-like systems, if no match is found by any of the above, and +the path element allows checking the filesystem (per the above), a +final check is made for a case-insensitive match. Thus, looking for a +name like @samp{./FooBar.TeX} will match a file @samp{./foobar.tex}, +and vice versa. This is not done on Windows. @xref{Casefolding +search}. + +@cindex expansion, path element +Although the simplest and most common path element is a directory name, +Kpathsea supports additional features in search paths: layered default +values, environment variable names, config file values, users' home +directories, and recursive subdirectory searching. Thus, we say that +Kpathsea @dfn{expands} a path element, meaning transforming all the +magic specifications into the basic directory name or names. This +process is described in the sections below. It happens in the same +order as the sections. + +@cindex absolute filenames +@cindex relative filenames +@cindex explicitly relative filenames +@cindex filenames, absolute or explicitly relative +Exception to all of the above: If the filename being searched for is +absolute or explicitly relative, i.e., starts with @samp{/} or @samp{./} +or @samp{../}, Kpathsea simply checks if that file exists, with a +fallback to a casefolding match if needed and enabled, as described above. + +@cindex permission denied +@cindex unreadable files +@cindex access warnings +@cindex warnings, file access +@flindex lost+found @r{directory} +@vindex TEX_HUSH +Ordinarily, if Kpathsea tries to access a file or directory that +cannot be read, it gives a warning. This is so you will be alerted to +directories or files that accidentally lack any read permission (for +example, a @file{lost+found} directory). If you prefer not to see +these warnings, include the value @samp{readable} in the +@code{TEX_HUSH} environment variable or config file value. + +This generic path searching algorithm is implemented in +@file{kpathsea/pathsearch.c}. It is employed by a higher-level +algorithm when searching for a file of a particular type (@pxref{File +lookup}, and @ref{Glyph lookup}). + + +@node Path sources +@section Path sources + +@cindex path sources +@cindex sources for search paths + +A search path or other configuration value can come from many sources. +In the order in which Kpathsea looks for them: + +@enumerate +@item +@opindex @samp{--cnf-line}, source for path +A command-line option such as @code{--cnf-line}, available in +@file{kpsewhich} and most @TeX{} engines. @xref{Path searching +options}. + +@cindex environment variable, source for path +A user-set environment variable, e.g., @code{TEXINPUTS}. +Environment variables with an underscore and the program name appended +override; for example, @code{TEXINPUTS_latex} overrides @code{TEXINPUTS} +if the program being run is named @samp{latex}. + +@item +A program-specific configuration file, e.g., an @samp{S /a:/b} line in +Dvips' @file{config.ps} (@pxref{Config files,,, dvips, Dvips}). + +@item +@cindex configuration file, source for path +@cindex Kpathsea config file, source for path +@flindex texmf.cnf@r{, source for path} +A line in a Kpathsea configuration file @file{texmf.cnf}, e.g., +@samp{TEXINPUTS=/c:/d} (see below). + +@item +@cindex compilation value, source for path +The compile-time default (specified in @file{kpathsea/paths.h}). +@end enumerate + +You can see each of these values for a given search path by using the +debugging options (@pxref{Debugging}). + +These sources may be combined via default expansion (@pxref{Default +expansion}). + +@menu +* Config files:: Kpathsea's runtime config files (texmf.cnf). +@end menu + + +@node Config files +@subsection Config files + +@cindex config files +@flindex texmf.cnf@r{, definition for} + +@cindex runtime configuration files +@vindex TEXMFCNF +As mentioned above, Kpathsea reads @dfn{runtime configuration files} +named @file{texmf.cnf} for search path and other definitions. The +search path used to look for these configuration files is named +@code{TEXMFCNF}, and is constructed in the usual way, as described +above, except that configuration files cannot be used to define the +path, naturally; also, an @file{ls-R} database is not used to search for +them. + +Kpathsea reads @emph{all} @file{texmf.cnf} files in the search path, not +just the first one found; definitions in earlier files override those in +later files. Thus, if the search path is @samp{.:$TEXMF}, values from +@file{./texmf.cnf} override those from @file{$TEXMF/texmf.cnf}. + +@vindex KPATHSEA_WARNING +@cindex warning, about missing @file{texmf.cnf} +@cindex @file{texmf.cnf} missing, warning about +If Kpathsea cannot find any @file{texmf.cnf} file, it reports a +warning including all the directories it checked. If you don't want +to see this warning, set the environment variable +@env{KPATHSEA_WARNING} to the single character @samp{0} (zero, not +oh). + +While (or instead of) reading this description, you may find it helpful +to look at the distributed @file{texmf.cnf}, which uses or at least +mentions most features. The format of @file{texmf.cnf} files follows: + +@itemize @bullet +@item +@cindex comments, in @file{texmf.cnf} +Comments start with @samp{%}, either at the beginning of a line or +preceded by whitespace, and continue to the end of the line. That is, +similar to most shells, a @samp{%} in the ``middle'' of a value does not +start a comment. Examples: + +@example +% this is a comment +var = a%b % but the value of var will be "a%b" +@end example + +@item +@cindex blank lines, in @file{texmf.cnf} +Blank lines are ignored. + +@item +@cindex backslash-newline +@cindex continuation character +@cindex whitespace, not ignored on continuation lines +@kindex \@r{, line continuation in @file{texmf.cnf}} +A @samp{\} at the end of a line acts as a continuation character, i.e., +the next line is appended. Whitespace at the beginning of continuation +lines is not ignored. + +@item Each remaining line will look like: + +@example +@var{variable} @r{[}. @var{progname}@r{]} @r{[}=@r{]} @var{value} +@end example + +@noindent where the @samp{=} and surrounding whitespace is optional. + +@item +@cindex identifiers, characters valid in +The @var{variable} name may contain any character other than whitespace, +@samp{=}, or @samp{.}, but sticking to @samp{A-Za-z_} is safest. + +@kindex .@var{progname} @r{qualifier in @file{texmf.cnf}} +@item If @samp{.@var{progname}} is present (preceding spaces are +ignored), the definition only applies if the program that is running +is named (i.e., the last component of @code{argv[0]} is) +@var{progname} or @file{@var{progname}.@{exe,bat,cmd,...@}}. Most +notably, this allows different flavors of @TeX{} to have different +search paths. The @var{progname} value is used literally, without +variable or other expansions. + +@item +@cindex right-hand side of variable assignments +Considered as strings, @var{value} may contain any character. +However, in practice most @file{texmf.cnf} values are related to path +expansion, and since various special characters are used in expansion, +such as braces and commas, they cannot be used in directory names. + +The @samp{$@var{var}.@var{prog}} feature is not available on the +right-hand side; instead, you must use an additional variable (see +below for example). + +@kindex ; @r{translated to @samp{:} in @file{texmf.cnf}} +A @samp{;} in @var{value} is translated to @samp{:} if running under +Unix, in order to have a single @file{texmf.cnf} that can support both +Unix and Windows systems. This translation happens with any value, not +just search paths, but fortunately in practice @samp{;} is not needed +in other values. + +@item All definitions are read before anything is expanded, so you can +use variables before they are defined (like Make, unlike most other +programs). +@end itemize + +@noindent Here is a configuration file fragment illustrating most of +these points: + +@example +% TeX input files -- i.e., anything to be found by \input or \openin ... +latex209_inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex// +latex2e_inputs = .:$TEXMF/tex/latex//:$TEXMF/tex// +TEXINPUTS = .:$TEXMF/tex// +TEXINPUTS.latex209 = $latex209_inputs +TEXINPUTS.latex2e = $latex2e_inputs +TEXINPUTS.latex = $latex2e_inputs +@end example + +@cindex shell scripts as configuration files +@cindex configuration files as shell scripts. +This format has some similarity to Bourne shell scripts---change the +comment character to @code{#}, disallow spaces around the @code{=}, +and get rid of the @code{.@var{name}} convention, and it could be run +through the shell. However, there seemed little advantage in this, +since all the information would have to passed back to Kpathsea and +parsed there anyway, since the @code{sh} process couldn't affect its +parent's environment. + +@kindex = @r{omitted in @file{texmf.cnf} and misparsing} +The combination of spaces being ignored before the @code{.} of a +program name qualifer and the optional @samp{=} for the assignment has +an unexpected consequence: if the value begins with a literal @samp{.} +and the @samp{=} is omitted, the intended value is interpreted as a +program name. For example, a line @code{var .;/some/path} is taken as +an empty value for @code{var} running under the program named +@samp{;/some/path}. To diagnose this, Kpathsea warns if the program +name contains a path separator or other special character. The +simplest way to avoid the problem is to use the @code{=}. + +Exactly when a character will be considered special or act as itself +depends on the context in which it is used. The rules are inherent in +the multiple levels of interpretation of the configuration (parsing, +expansion, search, @dots{}) and so cannot be concisely stated, +unfortunately. There is no general escape mechanism; in particular, +@samp{\} is not an ``escape character'' in @file{texmf.cnf} files. +When it comes choosing directory names for installation, it is safest to +avoid them all. + +@flindex cnf.c +The implementation of all this is in @file{kpathsea/cnf.c}. + + +@node Path expansion +@section Path expansion + +@cindex path expansion +@cindex expansion, search path + +Kpathsea recognizes certain special characters and constructions in +search paths, similar to that in shells. As a general example: +@samp{~$USER/@{foo,bar@}//baz} expands to all subdirectories under +directories @file{foo} and @file{bar} in @t{$USER}'s home directory that +contain a directory or file @file{baz}. + +These expansions are explained in the sections below. + +@menu +* Default expansion:: a: or :a or a::b expands to a default. +* Variable expansion:: $foo and $@{foo@} expand to environment values. +* Tilde expansion:: ~ and ~user expand to home directories. +* Brace expansion:: a@{foo,bar@}b expands to afoob abarb. +* KPSE_DOT expansion:: . is replaced with $KPSE_DOT if it is defined. +* Subdirectory expansion:: a// and a//b recursively expand to subdirs. +@end menu + + +@node Default expansion +@subsection Default expansion + +@kindex :: @r{expansion} +@cindex doubled colons +@cindex leading colons +@cindex trailing colons +@cindex extra colons +@cindex default expansion +@cindex expansion, default + +If the highest-priority search path (@pxref{Path sources}) contains an +@dfn{extra colon} (i.e., leading, trailing, or doubled), Kpathsea +inserts at that point the next-highest-priority search path that is +defined. If that inserted path has an extra colon, the same happens +with the next-highest. (An extra colon in the compile-time default +value has unpredictable results, so installers beware.) + +For example, given an environment variable setting + +@example +setenv TEXINPUTS /home/karl: +@end example + +@noindent and a @code{TEXINPUTS} value from @file{texmf.cnf} of + +@example +.:$TEXMF//tex +@end example + +@noindent then the final value used for searching will be: + +@example +/home/karl:.:$TEXMF//tex +@end example + +Put another way, default expansion works on ``formats'' (search +paths), and not directly on environment variables. Example, showing +the trailing @samp{:} ignored in the first case and expanded in the second: + +@example +$ env TTFONTS=/tmp: kpsewhich --expand-path '$TTFONTS' +/tmp +$ env TTFONTS=/tmp: kpsewhich --show-path=.ttf +/tmp:.:/home/olaf/texmf/fonts/truetype//:... +@end example + +Since Kpathsea looks for multiple configuration files, it would be +natural to expect that (for example) an extra colon in +@file{./texmf.cnf} would expand to the path in @file{$TEXMF/texmf.cnf}. +Or, with Dvips' configuration files, that an extra colon in +@file{config.$PRINTER} would expand to the path in @file{config.ps}. +This doesn't happen. It's not clear this would be desirable in all +cases, and trying to devise a way to specify the path to which the extra +colon should expand seemed truly baroque. +@cindex Bach, Johann Sebastian + +Technicality: Since it would be useless to insert the default value in +more than one place, Kpathsea changes only one extra @samp{:} and leaves +any others in place (they will eventually be ignored). Kpathsea checks +first for a leading @samp{:}, then a trailing @samp{:}, then a doubled +@samp{:}. + +@flindex kdefault.c +You can trace this by debugging ``paths'' (@pxref{Debugging}). +Default expansion is implemented in the source file +@file{kpathsea/kdefault.c}. + + +@node Variable expansion +@subsection Variable expansion + +@kindex $ @r{expansion} +@cindex environment variables in paths +@cindex variable expansion +@cindex expansion, variable +@flindex texmf.cnf@r{, and variable expansion} + +@samp{$foo} or @samp{$@{foo@}} in a path element is replaced by (1) the +value of an environment variable @samp{foo} (if defined); (2) the value +of @samp{foo} from @file{texmf.cnf} (if defined); (3) the empty string. + +If the character after the @samp{$} is alphanumeric or @samp{_}, the +variable name consists of all consecutive such characters. If the +character after the @samp{$} is a @samp{@{}, the variable name consists +of everything up to the next @samp{@}} (braces may not be nested around +variable names). Otherwise, Kpathsea gives a warning and ignores the +@samp{$} and its following character. + +@cindex quoting variable values +@cindex shell variables +You must quote the @t{$}'s and braces as necessary for your shell. +@emph{Shell} variable values cannot be seen by Kpathsea, i.e., ones +defined by @code{set} in C shells and without @code{export} in Bourne +shells. + +For example, given +@example +setenv tex /home/texmf +setenv TEXINPUTS .:$tex:$@{tex@}prev +@end example +@noindent the final @code{TEXINPUTS} path is the three directories: +@example +.:/home/texmf:/home/texmfprev +@end example + +The @samp{.@var{progname}} suffix on variables and +@samp{_@var{progname}} on environment variable names are not implemented +for general variable expansions. These are only recognized when search +paths are initialized (@pxref{Path sources}). + +@flindex variable.c +Variable expansion is implemented in the source file +@file{kpathsea/variable.c}. + + +@node Tilde expansion +@subsection Tilde expansion + +@kindex ~ @r{expansion} +@cindex home directories in paths +@cindex tilde expansion +@cindex expansion, tilde + +@vindex HOME@r{, as ~ expansion} +@vindex USERPROFILE@r{, as ~ expansion} +A leading @samp{~} in a path element is replaced by the value of the +environment variable @code{HOME}, or @file{.} if @code{HOME} is not +set. On Windows, the environment variable @code{USERPROFILE} is +checked instead of @code{HOME}. + +A leading @samp{~@var{user}} in a path element is replaced by +@var{user}'s home directory from the system @file{passwd} database. + +For example, +@example +setenv TEXINPUTS ~/mymacros: +@end example + +@noindent will prepend a directory @file{mymacros} in your home +directory to the default path. + +@cindex @t{root} user +@cindex trailing @samp{/} in home directory +@kindex /@r{, trailing in home directory} +As a special case, if a home directory ends in @samp{/}, the trailing +slash is dropped, to avoid inadvertently creating a @samp{//} construct +in the path. For example, if the home directory of the user @samp{root} +is @samp{/}, the path element @samp{~root/mymacros} expands to just +@samp{/mymacros}, not @samp{//mymacros}. + +@flindex tilde.c +Tilde expansion is implemented in the source file @file{kpathsea/tilde.c}. + + +@node Brace expansion +@subsection Brace expansion + +@kindex @{ @r{expansion} +@cindex brace expansion + +@samp{x@{@var{a},@var{b}@}y} expands to @samp{x@var{a}y:x@var{b}y}. +For example: + +@example +foo/@{1,2@}/baz +@end example + +@noindent expands to @samp{foo/1/baz:foo/2/baz}. @samp{:} is the path +separator on the current system; e.g., on a Windows system, it's @samp{;}. + +Braces can be nested; for example, @samp{x@{A,B@{1,2@}@}y} expands to +@samp{xAy:xB1y:xB2y}. + +Multiple non-nested braces are expanded from right to left; for example, +@samp{x@{A,B@}@{1,2@}y} expands to @samp{x@{A,B@}1y:x@{A,B@}2y}, which +expands to @samp{xA1y:xB1y:xA2y:xB2y}. + +@cindex multiple @TeX{} hierarchies +This feature can be used to implement multiple @TeX{} hierarchies, by +assigning a brace list to @code{$TEXMF}, as mentioned in +@file{texmf.in}. + +You can also use the path separator instead of the comma. The last +example could have been written @samp{x@{A:B@}@{1:2@}y} (on Unix). + + +@flindex expand.c +Brace expansion is implemented in the source file +@file{kpathsea/expand.c}. + + +@node KPSE_DOT expansion +@subsection @code{KPSE_DOT} expansion + +@kindex KPSE_DOT @r{expansion} + +When @code{KPSE_DOT} is defined in the environment, it names a directory +that should be considered the current directory for the purpose of +looking up files in the search paths. This feature is needed by the +@samp{mktex@dots{}} scripts @ref{mktex scripts}, because these +change the working directory. You should not ever define it yourself. + + +@node Subdirectory expansion +@subsection Subdirectory expansion + +@kindex // +@cindex subdirectory searching +@cindex expansion, subdirectory + +@cindex alphabetical order, not +Two or more consecutive slashes in a path element following a directory +@var{d} is replaced by all subdirectories of @var{d}: first those +subdirectories directly under @var{d}, then the subsubdirectories under +those, and so on. At each level, the order in which the directories are +searched is unspecified. (It's ``directory order'', and definitely not +alphabetical.) + +If you specify any filename components after the @samp{//}, only +subdirectories which match those components are included. For example, +@samp{/a//b} would expand into directories @file{/a/1/b}, @file{/a/2/b}, +@file{/a/1/1/b}, and so on, but not @file{/a/b/c} or @file{/a/1}. + +You can include multiple @samp{//} constructs in the path. + +@samp{//} at the beginning of a path is ignored; you didn't really want +to search every directory on the system, did you? + +@cindex trick for detecting leaf directories +@cindex leaf directory trick +@cindex Farwell, Matthew +@cindex MacKenzie, David +I should mention one related implementation trick, which I took from GNU +find. Matthew Farwell suggested it, and David MacKenzie implemented it. + +@vindex st_nlink +The trick is that in every real Unix implementation (as opposed to the +POSIX specification), a directory which contains no subdirectories will +have exactly two links (namely, one for @file{.} and one for @file{..}). +That is to say, the @code{st_nlink} field in the @samp{stat} structure +will be two. Thus, we don't have to stat everything in the bottom-level +(leaf) directories---we can just check @code{st_nlink}, notice it's two, +and do no more work. + +But if you have a directory that contains a single subdirectory and 500 +regular files, @code{st_nlink} will be 3, and Kpathsea has to stat every +one of those 501 entries. Therein lies slowness. + +@vindex ST_NLINK_TRICK +You can disable the trick by undefining @code{ST_NLINK_TRICK} in +@file{kpathsea/config.h}. (It is undefined by default except under Unix.) + +@flindex elt-dirs.c +Unfortunately, in some cases files in leaf directories are +@code{stat}'d: if the path specification is, say, +@samp{$TEXMF/fonts//pk//}, then files in a subdirectory +@samp{@dots{}/pk}, even if it is a leaf, are checked. The reason +cannot be explained without reference to the implementation, so read +@file{kpathsea/elt-dirs.c} (search for @samp{may descend}) if you are +curious. And if you find a way to solve the problem, please let me +know. + +@flindex elt-dirs.c +Subdirectory expansion is implemented in the source file +@file{kpathsea/elt-dirs.c}. + + +@node Casefolding search +@section Casefolding search + +@cindex casefolding search +@cindex search, case-insensitive + +In Kpathsea version 6.3.0 (released with @TeX{} Live 2018), a new +fallback search was implemented on Unix-like systems, including Macs: +for each path element in turn, if no match is found by the normal +search, and the path element allows for checking the filesystem, a +second check is made for a case-insensitive match. + +@vindex texmf_casefold_search +This is enabled at compile-time on Unix systems, and enabled at +runtime by setting the configuration variable +@code{texmf_casefold_search}, to a true value, e.g., @samp{1}; this is +done by default in @TeX{} Live. + +@menu +* Rationale: Casefolding rationale. +* Examples: Casefolding examples. +@end menu + +@node Casefolding rationale +@subsection Casefolding rationale + +@cindex casefolding fallback rationale +@cindex rationale for casefolding fallback +@cindex system-dependent casefolding behavior + +@cindex filesystem, case-(in)sensitive +@cindex Apple filesystem, case-insensitive +@cindex Mac filesystem, case-insensitive +The purpose of the fallback casefolding search is to ease moving +complex documents between case-insensitive (file)systems and +case-sensitive ones. In particular, Apple decided to make the default +filesystem on Macs be case-insensitive some years ago, and this has +exacerbated a problem of people creating documents that use, say, an +image under the name @file{foo.jpg}, while the actual file is named +@file{foo.JPG} or @file{Foo.jpg}. It works on the Mac but if the +document is transferred and run on a standard case-sensitive Unix +(file)system, the file can't be found, due only to differences in +case. + +This same problematic scenario has always existed on Windows, but for +whatever reason, it has become much more common since Apple also went +to a case-insensitive filesystem. Hence the relatively late change +to the Kpathsea behavior. + +@cindex Windows and casefolding +The fallback case-insensitive search is omitted at compile-time on +Windows, where (for practical purposes) all file names are +case-insensitive at the kernel level, and so the normal search will +already have definitively matched or not. Therefore, search results +in unusual cases can be different on Windows and Unix---but this has +always been true. + + +@node Casefolding examples +@subsection Casefolding examples + +@cindex casefolding examples +@cindex examples, of casefolding searches + +The casefolding implementation prefers exact matches to casefolded +matches within a given path element, so as to retain most +compatibility. Backward compatibility is not perfect, however, as a +casefolded match may be found in an earlier path element than an exact +match was previously found (see example #4 below). Still, preferring +the match in the earlier element seemed potentially less confusing +than otherwise, and is in fact consistent with past behavior on +Windows. Since case mismatches are rare to begin with, and name +collisions with respect only to case thus even more rare, the hope is +that it will not cause difficulties in practice. + +If it's desirable in a given situation to have the exact same search +behavior as previously, that can be accomplished by setting the +configuration variable @code{texmf_casefold_search} to @samp{0} +(@pxref{Path sources}). + +Some examples to illustrate the new behavior follow. + +Example #1: suppose the file @file{./foobar.tex} exists. Now, +searching for @file{./FooBar.TeX} (or any other case variation) will +succeed, returning @file{./foobar.tex}---the name as stored on disk. +In previous releases, or if @code{texmf_casefold_search} is false, the +search would fail. + +Example #2: suppose we are using a case-sensitive (file)system, and +the search path is @samp{.:/somedir}, and the files +@file{./foobar.tex} and @file{/somedir/FooBar.TeX} both exist. Both +now and previously, searching for @file{foobar.tex} returns +@file{./foobar.tex}. However, searching for @file{FooBar.TeX} now +returns @file{./foobar.tex} instead of @file{/somedir/FooBar.TeX}; +this is the incompatibility mentioned above. Also (as expected), +searching for @file{FOOBAR.TEX} (or whatever variation) will now +return @file{./foobar.tex}, whereas before it would fail. Searching +for all (@samp{kpsewhich --all}) @file{foobar.tex} will return both +matches. + +Example #3: same as example #2, but on a case-insensitive +(file)system: both now and previously, searching for @file{FooBar.TeX} +returns @file{./foobar.tex}, since the system considers that a match. +The Kpathsea casefolding never comes into play. + +Example #4: if we have (on a case-sensitive system) both +@file{./foobar.tex} and @file{./FOOBAR.TEX}, searching with the exact +case returns that exact match, now and previously. Searching for +@file{FooBar.tex} will now return one or the other (chosen +arbitrarily), rather than failing. Perhaps unexpectedly, searching +for all @file{foobar.tex} or @file{FooBar.tex} will also return only +one or the other, not both (see more below). + +Example #5: the font file @file{STIX-Regular.otf} is included in +@TeX{} Live in the system directory +@file{texmf-dist/fonts/opentype/public/stix}. Because Kpathsea never +searches the disk in the big system directory, the casefolding is not +done, and a search for @samp{stix-regular.otf} will fail (on +case-sensitive systems), as it always has. + +@kindex !! @r{and casefolding} +The caveat about not searching the disk amounts to saying that +casefolding does not happen in the trees specified with @samp{!!} +(@pxref{ls-R}), that is, where only database (@file{ls-R}) searching +is done. In @TeX{} Live, that is the @samp{texmf-local} and +@samp{texmf-dist} trees (also @code{$TEXMFSYSCONFIG} and +@code{$TEXMFSYSVAR}, but those are rarely noticed). The rationale for +this is that in practice, case mangling happens with user-created +files, not with packages distributed as part of the @TeX{} system. + +One more caveat: the purpose of @code{kpsewhich} is to exercise the +path searching in Kpathsea as it is actually done. Therefore, as +shown above, @samp{kpsewhich --all} will not return all matches +regardless of case within a given path element. If you want to find +all matches in all directories, @code{find} is the best tool, although +the setup takes a couple steps: + +@example +kpsewhich -show-path=tex >/tmp/texpath # search path specification +kpsewhich -expand-path="`cat /tmp/texpath`" >/tmp/texdirs # all dirs +tr ':' '\n' </tmp/texdirs >/tmp/texdirlist # colons to newlines +find `cat /tmp/texdirlist` -iname somefile.tex -print </tmp/texdirlist +@end example + +@cindex Findutils, GNU package +@opindex -iname@r{, find predicate} +Sorry that it's annoyingly lengthy, but implementing this inside +Kpathsea would be a lot of error-prone trouble for something that is +only useful for debugging. If your @code{find} does not support +@code{-iname}, you can get GNU Find from +@url{https://gnu.org/software/findutils}. + +The casefolding search is implemented in the source file +@file{kpathsea/pathsearch.c}. Two implementation points: + +@itemize +@findex access @r{system call} +@item +Kpathsea never tries to check if a given directory resides on a +case-insensitive filesystem, because there is no efficient and +portable way to do so. All it does is try to see if a potential file +name is a readable normal file (with, usually, the @code{access} +system call). + +@item +Kpathsea does not do any case-insensitive matching of the directories +along the path. It's not going to find @file{/Some/Random/file.tex} +when looking for @file{/some/random/file.tex}. The casefolding only +happens with the elements of the leaf directory. + +@end itemize + + +@node Filename database +@section Filename database (@code{ls-R}) + +@cindex filename database +@cindex database, for filenames +@cindex externally-built filename database + +Kpathsea goes to some lengths to minimize disk accesses for searches +(@pxref{Subdirectory expansion}). Nevertheless, in practice searching +every possible directory in typical @TeX{} installations takes an +excessively long time. + +Therefore, Kpathsea can use an externally-built @dfn{filename +database} file named @file{ls-R} that maps files to directories, thus +avoiding the need to exhaustively search the disk. + +A second database file @file{aliases} allows you to give additional +names to the files listed in @file{ls-R}. + +The @file{ls-R} and @file{aliases} features are implemented in the +source file @file{kpathsea/db.c}. + +@menu +* ls-R:: The main filename database. +* Filename aliases:: Aliases for those names. +* Database format:: Syntax details of the database file. +@end menu + + +@node ls-R +@subsection @file{ls-R} + +@flindex ls-R @r{database file} + +As mentioned above, you must name the main filename database +@file{ls-R}. You can put one at the root of each @TeX{} installation +hierarchy you wish to search (@code{$TEXMF} by default, which expands +to a braced list of several hierarchies in @TeX{} Live). + +@vindex TEXMFDBS +@kindex !! @r{in @code{TEXMFDBS}} +Kpathsea looks for @file{ls-R} files along the @code{TEXMFDBS} +path. It is best for this to contain all and only those hierarchies +from @code{$TEXMF} which are specified with @code{!!}---and also to +specify them with @code{!!} in @code{TEXMFDBS}. (See the end of this +section for more on @code{!!}.) + +The recommended way to create and maintain @samp{ls-R} is to run the +@code{mktexlsr} script, which is installed in @samp{$(bindir)} +(@file{/usr/local/bin} by default). That script goes to some trouble to +follow symbolic links as necessary, etc. It's also invoked by the +distributed @samp{mktex@dots{}} scripts. + +@flindex ls-R@r{, simplest build} +At its simplest, though, you can build @file{ls-R} with the command +@example +cd @var{/your/texmf/root} && ls -LAR ./ >ls-R +@end example + +@noindent +@opindex --color=tty +@flindex /etc/profile @r{and aliases} +presuming your @code{ls} produces the right output format (see the +section below). GNU @code{ls}, for example, outputs in this format. +Also presuming your @code{ls} hasn't been aliased in a system file +(e.g., @file{/etc/profile}) to something problematic, e.g., @samp{ls +--color=tty}. In that case, you will have to disable the alias before +generating @file{ls-R}. For the precise definition of the file format, +see @ref{Database format}. + +Regardless of whether you use the supplied script or your own, you +will almost certainly want to invoke it via @code{cron}, so when you +make changes in the installed files (say if you install a new @LaTeX{} +package), @file{ls-R} will be automatically updated. However, for +those using @TeX{} Live or system distributions, the package managers +should run @code{mktexlsr} as needed. + +@opindex -A @r{option to @code{ls}} +@cindex dot files +@flindex . @r{files} +@flindex . @r{directories, ignored} +@flindex .tex @r{file, included in @file{ls-R}} +The @samp{-A} option to @code{ls} includes files beginning with @samp{.} +(except for @file{.} and @file{..}), such as the file @file{.tex} +included with the @LaTeX{} tools package. (On the other hand, +@emph{directories} whose names begin with @samp{.} are always ignored.) + +@cindex symbolic links, and @file{ls-R} +@opindex -L @r{option to @code{ls}} +If your system does not support symbolic links, omit the @samp{-L}. + +@cindex automounter, and @file{ls-R} +@cindex NFS and @file{ls-R} +@code{ls -LAR @var{/your/texmf/root}} will also work. But using +@samp{./} avoids embedding absolute pathnames, so the hierarchy can be +easily transported. It also avoids possible trouble with automounters +or other network filesystem conventions. + +@cindex warning about unusable @file{ls-R} +@cindex unusable @file{ls-R} warning +Kpathsea warns you if it finds an @file{ls-R} file, but the file does +not contain any usable entries. The usual culprit is running plain +@samp{ls -R} instead of @samp{ls -LR ./} or @samp{ls -R +@var{/your/texmf/root}}. Another possibility is some system directory +name starting with a @samp{.} (perhaps if you are using AFS); Kpathsea +ignores everything under such directories. + +@kindex !! @r{in path specifications} +@cindex disk searching, avoiding +If a particular path element begins with @samp{!!}, @emph{only} the +database will be searched for that element, never the disk; and if the +database does not exist, nothing at all will be searched. In @TeX{} +Live, most of the trees are specified with @samp{!!}. + +For path elements that do not begin with @samp{!!}, if the database +exists, it will be used, and the disk will not be searched. However, +in this case, if the database does not exist, the disk will be +searched. In @TeX{} Live, the most notable case of this is the +@code{TEXMFHOME} tree, to allow users to add and remove files from +their own tree without having to worry about @code{ls-R}. + +(Aside: there are uncommon cases where a @samp{!!} tree will be +searched on disk even if the @code{ls-R} file exists; they are too +obscure to try to explain here. See @file{pathsearch.c} in the source +if you need to know.) + +To sum up: do not create an @code{ls-R} file unless you also take care +to keep it up to date. Otherwise newly-installed files will not be +found. + + + +@node Filename aliases +@subsection Filename aliases + +@cindex filename aliases +@cindex aliases, for filenames + +In some circumstances, you may wish to find a file under several names. +For example, suppose a @TeX{} document was created using a DOS system +and tries to read @file{longtabl.sty}. But now it's being run on a Unix +system, and the file has its original name, @file{longtable.sty}. The +file won't be found. You need to give the actual file +@file{longtable.sty} an alias @samp{longtabl.sty}. + +@c As another example, suppose you are creating a @TeX{} distribution on a +@c CD-ROM or a DOS system; then the file @file{mf.base} gets stored as +@c @file{mf.bas}. But Metafont on Unix wants to find @file{mf.base}. Here +@c you need to give the actual file @file{mf.bas} an alias @samp{mf.base}. + +You can handle this by creating a file @file{aliases} as a companion to +the @file{ls-R} for the hierarchy containing the file in question. (You +must have an @file{ls-R} for the alias feature to work.) + +The format of @file{aliases} is simple: two whitespace-separated words +per line; the first is the real name @file{longtable.sty}, and second is +the alias (@file{longtabl.sty}). These must be base filenames, with no +directory components. @file{longtable.sty} must be in the sibling +@file{ls-R}. + +Also, blank lines and lines starting with @samp{%} or @samp{#} are +ignored in @file{aliases}, to allow for comments. + +If a real file @file{longtabl.sty} exists, it is used regardless of any +aliases. + + +@node Database format +@subsection Database format + +@cindex format of external database +@cindex database, format of + +The ``database'' read by Kpathsea is a line-oriented file of plain +text. The format is that generated by GNU (and most other) @code{ls} +programs given the @samp{-R} option, as follows. + +@itemize @bullet +@item +Blank lines are ignored. + +@item +If a line begins with @samp{/} or @samp{./} or @samp{../} and ends with +a colon, it's the name of a directory. (@samp{../} lines aren't useful, +however, and should not be generated.) + +@item +All other lines define entries in the most recently seen directory. +@t{/}'s in such lines will produce possibly-strange results. + +@item +Files with no preceding directory line are ignored. +@end itemize + +For example, here's the first few lines of @file{ls-R} (which totals +about 30K bytes) on my system: + +@example +bibtex +dvips +fonts +ls-R +metafont +metapost +tex +web2c + +./bibtex: +bib +bst +doc + +./bibtex/bib: +asi.bib +btxdoc.bib +@dots{} +@end example + + +@node Invoking kpsewhich +@section @code{kpsewhich}: Standalone path searching + +@pindex kpsewhich +@cindex path searching, standalone +@cindex standalone path searching + +The Kpsewhich program exercises the path searching functionality +independent of any particular application. This can also be useful as a +sort of @code{find} program to locate files in your @TeX{} hierarchies, +perhaps in administrative scripts. It is used heavily in the +distributed @samp{mktex@dots{}} scripts. + +Synopsis: + +@example +kpsewhich @var{option}@dots{} @var{filename}@dots{} +@end example + +The options and filename(s) to look up can be intermixed. +Options can start with either @samp{-} or @samp{--}, and any unambiguous +abbreviation is accepted. + +@menu +* Path searching options:: Changing the mode, resolution, etc. +* Specially-recognized files:: Default formats for texmf.cnf, etc. +* Auxiliary tasks:: Path and variable expansion, etc. +* Standard options:: @samp{--help} and @samp{--version}. +@end menu + + +@node Path searching options +@subsection Path searching options + +@cindex path searching options + +Kpsewhich looks up each non-option argument on the command line as a +filename, and returns the first file found. + +Various options alter the path searching behavior: + +@table @samp +@item --all +@opindex --all +@cindex all matches, finding +Report all matches found, one per line. By default, if there is more +than one match, just one will be reported (chosen effectively at +random). Exception: with the glyph formats (@code{pk}, @code{gf}), +this option has no effect and only the first match is returned. + +@item --casefold-search +@itemx --no-casefold-search +@opindex --casefold-search +@opindex --no-casefold-search +Explicitly enable or disable the fallback to a case-insensitive search +on Unix platforms (@pxref{Casefolding search}); no effect on Windows. +The default is enabled, set in @code{texmf.cnf}. Disabling +(@code{--no-casefold-search}) does not mean that searches magically +become case-sensitive when the underlying (file)system is +case-insensitive, it merely means that Kpathsea does not do any +casefolding itself. + +@item --cnf-line=@var{str} +@opindex --cnf-line +Parse @var{str} as if it were a line in the @file{texmf.cnf} +configuration file (@pxref{Config files}), overriding settings in the +actual configuration files, and also in the environment (@pxref{Path +sources}). This is implemented by making any settings from @var{str} +in the environment, overwriting any value already there. Thus, an +extra colon in a @samp{--cnf-line} value will refer to the value from +a configuration file, not a user-set environment variable. + +Furthermore, any variable set from @var{str} will also be set with the +program name suffix. For example, @code{pdftex +--cnf-line=TEXINPUTS=/foo:} will set both @code{TEXINPUTS} and +@code{TEXINPUTS_pdftex} in the environment (and the value will be +@file{/foo} followed by the setting from @file{texmf.cnf}, ignoring +any user-set @code{TEXINPUTS}). + +This behavior is desirable because, in practice, many variables in the +distributed @file{texmf.cnf} are program-specific, and the intuitive +behavior is for values set on the command line with @code{--cnf-line} +to override them. + +@item --dpi=@var{num} +@opindex --dpi=@var{num} +@opindex -D @var{num} +@cindex resolution, setting +Set the resolution to @var{num}; this only affects @samp{gf} and +@samp{pk} lookups. @samp{-D} is a synonym, for compatibility with +Dvips. Default is 600. + +@item --engine=@var{name} +@opindex --engine=@var{name} +@cindex engine name +Set the engine name to @var{name}. By default it is not set. The +engine name is used in some search paths to allow files with the same +name but used by different engines to coexist. + +In particular, since the memory dump files +(@file{.fmt}/@file{.base}/@file{.mem}) are now stored in +subdirectories named for the engine (@file{tex}, @file{pdftex}, +@file{xetex}, etc.), you must specify an engine name in order to find +them. For example, @file{cont-en.fmt} typically exists for both +@file{pdftex} and @file{xetex}. With the default path settings, you +can use @samp{--engine=/} to look for any dump file, regardless of +engine; if a dump file exists for more than one engine, it's +indeterminate which one is returned. (The @samp{/} ends up specifying +a normal recursive search along the path where the dumps are stored, +namely @samp{$TEXMF/web2c@{/$engine,@}}.) + +@item --format=@var{name} +@opindex --format=@var{name} +Set the format for lookup to @var{name}. By default, the format is +guessed from the filename, with @samp{tex} being used if nothing else +fits. The recognized filename extensions (including any leading +@samp{.}) are also allowable @var{name}s. + +All formats also have a name, which is the only way to specify formats +with no associated suffix. For example, for Dvips configuration files +you can use @samp{--format="dvips config"}. (The quotes are for the +sake of the shell.) + +Here's the current list of recognized names and the associated suffixes. +@xref{Supported file formats}, for more information on each of these. + +The strings in parentheses are abbreviations recognized only by +@code{kpsewhich} (not the underlying library calls). They are +provided when it would otherwise require an argument containing a +space to specify the format, to simplify quoting of calls from shells. + +@example +gf: gf +pk: pk +bitmap font (bitmapfont): +tfm: .tfm +afm: .afm +base: .base +bib: .bib +bst: .bst +cnf: .cnf +ls-R: ls-R ls-r +fmt: .fmt +map: .map +mem: .mem +mf: .mf +mfpool: .pool +mft: .mft +mp: .mp +mppool: .pool +MetaPost support (mpsupport): +ocp: .ocp +ofm: .ofm .tfm +opl: .opl .pl +otp: .otp +ovf: .ovf .vf +ovp: .ovp .vpl +graphic/figure: .eps .epsi +tex: .tex .sty .cls .fd .aux .bbl .def .clo .ldf +TeX system documentation (doc): +texpool: .pool +TeX system sources (source): .dtx .ins +PostScript header: .pro +Troff fonts (trofffont): +type1 fonts: .pfa .pfb +vf: .vf +dvips config (dvipsconfig): +ist: .ist +truetype fonts: .ttf .ttc .TTF .TTC .dfont +type42 fonts: .t42 .T42 +web2c files (web2c): +other text files (othertext): +other binary files (otherbin): +misc fonts (miscfont): +web: .web .ch +cweb: .w .web .ch +enc files: .enc +cmap files (cmap): +subfont definition files: .sfd +opentype fonts: .otf +pdftex config (pdftexconfig): +lig files: .lig +texmfscripts: +lua: .lua .luatex .luc .luctex .texlua .texluc .tlu +font feature files: .fea +cid maps: .cid .cidmap +mlbib: .mlbib .bib +mlbst: .mlbst .bst +clua: .dll .so +ris: .ris +bltxml: .bltxml +@end example + +This option and @samp{--path} are mutually exclusive. + +@item --interactive +@opindex --interactive +@cindex interactive query +After processing the command line, read additional filenames to look up +from standard input. + +@item --mktex=@var{filetype} +@itemx --no-mktex=@var{filetype} +@opindex --mktex=@var{filetype} +@opindex --no-mktex=@var{filetype} +Turn on or off the @samp{mktex} script associated with @var{filetype}. +Usual values for @var{filetype} are @samp{pk}, @samp{mf}, @samp{tex}, +and @samp{tfm}. By default, all are off in Kpsewhich, even if they +are enabled for @TeX{}. This option implies setting +@code{--must-exist}. @xref{mktex scripts}. + +@item --mode=@var{string} +@opindex --mode=@var{string} +Set the mode name to @var{string}; this also only affects @samp{gf} and +@samp{pk} lookups. No default: any mode will be found. @xref{mktex +script arguments}. + +@item --must-exist +@opindex --must-exist +Do everything possible to find the files, notably including searching +the disk and running the @samp{mktex} scripts. By default, only the +@file{ls-R} database is checked, in the interest of efficiency. + +@item --path=@var{string} +@opindex --path=@var{string} +Search along the path @var{string} (colon-separated as usual), instead +of guessing the search path from the filename. @samp{//} and all the +usual expansions are supported (@pxref{Path expansion}). This option +and @samp{--format} are mutually exclusive. To output the complete +directory expansion of a path, instead of doing a one-shot lookup, see +@samp{--expand-path} and @samp{--show-path} in the following section. + +@item --progname=@var{name} +@opindex --progname=@var{name} +Set the program name to @var{name}; default is @samp{kpsewhich}. This +can affect the search paths via the @samp{.@var{prognam}} feature in +configuration files (@pxref{Config files}). + +@item --subdir=@var{string} +@opindex --subdir=@var{string} +Report only those matches whose directory part @emph{ends} with +@var{string} (compared literally, except case is ignored on a +case-insensitive operating system). For example, suppose there are +two matches for a given name: + +@example +kpsewhich foo.sty +@result{} /some/where/foo.sty +/another/place/foo.sty +@end example + +@noindent +Then we can narrow the result to what we are interested in with +@option{--subdir}: + +@example +kpsewhich --subdir=where foo.sty +@result{} /some/where/foo.sty + +kpsewhich --subdir=place foo.sty +@result{} /another/place/foo.sty +@end example + +@noindent +The string to match must be at the end of the directory part of the +match, and it is taken literally, with no pattern matching: + +@example +kpsewhich --subdir=another foo.sty +@result{} +@end example + +@noindent +The string to match may cross directory components: + +@example +kpsewhich --subdir=some/where foo.sty +@result{} /some/where/foo.sty +@end example + +@noindent +@option{--subdir} implies @option{--all}; if there is more than one +match, they will all be reported (in our example, both @samp{where} +and @samp{place} end in @samp{e}): + +@example +kpsewhich --subdir=e +@result{} /some/where/foo.sty +/another/place/foo.sty +@end example + +@noindent +Because of the above rules, the presence of a leading @samp{/} is +important, since it ``anchors'' the match to a full component name: + +@example +kpsewhich --subdir=/lace foo.sty +@result{} +@end example + +@noindent +However, a trailing @samp{/} is immaterial (and ignored), since the +match always takes place at the end of the directory part: + +@example +kpsewhich --subdir=lace/ foo.sty +@result{} /another/place/foo.sty +@end example + +@noindent +The purpose of these rules is to make it convenient to find results +only within a particular area of the tree. For instance, a given +script named @file{foo.lua} might exist within both +@file{texmf-dist/scripts/pkg1/} and @file{texmf-dist/scripts/pkg2/}. +By specifying, say, @samp{--subdir=/pkg1}, you can be sure of getting +the one you are interested in. + +We only match at the end because a site might happen to install @TeX{} +in @file{/some/coincidental/pkg1/path/}, and we wouldn't want to match +@file{texmf-dist/scripts/pkg2/} that when searching for @samp{/pkg1}. + +@end table + + +@node Specially-recognized files +@subsection Specially-recognized files for @command{kpsewhich} + +@command{kpsewhich} recognizes a few special filenames on the command +line and defaults to using the `known' file formats for them, merely +to save the time and trouble of specifying the format. This is only a +feature of @command{kpsewhich}; when using the Kpathsea library +itself, none of these special filenames are recognized, and it's still +up to the caller to specify the desired format. + +Here is the list of special filenames to @command{kpsewhich}, along +with their corresponding format: + +@table @file + +@flindex config.ps +@item config.ps +@code{dvips config} + +@flindex dvipdfmx.cfg +@item dvipdfmx.cfg +@samp{other text files} + +@flindex fmtutil.cnf +@item fmtutil.cnf +@samp{web2c files} + +@flindex glyphlist.txt +@item glyphlist.txt +@samp{map} + +@flindex mktex.cnf +@item mktex.cnf +@samp{web2c files} + +@flindex pdfglyphlist.txt +@item pdfglyphlist.txt +@samp{map} + +@flindex pdftex.cfg +@flindex pdftexconfig.tex +@item pdftex.cfg +@samp{pdftex config} (although @file{pdftex.cfg} is not used any more; +look for the file @file{pdftexconfig.tex} instead.) + +@flindex texmf.cnf +@item texmf.cnf +@samp{cnf} + +@flindex XDvi +@item XDvi +@samp{other text files} + +@end table + +A user-specified format will override the above defaults. + +@flindex tcfmgr.map +Another useful configuration file in this regard is @file{tcfmgr.map}, +found in @file{texmf/texconfig/tcfmgr.map}, which records various +information about the above configuration files (among others). + + +@node Auxiliary tasks +@subsection Auxiliary tasks + +@cindex auxiliary tasks + +Kpsewhich provides some features in addition to path lookup as such: + +@table @samp +@item --debug=@var{num} +@opindex --debug=@var{num} +Set debugging options to @var{num}. @xref{Debugging}. + +@item --expand-braces=@var{string} +@opindex --expand-braces=@var{string} +Output variable, tilde, and brace expansion of @var{string}, which is +assumed to be a single path element. @xref{Path expansion}. + +@item --expand-path=@var{string} +@opindex --expand-path=@var{string} +Output the complete expansion of @var{string}, with each element +separated by the usual path separator on the current system (@samp{;} +on Windows, @samp{:} otherwise). This may be useful to construct a +custom search path for a format not otherwise supported. To retrieve +the search path for a format that is already supported, see +@samp{--show-path}. + +Nonexistent directories are culled from the output: + +@example +$ kpsewhich --expand-path '/tmp' +@result{} /tmp +$ kpsewhich --expand-path '/nonesuch' +@result{} +@end example + +For one-shot uses of an arbitrary (not built in to Kpathsea) path, see +@samp{--path} (@pxref{Path searching options}). + +@item --expand-var=@var{string} +@opindex --expand-var=@var{string} +Output the variable and tilde expansion of @var{string}. For example, +with the usual @file{texmf.cnf}, @samp{kpsewhich +--expand-var='$TEXMF'} returns the @TeX{} system hierarchy root(s). +@xref{Path expansion}. The specified @var{string} can contain +anything, though, not just variable references. This calls +@code{kpse_var_expand} (@pxref{Programming with config files}). + +@item --help-formats +@opindex --help-formats +Output information about each supported format (@pxref{Supported file +formats}), including the names and abbreviations, variables +looked for, and the original path. + +@item --safe-in-name=@var{name} +@itemx --safe-out-name=@var{name} +@opindex --safe-in-name=@var{name} +@opindex --safe-out-name=@var{name} +Exit successfully if @var{name} is safe to open for reading or +writing, respectively, else unsuccessfully. No output is written. +These tests take account of the related Kpathsea configuration +settings (@pxref{Calling sequence}). + +@item --show-path=@var{name} +@opindex --show-path=@var{name} +Show the path that would be used for file lookups of file type +@var{name}. Either a filename extension (@samp{pk}, @samp{.vf}, etc.) +or an integer can be used, just as with @samp{--format}, described in +the previous section. + +@item --var-brace-value=@var{variable} +@opindex --var-brace-value=@var{variable} +Like @samp{--var-value} (next), but also expands @samp{@{...@}} +constructs. (@pxref{Brace expansion}). Thus, the value is assumed to +possibly be several path elements, and @samp{~} is expanded at the +beginning of each. The path separator is changed to that of the +current system in the expansion. + +Example: @samp{FOO='.;~' kpsewhich --var-brace-value=FOO} outputs (on +a Unix-ish system) @samp{.:/home/karl}, supposing the latter is the +current user's home directory. Note that the @samp{;} in the source +value, as commonly used in @file{texmf.cnf}, has changed to a +@samp{:}, as the normal path separator on the current system. On a +Windows-ish system, the @samp{;} would remain. + +@item --var-value=@var{variable} +@opindex --var-value=@var{variable} +Outputs the value of @var{variable} (a simple identifier like +@samp{TEXMFDIST}, with no @samp{$} or other constructs), expanding +@samp{$} (@pxref{Variable expansion}) and @samp{~} (@pxref{Tilde +expansion}) constructs in the value. @samp{~} expansion happens at the +beginning of the overall value and at the beginning of a variable +expansion, but not arbitrarily within the string. Braces are not expanded. + +Example: @samp{--var-value=texmf_casefold_search} outputs (if the +default is not changed) @samp{1}. + +Example to contrast with @samp{--var-brace-value}: @samp{FOO='.;~' +kpsewhich --var-value=FOO} outputs @samp{.;~}, i.e., the same as the +input value, on all systems. + +@end table + + +@node Standard options +@subsection Standard options + +@cindex standard options + +Kpsewhich accepts the standard GNU options: + +@itemize @bullet +@item +@opindex --help +@samp{--help} prints a help message on standard output and exits +successfully. + +@item +@opindex --version +@samp{--version} prints the Kpathsea version number and exits successfully. +@end itemize + + +@node TeX support +@chapter @TeX{} support + +@cindex @TeX{} support + +Although the basic features in Kpathsea can be used for any type of +path searching, it came about, as usual, with a specific application +in mind: I wrote Kpathsea specifically for @TeX{} system programs. I +had been struggling with the programs I was using (Dvips, Xdvi, and +@TeX{} itself) having slightly different notions of how to specify +paths; and debugging was painful, since no code was shared. + +Therefore, Kpathsea provides some @TeX{}-specific formats and +features. Indeed, many of the purportedly generic path searching +features were provided because they seemed useful in that con@TeX{}t +(font lookup, particularly). + +Kpathsea provides a standard way to search for files of any of the +supported file types; glyph fonts are a bit different than all the +rest. Searches are based solely on names of files, not their +contents---if a GF file is (mis)named @file{cmr10.600pk}, it will be +found as a PK file. + +@menu +* Supported file formats:: File types Kpathsea knows about. +* File lookup:: Searching for most kinds of files. +* Glyph lookup:: Searching for bitmap fonts. +* Suppressing warnings:: Avoiding warnings via TEX_HUSH. +* mktex scripts:: Generating files at runtime. +@end menu + + +@node Supported file formats +@section Supported file formats + +@cindex supported file formats +@cindex file formats, supported + +@cindex environment variables for @TeX{} +@cindex @TeX{} environment variables + +Kpathsea has support for a number of file types. Each file type has a +list of environment and config file variables that are checked to define +the search path, and most have a default suffix that plays a role in +finding files (see the next section). Some also define additional +suffixes, and/or a program to be run to create missing files on the fly. + +@cindex program-varying paths +Since environment variables containing periods, such as +@samp{TEXINPUTS.latex}, are not allowed on some systems, Kpathsea looks +for environment variables with an underscore, e.g., +@samp{TEXINPUTS_latex} (@pxref{Config files}). + +The following table lists the above information. You can also get the +list by giving the @samp{--help-formats} option to @code{kpsewhich} +(@pxref{Auxiliary tasks}). + +@table @samp +@item afm +@flindex .afm +@vindex AFMFONTS +(Adobe font metrics, @pxref{Metric files,,, dvips, Dvips}) +@code{AFMFONTS}; +suffix @samp{.afm}. + +@item base +@flindex .base +@vindex MFBASES +@vindex TEXMFINI +(Metafont memory dump, @pxref{Memory dumps,,, web2c, Web2c}) +@code{MFBASES}, @code{TEXMFINI}; +suffix @samp{.base}. + +@item bib +@flindex .bib +@vindex BIBINPUTS +@vindex TEXBIB +(Bib@TeX{} bibliography source, @pxref{bibtex invocation,,, web2c, Web2c}) +@code{BIBINPUTS}, @code{TEXBIB}; +suffix @samp{.bib}. + +@item bltxml +@flindex .bltxml +@vindex BLTXMLINPUTS +(Bib@LaTeX{}ML bibliography files for Biber, @url{https://ctan.org/pkg/biber}) +@code{BLTXMLINPUTS} +suffix @samp{.bltxml}. + +@item bst +@flindex .bst +@vindex BSTINPUTS +(Bib@TeX{} style, @pxref{Basic BibTeX style files,, Basic Bib@TeX{} +style files, web2c, Web2c}) +@code{BSTINPUTS}; +suffix @samp{.bst}. + +@item clua +@flindex .dll +@flindex .so +@vindex CLUAINPUTS +(dynamic libraries for Lua, @url{https://ctan.org/pkg/luatex}) +@code{CLUAINPUTS} +suffixes @samp{.dll} and @samp{.so}. + +@item cmap +@flindex .cmap +@vindex CMAPFONTS +(character map files) +@code{CMAPFONTS}; +suffix @samp{.cmap}. + +@item cnf +@flindex .cnf +@vindex TEXMFCNF +(Runtime configuration files, @pxref{Config files}) +@code{TEXMFCNF}; +suffix @samp{.cnf}. + +@item cweb +@flindex .w +@flindex .web +@vindex CWEBINPUTS +(CWEB input files) +@code{CWEBINPUTS}; +suffixes @samp{.w}, @samp{.web}; +additional suffix @samp{.ch}. + +@item dvips config +@vindex TEXCONFIG +@flindex config.ps@r{, search path for} +(Dvips @samp{config.*} files, such as @file{config.ps}, @pxref{Config +files,,, dvips, Dvips}) +@code{TEXCONFIG}. + +@item enc files +@flindex .enc +@vindex ENCFONTS +(encoding vectors) +@code{ENCFONTS}; +suffix @samp{.enc}. + +@item fmt +@flindex .fmt +@vindex TEXFORMATS +@vindex TEXMFINI +(@TeX{} memory dump, @pxref{Memory dumps,,, web2c, Web2c}) +@code{TEXFORMATS}, @code{TEXMFINI}; +suffix @samp{.fmt}. + +@item font cid map +@flindex .cid +@vindex FONTCIDMAPS +(CJK mapping) +@code{FONTCIDMAPS} +suffix @samp{.cid}. + +@item font feature files +@flindex .fea +@vindex FONTFEATURES +(primarily for OpenType font features) +@code{FONTFEATURES} +suffix @samp{.fea}. + +@item gf +@flindex gf +@vindex GFFONTS +@vindex GLYPHFONTS +@vindex TEXFONTS +(generic font bitmap, @pxref{Glyph files,,, dvips, Dvips}) +@code{@var{program}FONTS}, @code{GFFONTS}, @code{GLYPHFONTS}, @code{TEXFONTS}; +suffix @samp{gf}. + +@item graphic/figure +@flindex .eps +@flindex .epsi +@vindex TEXPICTS +@vindex TEXINPUTS +(Encapsulated PostScript figures, @pxref{PostScript figures,,, dvips, Dvips}) +@code{TEXPICTS}, @code{TEXINPUTS}; +additional suffixes: @samp{.eps}, @samp{.epsi}. + +@item ist +@flindex .ist +@vindex TEXINDEXSTYLE +@vindex INDEXSTYLE +(makeindex style files) +@code{TEXINDEXSTYLE}, @code{INDEXSTYLE}; +suffix @samp{.ist}. + +@item lig files +@flindex .lig +@vindex LIGFONTS +(ligature definition files) +@code{LIGFONTS}; +suffix @samp{.lig}. + +@item ls-R +@flindex ls-R +@vindex TEXMFDBS +(Filename databases, @pxref{Filename database}) +@code{TEXMFDBS}. + +@item map +@flindex .map +@vindex TEXFONTMAPS +(Fontmaps, @pxref{Fontmap}) +@code{TEXFONTMAPS}; +suffix @samp{.map}. + +@item mem +@flindex .mem +@vindex MPMEMS +@vindex TEXMFINI +(MetaPost memory dump, @pxref{Memory dumps,,, web2c, Web2c}) +@code{MPMEMS}, @code{TEXMFINI}; +suffix @samp{.mem}. + +@item @r{MetaPost support} +@vindex MPSUPPORT +(MetaPost support files, used by DMP; @pxref{dmp invocation,,, web2c, Web2c}) +@code{MPSUPPORT}. + +@item mf +@flindex .mf +@vindex MFINPUTS +(Metafont source, @pxref{mf invocation,,, web2c, Web2c}) +@code{MFINPUTS}; +suffix @samp{.mf}; +dynamic creation program: @code{mktexmf}. + +@item mfpool +@flindex .pool +@vindex MFPOOL +(Metafont program strings, @pxref{pooltype invocation,,, web2c, Web2c}) +@code{MFPOOL}, @code{TEXMFINI}; +suffix @samp{.pool}. + +@item mft +@flindex .mft +@vindex MFTINPUTS +(@code{MFT} style file, @pxref{mft invocation,,, web2c, Web2c}) +@code{MFTINPUTS}; +suffix @samp{.mft}. + +@item misc fonts +@vindex MISCFONTS +(font-related files that don't fit the other categories) +@code{MISCFONTS} + +@item mlbib +@flindex .mlbib +@vindex MLBIBINPUTS +@vindex BIBINPUTS +@vindex TEXBIB +(MlBib@TeX{} bibliography source) +@code{MLBIBINPUTS}, @code{BIBINPUTS}, @code{TEXBIB}; +suffixes @samp{.mlbib}, @samp{.mlbib}. + +@item mlbst +@flindex .mlbst +@vindex MLBSTINPUTS +@vindex BSTINPUTS +(MlBib@TeX{} style) +@code{MLBSTINPUTS}, @code{BSTINPUTS}; +suffixes @samp{.mlbst}, @samp{.bst}. + +@item mp +@flindex .mp +@vindex MPINPUTS +(MetaPost source, @pxref{mpost invocation,,, web2c, Web2c}) +@code{MPINPUTS}; +suffix @samp{.mp}. + +@item mppool +@flindex .pool +@vindex MPPOOL +(MetaPost program strings, @pxref{pooltype invocation,,, web2c, Web2c}) +@code{MPPOOL}, @code{TEXMFINI}; +suffix @samp{.pool}. + +@item ocp +@flindex .ocp +@vindex OCPINPUTS +(Omega compiled process files) +@code{OCPINPUTS}; @* +suffix @samp{.ocp}; +dynamic creation program: @code{MakeOmegaOCP}. + +@item ofm +@flindex .ofm +@vindex OFMFONTS +(Omega font metrics) +@code{OFMFONTS}, @code{TEXFONTS}; @* +suffixes @samp{.ofm}, @samp{.tfm}; +dynamic creation program: @code{MakeOmegaOFM}. + +@item opentype fonts +@vindex OPENTYPEFONTS +(OpenType fonts) +@code{OPENTYPEFONTS}. + +@item opl +@flindex .opl +(Omega property lists) +@code{OPLFONTS}, @code{TEXFONTS}; +suffix @samp{.opl}. + +@item otp +@flindex .otp +@vindex OTPINPUTS +(Omega translation process files) +@code{OTPINPUTS}; +suffix @samp{.otp}. + +@item ovf +@flindex .ovf +@vindex OVFFONTS +(Omega virtual fonts) +@code{OVFFONTS}, @code{TEXFONTS}; +suffix @samp{.ovf}. + +@item ovp +@flindex .ovp +@vindex OVPFONTS +(Omega virtual property lists) +@code{OVPFONTS}, @code{TEXFONTS}; +suffix @samp{.ovp}. + +@item pdftex config +@vindex PDFTEXCONFIG +(PDF@TeX{}-specific configuration files) +@code{PDFTEXCONFIG}. + +@item pk +@flindex .pk +@vindex PKFONTS +@vindex TEXPKS +@vindex GLYPHFONTS +@vindex TEXFONTS +(packed bitmap fonts, @pxref{Glyph files,,, dvips, Dvips}) +@code{@var{PROGRAM}FONTS} (@var{program} being @samp{XDVI}, etc.), +@code{PKFONTS}, @code{TEXPKS}, @code{GLYPHFONTS}, @code{TEXFONTS}; +suffix @samp{pk}; +dynamic creation program: @code{mktexpk}. + +@item PostScript header +@flindex .pro +@vindex TEXPSHEADERS +@vindex PSHEADERS +(downloadable PostScript, @pxref{Header files,,, dvips, Dvips}) +@code{TEXPSHEADERS}, @code{PSHEADERS}; +additional suffix @samp{.pro}. + +@item ris +@flindex .ris +@vindex RISINPUTS +(RIS bibliography files, primarily for Biber, @url{https://ctan.org/pkg/biber}) +@code{RISINPUTS} +suffix @samp{.ris}. + +@item subfont definition files +@flindex .sfd +@vindex SFDFONTS +(subfont definition files) +@code{SFDFONTS} +suffix @samp{.sfd}. + +@item tex +@flindex .tex +@vindex TEXINPUTS +(@TeX{} source, @pxref{tex invocation,,, web2c, Web2c}) +@code{TEXINPUTS}; +suffix @samp{.tex}; +additional suffixes: none, because such a list cannot be complete; +dynamic creation program: @code{mktextex}. + +@item TeX system documentation +@flindex doc files +@vindex TEXDOCS +(Documentation files for the @TeX{} system) +@code{TEXDOCS}. + +@item TeX system sources +@flindex source files +@vindex TEXSOURCES +(Source files for the @TeX{} system) +@code{TEXSOURCES}. + +@item texmfscripts +@vindex TEXMFSCRIPTS +(Architecture-independent executables distributed in the texmf trees) +@code{TEXMFSCRIPTS}. + +@item texpool +@flindex .pool +@vindex TEXPOOL +(@TeX{} program strings, @pxref{pooltype invocation,,, web2c, Web2c}) +@code{TEXPOOL}, @code{TEXMFINI}; +suffix @samp{.pool}. + +@item tfm +@flindex .tfm +@vindex TFMFONTS +@vindex TEXFONTS +(@TeX{} font metrics, @pxref{Metric files,,, dvips, Dvips}) +@code{TFMFONTS}, @code{TEXFONTS}; +suffix @samp{.tfm}; +dynamic creation program: @code{mktextfm}. + +@item Troff fonts +@vindex TRFONTS +(Troff fonts, used by DMP; @pxref{DMP invocation,,, web2c, Web2c}) +@code{TRFONTS}. + +@item truetype fonts +@flindex .ttf +@flindex .ttc +@vindex TTFONTS +(TrueType outline fonts) @code{TTFONTS}; suffixes @samp{.ttf} and +@samp{.TTF}, @samp{.ttc} and @samp{.TTC}, @samp{.dfont}. + +@item type1 fonts +@flindex .pfa +@flindex .pfb +@vindex T1FONTS +@vindex T1INPUTS +@vindex TEXPSHEADERS +@vindex DVIPSHEADERS +(Type 1 PostScript outline fonts, @pxref{Glyph files,,, dvips, Dvips}) +@code{T1FONTS}, @code{T1INPUTS}, @code{TEXPSHEADERS}, @code{DVIPSHEADERS}; +suffixes @samp{.pfa}, @samp{.pfb}. + +@item type42 fonts +@vindex T42FONTS +(Type 42 PostScript outline fonts) @code{T42FONTS}. + +@item vf +@flindex .vf +@vindex VFFONTS +@vindex TEXFONTS +(virtual fonts, @pxref{Virtual fonts,,, dvips, Dvips}) +@code{VFFONTS}, @code{TEXFONTS}; +suffix @samp{.vf}. + +@item web +@flindex .web +@vindex WEBINPUTS +(WEB input files) +@code{WEBINPUTS}; +suffix @samp{.web}; +additional suffix @samp{.ch}. + +@item web2c files +@vindex WEB2C +(files specific to the web2c implementation) +@code{WEB2C}. +@end table + +There are two special cases, because the paths and environment variables +always depend on the name of the program: the variable name is +constructed by converting the program name to upper case, and then +appending @samp{INPUTS}. Assuming the program is called @samp{foo}, +this gives us the following table. + +@table @samp +@item other text files +@vindex FOOINPUTS +(text files used by @samp{foo}) +@code{FOOINPUTS}. + +@item other binary files +@vindex FOOINPUTS +(binary files used by @samp{foo}) +@code{FOOINPUTS}. +@end table + +If an environment variable by these names are set, the corresponding +@file{texmf.cnf} definition won't be looked at (unless, as usual, the +environment variable value has an extra @samp{:}). @xref{Default +expansion}. + +For the font variables, the intent is that: +@itemize @bullet +@item +@code{TEXFONTS} is the default for everything. + +@item +@code{GLYPHFONTS} is the default for bitmap (or, more precisely, +non-metric) files. + +@item +Each font format has a variable of its own. + +@item +@vindex XDVIFONTS +@vindex DVIPSFONTS +Each program has its own font override path as well; e.g., +@code{DVIPSFONTS} for Dvipsk. Again, this is for bitmaps, not metrics. + +@end itemize + + +@node File lookup +@section File lookup + +@cindex file lookup +@cindex searching for files +@cindex @TeX{} file lookup + +This section describes how Kpathsea searches for most files (bitmap font +searches are the exception, as described in the next section). + +Here is the search strategy for a file @var{name}: + +@enumerate +@item +If the file format defines default suffixes, and the suffix of +@var{name} name is not already a known suffix for that format, try the +name with each default appended, and use alternative names found in +the fontmaps if necessary. Example: given @samp{foo.bar}, look for +@samp{foo.bar.tex}. + +@item +Search for @var{name}, and if necessary for alternative names found in +the fontmaps. Example: given @samp{foo.bar}, we also look for +@samp{foo.bar}. + +@item +If the file format defines a program to invoke to create missing files, +run it (@pxref{mktex scripts}). +@end enumerate + +@cindex extensions, filename +@cindex suffixes, filename +@vindex try_std_extension_first +The order in which we search for ``suffixed'' name (item@tie{}1) or +the ``as-is'' name (item@tie{}2) is controlled by the +@file{try_std_extension_first} configuration value. The default set +in @file{texmf.cnf} is true, since common suffixes are already +recognized: @samp{babel.sty} will only look for @samp{babel.sty}, not +@samp{babel.sty.tex}, regardless of this setting. + +When the suffix is unknown (e.g., @samp{foo.bar}), both names are +always tried; the difference is the order in which they are tried. + +@file{try_std_extension_first} only affects names being looked up +which *already* have an extension. A name without an extension (e.g., +@samp{tex story}) will always have an extension added first. + +@flindex tex-file.c +@findex kpathsea_find_file +This algorithm is implemented in the function +@code{kpathsea_find_file} in the source file +@file{kpathsea/tex-file.c}. You can watch it in action with the +debugging options (@pxref{Debugging}). + + +@node Glyph lookup +@section Glyph lookup + +@cindex glyph lookup +@cindex searching for glyphs +@cindex @TeX{} glyph lookup + +This section describes how Kpathsea searches for a bitmap font in GF or +PK format (or either) given a font name (e.g., @samp{cmr10}) and a +resolution (e.g., 600). + +Here is an outline of the search strategy (details in the sections +below) for a file @var{name} at resolution @var{dpi}. The search stops +at the first successful lookup. + +@enumerate +@item +Look for an existing file @var{name}.@var{dpi}@var{format} in the +specified format(s). + +@item If @var{name} is an alias for a file @var{f} in the fontmap +file @file{texfonts.map}, look for @var{f}.@var{dpi}. + +@item Run an external program (typically named @samp{mktexpk}) to +generate the font (@pxref{mktex scripts}) + +@item Look for @var{fallback}.@var{dpi}, where @var{fallback} is some +last-resort font (typically @samp{cmr10}). +@end enumerate + +@flindex tex-glyph.c +@findex kpathsea_find_glyph +This is implemented in @code{kpathsea_find_glyph} in +@file{kpathsea/tex-glyph.c}. + +@menu +* Basic glyph lookup:: Features common to all glyph lookups. +* Fontmap:: Aliases for fonts. +* Fallback font:: Resolutions and fonts of last resort. +@end menu + + +@node Basic glyph lookup +@subsection Basic glyph lookup + +@cindex basic glyph lookup +@cindex common features in glyph lookup + +When Kpathsea looks for a bitmap font @var{name} at resolution @var{dpi} +in a format @var{format}, it first checks each directory in the search +path for a file @samp{@var{name}.@var{dpi}@var{format}}; for example, +@samp{cmr10.600pk}. Kpathsea looks for a PK file first, then a GF file. + +If that fails, Kpathsea looks for +@samp{dpi@var{dpi}/@var{name}.@var{format}}; for example, +@samp{dpi600/cmr10.pk}. This is how fonts are typically stored on +filesystems (such as DOS) that permit only three-character extensions. + +@cindex tolerance for glyph lookup +@cindex glyph lookup bitmap tolerance +@findex KPSE_BITMAP_TOLERANCE +If that fails, Kpathsea looks for a font with a close-enough @var{dpi}. +``Close enough'' is defined by the macro @code{KPSE_BITMAP_TOLERANCE} in +@file{kpathsea/tex-glyph.h} to be @code{@var{dpi} / 500 + 1}. This is +slightly more than the 0.2% minimum allowed by the DVI standard +(@url{@var{CTAN:}/dviware/driv-standard/level-0}). + + +@node Fontmap +@subsection Fontmap + +@cindex fontmap files +@cindex font alias files +@cindex aliases for fonts + +@flindex texfonts.map +If a bitmap font or metric file is not found with the original name (see +the previous section), Kpathsea looks through any @dfn{fontmap} files +for an @dfn{alias} for the original font name. These files are named +@file{texfonts.map} and searched for along the @code{TEXFONTMAPS} +environment/config file variable. All @file{texfonts.map} files that +are found are read; earlier definitions override later ones. + +This feature is intended to help in two respects: + +@enumerate + +@item +@cindex fontnames, arbitrary length +An alias name is limited in length only by available memory, not by your +filesystem. Therefore, if you want to ask for @samp{Times-Roman} +instead of @file{ptmr}, you can (you get @samp{ptmr8r}). + +@item +@cindex circle fonts +@flindex lcircle10 +A few fonts have historically had multiple names: specifically, +La@TeX{}'s ``circle font'' has variously been known as @file{circle10}, +@file{lcircle10}, and @file{lcirc10}. Aliases can make all the names +equivalent, so that it no longer matters what the name of the installed +file is; @TeX{} documents will find their favorite name. + +@end enumerate + +The format of fontmap files is straightforward: + +@itemize @bullet +@cindex comments, in fontmap files +@item Comments start with the last @samp{%} on a line and continue to +the end of the line. (This provides for names that include a %, +ill-advised as that may be.) + +@cindex whitespace, in fontmap files +@item Blank lines are ignored. + +@item Each nonblank line is broken up into a series of @dfn{words}: + a sequence of non-whitespace characters. + +@findex include @r{fontmap directive} +@item If the first word is @samp{include}, the second word is used as + a filename, and it is searched for and read. + +@item Otherwise, the first word on each line is the true filename; + +@item the second word is the alias; + +@item subsequent words are ignored. +@end itemize + +If an alias has an extension, it matches only those files with that +extension; otherwise, it matches anything with the same root, regardless +of extension. For example, an alias @samp{foo.tfm} matches only when +@file{foo.tfm} is being searched for; but an alias @samp{foo} matches +@file{foo.vf}, @file{foo.600pk}, etc. + +As an example, here is an excerpt from the @file{texfonts.map} in the +Web2c distribution. It makes the old and new names of the @LaTeX{} +circle fonts equivalent. + +@example +circle10 lcircle10 +circle10 lcirc10 +lcircle10 circle10 +lcircle10 lcirc10 +lcirc10 circle10 +lcirc10 lcircle10 +@dots{} +@end example + +Fontmaps are implemented in the file @file{kpathsea/fontmap.c}. +The Fontname distribution has much more information on font naming +(@pxref{,,,fontname, Filenames for @TeX{} fonts}). + + +@node Fallback font +@subsection Fallback font + +@cindex fallback font +@cindex fallback resolutions +@cindex font of last resort +@cindex resolutions, last-resort +@cindex last-resort font + +@vindex DVIPSSIZES +@vindex XDVISIZES +@vindex DVILJSIZES +@vindex TEXSIZES +@vindex default_texsizes +If a bitmap font cannot be found or created at the requested size, +Kpathsea looks for the font at a set of @dfn{fallback resolutions}. You +specify these resolutions as a colon-separated list (like search paths). +Kpathsea looks first for a program-specific environment variable (e.g., +@code{DVIPSSIZES} for Dvipsk), then the environment variable +@code{TEXSIZES}, then a default specified at compilation time (the Make +variable @code{default_texsizes}). You can set this list to be empty if +you prefer to find fonts at their stated size or not at all. + +@flindex cmr10@r{, as fallback font} +@findex kpathsea_init_prog +Finally, if the font cannot be found even at the fallback resolutions, +Kpathsea looks for a fallback font, typically @file{cmr10}. Programs +must enable this feature by calling @code{kpathsea_init_prog} +(@pxref{Calling sequence}); the default is no fallback font. + + +@node Suppressing warnings +@section Suppressing warnings + +@cindex warnings, suppressing +@cindex suppressing warnings + +@vindex TEX_HUSH +Kpathsea provides a way to suppress selected usually-harmless warnings; +this is useful at large sites where most users are not administrators, +and thus the warnings are merely a source of confusion, not a help. To +do this, you set the environment variable or configuration file value +@code{TEX_HUSH} to a colon-separated list of values. Here are the +possibilities: + +@vtable @samp +@item all +Suppress everything possible. + +@item checksum +@cindex mismatched checksum warnings +Suppress mismatched font checksum warnings. + +@item lostchar +@cindex missing character warnings +Suppress warnings when a character is missing from a font that a DVI or +VF file tries to typeset. + +@item none +Don't suppress any warnings. + +@item readable +@cindex unreadable file warnings +Suppress warnings about attempts to access a file whose permissions +render it unreadable. + +@item special +@cindex unknown special warnings +@findex \special@r{, suppressing warnings about} +Suppresses warnings about an unimplemented or unparsable +@samp{\special} command. +@end vtable + +@noindent @file{tex-hush.c} defines the function that checks the +variable value. Each driver implements its own checks where +appropriate. + + +@node mktex scripts +@section @file{mktex} scripts + +@cindex @file{mktex} scripts +@cindex scripts for file creation + +@cindex font set, infinite +@cindex dynamic creation of files +@cindex Sauter fonts, and dynamic source creation +@cindex EC fonts, and dynamic source creation +If Kpathsea cannot otherwise find a file, for some file types it is +configured by default to invoke an external program to create it +dynamically (@pxref{mktex configuration}). These are collectively +known as @dfn{@code{mktex} scripts}, since most of them are named +@code{mktex...}. + +For example, this is useful for fonts (bitmaps, TFM's, and +arbitrarily-sizable Metafont sources such as the Sauter and EC fonts), +since any given document can use fonts never before referenced. +Building all fonts in advance is therefore impractical, if not +impossible. + +It is also useful for the @TeX{} @samp{.fmt} (and Metafont +@samp{.base} and Metapost @samp{.mem} files, @pxref{Memory +dumps,,,Web2c,web2c}), where pre-generating every format consumes a +lot of both time and space. + +The script is passed the name of the file to create and possibly other +arguments, as explained below. It must echo the full pathname of the +file it created (and nothing else) to standard output; it can write +diagnostics to standard error. + +@menu +* config: mktex configuration. +* names: mktex script names. +* args: mktex script arguments. +@end menu + + +@node mktex configuration +@subsection @file{mktex} configuration + +@cindex @file{mktex} script configuration +@cindex configuration of @file{mktex} scripts +@cindex enabling @file{mktex} scripts +@cindex disabling @file{mktex} scripts + +The list of file types and program names that can run an external +program to create missing files is listed in the next section. In the +absence of @code{configure} options specifying otherwise, everything +but @file{mktextex} will be enabled by default. The @code{configure} +options to change the defaults are: + +@cindex @code{configure} options for @file{mktex} scripts +@opindex --without-mktexfmt-default +@opindex --without-mktexmf-default +@opindex --without-mktexocp-default +@opindex --without-mktexofm-default +@opindex --without-mktexpk-default +@opindex --without-mktextfm-default +@opindex --with-mktextex-default +@example +--without-mktexfmt-default +--without-mktexmf-default +--without-mktexocp-default +--without-mktexofm-default +--without-mktexpk-default +--without-mktextfm-default +--with-mktextex-default +@end example + +The @code{configure} setting is overridden if the environment variable +or configuration file value named for the script is set; e.g., +@file{MKTEXPK} (@pxref{mktex script arguments}). + +@flindex fmtutils.cnf +@code{mktexfmt} reads a file @file{fmtutil.cnf}, typically located in +@file{texmf/web2c/} to glean its configuration information. The rest +of the files and features in this section are primarily intended for +the font generation scripts. + +@flindex mktex.cnf +@flindex mktex.opt +@cindex site overrides for @code{mktex@dots{}} +As distributed, all the scripts source a file +@file{texmf/web2c/mktex.cnf} if it exists, so you can override various +defaults. +See @file{mktex.opt}, for instance, which defines the default mode, +resolution, some special directory names, etc. If you prefer not to +change the distributed scripts, you can simply create @file{mktex.cnf} +with the appropriate definitions (you do not need to create it if you +have nothing to put in it). @file{mktex.cnf} has no special syntax; +it's an arbitrary Bourne shell script. The distribution contains a +sample @file{mktex.cnf} for you to copy and modify as you please (it +is not installed anywhere). + +@flindex mktex.opt +@vindex MT_FEATURES +In addition, you can configure a number of features with the +@code{MT_FEATURES} variable, which you can define: + +@itemize @bullet +@item +in @file{mktex.opt}, as just mentioned; + +@item +by editing the file @file{mktex.opt}, either before @samp{make +install} (in the source hierarchy) or after (in the installed +hierarchy); + +@item +or in the environment. +@end itemize + +If none of the options below are enabled, @code{mktexpk}, +@code{mktextfm}, and @code{mktexmf} follow the following procedure to +decide where fonts should be installed. Find the tree where the font's +sources are, and test the permissions of the @samp{fonts} directory of +that tree to determine whether it is writable. If it is, put the files +in the tree in appropriate locations. If it isn't writable, see whether +the tree is a system tree (named in @code{SYSTEXMF}). If so, the +@code{VARTEXFONTS} tree is used. In all other cases the working +directory is used. + +The @samp{appendonlydir} option is enabled by default. + +@vtable @samp +@item appendonlydir +@cindex directories, making append-only +@flindex mktexdir +Tell @code{mktexdir} to create directories append-only, i.e., set +their sticky bit (@pxref{Mode Structure,,, coreutils, GNU Core +Utilities}). This feature is silently ignored on non-Unix platforms +(e.g. Windows/NT and MS-DOS) which don't support similar functionality. +This feature is enabled by default. + +@item dosnames +@cindex 8.3 filenames, using +@cindex DOS compatible names +@flindex dpi@var{nnn} directories +Use 8.3 names; e.g., @file{dpi600/cmr10.pk} instead of +@file{cmr10.600pk}. Note that this feature only affects filenames that +would otherwise clash with other TeX-related filenames; @file{mktex} +scripts do nothing about filenames which exceed the 8+3 MS-DOS limits +but remain unique when truncated (by the OS) to these limits, and nether +do the scripts care about possible clashes with files which aren't +related with TeX. For example, @file{cmr10.600pk} would clash with +@file{cmr10.600gf} and is therefore changed when @samp{dosnames} is in +effect, but @file{mf.pool} and @file{mp.base} don't clash with any +TeX-related files and are therefore unchanged. + +This feature is turned on by default on MS-DOS. If you do not wish +@samp{dosnames} to be set on an MS-DOS platform, you need to set the +@code{MT_FEATURES} environment variable to a value that doesn't include +@samp{dosnames}. You can also change the default setting by editing +@file{mktex.opt}, but only if you use the @file{mktex} shell scripts; +the emulation programs don't consult @file{mktex.opt}. + +@item fontmaps +@cindex fontmaps +@cindex fontname +Instead of deriving the location of a font in the destination tree from +the location of the sources, the aliases and directory names from the +Fontname distribution are used. (@pxref{Top,, Introduction, fontname, +Fontname}). + +@item nomfdrivers +@cindex metafont driver files +Let mktexpk and mktextfm create metafont driver files in a temporary +directory. These will be used for just one metafont run and not +installed permanently. + +@item nomode +@cindex mode directory, omitting +Omit the directory level for the mode name; this is fine as long as +you generate fonts for only one mode. + +@item stripsupplier +@cindex supplier directory, omitting +Omit the font supplier name directory level. + +@item striptypeface +@cindex typeface directory, omitting +Omit the font typeface name directory level. + +@item strip +@cindex supplier directory, omitting +@cindex typeface directory, omitting +Omit the font supplier and typeface name directory levels. This feature +is deprecated in favour of @samp{stripsupplier} and @samp{striptypeface}. + +@item varfonts +@flindex /var/tmp/texfonts +@vindex VARTEXFONTS +@cindex Linux File System Standard +When this option is enabled, fonts that would otherwise be written in +system texmf tree go to the @code{VARTEXFONTS} tree instead. The +default value in @file{kpathsea/Makefile.in} is +@file{/var/tmp/texfonts}. The @cite{Linux File System Standard} +recommends @file{/var/tex/fonts}. + +@vindex USE_VARTEXFONTS +The @samp{varfonts} setting in @code{MT_FEATURES} is overridden by the +@code{USE_VARTEXFONTS} environment variable: if set to @samp{1}, the +feature is enabled, and if set to @samp{0}, the feature is disabled. + +@item texmfvar +@vindex TEXMFVAR +Force generated files that would go into a system tree (as defined by +@code{SYSTEXMF}) into @code{TEXMFVAR}. Starting with te@TeX{}-3.0, the +variable @code{TEXMFVAR} is always set. The @samp{varfonts} feature takes +precedence if also set. + +@vindex USE_TEXMFVAR +The @samp{texmfvar} setting in @code{MT_FEATURES} is overridden by the +@code{USE_TEXMFVAR} environment variable: if set to @samp{1}, the +feature is enabled, and if set to @samp{0}, the feature is disabled. +@end vtable + + +@node mktex script names +@subsection @file{mktex} script names + +@cindex @file{mktex} script names +@cindex names for @file{mktex} scripts + +The following table shows the default name of the script for each +of the file types which support runtime generation. + +@table @file +@item mktexfmt +@pindex mktexfmt +@pindex fmtutil +(@samp{.fmt}, @samp{.base}, @samp{.mem}) @TeX{}/Metafont/MetaPost +formats. This script is also named @command{fmtutil}, and reads +@file{fmtutil.cnf} for configuration information. + +@item mktexmf +@pindex mktexmf +(@samp{.mf}) Metafont input files. + +@item mkocp +@pindex mkocp +(@samp{.ocp}) Omega compiled process files. + +@item mkofm +@pindex mkofm +(@samp{.ofm}) Omega font metric files. + +@item mktexpk +@pindex mktexpk +(@samp{pk}) Glyph fonts. + +@item mktextex +@pindex mktextex +(@samp{.tex}) @TeX{} input files (disabled by default). + +@item mktextfm +@pindex mktextfm +(@samp{.tfm}) TFM files. +@end table + +@vindex DVIPSMAKEPK +@vindex XDVIMAKEPK +@vindex DVILJMAKEPK +@noindent These names can be overridden by an environment variable specific +to the program---for example, @code{DVIPSMAKEPK} for Dvipsk. + +@comment next two paragraphs are repeated in dvips.texi +@flindex missfont.log +@cindex failed @code{mktex@dots{}} script invocation +If a @code{mktex@dots{}} script fails, the invocation is appended to a +file @file{missfont.log} (by default) in the current directory. You can +then execute the log file to create the missing files after fixing the +problem. + +@vindex TEXMFOUTPUT +@vindex MISSFONT_LOG +If the current directory is not writable and the environment variable or +configuration file value @code{TEXMFOUTPUT} is set, its value is +used. Otherwise, nothing is written. The name @samp{missfont.log} is +overridden by the @code{MISSFONT_LOG} environment variable or +configuration file value. + + +@node mktex script arguments +@subsection @file{mktex} script arguments + +@cindex arguments to @file{mktex} + +The first argument to a @file{mktex} script is always the name +of the file to be created. + +In the default @file{mktexpk} implementation, additional arguments may +also be passed: + +@table @samp +@item --dpi @var{num} +Sets the resolution of the generated font to @var{num}. +@item --mfmode @var{name} +Sets the Metafont mode to @var{name}. +@item --bdpi @var{num} +Sets the ``base dpi'' for the font. This must match the mode being +used. +@item --mag @var{string} +A ``magstep'' string suitable for the Metafont @code{mag} variable. +This must match the combination of @var{bdpi} and @var{dpi} being used. +@item --destdir @var{string} +A directory name. If the directory is absolute, it is used as-is. +Otherwise, it is appended to the root destination directory set in the +script. +@end table + + +@node Programming +@chapter Programming + +This chapter is for programmers who wish to use Kpathsea. +@xref{Introduction}, for the conditions under which you may do so (in +short, it is released under LGPLv2.1 or later). + +@menu +* Overview: Programming overview. Introduction. +* Calling sequence:: Specifics of what to call. +* Program-specific files:: How to handle these. +* Config: Programming with config files. Getting info from texmf.cnf. +@end menu + + +@node Programming overview +@section Programming overview + +@cindex programming overview +@cindex overview of programming with Kpathsea + +Aside from this manual, your best source of information is the source +to the programs that use Kpathsea (@pxref{Introduction}). First, +Kpsewhich is a small utility program whose sole purpose is to exercise +the main path-searching functionality. Of the drivers, Dviljk is +probably the simplest full application program. Xdvik adds VF support +and the complication of X resources. Dvipsk adds the complication of +its own config files. Web2c is source code I also maintain, so it +uses Kpathsea rather straightforwardly, but is of course complicated +by the Web to C translation. + +@cindex re-entrant API +@cindex API, re-entrant +When looking at these program sources, you should know that previous +versions of the library had a different programming interface; the +current interface supports re-entrancy. Historically, the library +function names were prefixed with @code{kpse_} instead of +@code{kpathsea_}, and they did not need an instance variable as first +argument. This change was made in 2009. The old functions will never +disappear, and can reliably continue to be used when they suffice, as +they do for the programs above. The main application using the +re-entrant API is the MetaPost library used by MetaPost and Lua@TeX{}. + +@flindex pathsearch.h +@flindex tex-file.h +@flindex tex-glyph.h +@flindex kpathsea.h +Beyond these examples, the @file{.h} files in the Kpathsea source +describe the interfaces and functionality (and of course the @file{.c} +files define the actual routines, which are the ultimate documentation). +@file{pathsearch.h} declares the basic searching routine. +@file{tex-file.h} and @file{tex-glyph.h} define the interfaces for +looking up particular kinds of files. In view of the way the headers +depend on each other, it is recommended to use @code{#include +<kpathsea/kpathsea.h>}, which includes every Kpathsea header. + +@flindex config.h +@flindex c-auto.h +If you want to include only specific headers, you should still consider +including @file{kpathsea/config.h} before including any other Kpathsea +header, as it provides symbols used in the other headers. Note that +@file{kpathsea/config.h} includes @file{kpathsea/c-auto.h}, which is +generated by Autoconf. + +@cindex file types, registering new +The library provides no way for an external program to register new file +types: @file{tex-file.[ch]} must be modified to do this. For example, +Kpathsea has support for looking up Dvips config files, even though no +program other than Dvips will likely ever want to do so. I felt this +was acceptable, since along with new file types should also come new +defaults in @file{texmf.cnf} (and its descendant @file{paths.h}), since +it's simplest for users if they can modify one configuration file for +all kinds of paths. + +Kpathsea does not parse any formats itself; it barely opens any files. +Its primary purpose is to return filenames. The GNU font utilities does +contain libraries to read TFM, GF, and PK files, as do the programs +above, of course. + + +@node Calling sequence +@section Calling sequence + +@cindex programming with Kpathsea +@cindex calling sequence + +The typical way to use Kpathsea in your program goes something like this: + +@enumerate + +@item +@findex kpathsea_new +Call @code{kpathsea_new} to create a new library instance. This variable +must be passed as the first argument to all the following library functions. +The rest of this manual will be using @code{kpse} as a placeholder for +the name of this variable. + +@item +@findex kpathsea_set_program_name +@vindex argv[0] +Call @code{kpathsea_set_program_name} with @code{argv[0]} as the second +argument; the third argument is a string or @code{NULL}. The third +argument is used by Kpathsea as the program name for the +@code{.@var{program}} feature of config files (@pxref{Config files}). +If the third argument is @code{NULL}, the value of the second argument +is used. This function must be called before any other use of the +Kpathsea library. + +@vindex kpse->invocation_name +@vindex kpse->invocation_short_name +@vindex kpse->program_name +@cindex error message macros +@code{kpathsea_set_program_name} always sets the variables +@code{kpse->invocation_name} and @code{kpse->invocation_short_name}. +These variables are used in the error message macros defined in +@file{kpathsea/lib.h}. It sets the variable +@code{kpse->program_name} to the program name it uses. + +@vindex KPATHSEA_DEBUG +It also initializes debugging options based on the environment +variable @code{KPATHSEA_DEBUG} (if that is set). + +@cindex SELFAUTOLOC +@cindex SELFAUTODIR +@cindex SELFAUTOPARENT +@cindex symlinks, resolving +@cindex expanding symlinks +Finally, it sets the environment variables @code{SELFAUTOLOC}, @code{SELFAUTODIR} +and @code{SELFAUTOPARENT} to the location, parent and grandparent +directory of the executable, removing @file{.} and @file{..} path +elements and resolving symbolic links. These are used in the default +configuration file to allow people to invoke TeX from anywhere. You +can use @samp{kpsewhich --expand-var=\$SELFAUTOLOC}, etc., to see the +values. + +@item +@vindex kpse->debug @r{variable} +@cindex debugging options, in Kpathsea-using program +Set debugging options. @xref{Debugging}. If your program doesn't have a +debugging option already, you can define one and set +@code{kpse->debug} to the number that the user supplies (as in Dviljk +and Web2c), or you can just omit this altogether (people can always set +@code{KPATHSEA_DEBUG}). If you do have runtime debugging already, you +need to merge Kpathsea's options with yours (as in Dvipsk and Xdvik). + +@item +@vindex client_path @r{in @code{kpse->format_info}} +@vindex kpse->format_info +@flindex resident.c +@cindex config files, for Kpathsea-using programs +If your program has its own configuration files that can define search +paths, you should assign those paths to the @code{client_path} member in +the appropriate element of the @code{kpse->format_info} array. (This +array is indexed by file type; see @file{tex-file.h}.) See +@file{resident.c} in Dvipsk for an example. + +@item +@findex kpathsea_init_prog +@flindex proginit.h +Call @code{kpathsea_init_prog} (see @file{proginit.c}). It's useful for the +DVI drivers, at least, but for other programs it may be simpler to +extract the parts of it that actually apply. This does not initialize +any paths, it just looks for (and sets) certain environment variables +and other random information. (A search path is always initialized at +the first call to find a file of that type; this eliminates much useless +work, e.g., initializing the Bib@TeX{} search paths in a DVI driver.) + +@item +@findex kpathsea_find_file +The routine to actually find a file of type @var{format} is +@file{kpathsea_find_file}. You can call +@code{kpathsea_find_file} after doing only the first and second of the +initialization steps above---Kpathsea automatically reads the +@file{texmf.cnf} generic config files, looks for environment variables, +and does expansions at the first lookup. + +@item +To find PK and/or GF bitmap fonts, the routine +is @code{kpathsea_find_glyph}, defined in +@file{tex-glyph.h}. This returns a structure in addition to the +resultant filename, because fonts can be found in so many ways. See the +documentation in the source. + +@item +@findex kpathsea_open_file +To actually open a file, not just return a filename, call +@code{kpathsea_open_file}. This function takes the name to look up and a +Kpathsea file format as arguments, and returns the usual @code{FILE *}. +It always assumes the file must exist, and thus will search the disk if +necessary (unless the search path specified @samp{!!}, etc.). In other +words, if you are looking up a VF or some other file that need not +exist, don't use this. + +@item +@findex kpathsea_out_name_ok +@TeX{} can write output files, via the @code{\openout} primitive; this opens +a security hole vulnerable to Trojan horse attack: an unwitting user could +run a @TeX{} program that overwrites, say, @file{~/.rhosts}. Analogous +security holes exist for many other programs. To alleviate this, there is a +configuration variable @code{openout_any}, which selects one of three levels +of security. When it is set to @samp{a} (for ``any''), no restrictions are +imposed. When it is set to @samp{r} (for ``restricted''), filenames +beginning with @samp{.} are disallowed (except @file{.tex} because @LaTeX{} +needs it). When it is set to @samp{p} (for ``paranoid'') additional +restrictions are imposed: an absolute filename must refer to a file in (a +subdirectory) of @code{TEXMFOUTPUT}, and any attempt to go up a directory +level is forbidden (that is, paths may not contain a @samp{..} component). +The paranoid setting is the default. (For backwards compatibility, @samp{y} +and @samp{1} are synonyms of @samp{a}, while @samp{n} and @samp{0} are +synonyms for @samp{r}.) The function @code{kpathsea_out_name_ok}, with a +filename as second argument, returns @code{true} if that filename is +acceptable to be opend for output or @code{false} otherwise. + +@item +@findex kpathsea_in_name_ok +Similarly, the function @code{kpathsea_in_name_ok}, with a filename as +second argument, returns @code{true} if that filename is acceptable to be +opend for input or @code{false} otherwise, depending on the value of the +configuration variable @code{openin_any} (with @samp{a} as default). + +@item +@findex kpathsea_finish +To close the kpathsea library instance you are using, call +@code{kpathsea_finish}. This function closes any open log files and +frees the memory used by the instance. + +@end enumerate + +@cindex hash table routines +@cindex memory allocation routines +@cindex string routines +@cindex reading arbitrary-length lines +@cindex input lines, reading +@cindex lines, reading arbitrary-length +Kpathsea also provides many utility routines. Some are generic: hash +tables, memory allocation, string concatenation and copying, string +lists, reading input lines of arbitrary length, etc. Others are +filename-related: default path, tilde, and variable expansion, +@code{stat} calls, etc. (Perhaps someday I'll move the former to a +separate library.) + +@flindex c-*.h +@pindex autoconf@r{, recommended} +The @file{c-*.h} header files can also help your program adapt to many +different systems. You will almost certainly want to use Autoconf and +probably Automake for configuring and building your software if you use +Kpathsea; I strongly recommend using Autoconf and Automake regardless. +They are available from @url{https://gnu.org/software}. + + +@node Program-specific files +@section Program-specific files + +Many programs will need to find some configuration files. Kpathsea +contains some support to make it easy to place them in their own +directories. The Standard @TeX{} directory structure (@pxref{Top,, +Introduction, tds, A Directory Structure for @TeX{} files}), specifies +that such files should go into a subdirectory named after the program, +like @samp{texmf/ttf2pk}. + +Two formats, @samp{kpse_program_text_format} and +@samp{kpse_program_binary_format}, use @code{.:$TEXMF/@var{program}//} +as their compiled-in search path. To override this default, you can +use the variable @code{@var{PROGRAM}INPUTS} in the environment and/or +@samp{texmf.cnf}. That is to say, the name of the variable is +constructed by converting the name of the program to upper case, and +appending @code{INPUTS}. + +The only difference between these two formats is whether +@code{kpathsea_open_file} will open the files it finds in text or binary +mode. + + +@node Programming with config files +@section Programming with config files + +@cindex programming with config files +@cindex config files, programming with + +You can (and probably should) use the same @code{texmf.cnf} +configuration file that Kpathsea uses for your program. This helps +installers by keeping all configuration in one place. + +@findex kpathsea_var_value +@flindex variable.h +@vindex shell_escape@r{, example for code} +To retrieve a value for a configuration variable @var{var}, the best +way is to call @code{kpathsea_var_value} on the string +@code{@var{var}}. This will look first for an environment variable +@var{var}, then a config file value. The result will be the value +found or @samp{NULL}. This function is declared in +@file{kpathsea/variable.h}. For an example, see the +@code{shell_escape} code in @file{web2c/lib/texmfmp.c}. + +The routine to do full variable and tilde expansion of an arbitrary +string in the context of a search path (as opposed to simply +retrieving a value) is @code{kpathsea_var_expand}, also declared in +@file{kpathsea/variable.h}. However, it's generally only necessary to +set the search path structure components as explained in the previous +section instead of using this directly. Because of its usage with any +input string, undefined @code{$FOO} constructs in the argument to +@code{kpathsea_var_expand} are returned literally (@code{"$FOO"}), +while undefined @code{$@{FOO@}} constructs are expanded to the empty +string. + +@findex kpathsea_cnf_get +@flindex cnf.h +If for some reason you want to retrieve a value @emph{only} from a +config file, not automatically looking for a corresponding environment +variable, call @code{kpathsea_cnf_get} (declared in @file{kpathsea/cnf.h}) +with the string @var{var}. + +No initialization calls are needed. + + +@node Reporting bugs +@chapter Reporting bugs + +@cindex reporting bugs +@cindex bugs, reporting + +@flindex tex-k@@tug.org @r{(bug address)} +@cindex bug address +If you have problems or suggestions, please report them to +@email{tex-k@@tug.org} using the bug checklist below. + +Please report bugs in the documentation; not only factual errors or +inconsistent behavior, but unclear or incomplete explanations, typos, +wrong fonts, @dots{} + +@menu +* Bug checklist:: What to include in a good bug report. +* Mailing lists:: Joining the bugs or announcements mailing lists. +* Debugging:: Analyzing runtime problems. +* Logging:: Recording searches. +* Common problems:: When things go wrong. +@end menu + + +@node Bug checklist +@section Bug checklist + +@cindex checklist for bug reports +@cindex bug checklist + +Before reporting a bug, please check below to be sure it isn't already +known (@pxref{Common problems}). + +Bug reports should be sent via electronic mail to +@email{tex-k@@tug.org}. + +The general principle is that a good bug report includes all the +information necessary for reproduction. Therefore, to enable +investigation, your report should include the following: + +@itemize @bullet +@item +@cindex version numbers, determining +The version number(s) of the program(s) involved, and of Kpathsea +itself. You can get the former by giving a sole option @samp{--version} +to the program, and the latter by running @samp{kpsewhich --version}. +The @file{NEWS} and @file{ChangeLog} files also contain the version +number. + +@item +@pindex uname +The hardware, operating system (including version), compiler, and +@code{make} program you are using (the output of @code{uname -a} is a +start on the first two, though incomplete). + +@item +@flindex config.log +Any options you gave to @code{configure}. This is recorded in the +@file{config.status} files. + +@cindex configuration bugs +@flindex config.status +If you are reporting a bug in @samp{configure} itself, it's probably +system-dependent, and it will be unlikely the maintainers can do +anything useful if you merely report that thus-and-such is broken. +Therefore, you need to do some additional work: for some bugs, you can +look in the file @file{config.log} where the test that failed should +appear, along with the compiler invocation and source program in +question. You can then compile it yourself by hand, and discover why +the test failed. Other @samp{configure} bugs do not involve the +compiler; in that case, the only recourse is to inspect the +@code{configure} shell script itself, or the Autoconf macros that +generated @code{configure}. + +@item +The log of all debugging output, if the bug is in path searching. You +can get this by setting the environment variable @code{KPATHSEA_DEBUG} +to @samp{-1} before running the program. Please look at the log +yourself to make sure the behavior is really a bug before reporting it; +perhaps ``old'' environment variable settings are causing files not to +be found, for example. + +@item +The contents of any input files necessary to reproduce the bug. For +bugs in DVI-reading programs, for example, this generally means a DVI +file (and any EPS or other files it uses)---@TeX{} source files are +helpful, but the DVI file is required, because that's the actual +program input. + +@item +@cindex context diff +@cindex sending patches +@flindex ChangeLog @r{entry} +If you are sending a patch (do so if you can!), please do so in the form +of a context diff (@samp{diff -c}) against the original distribution +source. Any other form of diff is either not as complete or harder for +me to understand. Please also include a @file{ChangeLog} entry. + +@item +@cindex stack trace +@cindex debugger +@cindex crashes, reporting +@cindex core dumps, reporting +@cindex null pointers, dereferencing +@pindex gdb@r{, recommended} +If the bug involved is an actual crash (i.e., core dump), it is easy +and useful to include a stack trace from a debugger (I recommend the +GNU debugger GDB (@url{https://gnu.org/software/gdb}). If the +cause is apparent (a @code{NULL} value being dereferenced, for +example), please send the details along. If the program involved is +@TeX{} or Metafont, and the crash is happening at apparently-sound +code, however, the bug may well be in the compiler, rather than in the +program or the library (@pxref{TeX or Metafont failing,, @TeX{} or +Metafont failing}). + +@item +Any additional information that will be helpful in reproducing, +diagnosing, or fixing the bug. +@end itemize + + +@node Mailing lists +@section Mailing lists + +@cindex mailing lists +@cindex bug mailing list +@cindex announcement mailing list + +@flindex tex-k@@tug.org +Web2c and Kpathsea in general are discussed on the mailing list +@email{tex-k@@tug.org}. You can subscribe and peruse the archives on +the web @url{https://lists.tug.org/tex-k}. + +You do not need to join to submit a report, nor will it affect whether +you get a response. Be aware that large data files are sometimes +included in bug reports. If this is a problem for you, do not join +the list. + +If you are looking for general @TeX{} help, such as how to install a +full @TeX{} system or how to use @LaTeX{}, please see +@url{https://tug.org/begin.html}. + + +@node Debugging +@section Debugging + +@cindex debugging +@cindex runtime debugging +@cindex options for debugging + +@vindex kpse->debug +@flindex debug.h +Kpathsea provides a number of runtime debugging options, detailed below +by their names and corresponding numeric values. When the files you +expect aren't being found, the thing to do is enable these options and +examine the output. + +You can set these with some runtime argument (e.g., @samp{-d}) to the +program; in that case, you should use the numeric values described in +the program's documentation (which, for Dvipsk and Xdvik, are different +than those below). It's best to give the @samp{-d} (or whatever) option +first, for maximal output. Dvipsk and Xdvik have additional +program-specific debugging options as well. + +@vindex KPATHSEA_DEBUG +@vindex kpse->debug +You can also set the environment variable @code{KPATHSEA_DEBUG}; in this +case, you should use the numbers below. If you run the program under a +debugger and set the instance variable @code{kpse->debug}, also use the numbers +below. + +@kindex -1 @r{debugging value} +In any case, by far the simplest value to use is @samp{-1}, which will +turn on all debugging output. This is usually better than guessing +which particular values will yield the output you need. + +@cindex debugging output +@cindex standard error and debugging output +Debugging output always goes to standard error, so you can redirect it +easily. For example, in Bourne-compatible shells: +@example +dvips -d -1 @dots{} 2>/tmp/debug +@end example + +@cindex Kpsewhich, and debugging +It is sometimes helpful to run the standalone Kpsewhich utility +(@pxref{Invoking kpsewhich}), instead of the original program. + +@cindex numeric debugging values +In any case, you cannot use the names below; you must always use +somebody's numbers. (Sorry.) To set more than one option, just sum +the corresponding numbers. + +@vtable @code +@item KPSE_DEBUG_STAT @r{(1)} +Report @samp{stat}(2) calls. This is useful for verifying that your +directory structure is not forcing Kpathsea to do many additional file +tests (@pxref{Slow path searching}, and @pxref{Subdirectory +expansion}). If you are using an up-to-date @file{ls-R} database +(@pxref{Filename database}), this should produce no output unless a +nonexistent file that must exist is searched for. + +@item KPSE_DEBUG_HASH @r{(2)} +Report lookups in all hash tables: @file{ls-R} and @file{aliases} +(@pxref{Filename database}); font aliases (@pxref{Fontmap}); and config +file values (@pxref{Config files}). Useful when expected values are not +being found, e.g.., file searches are looking at the disk instead of +using @file{ls-R}. + +@item KPSE_DEBUG_FOPEN @r{(4)} +@findex fopen@r{, redefined} +Report file openings and closings. Especially useful when your system's +file table is full, for seeing which files have been opened but never +closed. In case you want to set breakpoints in a debugger: this works by +redefining @samp{fopen} (@samp{fclose}) to be @samp{kpse_fopen_trace} +(@samp{kpse_fclose_trace}). + +@item KPSE_DEBUG_PATHS @r{(8)} +@tindex kpse_format_info_type +Report general path information for each file type Kpathsea is asked to +search. This is useful when you are trying to track down how a +particular path got defined---from @file{texmf.cnf}, @file{config.ps}, +an environment variable, the compile-time default, etc. This is the +contents of the @code{kpse_format_info_type} structure defined in +@file{tex-file.h}. + +@item KPSE_DEBUG_EXPAND @r{(16)} +Report the directory list corresponding to each path element Kpathsea +searches. This is only relevant when Kpathsea searches the disk, since +@file{ls-R} searches don't look through directory lists in this way. + +@item KPSE_DEBUG_SEARCH @r{(32)} +Report on each file search: the name of the file searched for, the path +searched in, whether or not the file must exist (when drivers search for +@file{cmr10.vf}, it need not exist), and whether or not we are +collecting all occurrences of the file in the path (as with, e.g., +@file{texmf.cnf} and @file{texfonts.map}), or just the first (as with +most lookups). This can help you correlate what Kpathsea is doing with +what is in your input file. + +@item KPSE_DEBUG_VARS @r{(64)} +Report the value of each variable Kpathsea looks up. This is useful for +verifying that variables do indeed obtain their correct values. + +@item GSFTOPK_DEBUG @r{(128)} +Activates debugging printout specific to @code{gsftopk} program. + +@item MAKETEX_DEBUG @r{(512)} +If you use the optional @code{mktex} programs instead of the +traditional shell scripts, this will report the name of the site file +(@file{mktex.cnf} by default) which is read, directories created by +@code{mktexdir}, the full path of the @file{ls-R} database built by +@code{mktexlsr}, font map searches, @code{MT_FEATURES} in effect, +parameters from @code{mktexnam}, filenames added by +@code{mktexupd}, and some subsidiary commands run by the programs. + +@item MAKETEX_FINE_DEBUG @r{(1024)} +When the optional @code{mktex} programs are used, this will print +additional debugging info from functions internal to these programs. +@end vtable + +@cindex @samp{kdebug:} +@vindex hash_summary_only @r{variable for debugging} +@cindex hash table buckets, printing +Debugging output from Kpathsea is always written to standard error, and +begins with the string @samp{kdebug:}. (Except for hash table buckets, +which just start with the number, but you can only get that output +running under a debugger. See comments at the @code{hash_summary_only} +variable in @file{kpathsea/db.c}.) + + +@node Logging +@section Logging + +@cindex log file + +@cindex logging successful searches +@cindex recording successful searches +@cindex usage patterns, finding +@cindex disk usage, reducing +Kpathsea can record the time and filename found for each successful +search. This may be useful in finding good candidates for deletion when +your filesystem is full, or in discovering usage patterns +at your site. + +@vindex TEXMFLOG +To do this, define the environment or config file variable +@code{TEXMFLOG}. The value is the name of the file to append the +information to. The file is created if it doesn't exist, and appended +to if it does. + +@cindex epoch, seconds since +@findex time @r{system call} +Each successful search turns into one line in the log file: two words +separated by a space. The first word is the time of the search, as the +integer number of seconds since ``the epoch'', i.e., UTC midnight 1 +January 1970 (more precisely, the result of the @code{time} system +call). The second word is the filename. + +For example, after @code{setenv TEXMFLOG /tmp/log}, running Dvips on +@file{story.dvi} appends the following lines: + +@example +774455887 /usr/local/share/texmf/dvips/config.ps +774455887 /usr/local/share/texmf/dvips/psfonts.map +774455888 /usr/local/share/texmf/dvips/texc.pro +774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk +774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk +774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk +774455889 /usr/local/share/texmf/dvips/texc.pro +@end example + +@cindex privacy, semblance of +@noindent Only filenames that are absolute are recorded, to preserve +some semblance of privacy. + +In addition to this Kpathsea-specific logging, @command{pdftex} +provides an option @option{-recorder} to write the names of all files +accessed during a run to the file @file{@var{basefile}.fls}. + +Finally, most systems provide a general tool to output each system +call, thus including opening and closing files. It might be named +@command{strace}, @command{truss}, @command{struss}, or something +else. + + +@node Common problems +@section Common problems + +@cindex common problems +@cindex problems, common +@cindex FAQ, Kpathsea + +Here are some common problems with configuration, compilation, linking, +execution, @dots{} + +@menu +* Unable to find files:: If your program can't find fonts (or whatever). +* Slow path searching:: If it takes forever to find anything. +* Unable to generate fonts:: If mktexpk fails. +* TeX or Metafont failing:: Likely compiler bugs. +@end menu + +@node Unable to find files +@subsection Unable to find files + +@cindex unable to find files +@cindex files, unable to find + +If a program complains it cannot find fonts (or other input files), any +of several things might be wrong. In any case, you may find the +debugging options helpful. @xref{Debugging}. + +@itemize @bullet +@item +Perhaps you simply haven't installed all the necessary files; the basic +fonts and input files are distributed separately from the programs. +@xref{unixtex.ftp}. + +@item +@flindex /etc/profile +@cindex environment variables, old +You have (perhaps unknowingly) told Kpathsea to use search paths that +don't reflect where the files actually are. One common cause is having +environment variables set from a previous installation, thus overriding +what you carefully set in @file{texmf.cnf} (@pxref{Supported file +formats}). System @file{/etc/profile} or other files such may be the +culprit. + +@item +@cindex symbolic links not found +@cindex leaf directories wrongly guessed +Your files reside in a directory that is only pointed to via a symbolic +link, in a leaf directory and is not listed in @file{ls-R}. + +Unfortunately, Kpathsea's subdirectory searching has an irremediable +deficiency: If a directory @var{d} being searched for subdirectories +contains plain files and symbolic links to other directories, but no +true subdirectories, @var{d} will be considered a leaf directory, i.e., +the symbolic links will not be followed. @xref{Subdirectory expansion}. + +You can work around this problem by creating an empty dummy subdirectory +in @var{d}. Then @var{d} will no longer be a leaf, and the symlinks will +be followed. + +The directory immediately followed by the @samp{//} in the path +specification, however, is always searched for subdirectories, even if +it is a leaf. Presumably you would not have asked for the directory to +be searched for subdirectories if you didn't want it to be. + +@item +If the fonts (or whatever) don't already exist, @code{mktexpk} (or +@code{mktexmf} or @code{mktextfm}) will try to create them. If +these rather complicated shell scripts fail, you'll eventually get an +error message saying something like @samp{Can't find font +@var{fontname}}. The best solution is to fix (or at least report) the +bug in @code{mktexpk}; the workaround is to generate the necessary +fonts by hand with Metafont, or to grab them from a CTAN site +(@pxref{unixtex.ftp}). + +@item +There is a bug in the library. @xref{Reporting bugs}. +@end itemize + + +@node Slow path searching +@subsection Slow path searching + +@cindex excessive startup time +@cindex slow startup time +@cindex startup time, excessive + +If your program takes an excessively long time to find fonts or other +input files, but does eventually succeed, here are some possible culprits: + +@itemize @bullet +@item +Most likely, you just have a lot of directories to search, and that +takes a noticeable time. The solution is to create and maintain a +separate @file{ls-R} file that lists all the files in your main @TeX{} +hierarchy. @xref{Filename database}. Kpathsea always uses @file{ls-R} +if it's present; there's no need to recompile or reconfigure any of the +programs. + +@item +Your recursively-searched directories (e.g., +@file{/usr/local/share/texmf/fonts//}), contain a mixture of files and +directories. This prevents Kpathsea from using a useful optimization +(@pxref{Subdirectory expansion}). + +It is best to have only directories (and perhaps a @file{README}) in the +upper levels of the directory structure, and it's very important to have +@emph{only} files, and no subdirectories, in the leaf directories where +the dozens of TFM, PK, or whatever files reside. +@end itemize + +In any case, you may find the debugging options helpful in determining +precisely when the disk or network is being pounded. @xref{Debugging}. + + +@node Unable to generate fonts +@subsection Unable to generate fonts + +@cindex unable to generate fonts +@cindex font generation failures + +Metafont outputs fonts in bitmap format, tuned for a particular +device at a particular resolution, in order to allow for the +highest-possible quality of output. Some DVI-to-whatever programs, +such as Dvips, try to generate these on the fly when they are needed, +but this generation may fail in several cases. + +@cindex @code{mktexpk} can't guess mode +If @code{mktexpk} runs, but fails with this error: +@example +mktexpk: Can't guess mode for @var{nnn} dpi devices. +mktexpk: Use a config file to specify the mode, or update me. +@end example +you need to ensure the resolution and mode match; just +specifying the resolution, as in @code{-D 360}, is not enough. + +You can specify the mode name with the @code{-mode} option on the +Dvips command line, or in a Dvips configuration file (@pxref{Config +files,,, dvips, Dvips}), such as @file{config.ps} in your document +directory, @file{~/.dvipsrc} in your home directory, or in a system +directory (again named @file{config.ps}). (Other drivers use other +files, naturally.) + +For example, if you need 360@dmn{dpi} fonts, you could include this in +a configuration file: +@example +D 360 +M lqmed +@end example + +@cindex Metafont using the wrong device +@cindex device, wrong +If Metafont runs, but generates fonts at the wrong resolution or for +the wrong device, most likely @code{mktexpk}'s built-in guess for the +mode is wrong, and you should override it as above. + +See @url{https://ctan.org/pkg/modes} for a list of resolutions and mode +names for most devices (additional submissions are welcome). + +@flindex .2602gf +@flindex 2602gf +@cindex Metafont making too-large fonts +@cindex proof mode +@cindex online Metafont display, spurious +If Metafont runs but generates fonts at a resolution of 2602@dmn{dpi} +(and prints out the name of each character as well as just a character +number, and maybe tries to display the characters), then your Metafont +base file probably hasn't been made properly. (It's using the default +@code{proof} mode, instead of an actual device mode.) To make a proper +@file{plain.base}, assuming the local mode definitions are contained in +a file @file{modes.mf}, run the following command (assuming Unix): + +@example +inimf "plain; input modes; dump" +@end example + +@noindent +@flindex plain.base +Then copy the @file{plain.base} file from the current directory to where +the base files are stored on your system +(@file{/usr/local/share/texmf/web2c} by default), and make a link +(either hard or soft) from @file{plain.base} to @file{mf.base} in that +directory. +@xref{inimf invocation,,, web2c, Web2c}. + +@cindex Metafont installation +If @code{mf} is a command not found at all by @code{mktexpk}, then you +need to install Metafont (@pxref{unixtex.ftp}). + + +@node TeX or Metafont failing +@subsection @TeX{} or Metafont failing + +@cindex @TeX{} failures +@cindex Metafont failures +@cindex compiler bugs +If @TeX{} or Metafont get a segmentation fault or otherwise fail while +running a normal input file, the problem is usually a compiler bug +(unlikely as that may sound). Even if the trip and trap tests are +passed, problems may lurk. Optimization occasionally causes trouble in +programs other than @TeX{} and Metafont themselves, too. + +@cindex optimization caveat +For a workaround, if you enabled any optimization flags, it's best to +omit optimization entirely. In any case, the way to find the facts is +to run the program under the debugger and see where it's failing. + +@cindex GNU C compiler bugs +@cindex system C compiler bugs +Also, if you have trouble with a system C compiler, I advise trying the +GNU C compiler. And vice versa, unfortunately; but in that case I also +recommend reporting a bug to the GCC mailing list; see @ref{Bugs,,, gcc, +Using and Porting GNU CC}. + +@cindex compiler bugs, finding +To report compiler bugs effectively requires perseverance and +perspicacity: you must find the miscompiled line, and that usually +involves delving backwards in time from the point of error, checking +through @TeX{}'s (or whatever program's) data structures. Good luck. + + +@node Index +@unnumbered Index + +@printindex cp + +@bye |