phpman > info > kpsewhich(1)

File: kpathsea.info,  Node: Invoking kpsewhich,  Prev: Filename database,  Up: Path searching

5.6 'kpsewhich': 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 'find' program to locate files in your TeX hierarchies, perhaps
in administrative scripts.  It is used heavily in the distributed
'mktex...' scripts.

   Synopsis:

     kpsewhich OPTION... FILENAME...

   The options and filename(s) to look up can be intermixed.  Options
can start with either '-' or '--', 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::            '--help' and '--version'.

File: kpathsea.info,  Node: Path searching options,  Next: Specially-recognized files,  Up: Invoking kpsewhich

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 (*note 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 (*note Config files::), overriding settings in the actual
     configuration files, and also in the environment (*note 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.  *Note 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'.  *Note 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.  *Note 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 (*note 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 (*note 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'.

File: kpathsea.info,  Node: Specially-recognized files,  Next: Auxiliary tasks,  Prev: Path searching options,  Up: Invoking kpsewhich

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

File: kpathsea.info,  Node: Auxiliary tasks,  Next: Standard options,  Prev: Specially-recognized files,  Up: Invoking kpsewhich

5.6.3 Auxiliary tasks

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

'--debug=NUM'
     Set debugging options to NUM.  *Note Debugging::.

'--expand-braces=STRING'
     Output variable, tilde, and brace expansion of STRING, which is
     assumed to be a single path element.  *Note 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' (*note 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).  *Note Path expansion::.
     The specified STRING can contain anything, though, not just
     variable references.  This calls 'kpse_var_expand' (*note
     Programming with config files::).

'--help-formats'
     Output information about each supported format (*note 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
     (*note 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.
     (*note 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 '$' (*note
     Variable expansion::) and '~' (*note 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.

File: kpathsea.info,  Node: Standard options,  Prev: Auxiliary tasks,  Up: Invoking kpsewhich

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.