zlibc.texi

zlib压缩原码

this file is scanned later. The @var{criterion} parameter may be omitted
if it can be deduced from the @var{name}. In that case, the following
heuristics are used:

@itemize @bullet
@item
@var{Name}s beginning with a dot are considered as @code{suffix}.

@item
@var{Name}s beginning with a slash, but not ending with a slash are
considered as @var{filename}.

@item
@var{Name}s beginning and ending with a slash are considered as
@code{subdirectory}.

@item
A missing @var{name} is considered as @code{default}.

@item
All the other @var{name}s are considered as @code{basename}.
@end itemize

@c With the exception of the @code{filesystem} criterion, these selection
@c criteria are applied on the filename @emph{as it was provided by the
@c user program}.  Names might not match if they are accessed by a
@c different path than the one specified in the config file. This is
@c especially true for criteria using the directory part of a
@c filename. Whenever possible, use the @code{suffix}, @code{basename} or
@code{filesystem} criteria, because these tend to be more predictable.

@node Mode, , Criteria, Class section
@subsubsection Mode

The @var{mode} describes the behavior of zlibc in certain
situations. These are:
@enumerate
@item
What to do when a file is accessed in readonly mode.
@item
What to do when a user program tries to append data to an existing file.
@item
What to do when a user program tries to create a new file.
@item
What to do when a user program tries to access an existing file and none
of the preceding situations apply (@pxref{Write}).
@item
Whether to show the size of the uncompressed file or the size of the
compressed file as a response to stat (@pxref{Size}).
@end enumerate

The mode for each off these 5 situations has to be described separately.
For each of these 5 situations, the scan through the class description
is done until the reaction of zlibc for this situation is defined.


@menu
* Readonly::     Behavior for programs wanting to only read files
* Append::              - for programs wanting to add more data to
                          existing files
* Creation::            - for programs wanting to create new files
* Write::               - for programs wanting to apply other
                          modifications to files
* Size::                - for programs wanting to know the size of a 
                          file
@end menu


@node Readonly, Append, Mode, Mode
@unnumberedsubsubsec Reaction to a readonly request

The reaction to a @code{readonly} request may be one of the following:

@table @code

@item show-pipe
The uncompressed data file is sent to the user program using a
pipe. This consumes very few resources, and it allows the decompression
to run in paralell with the user process, but it has the disadvantage
that the user program cannot use lseek.  To warn the user program of
this, the data file is shown as a named pipe (FIFO) when it is
stat'ed.

@item use-tmp-file
This is the default setting.  The data is uncompressed and put into a
temporary file. The user programs then reads its data from the temporary
file. This has the advantage that the user program may lseek, and the
disadvantage that more disk space is consumed, while the programming is
accessing the file.

@item hide-pipe
The data is sent through a pipe, but the file is shown as a regular file
("hidden") to the user program when it stats it. This might be needed
for programs which are picky about a file type, but who actually don't
need lseek.

@item leave-compressed
The virtual (uncompressed) file is shown as non-existent to stat, and
readdir shows the physical (compressed) file. For certain programs, this
is enough to disable zlibc on a file per file basis. This is useful, for
example, to make emacs use its own compression support (crypt.el)
instead of zlibc. Crypt.el is able to compress files when writing them
back, whereas zlibc isn't able to do so. The @code{leave-compressed}
doesn't work correctly with the @code{directory} and @code{subdirectory}
criteria.  Use the @code{filesystem} criterion instead.

@item dir-leave-compressed
The virtual (uncompressed) file is shown to stat, but readdir shows the
physical (compressed) file. This is useful to tell zlibc that we prefer
working on the physical file, but without making access to the virtual
file impossible. The @code{dir-leave-compressed} doesn't work with the
@code{dir} and @code{subdir} criteria. Use the @code{filesystem}
criterion instead.

@end table

@node Append, Creation, Readonly, Mode
@unnumberedsubsubsec Reaction to an append request

The reaction to an @code{append} request may be one of the following:

@table @code
@item append-compressed
When a user program tries to append data to a non-existant file, but the
corresponding compressed file exists, zlibc translates this request into
appending the compressed data to the compressed file.

@strong{WARNING-1:}

This works with gzip, and might not work with other (un)compressors!
This relies on gzip's feature to consider a concatenation of compressed
files as a compression of concatenated files.

@strong{WARNING-2:}

This is only reliable if you can guarantee that the file is not accessed
by some other program while the first one has it still open, or that it
won't be opened again (even by the same program) shortly after it has
been closed. Delays longer than a second should be ok. Don't enable
@code{append-compressed} if you expect the file to be written to by
several programs at once.

@item no-append-compressed
Don't append to a compressed file (the user program will get a file not
found error). This is the default behavior.

@end table

@node Creation, Write, Append, Mode
@unnumberedsubsubsec Reaction to a file creation request

The reaction to a @code{create} request may be one of the following:

@table @code
@item create-compressed
When a user program tries to create a new file whose name matches the
pattern, zlibc translates this request into creating a compressed
file. A file is considered to be created, if the @code{O_TRUNC} flag is
set, or if both @code{O_CREAT} and @code{O_EXCL} are set. This only
applies to files opened write-only.

@strong{WARNING-1:}

This is only reliable if you can guarantee that the newly
created file is not accessed by some other program while the first one
has it still open, or that it won't be opened again (even by the same
program) shortly after it has been closed.

@strong{WARNING-2:}

This should not be used if you expect the program to seek in this
file.

@item no-create-compressed
Newly created files are created uncompressed. This is the default.
@end table

@node Write, Size, Creation, Mode
@unnumberedsubsubsec Other write requests

The reaction to other @code{write} requests may be one of the following:

@table @code
@item uncompress-before-write
When a user program tries to write to a non-existing file, and when a
compressed file with a corresponding name exists, this file is
uncompressed in place (i.e. having the same name, but without the .gz
extension)

@strong{WARNING-1:}

This is only safe when you can guarantee that the file is not opened by
several programs at once. However, once the call to the open function
has returned, other programs may open this file safely. If a second
program tries to open the file during the open call of the first, this
second program gets a permission error.

@strong{WARNING-2:}

When using this option, be careful when opening files belonging to
another user, or files living in a directory where you have no write
access to. Using this option in a directory without write access will
result in a permission error. Using this option in a directory where you
do have write access will change the ownership of the file to you, even
if it belonged to another user initially.

@item no-uncompress-before-write
Compressed files are not uncompressed before writing to them, and zlibc
returns a "file not found" error. This is the default.

@end table

If several of these options apply for the same file,
@code{create-compressed} has priority over @code{append-compressed}
which has priority over @code{uncompress-before-write}.

@node Size, , Write, Mode
@unnumberedsubsubsec Size shown for compressed files
@cindex find
@cindex size of compressed files
@cindex slowness (of find due to reading the size)
@vindex show-compressed-size
@cindex ftpfs
@cindex ls slowness (on an ftpfs filesystem)
@cindex slowness (of ls, on an ftpfs filesystem)
@cindex hanging (of ls, on an ftpfs filesystem)


When an application calls @code{stat} to fetch the attributes of a file
(such as its permissions, size, type, etc.), zlibc stats the
corresponding compressed file instead.  After doing so, zlibc has to
adjust some of the values returned by stat, such as the type and the
size.  The type has to be adjusted for those files that should be shown
as pipes.  The size has to be adjusted because user programs are usually
interested in the amount of data that they can actually read from the
file (i.e. the size of the uncompressed file) rather than the size of
the physical file (i.e. the size of the compressed file).  However, in
order to find out the size of the uncompressed file, zlibc has to read
some data of the file, which may impact performance in situations where
many files are stat'ed.  This is for instance the case for @code{find},
or for @code{ls} on an @code{ftpfs} filesystem.  The following two
behaviors of the stat call may be specified:

@table @code
@item show-compressed-size
Stat returns the size of the compressed file.  This is less useful for
the application, but more efficient.  If you mount any @code{ftpfs}
filesystems, you may switch on @code{show-compressed-size} just for that
filesystem by using the @code{filesystem} criterion (@pxref{Criteria}).

@item show-uncompressed-size
Stat returns the size of the uncompressed file.  This is more useful for
the application, but less efficient.  This is the default behavior.

@end table

@ignore
@subsection See also
zlibc(3)
@end ignore

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

@node Compiled-in defaults, Compile-time configuration, Configuration files, Customization
@section Compiled-in defaults

It is possible to operate zlibc entirely without configuration files.
In this case, it uses the @emph{compiled-in defaults}.  These are
generated at compile-time from the @file{zlibrc.sample} file.  This file
has the same syntax as the configuration files described above
(@pxref{Configuration files}).  If you want to change the compiled-in
defaults of zlibc, edit that file, and remake.

@node Compile-time configuration, , Compiled-in defaults, Customization
@section Compile-time configuration via GNU autoconf
@cindex configure options
@cindex temporary file directory
@cindex directory for temporary files
@cindex compile-time configuration

Before it can be compiled, zlibc must be configured using the GNU
autoconf script @code{./configure}.  In most circumstances, running
@code{./configure} without any parameters is enough. However, you may
customize zlibc using various options to @code{./configure}. The
following options are supported:
@table @code

@item --prefix @var{directory}
Prefix used for any directories used by zlibc.  By default, this is
@file{/usr/local}.  Zlibc is installed in @file{$prefix/lib}, looks for
its system wide configuration file in @file{$prefix/etc}.  Man pages are
installed in @file{$prefix/man}, info pages in @file{$prefix/info} etc.
On Linux, if you use zlibc via @file{/etc/ld.so.preload}, you should use
@file{/} as the prefix instead of the default @file{$prefix/lib}.

@item --sysconfdir @var{directory}
Directory containing the system-wide configuration file
@file{zlibc.conf}.  By default, this is derived from @code{prefix} (see
above).

@item --disable-runtime-conf
Disables run time configuration via environmental variables and via the
configuration files.  This may be needed in hyper secure environments.

@item --disable-env-conf
Disables run time configuration via environmental variables

@item --disable-have-proc
Tells zlibc not to use the /proc filesystem to find out the commandline
of the programs for which it runs, even if a working /proc is detected.

@item --disable-have-proc
Tells zlibc to use the /proc filesystem to find out the commandline of
the programs for which it runs, even if no working /proc is detected.

@item --with-compr-ext=@var{extension}
Uses @var{extension} as the filename extension of compressed files.  By
default, is @code{.gz}

@item --with-extlen=@var{length}
Allows to configure compressed filename extensions with at most
@var{length} character via runtime configuration.  By default is 5.

@item --with-tmpdir=@var{directory}
Uses @var{directory} to store the uncompressed files.  By default is
@code{/tmp}.  

@item --with-uncompressor=@var{uncompressor-command-line}
Defines how the program for uncompressing files should be invoked.  This
command should read the compressed file from stdin, and output the
uncompressed data to stdout By default is @code{gzip -dc}.

@end table

In addition to the above-listed options, the standard GNU autoconf
options apply.  Type @code{./configure --help} to get a complete list of
these.

@ignore
@subsection See also
zlibc.conf(5)
@end ignore

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

@node Porting zlibc, Variable Index, Customization, Top
@chapter Porting zlibc

Zlibc has been tested on three variants of Unix so far: Linux, SunOs,
Solaris.  On all three platforms, zlibc has been compiled using GNU make
and gcc.  However, porting it to other platforms should be
straightforward as long as they verify both of the following conditions:

@enumerate
@item
The target platform should have shared library support.  The default
Makefile links zlibc by supplying the flags @code{-nostdlib -shared} to
gcc in addition to the usual @code{CFLAGS}.  If your target platform
needs different flags to make shared libraries, change the definition of
the variable @code{SHAREDCFLAGS} in the Makefile.
@item
The target platform should supply a way to perform system calls
directly without going through the library functions.  Indeed, this is
needed because we are redefining the library functions and thus the
default functions become unavailable.

Usually direct syscalls done by calling the syscall function.  For
instance, in order to perform @code{open("test", O_RDONLY)} directly,
@code{sycall(SYS_open, "test", O_RDONLY)} is called.

If your target platform uses a different way to perform direct
system calls, you need to supply different definitions for the real_xxx
functions in direct_sys.h.  This is the case for AIX.
@item
The target platform should provide a way to instruct the dynamic linker
to preload programs with extra object files not present in the shared
library.  Any symbols defined in that object file override equivalent
symbols from libc.  Usually this is done by pointing the
@code{LD_PRELOAD} variable to the object file to be used.
Unfortunately, I have found no way to achieve this on AIX.  Any ideas
about how to do this are welcome.
@end enumerate

Many platforms, including Solaris, provide several aliases for their
syscall stubs.  It would be interesting to leave one of them alone, and
use it as a "direct syscall" stub, but unfortunately, it turns out that
in sometimes both stubs are used by the library!  Thus, what would be an
advantage, becomes actually a disadvantage, because we will need to
override these aliases in addition to the canonical names.  This is done
in altnames.c.  Change it as needed.  In order to know the names of
these aliases, try the following command: @code{nm /lib/libc.so | grep
lstat}.  This lists any library symbols with @code{unlink} in their
name, which could be aliases.

If you have successfully ported zlibc to a new platform, could you drop
me a note, so that I can include support for that platform in my next
release.  Thanks

@node Variable Index, Concept Index, Porting zlibc, Top
@unnumbered Variable index
@printindex vr

@node Concept Index, , Variable Index, Top
@unnumbered Concept index
@printindex cp

@contents

@c MANend-skip

@bye