kpathsea: Path searching options
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 (⇒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 (⇒Config files), overriding settings in the actual
configuration files, and also in the environment (⇒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. ⇒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
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'. ⇒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. ⇒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 (⇒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 (⇒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'.
Info Catalog
kpathsea: Invoking kpsewhich
kpathsea: Specially-recognized files