diff options
| -rw-r--r-- | Build/source/texk/kpathsea/ChangeLog | 6 | ||||
| -rw-r--r-- | Build/source/texk/kpathsea/doc/bugs.texi | 33 | ||||
| -rw-r--r-- | Build/source/texk/kpathsea/doc/kpathsea.info | 446 | ||||
| -rw-r--r-- | Build/source/texk/kpathsea/doc/kpathsea.texi | 154 |
4 files changed, 324 insertions, 315 deletions
diff --git a/Build/source/texk/kpathsea/ChangeLog b/Build/source/texk/kpathsea/ChangeLog index 66970cd166f..0ad534e6cca 100644 --- a/Build/source/texk/kpathsea/ChangeLog +++ b/Build/source/texk/kpathsea/ChangeLog @@ -1,3 +1,9 @@ +2009-04-05 Taco Hoekwater <taco@elvenkind.com> + + * doc/kpathsea.texi, + * doc/bugs.texi: updates for new reentrant API, mostly for + kpse->debug replacing the global kpathsea_debug. + 2009-04-02 Peter Breitenlohner <peb@mppmu.mpg.de> * config.h: For __MINGW32__ temporarily define eof as macro diff --git a/Build/source/texk/kpathsea/doc/bugs.texi b/Build/source/texk/kpathsea/doc/bugs.texi index 4ec2d560a57..c02e2d3ae5a 100644 --- a/Build/source/texk/kpathsea/doc/bugs.texi +++ b/Build/source/texk/kpathsea/doc/bugs.texi @@ -13,10 +13,10 @@ (A copy of this chapter is in the file @file{kpathsea/BUGS}.) @end ifset -@flindex tex-k@@mail.tug.org @r{(bug address)} +@flindex tex-k@@tug.org @r{(bug address)} @cindex bug address If you have problems or suggestions, please report them to -@email{tex-k@@mail.tug.org} using the bug checklist below. +@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, @@ -41,7 +41,7 @@ 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@@mail.tug.org}. +@email{tex-k@@tug.org}. The general principle is that a good bug report includes all the information necessary for reproduction. Therefore, to enable @@ -139,9 +139,9 @@ diagnosing, or fixing the bug. @cindex announcement mailing list Web2c and Kpathsea in general are discussed on the mailing list -@email{tex-k@@mail.tug.org}. -@flindex tex-k-request@@mail.tug.org -To join, email @email{tex-k-request@@mail.tug.org} with a line +@email{tex-k@@tug.org}. +@flindex tex-k-request@@tug.org +To join, email @email{tex-k-request@@tug.org} with a line consisting of @example @@ -160,12 +160,6 @@ read some of the archives from @url{ftp://ftp.tug.org/mail/archives/tex-k/}. Be aware that large data files are sometimes included in bug reports. If this is a problem for you, do not join the list. -@flindex tex-archive@@math.utah.edu -@cindex announcement mailing list -If you only want announcements of new releases, not bug reports and -discussion, join @email{tex-archive@@math.utah.edu} (via mail to -@email{tex-archive-request@@math.utah.edu}). - @cindex @TeX{} help mailing list @cindex La@TeX{} help mailing list @cindex Usenet @TeX{} newsgroup @@ -173,10 +167,11 @@ discussion, join @email{tex-archive@@math.utah.edu} (via mail to @cindex help, mailing list for general @TeX{} @flindex info-tex@@shsu.edu @flindex comp.text.tex -If you are looking for general @TeX{} help, such as how to use La@TeX{}, -please use the mailing list @email{info-tex@@shsu.edu} mailing list, -which is gatewayed to the @samp{comp.text.tex} Usenet newsgroup (or post -to the newsgroup; the gateway is bidirectional). +If you are looking for general @TeX{} help, such as how to use +@LaTeX{}, please use the mailing list @email{texhax@@tug.org} mailing +list (@url{http://lists.tug.org/texhax}) which is gatewayed to the +@samp{comp.text.tex} Usenet newsgroup (or post to the newsgroup; the +gateway is bidirectional). @node Debugging @@ -186,7 +181,7 @@ to the newsgroup; the gateway is bidirectional). @cindex runtime debugging @cindex options for debugging -@vindex kpathsea_debug +@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 @@ -201,10 +196,10 @@ first, for maximal output. Dvipsk and Xdvik have additional program-specific debugging options as well. @vindex KPATHSEA_DEBUG -@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 variable @code{kpathsea_debug}, also use the numbers +debugger and set the instance variable @code{kpse->debug}, also use the numbers below. @kindex -1 @r{debugging value} diff --git a/Build/source/texk/kpathsea/doc/kpathsea.info b/Build/source/texk/kpathsea/doc/kpathsea.info index 52e8fdc336f..486f8181266 100644 --- a/Build/source/texk/kpathsea/doc/kpathsea.info +++ b/Build/source/texk/kpathsea/doc/kpathsea.info @@ -1,10 +1,10 @@ -This is kpathsea.info, produced by makeinfo version 4.12 from +This is kpathsea.info, produced by makeinfo version 4.13 from kpathsea.texi. This file documents the Kpathsea library for path searching. Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, -2005, 2007, 2008 Karl Berry & Olaf Weber. +2005, 2007, 2008, 2009 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 @@ -18,7 +18,7 @@ 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 Free Software Foundation. +translation approved by the TeX Users Group. INFO-DIR-SECTION TeX START-INFO-DIR-ENTRY @@ -39,8 +39,8 @@ Kpathsea library **************** This manual documents how to install and use the Kpathsea library for -filename lookup. It corresponds to version 3.5.7, released in -July 2008. +filename lookup. It corresponds to version 5.0.0, released in +April 2009. * Menu: @@ -60,8 +60,8 @@ File: kpathsea.info, Node: Introduction, Next: Installation, Prev: Top, Up: 1 Introduction ************** -This manual corresponds to version 3.5.7 of the Kpathsea library, -released in July 2008. +This manual corresponds to version 5.0.0 of the Kpathsea library, +released in April 2009. The library's fundamental purpose is to return a filename from a list of directories specified by the user, similar to what shells do @@ -95,18 +95,10 @@ will. See the files `GPL' and `LGPL' for the text of the GNU licenses. 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, great!). TUG produces the periodical +you're already a member, thanks!). TUG produces the periodical `TUGboat', sponsors an annual meeting and publishes the proceedings, and arranges courses on TeX for all levels of users throughout the -world. Anyway, here is the address: - - TeX Users Group - P.O. Box 2311 - Portland OR 97208-2311 - USA - phone: +1 503 223-9994 - fax: +1 503 223-3960 - email: <tug@tug.org> +world. See `http://tug.org' for information. * Menu: @@ -1560,8 +1552,8 @@ program-specific debugging options as well. You can also set the environment variable `KPATHSEA_DEBUG'; in this case, you should use the numbers below. If you run the program under a -debugger and set the variable `kpathsea_debug', also use the numbers -below. +debugger and set the instance variable `kpse->debug', also use the +numbers below. In any case, by far the simplest value to use is `-1', which will turn on all debugging output. This is usually better than guessing @@ -2441,7 +2433,7 @@ more work. 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 `UNIX_ST_LINK' in + 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: @@ -2884,6 +2876,9 @@ their corresponding format: `texmf.cnf' `cnf' +`XDvi' + `other text files' + A user-specified format will override the above defaults. @@ -3248,7 +3243,7 @@ tried; the difference is the order in which they are tried. *already* have an extension. A name without an extension (e.g., `tex story') will always have an extension added first. - This algorithm is implemented in the routine `kpse_find_file' in + This algorithm is implemented in the routine `kpathsea_find_file' in `kpathsea/tex-file.c'. You can watch it in action with the debugging options (*note Debugging::). @@ -3278,7 +3273,7 @@ first successful lookup. 4. Look for FALLBACK.DPI, where FALLBACK is some last-resort font (typically `cmr10'). - This is implemented in `kpse_find_glyph_format' in + This is implemented in `kpathsea_find_glyph' in `kpathsea/tex-glyph.c'. * Menu: @@ -3396,9 +3391,8 @@ 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 assigning to the global variable -`kpse_fallback_font' or calling `kpse_init_prog' (*note Calling -sequence::); the default is no fallback font. +Programs must enable this feature by calling `kpathsea_init_prog' +(*note Calling sequence::); the default is no fallback font. File: kpathsea.info, Node: Suppressing warnings, Prev: Glyph lookup, Up: TeX support @@ -3459,16 +3453,24 @@ File: kpathsea.info, Node: Programming overview, Next: Calling sequence, Up: 5.1 Programming overview ======================== -Aside from this manual, your best source of information is the source to -the programs I've modified to use Kpathsea (*note Introduction::). Of -those, Dviljk is probably the simplest, and hence a good place to start. +Aside from this manual, your best source of information is the source +to the programs that use Kpathsea (*note Introduction::). Of those, +Dviljk is probably the simplest, and hence a good place to start. 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. Finally, Kpsewhich is a small -utility program whose sole purpose is to exercise the main +maintain, so it uses Kpathsea rather straightforwardly, but is of +course complicated by the Web to C translation. Finally, Kpsewhich is +a small utility program whose sole purpose is to exercise the main path-searching functionality. + When looking at these program sources, you should know that previous +versions of the library had a different programming interface, to +support re-entrancy. In that interface the library function names were +prefixed with `kpse_' instead of `kpathsea_', and they did not need an +instance variable as first argument. This change was made in 2009. +Some of the programs mentioned above may still be using the previous +interface. + Beyond these examples, the `.h' files in the Kpathsea source describe the interfaces and functionality (and of course the `.c' files define the actual routines, which are the ultimate documentation). @@ -3507,40 +3509,39 @@ File: kpathsea.info, Node: Calling sequence, Next: Program-specific files, Pr The typical way to use Kpathsea in your program goes something like this: - 1. Call `kpse_set_program_name' with `argv[0]' as the first argument; - the second argument is a string or `NULL'. The second argument is - used by Kpathsea as the program name for the `.PROGRAM' feature of - config files (*note Config files::). If the second argument is - `NULL', the value of the first argument is used. This function - must be called before any other use of the Kpathsea library. - - `kpse_set_program_name' always sets the global variables - `program_invocation_name' and `program_invocation_short_name'. - These variables are used in the error message macros defined in - `kpathsea/lib.h'. It sets the global variable `kpse_program_name' - to the program name it uses. + 1. Call `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 `kpse' as a + placeholder for the name of this variable. + + 2. Call `kpathsea_set_program_name' with `argv[0]' as the second + argument; the third argument is a string or `NULL'. The third + argument is used by Kpathsea as the program name for the + `.PROGRAM' feature of config files (*note Config files::). If the + third argument is `NULL', the value of the second argument is + used. This function must be called before any other use of the + Kpathsea library. + + `kpathsea_set_program_name' always sets the variables + `kpse->invocation_name' and `kpse->invocation_short_name'. These + variables are used in the error message macros defined in + `kpathsea/lib.h'. It sets the variable `kpse->program_name' to + the program name it uses. It also initializes debugging options based on the environment variable `KPATHSEA_DEBUG' (if that is set). - Finally, it sets the variables `SELFAUTOLOC', `SELFAUTODIR' and - `SELFAUTOPARENT' to the location, parent and grandparent directory - of the executable, removing `.' and `..' 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 `kpsewhich --expand-var=\$SELFAUTOLOC', etc., to see - the values. - - 2. The `kpse_set_progname' is deprecated. A call to - `kpse_set_progname' with `argv[0]' is equivalent to a call of - `kpse_set_program_name' with first argument `argv[0]' and second - argument `NULL'. The function is deprecated because it cannot - ensure that the `.PROGRAM' feature of config files will always - work (*note Config files::). + Finally, it sets the environment variables `SELFAUTOLOC', + `SELFAUTODIR' and `SELFAUTOPARENT' to the location, parent and + grandparent directory of the executable, removing `.' and `..' 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 `kpsewhich --expand-var=\$SELFAUTOLOC', + etc., to see the values. 3. Set debugging options. *Note Debugging::. If your program doesn't have a debugging option already, you can define one and set - `kpathsea_debug' to the number that the user supplies (as in Dviljk + `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 `KPATHSEA_DEBUG'). If you do have runtime debugging already, you need to merge Kpathsea's options with yours (as in @@ -3548,12 +3549,12 @@ this: 4. If your program has its own configuration files that can define search paths, you should assign those paths to the `client_path' - member in the appropriate element of the `kpse_format_info' array. - (This array is indexed by file type; see `tex-file.h'.) See - `resident.c' in Dvipsk for an example. + member in the appropriate element of the `kpse->format_info' + array. (This array is indexed by file type; see `tex-file.h'.) + See `resident.c' in Dvipsk for an example. - 5. Call `kpse_init_prog' (see `proginit.c'). It's useful for the DVI - drivers, at least, but for other programs it may be simpler to + 5. Call `kpathsea_init_prog' (see `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 @@ -3562,26 +3563,28 @@ this: the BibTeX search paths in a DVI driver.) 6. The routine to actually find a file of type FORMAT is - `kpse_find_FORMAT', defined in `tex-file.h'. These are macros that - expand to a call to `kpse_find_file'. You can call, say, - `kpse_find_tfm' after doing only the first of the initialization - steps above--Kpathsea automatically reads the `texmf.cnf' generic - config files, looks for environment variables, and does expansions - at the first lookup. - - 7. To find PK and/or GF bitmap fonts, the routines are `kpse_find_pk', - `kpse_find_gf' and `kpse_find_glyph', defined in `tex-glyph.h'. - These return a structure in addition to the resultant filename, - because fonts can be found in so many ways. See the documentation - in the source. + `kpathsea_find_file'. You can call `kpathsea_find_file' after + doing only the first and second of the initialization steps + above--Kpathsea automatically reads the `texmf.cnf' generic config + files, looks for environment variables, and does expansions at the + first lookup. + + 7. To find PK and/or GF bitmap fonts, the routine is + `kpathsea_find_glyph', defined in `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. 8. To actually open a file, not just return a filename, call - `kpse_open_file'. This function takes the name to look up and a - Kpathsea file format as arguments, and returns the usual `FILE *'. - It always assumes the file must exist, and thus will search the - disk if necessary (unless the search path specified `!!', etc.). - In other words, if you are looking up a VF or some other file that - need not exist, don't use this. + `kpathsea_open_file'. This function takes the name to look up and + a Kpathsea file format as arguments, and returns the usual `FILE + *'. It always assumes the file must exist, and thus will search + the disk if necessary (unless the search path specified `!!', + etc.). In other words, if you are looking up a VF or some other + file that need not exist, don't use this. + + 9. To close the kpathsea library instance you are using, call + `kpathsea_finish'. This function closes any open log files and + frees the memory used by the instance. Kpathsea also provides many utility routines. Some are generic: hash @@ -3617,7 +3620,8 @@ That is to say, the name of the variable is constructed by converting the name of the program to upper case, and appending `INPUTS'. The only difference between these two formats is whether -`kpse_open_file' will open the files it finds in text or binary mode. +`kpathsea_open_file' will open the files it finds in text or binary +mode. File: kpathsea.info, Node: Programming with config files, Prev: Program-specific files, Up: Programming @@ -3630,22 +3634,22 @@ file that Kpathsea uses for your program. This helps installers by keeping all configuration in one place. To retrieve a value VAR from config files, the best way is to call -`kpse_var_value' on the string `VAR'. This will look first for an +`kpathsea_var_value' on the string `VAR'. This will look first for an environment variable VAR, then a config file value. The result will be the value found or `NULL'. This function is declared in `kpathsea/variable.h'. For an example, see the `shell_escape' code in `web2c/lib/texmfmp.c'. The routine to do variable expansion in the context of a search path -(as opposed to simply retrieving a value) is `kpse_var_expand', also +(as opposed to simply retrieving a value) is `kpathsea_var_expand', also declared in `kpathsea/variable.h'. It's generally only necessary to set the search path structure components as explained in the previous section, rather than using this yourself. If for some reason you want to retrieve a value _only_ from a config file, not automatically looking for a corresponding environment -variable, call `kpse_cnf_get' (declared in `kpathsea/cnf.h') with the -string VAR. +variable, call `kpathsea_cnf_get' (declared in `kpathsea/cnf.h') with +the string VAR. No initialization calls are needed. @@ -3839,6 +3843,8 @@ Index * announcement mailing list: Mailing lists. (line 6) * ANSI C: TeX or Metafont failing. (line 30) +* API, re-entrant: Programming overview. + (line 16) * append-only directories and mktexpk: Security. (line 36) * appendonlydir: mktex configuration. (line 61) * architecture-(in)dependent files, installing only: Installing files. @@ -3846,9 +3852,9 @@ Index * architectures, compiling multiple: configure scenarios. (line 18) * arguments to mktex: mktex script arguments. (line 6) -* argv[0]: Calling sequence. (line 9) +* argv[0]: Calling sequence. (line 14) * ash, losing with configure: configure shells. (line 19) -* autoconf, recommended: Calling sequence. (line 93) +* autoconf, recommended: Calling sequence. (line 94) * automounter, and configuration: configure scenarios. (line 29) * automounter, and ls-R: ls-R. (line 40) * auxiliary tasks: Auxiliary tasks. (line 6) @@ -3876,9 +3882,9 @@ Index * bug checklist: Bug checklist. (line 6) * bug mailing list: Mailing lists. (line 6) * bugs, reporting: Reporting bugs. (line 6) -* c-*.h: Calling sequence. (line 93) +* c-*.h: Calling sequence. (line 94) * c-auto.h: Programming overview. - (line 25) + (line 33) * c-auto.in: Running configure. (line 6) * cache of fonts, local: Security. (line 22) * calling sequence: Calling sequence. (line 6) @@ -3897,7 +3903,7 @@ Index (line 16) * circle fonts: Fontmap. (line 19) * clean Make target: Cleaning up. (line 15) -* client_path in kpse_format_info: Calling sequence. (line 48) +* client_path in kpse->format_info: Calling sequence. (line 47) * CMAPFONTS: Supported file formats. (line 36) * cmr10, as fallback font: Fallback font. (line 15) @@ -3929,11 +3935,11 @@ Index * conditions for use: Introduction. (line 31) * config files: Config files. (line 6) * config files, for Kpathsea-using programs: Calling sequence. - (line 48) + (line 47) * config files, programming with: Programming with config files. (line 6) * config.h: Programming overview. - (line 25) + (line 33) * config.log: Bug checklist. (line 28) * config.ps: Specially-recognized files. (line 16) @@ -3972,7 +3978,7 @@ Index * debugger: Bug checklist. (line 62) * debugging: Debugging. (line 6) * debugging options, in Kpathsea-using program: Calling sequence. - (line 40) + (line 39) * debugging output: Debugging. (line 27) * debugging with -g, disabling: configure scenarios. (line 32) * DEC shells and configure: configure shells. (line 25) @@ -4053,10 +4059,10 @@ Index * environment variables, old: Unable to find files. (line 14) * epoch, seconds since: Logging. (line 15) -* error message macros: Calling sequence. (line 16) +* error message macros: Calling sequence. (line 22) * excessive startup time: Slow path searching. (line 6) * expand.c: Brace expansion. (line 26) -* expanding symlinks: Calling sequence. (line 25) +* expanding symlinks: Calling sequence. (line 31) * expansion, default: Default expansion. (line 6) * expansion, path element: Searching overview. (line 43) * expansion, search path: Path expansion. (line 6) @@ -4084,7 +4090,7 @@ Index * file lookup: File lookup. (line 6) * file permissions: Security. (line 47) * file types, registering new: Programming overview. - (line 31) + (line 39) * filename aliases: Filename aliases. (line 6) * filename database: Filename database. (line 6) * filename database generation: Filename database generation. @@ -4145,7 +4151,7 @@ Index * group-writable directories: Security. (line 40) * GSFTOPK_DEBUG (128): Debugging. (line 88) * hash table buckets, printing: Debugging. (line 105) -* hash table routines: Calling sequence. (line 86) +* hash table routines: Calling sequence. (line 87) * hash_summary_only variable for debugging: Debugging. (line 105) * help, mailing list for general TeX: Mailing lists. (line 29) * HIER: Default path features. @@ -4162,7 +4168,7 @@ Index * INDEXSTYLE: Supported file formats. (line 67) * info-tex@shsu.edu: Mailing lists. (line 29) -* input lines, reading: Calling sequence. (line 86) +* input lines, reading: Calling sequence. (line 87) * install-data Make target: Installing files. (line 28) * install-exec Make target: Installing files. (line 23) * installation: Installation. (line 6) @@ -4189,23 +4195,37 @@ Index * Knuth, Donald E., original author: Electronic distribution. (line 25) * Korn shell, losing with configure: configure shells. (line 14) +* kpathsae_var_value: Programming with config files. + (line 10) * Kpathsea config file, source for path: Path sources. (line 17) * Kpathsea version number: Kpathsea application distributions. (line 6) * kpathsea.h: Programming overview. - (line 16) + (line 24) * kpathsea/HIER: Default path features. (line 41) * kpathsea/README.CONFIGURE: Running configure. (line 15) -* KPATHSEA_DEBUG: Calling sequence. (line 22) -* kpathsea_debug: Debugging. (line 18) +* kpathsea_cnf_get: Programming with config files. + (line 23) +* KPATHSEA_DEBUG <1>: Calling sequence. (line 28) * KPATHSEA_DEBUG: Debugging. (line 18) -* kpathsea_debug: Debugging. (line 6) -* kpathsea_debug variable: Calling sequence. (line 40) +* kpathsea_find_file <1>: Calling sequence. (line 62) +* kpathsea_find_file: File lookup. (line 37) +* kpathsea_find_glyph: Glyph lookup. (line 26) +* kpathsea_finish: Calling sequence. (line 82) +* kpathsea_init_prog <1>: Calling sequence. (line 53) +* kpathsea_init_prog: Fallback font. (line 15) +* kpathsea_new: Calling sequence. (line 9) +* kpathsea_open_file: Calling sequence. (line 74) +* kpathsea_set_program_name: Calling sequence. (line 14) * KPATHSEA_WARNING: Config files. (line 18) +* kpse->debug: Debugging. (line 6) +* kpse->debug variable: Calling sequence. (line 39) +* kpse->format_info: Calling sequence. (line 47) +* kpse->invocation_name: Calling sequence. (line 22) +* kpse->invocation_short_name: Calling sequence. (line 22) +* kpse->program_name: Calling sequence. (line 22) * KPSE_BITMAP_TOLERANCE: Basic glyph lookup. (line 15) -* kpse_cnf_get: Programming with config files. - (line 23) * KPSE_DEBUG_EXPAND (16): Debugging. (line 68) * KPSE_DEBUG_FOPEN (4): Debugging. (line 53) * KPSE_DEBUG_HASH (2): Debugging. (line 46) @@ -4214,22 +4234,9 @@ Index * KPSE_DEBUG_STAT (1): Debugging. (line 38) * KPSE_DEBUG_VARS (64): Debugging. (line 83) * KPSE_DOT expansion: KPSE_DOT expansion. (line 6) -* kpse_fallback_font: Fallback font. (line 15) -* kpse_find_*: Calling sequence. (line 63) -* kpse_find_file <1>: Calling sequence. (line 63) -* kpse_find_file: File lookup. (line 37) -* kpse_find_glyph_format: Glyph lookup. (line 26) -* kpse_format_info: Calling sequence. (line 48) * kpse_format_info_type: Debugging. (line 61) -* kpse_init_prog: Calling sequence. (line 54) * kpse_init_prog, and MAKETEX_MODE: Default path features. (line 25) -* kpse_open_file: Calling sequence. (line 77) -* kpse_program_name: Calling sequence. (line 16) -* kpse_set_progname: Calling sequence. (line 33) -* kpse_set_program_name: Calling sequence. (line 9) -* kpse_var_value: Programming with config files. - (line 10) * kpsewhich: Invoking kpsewhich. (line 6) * Kpsewhich, and debugging: Debugging. (line 31) * ksh, losing with configure: configure shells. (line 14) @@ -4256,7 +4263,7 @@ Index * license for using the library: Introduction. (line 31) * LIGFONTS: Supported file formats. (line 71) -* lines, reading arbitrary-length: Calling sequence. (line 86) +* lines, reading arbitrary-length: Calling sequence. (line 87) * Linux File System Standard: mktex configuration. (line 114) * Linux shells and configure: configure shells. (line 19) * Linux, using Web2c: CD-ROM distribution. (line 16) @@ -4292,7 +4299,7 @@ Index * MAKETEX_FINE_DEBUG (1024): Debugging. (line 100) * MAKETEX_MODE: Default path features. (line 19) -* memory allocation routines: Calling sequence. (line 86) +* memory allocation routines: Calling sequence. (line 87) * metafont driver files: mktex configuration. (line 94) * Metafont failures: TeX or Metafont failing. (line 6) @@ -4424,7 +4431,7 @@ Index (line 27) * paths.h, creating: Running make. (line 6) * pathsearch.h: Programming overview. - (line 16) + (line 24) * pc Pascal compiler: History. (line 12) * PCL driver: Kpathsea application distributions. (line 13) @@ -4461,11 +4468,9 @@ Index * problems, common: Common problems. (line 6) * proginit.c: Default path features. (line 25) -* proginit.h: Calling sequence. (line 54) +* proginit.h: Calling sequence. (line 53) * program-varying paths: Supported file formats. (line 12) -* program_invocation_name: Calling sequence. (line 16) -* program_invocation_short_name: Calling sequence. (line 16) * programming overview: Programming overview. (line 6) * programming with config files: Programming with config files. @@ -4478,9 +4483,11 @@ Index (line 145) * pxp Pascal preprocessor: History. (line 12) * quoting variable values: Variable expansion. (line 17) +* re-entrant API: Programming overview. + (line 16) * readable: Suppressing warnings. (line 26) -* reading arbitrary-length lines: Calling sequence. (line 86) +* reading arbitrary-length lines: Calling sequence. (line 87) * README.CONFIGURE: Running configure. (line 15) * README.mirrors: Electronic distribution. (line 13) @@ -4488,7 +4495,7 @@ Index * relative filenames: Searching overview. (line 52) * relative filenames in ls-R: Installing files. (line 40) * reporting bugs: Reporting bugs. (line 6) -* resident.c: Calling sequence. (line 48) +* resident.c: Calling sequence. (line 47) * resolution, setting: Path searching options. (line 17) * resolutions, last-resort: Fallback font. (line 6) @@ -4510,9 +4517,9 @@ Index * searching the disk: Searching overview. (line 22) * security considerations: Security. (line 6) * sed error from configure: Empty Makefiles. (line 6) -* SELFAUTODIR: Calling sequence. (line 25) -* SELFAUTOLOC: Calling sequence. (line 25) -* SELFAUTOPARENT: Calling sequence. (line 25) +* SELFAUTODIR: Calling sequence. (line 31) +* SELFAUTOLOC: Calling sequence. (line 31) +* SELFAUTOPARENT: Calling sequence. (line 31) * sending patches: Bug checklist. (line 56) * setgid scripts: Security. (line 40) * SFDFONTS: Supported file formats. @@ -4538,6 +4545,8 @@ Index (line 30) * st_nlink: Subdirectory expansion. (line 26) +* ST_NLINK_TRICK: Subdirectory expansion. + (line 38) * stack trace: Bug checklist. (line 62) * standalone path searching: Invoking kpsewhich. (line 6) * standard error and debugging output: Debugging. (line 27) @@ -4545,7 +4554,7 @@ Index * startup time, excessive: Slow path searching. (line 6) * static linking: ShellWidgetClass. (line 39) * static linking and dlsym: dlopen. (line 6) -* string routines: Calling sequence. (line 86) +* string routines: Calling sequence. (line 87) * strip: mktex configuration. (line 108) * stripsupplier: mktex configuration. (line 102) * striptypeface: mktex configuration. (line 105) @@ -4565,7 +4574,7 @@ Index * symbolic links not found: Unable to find files. (line 21) * symbolic links, and ls-R: ls-R. (line 38) -* symlinks, resolving: Calling sequence. (line 25) +* symlinks, resolving: Calling sequence. (line 31) * system C compiler bugs: TeX or Metafont failing. (line 19) * system dependencies: Running configure. (line 6) @@ -4577,7 +4586,7 @@ Index * T42FONTS: Supported file formats. (line 189) * tcfmgr.map: Specially-recognized files. - (line 44) + (line 47) * TDS: TeX directory structure. (line 6) * testing, post-installation: Installation testing. @@ -4601,10 +4610,10 @@ Index * tex-archive@math.utah.edu: Mailing lists. (line 25) * tex-file.c: File lookup. (line 37) * tex-file.h: Programming overview. - (line 16) + (line 24) * tex-glyph.c: Glyph lookup. (line 26) * tex-glyph.h: Programming overview. - (line 16) + (line 24) * tex-k-request@mail.tug.org: Mailing lists. (line 7) * tex-k@mail.tug.org (bug address): Reporting bugs. (line 8) * TEX_HUSH <1>: Suppressing warnings. @@ -4687,7 +4696,6 @@ Index * TTFONTS: Supported file formats. (line 181) * tug.org: unixtex.ftp. (line 6) -* tug@tug.org: Introduction. (line 46) * typeface directory, omitting: mktex configuration. (line 106) * ucbinclude, avoiding: Running make. (line 44) * Ultrix shells and configure: configure shells. (line 25) @@ -4697,8 +4705,6 @@ Index (line 6) * uname: Bug checklist. (line 21) * universe, BSD vs. system V: Running make. (line 44) -* UNIX_ST_LINK: Subdirectory expansion. - (line 38) * unixtex.ftp: unixtex.ftp. (line 6) * unknown special warnings: Suppressing warnings. (line 31) @@ -4755,6 +4761,8 @@ Index * XCFLAGS: Running make. (line 26) * XCPPFLAGS: Running make. (line 22) * XDEFS: Running make. (line 23) +* XDvi: Specially-recognized files. + (line 41) * XDVIFONTS: Supported file formats. (line 227) * XDVIMAKEPK: mktex script names. (line 32) @@ -4771,86 +4779,86 @@ Index Tag Table: -Node: Top1552 -Node: Introduction2195 -Node: History4171 -Node: Installation8263 -Node: Simple installation9053 -Node: Custom installation12636 -Node: Disk space13810 -Node: Kpathsea application distributions14694 -Node: Changing search paths15809 -Node: Default path features16991 -Node: Default path generation19127 -Node: Running configure20570 -Node: configure shells21621 -Node: configure options22673 -Node: configure environment24180 -Node: configure scenarios25982 -Node: Shared library27568 -Node: Running make28582 -Node: Installing files30629 -Node: Cleaning up32576 -Node: Filename database generation33624 -Node: mktex scripts34191 -Node: mktex configuration35468 -Node: mktex script names41287 -Node: mktex script arguments42678 -Node: Installation testing43568 -Node: Security43932 -Node: TeX directory structure46499 -Node: unixtex.ftp50921 -Node: Electronic distribution52936 -Node: CD-ROM distribution55701 -Node: Other TeX packages56671 -Node: Reporting bugs57967 -Node: Bug checklist58707 -Node: Mailing lists62409 -Node: Debugging63768 -Node: Logging68840 -Node: Common problems70710 -Node: Unable to find files71541 -Node: Slow path searching73952 -Node: Unable to generate fonts75329 -Node: TeX or Metafont failing77838 -Node: Empty Makefiles79716 -Node: XtStrings80946 -Node: dlopen81782 -Node: ShellWidgetClass82600 -Node: Pointer combination warnings84232 -Node: Path searching84621 -Node: Searching overview85268 -Node: Path sources88664 -Node: Config files89735 -Node: Path expansion93380 -Node: Default expansion94329 -Node: Variable expansion96399 -Node: Tilde expansion97802 -Node: Brace expansion98782 -Node: KPSE_DOT expansion99887 -Node: Subdirectory expansion100400 -Node: Filename database102749 -Node: ls-R103803 -Node: Filename aliases106697 -Node: Database format107875 -Node: Invoking kpsewhich108888 -Node: Path searching options109833 -Node: Specially-recognized files116853 -Node: Auxiliary tasks118177 -Node: Standard options120002 -Node: TeX support120322 -Node: Supported file formats121613 -Node: File lookup128761 -Node: Glyph lookup130489 -Node: Basic glyph lookup131616 -Node: Fontmap132495 -Node: Fallback font135112 -Node: Suppressing warnings136077 -Node: Programming137182 -Node: Programming overview137695 -Node: Calling sequence139971 -Node: Program-specific files144963 -Node: Programming with config files146001 -Node: Index147301 +Node: Top1549 +Node: Introduction2193 +Node: History4020 +Node: Installation8112 +Node: Simple installation8902 +Node: Custom installation12485 +Node: Disk space13659 +Node: Kpathsea application distributions14543 +Node: Changing search paths15658 +Node: Default path features16840 +Node: Default path generation18976 +Node: Running configure20419 +Node: configure shells21470 +Node: configure options22522 +Node: configure environment24029 +Node: configure scenarios25831 +Node: Shared library27417 +Node: Running make28431 +Node: Installing files30478 +Node: Cleaning up32425 +Node: Filename database generation33473 +Node: mktex scripts34040 +Node: mktex configuration35317 +Node: mktex script names41136 +Node: mktex script arguments42527 +Node: Installation testing43417 +Node: Security43781 +Node: TeX directory structure46348 +Node: unixtex.ftp50770 +Node: Electronic distribution52785 +Node: CD-ROM distribution55550 +Node: Other TeX packages56520 +Node: Reporting bugs57816 +Node: Bug checklist58556 +Node: Mailing lists62258 +Node: Debugging63617 +Node: Logging68695 +Node: Common problems70565 +Node: Unable to find files71396 +Node: Slow path searching73807 +Node: Unable to generate fonts75184 +Node: TeX or Metafont failing77693 +Node: Empty Makefiles79571 +Node: XtStrings80801 +Node: dlopen81637 +Node: ShellWidgetClass82455 +Node: Pointer combination warnings84087 +Node: Path searching84476 +Node: Searching overview85123 +Node: Path sources88519 +Node: Config files89590 +Node: Path expansion93235 +Node: Default expansion94184 +Node: Variable expansion96254 +Node: Tilde expansion97657 +Node: Brace expansion98637 +Node: KPSE_DOT expansion99742 +Node: Subdirectory expansion100255 +Node: Filename database102606 +Node: ls-R103660 +Node: Filename aliases106554 +Node: Database format107732 +Node: Invoking kpsewhich108745 +Node: Path searching options109690 +Node: Specially-recognized files116710 +Node: Auxiliary tasks118066 +Node: Standard options119891 +Node: TeX support120211 +Node: Supported file formats121502 +Node: File lookup128650 +Node: Glyph lookup130382 +Node: Basic glyph lookup131506 +Node: Fontmap132385 +Node: Fallback font135002 +Node: Suppressing warnings135915 +Node: Programming137020 +Node: Programming overview137533 +Node: Calling sequence140227 +Node: Program-specific files145195 +Node: Programming with config files146237 +Node: Index147549 End Tag Table diff --git a/Build/source/texk/kpathsea/doc/kpathsea.texi b/Build/source/texk/kpathsea/doc/kpathsea.texi index c33aeb7aefe..2c6df84b161 100644 --- a/Build/source/texk/kpathsea/doc/kpathsea.texi +++ b/Build/source/texk/kpathsea/doc/kpathsea.texi @@ -2,14 +2,14 @@ @setfilename kpathsea.info @settitle Kpathsea: A library for path searching -@set version 3.5.7 -@set month-year July 2008 +@set version 5.0.0 +@set month-year April 2009 @copying This file documents the Kpathsea library for path searching. Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, -2004, 2005, 2007, 2008 Karl Berry & Olaf Weber. +2004, 2005, 2007, 2008, 2009 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 @@ -30,7 +30,7 @@ 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 Free Software Foundation. +approved by the TeX Users Group. @end copying @c Define new indices for commands, filenames, and options. @@ -67,6 +67,7 @@ approved by the Free Software Foundation. @subtitle @value{month-year} @author Karl Berry (@email{kb@@mail.tug.org}) @author Olaf Weber (@email{infovore@@xs4all.nl}) +@author Taco Hoekwater (@email{taco@@luatex.org}) @page @vskip 0pt plus 1filll @@ -148,21 +149,10 @@ the source to your program, although we hope you will. See the files @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, great!). TUG produces the periodical +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. Anyway, here is the address: - -@flindex tug@@tug.org -@display -@TeX{} Users Group -P.O. Box 2311 -Portland OR 97208-2311 -USA -phone: +1 503 223-9994 -fax: +1 503 223-3960 -email: @email{tug@@tug.org} -@end display +throughout the world. See @url{http://tug.org} for information. @menu * History:: @@ -1943,8 +1933,8 @@ 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 kpse_find_file -This algorithm is implemented in the routine @code{kpse_find_file} in +@findex kpathsea_find_file +This algorithm is implemented in the routine @code{kpathsea_find_file} in @file{kpathsea/tex-file.c}. You can watch it in action with the debugging options (@pxref{Debugging}). @@ -1980,8 +1970,8 @@ last-resort font (typically @samp{cmr10}). @end enumerate @flindex tex-glyph.c -@findex kpse_find_glyph_format -This is implemented in @code{kpse_find_glyph_format} in +@findex kpathsea_find_glyph +This is implemented in @code{kpathsea_find_glyph} in @file{kpathsea/tex-glyph.c}. @menu @@ -2124,11 +2114,10 @@ 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} -@vindex kpse_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 assigning to the global variable -@code{kpse_fallback_font} or calling @code{kpse_init_prog} +must enable this feature by calling @code{kpathsea_init_prog} (@pxref{Calling sequence}); the default is no fallback font. @@ -2199,16 +2188,26 @@ This chapter is for programmers who wish to use Kpathsea. @cindex programming overview @cindex overview of programming with Kpathsea -Aside from this manual, your best source of information is the source to -the programs I've modified to use Kpathsea (@pxref{Introduction}). Of -those, Dviljk is probably the simplest, and hence a good place to start. -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. Finally, Kpsewhich is a small -utility program whose sole purpose is to exercise the main +Aside from this manual, your best source of information is the source +to the programs that use Kpathsea (@pxref{Introduction}). Of those, +Dviljk is probably the simplest, and hence a good place to start. +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. Finally, Kpsewhich is +a small utility program whose sole purpose is to exercise the main path-searching functionality. +@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, to +support re-entrancy. In that interface 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. Some of the programs mentioned above may still be using +the previous interface. + @flindex pathsearch.h @flindex tex-file.h @flindex tex-glyph.h @@ -2257,25 +2256,32 @@ The typical way to use Kpathsea in your program goes something like this: @enumerate @item -@findex kpse_set_program_name +@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{kpse_set_program_name} with @code{argv[0]} as the first -argument; the second argument is a string or @code{NULL}. The second +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 second argument is @code{NULL}, the value of the first argument +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 program_invocation_name -@vindex program_invocation_short_name -@vindex kpse_program_name +@vindex kpse->invocation_name +@vindex kpse->invocation_short_name +@vindex kpse->program_name @cindex error message macros -@code{kpse_set_program_name} always sets the global variables -@code{program_invocation_name} and @code{program_invocation_short_name}. +@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 global variable -@code{kpse_program_name} to the program name it uses. +@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 @@ -2286,7 +2292,7 @@ variable @code{KPATHSEA_DEBUG} (if that is set). @cindex SELFAUTOPARENT @cindex symlinks, resolving @cindex expanding symlinks -Finally, it sets the variables @code{SELFAUTOLOC}, @code{SELFAUTODIR} +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 @@ -2295,40 +2301,30 @@ can use @samp{kpsewhich --expand-var=\$SELFAUTOLOC}, etc., to see the values. @item -@findex kpse_set_progname -@vindex argv[0] -The @code{kpse_set_progname} is deprecated. A call to -@code{kpse_set_progname} with @code{argv[0]} is equivalent to a call of -@code{kpse_set_program_name} with first argument @code{argv[0]} and -second argument @code{NULL}. The function is deprecated because it -cannot ensure that the @code{.@var{program}} feature of config files -will always work (@pxref{Config files}). - -@item -@vindex kpathsea_debug @r{variable} +@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{kpathsea_debug} to the number that the user supplies (as in Dviljk +@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 +@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 +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 kpse_init_prog +@findex kpathsea_init_prog @flindex proginit.h -Call @code{kpse_init_prog} (see @file{proginit.c}). It's useful for the +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 @@ -2337,33 +2333,37 @@ 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 kpse_find_* -@findex kpse_find_file +@findex kpathsea_find_file The routine to actually find a file of type @var{format} is -@code{kpse_find_@var{format}}, defined in @file{tex-file.h}. These are -macros that expand to a call to @file{kpse_find_file}. You can call, -say, @code{kpse_find_tfm} after doing only the first of the +@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 routines are @code{kpse_find_pk}, -@code{kpse_find_gf} and @code{kpse_find_glyph}, defined in -@file{tex-glyph.h}. These return a structure in addition to the +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 kpse_open_file +@findex kpathsea_open_file To actually open a file, not just return a filename, call -@code{kpse_open_file}. This function takes the name to look up and a +@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_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 @@ -2407,7 +2407,7 @@ 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{kpse_open_file} will open the files it finds in text or binary +@code{kpathsea_open_file} will open the files it finds in text or binary mode. @@ -2421,27 +2421,27 @@ 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 kpse_var_value +@findex kpathsae_var_value @flindex variable.h @vindex shell_escape@r{, example for code} To retrieve a value @var{var} from config files, the best way is to call -@code{kpse_var_value} on the string @code{@var{var}}. This will look +@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 variable expansion in the context of a search path (as -opposed to simply retrieving a value) is @code{kpse_var_expand}, also +opposed to simply retrieving a value) is @code{kpathsea_var_expand}, also declared in @file{kpathsea/variable.h}. It's generally only necessary to set the search path structure components as explained in the previous section, rather than using this yourself. -@findex kpse_cnf_get +@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{kpse_cnf_get} (declared in @file{kpathsea/cnf.h}) +variable, call @code{kpathsea_cnf_get} (declared in @file{kpathsea/cnf.h}) with the string @var{var}. No initialization calls are needed. |