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 filenamdle, $mode) ;
$status = $gz->gzread($buffer [,$size]) ;
$status = $gz->gzreadline($line) ;
$status = $gz->gzwrite($buffer) ;
$status = $gz->gzflush($flush) ;
$status = $gz->gzclose() ;
$errstring = $gz->gzerror() ;
$gzerrno
$dest = Compress::Zlib::memGzip($buffer) ;
$crc = adler32($buffer [,$crc]) ;
$crc = crc32($buffer [,$crc]) ;
ZLIB_VERSION
The module can be split into two general areas of functionality, namely in-memory compression/decompression and read/write access to gzip files. Each of these areas will be discussed separately below.
The main difference is that for both inflation and deflation, 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:
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 compatability, 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:
Z_BEST_SPEED, Z_BEST_COMPRESSION, and Z_DEFAULT_COMPRESSION.
The default is -Level =>Z_DEFAULT_COMPRESSION.
-Method =>Z_DEFLATED.
Defaults to -WindowBits =>MAX_WBITS.
Defaults to -MemLevel =>MAX_MEM_LEVEL.
Z_DEFAULT_STRATEGY, Z_FILTERED and Z_HUFFMAN_ONLY.
The default is -Strategy =>Z_DEFAULT_STRATEGY.
$d-dict_adler()>.
The default is no dictionary.
The default is 4096.
deflateInit( -Bufsize => 300,
-Level => Z_BEST_SPEED ) ;
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 necessarily 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.
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.
use Compress::Zlib ;
binmode STDIN;
binmode STDOUT;
$x = deflateInit()
or die "Cannot create a deflation stream\n" ;
while (<>)
{
($output, $status) = $x->deflate($_) ;
$status == Z_OK
or die "deflation failed\n" ;
print $output ;
}
($output, $status) = $x->flush() ;
$status == Z_OK
or die "deflation failed\n" ;
print $output ;
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 $status 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 compatability, 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:
Defaults to -WindowBits =>MAX_WBITS.
Default is 4096.
inflateInit( -Bufsize => 300 ) ;
Returns Z_OK if successful and Z_STREAM_END if the end of the compressed data has been reached.
The $buffer parameter is modified by inflate. On completion 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 contains what (if anything) was stored in the input buffer
after the deflated data stream.
This feature is needed when processing a file format that encapsulates a deflated data stream (e.g. gzip, zip).
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 ;
The source buffer can either be a scalar or a scalar reference.
The source buffer can either be a scalar or a scalar reference.
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 compression 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 section, gzstream, uses this feature.
It is legal to intermix calls to gzread and gzreadline.
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 '\n'.
Refer to the zlib documentation for the valid values of $flush.
Z_OK
Z_STREAM_END
Z_ERRNO
Z_STREAM_ERROR
Z_DATA_ERROR
Z_MEM_ERROR
Z_BUF_ERROR
As with gzerror() it returns an error number in numeric context and an error message in
string context. Unlike gzerror() though, the error message will correspond to the zlib message when the error is associated with zlib itself, or the UNIX error message 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 context. Use gzerror() to check for specific zlib errors. The gzcat example below shows how the variable can be used safely.
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 gzreadline. It implements a very simple 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, gzstream, does the opposite of the 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 ;
$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.
$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.
The zlib compression library was written by Jean-loup Gailly gzip@prep.ai.mit.edu and Mark Adler madler@alumni.caltech.edu. It is available at ftp://ftp.uu.net/pub/archiving/zip/zlib* and ftp://swrinde.nde.swri.edu/pub/png/src/zlib*. Alternatively check out the zlib home page at http://quest.jpl.nasa.gov/zlib/.
Questions about zlib itself should be sent to zlib@quest.jpl.nasa.gov or, if this fails, to the addresses given for the authors above.
compress
uncompress
deflate
inflate
crc32
adler32
This should mean applications that make use of the module don't have to copy large buffers around.
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.