2
# Author : Paul Marquess
3
# Created : 4 October 2005
6
# Copyright (c) 1995-2005 Paul Marquess. All rights reserved.
7
# This program is free software; you can redistribute it and/or
8
# modify it under the same terms as Perl itself.
11
package Compress::Zlib;
21
our ($VERSION, @ISA, @EXPORT, $AUTOLOAD);
22
our ($deflateDefault, $deflateParamsDefault, $inflateDefault);
27
# Items to export into callers namespace by default. Note: do not export
28
# names by default without a very good reason. Use EXPORT_OK instead.
29
# Do not simply export all your public functions/methods/constants.
86
($constname = $AUTOLOAD) =~ s/.*:://;
87
my ($error, $val) = constant($constname);
88
Carp::croak $error if $error;
90
*{$AUTOLOAD} = sub { $val };
96
XSLoader::load('Compress::Zlib', $VERSION);
99
local @ISA = qw(DynaLoader);
100
bootstrap Compress::Zlib $VERSION ;
103
# Preloaded methods go here.
109
return ((UNIVERSAL::isa($fh,'GLOB') or UNIVERSAL::isa(\$fh,'GLOB'))
110
and defined fileno($fh) )
118
return (! ref $name and UNIVERSAL::isa(\$name, 'SCALAR')) ;
123
my ($file, $mode) = @_ ;
125
if (isaFilehandle $file) {
126
IO::Handle::flush($file) ;
127
my $offset = tell($file) ;
128
gzdopen_(fileno($file), $mode, $offset) ;
130
elsif (isaFilename $file) {
131
gzopen_($file, $mode)
134
croak "gzopen: file parameter is not a filehandle or filename"
138
sub ParseParameters($@)
140
my ($default, @rest) = @_ ;
141
my (%got) = %$default ;
144
my $sub = (caller(1))[3] ;
147
# allow the options to be passed as a hash reference or
148
# as the complete hash.
151
croak "$sub: parameter is not a reference to a hash"
152
if ref $rest[0] ne "HASH" ;
154
%options = %{ $rest[0] } ;
158
croak "$sub: Expected even number of parameters, got $count"
163
while (($key, $value) = each %options)
167
if (exists $default->{$key})
168
{ $got{$key} = $value }
170
{ push (@Bad, $key) }
174
my ($bad) = join(", ", @Bad) ;
175
croak "unknown key value(s) @Bad" ;
182
'Level' => Z_DEFAULT_COMPRESSION(),
183
'Method' => Z_DEFLATED(),
184
'WindowBits' => MAX_WBITS(),
185
'MemLevel' => MAX_MEM_LEVEL(),
186
'Strategy' => Z_DEFAULT_STRATEGY(),
191
$deflateParamsDefault = {
198
'WindowBits' => MAX_WBITS(),
206
my ($got) = ParseParameters($deflateDefault, @_) ;
208
croak "deflateInit: Bufsize must be >= 1, you specified $got->{Bufsize}"
209
unless $got->{Bufsize} >= 1;
210
_deflateInit($got->{Level}, $got->{Method}, $got->{WindowBits},
211
$got->{MemLevel}, $got->{Strategy}, $got->{Bufsize},
212
$got->{Dictionary}) ;
218
my ($got) = ParseParameters($inflateDefault, @_) ;
220
croak "inflateInit: Bufsize must be >= 1, you specified $got->{Bufsize}"
221
unless $got->{Bufsize} >= 1;
222
_inflateInit($got->{WindowBits}, $got->{Bufsize}, $got->{Dictionary});
226
sub Compress::Zlib::deflateStream::deflateParams
229
my ($got) = ParseParameters($deflateParamsDefault, @_) ;
230
croak "deflateParams needs Level and/or Strategy"
231
unless defined $got->{Level} || defined $got->{Strategy};
233
croak "deflateParams: Bufsize must be >= 1, you specified $got->{Bufsize}"
234
unless !defined $got->{Bufsize} || $got->{Bufsize} >= 1;
237
if (defined $got->{Level})
240
{ $got->{Level} = 0 }
242
if (defined $got->{Strategy})
245
{ $got->{Strategy} = 0 }
248
if !defined $got->{Bufsize};
250
$self->_deflateParams($flags, $got->{Level}, $got->{Strategy},
257
my ($x, $output, $out, $err, $in) ;
261
croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
267
my $level = (@_ == 2 ? $_[1] : Z_DEFAULT_COMPRESSION() );
270
if ( (($x, $err) = deflateInit(Level => $level))[1] == Z_OK()) {
272
($output, $err) = $x->deflate($in) ;
273
return undef unless $err == Z_OK() ;
275
($out, $err) = $x->flush() ;
276
return undef unless $err == Z_OK() ;
278
return ($output . $out) ;
288
my ($x, $output, $err, $in) ;
292
croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
298
if ( (($x, $err) = inflateInit())[1] == Z_OK()) {
300
($output, $err) = $x->__unc_inflate($in) ;
301
return undef unless $err == Z_STREAM_END() ;
311
use constant MAGIC1 => 0x1f ;
312
use constant MAGIC2 => 0x8b ;
313
use constant OSCODE => 3 ;
315
use constant FTEXT => 1 ;
316
use constant FHCRC => 2 ;
317
use constant FEXTRA => 4 ;
318
use constant FNAME => 8 ;
319
use constant FCOMMENT => 16 ;
320
use constant NULL => pack("C", 0) ;
321
use constant RESERVED => 0xE0 ;
323
use constant MIN_HDR_SIZE => 10 ; # minimum gzip header size
328
-Level => Z_BEST_COMPRESSION(),
329
-WindowBits => - MAX_WBITS(),
333
# write a minimal gzip header
335
push @m, pack("C" . MIN_HDR_SIZE,
336
MAGIC1, MAGIC2, Z_DEFLATED(), 0,0,0,0,0,0, OSCODE) ;
338
# if the deflation buffer isn't a reference, make it one
339
my $string = (ref $_[0] ? $_[0] : \$_[0]) ;
341
my ($output, $status) = $x->deflate($string) ;
346
($output, $status) = $x->flush() ;
351
push @m, pack("V V", crc32($string), $x->total_in());
356
sub _removeGzipHeader($)
360
return Z_DATA_ERROR()
361
if length($$string) < MIN_HDR_SIZE ;
363
my ($magic1, $magic2, $method, $flags, $time, $xflags, $oscode) =
364
unpack ('CCCCVCC', $$string);
366
return Z_DATA_ERROR()
367
unless $magic1 == MAGIC1 and $magic2 == MAGIC2 and
368
$method == Z_DEFLATED() and !($flags & RESERVED()) ;
369
substr($$string, 0, MIN_HDR_SIZE) = '' ;
374
return Z_DATA_ERROR()
375
if length($$string) < 2 ;
377
my ($extra_len) = unpack ('v', $$string);
379
return Z_DATA_ERROR()
380
if length($$string) < $extra_len ;
382
substr($$string, 0, $extra_len) = '';
388
my $name_end = index ($$string, NULL);
389
return Z_DATA_ERROR()
391
substr($$string, 0, $name_end + 1) = '';
395
if ($flags & FCOMMENT)
397
my $comment_end = index ($$string, NULL);
398
return Z_DATA_ERROR()
399
if $comment_end == -1 ;
400
substr($$string, 0, $comment_end + 1) = '';
406
return Z_DATA_ERROR()
407
if length ($$string) < 2 ;
408
substr($$string, 0, 2) = '';
417
# if the buffer isn't a reference, make it one
418
my $string = (ref $_[0] ? $_[0] : \$_[0]);
420
_removeGzipHeader($string) == Z_OK()
423
my $bufsize = length $$string > 4096 ? length $$string : 4096 ;
424
my $x = inflateInit( -WindowBits => - MAX_WBITS(),
425
-Bufsize => $bufsize)
427
my ($output, $status) = $x->inflate($string);
429
unless $status == Z_STREAM_END();
431
if (length $$string >= 8)
433
my ($crc, $len) = unpack ("VV", substr($$string, 0, 8));
434
substr($$string, 0, 8) = '';
436
unless $len == length($output) and
437
$crc == crc32($output);
447
# Autoload methods go after __END__, and are processed by the autosplit program.
455
Compress::Zlib - Interface to zlib compression library
461
($d, $status) = deflateInit( [OPT] ) ;
462
($out, $status) = $d->deflate($buffer) ;
463
$status = $d->deflateParams([OPT]) ;
464
($out, $status) = $d->flush() ;
470
($i, $status) = inflateInit( [OPT] ) ;
471
($out, $status) = $i->inflate($buffer) ;
472
$status = $i->inflateSync($buffer) ;
478
$dest = compress($source, [$level]) ;
479
$dest = uncompress($source) ;
481
$gz = gzopen($filename or filehandle, $mode) ;
482
$bytesread = $gz->gzread($buffer [,$size]) ;
483
$bytesread = $gz->gzreadline($line) ;
484
$byteswritten = $gz->gzwrite($buffer) ;
485
$status = $gz->gzflush($flush) ;
486
$status = $gz->gzclose() ;
487
$status = $gz->gzeof() ;
488
$status = $gz->gzsetparams($level, $strategy) ;
489
$errstring = $gz->gzerror() ;
492
$dest = Compress::Zlib::memGzip($buffer) ;
493
$dest = Compress::Zlib::memGunzip($buffer) ;
495
$crc = adler32($buffer [,$crc]) ;
496
$crc = crc32($buffer [,$crc]) ;
502
The I<Compress::Zlib> module provides a Perl interface to the I<zlib>
503
compression library (see L</AUTHOR> for details about where to get
504
I<zlib>). Most of the functionality provided by I<zlib> is available
505
in I<Compress::Zlib>.
507
The module can be split into two general areas of functionality, namely
508
in-memory compression/decompression and read/write access to I<gzip>
509
files. Each of these areas will be discussed separately below.
513
The interface I<Compress::Zlib> provides to the in-memory I<deflate>
514
(and I<inflate>) functions has been modified to fit into a Perl model.
516
The main difference is that for both inflation and deflation, the Perl
517
interface will I<always> consume the complete input buffer before
518
returning. Also the output buffer returned will be automatically grown
519
to fit the amount of output available.
521
Here is a definition of the interface available:
524
=head2 B<($d, $status) = deflateInit( [OPT] )>
526
Initialises a deflation stream.
528
It combines the features of the I<zlib> functions B<deflateInit>,
529
B<deflateInit2> and B<deflateSetDictionary>.
531
If successful, it will return the initialised deflation stream, B<$d>
532
and B<$status> of C<Z_OK> in a list context. In scalar context it
533
returns the deflation stream, B<$d>, only.
535
If not successful, the returned deflation stream (B<$d>) will be
536
I<undef> and B<$status> will hold the exact I<zlib> error code.
538
The function optionally takes a number of named options specified as
539
C<-Name=E<gt>value> pairs. This allows individual options to be
540
tailored without having to specify them all in the parameter list.
542
For backward compatibility, it is also possible to pass the parameters
543
as a reference to a hash containing the name=>value pairs.
545
The function takes one optional parameter, a reference to a hash. The
546
contents of the hash allow the deflation interface to be tailored.
548
Here is a list of the valid options:
554
Defines the compression level. Valid values are 0 through 9,
555
C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
556
C<Z_DEFAULT_COMPRESSION>.
558
The default is C<-Level =E<gt>Z_DEFAULT_COMPRESSION>.
562
Defines the compression method. The only valid value at present (and
563
the default) is C<-Method =E<gt>Z_DEFLATED>.
567
For a definition of the meaning and valid values for B<WindowBits>
568
refer to the I<zlib> documentation for I<deflateInit2>.
570
Defaults to C<-WindowBits =E<gt>MAX_WBITS>.
574
For a definition of the meaning and valid values for B<MemLevel>
575
refer to the I<zlib> documentation for I<deflateInit2>.
577
Defaults to C<-MemLevel =E<gt>MAX_MEM_LEVEL>.
581
Defines the strategy used to tune the compression. The valid values are
582
C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
584
The default is C<-Strategy =E<gt>Z_DEFAULT_STRATEGY>.
588
When a dictionary is specified I<Compress::Zlib> will automatically
589
call B<deflateSetDictionary> directly after calling B<deflateInit>. The
590
Adler32 value for the dictionary can be obtained by calling the method
593
The default is no dictionary.
597
Sets the initial size for the deflation buffer. If the buffer has to be
598
reallocated to increase the size, it will grow in increments of
605
Here is an example of using the B<deflateInit> optional parameter list
606
to override the default buffer size and compression level. All other
607
options will take their default values.
609
deflateInit( -Bufsize => 300,
610
-Level => Z_BEST_SPEED ) ;
613
=head2 B<($out, $status) = $d-E<gt>deflate($buffer)>
616
Deflates the contents of B<$buffer>. The buffer can either be a scalar
617
or a scalar reference. When finished, B<$buffer> will be
618
completely processed (assuming there were no errors). If the deflation
619
was successful it returns the deflated output, B<$out>, and a status
620
value, B<$status>, of C<Z_OK>.
622
On error, B<$out> will be I<undef> and B<$status> will contain the
625
In a scalar context B<deflate> will return B<$out> only.
627
As with the I<deflate> function in I<zlib>, it is not necessarily the
628
case that any output will be produced by this method. So don't rely on
629
the fact that B<$out> is empty for an error test.
632
=head2 B<($out, $status) = $d-E<gt>flush([flush_type])>
634
Typically used to finish the deflation. Any pending output will be
635
returned via B<$out>.
636
B<$status> will have a value C<Z_OK> if successful.
638
In a scalar context B<flush> will return B<$out> only.
640
Note that flushing can seriously degrade the compression ratio, so it
641
should only be used to terminate a decompression (using C<Z_FINISH>) or
642
when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
644
By default the C<flush_type> used is C<Z_FINISH>. Other valid values
645
for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
646
and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
647
C<flush_type> parameter if you fully understand the implications of
648
what it does. See the C<zlib> documentation for details.
650
=head2 B<$status = $d-E<gt>deflateParams([OPT])>
652
Change settings for the deflate stream C<$d>.
654
The list of the valid options is shown below. Options not specified
655
will remain unchanged.
661
Defines the compression level. Valid values are 0 through 9,
662
C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
663
C<Z_DEFAULT_COMPRESSION>.
667
Defines the strategy used to tune the compression. The valid values are
668
C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
672
=head2 B<$d-E<gt>dict_adler()>
674
Returns the adler32 value for the dictionary.
676
=head2 B<$d-E<gt>msg()>
678
Returns the last error message generated by zlib.
680
=head2 B<$d-E<gt>total_in()>
682
Returns the total number of bytes uncompressed bytes input to deflate.
684
=head2 B<$d-E<gt>total_out()>
686
Returns the total number of compressed bytes output from deflate.
691
Here is a trivial example of using B<deflate>. It simply reads standard
692
input, deflates it and writes it to standard output.
701
my $x = deflateInit()
702
or die "Cannot create a deflation stream\n" ;
704
my ($output, $status) ;
707
($output, $status) = $x->deflate($_) ;
710
or die "deflation failed\n" ;
715
($output, $status) = $x->flush() ;
718
or die "deflation failed\n" ;
724
Here is a definition of the interface:
727
=head2 B<($i, $status) = inflateInit()>
729
Initialises an inflation stream.
731
In a list context it returns the inflation stream, B<$i>, and the
732
I<zlib> status code (B<$status>). In a scalar context it returns the
733
inflation stream only.
735
If successful, B<$i> will hold the inflation stream and B<$status> will
738
If not successful, B<$i> will be I<undef> and B<$status> will hold the
741
The function optionally takes a number of named options specified as
742
C<-Name=E<gt>value> pairs. This allows individual options to be
743
tailored without having to specify them all in the parameter list.
745
For backward compatibility, it is also possible to pass the parameters
746
as a reference to a hash containing the name=>value pairs.
748
The function takes one optional parameter, a reference to a hash. The
749
contents of the hash allow the deflation interface to be tailored.
751
Here is a list of the valid options:
757
For a definition of the meaning and valid values for B<WindowBits>
758
refer to the I<zlib> documentation for I<inflateInit2>.
760
Defaults to C<-WindowBits =E<gt>MAX_WBITS>.
764
Sets the initial size for the inflation buffer. If the buffer has to be
765
reallocated to increase the size, it will grow in increments of
772
The default is no dictionary.
776
Here is an example of using the B<inflateInit> optional parameter to
777
override the default buffer size.
779
inflateInit( -Bufsize => 300 ) ;
781
=head2 B<($out, $status) = $i-E<gt>inflate($buffer)>
783
Inflates the complete contents of B<$buffer>. The buffer can either be
784
a scalar or a scalar reference.
786
Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
787
compressed data has been successfully reached.
788
If not successful, B<$out> will be I<undef> and B<$status> will hold
789
the I<zlib> error code.
791
The C<$buffer> parameter is modified by C<inflate>. On completion it
792
will contain what remains of the input buffer after inflation. This
793
means that C<$buffer> will be an empty string when the return status is
794
C<Z_OK>. When the return status is C<Z_STREAM_END> the C<$buffer>
795
parameter will contains what (if anything) was stored in the input
796
buffer after the deflated data stream.
798
This feature is useful when processing a file format that encapsulates
799
a compressed data stream (e.g. gzip, zip).
801
=head2 B<$status = $i-E<gt>inflateSync($buffer)>
803
Scans C<$buffer> until it reaches either a I<full flush point> or the
806
If a I<full flush point> is found, C<Z_OK> is returned and C<$buffer>
807
will be have all data up to the flush point removed. This can then be
808
passed to the C<deflate> method.
810
Any other return code means that a flush point was not found. If more
811
data is available, C<inflateSync> can be called repeatedly with more
812
compressed data until the flush point is found.
815
=head2 B<$i-E<gt>dict_adler()>
817
Returns the adler32 value for the dictionary.
819
=head2 B<$i-E<gt>msg()>
821
Returns the last error message generated by zlib.
823
=head2 B<$i-E<gt>total_in()>
825
Returns the total number of bytes compressed bytes input to inflate.
827
=head2 B<$i-E<gt>total_out()>
829
Returns the total number of uncompressed bytes output from inflate.
833
Here is an example of using B<inflate>.
840
my $x = inflateInit()
841
or die "Cannot create a inflation stream\n" ;
847
my ($output, $status) ;
848
while (read(STDIN, $input, 4096))
850
($output, $status) = $x->inflate(\$input) ;
853
if $status == Z_OK or $status == Z_STREAM_END ;
855
last if $status != Z_OK ;
858
die "inflation failed\n"
859
unless $status == Z_STREAM_END ;
861
=head1 COMPRESS/UNCOMPRESS
863
Two high-level functions are provided by I<zlib> to perform in-memory
864
compression/uncompression of RFC1950 data streams. They are called
865
B<compress> and B<uncompress>.
867
The two Perl subs defined below provide the equivalent
872
=item B<$dest = compress($source [, $level] ) ;>
874
Compresses B<$source>. If successful it returns the
875
compressed data. Otherwise it returns I<undef>.
877
The source buffer can either be a scalar or a scalar reference.
879
The B<$level> paramter defines the compression level. Valid values are
880
0 through 9, C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>,
881
C<Z_BEST_COMPRESSION>, and C<Z_DEFAULT_COMPRESSION>.
882
If B<$level> is not specified C<Z_DEFAULT_COMPRESSION> will be used.
885
=item B<$dest = uncompress($source) ;>
887
Uncompresses B<$source>. If successful it returns the uncompressed
888
data. Otherwise it returns I<undef>.
890
The source buffer can either be a scalar or a scalar reference.
894
Please note: the two functions defined above are I<not> compatible with
895
the Unix commands of the same name.
897
=head1 GZIP INTERFACE
899
A number of functions are supplied in I<zlib> for reading and writing
900
I<gzip> files. This module provides an interface to most of them. In
901
general the interface provided by this module operates identically to
902
the functions provided by I<zlib>. Any differences are explained
907
=item B<$gz = gzopen(filename or filehandle, mode)>
909
This function operates identically to the I<zlib> equivalent except
910
that it returns an object which is used to access the other I<gzip>
913
As with the I<zlib> equivalent, the B<mode> parameter is used to
914
specify both whether the file is opened for reading or writing and to
915
optionally specify a a compression level. Refer to the I<zlib>
916
documentation for the exact format of the B<mode> parameter.
918
If a reference to an open filehandle is passed in place of the
919
filename, gzdopen will be called behind the scenes. The third example
920
at the end of this section, I<gzstream>, uses this feature.
922
=item B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>
924
Reads B<$size> bytes from the compressed file into B<$buffer>. If
925
B<$size> is not specified, it will default to 4096. If the scalar
926
B<$buffer> is not large enough, it will be extended automatically.
928
Returns the number of bytes actually read. On EOF it returns 0 and in
929
the case of an error, -1.
931
=item B<$bytesread = $gz-E<gt>gzreadline($line) ;>
933
Reads the next line from the compressed file into B<$line>.
935
Returns the number of bytes actually read. On EOF it returns 0 and in
936
the case of an error, -1.
938
It is legal to intermix calls to B<gzread> and B<gzreadline>.
940
At this time B<gzreadline> ignores the variable C<$/>
941
(C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use). The
942
end of a line is denoted by the C character C<'\n'>.
944
=item B<$byteswritten = $gz-E<gt>gzwrite($buffer) ;>
946
Writes the contents of B<$buffer> to the compressed file. Returns the
947
number of bytes actually written, or 0 on error.
949
=item B<$status = $gz-E<gt>gzflush($flush) ;>
951
Flushes all pending output to the compressed file.
952
Works identically to the I<zlib> function it interfaces to. Note that
953
the use of B<gzflush> can degrade compression.
955
Returns C<Z_OK> if B<$flush> is C<Z_FINISH> and all output could be
956
flushed. Otherwise the zlib error code is returned.
958
Refer to the I<zlib> documentation for the valid values of B<$flush>.
960
=item B<$status = $gz-E<gt>gzeof() ;>
962
Returns 1 if the end of file has been detected while reading the input
963
file, otherwise returns 0.
965
=item B<$gz-E<gt>gzclose>
967
Closes the compressed file. Any pending data is flushed to the file
970
=item B<$gz-E<gt>gzsetparams($level, $strategy>
972
Change settings for the deflate stream C<$gz>.
974
The list of the valid options is shown below. Options not specified
975
will remain unchanged.
977
Note: This method is only available if you are running zlib 1.0.6 or better.
983
Defines the compression level. Valid values are 0 through 9,
984
C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
985
C<Z_DEFAULT_COMPRESSION>.
989
Defines the strategy used to tune the compression. The valid values are
990
C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
994
=item B<$gz-E<gt>gzerror>
996
Returns the I<zlib> error message or number for the last operation
997
associated with B<$gz>. The return value will be the I<zlib> error
998
number when used in a numeric context and the I<zlib> error message
999
when used in a string context. The I<zlib> error number constants,
1000
shown below, are available for use.
1012
The B<$gzerrno> scalar holds the error code associated with the most
1013
recent I<gzip> routine. Note that unlike B<gzerror()>, the error is
1014
I<not> associated with a particular file.
1016
As with B<gzerror()> it returns an error number in numeric context and
1017
an error message in string context. Unlike B<gzerror()> though, the
1018
error message will correspond to the I<zlib> message when the error is
1019
associated with I<zlib> itself, or the UNIX error message when it is
1020
not (i.e. I<zlib> returned C<Z_ERRORNO>).
1022
As there is an overlap between the error numbers used by I<zlib> and
1023
UNIX, B<$gzerrno> should only be used to check for the presence of
1024
I<an> error in numeric context. Use B<gzerror()> to check for specific
1025
I<zlib> errors. The I<gzcat> example below shows how the variable can
1033
Here is an example script which uses the interface. It implements a
1039
use Compress::Zlib ;
1041
die "Usage: gzcat file...\n"
1046
foreach $file (@ARGV) {
1049
my $gz = gzopen($file, "rb")
1050
or die "Cannot open $file: $gzerrno\n" ;
1052
print $buffer while $gz->gzread($buffer) > 0 ;
1054
die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n"
1055
if $gzerrno != Z_STREAM_END ;
1060
Below is a script which makes use of B<gzreadline>. It implements a
1061
very simple I<grep> like script.
1066
use Compress::Zlib ;
1068
die "Usage: gzgrep pattern file...\n"
1071
my $pattern = shift ;
1075
foreach $file (@ARGV) {
1076
my $gz = gzopen($file, "rb")
1077
or die "Cannot open $file: $gzerrno\n" ;
1079
while ($gz->gzreadline($_) > 0) {
1080
print if /$pattern/ ;
1083
die "Error reading from $file: $gzerrno\n"
1084
if $gzerrno != Z_STREAM_END ;
1089
This script, I<gzstream>, does the opposite of the I<gzcat> script
1090
above. It reads from standard input and writes a gzip file to standard
1096
use Compress::Zlib ;
1098
binmode STDOUT; # gzopen only sets it on the fd
1100
my $gz = gzopen(\*STDOUT, "wb")
1101
or die "Cannot open stdout: $gzerrno\n" ;
1105
or die "error writing: $gzerrno\n" ;
1110
=head2 Compress::Zlib::memGzip
1112
This function is used to create an in-memory gzip file.
1113
It creates a minimal gzip header.
1115
$dest = Compress::Zlib::memGzip($buffer) ;
1117
If successful, it returns the in-memory gzip file, otherwise it returns
1120
The buffer parameter can either be a scalar or a scalar reference.
1122
=head2 Compress::Zlib::memGunzip
1124
This function is used to uncompress an in-memory gzip file.
1126
$dest = Compress::Zlib::memGunzip($buffer) ;
1128
If successful, it returns the uncompressed gzip file, otherwise it
1131
The buffer parameter can either be a scalar or a scalar reference. The
1132
contents of the buffer parameter are destroyed after calling this
1135
=head1 CHECKSUM FUNCTIONS
1137
Two functions are provided by I<zlib> to calculate a checksum. For the
1138
Perl interface, the order of the two parameters in both functions has
1139
been reversed. This allows both running checksums and one off
1140
calculations to be done.
1142
$crc = adler32($buffer [,$crc]) ;
1143
$crc = crc32($buffer [,$crc]) ;
1145
The buffer parameters can either be a scalar or a scalar reference.
1147
If the $crc parameters is C<undef>, the crc value will be reset.
1151
=head2 Compatibility with Unix compress/uncompress.
1153
Although C<Compress::Zlib> has a pair of functions called C<compress>
1154
and C<uncompress>, they are I<not> the same as the Unix programs of the
1155
same name. The C<Compress::Zlib> library is not compatable with Unix
1158
If you have the C<uncompress> program available, you can use this to
1159
read compressed files
1161
open F, "uncompress -c $filename |";
1166
If you have the C<gunzip> program available, you can use this to read
1169
open F, "gunzip -c $filename |";
1174
and this to write compress files if you have the C<compress> program
1177
open F, "| compress -c $filename ";
1182
=head2 Accessing .tar.Z files
1184
The C<Archive::Tar> module can optionally use C<Compress::Zlib> (via
1185
the C<IO::Zlib> module) to access tar files that have been compressed
1186
with C<gzip>. Unfortunately tar files compressed with the Unix C<compress>
1187
utility cannot be read by C<Compress::Zlib> and so cannot be directly
1188
accesses by C<Archive::Tar>.
1190
If the C<uncompress> or C<gunzip> programs are available, you can use
1191
one of these workarounds to read C<.tar.Z> files from C<Archive::Tar>
1193
Firstly with C<uncompress>
1199
open F, "uncompress -c $filename |";
1200
my $tar = Archive::Tar->new(*F);
1203
and this with C<gunzip>
1209
open F, "gunzip -c $filename |";
1210
my $tar = Archive::Tar->new(*F);
1213
Similarly, if the C<compress> program is available, you can use this to
1214
write a C<.tar.Z> file
1221
my $fh = newIO::File "| compress -c >$filename";
1222
my $tar = Archive::Tar->new();
1227
=head2 Accessing ZIP Files
1229
Although it is possible to use this module to access .zip files, there
1230
is a module on CPAN that will do all the hard work for you. Check out
1232
http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
1234
Assuming you don't want to use this module to access zip files there
1235
are a number of undocumented features in the zlib library you need to
1242
When calling B<inflateInit> or B<deflateInit> the B<WindowBits> parameter
1243
must be set to C<-MAX_WBITS>. This disables the creation of the zlib
1248
The zlib function B<inflate>, and so the B<inflate> method supplied in
1249
this module, assume that there is at least one trailing byte after the
1250
compressed data stream. Normally this isn't a problem because both
1251
the gzip and zip file formats will guarantee that there is data directly
1252
after the compressed data stream.
1258
All the I<zlib> constants are automatically imported when you make use
1259
of I<Compress::Zlib>.
1263
The I<Compress::Zlib> module was written by Paul Marquess,
1264
F<pmqs@cpan.org>. The latest copy of the module can be
1265
found on CPAN in F<modules/by-module/Compress/Compress-Zlib-x.x.tar.gz>.
1267
The primary site for the I<zlib> compression library is
1268
F<http://www.zlib.org>.
1270
=head1 MODIFICATION HISTORY
1272
See the Changes file.
added
removed
0CPAN/Compress-Zlib-1.41/Zlib.pm
