2 package Compress::Zlib;
9 use Scalar::Util qw(dualvar);
11 use Compress::Zlib::Common ;
12 use Compress::Zlib::ParseParameters;
17 our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
19 $VERSION = '2.000_07';
20 $XS_VERSION = $VERSION;
21 $VERSION = eval $VERSION;
24 # Items to export into callers namespace by default. Note: do not export
25 # names by default without a very good reason. Use EXPORT_OK instead.
26 # Do not simply export all your public functions/methods/constants.
28 deflateInit inflateInit
79 ($constname = $AUTOLOAD) =~ s/.*:://;
80 my ($error, $val) = constant($constname);
81 Carp::croak $error if $error;
83 *{$AUTOLOAD} = sub { $val };
87 use constant FLAG_APPEND => 1 ;
88 use constant FLAG_CRC => 2 ;
89 use constant FLAG_ADLER => 4 ;
90 use constant FLAG_CONSUME_INPUT => 8 ;
94 XSLoader::load('Compress::Zlib', $XS_VERSION);
99 local @ISA = qw(DynaLoader);
100 bootstrap Compress::Zlib $XS_VERSION ;
103 # Preloaded methods go here.
105 require IO::Compress::Gzip;
106 require IO::Uncompress::Gunzip;
111 "need dictionary", # Z_NEED_DICT 2
112 "stream end", # Z_STREAM_END 1
114 "file error", # Z_ERRNO (-1)
115 "stream error", # Z_STREAM_ERROR (-2)
116 "data error", # Z_DATA_ERROR (-3)
117 "insufficient memory", # Z_MEM_ERROR (-4)
118 "buffer error", # Z_BUF_ERROR (-5)
119 "incompatible version",# Z_VERSION_ERROR(-6)
128 $Compress::Zlib::gzerrno = 0 ;
130 elsif ($value == Z_ERRNO() || $value > 2) {
131 $Compress::Zlib::gzerrno = $! ;
134 $Compress::Zlib::gzerrno = dualvar($value+0, $my_z_errmsg[2 - $value]);
143 my $test_eof = shift ;
145 my $value = $gz->errorNo() || 0 ;
148 #my $gz = $self->[0] ;
149 # gzread uses Z_STREAM_END to denote a successful end
150 $value = Z_STREAM_END() if $gz->eof() && $value == 0 ;
158 my ($file, $mode) = @_ ;
161 my %defOpts = (Level => Z_DEFAULT_COMPRESSION(),
162 Strategy => Z_DEFAULT_STRATEGY(),
166 $writing = ! ($mode =~ /r/i) ;
167 $writing = ($mode =~ /[wa]/i) ;
169 $defOpts{Level} = $1 if $mode =~ /(\d)/;
170 $defOpts{Strategy} = Z_FILTERED() if $mode =~ /f/i;
171 $defOpts{Strategy} = Z_HUFFMAN_ONLY() if $mode =~ /h/i;
173 my $infDef = $writing ? 'deflate' : 'inflate';
176 croak "gzopen: file parameter is not a filehandle or filename"
177 unless isaFilehandle $file || isaFilename $file ;
179 return undef unless $mode =~ /[rwa]/i ;
184 $gz = new IO::Compress::Gzip($file, Minimal => 1, AutoClose => 1,
186 or $Compress::Zlib::gzerrno = $IO::Compress::Gzip::GzipError;
189 $gz = new IO::Uncompress::Gunzip($file,
194 or $Compress::Zlib::gzerrno = $IO::Uncompress::Gunzip::GunzipError;
200 bless [$gz, $infDef], 'Compress::Zlib::gzFile';
203 sub Compress::Zlib::gzFile::gzread
207 return _set_gzerr(Z_STREAM_ERROR())
208 if $self->[1] ne 'inflate';
210 return 0 if $self->gzeof();
212 my $gz = $self->[0] ;
213 my $status = $gz->read($_[0], defined $_[1] ? $_[1] : 4096) ;
214 $_[0] = "" if ! defined $_[0] ;
219 sub Compress::Zlib::gzFile::gzreadline
223 my $gz = $self->[0] ;
224 $_[0] = $gz->getline() ;
226 return defined $_[0] ? length $_[0] : 0 ;
229 sub Compress::Zlib::gzFile::gzwrite
232 my $gz = $self->[0] ;
234 return _set_gzerr(Z_STREAM_ERROR())
235 if $self->[1] ne 'deflate';
237 my $status = $gz->write($_[0]) ;
242 sub Compress::Zlib::gzFile::gztell
245 my $gz = $self->[0] ;
246 my $status = $gz->tell() ;
251 sub Compress::Zlib::gzFile::gzseek
257 my $gz = $self->[0] ;
259 eval { $status = $gz->seek($offset, $whence) ; };
263 $error =~ s/^.*: /gzseek: /;
264 $error =~ s/ at .* line \d+\s*$//;
271 sub Compress::Zlib::gzFile::gzflush
276 my $gz = $self->[0] ;
277 my $status = $gz->flush($f) ;
282 sub Compress::Zlib::gzFile::gzclose
285 my $gz = $self->[0] ;
287 my $status = $gz->close() ;
292 sub Compress::Zlib::gzFile::gzeof
295 my $gz = $self->[0] ;
298 if $self->[1] ne 'inflate';
300 my $status = $gz->eof() ;
305 sub Compress::Zlib::gzFile::gzsetparams
308 croak "Usage: Compress::Zlib::gzFile::gzsetparams(file, level, strategy)"
311 my $gz = $self->[0] ;
313 my $strategy = shift;
315 return _set_gzerr(Z_STREAM_ERROR())
316 if $self->[1] ne 'deflate';
318 my $status = *$gz->{Compress}->deflateParams(-Level => $level,
319 -Strategy => $strategy);
324 sub Compress::Zlib::gzFile::gzerror
327 my $gz = $self->[0] ;
329 return $Compress::Zlib::gzerrno ;
332 sub Compress::Zlib::Deflate::new
335 my ($got) = ParseParameters(0,
337 'AppendOutput' => [1, 1, Parse_boolean, 0],
338 'CRC32' => [1, 1, Parse_boolean, 0],
339 'ADLER32' => [1, 1, Parse_boolean, 0],
340 'Bufsize' => [1, 1, Parse_unsigned, 4096],
342 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()],
343 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()],
344 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
345 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
346 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
347 'Dictionary' => [1, 1, Parse_any, ""],
351 croak "Compress::Zlib::Deflate::new: Bufsize must be >= 1, you specified " .
352 $got->value('Bufsize')
353 unless $got->value('Bufsize') >= 1;
356 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
357 $flags |= FLAG_CRC if $got->value('CRC32') ;
358 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
361 $got->value('Level'),
362 $got->value('Method'),
363 $got->value('WindowBits'),
364 $got->value('MemLevel'),
365 $got->value('Strategy'),
366 $got->value('Bufsize'),
367 $got->value('Dictionary')) ;
371 sub Compress::Zlib::Inflate::new
374 my ($got) = ParseParameters(0,
376 'AppendOutput' => [1, 1, Parse_boolean, 0],
377 'CRC32' => [1, 1, Parse_boolean, 0],
378 'ADLER32' => [1, 1, Parse_boolean, 0],
379 'ConsumeInput' => [1, 1, Parse_boolean, 1],
380 'Bufsize' => [1, 1, Parse_unsigned, 4096],
382 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
383 'Dictionary' => [1, 1, Parse_any, ""],
387 croak "Compress::Zlib::Inflate::new: Bufsize must be >= 1, you specified " .
388 $got->value('Bufsize')
389 unless $got->value('Bufsize') >= 1;
392 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
393 $flags |= FLAG_CRC if $got->value('CRC32') ;
394 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
395 $flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
397 _inflateInit($flags, $got->value('WindowBits'), $got->value('Bufsize'),
398 $got->value('Dictionary')) ;
401 sub Compress::Zlib::InflateScan::new
404 my ($got) = ParseParameters(0,
406 'CRC32' => [1, 1, Parse_boolean, 0],
407 'ADLER32' => [1, 1, Parse_boolean, 0],
408 'Bufsize' => [1, 1, Parse_unsigned, 4096],
410 'WindowBits' => [1, 1, Parse_signed, -MAX_WBITS()],
411 'Dictionary' => [1, 1, Parse_any, ""],
415 croak "Compress::Zlib::InflateScan::new: Bufsize must be >= 1, you specified " .
416 $got->value('Bufsize')
417 unless $got->value('Bufsize') >= 1;
420 #$flags |= FLAG_APPEND if $got->value('AppendOutput') ;
421 $flags |= FLAG_CRC if $got->value('CRC32') ;
422 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
423 #$flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
425 _inflateScanInit($flags, $got->value('WindowBits'), $got->value('Bufsize'),
429 sub Compress::Zlib::inflateScanStream::createDeflateStream
432 my ($got) = ParseParameters(0,
434 'AppendOutput' => [1, 1, Parse_boolean, 0],
435 'CRC32' => [1, 1, Parse_boolean, 0],
436 'ADLER32' => [1, 1, Parse_boolean, 0],
437 'Bufsize' => [1, 1, Parse_unsigned, 4096],
439 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()],
440 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()],
441 'WindowBits' => [1, 1, Parse_signed, - MAX_WBITS()],
442 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
443 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
446 croak "Compress::Zlib::InflateScan::createDeflateStream: Bufsize must be >= 1, you specified " .
447 $got->value('Bufsize')
448 unless $got->value('Bufsize') >= 1;
451 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
452 $flags |= FLAG_CRC if $got->value('CRC32') ;
453 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
455 $pkg->_createDeflateStream($flags,
456 $got->value('Level'),
457 $got->value('Method'),
458 $got->value('WindowBits'),
459 $got->value('MemLevel'),
460 $got->value('Strategy'),
461 $got->value('Bufsize'),
466 sub Compress::Zlib::inflateScanStream::inflate
472 my $status = $self->scan(@_);
474 if ($status == Z_OK() && $_[2]) {
477 $status = $self->scan(\$byte, $_[1]) ;
483 sub Compress::Zlib::deflateStream::deflateParams
486 my ($got) = ParseParameters(0, {
487 'Level' => [1, 1, Parse_signed, undef],
488 'Strategy' => [1, 1, Parse_unsigned, undef],
489 'Bufsize' => [1, 1, Parse_unsigned, undef],
493 croak "Compress::Zlib::deflateParams needs Level and/or Strategy"
494 unless $got->parsed('Level') + $got->parsed('Strategy') +
495 $got->parsed('Bufsize');
497 croak "Compress::Zlib::Inflate::deflateParams: Bufsize must be >= 1, you specified " .
498 $got->value('Bufsize')
499 if $got->parsed('Bufsize') && $got->value('Bufsize') <= 1;
502 $flags |= 1 if $got->parsed('Level') ;
503 $flags |= 2 if $got->parsed('Strategy') ;
504 $flags |= 4 if $got->parsed('Bufsize') ;
506 $self->_deflateParams($flags, $got->value('Level'),
507 $got->value('Strategy'), $got->value('Bufsize'));
513 my ($x, $output, $err, $in) =('', '', '', '') ;
517 croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
523 my $level = (@_ == 2 ? $_[1] : Z_DEFAULT_COMPRESSION() );
525 $x = new Compress::Zlib::Deflate -AppendOutput => 1, -Level => $level
528 $err = $x->deflate($in, $output) ;
529 return undef unless $err == Z_OK() ;
531 $err = $x->flush($output) ;
532 return undef unless $err == Z_OK() ;
540 my ($x, $output, $err, $in) =('', '', '', '') ;
544 croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
550 $x = new Compress::Zlib::Inflate -ConsumeInput => 0 or return undef ;
552 $err = $x->inflate($in, $output) ;
553 return undef unless $err == Z_STREAM_END() ;
559 ### This stuff is for backward compat. with Compress::Zlib 1.x
564 my ($got) = ParseParameters(0,
566 'Bufsize' => [1, 1, Parse_unsigned, 4096],
567 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()],
568 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()],
569 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
570 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
571 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
572 'Dictionary' => [1, 1, Parse_any, ""],
575 croak "Compress::Zlib::deflateInit: Bufsize must be >= 1, you specified " .
576 $got->value('Bufsize')
577 unless $got->value('Bufsize') >= 1;
584 $got->value('Level'),
585 $got->value('Method'),
586 $got->value('WindowBits'),
587 $got->value('MemLevel'),
588 $got->value('Strategy'),
589 $got->value('Bufsize'),
590 $got->value('Dictionary')) ;
592 my $x = ($status == Z_OK() ? bless $obj, "Zlib::OldDeflate" : undef) ;
593 return wantarray ? ($x, $status) : $x ;
598 my ($got) = ParseParameters(0,
600 'Bufsize' => [1, 1, Parse_unsigned, 4096],
601 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
602 'Dictionary' => [1, 1, Parse_any, ""],
606 croak "Compress::Zlib::inflateInit: Bufsize must be >= 1, you specified " .
607 $got->value('Bufsize')
608 unless $got->value('Bufsize') >= 1;
612 ($obj, $status) = _inflateInit(FLAG_CONSUME_INPUT,
613 $got->value('WindowBits'),
614 $got->value('Bufsize'),
615 $got->value('Dictionary')) ;
617 my $x = ($status == Z_OK() ? bless $obj, "Zlib::OldInflate" : undef) ;
619 wantarray ? ($x, $status) : $x ;
622 package Zlib::OldDeflate ;
625 @ISA = qw(Compress::Zlib::deflateStream);
633 my $status = $self->SUPER::deflate($_[0], $output) ;
634 wantarray ? ($output, $status) : $output ;
641 my $flag = shift || Compress::Zlib::Z_FINISH();
642 my $status = $self->SUPER::flush($output, $flag) ;
644 wantarray ? ($output, $status) : $output ;
647 package Zlib::OldInflate ;
650 @ISA = qw(Compress::Zlib::inflateStream);
656 my $status = $self->SUPER::inflate($_[0], $output) ;
657 wantarray ? ($output, $status) : $output ;
660 package Compress::Zlib ;
662 use Compress::Gzip::Constants;
666 my $x = new Compress::Zlib::Deflate(
670 -Level => Z_BEST_COMPRESSION(),
671 -WindowBits => - MAX_WBITS(),
675 # write a minimal gzip header
676 my $output = GZIP_MINIMUM_HEADER ;
678 # if the deflation buffer isn't a reference, make it one
679 my $string = (ref $_[0] ? $_[0] : \$_[0]) ;
681 my $status = $x->deflate($string, \$output) ;
685 $status = $x->flush(\$output) ;
689 return $output . pack("V V", $x->crc32(), $x->total_in()) ;
694 sub _removeGzipHeader($)
698 return Z_DATA_ERROR()
699 if length($$string) < GZIP_MIN_HEADER_SIZE ;
701 my ($magic1, $magic2, $method, $flags, $time, $xflags, $oscode) =
702 unpack ('CCCCVCC', $$string);
704 return Z_DATA_ERROR()
705 unless $magic1 == GZIP_ID1 and $magic2 == GZIP_ID2 and
706 $method == Z_DEFLATED() and !($flags & GZIP_FLG_RESERVED) ;
707 substr($$string, 0, GZIP_MIN_HEADER_SIZE) = '' ;
710 if ($flags & GZIP_FLG_FEXTRA)
712 return Z_DATA_ERROR()
713 if length($$string) < GZIP_FEXTRA_HEADER_SIZE ;
715 my ($extra_len) = unpack ('v', $$string);
716 $extra_len += GZIP_FEXTRA_HEADER_SIZE;
717 return Z_DATA_ERROR()
718 if length($$string) < $extra_len ;
720 substr($$string, 0, $extra_len) = '';
724 if ($flags & GZIP_FLG_FNAME)
726 my $name_end = index ($$string, GZIP_NULL_BYTE);
727 return Z_DATA_ERROR()
729 substr($$string, 0, $name_end + 1) = '';
733 if ($flags & GZIP_FLG_FCOMMENT)
735 my $comment_end = index ($$string, GZIP_NULL_BYTE);
736 return Z_DATA_ERROR()
737 if $comment_end == -1 ;
738 substr($$string, 0, $comment_end + 1) = '';
742 if ($flags & GZIP_FLG_FHCRC)
744 return Z_DATA_ERROR()
745 if length ($$string) < GZIP_FHCRC_SIZE ;
746 substr($$string, 0, GZIP_FHCRC_SIZE) = '';
755 # if the buffer isn't a reference, make it one
756 my $string = (ref $_[0] ? $_[0] : \$_[0]);
758 _removeGzipHeader($string) == Z_OK()
761 my $bufsize = length $$string > 4096 ? length $$string : 4096 ;
762 my $x = new Compress::Zlib::Inflate({-WindowBits => - MAX_WBITS(),
763 -Bufsize => $bufsize})
768 my $status = $x->inflate($string, $output);
770 unless $status == Z_STREAM_END();
772 if (length $$string >= 8)
774 my ($crc, $len) = unpack ("VV", substr($$string, 0, 8));
775 substr($$string, 0, 8) = '';
777 unless $len == length($output) and
778 $crc == crc32($output);
787 # Autoload methods go after __END__, and are processed by the autosplit program.
795 Compress::Zlib - Interface to zlib compression library
799 use Compress::Zlib 2 ;
801 ($d, $status) = new Compress::Zlib::Deflate( [OPT] ) ;
802 $status = $d->deflate($input, $output) ;
803 $status = $d->flush($output [, $flush_type]) ;
804 $d->deflateParams(OPTS) ;
805 $d->deflateTune(OPTS) ;
816 ($i, $status) = new Compress::Zlib::Inflate( [OPT] ) ;
817 $status = $i->inflate($input, $output [, $eof]) ;
818 $status = $i->inflateSync($input) ;
827 $dest = compress($source) ;
828 $dest = uncompress($source) ;
830 $gz = gzopen($filename or filehandle, $mode) ;
831 $bytesread = $gz->gzread($buffer [,$size]) ;
832 $bytesread = $gz->gzreadline($line) ;
833 $byteswritten = $gz->gzwrite($buffer) ;
834 $status = $gz->gzflush($flush) ;
835 $offset = $gz->gztell() ;
836 $status = $gz->gzseek($offset, $whence) ;
837 $status = $gz->gzclose() ;
838 $status = $gz->gzeof() ;
839 $status = $gz->gzsetparams($level, $strategy) ;
840 $errstring = $gz->gzerror() ;
843 $dest = Compress::Zlib::memGzip($buffer) ;
844 $dest = Compress::Zlib::memGunzip($buffer) ;
846 $crc = adler32($buffer [,$crc]) ;
847 $crc = crc32($buffer [,$crc]) ;
849 $crc = adler32_combine($crc1, $crc2, $len2)l
850 $crc = crc32_combine($adler1, $adler2, $len2)
855 # Compress::Zlib 1.x legacy interface
857 ($d, $status) = deflateInit( [OPT] ) ;
858 ($out, $status) = $d->deflate($buffer) ;
859 $status = $d->deflateParams([OPT]) ;
860 ($out, $status) = $d->flush() ;
866 ($i, $status) = inflateInit( [OPT] ) ;
867 ($out, $status) = $i->inflate($buffer) ;
868 $status = $i->inflateSync($buffer) ;
877 The I<Compress::Zlib> module provides a Perl interface to the I<zlib>
878 compression library (see L</AUTHOR> for details about where to get
880 The I<zlib> library allows reading and writing of
881 compressed data streams that conform to RFC1950, RFC1951 and RFC1952
883 Most of the I<zlib> functionality is available in I<Compress::Zlib>.
885 Unless you are working with legacy code, or you need to work directly
886 with the low-level zlib interface, it is recommended that applications
887 use one of the newer C<IO::*> interfaces provided with this module.
889 The C<Compress::Zlib> module can be split into two general areas of
890 functionality, namely a low-level in-memory compression/decompression
891 interface and a simple read/write interface to I<gzip> files.
893 Each of these areas will be discussed separately below.
896 =head1 GZIP INTERFACE
898 A number of functions are supplied in I<zlib> for reading and writing
899 I<gzip> files that conform to RFC1952. This module provides an interface
902 If you are upgrading from C<Compress::Zlib> 1.x, the following enhancements
903 have been made to the C<gzopen> interface:
909 If you want to to open either STDIN or STDOUT with C<gzopen>, you can now
910 optionally use the special filename "C<->" as a synonym for C<\*STDIN> and
915 In C<Compress::Zlib> version 1.x, C<gzopen> used the zlib library to open the
916 underlying file. This made things especially tricky when a Perl filehandle was
917 passed to C<gzopen>. Behind the scenes the numeric C file descriptor had to be
918 extracted from the Perl filehandle and this passed to the zlib library.
920 Apart from being non-portable to some operating systems, this made it difficult
921 to use C<gzopen> in situations where you wanted to extract/create a gzip data
922 stream that is embedded in a larger file, without having to resort to opening
923 and closing the file multiple times.
925 In C<Compress::Zlib> version 2.x, the C<gzopen> interface has been completely
926 rewritten to use the L<IO::Gzip|IO::Gzip> for writing gzip files and
927 L<IO::Gunzip|IO::Gunzip> for reading gzip files.
931 Addition of C<gzseek> to provide a restricted C<seek> interface.
939 A more complete and flexible interface for reading/writing gzip
940 files/buffers is included with this module. See L<IO::Gzip|IO::Gzip> and
941 L<IO::Gunzip|IO::Gunzip> for more details.
945 =item B<$gz = gzopen($filename, $mode)>
947 =item B<$gz = gzopen($filehandle, $mode)>
949 This function opens either the I<gzip> file C<$filename> for reading or
950 writing or attaches to the opened filehandle, C<$filehandle>.
951 It returns an object on success and C<undef> on failure.
953 When writing a gzip file this interface will always create the smallest
954 possible gzip header (exactly 10 bytes). If you want greater control over
955 the information stored in the gzip header (like the original filename or a
956 comment) use L<IO::Gzip|IO::Gzip> instead.
958 The second parameter, C<$mode>, is used to specify whether the file is
959 opened for reading or writing and to optionally specify a compression
960 level and compression strategy when writing. The format of the C<$mode>
961 parameter is similar to the mode parameter to the 'C' function C<fopen>,
962 so "rb" is used to open for reading and "wb" for writing.
964 To specify a compression level when writing, append a digit between 0
965 and 9 to the mode string -- 0 means no compression and 9 means maximum
967 If no compression level is specified Z_DEFAULT_COMPRESSION is used.
969 To specify the compression strategy when writing, append 'f' for filtered
970 data, 'h' for Huffman only compression, or 'R' for run-length encoding.
971 If no strategy is specified Z_DEFAULT_STRATEGY is used.
973 So, for example, "wb9" means open for writing with the maximum compression
974 using the default strategy and "wb4R" means open for writing with compression
975 level 4 and run-length encoding.
977 Refer to the I<zlib> documentation for the exact format of the C<$mode>
981 =item B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>
983 Reads C<$size> bytes from the compressed file into C<$buffer>. If
984 C<$size> is not specified, it will default to 4096. If the scalar
985 C<$buffer> is not large enough, it will be extended automatically.
987 Returns the number of bytes actually read. On EOF it returns 0 and in
988 the case of an error, -1.
990 =item B<$bytesread = $gz-E<gt>gzreadline($line) ;>
992 Reads the next line from the compressed file into C<$line>.
994 Returns the number of bytes actually read. On EOF it returns 0 and in
995 the case of an error, -1.
997 It is legal to intermix calls to C<gzread> and C<gzreadline>.
999 In addition, C<gzreadline> fully supports the use of of the variable C<$/>
1000 (C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
1001 determine what constitutes an end of line. Both paragraph mode and file
1002 slurp mode are supported.
1005 =item B<$byteswritten = $gz-E<gt>gzwrite($buffer) ;>
1007 Writes the contents of C<$buffer> to the compressed file. Returns the
1008 number of bytes actually written, or 0 on error.
1010 =item B<$status = $gz-E<gt>gzflush($flush_type) ;>
1012 Flushes all pending output into the compressed file.
1014 This method takes an optional parameter, C<$flush_type>, that controls
1015 how the flushing will be carried out. By default the C<$flush_type>
1016 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
1017 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
1018 strongly recommended that you only set the C<flush_type> parameter if
1019 you fully understand the implications of what it does - overuse of C<flush>
1020 can seriously degrade the level of compression achieved. See the C<zlib>
1021 documentation for details.
1023 Returns 1 on success, 0 on failure.
1026 =item B<$offset = $gz-E<gt>gztell() ;>
1028 Returns the uncompressed file offset.
1030 =item B<$status = $gz-E<gt>gzseek($offset, $whence) ;>
1032 Provides a sub-set of the C<seek> functionality, with the restriction
1033 that it is only legal to seek forward in the compressed file.
1034 It is a fatal error to attempt to seek backward.
1036 When opened for writing, empty parts of the file will have NULL (0x00)
1037 bytes written to them.
1039 The C<$whence> parameter should be one of SEEK_SET, SEEK_CUR or SEEK_END.
1041 Returns 1 on success, 0 on failure.
1043 =item B<$gz-E<gt>gzclose>
1045 Closes the compressed file. Any pending data is flushed to the file
1046 before it is closed.
1048 Returns 1 on success, 0 on failure.
1050 =item B<$gz-E<gt>gzsetparams($level, $strategy>
1052 Change settings for the deflate stream C<$gz>.
1054 The list of the valid options is shown below. Options not specified
1055 will remain unchanged.
1057 Note: This method is only available if you are running zlib 1.0.6 or better.
1063 Defines the compression level. Valid values are 0 through 9,
1064 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1065 C<Z_DEFAULT_COMPRESSION>.
1069 Defines the strategy used to tune the compression. The valid values are
1070 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1074 =item B<$gz-E<gt>gzerror>
1076 Returns the I<zlib> error message or number for the last operation
1077 associated with C<$gz>. The return value will be the I<zlib> error
1078 number when used in a numeric context and the I<zlib> error message
1079 when used in a string context. The I<zlib> error number constants,
1080 shown below, are available for use.
1092 The C<$gzerrno> scalar holds the error code associated with the most
1093 recent I<gzip> routine. Note that unlike C<gzerror()>, the error is
1094 I<not> associated with a particular file.
1096 As with C<gzerror()> it returns an error number in numeric context and
1097 an error message in string context. Unlike C<gzerror()> though, the
1098 error message will correspond to the I<zlib> message when the error is
1099 associated with I<zlib> itself, or the UNIX error message when it is
1100 not (i.e. I<zlib> returned C<Z_ERRORNO>).
1102 As there is an overlap between the error numbers used by I<zlib> and
1103 UNIX, C<$gzerrno> should only be used to check for the presence of
1104 I<an> error in numeric context. Use C<gzerror()> to check for specific
1105 I<zlib> errors. The I<gzcat> example below shows how the variable can
1113 Here is an example script which uses the interface. It implements a
1119 use Compress::Zlib ;
1121 # use stdin if no files supplied
1122 @ARGV = '-' unless @ARGV ;
1124 foreach my $file (@ARGV) {
1127 my $gz = gzopen($file, "rb")
1128 or die "Cannot open $file: $gzerrno\n" ;
1130 print $buffer while $gz->gzread($buffer) > 0 ;
1132 die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n"
1133 if $gzerrno != Z_STREAM_END ;
1138 Below is a script which makes use of C<gzreadline>. It implements a
1139 very simple I<grep> like script.
1144 use Compress::Zlib ;
1146 die "Usage: gzgrep pattern [file...]\n"
1149 my $pattern = shift ;
1151 # use stdin if no files supplied
1152 @ARGV = '-' unless @ARGV ;
1154 foreach my $file (@ARGV) {
1155 my $gz = gzopen($file, "rb")
1156 or die "Cannot open $file: $gzerrno\n" ;
1158 while ($gz->gzreadline($_) > 0) {
1159 print if /$pattern/ ;
1162 die "Error reading from $file: $gzerrno\n"
1163 if $gzerrno != Z_STREAM_END ;
1168 This script, I<gzstream>, does the opposite of the I<gzcat> script
1169 above. It reads from standard input and writes a gzip data stream to
1175 use Compress::Zlib ;
1177 binmode STDOUT; # gzopen only sets it on the fd
1179 my $gz = gzopen(\*STDOUT, "wb")
1180 or die "Cannot open stdout: $gzerrno\n" ;
1184 or die "error writing: $gzerrno\n" ;
1189 =head2 Compress::Zlib::memGzip
1191 This function is used to create an in-memory gzip file with the minimum
1192 possible gzip header (exactly 10 bytes).
1194 $dest = Compress::Zlib::memGzip($buffer) ;
1196 If successful, it returns the in-memory gzip file, otherwise it returns
1199 The C<$buffer> parameter can either be a scalar or a scalar reference.
1201 See L<IO::Gzip|IO::Gzip> for an alternative way to carry out in-memory gzip
1204 =head2 Compress::Zlib::memGunzip
1206 This function is used to uncompress an in-memory gzip file.
1208 $dest = Compress::Zlib::memGunzip($buffer) ;
1210 If successful, it returns the uncompressed gzip file, otherwise it
1213 The C<$buffer> parameter can either be a scalar or a scalar reference. The
1214 contents of the C<$buffer> parameter are destroyed after calling this function.
1216 See L<IO::Gunzip|IO::Gunzip> for an alternative way to carry out in-memory gzip
1219 =head1 COMPRESS/UNCOMPRESS
1221 Two functions are provided to perform in-memory compression/uncompression of
1222 RFC 1950 data streams. They are called C<compress> and C<uncompress>.
1226 =item B<$dest = compress($source [, $level] ) ;>
1228 Compresses C<$source>. If successful it returns the compressed
1229 data. Otherwise it returns I<undef>.
1231 The source buffer, C<$source>, can either be a scalar or a scalar
1234 The C<$level> parameter defines the compression level. Valid values are
1235 0 through 9, C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>,
1236 C<Z_BEST_COMPRESSION>, and C<Z_DEFAULT_COMPRESSION>.
1237 If C<$level> is not specified C<Z_DEFAULT_COMPRESSION> will be used.
1240 =item B<$dest = uncompress($source) ;>
1242 Uncompresses C<$source>. If successful it returns the uncompressed
1243 data. Otherwise it returns I<undef>.
1245 The source buffer can either be a scalar or a scalar reference.
1249 Please note: the two functions defined above are I<not> compatible with
1250 the Unix commands of the same name.
1252 See L<IO::Deflate|IO::Deflate> and L<IO::Inflate|IO::Inflate> included with
1253 this distribution for an alternative interface for reading/writing RFC 1950
1256 =head1 CHECKSUM FUNCTIONS
1258 Two functions are provided by I<zlib> to calculate checksums. For the
1259 Perl interface, the order of the two parameters in both functions has
1260 been reversed. This allows both running checksums and one off
1261 calculations to be done.
1263 $crc = adler32($buffer [,$crc]) ;
1264 $crc = crc32($buffer [,$crc]) ;
1266 The buffer parameters can either be a scalar or a scalar reference.
1268 If the $crc parameters is C<undef>, the crc value will be reset.
1270 If you have built this module with zlib 1.2.3 or better, two more
1271 CRC-related functions are available.
1273 $crc = adler32_combine($crc1, $crc2, $len2)l
1274 $crc = crc32_combine($adler1, $adler2, $len2)
1276 These functions allow checksums to be merged.
1278 =head1 Compress::Zlib::Deflate
1280 This section defines an interface that allows in-memory compression using
1281 the I<deflate> interface provided by zlib.
1283 Note: The interface defined in this section is different from version
1284 1.x of this module. The original deflate interface is still available
1285 for backward compatibility and is documented in the section
1286 L<Compress::Zlib 1.x Deflate Interface>.
1288 Here is a definition of the interface available:
1291 =head2 B<($d, $status) = new Compress::Zlib::Deflate( [OPT] ) >
1293 Initialises a deflation object.
1295 If you are familiar with the I<zlib> library, it combines the
1296 features of the I<zlib> functions C<deflateInit>, C<deflateInit2>
1297 and C<deflateSetDictionary>.
1299 If successful, it will return the initialised deflation object, C<$d>
1300 and a C<$status> of C<Z_OK> in a list context. In scalar context it
1301 returns the deflation object, C<$d>, only.
1303 If not successful, the returned deflation object, C<$d>, will be
1304 I<undef> and C<$status> will hold the a I<zlib> error code.
1306 The function optionally takes a number of named options specified as
1307 C<-Name =E<gt> value> pairs. This allows individual options to be
1308 tailored without having to specify them all in the parameter list.
1310 For backward compatibility, it is also possible to pass the parameters
1311 as a reference to a hash containing the name=>value pairs.
1313 Below is a list of the valid options:
1319 Defines the compression level. Valid values are 0 through 9,
1320 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1321 C<Z_DEFAULT_COMPRESSION>.
1323 The default is C<-Level =E<gt> Z_DEFAULT_COMPRESSION>.
1327 Defines the compression method. The only valid value at present (and
1328 the default) is C<-Method =E<gt> Z_DEFLATED>.
1330 =item B<-WindowBits>
1332 For a definition of the meaning and valid values for C<WindowBits>
1333 refer to the I<zlib> documentation for I<deflateInit2>.
1335 Defaults to C<-WindowBits =E<gt> MAX_WBITS>.
1339 For a definition of the meaning and valid values for C<MemLevel>
1340 refer to the I<zlib> documentation for I<deflateInit2>.
1342 Defaults to C<-MemLevel =E<gt> MAX_MEM_LEVEL>.
1346 Defines the strategy used to tune the compression. The valid values are
1347 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED>, C<Z_RLE>, C<Z_FIXED> and
1350 The default is C<-Strategy =E<gt>Z_DEFAULT_STRATEGY>.
1352 =item B<-Dictionary>
1354 When a dictionary is specified I<Compress::Zlib> will automatically
1355 call C<deflateSetDictionary> directly after calling C<deflateInit>. The
1356 Adler32 value for the dictionary can be obtained by calling the method
1357 C<$d-E<gt>dict_adler()>.
1359 The default is no dictionary.
1363 Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
1364 and C<$d-E<gt>flush> methods. If the buffer has to be
1365 reallocated to increase the size, it will grow in increments of
1368 The default buffer size is 4096.
1370 =item B<-AppendOutput>
1372 This option controls how data is written to the output buffer by the
1373 C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
1375 If the C<AppendOutput> option is set to false, the output buffers in the
1376 C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods will be truncated before
1377 uncompressed data is written to them.
1379 If the option is set to true, uncompressed data will be appended to the
1380 output buffer in the C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
1382 This option defaults to false.
1386 If set to true, a crc32 checksum of the uncompressed data will be
1387 calculated. Use the C<$d-E<gt>crc32> method to retrieve this value.
1389 This option defaults to false.
1394 If set to true, an adler32 checksum of the uncompressed data will be
1395 calculated. Use the C<$d-E<gt>adler32> method to retrieve this value.
1397 This option defaults to false.
1402 Here is an example of using the C<Compress::Zlib::Deflate> optional
1403 parameter list to override the default buffer size and compression
1404 level. All other options will take their default values.
1406 my $d = new Compress::Zlib::Deflate ( -Bufsize => 300,
1407 -Level => Z_BEST_SPEED ) ;
1410 =head2 B<$status = $d-E<gt>deflate($input, $output)>
1412 Deflates the contents of C<$input> and writes the compressed data to
1415 The C<$input> and C<$output> parameters can be either scalars or scalar
1418 When finished, C<$input> will be completely processed (assuming there
1419 were no errors). If the deflation was successful it writes the deflated
1420 data to C<$output> and returns a status value of C<Z_OK>.
1422 On error, it returns a I<zlib> error code.
1424 If the C<AppendOutput> option is set to true in the constructor for
1425 the C<$d> object, the compressed data will be appended to C<$output>. If
1426 it is false, C<$output> will be truncated before any compressed data is
1429 B<Note>: This method will not necessarily write compressed data to
1430 C<$output> every time it is called. So do not assume that there has been
1431 an error if the contents of C<$output> is empty on returning from
1432 this method. As long as the return code from the method is C<Z_OK>,
1433 the deflate has succeeded.
1435 =head2 B<$status = $d-E<gt>flush($output [, $flush_type]) >
1437 Typically used to finish the deflation. Any pending output will be
1438 written to C<$output>.
1440 Returns C<Z_OK> if successful.
1442 Note that flushing can seriously degrade the compression ratio, so it
1443 should only be used to terminate a decompression (using C<Z_FINISH>) or
1444 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
1446 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
1447 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
1448 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
1449 C<flush_type> parameter if you fully understand the implications of
1450 what it does. See the C<zlib> documentation for details.
1452 If the C<AppendOutput> option is set to true in the constructor for
1453 the C<$d> object, the compressed data will be appended to C<$output>. If
1454 it is false, C<$output> will be truncated before any compressed data is
1457 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
1459 Change settings for the deflate object C<$d>.
1461 The list of the valid options is shown below. Options not specified
1462 will remain unchanged.
1469 Defines the compression level. Valid values are 0 through 9,
1470 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1471 C<Z_DEFAULT_COMPRESSION>.
1475 Defines the strategy used to tune the compression. The valid values are
1476 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1480 Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
1481 and C<$d-E<gt>flush> methods. If the buffer has to be
1482 reallocated to increase the size, it will grow in increments of
1488 =head2 B<$status = $d-E<gt>deflateTune($good_length, $max_lazy, $nice_length, $max_chain)>
1490 Tune the internal settings for the deflate object C<$d>. This option is
1491 only available if you are running zlib 1.2.2.3 or better.
1493 Refer to the documentation in zlib.h for instructions on how to fly
1496 =head2 B<$d-E<gt>dict_adler()>
1498 Returns the adler32 value for the dictionary.
1500 =head2 B<$d-E<gt>crc32()>
1502 Returns the crc32 value for the uncompressed data to date.
1504 If the C<CRC32> option is not enabled in the constructor for this object,
1505 this method will always return 0;
1507 =head2 B<$d-E<gt>adler32()>
1509 Returns the adler32 value for the uncompressed data to date.
1511 =head2 B<$d-E<gt>msg()>
1513 Returns the last error message generated by zlib.
1515 =head2 B<$d-E<gt>total_in()>
1517 Returns the total number of bytes uncompressed bytes input to deflate.
1519 =head2 B<$d-E<gt>total_out()>
1521 Returns the total number of compressed bytes output from deflate.
1523 =head2 B<$d-E<gt>get_Strategy()>
1525 Returns the deflation strategy currently used. Valid values are
1526 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1529 =head2 B<$d-E<gt>get_Level()>
1531 Returns the compression level being used.
1533 =head2 B<$d-E<gt>get_BufSize()>
1535 Returns the buffer size used to carry out the compression.
1540 Here is a trivial example of using C<deflate>. It simply reads standard
1541 input, deflates it and writes it to standard output.
1546 use Compress::Zlib 2 ;
1550 my $x = new Compress::Zlib::Deflate
1551 or die "Cannot create a deflation stream\n" ;
1553 my ($output, $status) ;
1556 $status = $x->deflate($_, $output) ;
1559 or die "deflation failed\n" ;
1564 $status = $x->flush($output) ;
1567 or die "deflation failed\n" ;
1571 =head1 Compress::Zlib::Inflate
1573 This section defines an interface that allows in-memory uncompression using
1574 the I<inflate> interface provided by zlib.
1576 Note: The interface defined in this section is different from version
1577 1.x of this module. The original inflate interface is still available
1578 for backward compatibility and is documented in the section
1579 L<Compress::Zlib 1.x Inflate Interface>.
1581 Here is a definition of the interface:
1584 =head2 B< ($i, $status) = new Compress::Zlib::Inflate( [OPT] ) >
1586 Initialises an inflation object.
1588 In a list context it returns the inflation object, C<$i>, and the
1589 I<zlib> status code (C<$status>). In a scalar context it returns the
1590 inflation object only.
1592 If successful, C<$i> will hold the inflation object and C<$status> will
1595 If not successful, C<$i> will be I<undef> and C<$status> will hold the
1598 The function optionally takes a number of named options specified as
1599 C<-Name =E<gt> value> pairs. This allows individual options to be
1600 tailored without having to specify them all in the parameter list.
1602 For backward compatibility, it is also possible to pass the parameters
1603 as a reference to a hash containing the name=E<gt>value pairs.
1605 Here is a list of the valid options:
1609 =item B<-WindowBits>
1611 To uncompress an RFC1950 data stream, set C<WindowBits> to a positive number.
1613 To uncompress an RFC1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
1615 For a full definition of the meaning and valid values for C<WindowBits> refer
1616 to the I<zlib> documentation for I<inflateInit2>.
1618 Defaults to C<-WindowBits =E<gt>MAX_WBITS>.
1622 Sets the initial size for the output buffer used by the C<$i-E<gt>inflate>
1623 method. If the output buffer in this method has to be reallocated to
1624 increase the size, it will grow in increments of C<Bufsize>.
1628 =item B<-Dictionary>
1630 The default is no dictionary.
1632 =item B<-AppendOutput>
1634 This option controls how data is written to the output buffer by the
1635 C<$i-E<gt>inflate> method.
1637 If the option is set to false, the output buffer in the C<$i-E<gt>inflate>
1638 method will be truncated before uncompressed data is written to it.
1640 If the option is set to true, uncompressed data will be appended to the
1641 output buffer by the C<$i-E<gt>inflate> method.
1643 This option defaults to false.
1648 If set to true, a crc32 checksum of the uncompressed data will be
1649 calculated. Use the C<$i-E<gt>crc32> method to retrieve this value.
1651 This option defaults to false.
1655 If set to true, an adler32 checksum of the uncompressed data will be
1656 calculated. Use the C<$i-E<gt>adler32> method to retrieve this value.
1658 This option defaults to false.
1660 =item B<-ConsumeInput>
1662 If set to true, this option will remove compressed data from the input
1663 buffer of the the C< $i-E<gt>inflate > method as the inflate progresses.
1665 This option can be useful when you are processing compressed data that is
1666 embedded in another file/buffer. In this case the data that immediately
1667 follows the compressed stream will be left in the input buffer.
1669 This option defaults to true.
1673 Here is an example of using an optional parameter to override the default
1676 my ($i, $status) = new Compress::Zlib::Inflate( -Bufsize => 300 ) ;
1678 =head2 B< $status = $i-E<gt>inflate($input, $output [,$eof]) >
1680 Inflates the complete contents of C<$input> and writes the uncompressed
1681 data to C<$output>. The C<$input> and C<$output> parameters can either be
1682 scalars or scalar references.
1684 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
1685 compressed data has been successfully reached.
1687 If not successful C<$status> will hold the I<zlib> error code.
1689 If the C<ConsumeInput> option has been set to true when the
1690 C<Compress::Zlib::Inflate> object is created, the C<$input> parameter
1691 is modified by C<inflate>. On completion it will contain what remains
1692 of the input buffer after inflation. In practice, this means that when
1693 the return status is C<Z_OK> the C<$input> parameter will contain an
1694 empty string, and when the return status is C<Z_STREAM_END> the C<$input>
1695 parameter will contains what (if anything) was stored in the input buffer
1696 after the deflated data stream.
1698 This feature is useful when processing a file format that encapsulates
1699 a compressed data stream (e.g. gzip, zip) and there is useful data
1700 immediately after the deflation stream.
1702 If the C<AppendOutput> option is set to true in the constructor for
1703 this object, the uncompressed data will be appended to C<$output>. If
1704 it is false, C<$output> will be truncated before any uncompressed data
1707 The C<$eof> parameter needs a bit of explanation.
1709 Prior to version 1.2.0, zlib assumed that there was at least one trailing
1710 byte immediately after the compressed data stream when it was carrying out
1711 decompression. This normally isn't a problem because the majority of zlib
1712 applications guarantee that there will be data directly after the
1713 compressed data stream. For example, both gzip (RFC1950) and zip both
1714 define trailing data that follows the compressed data stream.
1716 The C<$eof> parameter only needs to be used if B<all> of the following
1723 You are either using a copy of zlib that is older than version 1.2.0 or you
1724 want your application code to be able to run with as many different
1725 versions of zlib as possible.
1729 You have set the C<WindowBits> parameter to C<-MAX_WBITS> in the constructor
1730 for this object, i.e. you are uncompressing a raw deflated data stream
1735 There is no data immediately after the compressed data stream.
1739 If B<all> of these are the case, then you need to set the C<$eof> parameter to
1740 true on the final call (and only the final call) to C<$i-E<gt>inflate>.
1742 If you have built this module with zlib >= 1.2.0, the C<$eof> parameter is
1743 ignored. You can still set it if you want, but it won't be used behind the
1746 =head2 B<$status = $i-E<gt>inflateSync($input)>
1748 This method can be used to attempt to recover good data from a compressed
1749 data stream that is partially corrupt.
1750 It scans C<$input> until it reaches either a I<full flush point> or the
1753 If a I<full flush point> is found, C<Z_OK> is returned and C<$input>
1754 will be have all data up to the flush point removed. This data can then be
1755 passed to the C<$i-E<gt>inflate> method to be uncompressed.
1757 Any other return code means that a flush point was not found. If more
1758 data is available, C<inflateSync> can be called repeatedly with more
1759 compressed data until the flush point is found.
1761 Note I<full flush points> are not present by default in compressed
1762 data streams. They must have been added explicitly when the data stream
1763 was created by calling C<Compress::Deflate::flush> with C<Z_FULL_FLUSH>.
1766 =head2 B<$i-E<gt>dict_adler()>
1768 Returns the adler32 value for the dictionary.
1770 =head2 B<$i-E<gt>crc32()>
1772 Returns the crc32 value for the uncompressed data to date.
1774 If the C<CRC32> option is not enabled in the constructor for this object,
1775 this method will always return 0;
1777 =head2 B<$i-E<gt>adler32()>
1779 Returns the adler32 value for the uncompressed data to date.
1781 If the C<ADLER32> option is not enabled in the constructor for this object,
1782 this method will always return 0;
1784 =head2 B<$i-E<gt>msg()>
1786 Returns the last error message generated by zlib.
1788 =head2 B<$i-E<gt>total_in()>
1790 Returns the total number of bytes compressed bytes input to inflate.
1792 =head2 B<$i-E<gt>total_out()>
1794 Returns the total number of uncompressed bytes output from inflate.
1796 =head2 B<$d-E<gt>get_BufSize()>
1798 Returns the buffer size used to carry out the decompression.
1802 Here is an example of using C<inflate>.
1807 use Compress::Zlib 2 ;
1809 my $x = new Compress::Zlib::Inflate()
1810 or die "Cannot create a inflation stream\n" ;
1816 my ($output, $status) ;
1817 while (read(STDIN, $input, 4096))
1819 $status = $x->inflate(\$input, $output) ;
1822 if $status == Z_OK or $status == Z_STREAM_END ;
1824 last if $status != Z_OK ;
1827 die "inflation failed\n"
1828 unless $status == Z_STREAM_END ;
1830 =head1 Compress::Zlib 1.x Deflate Interface
1832 This section defines the interface available in C<Compress::Zlib> version
1833 1.x that allows in-memory compression using the I<deflate> interface
1836 Here is a definition of the interface available:
1839 =head2 B<($d, $status) = deflateInit( [OPT] )>
1841 Initialises a deflation stream.
1843 It combines the features of the I<zlib> functions C<deflateInit>,
1844 C<deflateInit2> and C<deflateSetDictionary>.
1846 If successful, it will return the initialised deflation stream, C<$d>
1847 and C<$status> of C<Z_OK> in a list context. In scalar context it
1848 returns the deflation stream, C<$d>, only.
1850 If not successful, the returned deflation stream (C<$d>) will be
1851 I<undef> and C<$status> will hold the exact I<zlib> error code.
1853 The function optionally takes a number of named options specified as
1854 C<-Name=E<gt>value> pairs. This allows individual options to be
1855 tailored without having to specify them all in the parameter list.
1857 For backward compatibility, it is also possible to pass the parameters
1858 as a reference to a hash containing the name=>value pairs.
1860 The function takes one optional parameter, a reference to a hash. The
1861 contents of the hash allow the deflation interface to be tailored.
1863 Here is a list of the valid options:
1869 Defines the compression level. Valid values are 0 through 9,
1870 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1871 C<Z_DEFAULT_COMPRESSION>.
1873 The default is C<-Level =E<gt>Z_DEFAULT_COMPRESSION>.
1877 Defines the compression method. The only valid value at present (and
1878 the default) is C<-Method =E<gt>Z_DEFLATED>.
1880 =item B<-WindowBits>
1882 To create an RFC1950 data stream, set C<WindowBits> to a positive number.
1884 To create an RFC1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
1886 For a full definition of the meaning and valid values for C<WindowBits> refer
1887 to the I<zlib> documentation for I<deflateInit2>.
1889 Defaults to C<-WindowBits =E<gt>MAX_WBITS>.
1893 For a definition of the meaning and valid values for C<MemLevel>
1894 refer to the I<zlib> documentation for I<deflateInit2>.
1896 Defaults to C<-MemLevel =E<gt>MAX_MEM_LEVEL>.
1900 Defines the strategy used to tune the compression. The valid values are
1901 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1903 The default is C<-Strategy =E<gt>Z_DEFAULT_STRATEGY>.
1905 =item B<-Dictionary>
1907 When a dictionary is specified I<Compress::Zlib> will automatically
1908 call C<deflateSetDictionary> directly after calling C<deflateInit>. The
1909 Adler32 value for the dictionary can be obtained by calling the method
1910 C<$d->dict_adler()>.
1912 The default is no dictionary.
1916 Sets the initial size for the deflation buffer. If the buffer has to be
1917 reallocated to increase the size, it will grow in increments of
1920 The default is 4096.
1924 Here is an example of using the C<deflateInit> optional parameter list
1925 to override the default buffer size and compression level. All other
1926 options will take their default values.
1928 deflateInit( -Bufsize => 300,
1929 -Level => Z_BEST_SPEED ) ;
1932 =head2 B<($out, $status) = $d-E<gt>deflate($buffer)>
1935 Deflates the contents of C<$buffer>. The buffer can either be a scalar
1936 or a scalar reference. When finished, C<$buffer> will be
1937 completely processed (assuming there were no errors). If the deflation
1938 was successful it returns the deflated output, C<$out>, and a status
1939 value, C<$status>, of C<Z_OK>.
1941 On error, C<$out> will be I<undef> and C<$status> will contain the
1944 In a scalar context C<deflate> will return C<$out> only.
1946 As with the I<deflate> function in I<zlib>, it is not necessarily the
1947 case that any output will be produced by this method. So don't rely on
1948 the fact that C<$out> is empty for an error test.
1951 =head2 B<($out, $status) = $d-E<gt>flush([flush_type])>
1953 Typically used to finish the deflation. Any pending output will be
1954 returned via C<$out>.
1955 C<$status> will have a value C<Z_OK> if successful.
1957 In a scalar context C<flush> will return C<$out> only.
1959 Note that flushing can seriously degrade the compression ratio, so it
1960 should only be used to terminate a decompression (using C<Z_FINISH>) or
1961 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
1963 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
1964 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
1965 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
1966 C<flush_type> parameter if you fully understand the implications of
1967 what it does. See the C<zlib> documentation for details.
1969 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
1971 Change settings for the deflate stream C<$d>.
1973 The list of the valid options is shown below. Options not specified
1974 will remain unchanged.
1980 Defines the compression level. Valid values are 0 through 9,
1981 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1982 C<Z_DEFAULT_COMPRESSION>.
1986 Defines the strategy used to tune the compression. The valid values are
1987 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1991 =head2 B<$d-E<gt>dict_adler()>
1993 Returns the adler32 value for the dictionary.
1995 =head2 B<$d-E<gt>msg()>
1997 Returns the last error message generated by zlib.
1999 =head2 B<$d-E<gt>total_in()>
2001 Returns the total number of bytes uncompressed bytes input to deflate.
2003 =head2 B<$d-E<gt>total_out()>
2005 Returns the total number of compressed bytes output from deflate.
2010 Here is a trivial example of using C<deflate>. It simply reads standard
2011 input, deflates it and writes it to standard output.
2016 use Compress::Zlib ;
2020 my $x = deflateInit()
2021 or die "Cannot create a deflation stream\n" ;
2023 my ($output, $status) ;
2026 ($output, $status) = $x->deflate($_) ;
2029 or die "deflation failed\n" ;
2034 ($output, $status) = $x->flush() ;
2037 or die "deflation failed\n" ;
2041 =head1 Compress::Zlib 1.x Inflate Interface
2043 This section defines the interface available in C<Compress::Zlib> version
2044 1.x that allows in-memory uncompression using the I<deflate> interface
2047 Here is a definition of the interface:
2050 =head2 B<($i, $status) = inflateInit()>
2052 Initializes an inflation stream.
2054 In a list context it returns the inflation stream, C<$i>, and the
2055 I<zlib> status code (C<$status>). In a scalar context it returns the
2056 inflation stream only.
2058 If successful, C<$i> will hold the inflation stream and C<$status> will
2061 If not successful, C<$i> will be I<undef> and C<$status> will hold the
2064 The function optionally takes a number of named options specified as
2065 C<-Name=E<gt>value> pairs. This allows individual options to be
2066 tailored without having to specify them all in the parameter list.
2068 For backward compatibility, it is also possible to pass the parameters
2069 as a reference to a hash containing the name=>value pairs.
2071 The function takes one optional parameter, a reference to a hash. The
2072 contents of the hash allow the deflation interface to be tailored.
2074 Here is a list of the valid options:
2078 =item B<-WindowBits>
2080 To uncompress an RFC1950 data stream, set C<WindowBits> to a positive number.
2082 To uncompress an RFC1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
2084 For a full definition of the meaning and valid values for C<WindowBits> refer
2085 to the I<zlib> documentation for I<inflateInit2>.
2087 Defaults to C<-WindowBits =E<gt>MAX_WBITS>.
2091 Sets the initial size for the inflation buffer. If the buffer has to be
2092 reallocated to increase the size, it will grow in increments of
2097 =item B<-Dictionary>
2099 The default is no dictionary.
2103 Here is an example of using the C<inflateInit> optional parameter to
2104 override the default buffer size.
2106 inflateInit( -Bufsize => 300 ) ;
2108 =head2 B<($out, $status) = $i-E<gt>inflate($buffer)>
2110 Inflates the complete contents of C<$buffer>. The buffer can either be
2111 a scalar or a scalar reference.
2113 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
2114 compressed data has been successfully reached.
2115 If not successful, C<$out> will be I<undef> and C<$status> will hold
2116 the I<zlib> error code.
2118 The C<$buffer> parameter is modified by C<inflate>. On completion it
2119 will contain what remains of the input buffer after inflation. This
2120 means that C<$buffer> will be an empty string when the return status is
2121 C<Z_OK>. When the return status is C<Z_STREAM_END> the C<$buffer>
2122 parameter will contains what (if anything) was stored in the input
2123 buffer after the deflated data stream.
2125 This feature is useful when processing a file format that encapsulates
2126 a compressed data stream (e.g. gzip, zip).
2128 =head2 B<$status = $i-E<gt>inflateSync($buffer)>
2130 Scans C<$buffer> until it reaches either a I<full flush point> or the
2133 If a I<full flush point> is found, C<Z_OK> is returned and C<$buffer>
2134 will be have all data up to the flush point removed. This can then be
2135 passed to the C<deflate> method.
2137 Any other return code means that a flush point was not found. If more
2138 data is available, C<inflateSync> can be called repeatedly with more
2139 compressed data until the flush point is found.
2142 =head2 B<$i-E<gt>dict_adler()>
2144 Returns the adler32 value for the dictionary.
2146 =head2 B<$i-E<gt>msg()>
2148 Returns the last error message generated by zlib.
2150 =head2 B<$i-E<gt>total_in()>
2152 Returns the total number of bytes compressed bytes input to inflate.
2154 =head2 B<$i-E<gt>total_out()>
2156 Returns the total number of uncompressed bytes output from inflate.
2160 Here is an example of using C<inflate>.
2165 use Compress::Zlib ;
2167 my $x = inflateInit()
2168 or die "Cannot create a inflation stream\n" ;
2174 my ($output, $status) ;
2175 while (read(STDIN, $input, 4096))
2177 ($output, $status) = $x->inflate(\$input) ;
2180 if $status == Z_OK or $status == Z_STREAM_END ;
2182 last if $status != Z_OK ;
2185 die "inflation failed\n"
2186 unless $status == Z_STREAM_END ;
2188 =head1 ACCESSING ZIP FILES
2190 Although it is possible (with some effort on your part) to use this
2191 module to access .zip files, there is a module on CPAN that will do all
2192 the hard work for you. Check out the C<Archive::Zip> module on CPAN at
2194 http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
2199 All the I<zlib> constants are automatically imported when you make use
2200 of I<Compress::Zlib>.
2205 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::Uncompress::AnyInflate>
2207 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
2209 L<File::GlobMapper|File::GlobMapper>, L<Archive::Tar|Archive::Zip>,
2210 L<IO::Zlib|IO::Zlib>
2212 For RFC 1950, 1951 and 1952 see
2213 F<http://www.faqs.org/rfcs/rfc1950.html>,
2214 F<http://www.faqs.org/rfcs/rfc1951.html> and
2215 F<http://www.faqs.org/rfcs/rfc1952.html>
2217 The primary site for the gzip program is F<http://www.gzip.org>.
2221 The I<Compress::Zlib> module was written by Paul Marquess,
2222 F<pmqs@cpan.org>. The latest copy of the module can be
2223 found on CPAN in F<modules/by-module/Compress/Compress-Zlib-x.x.tar.gz>.
2225 The I<zlib> compression library was written by Jean-loup Gailly
2226 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
2228 The primary site for the I<zlib> compression library is
2229 F<http://www.zlib.org>.
2231 =head1 MODIFICATION HISTORY
2233 See the Changes file.
2235 =head1 COPYRIGHT AND LICENSE
2238 Copyright (c) 1995-2006 Paul Marquess. All rights reserved.
2239 This program is free software; you can redistribute it and/or
2240 modify it under the same terms as Perl itself.