2 # Author : Paul Marquess
3 # Created : 30 January 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 local ($^W) = 1; #use warnings ;
22 use vars qw($VERSION @ISA @EXPORT $AUTOLOAD);
23 use vars qw($deflateDefault $deflateParamsDefault $inflateDefault);
25 $VERSION = "1.34_01" ;
27 @ISA = qw(Exporter DynaLoader);
28 # Items to export into callers namespace by default. Note: do not export
29 # names by default without a very good reason. Use EXPORT_OK instead.
30 # 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 };
94 bootstrap Compress::Zlib $VERSION ;
96 # Preloaded methods go here.
102 return ((UNIVERSAL::isa($fh,'GLOB') or UNIVERSAL::isa(\$fh,'GLOB'))
103 and defined fileno($fh) )
111 return (! ref $name and UNIVERSAL::isa(\$name, 'SCALAR')) ;
116 my ($file, $mode) = @_ ;
118 if (isaFilehandle $file) {
119 IO::Handle::flush($file) ;
120 my $offset = tell($file) ;
121 gzdopen_(fileno($file), $mode, $offset) ;
123 elsif (isaFilename $file) {
124 gzopen_($file, $mode)
127 croak "gzopen: file parameter is not a filehandle or filename"
131 sub ParseParameters($@)
133 my ($default, @rest) = @_ ;
134 my (%got) = %$default ;
137 my $sub = (caller(1))[3] ;
140 # allow the options to be passed as a hash reference or
141 # as the complete hash.
144 croak "$sub: parameter is not a reference to a hash"
145 if ref $rest[0] ne "HASH" ;
147 %options = %{ $rest[0] } ;
151 croak "$sub: Expected even number of parameters, got $count"
156 while (($key, $value) = each %options)
160 if (exists $default->{$key})
161 { $got{$key} = $value }
163 { push (@Bad, $key) }
167 my ($bad) = join(", ", @Bad) ;
168 croak "unknown key value(s) @Bad" ;
175 'Level' => Z_DEFAULT_COMPRESSION(),
176 'Method' => Z_DEFLATED(),
177 'WindowBits' => MAX_WBITS(),
178 'MemLevel' => MAX_MEM_LEVEL(),
179 'Strategy' => Z_DEFAULT_STRATEGY(),
184 $deflateParamsDefault = {
191 'WindowBits' => MAX_WBITS(),
199 my ($got) = ParseParameters($deflateDefault, @_) ;
200 local ($^W) = 0; #no warnings;
201 croak "deflateInit: Bufsize must be >= 1, you specified $got->{Bufsize}"
202 unless $got->{Bufsize} >= 1;
203 _deflateInit($got->{Level}, $got->{Method}, $got->{WindowBits},
204 $got->{MemLevel}, $got->{Strategy}, $got->{Bufsize},
205 $got->{Dictionary}) ;
211 my ($got) = ParseParameters($inflateDefault, @_) ;
212 local ($^W) = 0; #no warnings;
213 croak "inflateInit: Bufsize must be >= 1, you specified $got->{Bufsize}"
214 unless $got->{Bufsize} >= 1;
215 _inflateInit($got->{WindowBits}, $got->{Bufsize}, $got->{Dictionary});
219 sub Compress::Zlib::deflateStream::deflateParams
222 my ($got) = ParseParameters($deflateParamsDefault, @_) ;
223 croak "deflateParams needs Level and/or Strategy"
224 unless defined $got->{Level} || defined $got->{Strategy};
225 local ($^W) = 0; #no warnings;
226 croak "deflateParams: Bufsize must be >= 1, you specified $got->{Bufsize}"
227 unless !defined $got->{Bufsize} || $got->{Bufsize} >= 1;
230 if (defined $got->{Level})
233 { $got->{Level} = 0 }
235 if (defined $got->{Strategy})
238 { $got->{Strategy} = 0 }
241 if !defined $got->{Bufsize};
243 $self->_deflateParams($flags, $got->{Level}, $got->{Strategy},
250 my ($x, $output, $out, $err, $in) ;
254 croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
260 my $level = (@_ == 2 ? $_[1] : Z_DEFAULT_COMPRESSION() );
263 if ( (($x, $err) = deflateInit(Level => $level))[1] == Z_OK()) {
265 ($output, $err) = $x->deflate($in) ;
266 return undef unless $err == Z_OK() ;
268 ($out, $err) = $x->flush() ;
269 return undef unless $err == Z_OK() ;
271 return ($output . $out) ;
281 my ($x, $output, $err, $in) ;
285 croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
291 if ( (($x, $err) = inflateInit())[1] == Z_OK()) {
293 ($output, $err) = $x->__unc_inflate($in) ;
294 return undef unless $err == Z_STREAM_END() ;
304 use constant MAGIC1 => 0x1f ;
305 use constant MAGIC2 => 0x8b ;
306 use constant OSCODE => 3 ;
308 use constant FTEXT => 1 ;
309 use constant FHCRC => 2 ;
310 use constant FEXTRA => 4 ;
311 use constant FNAME => 8 ;
312 use constant FCOMMENT => 16 ;
313 use constant NULL => pack("C", 0) ;
314 use constant RESERVED => 0xE0 ;
316 use constant MIN_HDR_SIZE => 10 ; # minimum gzip header size
321 -Level => Z_BEST_COMPRESSION(),
322 -WindowBits => - MAX_WBITS(),
326 # write a minimal gzip header
328 push @m, pack("C" . MIN_HDR_SIZE,
329 MAGIC1, MAGIC2, Z_DEFLATED(), 0,0,0,0,0,0, OSCODE) ;
331 # if the deflation buffer isn't a reference, make it one
332 my $string = (ref $_[0] ? $_[0] : \$_[0]) ;
334 my ($output, $status) = $x->deflate($string) ;
339 ($output, $status) = $x->flush() ;
344 push @m, pack("V V", crc32($string), $x->total_in());
349 sub _removeGzipHeader($)
353 return Z_DATA_ERROR()
354 if length($$string) < MIN_HDR_SIZE ;
356 my ($magic1, $magic2, $method, $flags, $time, $xflags, $oscode) =
357 unpack ('CCCCVCC', $$string);
359 return Z_DATA_ERROR()
360 unless $magic1 == MAGIC1 and $magic2 == MAGIC2 and
361 $method == Z_DEFLATED() and !($flags & RESERVED()) ;
362 substr($$string, 0, MIN_HDR_SIZE) = '' ;
367 return Z_DATA_ERROR()
368 if length($$string) < 2 ;
370 my ($extra_len) = unpack ('v', $$string);
372 return Z_DATA_ERROR()
373 if length($$string) < $extra_len ;
375 substr($$string, 0, $extra_len) = '';
381 my $name_end = index ($$string, NULL);
382 return Z_DATA_ERROR()
384 substr($$string, 0, $name_end + 1) = '';
388 if ($flags & FCOMMENT)
390 my $comment_end = index ($$string, NULL);
391 return Z_DATA_ERROR()
392 if $comment_end == -1 ;
393 substr($$string, 0, $comment_end + 1) = '';
399 return Z_DATA_ERROR()
400 if length ($$string) < 2 ;
401 substr($$string, 0, 2) = '';
410 # if the buffer isn't a reference, make it one
411 my $string = (ref $_[0] ? $_[0] : \$_[0]);
413 _removeGzipHeader($string) == Z_OK()
416 my $bufsize = length $$string > 4096 ? length $$string : 4096 ;
417 my $x = inflateInit( -WindowBits => - MAX_WBITS(),
418 -Bufsize => $bufsize)
420 my ($output, $status) = $x->inflate($string);
422 unless $status == Z_STREAM_END();
424 if (length $$string >= 8)
426 my ($crc, $len) = unpack ("VV", substr($$string, 0, 8));
427 substr($$string, 0, 8) = '';
429 unless $len == length($output) and
430 $crc == crc32($output);
440 # Autoload methods go after __END__, and are processed by the autosplit program.
449 Compress::Zlib - Interface to zlib compression library
455 ($d, $status) = deflateInit( [OPT] ) ;
456 ($out, $status) = $d->deflate($buffer) ;
457 $status = $d->deflateParams([OPT]) ;
458 ($out, $status) = $d->flush() ;
464 ($i, $status) = inflateInit( [OPT] ) ;
465 ($out, $status) = $i->inflate($buffer) ;
466 $status = $i->inflateSync($buffer) ;
472 $dest = compress($source, [$level]) ;
473 $dest = uncompress($source) ;
475 $gz = gzopen($filename or filehandle, $mode) ;
476 $bytesread = $gz->gzread($buffer [,$size]) ;
477 $bytesread = $gz->gzreadline($line) ;
478 $byteswritten = $gz->gzwrite($buffer) ;
479 $status = $gz->gzflush($flush) ;
480 $status = $gz->gzclose() ;
481 $status = $gz->gzeof() ;
482 $status = $gz->gzsetparams($level, $strategy) ;
483 $errstring = $gz->gzerror() ;
486 $dest = Compress::Zlib::memGzip($buffer) ;
487 $dest = Compress::Zlib::memGunzip($buffer) ;
489 $crc = adler32($buffer [,$crc]) ;
490 $crc = crc32($buffer [,$crc]) ;
496 The I<Compress::Zlib> module provides a Perl interface to the I<zlib>
497 compression library (see L</AUTHOR> for details about where to get
498 I<zlib>). Most of the functionality provided by I<zlib> is available
499 in I<Compress::Zlib>.
501 The module can be split into two general areas of functionality, namely
502 in-memory compression/decompression and read/write access to I<gzip>
503 files. Each of these areas will be discussed separately below.
507 The interface I<Compress::Zlib> provides to the in-memory I<deflate>
508 (and I<inflate>) functions has been modified to fit into a Perl model.
510 The main difference is that for both inflation and deflation, the Perl
511 interface will I<always> consume the complete input buffer before
512 returning. Also the output buffer returned will be automatically grown
513 to fit the amount of output available.
515 Here is a definition of the interface available:
518 =head2 B<($d, $status) = deflateInit( [OPT] )>
520 Initialises a deflation stream.
522 It combines the features of the I<zlib> functions B<deflateInit>,
523 B<deflateInit2> and B<deflateSetDictionary>.
525 If successful, it will return the initialised deflation stream, B<$d>
526 and B<$status> of C<Z_OK> in a list context. In scalar context it
527 returns the deflation stream, B<$d>, only.
529 If not successful, the returned deflation stream (B<$d>) will be
530 I<undef> and B<$status> will hold the exact I<zlib> error code.
532 The function optionally takes a number of named options specified as
533 C<-Name=E<gt>value> pairs. This allows individual options to be
534 tailored without having to specify them all in the parameter list.
536 For backward compatibility, it is also possible to pass the parameters
537 as a reference to a hash containing the name=>value pairs.
539 The function takes one optional parameter, a reference to a hash. The
540 contents of the hash allow the deflation interface to be tailored.
542 Here is a list of the valid options:
548 Defines the compression level. Valid values are 0 through 9,
549 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
550 C<Z_DEFAULT_COMPRESSION>.
552 The default is C<-Level =E<gt>Z_DEFAULT_COMPRESSION>.
556 Defines the compression method. The only valid value at present (and
557 the default) is C<-Method =E<gt>Z_DEFLATED>.
561 For a definition of the meaning and valid values for B<WindowBits>
562 refer to the I<zlib> documentation for I<deflateInit2>.
564 Defaults to C<-WindowBits =E<gt>MAX_WBITS>.
568 For a definition of the meaning and valid values for B<MemLevel>
569 refer to the I<zlib> documentation for I<deflateInit2>.
571 Defaults to C<-MemLevel =E<gt>MAX_MEM_LEVEL>.
575 Defines the strategy used to tune the compression. The valid values are
576 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
578 The default is C<-Strategy =E<gt>Z_DEFAULT_STRATEGY>.
582 When a dictionary is specified I<Compress::Zlib> will automatically
583 call B<deflateSetDictionary> directly after calling B<deflateInit>. The
584 Adler32 value for the dictionary can be obtained by calling the method
587 The default is no dictionary.
591 Sets the initial size for the deflation buffer. If the buffer has to be
592 reallocated to increase the size, it will grow in increments of
599 Here is an example of using the B<deflateInit> optional parameter list
600 to override the default buffer size and compression level. All other
601 options will take their default values.
603 deflateInit( -Bufsize => 300,
604 -Level => Z_BEST_SPEED ) ;
607 =head2 B<($out, $status) = $d-E<gt>deflate($buffer)>
610 Deflates the contents of B<$buffer>. The buffer can either be a scalar
611 or a scalar reference. When finished, B<$buffer> will be
612 completely processed (assuming there were no errors). If the deflation
613 was successful it returns the deflated output, B<$out>, and a status
614 value, B<$status>, of C<Z_OK>.
616 On error, B<$out> will be I<undef> and B<$status> will contain the
619 In a scalar context B<deflate> will return B<$out> only.
621 As with the I<deflate> function in I<zlib>, it is not necessarily the
622 case that any output will be produced by this method. So don't rely on
623 the fact that B<$out> is empty for an error test.
626 =head2 B<($out, $status) = $d-E<gt>flush([flush_type])>
628 Typically used to finish the deflation. Any pending output will be
629 returned via B<$out>.
630 B<$status> will have a value C<Z_OK> if successful.
632 In a scalar context B<flush> will return B<$out> only.
634 Note that flushing can seriously degrade the compression ratio, so it
635 should only be used to terminate a decompression (using C<Z_FINISH>) or
636 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
638 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
639 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
640 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
641 C<flush_type> parameter if you fully understand the implications of
642 what it does. See the C<zlib> documentation for details.
644 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
646 Change settings for the deflate stream C<$d>.
648 The list of the valid options is shown below. Options not specified
649 will remain unchanged.
655 Defines the compression level. Valid values are 0 through 9,
656 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
657 C<Z_DEFAULT_COMPRESSION>.
661 Defines the strategy used to tune the compression. The valid values are
662 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
666 =head2 B<$d-E<gt>dict_adler()>
668 Returns the adler32 value for the dictionary.
670 =head2 B<$d-E<gt>msg()>
672 Returns the last error message generated by zlib.
674 =head2 B<$d-E<gt>total_in()>
676 Returns the total number of bytes uncompressed bytes input to deflate.
678 =head2 B<$d-E<gt>total_out()>
680 Returns the total number of compressed bytes output from deflate.
685 Here is a trivial example of using B<deflate>. It simply reads standard
686 input, deflates it and writes it to standard output.
695 my $x = deflateInit()
696 or die "Cannot create a deflation stream\n" ;
698 my ($output, $status) ;
701 ($output, $status) = $x->deflate($_) ;
704 or die "deflation failed\n" ;
709 ($output, $status) = $x->flush() ;
712 or die "deflation failed\n" ;
718 Here is a definition of the interface:
721 =head2 B<($i, $status) = inflateInit()>
723 Initialises an inflation stream.
725 In a list context it returns the inflation stream, B<$i>, and the
726 I<zlib> status code (B<$status>). In a scalar context it returns the
727 inflation stream only.
729 If successful, B<$i> will hold the inflation stream and B<$status> will
732 If not successful, B<$i> will be I<undef> and B<$status> will hold the
735 The function optionally takes a number of named options specified as
736 C<-Name=E<gt>value> pairs. This allows individual options to be
737 tailored without having to specify them all in the parameter list.
739 For backward compatibility, it is also possible to pass the parameters
740 as a reference to a hash containing the name=>value pairs.
742 The function takes one optional parameter, a reference to a hash. The
743 contents of the hash allow the deflation interface to be tailored.
745 Here is a list of the valid options:
751 For a definition of the meaning and valid values for B<WindowBits>
752 refer to the I<zlib> documentation for I<inflateInit2>.
754 Defaults to C<-WindowBits =E<gt>MAX_WBITS>.
758 Sets the initial size for the inflation buffer. If the buffer has to be
759 reallocated to increase the size, it will grow in increments of
766 The default is no dictionary.
770 Here is an example of using the B<inflateInit> optional parameter to
771 override the default buffer size.
773 inflateInit( -Bufsize => 300 ) ;
775 =head2 B<($out, $status) = $i-E<gt>inflate($buffer)>
777 Inflates the complete contents of B<$buffer>. The buffer can either be
778 a scalar or a scalar reference.
780 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
781 compressed data has been successfully reached.
782 If not successful, B<$out> will be I<undef> and B<$status> will hold
783 the I<zlib> error code.
785 The C<$buffer> parameter is modified by C<inflate>. On completion it
786 will contain what remains of the input buffer after inflation. This
787 means that C<$buffer> will be an empty string when the return status is
788 C<Z_OK>. When the return status is C<Z_STREAM_END> the C<$buffer>
789 parameter will contains what (if anything) was stored in the input
790 buffer after the deflated data stream.
792 This feature is useful when processing a file format that encapsulates
793 a compressed data stream (e.g. gzip, zip).
795 =head2 B<$status = $i-E<gt>inflateSync($buffer)>
797 Scans C<$buffer> until it reaches either a I<full flush point> or the
800 If a I<full flush point> is found, C<Z_OK> is returned and C<$buffer>
801 will be have all data up to the flush point removed. This can then be
802 passed to the C<deflate> method.
804 Any other return code means that a flush point was not found. If more
805 data is available, C<inflateSync> can be called repeatedly with more
806 compressed data until the flush point is found.
809 =head2 B<$i-E<gt>dict_adler()>
811 Returns the adler32 value for the dictionary.
813 =head2 B<$i-E<gt>msg()>
815 Returns the last error message generated by zlib.
817 =head2 B<$i-E<gt>total_in()>
819 Returns the total number of bytes compressed bytes input to inflate.
821 =head2 B<$i-E<gt>total_out()>
823 Returns the total number of uncompressed bytes output from inflate.
827 Here is an example of using B<inflate>.
834 my $x = inflateInit()
835 or die "Cannot create a inflation stream\n" ;
841 my ($output, $status) ;
842 while (read(STDIN, $input, 4096))
844 ($output, $status) = $x->inflate(\$input) ;
847 if $status == Z_OK or $status == Z_STREAM_END ;
849 last if $status != Z_OK ;
852 die "inflation failed\n"
853 unless $status == Z_STREAM_END ;
855 =head1 COMPRESS/UNCOMPRESS
857 Two high-level functions are provided by I<zlib> to perform in-memory
858 compression. They are B<compress> and B<uncompress>. Two Perl subs are
859 provided which provide similar functionality.
863 =item B<$dest = compress($source [, $level] ) ;>
865 Compresses B<$source>. If successful it returns the
866 compressed data. Otherwise it returns I<undef>.
868 The source buffer can either be a scalar or a scalar reference.
870 The B<$level> paramter defines the compression level. Valid values are
871 0 through 9, C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>,
872 C<Z_BEST_COMPRESSION>, and C<Z_DEFAULT_COMPRESSION>.
873 If B<$level> is not specified C<Z_DEFAULT_COMPRESSION> will be used.
876 =item B<$dest = uncompress($source) ;>
878 Uncompresses B<$source>. If successful it returns the uncompressed
879 data. Otherwise it returns I<undef>.
881 The source buffer can either be a scalar or a scalar reference.
885 =head1 GZIP INTERFACE
887 A number of functions are supplied in I<zlib> for reading and writing
888 I<gzip> files. This module provides an interface to most of them. In
889 general the interface provided by this module operates identically to
890 the functions provided by I<zlib>. Any differences are explained
895 =item B<$gz = gzopen(filename or filehandle, mode)>
897 This function operates identically to the I<zlib> equivalent except
898 that it returns an object which is used to access the other I<gzip>
901 As with the I<zlib> equivalent, the B<mode> parameter is used to
902 specify both whether the file is opened for reading or writing and to
903 optionally specify a a compression level. Refer to the I<zlib>
904 documentation for the exact format of the B<mode> parameter.
906 If a reference to an open filehandle is passed in place of the
907 filename, gzdopen will be called behind the scenes. The third example
908 at the end of this section, I<gzstream>, uses this feature.
910 =item B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>
912 Reads B<$size> bytes from the compressed file into B<$buffer>. If
913 B<$size> is not specified, it will default to 4096. If the scalar
914 B<$buffer> is not large enough, it will be extended automatically.
916 Returns the number of bytes actually read. On EOF it returns 0 and in
917 the case of an error, -1.
919 =item B<$bytesread = $gz-E<gt>gzreadline($line) ;>
921 Reads the next line from the compressed file into B<$line>.
923 Returns the number of bytes actually read. On EOF it returns 0 and in
924 the case of an error, -1.
926 It is legal to intermix calls to B<gzread> and B<gzreadline>.
928 At this time B<gzreadline> ignores the variable C<$/>
929 (C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use). The
930 end of a line is denoted by the C character C<'\n'>.
932 =item B<$byteswritten = $gz-E<gt>gzwrite($buffer) ;>
934 Writes the contents of B<$buffer> to the compressed file. Returns the
935 number of bytes actually written, or 0 on error.
937 =item B<$status = $gz-E<gt>gzflush($flush) ;>
939 Flushes all pending output to the compressed file.
940 Works identically to the I<zlib> function it interfaces to. Note that
941 the use of B<gzflush> can degrade compression.
943 Returns C<Z_OK> if B<$flush> is C<Z_FINISH> and all output could be
944 flushed. Otherwise the zlib error code is returned.
946 Refer to the I<zlib> documentation for the valid values of B<$flush>.
948 =item B<$status = $gz-E<gt>gzeof() ;>
950 Returns 1 if the end of file has been detected while reading the input
951 file, otherwise returns 0.
953 =item B<$gz-E<gt>gzclose>
955 Closes the compressed file. Any pending data is flushed to the file
958 =item B<$gz-E<gt>gzsetparams($level, $strategy>
960 Change settings for the deflate stream C<$gz>.
962 The list of the valid options is shown below. Options not specified
963 will remain unchanged.
965 Note: This method is only available if you are running zlib 1.0.6 or better.
971 Defines the compression level. Valid values are 0 through 9,
972 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
973 C<Z_DEFAULT_COMPRESSION>.
977 Defines the strategy used to tune the compression. The valid values are
978 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
982 =item B<$gz-E<gt>gzerror>
984 Returns the I<zlib> error message or number for the last operation
985 associated with B<$gz>. The return value will be the I<zlib> error
986 number when used in a numeric context and the I<zlib> error message
987 when used in a string context. The I<zlib> error number constants,
988 shown below, are available for use.
1000 The B<$gzerrno> scalar holds the error code associated with the most
1001 recent I<gzip> routine. Note that unlike B<gzerror()>, the error is
1002 I<not> associated with a particular file.
1004 As with B<gzerror()> it returns an error number in numeric context and
1005 an error message in string context. Unlike B<gzerror()> though, the
1006 error message will correspond to the I<zlib> message when the error is
1007 associated with I<zlib> itself, or the UNIX error message when it is
1008 not (i.e. I<zlib> returned C<Z_ERRORNO>).
1010 As there is an overlap between the error numbers used by I<zlib> and
1011 UNIX, B<$gzerrno> should only be used to check for the presence of
1012 I<an> error in numeric context. Use B<gzerror()> to check for specific
1013 I<zlib> errors. The I<gzcat> example below shows how the variable can
1021 Here is an example script which uses the interface. It implements a
1027 use Compress::Zlib ;
1029 die "Usage: gzcat file...\n"
1034 foreach $file (@ARGV) {
1037 my $gz = gzopen($file, "rb")
1038 or die "Cannot open $file: $gzerrno\n" ;
1040 print $buffer while $gz->gzread($buffer) > 0 ;
1042 die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n"
1043 if $gzerrno != Z_STREAM_END ;
1048 Below is a script which makes use of B<gzreadline>. It implements a
1049 very simple I<grep> like script.
1054 use Compress::Zlib ;
1056 die "Usage: gzgrep pattern file...\n"
1059 my $pattern = shift ;
1063 foreach $file (@ARGV) {
1064 my $gz = gzopen($file, "rb")
1065 or die "Cannot open $file: $gzerrno\n" ;
1067 while ($gz->gzreadline($_) > 0) {
1068 print if /$pattern/ ;
1071 die "Error reading from $file: $gzerrno\n"
1072 if $gzerrno != Z_STREAM_END ;
1077 This script, I<gzstream>, does the opposite of the I<gzcat> script
1078 above. It reads from standard input and writes a gzip file to standard
1084 use Compress::Zlib ;
1086 binmode STDOUT; # gzopen only sets it on the fd
1088 my $gz = gzopen(\*STDOUT, "wb")
1089 or die "Cannot open stdout: $gzerrno\n" ;
1093 or die "error writing: $gzerrno\n" ;
1098 =head2 Compress::Zlib::memGzip
1100 This function is used to create an in-memory gzip file.
1101 It creates a minimal gzip header.
1103 $dest = Compress::Zlib::memGzip($buffer) ;
1105 If successful, it returns the in-memory gzip file, otherwise it returns
1108 The buffer parameter can either be a scalar or a scalar reference.
1110 =head2 Compress::Zlib::memGunzip
1112 This function is used to uncompress an in-memory gzip file.
1114 $dest = Compress::Zlib::memGunzip($buffer) ;
1116 If successful, it returns the uncompressed gzip file, otherwise it
1119 The buffer parameter can either be a scalar or a scalar reference. The
1120 contents of the buffer parameter are destroyed after calling this
1123 =head1 CHECKSUM FUNCTIONS
1125 Two functions are provided by I<zlib> to calculate a checksum. For the
1126 Perl interface, the order of the two parameters in both functions has
1127 been reversed. This allows both running checksums and one off
1128 calculations to be done.
1130 $crc = adler32($buffer [,$crc]) ;
1131 $crc = crc32($buffer [,$crc]) ;
1133 The buffer parameters can either be a scalar or a scalar reference.
1135 If the $crc parameters is C<undef>, the crc value will be reset.
1137 =head1 ACCESSING ZIP FILES
1139 Although it is possible to use this module to access .zip files, there
1140 is a module on CPAN that will do all the hard work for you. Check out
1142 http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
1144 Assuming you don't want to use this module to access zip files there
1145 are a number of undocumented features in the zlib library you need to
1152 When calling B<inflateInit> or B<deflateInit> the B<WindowBits> parameter
1153 must be set to C<-MAX_WBITS>. This disables the creation of the zlib
1158 The zlib function B<inflate>, and so the B<inflate> method supplied in
1159 this module, assume that there is at least one trailing byte after the
1160 compressed data stream. Normally this isn't a problem because both
1161 the gzip and zip file formats will guarantee that there is data directly
1162 after the compressed data stream.
1168 All the I<zlib> constants are automatically imported when you make use
1169 of I<Compress::Zlib>.
1173 The I<Compress::Zlib> module was written by Paul Marquess,
1174 F<pmqs@cpan.org>. The latest copy of the module can be
1175 found on CPAN in F<modules/by-module/Compress/Compress-Zlib-x.x.tar.gz>.
1177 The primary site for the I<zlib> compression library is
1178 F<http://www.zlib.org>.
1180 =head1 MODIFICATION HISTORY
1182 See the Changes file.