2 package Compress::Zlib;
9 use Scalar::Util qw(dualvar);
11 use IO::Compress::Base::Common ;
12 use Compress::Raw::Zlib;
13 use IO::Compress::Gzip;
14 use IO::Uncompress::Gunzip;
19 our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
22 $XS_VERSION = $VERSION;
23 $VERSION = eval $VERSION;
26 # Items to export into callers namespace by default. Note: do not export
27 # names by default without a very good reason. Use EXPORT_OK instead.
28 # Do not simply export all your public functions/methods/constants.
30 deflateInit inflateInit
37 push @EXPORT, @Compress::Raw::Zlib::EXPORT ;
41 *zlib_version = \&Compress::Raw::Zlib::zlib_version;
46 ($constname = $AUTOLOAD) =~ s/.*:://;
47 my ($error, $val) = Compress::Raw::Zlib::constant($constname);
48 Carp::croak $error if $error;
50 *{$AUTOLOAD} = sub { $val };
54 use constant FLAG_APPEND => 1 ;
55 use constant FLAG_CRC => 2 ;
56 use constant FLAG_ADLER => 4 ;
57 use constant FLAG_CONSUME_INPUT => 8 ;
62 "need dictionary", # Z_NEED_DICT 2
63 "stream end", # Z_STREAM_END 1
65 "file error", # Z_ERRNO (-1)
66 "stream error", # Z_STREAM_ERROR (-2)
67 "data error", # Z_DATA_ERROR (-3)
68 "insufficient memory", # Z_MEM_ERROR (-4)
69 "buffer error", # Z_BUF_ERROR (-5)
70 "incompatible version",# Z_VERSION_ERROR(-6)
79 $Compress::Zlib::gzerrno = 0 ;
81 elsif ($value == Z_ERRNO() || $value > 2) {
82 $Compress::Zlib::gzerrno = $! ;
85 $Compress::Zlib::gzerrno = dualvar($value+0, $my_z_errmsg[2 - $value]);
94 my $test_eof = shift ;
96 my $value = $gz->errorNo() || 0 ;
99 #my $gz = $self->[0] ;
100 # gzread uses Z_STREAM_END to denote a successful end
101 $value = Z_STREAM_END() if $gz->eof() && $value == 0 ;
109 my ($file, $mode) = @_ ;
112 my %defOpts = (Level => Z_DEFAULT_COMPRESSION(),
113 Strategy => Z_DEFAULT_STRATEGY(),
117 $writing = ! ($mode =~ /r/i) ;
118 $writing = ($mode =~ /[wa]/i) ;
120 $defOpts{Level} = $1 if $mode =~ /(\d)/;
121 $defOpts{Strategy} = Z_FILTERED() if $mode =~ /f/i;
122 $defOpts{Strategy} = Z_HUFFMAN_ONLY() if $mode =~ /h/i;
124 my $infDef = $writing ? 'deflate' : 'inflate';
127 croak "gzopen: file parameter is not a filehandle or filename"
128 unless isaFilehandle $file || isaFilename $file ;
130 return undef unless $mode =~ /[rwa]/i ;
135 $gz = new IO::Compress::Gzip($file, Minimal => 1, AutoClose => 1,
137 or $Compress::Zlib::gzerrno = $IO::Compress::Gzip::GzipError;
140 $gz = new IO::Uncompress::Gunzip($file,
145 or $Compress::Zlib::gzerrno = $IO::Uncompress::Gunzip::GunzipError;
151 bless [$gz, $infDef], 'Compress::Zlib::gzFile';
154 sub Compress::Zlib::gzFile::gzread
158 return _set_gzerr(Z_STREAM_ERROR())
159 if $self->[1] ne 'inflate';
161 my $len = defined $_[1] ? $_[1] : 4096 ;
163 if ($self->gzeof() || $len == 0) {
164 # Zap the output buffer to match ver 1 behaviour.
169 my $gz = $self->[0] ;
170 my $status = $gz->read($_[0], $len) ;
175 sub Compress::Zlib::gzFile::gzreadline
179 my $gz = $self->[0] ;
180 $_[0] = $gz->getline() ;
182 return defined $_[0] ? length $_[0] : 0 ;
185 sub Compress::Zlib::gzFile::gzwrite
188 my $gz = $self->[0] ;
190 return _set_gzerr(Z_STREAM_ERROR())
191 if $self->[1] ne 'deflate';
193 my $status = $gz->write($_[0]) ;
198 sub Compress::Zlib::gzFile::gztell
201 my $gz = $self->[0] ;
202 my $status = $gz->tell() ;
207 sub Compress::Zlib::gzFile::gzseek
213 my $gz = $self->[0] ;
215 eval { $status = $gz->seek($offset, $whence) ; };
219 $error =~ s/^.*: /gzseek: /;
220 $error =~ s/ at .* line \d+\s*$//;
227 sub Compress::Zlib::gzFile::gzflush
232 my $gz = $self->[0] ;
233 my $status = $gz->flush($f) ;
238 sub Compress::Zlib::gzFile::gzclose
241 my $gz = $self->[0] ;
243 my $status = $gz->close() ;
248 sub Compress::Zlib::gzFile::gzeof
251 my $gz = $self->[0] ;
254 if $self->[1] ne 'inflate';
256 my $status = $gz->eof() ;
261 sub Compress::Zlib::gzFile::gzsetparams
264 croak "Usage: Compress::Zlib::gzFile::gzsetparams(file, level, strategy)"
267 my $gz = $self->[0] ;
269 my $strategy = shift;
271 return _set_gzerr(Z_STREAM_ERROR())
272 if $self->[1] ne 'deflate';
274 my $status = *$gz->{Compress}->deflateParams(-Level => $level,
275 -Strategy => $strategy);
280 sub Compress::Zlib::gzFile::gzerror
283 my $gz = $self->[0] ;
285 return $Compress::Zlib::gzerrno ;
291 my ($x, $output, $err, $in) =('', '', '', '') ;
295 croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
301 my $level = (@_ == 2 ? $_[1] : Z_DEFAULT_COMPRESSION() );
303 $x = new Compress::Raw::Zlib::Deflate -AppendOutput => 1, -Level => $level
306 $err = $x->deflate($in, $output) ;
307 return undef unless $err == Z_OK() ;
309 $err = $x->flush($output) ;
310 return undef unless $err == Z_OK() ;
318 my ($x, $output, $err, $in) =('', '', '', '') ;
322 croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
328 $x = new Compress::Raw::Zlib::Inflate -ConsumeInput => 0 or return undef ;
330 $err = $x->inflate($in, $output) ;
331 return undef unless $err == Z_STREAM_END() ;
340 my ($got) = ParseParameters(0,
342 'Bufsize' => [1, 1, Parse_unsigned, 4096],
343 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()],
344 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()],
345 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
346 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
347 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
348 'Dictionary' => [1, 1, Parse_any, ""],
351 croak "Compress::Zlib::deflateInit: Bufsize must be >= 1, you specified " .
352 $got->value('Bufsize')
353 unless $got->value('Bufsize') >= 1;
359 Compress::Raw::Zlib::_deflateInit(0,
360 $got->value('Level'),
361 $got->value('Method'),
362 $got->value('WindowBits'),
363 $got->value('MemLevel'),
364 $got->value('Strategy'),
365 $got->value('Bufsize'),
366 $got->value('Dictionary')) ;
368 my $x = ($status == Z_OK() ? bless $obj, "Zlib::OldDeflate" : undef) ;
369 return wantarray ? ($x, $status) : $x ;
374 my ($got) = ParseParameters(0,
376 'Bufsize' => [1, 1, Parse_unsigned, 4096],
377 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
378 'Dictionary' => [1, 1, Parse_any, ""],
382 croak "Compress::Zlib::inflateInit: Bufsize must be >= 1, you specified " .
383 $got->value('Bufsize')
384 unless $got->value('Bufsize') >= 1;
388 ($obj, $status) = Compress::Raw::Zlib::_inflateInit(FLAG_CONSUME_INPUT,
389 $got->value('WindowBits'),
390 $got->value('Bufsize'),
391 $got->value('Dictionary')) ;
393 my $x = ($status == Z_OK() ? bless $obj, "Zlib::OldInflate" : undef) ;
395 wantarray ? ($x, $status) : $x ;
398 package Zlib::OldDeflate ;
401 @ISA = qw(Compress::Raw::Zlib::deflateStream);
409 my $status = $self->SUPER::deflate($_[0], $output) ;
410 wantarray ? ($output, $status) : $output ;
417 my $flag = shift || Compress::Zlib::Z_FINISH();
418 my $status = $self->SUPER::flush($output, $flag) ;
420 wantarray ? ($output, $status) : $output ;
423 package Zlib::OldInflate ;
426 @ISA = qw(Compress::Raw::Zlib::inflateStream);
432 my $status = $self->SUPER::inflate($_[0], $output) ;
433 wantarray ? ($output, $status) : $output ;
436 package Compress::Zlib ;
438 use IO::Compress::Gzip::Constants;
442 my $x = new Compress::Raw::Zlib::Deflate(
446 -Level => Z_BEST_COMPRESSION(),
447 -WindowBits => - MAX_WBITS(),
451 # write a minimal gzip header
452 my $output = GZIP_MINIMUM_HEADER ;
454 # if the deflation buffer isn't a reference, make it one
455 my $string = (ref $_[0] ? $_[0] : \$_[0]) ;
457 my $status = $x->deflate($string, \$output) ;
461 $status = $x->flush(\$output) ;
465 return $output . pack("V V", $x->crc32(), $x->total_in()) ;
470 sub _removeGzipHeader($)
474 return Z_DATA_ERROR()
475 if length($$string) < GZIP_MIN_HEADER_SIZE ;
477 my ($magic1, $magic2, $method, $flags, $time, $xflags, $oscode) =
478 unpack ('CCCCVCC', $$string);
480 return Z_DATA_ERROR()
481 unless $magic1 == GZIP_ID1 and $magic2 == GZIP_ID2 and
482 $method == Z_DEFLATED() and !($flags & GZIP_FLG_RESERVED) ;
483 substr($$string, 0, GZIP_MIN_HEADER_SIZE) = '' ;
486 if ($flags & GZIP_FLG_FEXTRA)
488 return Z_DATA_ERROR()
489 if length($$string) < GZIP_FEXTRA_HEADER_SIZE ;
491 my ($extra_len) = unpack ('v', $$string);
492 $extra_len += GZIP_FEXTRA_HEADER_SIZE;
493 return Z_DATA_ERROR()
494 if length($$string) < $extra_len ;
496 substr($$string, 0, $extra_len) = '';
500 if ($flags & GZIP_FLG_FNAME)
502 my $name_end = index ($$string, GZIP_NULL_BYTE);
503 return Z_DATA_ERROR()
505 substr($$string, 0, $name_end + 1) = '';
509 if ($flags & GZIP_FLG_FCOMMENT)
511 my $comment_end = index ($$string, GZIP_NULL_BYTE);
512 return Z_DATA_ERROR()
513 if $comment_end == -1 ;
514 substr($$string, 0, $comment_end + 1) = '';
518 if ($flags & GZIP_FLG_FHCRC)
520 return Z_DATA_ERROR()
521 if length ($$string) < GZIP_FHCRC_SIZE ;
522 substr($$string, 0, GZIP_FHCRC_SIZE) = '';
531 # if the buffer isn't a reference, make it one
532 my $string = (ref $_[0] ? $_[0] : \$_[0]);
534 _removeGzipHeader($string) == Z_OK()
537 my $bufsize = length $$string > 4096 ? length $$string : 4096 ;
538 my $x = new Compress::Raw::Zlib::Inflate({-WindowBits => - MAX_WBITS(),
539 -Bufsize => $bufsize})
544 my $status = $x->inflate($string, $output);
546 unless $status == Z_STREAM_END();
548 if (length $$string >= 8)
550 my ($crc, $len) = unpack ("VV", substr($$string, 0, 8));
551 substr($$string, 0, 8) = '';
553 unless $len == length($output) and
554 $crc == crc32($output);
563 # Autoload methods go after __END__, and are processed by the autosplit program.
571 Compress::Zlib - Interface to zlib compression library
577 ($d, $status) = deflateInit( [OPT] ) ;
578 $status = $d->deflate($input, $output) ;
579 $status = $d->flush($output [, $flush_type]) ;
580 $d->deflateParams(OPTS) ;
581 $d->deflateTune(OPTS) ;
592 ($i, $status) = inflateInit( [OPT] ) ;
593 $status = $i->inflate($input, $output [, $eof]) ;
594 $status = $i->inflateSync($input) ;
603 $dest = compress($source) ;
604 $dest = uncompress($source) ;
606 $gz = gzopen($filename or filehandle, $mode) ;
607 $bytesread = $gz->gzread($buffer [,$size]) ;
608 $bytesread = $gz->gzreadline($line) ;
609 $byteswritten = $gz->gzwrite($buffer) ;
610 $status = $gz->gzflush($flush) ;
611 $offset = $gz->gztell() ;
612 $status = $gz->gzseek($offset, $whence) ;
613 $status = $gz->gzclose() ;
614 $status = $gz->gzeof() ;
615 $status = $gz->gzsetparams($level, $strategy) ;
616 $errstring = $gz->gzerror() ;
619 $dest = Compress::Zlib::memGzip($buffer) ;
620 $dest = Compress::Zlib::memGunzip($buffer) ;
622 $crc = adler32($buffer [,$crc]) ;
623 $crc = crc32($buffer [,$crc]) ;
625 $crc = adler32_combine($crc1, $crc2, $len2)l
626 $crc = crc32_combine($adler1, $adler2, $len2)
635 The I<Compress::Zlib> module provides a Perl interface to the I<zlib>
636 compression library (see L</AUTHOR> for details about where to get
639 The C<Compress::Zlib> module can be split into two general areas of
640 functionality, namely a simple read/write interface to I<gzip> files
641 and a low-level in-memory compression/decompression interface.
643 Each of these areas will be discussed separately below.
645 =head2 Notes for users of Compress::Zlib version 1
647 Version 2 of this module is a total rewrite. The net result of this is that
648 C<Compress::Zlib> does not now access the zlib library directly.
650 It now uses the C<IO::Compress::Gzip> and C<IO::Uncompress::Gunzip> modules
651 for reading/writing gzip files, and the C<Compress::Raw::Zlib> module for
652 low-level zlib access.
654 If you are writing new code, your first port of call should be to use one
657 =head1 GZIP INTERFACE
659 A number of functions are supplied in I<zlib> for reading and writing
660 I<gzip> files that conform to RFC 1952. This module provides an interface
663 If you are upgrading from C<Compress::Zlib> 1.x, the following
664 enhancements/changes have been made to the C<gzopen> interface:
670 If you want to to open either STDIN or STDOUT with C<gzopen>, you can now
671 optionally use the special filename "C<->" as a synonym for C<\*STDIN> and
676 In C<Compress::Zlib> version 1.x, C<gzopen> used the zlib library to open
677 the underlying file. This made things especially tricky when a Perl
678 filehandle was passed to C<gzopen>. Behind the scenes the numeric C file
679 descriptor had to be extracted from the Perl filehandle and this passed to
682 Apart from being non-portable to some operating systems, this made it
683 difficult to use C<gzopen> in situations where you wanted to extract/create
684 a gzip data stream that is embedded in a larger file, without having to
685 resort to opening and closing the file multiple times.
687 It also made it impossible to pass a perl filehandle that wasn't associated
688 with a real filesystem file, like, say, an C<IO::String>.
690 In C<Compress::Zlib> version 2.x, the C<gzopen> interface has been
691 completely rewritten to use the L<IO::Compress::Gzip|IO::Compress::Gzip>
692 for writing gzip files and L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>
693 for reading gzip files. None of the limitations mentioned above apply.
697 Addition of C<gzseek> to provide a restricted C<seek> interface.
705 A more complete and flexible interface for reading/writing gzip
706 files/buffers is included with the module C<IO-Compress-Zlib>. See
707 L<IO::Compress::Gzip|IO::Compress::Gzip> and
708 L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for more details.
712 =item B<$gz = gzopen($filename, $mode)>
714 =item B<$gz = gzopen($filehandle, $mode)>
716 This function opens either the I<gzip> file C<$filename> for reading or
717 writing or attaches to the opened filehandle, C<$filehandle>.
718 It returns an object on success and C<undef> on failure.
720 When writing a gzip file this interface will always create the smallest
721 possible gzip header (exactly 10 bytes). If you want greater control over
722 the information stored in the gzip header (like the original filename or a
723 comment) use L<IO::Compress::Gzip|IO::Compress::Gzip> instead.
725 The second parameter, C<$mode>, is used to specify whether the file is
726 opened for reading or writing and to optionally specify a compression
727 level and compression strategy when writing. The format of the C<$mode>
728 parameter is similar to the mode parameter to the 'C' function C<fopen>,
729 so "rb" is used to open for reading and "wb" for writing.
731 To specify a compression level when writing, append a digit between 0
732 and 9 to the mode string -- 0 means no compression and 9 means maximum
734 If no compression level is specified Z_DEFAULT_COMPRESSION is used.
736 To specify the compression strategy when writing, append 'f' for filtered
737 data, 'h' for Huffman only compression, or 'R' for run-length encoding.
738 If no strategy is specified Z_DEFAULT_STRATEGY is used.
740 So, for example, "wb9" means open for writing with the maximum compression
741 using the default strategy and "wb4R" means open for writing with compression
742 level 4 and run-length encoding.
744 Refer to the I<zlib> documentation for the exact format of the C<$mode>
748 =item B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>
750 Reads C<$size> bytes from the compressed file into C<$buffer>. If
751 C<$size> is not specified, it will default to 4096. If the scalar
752 C<$buffer> is not large enough, it will be extended automatically.
754 Returns the number of bytes actually read. On EOF it returns 0 and in
755 the case of an error, -1.
757 =item B<$bytesread = $gz-E<gt>gzreadline($line) ;>
759 Reads the next line from the compressed file into C<$line>.
761 Returns the number of bytes actually read. On EOF it returns 0 and in
762 the case of an error, -1.
764 It is legal to intermix calls to C<gzread> and C<gzreadline>.
766 In addition, C<gzreadline> fully supports the use of of the variable C<$/>
767 (C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
768 determine what constitutes an end of line. Both paragraph mode and file
769 slurp mode are supported.
772 =item B<$byteswritten = $gz-E<gt>gzwrite($buffer) ;>
774 Writes the contents of C<$buffer> to the compressed file. Returns the
775 number of bytes actually written, or 0 on error.
777 =item B<$status = $gz-E<gt>gzflush($flush_type) ;>
779 Flushes all pending output into the compressed file.
781 This method takes an optional parameter, C<$flush_type>, that controls
782 how the flushing will be carried out. By default the C<$flush_type>
783 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
784 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
785 strongly recommended that you only set the C<flush_type> parameter if
786 you fully understand the implications of what it does - overuse of C<flush>
787 can seriously degrade the level of compression achieved. See the C<zlib>
788 documentation for details.
790 Returns 1 on success, 0 on failure.
793 =item B<$offset = $gz-E<gt>gztell() ;>
795 Returns the uncompressed file offset.
797 =item B<$status = $gz-E<gt>gzseek($offset, $whence) ;>
799 Provides a sub-set of the C<seek> functionality, with the restriction
800 that it is only legal to seek forward in the compressed file.
801 It is a fatal error to attempt to seek backward.
803 When opened for writing, empty parts of the file will have NULL (0x00)
804 bytes written to them.
806 The C<$whence> parameter should be one of SEEK_SET, SEEK_CUR or SEEK_END.
808 Returns 1 on success, 0 on failure.
810 =item B<$gz-E<gt>gzclose>
812 Closes the compressed file. Any pending data is flushed to the file
815 Returns 1 on success, 0 on failure.
817 =item B<$gz-E<gt>gzsetparams($level, $strategy>
819 Change settings for the deflate stream C<$gz>.
821 The list of the valid options is shown below. Options not specified
822 will remain unchanged.
824 Note: This method is only available if you are running zlib 1.0.6 or better.
830 Defines the compression level. Valid values are 0 through 9,
831 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
832 C<Z_DEFAULT_COMPRESSION>.
836 Defines the strategy used to tune the compression. The valid values are
837 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
841 =item B<$gz-E<gt>gzerror>
843 Returns the I<zlib> error message or number for the last operation
844 associated with C<$gz>. The return value will be the I<zlib> error
845 number when used in a numeric context and the I<zlib> error message
846 when used in a string context. The I<zlib> error number constants,
847 shown below, are available for use.
859 The C<$gzerrno> scalar holds the error code associated with the most
860 recent I<gzip> routine. Note that unlike C<gzerror()>, the error is
861 I<not> associated with a particular file.
863 As with C<gzerror()> it returns an error number in numeric context and
864 an error message in string context. Unlike C<gzerror()> though, the
865 error message will correspond to the I<zlib> message when the error is
866 associated with I<zlib> itself, or the UNIX error message when it is
867 not (i.e. I<zlib> returned C<Z_ERRORNO>).
869 As there is an overlap between the error numbers used by I<zlib> and
870 UNIX, C<$gzerrno> should only be used to check for the presence of
871 I<an> error in numeric context. Use C<gzerror()> to check for specific
872 I<zlib> errors. The I<gzcat> example below shows how the variable can
880 Here is an example script which uses the interface. It implements a
888 # use stdin if no files supplied
889 @ARGV = '-' unless @ARGV ;
891 foreach my $file (@ARGV) {
894 my $gz = gzopen($file, "rb")
895 or die "Cannot open $file: $gzerrno\n" ;
897 print $buffer while $gz->gzread($buffer) > 0 ;
899 die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n"
900 if $gzerrno != Z_STREAM_END ;
905 Below is a script which makes use of C<gzreadline>. It implements a
906 very simple I<grep> like script.
913 die "Usage: gzgrep pattern [file...]\n"
916 my $pattern = shift ;
918 # use stdin if no files supplied
919 @ARGV = '-' unless @ARGV ;
921 foreach my $file (@ARGV) {
922 my $gz = gzopen($file, "rb")
923 or die "Cannot open $file: $gzerrno\n" ;
925 while ($gz->gzreadline($_) > 0) {
926 print if /$pattern/ ;
929 die "Error reading from $file: $gzerrno\n"
930 if $gzerrno != Z_STREAM_END ;
935 This script, I<gzstream>, does the opposite of the I<gzcat> script
936 above. It reads from standard input and writes a gzip data stream to
944 binmode STDOUT; # gzopen only sets it on the fd
946 my $gz = gzopen(\*STDOUT, "wb")
947 or die "Cannot open stdout: $gzerrno\n" ;
951 or die "error writing: $gzerrno\n" ;
956 =head2 Compress::Zlib::memGzip
958 This function is used to create an in-memory gzip file with the minimum
959 possible gzip header (exactly 10 bytes).
961 $dest = Compress::Zlib::memGzip($buffer) ;
963 If successful, it returns the in-memory gzip file, otherwise it returns
966 The C<$buffer> parameter can either be a scalar or a scalar reference.
968 See L<IO::Compress::Gzip|IO::Compress::Gzip> for an alternative way to
969 carry out in-memory gzip compression.
971 =head2 Compress::Zlib::memGunzip
973 This function is used to uncompress an in-memory gzip file.
975 $dest = Compress::Zlib::memGunzip($buffer) ;
977 If successful, it returns the uncompressed gzip file, otherwise it
980 The C<$buffer> parameter can either be a scalar or a scalar reference. The
981 contents of the C<$buffer> parameter are destroyed after calling this function.
983 See L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for an alternative way
984 to carry out in-memory gzip uncompression.
986 =head1 COMPRESS/UNCOMPRESS
988 Two functions are provided to perform in-memory compression/uncompression of
989 RFC 1950 data streams. They are called C<compress> and C<uncompress>.
993 =item B<$dest = compress($source [, $level] ) ;>
995 Compresses C<$source>. If successful it returns the compressed
996 data. Otherwise it returns I<undef>.
998 The source buffer, C<$source>, can either be a scalar or a scalar
1001 The C<$level> parameter defines the compression level. Valid values are
1002 0 through 9, C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>,
1003 C<Z_BEST_COMPRESSION>, and C<Z_DEFAULT_COMPRESSION>.
1004 If C<$level> is not specified C<Z_DEFAULT_COMPRESSION> will be used.
1007 =item B<$dest = uncompress($source) ;>
1009 Uncompresses C<$source>. If successful it returns the uncompressed
1010 data. Otherwise it returns I<undef>.
1012 The source buffer can either be a scalar or a scalar reference.
1016 Please note: the two functions defined above are I<not> compatible with
1017 the Unix commands of the same name.
1019 See L<IO::Deflate|IO::Deflate> and L<IO::Inflate|IO::Inflate> included with
1020 this distribution for an alternative interface for reading/writing RFC 1950
1024 =head1 Deflate Interface
1026 This section defines an interface that allows in-memory compression using
1027 the I<deflate> interface provided by zlib.
1029 Here is a definition of the interface available:
1032 =head2 B<($d, $status) = deflateInit( [OPT] )>
1034 Initialises a deflation stream.
1036 It combines the features of the I<zlib> functions C<deflateInit>,
1037 C<deflateInit2> and C<deflateSetDictionary>.
1039 If successful, it will return the initialised deflation stream, C<$d>
1040 and C<$status> of C<Z_OK> in a list context. In scalar context it
1041 returns the deflation stream, C<$d>, only.
1043 If not successful, the returned deflation stream (C<$d>) will be
1044 I<undef> and C<$status> will hold the exact I<zlib> error code.
1046 The function optionally takes a number of named options specified as
1047 C<< -Name=>value >> pairs. This allows individual options to be
1048 tailored without having to specify them all in the parameter list.
1050 For backward compatibility, it is also possible to pass the parameters
1051 as a reference to a hash containing the name=>value pairs.
1053 The function takes one optional parameter, a reference to a hash. The
1054 contents of the hash allow the deflation interface to be tailored.
1056 Here is a list of the valid options:
1062 Defines the compression level. Valid values are 0 through 9,
1063 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1064 C<Z_DEFAULT_COMPRESSION>.
1066 The default is Z_DEFAULT_COMPRESSION.
1070 Defines the compression method. The only valid value at present (and
1071 the default) is Z_DEFLATED.
1073 =item B<-WindowBits>
1075 To create an RFC 1950 data stream, set C<WindowBits> to a positive number.
1077 To create an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
1079 For a full definition of the meaning and valid values for C<WindowBits> refer
1080 to the I<zlib> documentation for I<deflateInit2>.
1082 Defaults to MAX_WBITS.
1086 For a definition of the meaning and valid values for C<MemLevel>
1087 refer to the I<zlib> documentation for I<deflateInit2>.
1089 Defaults to MAX_MEM_LEVEL.
1093 Defines the strategy used to tune the compression. The valid values are
1094 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1096 The default is Z_DEFAULT_STRATEGY.
1098 =item B<-Dictionary>
1100 When a dictionary is specified I<Compress::Zlib> will automatically
1101 call C<deflateSetDictionary> directly after calling C<deflateInit>. The
1102 Adler32 value for the dictionary can be obtained by calling the method
1103 C<$d->dict_adler()>.
1105 The default is no dictionary.
1109 Sets the initial size for the deflation buffer. If the buffer has to be
1110 reallocated to increase the size, it will grow in increments of
1113 The default is 4096.
1117 Here is an example of using the C<deflateInit> optional parameter list
1118 to override the default buffer size and compression level. All other
1119 options will take their default values.
1121 deflateInit( -Bufsize => 300,
1122 -Level => Z_BEST_SPEED ) ;
1125 =head2 B<($out, $status) = $d-E<gt>deflate($buffer)>
1128 Deflates the contents of C<$buffer>. The buffer can either be a scalar
1129 or a scalar reference. When finished, C<$buffer> will be
1130 completely processed (assuming there were no errors). If the deflation
1131 was successful it returns the deflated output, C<$out>, and a status
1132 value, C<$status>, of C<Z_OK>.
1134 On error, C<$out> will be I<undef> and C<$status> will contain the
1137 In a scalar context C<deflate> will return C<$out> only.
1139 As with the I<deflate> function in I<zlib>, it is not necessarily the
1140 case that any output will be produced by this method. So don't rely on
1141 the fact that C<$out> is empty for an error test.
1144 =head2 B<($out, $status) = $d-E<gt>flush([flush_type])>
1146 Typically used to finish the deflation. Any pending output will be
1147 returned via C<$out>.
1148 C<$status> will have a value C<Z_OK> if successful.
1150 In a scalar context C<flush> will return C<$out> only.
1152 Note that flushing can seriously degrade the compression ratio, so it
1153 should only be used to terminate a decompression (using C<Z_FINISH>) or
1154 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
1156 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
1157 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
1158 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
1159 C<flush_type> parameter if you fully understand the implications of
1160 what it does. See the C<zlib> documentation for details.
1162 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
1164 Change settings for the deflate stream C<$d>.
1166 The list of the valid options is shown below. Options not specified
1167 will remain unchanged.
1173 Defines the compression level. Valid values are 0 through 9,
1174 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1175 C<Z_DEFAULT_COMPRESSION>.
1179 Defines the strategy used to tune the compression. The valid values are
1180 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1184 =head2 B<$d-E<gt>dict_adler()>
1186 Returns the adler32 value for the dictionary.
1188 =head2 B<$d-E<gt>msg()>
1190 Returns the last error message generated by zlib.
1192 =head2 B<$d-E<gt>total_in()>
1194 Returns the total number of bytes uncompressed bytes input to deflate.
1196 =head2 B<$d-E<gt>total_out()>
1198 Returns the total number of compressed bytes output from deflate.
1203 Here is a trivial example of using C<deflate>. It simply reads standard
1204 input, deflates it and writes it to standard output.
1209 use Compress::Zlib ;
1213 my $x = deflateInit()
1214 or die "Cannot create a deflation stream\n" ;
1216 my ($output, $status) ;
1219 ($output, $status) = $x->deflate($_) ;
1222 or die "deflation failed\n" ;
1227 ($output, $status) = $x->flush() ;
1230 or die "deflation failed\n" ;
1234 =head1 Inflate Interface
1236 This section defines the interface available that allows in-memory
1237 uncompression using the I<deflate> interface provided by zlib.
1239 Here is a definition of the interface:
1242 =head2 B<($i, $status) = inflateInit()>
1244 Initialises an inflation stream.
1246 In a list context it returns the inflation stream, C<$i>, and the
1247 I<zlib> status code in C<$status>. In a scalar context it returns the
1248 inflation stream only.
1250 If successful, C<$i> will hold the inflation stream and C<$status> will
1253 If not successful, C<$i> will be I<undef> and C<$status> will hold the
1256 The function optionally takes a number of named options specified as
1257 C<< -Name=>value >> pairs. This allows individual options to be
1258 tailored without having to specify them all in the parameter list.
1260 For backward compatibility, it is also possible to pass the parameters
1261 as a reference to a hash containing the name=>value pairs.
1263 The function takes one optional parameter, a reference to a hash. The
1264 contents of the hash allow the deflation interface to be tailored.
1266 Here is a list of the valid options:
1270 =item B<-WindowBits>
1272 To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive number.
1274 To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
1276 For a full definition of the meaning and valid values for C<WindowBits> refer
1277 to the I<zlib> documentation for I<inflateInit2>.
1279 Defaults to MAX_WBITS.
1283 Sets the initial size for the inflation buffer. If the buffer has to be
1284 reallocated to increase the size, it will grow in increments of
1289 =item B<-Dictionary>
1291 The default is no dictionary.
1295 Here is an example of using the C<inflateInit> optional parameter to
1296 override the default buffer size.
1298 inflateInit( -Bufsize => 300 ) ;
1300 =head2 B<($out, $status) = $i-E<gt>inflate($buffer)>
1302 Inflates the complete contents of C<$buffer>. The buffer can either be
1303 a scalar or a scalar reference.
1305 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
1306 compressed data has been successfully reached.
1307 If not successful, C<$out> will be I<undef> and C<$status> will hold
1308 the I<zlib> error code.
1310 The C<$buffer> parameter is modified by C<inflate>. On completion it
1311 will contain what remains of the input buffer after inflation. This
1312 means that C<$buffer> will be an empty string when the return status is
1313 C<Z_OK>. When the return status is C<Z_STREAM_END> the C<$buffer>
1314 parameter will contains what (if anything) was stored in the input
1315 buffer after the deflated data stream.
1317 This feature is useful when processing a file format that encapsulates
1318 a compressed data stream (e.g. gzip, zip).
1320 =head2 B<$status = $i-E<gt>inflateSync($buffer)>
1322 Scans C<$buffer> until it reaches either a I<full flush point> or the
1325 If a I<full flush point> is found, C<Z_OK> is returned and C<$buffer>
1326 will be have all data up to the flush point removed. This can then be
1327 passed to the C<deflate> method.
1329 Any other return code means that a flush point was not found. If more
1330 data is available, C<inflateSync> can be called repeatedly with more
1331 compressed data until the flush point is found.
1334 =head2 B<$i-E<gt>dict_adler()>
1336 Returns the adler32 value for the dictionary.
1338 =head2 B<$i-E<gt>msg()>
1340 Returns the last error message generated by zlib.
1342 =head2 B<$i-E<gt>total_in()>
1344 Returns the total number of bytes compressed bytes input to inflate.
1346 =head2 B<$i-E<gt>total_out()>
1348 Returns the total number of uncompressed bytes output from inflate.
1352 Here is an example of using C<inflate>.
1357 use Compress::Zlib ;
1359 my $x = inflateInit()
1360 or die "Cannot create a inflation stream\n" ;
1366 my ($output, $status) ;
1367 while (read(STDIN, $input, 4096))
1369 ($output, $status) = $x->inflate(\$input) ;
1372 if $status == Z_OK or $status == Z_STREAM_END ;
1374 last if $status != Z_OK ;
1377 die "inflation failed\n"
1378 unless $status == Z_STREAM_END ;
1380 =head1 CHECKSUM FUNCTIONS
1382 Two functions are provided by I<zlib> to calculate checksums. For the
1383 Perl interface, the order of the two parameters in both functions has
1384 been reversed. This allows both running checksums and one off
1385 calculations to be done.
1387 $crc = adler32($buffer [,$crc]) ;
1388 $crc = crc32($buffer [,$crc]) ;
1390 The buffer parameters can either be a scalar or a scalar reference.
1392 If the $crc parameters is C<undef>, the crc value will be reset.
1394 If you have built this module with zlib 1.2.3 or better, two more
1395 CRC-related functions are available.
1397 $crc = adler32_combine($crc1, $crc2, $len2)l
1398 $crc = crc32_combine($adler1, $adler2, $len2)
1400 These functions allow checksums to be merged.
1404 All the I<zlib> constants are automatically imported when you make use
1405 of I<Compress::Zlib>.
1410 L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1412 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1414 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1415 L<Archive::Tar|Archive::Tar>,
1416 L<IO::Zlib|IO::Zlib>
1419 For RFC 1950, 1951 and 1952 see
1420 F<http://www.faqs.org/rfcs/rfc1950.html>,
1421 F<http://www.faqs.org/rfcs/rfc1951.html> and
1422 F<http://www.faqs.org/rfcs/rfc1952.html>
1424 The I<zlib> compression library was written by Jean-loup Gailly
1425 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1427 The primary site for the I<zlib> compression library is
1428 F<http://www.zlib.org>.
1430 The primary site for gzip is F<http://www.gzip.org>.
1437 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1441 =head1 MODIFICATION HISTORY
1443 See the Changes file.
1445 =head1 COPYRIGHT AND LICENSE
1447 Copyright (c) 1995-2006 Paul Marquess. All rights reserved.
1449 This program is free software; you can redistribute it and/or
1450 modify it under the same terms as Perl itself.