zlibc.texi

zlib压缩原码

as the compiled-in defaults are already pretty complete.


@menu
* Environmental variables::
* Configuration files::
* Compiled-in defaults::
* Compile-time configuration::
@end menu

@node Environmental variables, Configuration files, Customization, Customization
@section Environmental variables

Environmental variables come in two kinds: @emph{switch} variables have
a boolean value and can only be turned on or off, whereas @emph{string}
variables can have arbitrary strings as values.


@menu
* Switch variables::
* String variables::
@end menu


@node Switch variables, String variables, Environmental variables, Environmental variables
@subsection Switch variables
@vindex LD_ZLIB_VERBOSE
@cindex debugging zlibc
@vindex LD_ZLIB_UNLINK
@cindex removing files
@cindex preventing accidental removal of compressed files (env.var.)
@vindex LD_ZLIB_DISABLE
@vindex LD_ZLIB_READDIR_COMPR
@cindex showing compressed files in a directory listing (env.var.)

These variables represent a flag which can be turned on or off.  If
their value is @code{on} or @code{1} they are turned on, if their value
is @code{off} or @code{0} they are turned off. All other values are
ignored. If the same flag can be turned on or off using config files,
the environmental variable always has the priority.

@table @code
@item LD_ZLIB_VERBOSE 
If this variable is turned on, informational messages are printed on
many operations of zlibc.  Moreover, error messages are printed in order
to point out errors in the configuration files, if any. If this variable
is turned off, errors are silently ignored.

@item LD_ZLIB_UNLINK
If this variable is turned on, and if the user program tries to unlink a
virtual (uncompressed) file, zlibc translates this call into unlinking
the real file. If this variable is turned off, unlink calls on virtual
files are ignored.

@item LD_ZLIB_DISABLE
If this variable is turned on, zlibc is switched off.

@item LD_ZLIB_READDIR_COMPR
If this variable is turned on, the readdir function shows the real
(compressed) files instead of the virtual (uncompressed) files.
@end table

@node String variables, , Switch variables, Environmental variables
@subsection String variables
@vindex LD_ZLIB_TMP
@cindex directory for temporary files (env.var.)
@vindex LD_ZLIB_EXT
@cindex filename extension for compressed files (env.var.)
@vindex LD_ZLIB_UNCOMPRESSOR
@cindex command line for the uncompressing program (env.var.)
@vindex LD_ZLIB_CONFFILE
@cindex location of the configuration file (env.var.)

These variables have a string value, which represent a file, a directory
or a command.

@table @code
@item LD_ZLIB_TMP
This is the name of the directory where the temporary uncompressed files are 
put. The default is /tmp.

@item LD_ZLIB_EXT
This is the extension which is appended to a virtual file name in order
to obtain the real (compressed) file name. The default is @code{.gz}.

@item LD_ZLIB_UNCOMPRESSOR
This is the name of the program to be invoked to uncompress the data. Default
is @code{gzip -dc}.

@item LD_ZLIB_CONFFILE 
This is the name of an additional configuration file. If this variable
is defined and if the corresponding file exists, the configuration
described in this file overrides the configurations in @file{~/.zlibrc}
and in @file{/usr/local/etc/zlibc.conf} (@file{/etc/zlibc.conf} on
Linux).
@end table

@c zlibc.3skip
@c zlibc-conf.5end-skip

@c MANskip
@node Configuration files, Compiled-in defaults, Environmental variables, Customization
@section Configuration files
@cindex Processing order of configuration file.
@c MANend-skip
@ignore
@subsection Name
zlibc.conf - zlibc's configuration file
@include man-warning.texi
@subsection Description
@end ignore



To get its configuration, zlibc first looks into the file described by
the environment variable @code{LD_ZLIB_CONFFILE} (if any), then in
@file{~/.zlibrc} and finally in @file{/usr/local/etc/zlibc.conf}
(@file{/etc/zlibc.conf} on Linux @footnote{Actually the location of the
system-wide include file depends on the settings of @code{sysconfdir}
and @code{prefix} during @code{./configure} (@pxref{Compile-time
configuration}).}).  If the desired information is found in neither of
these files, the compiled-in defaults are used.  It is possible to
supply only part of the needed information in the configuration
files. In that case, the missing information is retrieved from the
compiled-in defaults. This allows you to have really small runtime
configuration files, which only list the differences between the desired
configuration and the compiled-in configuration.

If an error occurs while parsing one of the configuration files, the
offending file is skipped, and the search continues with the next
file. However, no error message is printed unless the environmental
variable @code{LD_ZLIB_VERBOSE} is turned on (i.e. set to @code{1} or
to @code{on} ).

If two files contain contradictory information, the information in the
file which is scanned first is retained (usually @file{~/.zlibrc}). If
any flags have been set or unset using environmental variables, these
settings override the flags specified in the configuration files.

The configuration files are read by each process. For each process, they
are read at most once, at the time when zlibc is first used (attempt to
access a compressed file). Afterwards they are cached in the process's
virtual memory.  Thus, changing zlibc configuration files doesn't
generally have any effect on already running processes.

@menu
* Overall structure::
* Commands section::
* Class section::
@end menu

@node Overall structure, Commands section, Configuration files, Configuration files
@subsection Overall structure
@cindex commands section
@cindex class section
@cindex Parsing order of configuration files.

The zlibrc files consist of two sections: A @emph{commands} section
(@ref{Commands line flags}) and a @emph{class definition} section
(@ref{Class section}).

The commands section describes how zlibc should behave depending on
the executable that it was called from.  Several commands are grouped
together into @emph{command classe}.

The class definition section describes how zlibc should behave depending
on the class of the command and the datafile opened.

The configuration file may contain comments in both sections: a comment
starts with a hash (@code{#}) and stops at the end of the line.

Dashes (@code{-}) and underbars (@code{_}) may be used indifferently in
all keywords.

@node Commands section, Class section, Overall structure, Configuration files
@subsection Commands section

@menu
* Commands section syntax::             What goes into the commands
                                        section
* Commands line flags::                 Which flags are available
@end menu

@node Commands section syntax, Commands line flags, Commands section, Commands section
@subsubsection General syntax of the commands section
@cindex commands section

The format for a line in the "commands" section is as follows:

@display
@code{commands "}@var{cmd1}@code{"} [ @dots{} @code{"}@var{cmdn}@code{"} ] @code{use} @var{flags} @code{"}@var{class}@code{"}

@end display


In this line, the @var{cmd1} @dots{} @var{cmdn} are the basenames of the
programs (commands) for which this line should apply.  The basename is
the name without the path, i.e. @code{ls} instead of
@code{/usr/bin/ls}. The command names should be enclosed in quotes.  You
may also use the keyword @code{default} (without quotes) to match all
commands.

The @var{flags} describe those aspects of zlibc's behaviour that are
independant from the datafile which is being accessed. These flags come
in pairs.  The flags need not to be listed on a single @code{commands}
line, they may occur in several places, even in several different
configuration files (for instance one in @code{/etc/zlibc.conf} and
another one in @code{~/.zlibrc}.

If two contradictory flags are found in the configuration files, the one
which is seen first is taken.

If on the other hand a certain flag is not found at all in the
configuration files, the compiled-in default for this flag is used. This
is usually the second flag of each pair, described below
(@pxref{Commands line flags}).

These flags can all be overridden by environmental variables.  When the
corresponding environmental variable is set to @code{1} or to @code{on},
the first flag is used, when it is set to @code{0} or to @code{off}.  If
the environmental variables is set to neither of these 4 values, it is
ignored).

The @var{class} names the commands class that these commands belong to.
If, for a given command, two @code{commands} lines give different
classes, the one which is seen first is taken. No union of classes is
made, the classes are always treated as a whole. Thus, if you want to
make a change to a command class, you need to describe it in its
entirety.

The following example says that the @code{tar}, @code{cpio}, @code{pax},
@code{cp} and @code{mv} show compressed files in a directory listing
(@code{readdir_compr} flag), and are of class @code{generic_safe}.
@example
commands "tar" "cpio" "pax" "cp" "mv" use readdir_compr "generic_safe"
@end example

The class @code{generic_safe} would then need to be described further in
the class section.

@node Commands line flags, , Commands section syntax, Commands section
@subsubsection Available commands line flags
@vindex disable
@vindex enable
@vindex readdir_compr
@vindex readdir_uncompr
@vindex verbose
@vindex silent

@cindex disabling zlibc (conf. file)
@cindex showing compressed files on a directory listing (conf. file)
@cindex debugging zlibc


This section describes the flags which can be used on a @code{commands}
line. All these flags come in pairs.

The table below describes each of these pairs.  The first word in the
header of each item is the non-default flag, the second word is the
default flag, and the third word is the environmental variable by which
you can override the settings from the configuration files. If this
environmental variable is turned on (set to 1), the non-default (first)
flag is taken, if it is turned off (set to 0), the default (second) flag
is taken.

@table @code
@item disable / enable / LD_ZLIB_DISAB
The @code{disable} flag disables zlibc for the programs on this commands
line.  This is useful for compression and uncompression utilities.
Without this flag, @code{gunzip} would not work anymore, because it
would think that the uncompressed file exists already, and it would
refuse to overwrite this file.

@item disable_child / enable_child / LD_ZLIB_DISAB_CHILD
The @code{disable_child} flag disables zlibc for the programs started by
programs on this commands line. This is implemented by removeing all
occurrences of @code{uncompress.o} from the LD_PRELOAD environment
variable. This function is useful for programs such as xemacs, in order
to make sure that all launched subprograms return results consistent
with emacs itself (directory listings, etc)

@item readdir_compr / readdir_uncompr / LD_ZLIB_READDIR
The readdir function shows the uncompressed files (i.e. with their
trailing @code{.gz} extension) when the @code{readdir_compr} flag is
set, and the compressed files otherwise.

@item verbose / silent / LD_ZLIB_VERBOSE
When @code{verbose} is set, zlibc prints informational messages.

@item unlink / no_unlink / LD_ZLIB_UNLINK
If the @code{unlink} flag is set, and if the user program tries to
unlink a virtual (uncompressed) file, the package translates this call
into unlinking the real file. If the @code{no_unlink} flag is set,
requests to unlink virtual (uncompressed) files are silently ignored.

@end table

@node Class section, , Commands section, Configuration files
@subsection Class section


A command class@footnote{These command classes are unrelated to the
classes in object oriented programming.} definition describes those
aspects of zlibc's behavior that depend on the name of the datafile
which is being accessed. Command classes are identified by a name which
is matched against the @var{class} parameter from the commands.  The
class name should be enclosed between quotes both in the commands line
and in the class definition.


The class section contains descriptions of different command classes
(i.e descriptions how datafiles should be uncompressed). Each class
definition begins with a line of the following format:

@display
@code{class "}@var{id}@code{"}
@end display

The class @var{id} is the same string as the one used in the commands
line. The remaining lines of a class definition are as follows:
@display
[ [ @var{criterion} ] [ @code{"}@var{name}@code{"} ]] @var{mode}
@end display

The following example shows the definition of the class used for X-servers.

@example
# X uses tmp files in its own directories.
class "X"
subdir "/usr/X11R6" usetmpfile
subdir "/usr/X386" usetmpfile
subdir "/usr/lib/X11" usetmpfile
showpipe
@end example

This says that all compressed files who are in a subdirectory below
@file{/usr/X11R6}, @file{/usr/X386} or @file{/usr/lib/X11} are
decompressed using temporary files (@code{usetmpfile}), and that files
from other directories are decompressed using pipes (@code{showpipe})


The following examples illustrates a command class, named @code{nopipe},
which always uses temporary files for decompression
@display
# generic class which uses temp files for all files.
class "nopipe"
usetmpfile
@end display

@menu
* Criteria::           To which data files does this line apply
* Mode::               How zlibc behaves for the files matching the
                       criterion
@end menu

@node Criteria, Mode, Class section, Class section
@subsubsection File selection Criteria
@cindex directory (selection criterion)
@cindex filename (selection criterion)
@cindex extension (selection criterion)
@cindex suffix (selection criterion)
@cindex basename (selection criterion)
@cindex doublespaced DOS filesystem

The @var{criterion } describes what parts of the filename should match:

@table @code
@item filename
The entire filename of the target data file must match
@var{name}.

@item basename
The basename (filename without directory) of the target data file must
match @var{name}.

@item directory
The data file must live in the directory @var{name}.  If the user
program opens the file with an absolute pathname, that filename is used
as is.  If on the other hand the user program uses a relative pathname,
zlibc uses the most direct path to the file (i.e. without symlinks).

@item subdirectory
The data file must live in the directory @var{name} or in one of its
subdirectories. If the user program opens the file with an absolute
pathname, that filename is used as is.  If on the other hand the user
program uses a relative pathname, zlibc uses the most direct path to the
file (i.e. without symlinks).

@item suffix
The data file's name must end in @var{name}.  This is useful for
selecting files according to their extension.

@item filesystem
The data file must live on the same filesystem as @var{name}. This
criterion can for example be used for example to disable zlibc on a
doublespaced filesystem (where zlibc would be redundant), or to switch
off uncompressed size reporting on an @code{ftpfs} filesystems
@footnote{uncompressed size reporting (@pxref{Size} would make @code{ls}
painfully slow on an @code{ftpfs} filesystem, as all files would have to
be downloaded before their size could be reported.}.

@item default
All data files match. All class definitions must have a default line,
and this default line must be the last line of the definition. The
default criterion needs no 'name' parameter.

@item all
All data files match. Unlike @code{default}, this line needs not to be
the last line of the class definitions. Thus it is possible to specify
several @code{all} lines for different aspects of @code{zlibc}
behaviour.
@end table

The lines of each class definition are scanned in sequence, and, for
each aspect@footnote{See @pxref{Mode}}, the first matching line is
adopted.  The class may be defined in another initialisation file, if