zlib(3)

NAME

Compress::Zlib - Interface to zlib compression library

SYNOPSIS

use Compress::Zlib ;
($d, $status) = deflateInit( [OPT] ) ;
($out, $status) = $d->deflate($buffer) ;
($out, $status) = $d->flush() ;
$d->dict_adler() ;
($i, $status) = inflateInit( [OPT] ) ;
($out, $status) = $i->inflate($buffer) ;
$i->dict_adler() ;
$dest = compress($source) ;
$dest = uncompress($source) ;
$gz = gzopen($filename or filehandle, $mode) ;
$bytesread = $gz->gzread($buffer [,$size]) ;
$bytesread = $gz->gzreadline($line) ;
$byteswritten = $gz->gzwrite($buffer) ;
$status = $gz->gzflush($flush) ;
$status = $gz->gzclose() ;
$errstring = $gz->gzerror() ;
$gzerrno
$dest = Compress::Zlib::memGzip($buffer) ;
$dest = Compress::Zlib::memGunzip($buffer) ;
$crc = adler32($buffer [,$crc]) ;
$crc = crc32($buffer [,$crc]) ;
ZLIB_VERSION

DESCRIPTION

The Compress::Zlib module provides a Perl interface to the zlib compression library (see "AUTHOR" for details about
where to get zlib). Most of the functionality provided by
zlib is available in Compress::Zlib.

The module can be split into two general areas of func
tionality, namely in-memory compression/decompression and
read/write access to gzip files. Each of these areas will
be discussed separately below.

DEFLATE

The interface Compress::Zlib provides to the in-memory deflate (and inflate) functions has been modified to fit into a Perl model.

The main difference is that for both inflation and defla
tion, the Perl interface will always consume the complete
input buffer before returning. Also the output buffer
returned will be automatically grown to fit the amount of
output available.

Here is a definition of the interface available:

($d, $status) = deflateInit( [OPT] )

Initialises a deflation stream.

It combines the features of the zlib functions
deflateInit, deflateInit2 and deflateSetDictionary.

If successful, it will return the initialised deflation
stream, $d and $status of "Z_OK" in a list context. In scalar context it returns the deflation stream, $d, only.

If not successful, the returned deflation stream ($d) will
be undef and $status will hold the exact zlib error code.

The function optionally takes a number of named options
specified as "-Name=>value" pairs. This allows individual
options to be tailored without having to specify them all
in the parameter list.

For backward compatibility, it is also possible to pass
the parameters as a reference to a hash containing the
name=>value pairs.

The function takes one optional parameter, a reference to
a hash. The contents of the hash allow the deflation
interface to be tailored.

Here is a list of the valid options:

-Level

Defines the compression level. Valid values are 1
through 9, "Z_BEST_SPEED", "Z_BEST_COMPRESSION", and
"Z_DEFAULT_COMPRESSION".

The default is "-Level =>Z_DEFAULT_COMPRESSION".

-Method

Defines the compression method. The only valid value
at present (and the default) is "-Method
=>Z_DEFLATED".

-WindowBits

For a definition of the meaning and valid values for
WindowBits refer to the zlib documentation for deflateInit2.

Defaults to "-WindowBits =>MAX_WBITS".

-MemLevel

For a definition of the meaning and valid values for
MemLevel refer to the zlib documentation for deflateInit2.

Defaults to "-MemLevel =>MAX_MEM_LEVEL".

-Strategy

Defines the strategy used to tune the compression.
The valid values are "Z_DEFAULT_STRATEGY", "Z_FIL
TERED" and "Z_HUFFMAN_ONLY".

The default is "-Strategy =>Z_DEFAULT_STRATEGY".

-Dictionary

When a dictionary is specified Compress::Zlib will automatically call deflateSetDictionary directly after calling deflateInit. The Adler32 value for the dictionary can be obtained by calling the method
"$d-"dict_adler()>.

The default is no dictionary.

-Bufsize

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

The default is 4096.

Here is an example of using the deflateInit optional parameter list to override the default buffer size and
compression level. All other options will take their
default values.

deflateInit( -Bufsize => 300,

-Level => Z_BEST_SPEED ) ;

($out, $status) = $$dd->deflate($buffer)

Deflates the contents of $buffer. The buffer can either be a scalar or a scalar reference. When finished, $buffer
will be completely processed (assuming there were no
errors). If the deflation was successful it returns the
deflated output, $out, and a status value, $status, of "Z_OK".

On error, $out will be undef and $status will contain the zlib error code.

In a scalar context deflate will return $out only.

As with the deflate function in zlib, it is not necessar ily the case that any output will be produced by this
method. So don't rely on the fact that $out is empty for
an error test.

($out, $status) = $$dd->flush([flush_type])

Finishes the deflation. Any pending output will be
returned via $out. $status will have a value "Z_OK" if successful.

In a scalar context flush will return $out only.

Note that flushing can degrade the compression ratio, so
it should only be used to terminate a decompression.

By default the "flush_type" used is "Z_FINISH". Other
valid values for "flush_type" are Z_NO_FLUSH, Z_PAR
TIAL_FLUSH, Z_SYNC_FLUSH and Z_FULL_FLUSH. It is strongly
recommended that you only set the "flush_type" parameter
if you fully understand what it does. See the "zlib" docu
mentation for details.

$d->ddiicctt__aaddlleerr(())

Returns the adler32 value for the dictionary.

Example

Here is a trivial example of using deflate. It simply
reads standard input, deflates it and writes it to
standard output.

use strict ;
use warnings ;

use Compress::Zlib ;

binmode STDIN;
binmode STDOUT;
my $x = deflateInit()

or die "Cannot create a deflation stream0 ;

my ($output, $status) ;
while (<>)
{

($output, $status) = $x->deflate($_) ;

$status == Z_OK

or die "deflation failed0 ;

print $output ;

}

($output, $status) = $x->flush() ;

$status == Z_OK

or die "deflation failed0 ;

print $output ;

INFLATE

Here is a definition of the interface:

($i, $status) = iinnffllaatteeIInniitt(())

Initialises an inflation stream.

In a list context it returns the inflation stream, $i, and
the zlib status code ($status). In a scalar context it returns the inflation stream only.

If successful, $i will hold the inflation stream and $sta
tus will be "Z_OK".

If not successful, $i will be undef and $status will hold the zlib error code.

The function optionally takes a number of named options
specified as "-Name=>value" pairs. This allows individual
options to be tailored without having to specify them all
in the parameter list.

For backward compatibility, it is also possible to pass
the parameters as a reference to a hash containing the
name=>value pairs.

The function takes one optional parameter, a reference to
a hash. The contents of the hash allow the deflation
interface to be tailored.

Here is a list of the valid options:

-WindowBits

For a definition of the meaning and valid values for
WindowBits refer to the zlib documentation for inflateInit2.

Defaults to "-WindowBits =>MAX_WBITS".

-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 Bufsize.

Default is 4096.

-Dictionary

The default is no dictionary.

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

inflateInit( -Bufsize => 300 ) ;

($out, $status) = $$ii->inflate($buffer)

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

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

The $buffer parameter is modified by "inflate". On comple
tion it will contain what remains of the input buffer
after inflation. This means that $buffer will be an empty
string when the return status is "Z_OK". When the return
status is "Z_STREAM_END" the $buffer parameter will con
tains 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).

$i->ddiicctt__aaddlleerr(())

Returns the adler32 value for the dictionary.

Example

Here is an example of using inflate.

use strict ;
use warnings ;

use Compress::Zlib ;

my $x = inflateInit()

or die "Cannot create a inflation stream0 ;

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

my ($output, $status) ;
while (read(STDIN, $input, 4096))
{

($output, $status) = $x->inflate(nput) ;

print $output

if $status == Z_OK or $status == Z_STREAM_END

;

last if $status != Z_OK ;

}

die "inflation failed0

unless $status == Z_STREAM_END ;

COMPRESS/UNCOMPRESS

Two high-level functions are provided by zlib to perform
in-memory compression. They are compress and uncompress. Two Perl subs are provided which provide similar function
ality.

$dest = compress($source) ;

Compresses $source. If successful it returns the com pressed data. Otherwise it returns undef.

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

$dest = uncompress($source) ;

Uncompresses $source. If successful it returns the
uncompressed data. Otherwise it returns undef.

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

GZIP INTERFACE

A number of functions are supplied in zlib for reading and
writing 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
zlib. Any differences are explained below.

$gz = gzopen(filename or filehandle, mode)

This function operates identically to the zlib equiv
alent except that it returns an object which is used
to access the other gzip methods.

As with the zlib equivalent, the mode parameter is used to specify both whether the file is opened for
reading or writing and to optionally specify a a com
pression level. Refer to the zlib documentation for
the exact format of the 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 sec
tion, gzstream, uses this feature.

$bytesread = $gz->gzread($buffer [, $$ssiizzee]) ;

Reads $size bytes from the compressed file into
$buffer. If $size is not specified, it will default to 4096. If the scalar $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.

$bytesread = $gz->gzreadline($line) ;

Reads the next line from the compressed file into
$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 gzread and gzread line.

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

$byteswritten = $gz->gzwrite($buffer) ;

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

$status = $gz->gzflush($flush) ;

Flushes all pending output into the compressed file.
Works identically to the zlib function it interfaces
to. Note that the use of gzflush can degrade compres sion.

Refer to the zlib documentation for the valid values
of $flush.

$gz->gzclose

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

$gz->gzerror

Returns the zlib error message or number for the last
operation associated with $gz. The return value will
be the zlib error number when used in a numeric con
text and the zlib error message when used in a string
context. The 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

$gzerrno

The $gzerrno scalar holds the error code associated with the most recent gzip routine. Note that unlike
ggzzeerrrroorr(()), the error is not associated with a partic ular file.

As with ggzzeerrrroorr(()) it returns an error number in numeric context and an error message in string con
text. Unlike ggzzeerrrroorr(()) though, the error message will correspond to the zlib message when the error is
associated with zlib itself, or the UNIX error mes
sage when it is not (i.e. zlib returned "Z_ERRORNO").

As there is an overlap between the error numbers used
by zlib and UNIX, $gzerrno should only be used to check for the presence of an error in numeric con
text. Use ggzzeerrrroorr(()) to check for specific zlib errors. The gzcat example below shows how the vari
able can be used safely.

Examples

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

use strict ;
use warnings ;

use Compress::Zlib ;

die "Usage: gzcat file...0

unless @ARGV ;

my $file ;

foreach $file (@ARGV) {

my $buffer ;

my $gz = gzopen($file, "rb")

or die "Cannot open $file: $gzerrno0 ;

print $buffer while $gz->gzread($buffer) > 0 ;

die "Error reading from $file: $gzerrno" . ($gzer

rno+0) . "0

if $gzerrno != Z_STREAM_END ;

$gz->gzclose() ;

}

Below is a script which makes use of gzreadline. It imple ments a very simple grep like script.

use strict ;
use warnings ;

use Compress::Zlib ;

die "Usage: gzgrep pattern file...0

unless @ARGV >= 2;

my $pattern = shift ;

my $file ;

foreach $file (@ARGV) {

my $gz = gzopen($file, "rb")

or die "Cannot open $file: $gzerrno0 ;

while ($gz->gzreadline($_) > 0) {

print if /$pattern/ ;

}

die "Error reading from $file: $gzerrno0

if $gzerrno != Z_STREAM_END ;

$gz->gzclose() ;

}

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

use strict ;
use warnings ;

use Compress::Zlib ;

binmode STDOUT; # gzopen only sets it on the fd

my $gz = gzopen(TDOUT, "wb")

or die "Cannot open stdout: $gzerrno0 ;

while (<>) {

$gz->gzwrite($_)
or die "error writing: $gzerrno0 ;

}

$gz->gzclose ;

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, other
wise it returns undef.

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

Compress::Zlib::memGunzip

This function is used to uncompress an in-memory gzip
file.

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

If successful, it returns the uncompressed gzip file, oth
erwise it returns undef.

The buffer parameter can either be a scalar or a scalar
reference. The contents of the buffer parameter are
destroyed after calling this function.

CHECKSUM FUNCTIONS

Two functions are provided by zlib to calculate a check
sum. For the Perl interface, the order of the two parame
ters 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 "undef", the crc value will be
reset.

ACCESSING ZIP FILES

Although it is possible to use this module to access .zip
files, there is a module on CPAN that will do all the hard
work for you. Check out

http://www.cpan.org/modules/by-module/Archive/Archive

Zip-*.tar.gz

Assuming you don't 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.

1. When calling inflateInit or deflateInit the Window Bits parameter must be set to "-MAX_WBITS". This dis
ables the creation of the zlib header.

2. The zlib function inflate, and so the inflate method supplied in this module, assume that there is at
least 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.

CONSTANTS

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

AUTHOR

The Compress::Zlib module was written by Paul Marquess, Paul.Marquess@btinternet.com. The latest copy of the mod ule can be found on CPAN in modules/by-module/Com_ press/Compress-Zlib-x.x.tar.gz.

The primary site for the zlib compression library is
http://www.gzip.org/zlib/.

MODIFICATION HISTORY

See the README file.

perl v5.8.0 2002-07-31 Zlib(3)