summaryrefslogtreecommitdiff
path: root/Build/source/texk/kpathsea/doc/kpathsea.texi
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-04-05 18:32:02 +0000
committerKarl Berry <karl@freefriends.org>2009-04-05 18:32:02 +0000
commit063b8df0a35c0536f6cac802be7a571fd7c9c0aa (patch)
tree798f1c32ece27869ba12a0ff80a5ac1cd7a5fc55 /Build/source/texk/kpathsea/doc/kpathsea.texi
parent1c7395d469d47d74a0f215fa029895e2640cecab (diff)
doc updates for re-entrant API from Taco, plus tweaks from Karl
git-svn-id: svn://tug.org/texlive/trunk@12635 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/kpathsea/doc/kpathsea.texi')
-rw-r--r--Build/source/texk/kpathsea/doc/kpathsea.texi154
1 files changed, 77 insertions, 77 deletions
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.