zlibc.texi

zlib压缩原码

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename zlibc.info
@settitle Zlibc
@c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES!
@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@setchapternewpage off
@c %**end of header

@c MANskip

@set EDITION 0.9j
@set VERSION 0.9j
@set UPDATED July 2000

@iftex
@finalout
@end iftex

@ifinfo
@format
START-INFO-DIR-ENTRY
* Zlibc: (zlibc).        Zlibc: transparently access compressed files.
END-INFO-DIR-ENTRY
@end format
@end ifinfo


@ifinfo
Zlibc Copyright (C) 1993-1999 Alain Knaff

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one, and provided that the privacy
of any reader of the resulting derived work is respected. In particular
is it strictly forbidden to make this documentation available on a World
Wide Web server which deals cookies. However, keeping access statistics
is allowed.

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.
@end ifinfo

@titlepage
@title Zlibc
@subtitle Transparently access compressed files.
@subtitle Edition @value{EDITION}, for Zlibc version @value{VERSION}
@subtitle @value{UPDATED}
@author by Alain Knaff
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 1993-1999 Alain Knaff

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one and provided that the privacy of
any reader of the resulting derived work is respected. In particular is
it strictly forbidden to make this documentation available on a World
Wide Web server which deals cookies. However, keeping access statistics
is allowed.

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.

@end titlepage

@ifinfo
@node Top, Location, (dir), (dir)

@end ifinfo

@c MANend-skip
@c zlibc-conf.5skip

@ignore
@unnumbered Name
zlibc - transparently access compressed files.
@end ignore

@unnumbered Introduction

The zlibc package allows transparent on the fly uncompression of gzipped
files.  Your programs will be able to access any compressed file, just
as if they were uncompressed.  Zlibc will transparently uncompresses the
data from these files as soon as they are read, just as a compressed
filesystem would do.  No kernel patch, no recompilation of these
executables and no recompilation of the libraries is needed.

It is not (yet) possible execute compressed files with zlibc. However,
there is another package, called @code{tcx}, which is able to uncompress
executables on the fly.  On the other hand @code{tcx} isn't able to
uncompress data files on the fly.  Fortunately, the both zlibc and tcx
may coexist on the same machine without problems.

@menu
* Location::              Where to get zlibc and early bug fixes
* Installing zlibc::      How to install zlibc
* Using zlibc::           How to configure your system to use zlibc
* How it works::          The general principles behind zlibc
* Customization::         How to customize zlibc to your needs
* Porting zlibc::         How to port zlibc to new architectures
* Variable Index::        Variable Index
* Concept Index::         Concept Index
@end menu
@c MANskip
This documentation looks most pretty when printed or as html.  Indeed,
in the info version certain examples are difficult to read due to the
confusing quoting conventions of info.
@c MANend-skip

@include man-warning.texi


@cindex bugs
@cindex ALPHA patches
@cindex patches
@cindex diffs
@cindex mailing list


@node Location, Installing zlibc, Top, Top
@chapter Where to get zlibc

Zlibc can be found at the following places (and their mirrors):
@example
ftp://zlibc.linux.lu/zlibc-0.9j.tar.gz
ftp://www.tux.org/pub/knaff/zlibc/zlibc-0.9j.tar.gz
ftp://ibiblio.unc.edu/pub/Linux/libc/zlibc-0.9j.tar.gz
@end example

Before reporting a bug, make sure that it has not yet been fixed in the
Alpha patches which can be found at:
@example
http://zlibc.linux.lu/
http://www.tux.org/pub/knaff/zlibc
@end example

These patches are named
@code{zlibc-}@var{version}@code{-}@var{ddmm}@code{.taz}, where version
stands for the base version, @var{dd} for the day and @var{mm} for the
month. Due to a lack of space, I usually leave only the most recent
patch.

There is an zlibc mailing list at zlibc @@ www.tux.org .  Please
send all bug reports to this list.  You may subscribe to the list by
sending a message with 'subscribe zlibc @@ www.tux.org' in its
body to majordomo @@ www.tux.org . (N.B. Please remove the spaces
around the "@@" both times. I left them there in order to fool
spambots.)  Announcements of new zlibc versions will also be sent to
the list, in addition to the linux announce newsgroups.  The mailing
list is archived at http://www.tux.org/hypermail/zlibc/latest

@node Installing zlibc, Using zlibc, Location, Top
@chapter Installing zlibc
@vindex LD_PRELOAD
@cindex Installation
@cindex Set-uid programs
@cindex Boot problems

@enumerate
@item 
If you install zlibc on Linux, make sure that your shared loader
(ld-linux.so.1/ld.so) understands @code{LD_PRELOAD}. (Best if
ld.so-1.8.5 or more recent)

@item
Type @code{./configure}. This runs the GNU autoconfigure script which
configures the @file{Makefile} and the @file{config.h} file.  You may
compile time configuration options to @code{./configure}, see for
details.

@item
Type @code{make} to compile zlibc.

@item
Type @code{make install} to install zlibc and associated programs to its
final target.

@item
To use this module, set the environment variable @code{LD_PRELOAD} to
point to the object. Example (sh syntax):

@example
      LD_PRELOAD=/usr/local/lib/uncompress.o
      export LD_PRELOAD
@end example

or (csh syntax):

@example
      setenv LD_PRELOAD /usr/local/lib/uncompress.o
@end example
On linux, use /lib/uncompress.o instead of /usr/local/lib/uncompress.o .

You might want to put these lines in your @file{.profile} or
@file{.cshrc} in order to have the uncompressing functions available all
the time.
@item
Compress your files using gzip and enjoy

@end enumerate

For security reasons, the dynamic loader disregards environmental
variables such as @code{LD_PRELOAD} when executing set uid programs.

However, on Linux, you can use zlibc with set uid programs too, by using
one of the two methods described below:

@enumerate
@item
You may ing the path to @file{uncompress.o} into
@file{/etc/ld.so.preload} instead of using @code{LD_PRELOAD}.

@strong{WARNING}: If you use @file{/etc/ld.so.preload}, be sure to
install @file{uncompress.o} on your root filesystem, for instance in
@code{/lib}, as is done by the default configuration.  Using a directory
which is not available at boot time, such as /usr/local/lib will cause
trouble at the next reboot!

It is also careful to remove zlibc from @file{/etc/ld.so.preload} when
installing a new version.  First test it out using @code{LD_PRELOAD},
and only if everything is ok, put it back into
@file{/etc/ld.so.preload}.  The zlibc package also supplies four
statically linked programs @code{srm}, @code{smv}, @code{sln} and
@code{ssln}, which are equivalen to @code{rm}, @code{mv}, @code{ln} and
@code{ln -s}.  These can be used in case anything goes wrong with the
installation.

@item
If you have a version of @code{ld.so} which is more recent than
@code{1.9.0}, you can set @code{LD_PRELOAD} to just contain the basename
of @file{uncompress.o} without the directory.  In that case, the file is
found as long as it is in the shared library path (which usually
contains @file{/lib} and @file{/usr/lib})). Because the search is
restricted to the library search path, this also works for set-uid
programs.

Example (sh syntax):

@example
      LD_PRELOAD=uncompress.o
      export LD_PRELOAD
@end example

or (csh syntax):

@example
      setenv LD_PRELOAD uncompress.o
@end example

The advantage of this approach over @file{ld.so.preload} is that zlibc
can more easily be switched off in case something goes wrong.

@end enumerate

@node Using zlibc, How it works, Installing zlibc, Top
@chapter Using zlibc
@cindex Symbolic links

Once zlibc is installed, simply compress your biggest datafiles
using gzip. Your programs are now able to uncompress these files on the
fly whenever they need them.

@section Zlibc and links

@subsection Symbolic links

After compressing your datafiles, you also need to change any potential
symbolic links pointing to them.  Let's suppose that @file{x} is a
symlink to @file{tstfil}:

@example
> echo 'this is a test' >tstfil
> ln -s tstfil x
> ls -l
total 1
-rw-r--r--   1 alknaff  sirac          15 Feb 25 19:40 tstfil
lrwxrwxrwx   1 alknaff  sirac           8 Feb 25 19:40 x -> tstfil
@end example

After compressing it, you'll see the following listing:

@example
> gzip tstfil
> ls -l
total 1
pr--r--r--   1 alknaff  sirac          15 Feb 25 19:40 tstfil
lrwxrwxrwx   1 alknaff  sirac           8 Feb 25 19:40 x -> tstfil
@end example

@file{Tstfil} is now shown as a pipe by zlibc in order to warn programs
that they cannot seek in it.  Zlibc still shows it with its old name,
and you can directly look at its contents:
@example
> cat tstfil
this is a test
@end example

However, @file{tstfil} is not yet accessible using the symbolic link:
@example
> cat x
cat: x: No such file or directory
@end example

In order to make @file{tstfil} accessible using the link, you have to
destroy the link, and remake it:
@example
> rm x
/bin/rm: remove `x'? y
> ln -s tstfil x
> ls -l
total 1
pr--r--r--   1 alknaff  sirac          15 Feb 25 19:40 tstfil
lrwxrwxrwx   1 alknaff  sirac           8 Feb 25 19:44 x -> tstfil
> cat x
this is a test
@end example

@subsection Hard links

If you compress datafiles with hard links pointing to them, gzip refuses
to compress them. 

@example
> echo 'this is a test' >tstfil
> ln tstfil x
> ls -li
total 2
    166 -rw-r--r--   2 alknaff  sirac          15 Feb 25 19:46 tstfil
    166 -rw-r--r--   2 alknaff  sirac          15 Feb 25 19:46 x
> gzip tstfil
gzip: tstfil has 1 other link  -- unchanged
@end example

Thus you need to remove these hard links first, and remake them after
compressing the file.

@example
> rm x
/bin/rm: remove `x'? y
> gzip tstfil
> ln tstfil x
> ls -li
total 2
    167 pr--r--r--   2 alknaff  sirac          15 Feb 25 19:46 tstfil
    167 pr--r--r--   2 alknaff  sirac          15 Feb 25 19:46 x
> cat x
this is a test
@end example

@node How it works, Customization, Using zlibc, Top
@chapter How it works

Usually, programs don't make system calls directly, but instead call a
library function which performs the actual system calls. For instance,
to open a file, the program first calls the @code{open} library
function, and then this function makes the actual syscall.  Zlibc
overrides the @code{open} function and other related functions in order
to do the uncompression on the fly.

If the @code{open} system call fails because the file doesn't exist,
zlibc constructs the filename of a compressed file by appending
@code{.gz} to the filename supplied by the user program. If this
compressed file exists, it is opened and piped trough @code{gunzip}, and
the descriptor of the read end of this pipe is returned to the caller.

In some cases, the compressed file is first uncompressed into a
temporary file, and a read descriptor for this file is passed to the
caller.  This is necessary if the caller wants to call @code{lseek} on
the file or @code{mmap} it. A description of data files for which using
temporary is necessary can be given in the configuration files
@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}).} and
@file{~/.zlibrc}. @xref{Configuration files}, for a detailed description
of their syntax.

Many user programs try to check the existence of a given file by other
system calls before actually opening it. That's why zlibc also
overrides these system calls. If for example the user program tries to
stat a file, this call is also intercepted.

The compressed file, which exists physically on the disk, is also called
'the real file', and the uncompressed file, whose existence is only
simulated by zlibc is called 'the virtual file'.

@node Customization, Porting zlibc, How it works, Top
@chapter Customization
@cindex Customization

The behavior of zlibc can be tailored using configuration files or
environment variables. This customization should normally not be needed,