Kpathsea library

5.2.1 Config files

As mentioned above, Kpathsea reads runtime configuration files named texmf.cnf for search path and other definitions. The search path used to look for these configuration files is named 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 ls-R database is not used to search for them.

Kpathsea reads all 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 ‘.:$TEXMF’, values from ./texmf.cnf override those from $TEXMF/texmf.cnf.

If Kpathsea cannot find any 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 KPATHSEA_WARNING to the single character ‘0’ (zero, not oh).

While (or instead of) reading this description, you may find it helpful to look at the distributed texmf.cnf, which uses or at least mentions most features. The format of texmf.cnf files follows:

• Comments start with ‘%’ or ‘#’, 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 comment character in the “middle” of a value does not start a comment. Examples:

  % this is a comment
  var = a%b  % but the value of var will be "a%b"
  

• Blank lines are ignored.
• A ‘\’ 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.
• Each remaining line will look like:

  variable [. progname] [=] value
  

  where the ‘=’ and surrounding whitespace is optional.

• The variable name may contain any character other than whitespace, ‘=’, or ‘.’, but sticking to ‘A-Za-z_’ is safest.
• If ‘.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 argv[0] is) progname or progname.{exe,bat,cmd,...}. Most notably, this allows different flavors of TeX to have different search paths. The progname value is used literally, without variable or other expansions.
• Considered as strings, value may contain any character. However, in practice most 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 ‘$var.prog’ feature is not available on the right-hand side; instead, you must use an additional variable (see below for example).

  A ‘;’ in value is translated to ‘:’ if running under Unix, in order to have a single texmf.cnf that can support both Unix and Windows systems. This translation happens with any value, not just search paths, but fortunately in practice ‘;’ is not needed in other values.

• All definitions are read before anything is expanded, so you can use variables before they are defined (like Make, unlike most other programs).

Here is a configuration file fragment illustrating most of these points:

% 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

The combination of spaces being ignored before the . of a program name qualifer and the optional ‘=’ for the assignment has an unexpected consequence: if the value begins with a literal ‘.’ and the ‘=’ is omitted, the intended value is interpreted as a program name. For example, a line var .;/some/path is taken as an empty value for var running under the program named ‘;/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 =.

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, …) and so cannot be concisely stated, unfortunately. There is no general escape mechanism; in particular, ‘\’ is not an “escape character” in texmf.cnf files. When it comes choosing directory names for installation, it is safest to avoid them all.

The implementation of all this is in kpathsea/cnf.c.

5.3.1 Default expansion

If the highest-priority search path (see Path sources) contains an 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

setenv TEXINPUTS /home/karl:

and a TEXINPUTS value from texmf.cnf of

.:$TEXMF//tex

then the final value used for searching will be:

/home/karl:.:$TEXMF//tex

Put another way, default expansion works on “formats” (search paths), and not directly on environment variables. Example, showing the trailing ‘:’ ignored in the first case and expanded in the second:

$ env TTFONTS=/tmp: kpsewhich --expand-path '$TTFONTS'
/tmp
$ env TTFONTS=/tmp: kpsewhich --show-path=.ttf
/tmp:.:/home/olaf/texmf/fonts/truetype//:...

Since Kpathsea looks for multiple configuration files, it would be natural to expect that (for example) an extra colon in ./texmf.cnf would expand to the path in $TEXMF/texmf.cnf. Or, with Dvips’ configuration files, that an extra colon in config.$PRINTER would expand to the path in 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.

Technicality: Since it would be useless to insert the default value in more than one place, Kpathsea changes only one extra ‘:’ and leaves any others in place (they will eventually be ignored). Kpathsea checks first for a leading ‘:’, then a trailing ‘:’, then a doubled ‘:’.

You can trace this by debugging “paths” (see Debugging). Default expansion is implemented in the source file kpathsea/kdefault.c.

5.3.2 Variable expansion

‘$foo’ or ‘${foo}’ in a path element is replaced by (1) the value of an environment variable ‘foo’ (if defined); (2) the value of ‘foo’ from texmf.cnf (if defined); (3) the empty string.

If the character after the ‘$’ is alphanumeric or ‘_’, the variable name consists of all consecutive such characters. If the character after the ‘$’ is a ‘{’, the variable name consists of everything up to the next ‘}’ (braces may not be nested around variable names). Otherwise, Kpathsea gives a warning and ignores the ‘$’ and its following character.

You must quote the $’s and braces as necessary for your shell. Shell variable values cannot be seen by Kpathsea, i.e., ones defined by set in C shells and without export in Bourne shells.

For example, given

setenv tex /home/texmf
setenv TEXINPUTS .:$tex:${tex}prev

the final TEXINPUTS path is the three directories:

.:/home/texmf:/home/texmfprev

The ‘.progname’ suffix on variables and ‘_progname’ on environment variable names are not implemented for general variable expansions. These are only recognized when search paths are initialized (see Path sources).

Variable expansion is implemented in the source file kpathsea/variable.c.

5.3.3 Tilde expansion

A leading ‘~’ in a path element is replaced by the value of the environment variable HOME, or . if HOME is not set. On Windows, the environment variable USERPROFILE is checked instead of HOME.

A leading ‘~user’ in a path element is replaced by user’s home directory from the system passwd database.

For example,

setenv TEXINPUTS ~/mymacros:

will prepend a directory mymacros in your home directory to the default path.

As a special case, if a home directory ends in ‘/’, the trailing slash is dropped, to avoid inadvertently creating a ‘//’ construct in the path. For example, if the home directory of the user ‘root’ is ‘/’, the path element ‘~root/mymacros’ expands to just ‘/mymacros’, not ‘//mymacros’.

Tilde expansion is implemented in the source file kpathsea/tilde.c.

5.3.4 Brace expansion

‘x{a,b}y’ expands to ‘xay:xby’. For example:

foo/{1,2}/baz

expands to ‘foo/1/baz:foo/2/baz’. ‘:’ is the path separator on the current system; e.g., on a Windows system, it’s ‘;’.

Braces can be nested; for example, ‘x{A,B{1,2}}y’ expands to ‘xAy:xB1y:xB2y’.

Multiple non-nested braces are expanded from right to left; for example, ‘x{A,B}{1,2}y’ expands to ‘x{A,B}1y:x{A,B}2y’, which expands to ‘xA1y:xB1y:xA2y:xB2y’.

This feature can be used to implement multiple TeX hierarchies, by assigning a brace list to $TEXMF, as mentioned in texmf.in.

You can also use the path separator instead of the comma. The last example could have been written ‘x{A:B}{1:2}y’ (on Unix).

Brace expansion is implemented in the source file kpathsea/expand.c.

5.3.5 KPSE_DOT expansion

When 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 ‘mktex…’ scripts mktex scripts, because these change the working directory. You should not ever define it yourself.

5.3.6 Subdirectory expansion

Two or more consecutive slashes in a path element following a directory d is replaced by all subdirectories of d: first those subdirectories directly under 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 ‘//’, only subdirectories which match those components are included. For example, ‘/a//b’ would expand into directories /a/1/b, /a/2/b, /a/1/1/b, and so on, but not /a/b/c or /a/1.

You can include multiple ‘//’ constructs in the path.

‘//’ at the beginning of a path is ignored; you didn’t really want to search every directory on the system, did you?

I should mention one related implementation trick, which I took from GNU find. Matthew Farwell suggested it, and David MacKenzie implemented it.

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 . and one for ..). That is to say, the st_nlink field in the ‘stat’ structure will be two. Thus, we don’t have to stat everything in the bottom-level (leaf) directories—we can just check 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, st_nlink will be 3, and Kpathsea has to stat every one of those 501 entries. Therein lies slowness.

You can disable the trick by undefining ST_NLINK_TRICK in kpathsea/config.h. (It is undefined by default except under Unix.)

Unfortunately, in some cases files in leaf directories are stat’d: if the path specification is, say, ‘$TEXMF/fonts//pk//’, then files in a subdirectory ‘…/pk’, even if it is a leaf, are checked. The reason cannot be explained without reference to the implementation, so read kpathsea/elt-dirs.c (search for ‘may descend’) if you are curious. And if you find a way to solve the problem, please let me know.

Subdirectory expansion is implemented in the source file kpathsea/elt-dirs.c.

5.4.1 Casefolding rationale

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 foo.jpg, while the actual file is named foo.JPG or 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.

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.

5.4.2 Casefolding examples

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 texmf_casefold_search to ‘0’ (see Path sources).

Some examples to illustrate the new behavior follow.

Example #1: suppose the file ./foobar.tex exists. Now, searching for ./FooBar.TeX (or any other case variation) will succeed, returning ./foobar.tex—the name as stored on disk. In previous releases, or if 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 ‘.:/somedir’, and the files ./foobar.tex and /somedir/FooBar.TeX both exist. Both now and previously, searching for foobar.tex returns ./foobar.tex. However, searching for FooBar.TeX now returns ./foobar.tex instead of /somedir/FooBar.TeX; this is the incompatibility mentioned above. Also (as expected), searching for FOOBAR.TEX (or whatever variation) will now return ./foobar.tex, whereas before it would fail. Searching for all (‘kpsewhich --all’) 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 FooBar.TeX returns ./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 ./foobar.tex and ./FOOBAR.TEX, searching with the exact case returns that exact match, now and previously. Searching for FooBar.tex will now return one or the other (chosen arbitrarily), rather than failing. Perhaps unexpectedly, searching for all foobar.tex or FooBar.tex will also return only one or the other, not both (see more below).

Example #5: the font file STIX-Regular.otf is included in TeX Live in the system directory 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 ‘stix-regular.otf’ will fail (on case-sensitive systems), as it always has.

The caveat about not searching the disk amounts to saying that casefolding does not happen in the trees specified with ‘!!’ (see ls-R), that is, where only database (ls-R) searching is done. In TeX Live, that is the ‘texmf-local’ and ‘texmf-dist’ trees (also $TEXMFSYSCONFIG and $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 kpsewhich is to exercise the path searching in Kpathsea as it is actually done. Therefore, as shown above, ‘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, find is the best tool, although the setup takes a couple steps:

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

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 find does not support -iname, you can get GNU Find from https://gnu.org/software/findutils.

The casefolding search is implemented in the source file kpathsea/pathsearch.c. Two implementation points:

• 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 access system call).
• Kpathsea does not do any case-insensitive matching of the directories along the path. It’s not going to find /Some/Random/file.tex when looking for /some/random/file.tex. The casefolding only happens with the elements of the leaf directory.

5.5.1 ls-R

As mentioned above, you must name the main filename database ls-R. You can put one at the root of each TeX installation hierarchy you wish to search ($TEXMF by default, which expands to a braced list of several hierarchies in TeX Live).

Kpathsea looks for ls-R files along the TEXMFDBS path. It is best for this to contain all and only those hierarchies from $TEXMF which are specified with !!—and also to specify them with !! in TEXMFDBS. (See the end of this section for more on !!.)

The recommended way to create and maintain ‘ls-R’ is to run the mktexlsr script, which is installed in ‘$(bindir)’ (/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 ‘mktex…’ scripts.

At its simplest, though, you can build ls-R with the command

cd /your/texmf/root && ls -LAR ./ >ls-R

presuming your ls produces the right output format (see the section below). GNU ls, for example, outputs in this format. Also presuming your ls hasn’t been aliased in a system file (e.g., /etc/profile) to something problematic, e.g., ‘ls --color=tty’. In that case, you will have to disable the alias before generating ls-R. For the precise definition of the file format, see Database format.

Regardless of whether you use the supplied script or your own, you will almost certainly want to invoke it via cron, so when you make changes in the installed files (say if you install a new LaTeX package), ls-R will be automatically updated. However, for those using TeX Live or system distributions, the package managers should run mktexlsr as needed.

The ‘-A’ option to ls includes files beginning with ‘.’ (except for . and ..), such as the file .tex included with the LaTeX tools package. (On the other hand, directories whose names begin with ‘.’ are always ignored.)

If your system does not support symbolic links, omit the ‘-L’.

ls -LAR /your/texmf/root will also work. But using ‘./’ avoids embedding absolute pathnames, so the hierarchy can be easily transported. It also avoids possible trouble with automounters or other network filesystem conventions.

Kpathsea warns you if it finds an ls-R file, but the file does not contain any usable entries. The usual culprit is running plain ‘ls -R’ instead of ‘ls -LR ./’ or ‘ls -R /your/texmf/root’. Another possibility is some system directory name starting with a ‘.’ (perhaps if you are using AFS); Kpathsea ignores everything under such directories.

If a particular path element begins with ‘!!’, 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 ‘!!’.

For path elements that do not begin with ‘!!’, 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 TEXMFHOME tree, to allow users to add and remove files from their own tree without having to worry about ls-R.

(Aside: there are uncommon cases where a ‘!!’ tree will be searched on disk even if the ls-R file exists; they are too obscure to try to explain here. See pathsearch.c in the source if you need to know.)

To sum up: do not create an ls-R file unless you also take care to keep it up to date. Otherwise newly-installed files will not be found.

5.5.2 Filename aliases

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 longtabl.sty. But now it’s being run on a Unix system, and the file has its original name, longtable.sty. The file won’t be found. You need to give the actual file longtable.sty an alias ‘longtabl.sty’.

You can handle this by creating a file aliases as a companion to the ls-R for the hierarchy containing the file in question. (You must have an ls-R for the alias feature to work.)

The format of aliases is simple: two whitespace-separated words per line; the first is the real name longtable.sty, and second is the alias (longtabl.sty). These must be base filenames, with no directory components. longtable.sty must be in the sibling ls-R.

Also, blank lines and lines starting with ‘%’ or ‘#’ are ignored in aliases, to allow for comments.

If a real file longtabl.sty exists, it is used regardless of any aliases.

5.5.3 Database format

The “database” read by Kpathsea is a line-oriented file of plain text. The format is that generated by GNU (and most other) ls programs given the ‘-R’ option, as follows.

• Blank lines are ignored.
• If a line begins with ‘/’ or ‘./’ or ‘../’ and ends with a colon, it’s the name of a directory. (‘../’ lines aren’t useful, however, and should not be generated.)
• All other lines define entries in the most recently seen directory. /’s in such lines will produce possibly-strange results.
• Files with no preceding directory line are ignored.

For example, here’s the first few lines of ls-R (which totals about 30K bytes) on my system:

bibtex
dvips
fonts
ls-R
metafont
metapost
tex
web2c

./bibtex:
bib
bst
doc

./bibtex/bib:
asi.bib
btxdoc.bib
…

5.6.1 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:

‘--all’ ¶

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 (pk, gf), this option has no effect and only the first match is returned.

‘--casefold-search’ ¶

‘--no-casefold-search’

Explicitly enable or disable the fallback to a case-insensitive search on Unix platforms (see Casefolding search); no effect on Windows. The default is enabled, set in texmf.cnf. Disabling (--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.

‘--cnf-line=str’ ¶

Parse str as if it were a line in the texmf.cnf configuration file (see Config files), overriding settings in the actual configuration files, and also in the environment (see Path sources). This is implemented by making any settings from str in the environment, overwriting any value already there. Thus, an extra colon in a ‘--cnf-line’ value will refer to the value from a configuration file, not a user-set environment variable.

Furthermore, any variable set from str will also be set with the program name suffix. For example, pdftex --cnf-line=TEXINPUTS=/foo: will set both TEXINPUTS and TEXINPUTS_pdftex in the environment (and the value will be /foo followed by the setting from texmf.cnf, ignoring any user-set TEXINPUTS).

This behavior is desirable because, in practice, many variables in the distributed texmf.cnf are program-specific, and the intuitive behavior is for values set on the command line with --cnf-line to override them.

‘--dpi=num’ ¶

Set the resolution to num; this only affects ‘gf’ and ‘pk’ lookups. ‘-D’ is a synonym, for compatibility with Dvips. Default is 600.

‘--engine=name’ ¶

Set the engine name to 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 (.fmt/.base/.mem) are now stored in subdirectories named for the engine (tex, pdftex, xetex, etc.), you must specify an engine name in order to find them. For example, cont-en.fmt typically exists for both pdftex and xetex. With the default path settings, you can use ‘--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 ‘/’ ends up specifying a normal recursive search along the path where the dumps are stored, namely ‘$TEXMF/web2c{/$engine,}’.)

‘--format=name’ ¶

Set the format for lookup to name. By default, the format is guessed from the filename, with ‘tex’ being used if nothing else fits. The recognized filename extensions (including any leading ‘.’) are also allowable names.

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 ‘--format="dvips config"’. (The quotes are for the sake of the shell.)

Here’s the current list of recognized names and the associated suffixes. See Supported file formats, for more information on each of these.

The strings in parentheses are abbreviations recognized only by 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.

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 .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

This option and ‘--path’ are mutually exclusive.

‘--interactive’ ¶

After processing the command line, read additional filenames to look up from standard input.

‘--mktex=filetype’ ¶

‘--no-mktex=filetype’

Turn on or off the ‘mktex’ script associated with filetype. Usual values for filetype are ‘pk’, ‘mf’, ‘tex’, and ‘tfm’. By default, all are off in Kpsewhich, even if they are enabled for TeX. This option implies setting --must-exist. See mktex scripts.

‘--mode=string’ ¶

Set the mode name to string; this also only affects ‘gf’ and ‘pk’ lookups. No default: any mode will be found. See mktex script arguments.

‘--must-exist’ ¶

Do everything possible to find the files, notably including searching the disk and running the ‘mktex’ scripts. By default, only the ls-R database is checked, in the interest of efficiency.

‘--path=string’ ¶

Search along the path string (colon-separated as usual), instead of guessing the search path from the filename. ‘//’ and all the usual expansions are supported (see Path expansion). This option and ‘--format’ are mutually exclusive. To output the complete directory expansion of a path, instead of doing a one-shot lookup, see ‘--expand-path’ and ‘--show-path’ in the following section.

‘--progname=name’ ¶

Set the program name to name; default is ‘kpsewhich’. This can affect the search paths via the ‘.prognam’ feature in configuration files (see Config files).

‘--subdir=string’ ¶

Report only those matches whose directory part ends with string (compared literally, except case is ignored on a case-insensitive operating system). For example, suppose there are two matches for a given name:

kpsewhich foo.sty
⇒ /some/where/foo.sty
/another/place/foo.sty

Then we can narrow the result to what we are interested in with --subdir:

kpsewhich --subdir=where foo.sty
⇒ /some/where/foo.sty

kpsewhich --subdir=place foo.sty
⇒ /another/place/foo.sty

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:

kpsewhich --subdir=another foo.sty
⇒

The string to match may cross directory components:

kpsewhich --subdir=some/where foo.sty
⇒ /some/where/foo.sty

--subdir implies --all; if there is more than one match, they will all be reported (in our example, both ‘where’ and ‘place’ end in ‘e’):

kpsewhich --subdir=e
⇒ /some/where/foo.sty
/another/place/foo.sty

Because of the above rules, the presence of a leading ‘/’ is important, since it “anchors” the match to a full component name:

kpsewhich --subdir=/lace foo.sty
⇒

However, a trailing ‘/’ is immaterial (and ignored), since the match always takes place at the end of the directory part:

kpsewhich --subdir=lace/ foo.sty
⇒ /another/place/foo.sty

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 foo.lua might exist within both texmf-dist/scripts/pkg1/ and texmf-dist/scripts/pkg2/. By specifying, say, ‘--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 /some/coincidental/pkg1/path/, and we wouldn’t want to match texmf-dist/scripts/pkg2/ that when searching for ‘/pkg1’.

5.6.2 Specially-recognized files for kpsewhich

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 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 kpsewhich, along with their corresponding format:

config.ps

dvips config

dvipdfmx.cfg

‘other text files’

fmtutil.cnf

‘web2c files’

glyphlist.txt

‘map’

mktex.cnf

‘web2c files’

pdfglyphlist.txt

‘map’

pdftex.cfg

‘pdftex config’ (although pdftex.cfg is not used any more; look for the file pdftexconfig.tex instead.)

texmf.cnf

‘cnf’

XDvi

‘other text files’

A user-specified format will override the above defaults.

Another useful configuration file in this regard is tcfmgr.map, found in texmf/texconfig/tcfmgr.map, which records various information about the above configuration files (among others).

5.6.3 Auxiliary tasks

Kpsewhich provides some features in addition to path lookup as such:

‘--debug=num’ ¶

Set debugging options to num. See Debugging.

‘--expand-braces=string’ ¶

Output variable, tilde, and brace expansion of string, which is assumed to be a single path element. See Path expansion.

‘--expand-path=string’ ¶

Output the complete expansion of string, with each element separated by the usual path separator on the current system (‘;’ on Windows, ‘:’ 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 ‘--show-path’.

Nonexistent directories are culled from the output:

$ kpsewhich --expand-path '/tmp'
⇒ /tmp
$ kpsewhich --expand-path '/nonesuch'
⇒

For one-shot uses of an arbitrary (not built in to Kpathsea) path, see ‘--path’ (see Path searching options).

‘--expand-var=string’ ¶

Output the variable and tilde expansion of string. For example, with the usual texmf.cnf, ‘kpsewhich --expand-var='$TEXMF'’ returns the TeX system hierarchy root(s). See Path expansion. The specified string can contain anything, though, not just variable references. This calls kpse_var_expand (see Programming with config files).

‘--help-formats’ ¶

Output information about each supported format (see Supported file formats), including the names and abbreviations, variables looked for, and the original path.

‘--safe-in-name=name’ ¶

‘--safe-out-name=name’

Exit successfully if 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 (see Calling sequence).

‘--show-path=name’ ¶

Show the path that would be used for file lookups of file type name. Either a filename extension (‘pk’, ‘.vf’, etc.) or an integer can be used, just as with ‘--format’, described in the previous section.

‘--var-brace-value=variable’ ¶

Like ‘--var-value’ (next), but also expands ‘{...}’ constructs. (see Brace expansion). Thus, the value is assumed to possibly be several path elements, and ‘~’ is expanded at the beginning of each. The path separator is changed to that of the current system in the expansion.

Example: ‘FOO='.;~' kpsewhich --var-brace-value=FOO’ outputs (on a Unix-ish system) ‘.:/home/karl’, supposing the latter is the current user’s home directory. Note that the ‘;’ in the source value, as commonly used in texmf.cnf, has changed to a ‘:’, as the normal path separator on the current system. On a Windows-ish system, the ‘;’ would remain.

‘--var-value=variable’ ¶

Outputs the value of variable (a simple identifier like ‘TEXMFDIST’, with no ‘$’ or other constructs), expanding ‘$’ (see Variable expansion) and ‘~’ (see Tilde expansion) constructs in the value. ‘~’ 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: ‘--var-value=texmf_casefold_search’ outputs (if the default is not changed) ‘1’.

Example to contrast with ‘--var-brace-value’: ‘FOO='.;~' kpsewhich --var-value=FOO’ outputs ‘.;~’, i.e., the same as the input value, on all systems.

5.6.4 Standard options

Kpsewhich accepts the standard GNU options:

• ‘--help’ prints a help message on standard output and exits successfully.
• ‘--version’ prints the Kpathsea version number and exits successfully.

6.3.1 Basic glyph lookup

When Kpathsea looks for a bitmap font name at resolution dpi in a format format, it first checks each directory in the search path for a file ‘name.dpiformat’; for example, ‘cmr10.600pk’. Kpathsea looks for a PK file first, then a GF file.

If that fails, Kpathsea looks for ‘dpidpi/name.format’; for example, ‘dpi600/cmr10.pk’. This is how fonts are typically stored on filesystems (such as DOS) that permit only three-character extensions.

If that fails, Kpathsea looks for a font with a close-enough dpi. “Close enough” is defined by the macro KPSE_BITMAP_TOLERANCE in kpathsea/tex-glyph.h to be dpi / 500 + 1. This is slightly more than the 0.2% minimum allowed by the DVI standard (CTAN:/dviware/driv-standard/level-0).

6.3.2 Fontmap

If a bitmap font or metric file is not found with the original name (see the previous section), Kpathsea looks through any fontmap files for an alias for the original font name. These files are named texfonts.map and searched for along the TEXFONTMAPS environment/config file variable. All texfonts.map files that are found are read; earlier definitions override later ones.

This feature is intended to help in two respects:

1. An alias name is limited in length only by available memory, not by your filesystem. Therefore, if you want to ask for ‘Times-Roman’ instead of ptmr, you can (you get ‘ptmr8r’).
2. A few fonts have historically had multiple names: specifically, LaTeX’s “circle font” has variously been known as circle10, lcircle10, and 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.

The format of fontmap files:

• Comments start with the last ‘%’ on a line and continue to the end of the line. (This provides for names that include a %, ill-advised as that may be.)
• Blank lines are ignored.
• Each nonblank line is broken up into a series of words: a sequence of non-whitespace characters.
• If the first word is ‘include’, the second word is used as a filename, and it is searched for and read.
• Otherwise, the first word on each line is the true filename;
• the second word is the alias;
• subsequent words are ignored.

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 ‘foo.tfm’ matches only when foo.tfm is being searched for; but an alias ‘foo’ matches foo.vf, foo.600pk, etc.

As an example, here is an excerpt from the texfonts.map in the Web2c distribution. It makes the old and new names of the LaTeX circle fonts equivalent.

circle10        lcircle10
circle10        lcirc10
lcircle10       circle10
lcircle10       lcirc10
lcirc10         circle10
lcirc10         lcircle10
…

Fontmaps are implemented in the file kpathsea/fontmap.c. The Fontname distribution has much more information on font naming (see Filenames for TeX fonts).

6.3.3 Fallback font

If a bitmap font cannot be found or created at the requested size, Kpathsea looks for the font at a set of 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., DVIPSSIZES for Dvipsk), then the environment variable TEXSIZES, then a default specified at compilation time (the Make variable default_texsizes). You can set this list to be empty if you prefer to find fonts at their stated size or not at all.

Finally, if the font cannot be found even at the fallback resolutions, Kpathsea looks for a fallback font, typically cmr10. Programs must enable this feature by calling kpathsea_init_prog (see Calling sequence); the default is no fallback font.

6.5.1 mktex configuration

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 configure options specifying otherwise, everything but mktextex will be enabled by default. The configure options to change the defaults are:

--without-mktexfmt-default
--without-mktexmf-default
--without-mktexocp-default
--without-mktexofm-default
--without-mktexpk-default
--without-mktextfm-default
--with-mktextex-default

The configure setting is overridden if the environment variable or configuration file value named for the script is set; e.g., MKTEXPK (see mktex script arguments).

mktexfmt reads a file fmtutil.cnf, typically located in 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.

As distributed, all the scripts source a file texmf/web2c/mktex.cnf if it exists, so you can override various defaults. See 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 mktex.cnf with the appropriate definitions (you do not need to create it if you have nothing to put in it). mktex.cnf has no special syntax; it’s an arbitrary Bourne shell script. The distribution contains a sample mktex.cnf for you to copy and modify as you please (it is not installed anywhere).

In addition, you can configure a number of features with the MT_FEATURES variable, which you can define:

• in mktex.opt, as just mentioned;
• by editing the file mktex.opt, either before ‘make install’ (in the source hierarchy) or after (in the installed hierarchy);
• or in the environment.

If none of the options below are enabled, mktexpk, mktextfm, and 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 ‘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 SYSTEXMF). If so, the VARTEXFONTS tree is used. In all other cases the working directory is used.

The ‘appendonlydir’ option is enabled by default.

‘appendonlydir’ ¶

Tell mktexdir to create directories append-only, i.e., set their sticky bit (see Mode Structure in 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.

‘dosnames’ ¶

Use 8.3 names; e.g., dpi600/cmr10.pk instead of cmr10.600pk. Note that this feature only affects filenames that would otherwise clash with other TeX-related filenames; 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, cmr10.600pk would clash with cmr10.600gf and is therefore changed when ‘dosnames’ is in effect, but mf.pool and 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 ‘dosnames’ to be set on an MS-DOS platform, you need to set the MT_FEATURES environment variable to a value that doesn’t include ‘dosnames’. You can also change the default setting by editing mktex.opt, but only if you use the mktex shell scripts; the emulation programs don’t consult mktex.opt.

‘fontmaps’ ¶

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. (see Introduction in Fontname).

‘nomfdrivers’ ¶

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.

‘nomode’ ¶

Omit the directory level for the mode name; this is fine as long as you generate fonts for only one mode.

‘stripsupplier’ ¶

Omit the font supplier name directory level.

‘striptypeface’ ¶

Omit the font typeface name directory level.

‘strip’ ¶

Omit the font supplier and typeface name directory levels. This feature is deprecated in favour of ‘stripsupplier’ and ‘striptypeface’.

‘varfonts’ ¶

When this option is enabled, fonts that would otherwise be written in system texmf tree go to the VARTEXFONTS tree instead. The default value in kpathsea/Makefile.in is /var/tmp/texfonts. The Linux File System Standard recommends /var/tex/fonts.

The ‘varfonts’ setting in MT_FEATURES is overridden by the USE_VARTEXFONTS environment variable: if set to ‘1’, the feature is enabled, and if set to ‘0’, the feature is disabled.

‘texmfvar’ ¶

Force generated files that would go into a system tree (as defined by SYSTEXMF) into TEXMFVAR. Starting with teTeX-3.0, the variable TEXMFVAR is always set. The ‘varfonts’ feature takes precedence if also set.

The ‘texmfvar’ setting in MT_FEATURES is overridden by the USE_TEXMFVAR environment variable: if set to ‘1’, the feature is enabled, and if set to ‘0’, the feature is disabled.

6.5.2 mktex script names

The following table shows the default name of the script for each of the file types which support runtime generation.

mktexfmt ¶

(‘.fmt’, ‘.base’, ‘.mem’) TeX/Metafont/MetaPost formats. This script is also named fmtutil, and reads fmtutil.cnf for configuration information.

mktexmf ¶

(‘.mf’) Metafont input files.

mkocp ¶

(‘.ocp’) Omega compiled process files.

mkofm ¶

(‘.ofm’) Omega font metric files.

mktexpk ¶

(‘pk’) Glyph fonts.

mktextex ¶

(‘.tex’) TeX input files (disabled by default).

mktextfm ¶

(‘.tfm’) TFM files.

These names can be overridden by an environment variable specific to the program—for example, DVIPSMAKEPK for Dvipsk.

If a mktex… script fails, the invocation is appended to a 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.

If the current directory is not writable and the environment variable or configuration file value TEXMFOUTPUT is set, its value is used. Otherwise, nothing is written. The name ‘missfont.log’ is overridden by the MISSFONT_LOG environment variable or configuration file value.

6.5.3 mktex script arguments

The first argument to a mktex script is always the name of the file to be created.

In the default mktexpk implementation, additional arguments may also be passed:

‘--dpi num’

Sets the resolution of the generated font to num.

‘--mfmode name’

Sets the Metafont mode to name.

‘--bdpi num’

Sets the “base dpi” for the font. This must match the mode being used.

‘--mag string’

A “magstep” string suitable for the Metafont mag variable. This must match the combination of bdpi and dpi being used.

‘--destdir 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.

8.5.1 Unable to find files

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. See Debugging.

• Perhaps you simply haven’t installed all the necessary files; the basic fonts and input files are distributed separately from the programs. See unixtex.ftp: Obtaining TeX.
• 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 texmf.cnf (see Supported file formats). System /etc/profile or other files such may be the culprit.
• Your files reside in a directory that is only pointed to via a symbolic link, in a leaf directory and is not listed in ls-R.

  Unfortunately, Kpathsea’s subdirectory searching has an irremediable deficiency: If a directory d being searched for subdirectories contains plain files and symbolic links to other directories, but no true subdirectories, d will be considered a leaf directory, i.e., the symbolic links will not be followed. See Subdirectory expansion.

  You can work around this problem by creating an empty dummy subdirectory in d. Then d will no longer be a leaf, and the symlinks will be followed.

  The directory immediately followed by the ‘//’ 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.

• If the fonts (or whatever) don’t already exist, mktexpk (or mktexmf or mktextfm) will try to create them. If these rather complicated shell scripts fail, you’ll eventually get an error message saying something like ‘Can't find font fontname’. The best solution is to fix (or at least report) the bug in mktexpk; the workaround is to generate the necessary fonts by hand with Metafont, or to grab them from a CTAN site (see unixtex.ftp: Obtaining TeX).
• There is a bug in the library. See Reporting bugs.

8.5.2 Slow path searching

If your program takes an excessively long time to find fonts or other input files, but does eventually succeed, here are some possible culprits:

• 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 ls-R file that lists all the files in your main TeX hierarchy. See Filename database (ls-R). Kpathsea always uses ls-R if it’s present; there’s no need to recompile or reconfigure any of the programs.
• Your recursively-searched directories (e.g., /usr/local/share/texmf/fonts//), contain a mixture of files and directories. This prevents Kpathsea from using a useful optimization (see Subdirectory expansion).

  It is best to have only directories (and perhaps a README) in the upper levels of the directory structure, and it’s very important to have only files, and no subdirectories, in the leaf directories where the dozens of TFM, PK, or whatever files reside.

In any case, you may find the debugging options helpful in determining precisely when the disk or network is being pounded. See Debugging.

8.5.3 Unable to generate fonts

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.

If mktexpk runs, but fails with this error:

mktexpk: Can't guess mode for nnn dpi devices.
mktexpk: Use a config file to specify the mode, or update me.

you need to ensure the resolution and mode match; just specifying the resolution, as in -D 360, is not enough.

You can specify the mode name with the -mode option on the Dvips command line, or in a Dvips configuration file (see Config files in Dvips), such as config.ps in your document directory, ~/.dvipsrc in your home directory, or in a system directory (again named config.ps). (Other drivers use other files, naturally.)

For example, if you need 360dpi fonts, you could include this in a configuration file:

D 360
M lqmed

If Metafont runs, but generates fonts at the wrong resolution or for the wrong device, most likely mktexpk’s built-in guess for the mode is wrong, and you should override it as above.

See https://ctan.org/pkg/modes for a list of resolutions and mode names for most devices (additional submissions are welcome).

If Metafont runs but generates fonts at a resolution of 2602dpi (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 proof mode, instead of an actual device mode.) To make a proper plain.base, assuming the local mode definitions are contained in a file modes.mf, run the following command (assuming Unix):

inimf "plain; input modes; dump"

Then copy the plain.base file from the current directory to where the base files are stored on your system (/usr/local/share/texmf/web2c by default), and make a link (either hard or soft) from plain.base to mf.base in that directory. See inimf invocation in Web2c.

If mf is a command not found at all by mktexpk, then you need to install Metafont (see unixtex.ftp: Obtaining TeX).

8.5.4 TeX or Metafont failing

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.

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.

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 Bugs in Using and Porting GNU CC.

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.