package Compress::Zlib;
require 5.006 ;
require Exporter;
use Carp ;
use IO::Handle ;
use Scalar::Util qw(dualvar);
use IO::Compress::Base::Common 2.060 ;
use Compress::Raw::Zlib 2.060 ;
use IO::Compress::Gzip 2.060 ;
use IO::Uncompress::Gunzip 2.060 ;
use strict ;
use warnings ;
use bytes ;
our ($VERSION, $XS_VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
$VERSION = '2.060';
$XS_VERSION = $VERSION;
$VERSION = eval $VERSION;
@ISA = qw(Exporter);
# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
@EXPORT = qw(
deflateInit inflateInit
compress uncompress
gzopen $gzerrno
);
push @EXPORT, @Compress::Raw::Zlib::EXPORT ;
@EXPORT_OK = qw(memGunzip memGzip zlib_version);
%EXPORT_TAGS = (
ALL => \@EXPORT
);
BEGIN
{
*zlib_version = \&Compress::Raw::Zlib::zlib_version;
}
use constant FLAG_APPEND => 1 ;
use constant FLAG_CRC => 2 ;
use constant FLAG_ADLER => 4 ;
use constant FLAG_CONSUME_INPUT => 8 ;
our (@my_z_errmsg);
@my_z_errmsg = (
"need dictionary", # Z_NEED_DICT 2
"stream end", # Z_STREAM_END 1
"", # Z_OK 0
"file error", # Z_ERRNO (-1)
"stream error", # Z_STREAM_ERROR (-2)
"data error", # Z_DATA_ERROR (-3)
"insufficient memory", # Z_MEM_ERROR (-4)
"buffer error", # Z_BUF_ERROR (-5)
"incompatible version",# Z_VERSION_ERROR(-6)
);
sub _set_gzerr
{
my $value = shift ;
if ($value == 0) {
$Compress::Zlib::gzerrno = 0 ;
}
elsif ($value == Z_ERRNO() || $value > 2) {
$Compress::Zlib::gzerrno = $! ;
}
else {
$Compress::Zlib::gzerrno = dualvar($value+0, $my_z_errmsg[2 - $value]);
}
return $value ;
}
sub _set_gzerr_undef
{
_set_gzerr(@_);
return undef;
}
sub _save_gzerr
{
my $gz = shift ;
my $test_eof = shift ;
my $value = $gz->errorNo() || 0 ;
my $eof = $gz->eof() ;
if ($test_eof) {
# gzread uses Z_STREAM_END to denote a successful end
$value = Z_STREAM_END() if $gz->eof() && $value == 0 ;
}
_set_gzerr($value) ;
}
sub gzopen($$)
{
my ($file, $mode) = @_ ;
my $gz ;
my %defOpts = (Level => Z_DEFAULT_COMPRESSION(),
Strategy => Z_DEFAULT_STRATEGY(),
);
my $writing ;
$writing = ! ($mode =~ /r/i) ;
$writing = ($mode =~ /[wa]/i) ;
$defOpts{Level} = $1 if $mode =~ /(\d)/;
$defOpts{Strategy} = Z_FILTERED() if $mode =~ /f/i;
$defOpts{Strategy} = Z_HUFFMAN_ONLY() if $mode =~ /h/i;
$defOpts{Append} = 1 if $mode =~ /a/i;
my $infDef = $writing ? 'deflate' : 'inflate';
my @params = () ;
croak "gzopen: file parameter is not a filehandle or filename"
unless isaFilehandle $file || isaFilename $file ||
(ref $file && ref $file eq 'SCALAR');
return undef unless $mode =~ /[rwa]/i ;
_set_gzerr(0) ;
if ($writing) {
$gz = new IO::Compress::Gzip($file, Minimal => 1, AutoClose => 1,
%defOpts)
or $Compress::Zlib::gzerrno = $IO::Compress::Gzip::GzipError;
}
else {
$gz = new IO::Uncompress::Gunzip($file,
Transparent => 1,
Append => 0,
AutoClose => 1,
MultiStream => 1,
Strict => 0)
or $Compress::Zlib::gzerrno = $IO::Uncompress::Gunzip::GunzipError;
}
return undef
if ! defined $gz ;
bless [$gz, $infDef], 'Compress::Zlib::gzFile';
}
sub Compress::Zlib::gzFile::gzread
{
my $self = shift ;
return _set_gzerr(Z_STREAM_ERROR())
if $self->[1] ne 'inflate';
my $len = defined $_[1] ? $_[1] : 4096 ;
my $gz = $self->[0] ;
if ($self->gzeof() || $len == 0) {
# Zap the output buffer to match ver 1 behaviour.
$_[0] = "" ;
_save_gzerr($gz, 1);
return 0 ;
}
my $status = $gz->read($_[0], $len) ;
_save_gzerr($gz, 1);
return $status ;
}
sub Compress::Zlib::gzFile::gzreadline
{
my $self = shift ;
my $gz = $self->[0] ;
{
# Maintain backward compatibility with 1.x behaviour
# It didn't support $/, so this can't either.
local $/ = "\n" ;
$_[0] = $gz->getline() ;
}
_save_gzerr($gz, 1);
return defined $_[0] ? length $_[0] : 0 ;
}
sub Compress::Zlib::gzFile::gzwrite
{
my $self = shift ;
my $gz = $self->[0] ;
return _set_gzerr(Z_STREAM_ERROR())
if $self->[1] ne 'deflate';
$] >= 5.008 and (utf8::downgrade($_[0], 1)
or croak "Wide character in gzwrite");
my $status = $gz->write($_[0]) ;
_save_gzerr($gz);
return $status ;
}
sub Compress::Zlib::gzFile::gztell
{
my $self = shift ;
my $gz = $self->[0] ;
my $status = $gz->tell() ;
_save_gzerr($gz);
return $status ;
}
sub Compress::Zlib::gzFile::gzseek
{
my $self = shift ;
my $offset = shift ;
my $whence = shift ;
my $gz = $self->[0] ;
my $status ;
eval { $status = $gz->seek($offset, $whence) ; };
if ($@)
{
my $error = $@;
$error =~ s/^.*: /gzseek: /;
$error =~ s/ at .* line \d+\s*$//;
croak $error;
}
_save_gzerr($gz);
return $status ;
}
sub Compress::Zlib::gzFile::gzflush
{
my $self = shift ;
my $f = shift ;
my $gz = $self->[0] ;
my $status = $gz->flush($f) ;
my $err = _save_gzerr($gz);
return $status ? 0 : $err;
}
sub Compress::Zlib::gzFile::gzclose
{
my $self = shift ;
my $gz = $self->[0] ;
my $status = $gz->close() ;
my $err = _save_gzerr($gz);
return $status ? 0 : $err;
}
sub Compress::Zlib::gzFile::gzeof
{
my $self = shift ;
my $gz = $self->[0] ;
return 0
if $self->[1] ne 'inflate';
my $status = $gz->eof() ;
_save_gzerr($gz);
return $status ;
}
sub Compress::Zlib::gzFile::gzsetparams
{
my $self = shift ;
croak "Usage: Compress::Zlib::gzFile::gzsetparams(file, level, strategy)"
unless @_ eq 2 ;
my $gz = $self->[0] ;
my $level = shift ;
my $strategy = shift;
return _set_gzerr(Z_STREAM_ERROR())
if $self->[1] ne 'deflate';
my $status = *$gz->{Compress}->deflateParams(-Level => $level,
-Strategy => $strategy);
_save_gzerr($gz);
return $status ;
}
sub Compress::Zlib::gzFile::gzerror
{
my $self = shift ;
my $gz = $self->[0] ;
return $Compress::Zlib::gzerrno ;
}
sub compress($;$)
{
my ($x, $output, $err, $in) =('', '', '', '') ;
if (ref $_[0] ) {
$in = $_[0] ;
croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
}
else {
$in = \$_[0] ;
}
$] >= 5.008 and (utf8::downgrade($$in, 1)
or croak "Wide character in compress");
my $level = (@_ == 2 ? $_[1] : Z_DEFAULT_COMPRESSION() );
$x = Compress::Raw::Zlib::_deflateInit(FLAG_APPEND,
$level,
Z_DEFLATED,
MAX_WBITS,
MAX_MEM_LEVEL,
Z_DEFAULT_STRATEGY,
4096,
'')
or return undef ;
$err = $x->deflate($in, $output) ;
return undef unless $err == Z_OK() ;
$err = $x->flush($output) ;
return undef unless $err == Z_OK() ;
return $output ;
}
sub uncompress($)
{
my ($output, $in) =('', '') ;
if (ref $_[0] ) {
$in = $_[0] ;
croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
}
else {
$in = \$_[0] ;
}
$] >= 5.008 and (utf8::downgrade($$in, 1)
or croak "Wide character in uncompress");
my ($obj, $status) = Compress::Raw::Zlib::_inflateInit(0,
MAX_WBITS, 4096, "") ;
$status == Z_OK
or return undef;
$obj->inflate($in, $output) == Z_STREAM_END
or return undef;
return $output;
}
sub deflateInit(@)
{
my ($got) = ParseParameters(0,
{
'bufsize' => [IO::Compress::Base::Common::Parse_unsigned, 4096],
'level' => [IO::Compress::Base::Common::Parse_signed, Z_DEFAULT_COMPRESSION()],
'method' => [IO::Compress::Base::Common::Parse_unsigned, Z_DEFLATED()],
'windowbits' => [IO::Compress::Base::Common::Parse_signed, MAX_WBITS()],
'memlevel' => [IO::Compress::Base::Common::Parse_unsigned, MAX_MEM_LEVEL()],
'strategy' => [IO::Compress::Base::Common::Parse_unsigned, Z_DEFAULT_STRATEGY()],
'dictionary' => [IO::Compress::Base::Common::Parse_any, ""],
}, @_ ) ;
croak "Compress::Zlib::deflateInit: Bufsize must be >= 1, you specified " .
$got->getValue('bufsize')
unless $got->getValue('bufsize') >= 1;
my $obj ;
my $status = 0 ;
($obj, $status) =
Compress::Raw::Zlib::_deflateInit(0,
$got->getValue('level'),
$got->getValue('method'),
$got->getValue('windowbits'),
$got->getValue('memlevel'),
$got->getValue('strategy'),
$got->getValue('bufsize'),
$got->getValue('dictionary')) ;
my $x = ($status == Z_OK() ? bless $obj, "Zlib::OldDeflate" : undef) ;
return wantarray ? ($x, $status) : $x ;
}
sub inflateInit(@)
{
my ($got) = ParseParameters(0,
{
'bufsize' => [IO::Compress::Base::Common::Parse_unsigned, 4096],
'windowbits' => [IO::Compress::Base::Common::Parse_signed, MAX_WBITS()],
'dictionary' => [IO::Compress::Base::Common::Parse_any, ""],
}, @_) ;
croak "Compress::Zlib::inflateInit: Bufsize must be >= 1, you specified " .
$got->getValue('bufsize')
unless $got->getValue('bufsize') >= 1;
my $status = 0 ;
my $obj ;
($obj, $status) = Compress::Raw::Zlib::_inflateInit(FLAG_CONSUME_INPUT,
$got->getValue('windowbits'),
$got->getValue('bufsize'),
$got->getValue('dictionary')) ;
my $x = ($status == Z_OK() ? bless $obj, "Zlib::OldInflate" : undef) ;
wantarray ? ($x, $status) : $x ;
}
package Zlib::OldDeflate ;
our (@ISA);
@ISA = qw(Compress::Raw::Zlib::deflateStream);
sub deflate
{
my $self = shift ;
my $output ;
my $status = $self->SUPER::deflate($_[0], $output) ;
wantarray ? ($output, $status) : $output ;
}
sub flush
{
my $self = shift ;
my $output ;
my $flag = shift || Compress::Zlib::Z_FINISH();
my $status = $self->SUPER::flush($output, $flag) ;
wantarray ? ($output, $status) : $output ;
}
package Zlib::OldInflate ;
our (@ISA);
@ISA = qw(Compress::Raw::Zlib::inflateStream);
sub inflate
{
my $self = shift ;
my $output ;
my $status = $self->SUPER::inflate($_[0], $output) ;
wantarray ? ($output, $status) : $output ;
}
package Compress::Zlib ;
use IO::Compress::Gzip::Constants 2.060 ;
sub memGzip($)
{
_set_gzerr(0);
my $x = Compress::Raw::Zlib::_deflateInit(FLAG_APPEND|FLAG_CRC,
Z_BEST_COMPRESSION,
Z_DEFLATED,
-MAX_WBITS(),
MAX_MEM_LEVEL,
Z_DEFAULT_STRATEGY,
4096,
'')
or return undef ;
# if the deflation buffer isn't a reference, make it one
my $string = (ref $_[0] ? $_[0] : \$_[0]) ;
$] >= 5.008 and (utf8::downgrade($$string, 1)
or croak "Wide character in memGzip");
my $out;
my $status ;
$x->deflate($string, $out) == Z_OK
or return undef ;
$x->flush($out) == Z_OK
or return undef ;
return IO::Compress::Gzip::Constants::GZIP_MINIMUM_HEADER .
$out .
pack("V V", $x->crc32(), $x->total_in());
}
sub _removeGzipHeader($)
{
my $string = shift ;
return Z_DATA_ERROR()
if length($$string) < GZIP_MIN_HEADER_SIZE ;
my ($magic1, $magic2, $method, $flags, $time, $xflags, $oscode) =
unpack ('CCCCVCC', $$string);
return Z_DATA_ERROR()
unless $magic1 == GZIP_ID1 and $magic2 == GZIP_ID2 and
$method == Z_DEFLATED() and !($flags & GZIP_FLG_RESERVED) ;
substr($$string, 0, GZIP_MIN_HEADER_SIZE) = '' ;
# skip extra field
if ($flags & GZIP_FLG_FEXTRA)
{
return Z_DATA_ERROR()
if length($$string) < GZIP_FEXTRA_HEADER_SIZE ;
my ($extra_len) = unpack ('v', $$string);
$extra_len += GZIP_FEXTRA_HEADER_SIZE;
return Z_DATA_ERROR()
if length($$string) < $extra_len ;
substr($$string, 0, $extra_len) = '';
}
# skip orig name
if ($flags & GZIP_FLG_FNAME)
{
my $name_end = index ($$string, GZIP_NULL_BYTE);
return Z_DATA_ERROR()
if $name_end == -1 ;
substr($$string, 0, $name_end + 1) = '';
}
# skip comment
if ($flags & GZIP_FLG_FCOMMENT)
{
my $comment_end = index ($$string, GZIP_NULL_BYTE);
return Z_DATA_ERROR()
if $comment_end == -1 ;
substr($$string, 0, $comment_end + 1) = '';
}
# skip header crc
if ($flags & GZIP_FLG_FHCRC)
{
return Z_DATA_ERROR()
if length ($$string) < GZIP_FHCRC_SIZE ;
substr($$string, 0, GZIP_FHCRC_SIZE) = '';
}
return Z_OK();
}
sub _ret_gun_error
{
$Compress::Zlib::gzerrno = $IO::Uncompress::Gunzip::GunzipError;
return undef;
}
sub memGunzip($)
{
# if the buffer isn't a reference, make it one
my $string = (ref $_[0] ? $_[0] : \$_[0]);
$] >= 5.008 and (utf8::downgrade($$string, 1)
or croak "Wide character in memGunzip");
_set_gzerr(0);
my $status = _removeGzipHeader($string) ;
$status == Z_OK()
or return _set_gzerr_undef($status);
my $bufsize = length $$string > 4096 ? length $$string : 4096 ;
my $x = Compress::Raw::Zlib::_inflateInit(FLAG_CRC | FLAG_CONSUME_INPUT,
-MAX_WBITS(), $bufsize, '')
or return _ret_gun_error();
my $output = '' ;
$status = $x->inflate($string, $output);
if ( $status == Z_OK() )
{
_set_gzerr(Z_DATA_ERROR());
return undef;
}
return _ret_gun_error()
if ($status != Z_STREAM_END());
if (length $$string >= 8)
{
my ($crc, $len) = unpack ("VV", substr($$string, 0, 8));
substr($$string, 0, 8) = '';
return _set_gzerr_undef(Z_DATA_ERROR())
unless $len == length($output) and
$crc == Compress::Raw::Zlib::crc32($output);
}
else
{
$$string = '';
}
return $output;
}
# Autoload methods go after __END__, and are processed by the autosplit program.
1;
__END__
=head1 NAME
Compress::Zlib - Interface to zlib compression library
=head1 SYNOPSIS
use Compress::Zlib ;
($d, $status) = deflateInit( [OPT] ) ;
$status = $d->deflate($input, $output) ;
$status = $d->flush([$flush_type]) ;
$d->deflateParams(OPTS) ;
$d->deflateTune(OPTS) ;
$d->dict_adler() ;
$d->crc32() ;
$d->adler32() ;
$d->total_in() ;
$d->total_out() ;
$d->msg() ;
$d->get_Strategy();
$d->get_Level();
$d->get_BufSize();
($i, $status) = inflateInit( [OPT] ) ;
$status = $i->inflate($input, $output [, $eof]) ;
$status = $i->inflateSync($input) ;
$i->dict_adler() ;
$d->crc32() ;
$d->adler32() ;
$i->total_in() ;
$i->total_out() ;
$i->msg() ;
$d->get_BufSize();
$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) ;
$offset = $gz->gztell() ;
$status = $gz->gzseek($offset, $whence) ;
$status = $gz->gzclose() ;
$status = $gz->gzeof() ;
$status = $gz->gzsetparams($level, $strategy) ;
$errstring = $gz->gzerror() ;
$gzerrno
$dest = Compress::Zlib::memGzip($buffer) ;
$dest = Compress::Zlib::memGunzip($buffer) ;
$crc = adler32($buffer [,$crc]) ;
$crc = crc32($buffer [,$crc]) ;
$crc = adler32_combine($crc1, $crc2, $len2)l
$crc = crc32_combine($adler1, $adler2, $len2)
my $version = Compress::Raw::Zlib::zlib_version();
=head1 DESCRIPTION
The I<Compress::Zlib> module provides a Perl interface to the I<zlib>
compression library (see L</AUTHOR> for details about where to get
I<zlib>).
The C<Compress::Zlib> module can be split into two general areas of
functionality, namely a simple read/write interface to I<gzip> files
and a low-level in-memory compression/decompression interface.
Each of these areas will be discussed in the following sections.
=head2 Notes for users of Compress::Zlib version 1
The main change in C<Compress::Zlib> version 2.x is that it does not now
interface directly to the zlib library. Instead it uses the
C<IO::Compress::Gzip> and C<IO::Uncompress::Gunzip> modules for
reading/writing gzip files, and the C<Compress::Raw::Zlib> module for some
low-level zlib access.
The interface provided by version 2 of this module should be 100% backward
compatible with version 1. If you find a difference in the expected
behaviour please contact the author (See L</AUTHOR>). See L<GZIP INTERFACE>
With the creation of the C<IO::Compress> and C<IO::Uncompress> modules no
new features are planned for C<Compress::Zlib> - the new modules do
everything that C<Compress::Zlib> does and then some. Development on
C<Compress::Zlib> will be limited to bug fixes only.
If you are writing new code, your first port of call should be one of the
new C<IO::Compress> or C<IO::Uncompress> modules.
=head1 GZIP INTERFACE
A number of functions are supplied in I<zlib> for reading and writing
I<gzip> files that conform to RFC 1952. This module provides an interface
to most of them.
If you have previously used C<Compress::Zlib> 1.x, the following
enhancements/changes have been made to the C<gzopen> interface:
=over 5
=item 1
If you want to open either STDIN or STDOUT with C<gzopen>, you can now
optionally use the special filename "C<->" as a synonym for C<\*STDIN> and
C<\*STDOUT>.
=item 2
In C<Compress::Zlib> version 1.x, C<gzopen> used the zlib library to open
the underlying file. This made things especially tricky when a Perl
filehandle was passed to C<gzopen>. Behind the scenes the numeric C file
descriptor had to be extracted from the Perl filehandle and this passed to
the zlib library.
Apart from being non-portable to some operating systems, this made it
difficult to use C<gzopen> in situations where you wanted to extract/create
a gzip data stream that is embedded in a larger file, without having to
resort to opening and closing the file multiple times.
It also made it impossible to pass a perl filehandle that wasn't associated
with a real filesystem file, like, say, an C<IO::String>.
In C<Compress::Zlib> version 2.x, the C<gzopen> interface has been
completely rewritten to use the L<IO::Compress::Gzip|IO::Compress::Gzip>
for writing gzip files and L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>
for reading gzip files. None of the limitations mentioned above apply.
=item 3
Addition of C<gzseek> to provide a restricted C<seek> interface.
=item 4.
Added C<gztell>.
=back
A more complete and flexible interface for reading/writing gzip
files/buffers is included with the module C<IO-Compress-Zlib>. See
L<IO::Compress::Gzip|IO::Compress::Gzip> and
L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for more details.
=over 5
=item B<$gz = gzopen($filename, $mode)>
=item B<$gz = gzopen($filehandle, $mode)>
This function opens either the I<gzip> file C<$filename> for reading or
writing or attaches to the opened filehandle, C<$filehandle>.
It returns an object on success and C<undef> on failure.
When writing a gzip file this interface will I<always> create the smallest
possible gzip header (exactly 10 bytes). If you want greater control over
what gets stored in the gzip header (like the original filename or a
comment) use L<IO::Compress::Gzip|IO::Compress::Gzip> instead. Similarly if
you want to read the contents of the gzip header use
L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
The second parameter, C<$mode>, is used to specify whether the file is
opened for reading or writing and to optionally specify a compression
level and compression strategy when writing. The format of the C<$mode>
parameter is similar to the mode parameter to the 'C' function C<fopen>,
so "rb" is used to open for reading, "wb" for writing and "ab" for
appending (writing at the end of the file).
To specify a compression level when writing, append a digit between 0
and 9 to the mode string -- 0 means no compression and 9 means maximum
compression.
If no compression level is specified Z_DEFAULT_COMPRESSION is used.
To specify the compression strategy when writing, append 'f' for filtered
data, 'h' for Huffman only compression, or 'R' for run-length encoding.
If no strategy is specified Z_DEFAULT_STRATEGY is used.
So, for example, "wb9" means open for writing with the maximum compression
using the default strategy and "wb4R" means open for writing with compression
level 4 and run-length encoding.
Refer to the I<zlib> documentation for the exact format of the C<$mode>
parameter.
=item B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>
Reads C<$size> bytes from the compressed file into C<$buffer>. If
C<$size> is not specified, it will default to 4096. If the scalar
C<$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 C<$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 C<gzread> and C<gzreadline>.
To maintain backward compatibility with version 1.x of this module
C<gzreadline> ignores the C<$/> variable - it I<always> uses the string
C<"\n"> as the line delimiter.
If you want to read a gzip file a line at a time and have it respect the
C<$/> variable (or C<$INPUT_RECORD_SEPARATOR>, or C<$RS> when C<English> is
in use) see L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
=item B<$byteswritten = $gz-E<gt>gzwrite($buffer) ;>
Writes the contents of C<$buffer> to the compressed file. Returns the
number of bytes actually written, or 0 on error.
=item B<$status = $gz-E<gt>gzflush($flush_type) ;>
Flushes all pending output into the compressed file.
This method takes an optional parameter, C<$flush_type>, that controls
how the flushing will be carried out. By default the C<$flush_type>
used is C<Z_FINISH>. Other valid values for C<$flush_type> are
C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
strongly recommended that you only set the C<flush_type> parameter if
you fully understand the implications of what it does - overuse of C<flush>
can seriously degrade the level of compression achieved. See the C<zlib>
documentation for details.
Returns 0 on success.
=item B<$offset = $gz-E<gt>gztell() ;>
Returns the uncompressed file offset.
=item B<$status = $gz-E<gt>gzseek($offset, $whence) ;>
Provides a sub-set of the C<seek> functionality, with the restriction
that it is only legal to seek forward in the compressed file.
It is a fatal error to attempt to seek backward.
When opened for writing, empty parts of the file will have NULL (0x00)
bytes written to them.
The C<$whence> parameter should be one of SEEK_SET, SEEK_CUR or SEEK_END.
Returns 1 on success, 0 on failure.
=item B<$gz-E<gt>gzclose>
Closes the compressed file. Any pending data is flushed to the file
before it is closed.
Returns 0 on success.
=item B<$gz-E<gt>gzsetparams($level, $strategy>
Change settings for the deflate stream C<$gz>.
The list of the valid options is shown below. Options not specified
will remain unchanged.
Note: This method is only available if you are running zlib 1.0.6 or better.
=over 5
=item B<$level>
Defines the compression level. Valid values are 0 through 9,
C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
C<Z_DEFAULT_COMPRESSION>.
=item B<$strategy>
Defines the strategy used to tune the compression. The valid values are
C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
=back
=item B<$gz-E<gt>gzerror>
Returns the I<zlib> error message or number for the last operation
associated with C<$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 C<$gzerrno> scalar holds the error code associated with the most
recent I<gzip> routine. Note that unlike C<gzerror()>, the error is
I<not> associated with a particular file.
As with C<gzerror()> it returns an error number in numeric context and
an error message in string context. Unlike C<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, C<$gzerrno> should only be used to check for the presence of
I<an> error in numeric context. Use C<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 strict ;
use warnings ;
use Compress::Zlib ;
# use stdin if no files supplied
@ARGV = '-' unless @ARGV ;
foreach my $file (@ARGV) {
my $buffer ;
my $gz = gzopen($file, "rb")
or die "Cannot open $file: $gzerrno\n" ;
print $buffer while $gz->gzread($buffer) > 0 ;
die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n"
if $gzerrno != Z_STREAM_END ;
$gz->gzclose() ;
}
Below is a script which makes use of C<gzreadline>. It implements a
very simple I<grep> like script.
use strict ;
use warnings ;
use Compress::Zlib ;
die "Usage: gzgrep pattern [file...]\n"
unless @ARGV >= 1;
my $pattern = shift ;
# use stdin if no files supplied
@ARGV = '-' unless @ARGV ;
foreach my $file (@ARGV) {
my $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 data stream to
standard output.
use strict ;
use warnings ;
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 with the minimum
possible gzip header (exactly 10 bytes).
$dest = Compress::Zlib::memGzip($buffer)
or die "Cannot compress: $gzerrno\n";
If successful, it returns the in-memory gzip file. Otherwise it returns
C<undef> and the C<$gzerrno> variable will store the zlib error code.
The C<$buffer> parameter can either be a scalar or a scalar reference.
See L<IO::Compress::Gzip|IO::Compress::Gzip> for an alternative way to
carry out in-memory gzip compression.
=head2 Compress::Zlib::memGunzip
This function is used to uncompress an in-memory gzip file.
$dest = Compress::Zlib::memGunzip($buffer)
or die "Cannot uncompress: $gzerrno\n";
If successful, it returns the uncompressed gzip file. Otherwise it
returns C<undef> and the C<$gzerrno> variable will store the zlib error
code.
The C<$buffer> parameter can either be a scalar or a scalar reference. The
contents of the C<$buffer> parameter are destroyed after calling this function.
If C<$buffer> consists of multiple concatenated gzip data streams only the
first will be uncompressed. Use C<gunzip> with the C<MultiStream> option in
the C<IO::Uncompress::Gunzip> module if you need to deal with concatenated
data streams.
See L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for an alternative way
to carry out in-memory gzip uncompression.
=head1 COMPRESS/UNCOMPRESS
Two functions are provided to perform in-memory compression/uncompression of
RFC 1950 data streams. They are called C<compress> and C<uncompress>.
=over 5
=item B<$dest = compress($source [, $level] ) ;>
Compresses C<$source>. If successful it returns the compressed
data. Otherwise it returns I<undef>.
The source buffer, C<$source>, can either be a scalar or a scalar
reference.
The C<$level> parameter defines the compression level. Valid values are
0 through 9, C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>,
C<Z_BEST_COMPRESSION>, and C<Z_DEFAULT_COMPRESSION>.
If C<$level> is not specified C<Z_DEFAULT_COMPRESSION> will be used.
=item B<$dest = uncompress($source) ;>
Uncompresses C<$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
Please note: the two functions defined above are I<not> compatible with
the Unix commands of the same name.
See L<IO::Deflate|IO::Deflate> and L<IO::Inflate|IO::Inflate> included with
this distribution for an alternative interface for reading/writing RFC 1950
files/buffers.
=head1 Deflate Interface
This section defines an interface that allows in-memory compression using
the I<deflate> interface provided by zlib.
Here is a definition of the interface available:
=head2 B<($d, $status) = deflateInit( [OPT] )>
Initialises a deflation stream.
It combines the features of the I<zlib> functions C<deflateInit>,
C<deflateInit2> and C<deflateSetDictionary>.
If successful, it will return the initialised deflation stream, C<$d>
and C<$status> of C<Z_OK> in a list context. In scalar context it
returns the deflation stream, C<$d>, only.
If not successful, the returned deflation stream (C<$d>) will be
I<undef> and C<$status> will hold the exact I<zlib> error code.
The function optionally takes a number of named options specified as
C<< -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:
=over 5
=item B<-Level>
Defines the compression level. Valid values are 0 through 9,
C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
C<Z_DEFAULT_COMPRESSION>.
The default is Z_DEFAULT_COMPRESSION.
=item B<-Method>
Defines the compression method. The only valid value at present (and
the default) is Z_DEFLATED.
=item B<-WindowBits>
To create an RFC 1950 data stream, set C<WindowBits> to a positive number.
To create an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
For a full definition of the meaning and valid values for C<WindowBits> refer
to the I<zlib> documentation for I<deflateInit2>.
Defaults to MAX_WBITS.
=item B<-MemLevel>
For a definition of the meaning and valid values for C<MemLevel>
refer to the I<zlib> documentation for I<deflateInit2>.
Defaults to MAX_MEM_LEVEL.
=item B<-Strategy>
Defines the strategy used to tune the compression. The valid values are
C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
The default is Z_DEFAULT_STRATEGY.
=item B<-Dictionary>
When a dictionary is specified I<Compress::Zlib> will automatically
call C<deflateSetDictionary> directly after calling C<deflateInit>. The
Adler32 value for the dictionary can be obtained by calling the method
C<$d->dict_adler()>.
The default is no dictionary.
=item B<-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
C<Bufsize>.
The default is 4096.
=back
Here is an example of using the C<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 ) ;
=head2 B<($out, $status) = $d-E<gt>deflate($buffer)>
Deflates the contents of C<$buffer>. The buffer can either be a scalar
or a scalar reference. When finished, C<$buffer> will be
completely processed (assuming there were no errors). If the deflation
was successful it returns the deflated output, C<$out>, and a status
value, C<$status>, of C<Z_OK>.
On error, C<$out> will be I<undef> and C<$status> will contain the
I<zlib> error code.
In a scalar context C<deflate> will return C<$out> only.
As with the I<deflate> function in I<zlib>, it is not necessarily the
case that any output will be produced by this method. So don't rely on
the fact that C<$out> is empty for an error test.
=head2 B<($out, $status) = $d-E<gt>flush()>
=head2 B<($out, $status) = $d-E<gt>flush($flush_type)>
Typically used to finish the deflation. Any pending output will be
returned via C<$out>.
C<$status> will have a value C<Z_OK> if successful.
In a scalar context C<flush> will return C<$out> only.
Note that flushing can seriously degrade the compression ratio, so it
should only be used to terminate a decompression (using C<Z_FINISH>) or
when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
By default the C<flush_type> used is C<Z_FINISH>. Other valid values
for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
C<flush_type> parameter if you fully understand the implications of
what it does. See the C<zlib> documentation for details.
=head2 B<$status = $d-E<gt>deflateParams([OPT])>
Change settings for the deflate stream C<$d>.
The list of the valid options is shown below. Options not specified
will remain unchanged.
=over 5
=item B<-Level>
Defines the compression level. Valid values are 0 through 9,
C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
C<Z_DEFAULT_COMPRESSION>.
=item B<-Strategy>
Defines the strategy used to tune the compression. The valid values are
C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
=back
=head2 B<$d-E<gt>dict_adler()>
Returns the adler32 value for the dictionary.
=head2 B<$d-E<gt>msg()>
Returns the last error message generated by zlib.
=head2 B<$d-E<gt>total_in()>
Returns the total number of bytes uncompressed bytes input to deflate.
=head2 B<$d-E<gt>total_out()>
Returns the total number of compressed bytes output from deflate.
=head2 Example
Here is a trivial example of using C<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 stream\n" ;
my ($output, $status) ;
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 ;
=head1 Inflate Interface
This section defines the interface available that allows in-memory
uncompression using the I<deflate> interface provided by zlib.
Here is a definition of the interface:
=head2 B<($i, $status) = inflateInit()>
Initialises an inflation stream.
In a list context it returns the inflation stream, C<$i>, and the
I<zlib> status code in C<$status>. In a scalar context it returns the
inflation stream only.
If successful, C<$i> will hold the inflation stream and C<$status> will
be C<Z_OK>.
If not successful, C<$i> will be I<undef> and C<$status> will hold the
I<zlib> error code.
The function optionally takes a number of named options specified as
C<< -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:
=over 5
=item B<-WindowBits>
To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive number.
To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
For a full definition of the meaning and valid values for C<WindowBits> refer
to the I<zlib> documentation for I<inflateInit2>.
Defaults to MAX_WBITS.
=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
C<Bufsize>.
Default is 4096.
=item B<-Dictionary>
The default is no dictionary.
=back
Here is an example of using the C<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 C<$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, C<$out> will be I<undef> and C<$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<$status = $i-E<gt>inflateSync($buffer)>
Scans C<$buffer> until it reaches either a I<full flush point> or the
end of the buffer.
If a I<full flush point> is found, C<Z_OK> is returned and C<$buffer>
will be have all data up to the flush point removed. This can then be
passed to the C<deflate> method.
Any other return code means that a flush point was not found. If more
data is available, C<inflateSync> can be called repeatedly with more
compressed data until the flush point is found.
=head2 B<$i-E<gt>dict_adler()>
Returns the adler32 value for the dictionary.
=head2 B<$i-E<gt>msg()>
Returns the last error message generated by zlib.
=head2 B<$i-E<gt>total_in()>
Returns the total number of bytes compressed bytes input to inflate.
=head2 B<$i-E<gt>total_out()>
Returns the total number of uncompressed bytes output from inflate.
=head2 Example
Here is an example of using C<inflate>.
use strict ;
use warnings ;
use Compress::Zlib ;
my $x = inflateInit()
or die "Cannot create a inflation stream\n" ;
my $input = '' ;
binmode STDIN;
binmode STDOUT;
my ($output, $status) ;
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 CHECKSUM FUNCTIONS
Two functions are provided by I<zlib> to calculate checksums. 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.
If you have built this module with zlib 1.2.3 or better, two more
CRC-related functions are available.
$crc = adler32_combine($crc1, $crc2, $len2)l
$crc = crc32_combine($adler1, $adler2, $len2)
These functions allow checksums to be merged.
=head1 Misc
=head2 my $version = Compress::Zlib::zlib_version();
Returns the version of the zlib library.
=head1 CONSTANTS
All the I<zlib> constants are automatically imported when you make use
of I<Compress::Zlib>.
=head1 SEE ALSO
L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
L<IO::Compress::FAQ|IO::Compress::FAQ>
L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
For RFC 1950, 1951 and 1952 see
F<http://www.faqs.org/rfcs/rfc1950.html>,
F<http://www.faqs.org/rfcs/rfc1951.html> and
F<http://www.faqs.org/rfcs/rfc1952.html>
The I<zlib> compression library was written by Jean-loup Gailly
F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
The primary site for the I<zlib> compression library is
F<http://www.zlib.org>.
The primary site for gzip is F<http://www.gzip.org>.
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
Copyright (c) 1995-2013 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.