zlib.pm

来自「perl中编译使用zlib」· PM 代码 · 共 1,118 行 · 第 1/2 页

=item B<-Bufsize>

Sets the initial size for the inflation buffer. If the buffer has to be
reallocated to increase the size, it will grow in increments of
B<Bufsize>. 

Default is 4096.

=item B<-Dictionary>

The default is no dictionary.

=back

Here is an example of using the B<inflateInit> optional parameter to
override the default buffer size.

    inflateInit( -Bufsize => 300 ) ;

=head2 B<($out, $status) = $i-E<gt>inflate($buffer)>

Inflates the complete contents of B<$buffer>. The buffer can either be
a scalar or a scalar reference.

Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
compressed data has been successfully reached. 
If not successful, B<$out> will be I<undef> and B<$status> will hold
the I<zlib> error code.

The C<$buffer> parameter is modified by C<inflate>. On completion it
will contain what remains of the input buffer after inflation. This
means that C<$buffer> will be an empty string when the return status is
C<Z_OK>. When the return status is C<Z_STREAM_END> the C<$buffer>
parameter will contains what (if anything) was stored in the input
buffer after the deflated data stream.

This feature is useful when processing a file format that encapsulates
a  compressed data stream (e.g. gzip, zip).

=head2 B<$i-E<gt>dict_adler()>

Returns the adler32 value for the dictionary.

=head2 Example

Here is an example of using B<inflate>.

    use Compress::Zlib ;

    $x = inflateInit()
       or die "Cannot create a inflation stream\n" ;

    $input = '' ;
    binmode STDIN;
    binmode STDOUT;

    while (read(STDIN, $input, 4096))
    {
        ($output, $status) = $x->inflate(\$input) ;

        print $output 
            if $status == Z_OK or $status == Z_STREAM_END ;

        last if $status != Z_OK ;
    }

    die "inflation failed\n"
        unless $status == Z_STREAM_END ;

=head1 COMPRESS/UNCOMPRESS

Two high-level functions are provided by I<zlib> to perform in-memory
compression. They are B<compress> and B<uncompress>. Two Perl subs are
provided which provide similar functionality.

=over 5

=item B<$dest = compress($source) ;>

Compresses B<$source>. If successful it returns the
compressed data. Otherwise it returns I<undef>.

The source buffer can either be a scalar or a scalar reference.

=item B<$dest = uncompress($source) ;>

Uncompresses B<$source>. If successful it returns the uncompressed
data. Otherwise it returns I<undef>.

The source buffer can either be a scalar or a scalar reference.

=back

=head1 GZIP INTERFACE

A number of functions are supplied in I<zlib> for reading and writing
I<gzip> files. This module provides an interface to most of them. In
general the interface provided by this module operates identically to
the functions provided by I<zlib>. Any differences are explained
below.

=over 5

=item B<$gz = gzopen(filename or filehandle, mode)>

This function operates identically to the I<zlib> equivalent except
that it returns an object which is used to access the other I<gzip>
methods.

As with the I<zlib> equivalent, the B<mode> parameter is used to
specify both whether the file is opened for reading or writing and to
optionally specify a a compression level. Refer to the I<zlib>
documentation for the exact format of the B<mode> parameter.

If a reference to an open filehandle is passed in place of the
filename, gzdopen will be called behind the scenes. The third example
at the end of this section, I<gzstream>, uses this feature.

=item B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>

Reads B<$size> bytes from the compressed file into B<$buffer>. If
B<$size> is not specified, it will default to 4096. If the scalar
B<$buffer> is not large enough, it will be extended automatically.

Returns the number of bytes actually read. On EOF it returns 0 and in
the case of an error, -1.

=item B<$bytesread = $gz-E<gt>gzreadline($line) ;>

Reads the next line from the compressed file into B<$line>. 

Returns the number of bytes actually read. On EOF it returns 0 and in
the case of an error, -1.

It is legal to intermix calls to B<gzread> and B<gzreadline>.

At this time B<gzreadline> ignores the variable C<$/>
(C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use). The
end of a line is denoted by the C character C<'\n'>.

=item B<$byteswritten = $gz-E<gt>gzwrite($buffer) ;>

Writes the contents of B<$buffer> to the compressed file. Returns the
number of bytes actually written, or 0 on error.

=item B<$status = $gz-E<gt>gzflush($flush) ;>

Flushes all pending output into the compressed file.
Works identically to the I<zlib> function it interfaces to. Note that
the use of B<gzflush> can degrade compression.

Refer to the I<zlib> documentation for the valid values of B<$flush>.

=item B<$gz-E<gt>gzclose>

Closes the compressed file. Any pending data is flushed to the file
before it is closed.

=item B<$gz-E<gt>gzerror>

Returns the I<zlib> error message or number for the last operation
associated with B<$gz>. The return value will be the I<zlib> error
number when used in a numeric context and the I<zlib> error message
when used in a string context. The I<zlib> error number constants,
shown below, are available for use.

    Z_OK
    Z_STREAM_END
    Z_ERRNO
    Z_STREAM_ERROR
    Z_DATA_ERROR
    Z_MEM_ERROR
    Z_BUF_ERROR

=item B<$gzerrno>

The B<$gzerrno> scalar holds the error code associated with the most
recent I<gzip> routine. Note that unlike B<gzerror()>, the error is
I<not> associated with a particular file.

As with B<gzerror()> it returns an error number in numeric context and
an error message in string context. Unlike B<gzerror()> though, the
error message will correspond to the I<zlib> message when the error is
associated with I<zlib> itself, or the UNIX error message when it is
not (i.e. I<zlib> returned C<Z_ERRORNO>).

As there is an overlap between the error numbers used by I<zlib> and
UNIX, B<$gzerrno> should only be used to check for the presence of
I<an> error in numeric context. Use B<gzerror()> to check for specific
I<zlib> errors. The I<gzcat> example below shows how the variable can
be used safely.

=back


=head2 Examples

Here is an example script which uses the interface. It implements a
I<gzcat> function.

    use Compress::Zlib ;

    die "Usage: gzcat file...\n"
	unless @ARGV ;

    foreach $file (@ARGV) {
        $gz = gzopen($file, "rb") 
	    or die "Cannot open $file: $gzerrno\n" ;

        print $buffer 
            while $gz->gzread($buffer) > 0 ;
        die "Error reading from $file: $gzerrno\n" 
            if $gzerrno != Z_STREAM_END ;
    
        $gz->gzclose() ;
    }

Below is a script which makes use of B<gzreadline>. It implements a
very simple I<grep> like script.

    use Compress::Zlib ;

    die "Usage: gzgrep pattern file...\n"
        unless @ARGV >= 2;

    $pattern = shift ;

    foreach $file (@ARGV) {
        $gz = gzopen($file, "rb") 
             or die "Cannot open $file: $gzerrno\n" ;
    
        while ($gz->gzreadline($_) > 0) {
            print if /$pattern/ ;
        }
    
        die "Error reading from $file: $gzerrno\n" 
            if $gzerrno != Z_STREAM_END ;
    
        $gz->gzclose() ;
    }


This script, I<gzstream>, does the opposite of the I<gzcat> script
above. It reads from standard input and writes a gzip file to standard
output.

    use Compress::Zlib ;

    binmode STDOUT; # gzopen only sets it on the fd

    my $gz = gzopen(\*STDOUT, "wb")
	  or die "Cannot open stdout: $gzerrno\n" ;

    while (<>) {
        $gz->gzwrite($_) 
	    or die "error writing: $gzerrno\n" ;
    }

    $gz->gzclose ;

=head2 Compress::Zlib::memGzip

This function is used to create an in-memory gzip file. 
It creates a minimal gzip header.

    $dest = Compress::Zlib::memGzip($buffer) ;

If successful, it returns the in-memory gzip file, otherwise it returns
undef.

The buffer parameter can either be a scalar or a scalar reference.

=head1 CHECKSUM FUNCTIONS

Two functions are provided by I<zlib> to calculate a checksum. For the
Perl interface, the order of the two parameters in both functions has
been reversed. This allows both running checksums and one off
calculations to be done.

    $crc = adler32($buffer [,$crc]) ;
    $crc = crc32($buffer [,$crc]) ;

The buffer parameters can either be a scalar or a scalar reference.

If the $crc parameters is C<undef>, the crc value will be reset.

=head1 ACCESSING ZIP FILES

If you want to use this module to access zip files there are a number of
undocumented features in the zlib library you need to be aware of.

=over 5

=item 1.

When calling B<inflateInit> or B<deflateInit> the B<WindowBits> parameter
must be set to C<-MAX_WBITS>. This disables the creation of the zlib
header.

=item 2.

The zlib function B<inflate>, and so the B<inflate> method supplied in
this module, assume that there is at leat one trailing byte after the
compressed data stream. Normally this isn't a problem because both
the gzip and zip file formats will guarantee that there is data directly
after the compressed data stream.

=back

=head1 CONSTANTS

All the I<zlib> constants are automatically imported when you make use
of I<Compress::Zlib>.

=head1 AUTHOR

The I<Compress::Zlib> module was written by Paul Marquess,
F<[e-mail]>. The latest copy of the module can be
found on CPAN in F<modules/by-module/Compress/Compress-Zlib-x.x.tar.gz>.

The primary site for the I<zlib> compression library is
F<http://www.cdrom.com/pub/infozip/zlib/>.

=head1 MODIFICATION HISTORY

=head2 0.1 2nd October 1995.

First public release of I<Compress::Zlib>.


=head2 0.2 5th October 1995.

Fixed a minor allocation problem in Zlib.xs


=head2 0.3 12th October 1995.

Added prototype specification.


=head2 0.4 25th June 1996.

=over 5

=item 1.

Documentation update.

=item 2.

Upgraded to support zlib 1.0.2

=item 3.

Added dictionary interface.

=item 4.

Fixed bug in gzreadline - previously it would keep returning the same
buffer. This bug was reported by Helmut Jarausch

=item 5.

Removed dependancy to zutil.h and so dropped support for 
	
    DEF_MEM_LEVEL (use MAX_MEM_LEVEL instead)
    DEF_WBITS     (use MAX_WBITS instead)

=back

=head2 0.50 19th Feb 1997

=over 5

=item 1.

Confirmed that no changes were necessary for zlib 1.0.3 or 1.0.4.

=item 2.

The optional parameters for deflateInit and inflateInit can now be
specified as an associative array in addition to a reference to an
associative array. They can also accept the -Name syntax.

=item 3.

gzopen can now optionally take a reference to an open filehandle in
place of a filename. In this case it will call gzdopen.

=item 4.

Added gzstream example script.

=back

=head2 1.00 14 Nov 1997

=over 5

=item 1.

The following functions can now take a scalar reference in place of a
scalar for their buffer parameters:

    compress
    uncompress
    deflate
    inflate
    crc32
    adler32

This should mean applications that make use of the module don't have to
copy large buffers around.

=item 2.

Normally the inflate method consumes I<all> of the input buffer before
returning. The exception to this is when inflate detects the end of the
stream (Z_STREAM_END). In this case the input buffer need not be
completely consumed. To allow processing of file formats that embed a
deflation stream (e.g. zip, gzip), the inflate method now sets the
buffer parameter to be what remains after inflation.

When the return status is Z_STREAM_END, it will be what remains of the
buffer (if any) after deflation. When the status is Z_OK it will be an
empty string.

This change means that the buffer parameter must be a lvalue.

=item 3.

Fixed crc32 and adler32. They were both very broken. 

=item 4,

Added the Compress::Zlib::memGzip function.

=back

=head2 1.01 23 Nov 1997

=over 5

=item 1.

A number of fixes to the test suite and the example scripts to allow
them to work under win32. All courtesy of Gurusamy Sarathy.

=back

=head2 1.02 10 Jan 1998

=over 5

=item 1.

The return codes for gzread, gzreadline and gzwrite were documented
incorrectly as returning a status code.

=item 2.

The test harness was missing a "gzclose". This caused problem showed up
on an amiga. Thanks to Erik van Roode for reporting this one.

=item 3.

Patched zlib.t for OS/2. Thanks to Ilya Zakharevich for the patch.

=back

=head2 1.03 17 Mar 1999

=over 5

=item 1.

Updated to use the new PL_ symbols. 
Means the module can be built with Perl 5.005_5*

=head2 1.04 27 May 1999

=over 5

=item 1.

Bug 19990527.001: compress(undef) core dumps -- Fixed.

=back

=head2 1.05 3 June 1999

=over 5

=item 1.

Previous release used newSVpvn, which doesn't exist in 5.004_04 or
earlier. Changed to use newSVpv instead.

=item 2.

The module needs Perl 5.004 or better, so updated the version checking in
Zlib.pm and Makefile.PL

=back

=head2 1.06 20 September 1999

=over 5

=item 1.

Fixed a nasty problem where inflate could truncate the data
returned. Thanks to Douglas Thomson <[e-mail]> for
both spotting the problem and fixing the bug.

=item 2.

Added a note about the undocumented features in zlib that are required
when accessing zip files.

=item 3.

gzclose will now get called automaticallly when the gzip object is
destroyed.

=back

=head2 1.07 27 November 1999

=over 5

=item 1.

ANSI-ified the static functions in Zlib.xs

=item 2.

Added the ability to build zlib along with the module.
This feature is 90% based on a Makefile provided by Gurusamy Sarathy.

=back

=head2 1.08 27 January 2000

=over 5

=item 1.

uncompress was clobbering its input parameter. Now it doesn't.  
This bug was spotted by Deven T. Corzine.

=item 2.

If a variable that only ever contained a number was given to compress
or delate, it would not be compresed properly. Now it will be coerced
to a string and then compressed. This bug was spotted by Deven T. Corzine.

=back