2 # Author : Paul Marquess
3 # Created : 23 September 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.