ext/Compress/Zlib/lib/Compress/Zlib.pm

   1
   2 package Compress::Zlib;
   3
   4 require 5.004 ;
   5 require Exporter;
   6 use AutoLoader;
   7 use Carp ;
   8 use IO::Handle ;
   9 use Scalar::Util qw(dualvar);
  10
  11 use IO::Compress::Base::Common 2.003 ;
  12 use Compress::Raw::Zlib 2.003 ;
  13 use IO::Compress::Gzip 2.003 ;
  14 use IO::Uncompress::Gunzip 2.003 ;
  15
  16 use strict ;
  17 use warnings ;
  18 use bytes ;
  19 our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
  20
  21 $VERSION = '2.003';
  22 $XS_VERSION = $VERSION;
  23 $VERSION = eval $VERSION;
  24
  25 @ISA = qw(Exporter);
  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.
  29 @EXPORT = qw(
  30         deflateInit inflateInit
  31
  32         compress uncompress
  33
  34         gzopen $gzerrno
  35     );
  36
  37 push @EXPORT, @Compress::Raw::Zlib::EXPORT ;
  38
  39 BEGIN
  40 {
  41     *zlib_version = \&Compress::Raw::Zlib::zlib_version;
  42 }
  43
  44 sub AUTOLOAD {
  45     my($constname);
  46     ($constname = $AUTOLOAD) =~ s/.*:://;
  47     my ($error, $val) = Compress::Raw::Zlib::constant($constname);
  48     Carp::croak $error if $error;
  49     no strict 'refs';
  50     *{$AUTOLOAD} = sub { $val };
  51     goto &{$AUTOLOAD};
  52 }
  53
  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 ;
  58
  59 our (@my_z_errmsg);
  60
  61 @my_z_errmsg = (
  62     "need dictionary",     # Z_NEED_DICT     2
  63     "stream end",          # Z_STREAM_END    1
  64     "",                    # Z_OK            0
  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)
  71     );
  72
  73
  74 sub _set_gzerr
  75 {
  76     my $value = shift ;
  77
  78     if ($value == 0) {
  79         $Compress::Zlib::gzerrno = 0 ;
  80     }
  81     elsif ($value == Z_ERRNO() || $value > 2) {
  82         $Compress::Zlib::gzerrno = $! ;
  83     }
  84     else {
  85         $Compress::Zlib::gzerrno = dualvar($value+0, $my_z_errmsg[2 - $value]);
  86     }
  87
  88     return $value ;
  89 }
  90
  91 sub _save_gzerr
  92 {
  93     my $gz = shift ;
  94     my $test_eof = shift ;
  95
  96     my $value = $gz->errorNo() || 0 ;
  97
  98     if ($test_eof) {
  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 ;
 102     }
 103
 104     _set_gzerr($value) ;
 105 }
 106
 107 sub gzopen($$)
 108 {
 109     my ($file, $mode) = @_ ;
 110
 111     my $gz ;
 112     my %defOpts = (Level    => Z_DEFAULT_COMPRESSION(),
 113                    Strategy => Z_DEFAULT_STRATEGY(),
 114                   );
 115
 116     my $writing ;
 117     $writing = ! ($mode =~ /r/i) ;
 118     $writing = ($mode =~ /[wa]/i) ;
 119
 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;
 123     $defOpts{Append}   = 1                if $mode =~ /a/i;
 124
 125     my $infDef = $writing ? 'deflate' : 'inflate';
 126     my @params = () ;
 127
 128     croak "gzopen: file parameter is not a filehandle or filename"
 129         unless isaFilehandle $file || isaFilename $file  ||
 130                (ref $file && ref $file eq 'SCALAR');
 131
 132     return undef unless $mode =~ /[rwa]/i ;
 133
 134     _set_gzerr(0) ;
 135
 136     if ($writing) {
 137         $gz = new IO::Compress::Gzip($file, Minimal => 1, AutoClose => 1,
 138                                      %defOpts)
 139             or $Compress::Zlib::gzerrno = $IO::Compress::Gzip::GzipError;
 140     }
 141     else {
 142         $gz = new IO::Uncompress::Gunzip($file,
 143                                          Transparent => 1,
 144                                          Append => 0,
 145                                          AutoClose => 1,
 146                                          MultiStream => 1,
 147                                          Strict => 0)
 148             or $Compress::Zlib::gzerrno = $IO::Uncompress::Gunzip::GunzipError;
 149     }
 150
 151     return undef
 152         if ! defined $gz ;
 153
 154     bless [$gz, $infDef], 'Compress::Zlib::gzFile';
 155 }
 156
 157 sub Compress::Zlib::gzFile::gzread
 158 {
 159     my $self = shift ;
 160
 161     return _set_gzerr(Z_STREAM_ERROR())
 162         if $self->[1] ne 'inflate';
 163
 164     my $len = defined $_[1] ? $_[1] : 4096 ;
 165
 166     if ($self->gzeof() || $len == 0) {
 167         # Zap the output buffer to match ver 1 behaviour.
 168         $_[0] = "" ;
 169         return 0 ;
 170     }
 171
 172     my $gz = $self->[0] ;
 173     my $status = $gz->read($_[0], $len) ;
 174     _save_gzerr($gz, 1);
 175     return $status ;
 176 }
 177
 178 sub Compress::Zlib::gzFile::gzreadline
 179 {
 180     my $self = shift ;
 181
 182     my $gz = $self->[0] ;
 183     $_[0] = $gz->getline() ;
 184     _save_gzerr($gz, 1);
 185     return defined $_[0] ? length $_[0] : 0 ;
 186 }
 187
 188 sub Compress::Zlib::gzFile::gzwrite
 189 {
 190     my $self = shift ;
 191     my $gz = $self->[0] ;
 192
 193     return _set_gzerr(Z_STREAM_ERROR())
 194         if $self->[1] ne 'deflate';
 195
 196     my $status = $gz->write($_[0]) ;
 197     _save_gzerr($gz);
 198     return $status ;
 199 }
 200
 201 sub Compress::Zlib::gzFile::gztell
 202 {
 203     my $self = shift ;
 204     my $gz = $self->[0] ;
 205     my $status = $gz->tell() ;
 206     _save_gzerr($gz);
 207     return $status ;
 208 }
 209
 210 sub Compress::Zlib::gzFile::gzseek
 211 {
 212     my $self   = shift ;
 213     my $offset = shift ;
 214     my $whence = shift ;
 215
 216     my $gz = $self->[0] ;
 217     my $status ;
 218     eval { $status = $gz->seek($offset, $whence) ; };
 219     if ($@)
 220     {
 221         my $error = $@;
 222         $error =~ s/^.*: /gzseek: /;
 223         $error =~ s/ at .* line \d+\s*$//;
 224         croak $error;
 225     }
 226     _save_gzerr($gz);
 227     return $status ;
 228 }
 229
 230 sub Compress::Zlib::gzFile::gzflush
 231 {
 232     my $self = shift ;
 233     my $f    = shift ;
 234
 235     my $gz = $self->[0] ;
 236     my $status = $gz->flush($f) ;
 237     _save_gzerr($gz);
 238     return $status ;
 239 }
 240
 241 sub Compress::Zlib::gzFile::gzclose
 242 {
 243     my $self = shift ;
 244     my $gz = $self->[0] ;
 245
 246     my $status = $gz->close() ;
 247     _save_gzerr($gz);
 248     return ! $status ;
 249 }
 250
 251 sub Compress::Zlib::gzFile::gzeof
 252 {
 253     my $self = shift ;
 254     my $gz = $self->[0] ;
 255
 256     return 0
 257         if $self->[1] ne 'inflate';
 258
 259     my $status = $gz->eof() ;
 260     _save_gzerr($gz);
 261     return $status ;
 262 }
 263
 264 sub Compress::Zlib::gzFile::gzsetparams
 265 {
 266     my $self = shift ;
 267     croak "Usage: Compress::Zlib::gzFile::gzsetparams(file, level, strategy)"
 268         unless @_ eq 2 ;
 269
 270     my $gz = $self->[0] ;
 271     my $level = shift ;
 272     my $strategy = shift;
 273
 274     return _set_gzerr(Z_STREAM_ERROR())
 275         if $self->[1] ne 'deflate';
 276
 277     my $status = *$gz->{Compress}->deflateParams(-Level   => $level,
 278                                                 -Strategy => $strategy);
 279     _save_gzerr($gz);
 280     return $status ;
 281 }
 282
 283 sub Compress::Zlib::gzFile::gzerror
 284 {
 285     my $self = shift ;
 286     my $gz = $self->[0] ;
 287
 288     return $Compress::Zlib::gzerrno ;
 289 }
 290
 291
 292 sub compress($;$)
 293 {
 294     my ($x, $output, $err, $in) =('', '', '', '') ;
 295
 296     if (ref $_[0] ) {
 297         $in = $_[0] ;
 298         croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
 299     }
 300     else {
 301         $in = \$_[0] ;
 302     }
 303
 304     my $level = (@_ == 2 ? $_[1] : Z_DEFAULT_COMPRESSION() );
 305
 306     $x = new Compress::Raw::Zlib::Deflate -AppendOutput => 1, -Level => $level
 307             or return undef ;
 308
 309     $err = $x->deflate($in, $output) ;
 310     return undef unless $err == Z_OK() ;
 311
 312     $err = $x->flush($output) ;
 313     return undef unless $err == Z_OK() ;
 314
 315     return $output ;
 316
 317 }
 318
 319 sub uncompress($)
 320 {
 321     my ($x, $output, $err, $in) =('', '', '', '') ;
 322
 323     if (ref $_[0] ) {
 324         $in = $_[0] ;
 325         croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
 326     }
 327     else {
 328         $in = \$_[0] ;
 329     }
 330
 331     $x = new Compress::Raw::Zlib::Inflate -ConsumeInput => 0 or return undef ;
 332
 333     $err = $x->inflate($in, $output) ;
 334     return undef unless $err == Z_STREAM_END() ;
 335
 336     return $output ;
 337 }
 338
 339
 340
 341 sub deflateInit(@)
 342 {
 343     my ($got) = ParseParameters(0,
 344                 {
 345                 'Bufsize'       => [1, 1, Parse_unsigned, 4096],
 346                 'Level'         => [1, 1, Parse_signed,   Z_DEFAULT_COMPRESSION()],
 347                 'Method'        => [1, 1, Parse_unsigned, Z_DEFLATED()],
 348                 'WindowBits'    => [1, 1, Parse_signed,   MAX_WBITS()],
 349                 'MemLevel'      => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
 350                 'Strategy'      => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
 351                 'Dictionary'    => [1, 1, Parse_any,      ""],
 352                 }, @_ ) ;
 353
 354     croak "Compress::Zlib::deflateInit: Bufsize must be >= 1, you specified " .
 355             $got->value('Bufsize')
 356         unless $got->value('Bufsize') >= 1;
 357
 358     my $obj ;
 359
 360     my $status = 0 ;
 361     ($obj, $status) =
 362       Compress::Raw::Zlib::_deflateInit(0,
 363                 $got->value('Level'),
 364                 $got->value('Method'),
 365                 $got->value('WindowBits'),
 366                 $got->value('MemLevel'),
 367                 $got->value('Strategy'),
 368                 $got->value('Bufsize'),
 369                 $got->value('Dictionary')) ;
 370
 371     my $x = ($status == Z_OK() ? bless $obj, "Zlib::OldDeflate"  : undef) ;
 372     return wantarray ? ($x, $status) : $x ;
 373 }
 374
 375 sub inflateInit(@)
 376 {
 377     my ($got) = ParseParameters(0,
 378                 {
 379                 'Bufsize'       => [1, 1, Parse_unsigned, 4096],
 380                 'WindowBits'    => [1, 1, Parse_signed,   MAX_WBITS()],
 381                 'Dictionary'    => [1, 1, Parse_any,      ""],
 382                 }, @_) ;
 383
 384
 385     croak "Compress::Zlib::inflateInit: Bufsize must be >= 1, you specified " .
 386             $got->value('Bufsize')
 387         unless $got->value('Bufsize') >= 1;
 388
 389     my $status = 0 ;
 390     my $obj ;
 391     ($obj, $status) = Compress::Raw::Zlib::_inflateInit(FLAG_CONSUME_INPUT,
 392                                 $got->value('WindowBits'),
 393                                 $got->value('Bufsize'),
 394                                 $got->value('Dictionary')) ;
 395
 396     my $x = ($status == Z_OK() ? bless $obj, "Zlib::OldInflate"  : undef) ;
 397
 398     wantarray ? ($x, $status) : $x ;
 399 }
 400
 401 package Zlib::OldDeflate ;
 402
 403 our (@ISA);
 404 @ISA = qw(Compress::Raw::Zlib::deflateStream);
 405
 406
 407 sub deflate
 408 {
 409     my $self = shift ;
 410     my $output ;
 411
 412     my $status = $self->SUPER::deflate($_[0], $output) ;
 413     wantarray ? ($output, $status) : $output ;
 414 }
 415
 416 sub flush
 417 {
 418     my $self = shift ;
 419     my $output ;
 420     my $flag = shift || Compress::Zlib::Z_FINISH();
 421     my $status = $self->SUPER::flush($output, $flag) ;
 422
 423     wantarray ? ($output, $status) : $output ;
 424 }
 425
 426 package Zlib::OldInflate ;
 427
 428 our (@ISA);
 429 @ISA = qw(Compress::Raw::Zlib::inflateStream);
 430
 431 sub inflate
 432 {
 433     my $self = shift ;
 434     my $output ;
 435     my $status = $self->SUPER::inflate($_[0], $output) ;
 436     wantarray ? ($output, $status) : $output ;
 437 }
 438
 439 package Compress::Zlib ;
 440
 441 use IO::Compress::Gzip::Constants 2.003 ;
 442
 443 sub memGzip($)
 444 {
 445   my $x = new Compress::Raw::Zlib::Deflate(
 446                       -AppendOutput  => 1,
 447                       -CRC32         => 1,
 448                       -ADLER32       => 0,
 449                       -Level         => Z_BEST_COMPRESSION(),
 450                       -WindowBits    => - MAX_WBITS(),
 451                      )
 452       or return undef ;
 453
 454   # write a minimal gzip header
 455   my $output = GZIP_MINIMUM_HEADER ;
 456
 457   # if the deflation buffer isn't a reference, make it one
 458   my $string = (ref $_[0] ? $_[0] : \$_[0]) ;
 459
 460   my $status = $x->deflate($string, \$output) ;
 461   $status == Z_OK()
 462       or return undef ;
 463
 464   $status = $x->flush(\$output) ;
 465   $status == Z_OK()
 466       or return undef ;
 467
 468   return $output . pack("V V", $x->crc32(), $x->total_in()) ;
 469
 470 }
 471
 472
 473 sub _removeGzipHeader($)
 474 {
 475     my $string = shift ;
 476
 477     return Z_DATA_ERROR()
 478         if length($$string) < GZIP_MIN_HEADER_SIZE ;
 479
 480     my ($magic1, $magic2, $method, $flags, $time, $xflags, $oscode) =
 481         unpack ('CCCCVCC', $$string);
 482
 483     return Z_DATA_ERROR()
 484         unless $magic1 == GZIP_ID1 and $magic2 == GZIP_ID2 and
 485            $method == Z_DEFLATED() and !($flags & GZIP_FLG_RESERVED) ;
 486     substr($$string, 0, GZIP_MIN_HEADER_SIZE) = '' ;
 487
 488     # skip extra field
 489     if ($flags & GZIP_FLG_FEXTRA)
 490     {
 491         return Z_DATA_ERROR()
 492             if length($$string) < GZIP_FEXTRA_HEADER_SIZE ;
 493
 494         my ($extra_len) = unpack ('v', $$string);
 495         $extra_len += GZIP_FEXTRA_HEADER_SIZE;
 496         return Z_DATA_ERROR()
 497             if length($$string) < $extra_len ;
 498
 499         substr($$string, 0, $extra_len) = '';
 500     }
 501
 502     # skip orig name
 503     if ($flags & GZIP_FLG_FNAME)
 504     {
 505         my $name_end = index ($$string, GZIP_NULL_BYTE);
 506         return Z_DATA_ERROR()
 507            if $name_end == -1 ;
 508         substr($$string, 0, $name_end + 1) =  '';
 509     }
 510
 511     # skip comment
 512     if ($flags & GZIP_FLG_FCOMMENT)
 513     {
 514         my $comment_end = index ($$string, GZIP_NULL_BYTE);
 515         return Z_DATA_ERROR()
 516             if $comment_end == -1 ;
 517         substr($$string, 0, $comment_end + 1) = '';
 518     }
 519
 520     # skip header crc
 521     if ($flags & GZIP_FLG_FHCRC)
 522     {
 523         return Z_DATA_ERROR()
 524             if length ($$string) < GZIP_FHCRC_SIZE ;
 525         substr($$string, 0, GZIP_FHCRC_SIZE) = '';
 526     }
 527
 528     return Z_OK();
 529 }
 530
 531
 532 sub memGunzip($)
 533 {
 534     # if the buffer isn't a reference, make it one
 535     my $string = (ref $_[0] ? $_[0] : \$_[0]);
 536
 537     _removeGzipHeader($string) == Z_OK()
 538         or return undef;
 539
 540     my $bufsize = length $$string > 4096 ? length $$string : 4096 ;
 541     my $x = new Compress::Raw::Zlib::Inflate({-WindowBits => - MAX_WBITS(),
 542                          -Bufsize => $bufsize})
 543
 544               or return undef;
 545
 546     my $output = "" ;
 547     my $status = $x->inflate($string, $output);
 548     return undef
 549         unless $status == Z_STREAM_END();
 550
 551     if (length $$string >= 8)
 552     {
 553         my ($crc, $len) = unpack ("VV", substr($$string, 0, 8));
 554         substr($$string, 0, 8) = '';
 555         return undef
 556             unless $len == length($output) and
 557                    $crc == crc32($output);
 558     }
 559     else
 560     {
 561         $$string = '';
 562     }
 563     return $output;
 564 }
 565
 566 # Autoload methods go after __END__, and are processed by the autosplit program.
 567
 568 1;
 569 __END__
 570
 571
 572 =head1 NAME
 573
 574 Compress::Zlib - Interface to zlib compression library
 575
 576 =head1 SYNOPSIS
 577
 578     use Compress::Zlib ;
 579
 580     ($d, $status) = deflateInit( [OPT] ) ;
 581     $status = $d->deflate($input, $output) ;
 582     $status = $d->flush($output [, $flush_type]) ;
 583     $d->deflateParams(OPTS) ;
 584     $d->deflateTune(OPTS) ;
 585     $d->dict_adler() ;
 586     $d->crc32() ;
 587     $d->adler32() ;
 588     $d->total_in() ;
 589     $d->total_out() ;
 590     $d->msg() ;
 591     $d->get_Strategy();
 592     $d->get_Level();
 593     $d->get_BufSize();
 594
 595     ($i, $status) = inflateInit( [OPT] ) ;
 596     $status = $i->inflate($input, $output [, $eof]) ;
 597     $status = $i->inflateSync($input) ;
 598     $i->dict_adler() ;
 599     $d->crc32() ;
 600     $d->adler32() ;
 601     $i->total_in() ;
 602     $i->total_out() ;
 603     $i->msg() ;
 604     $d->get_BufSize();
 605
 606     $dest = compress($source) ;
 607     $dest = uncompress($source) ;
 608
 609     $gz = gzopen($filename or filehandle, $mode) ;
 610     $bytesread = $gz->gzread($buffer [,$size]) ;
 611     $bytesread = $gz->gzreadline($line) ;
 612     $byteswritten = $gz->gzwrite($buffer) ;
 613     $status = $gz->gzflush($flush) ;
 614     $offset = $gz->gztell() ;
 615     $status = $gz->gzseek($offset, $whence) ;
 616     $status = $gz->gzclose() ;
 617     $status = $gz->gzeof() ;
 618     $status = $gz->gzsetparams($level, $strategy) ;
 619     $errstring = $gz->gzerror() ;
 620     $gzerrno
 621
 622     $dest = Compress::Zlib::memGzip($buffer) ;
 623     $dest = Compress::Zlib::memGunzip($buffer) ;
 624
 625     $crc = adler32($buffer [,$crc]) ;
 626     $crc = crc32($buffer [,$crc]) ;
 627
 628     $crc = adler32_combine($crc1, $crc2, $len2)l
 629     $crc = crc32_combine($adler1, $adler2, $len2)
 630
 631     ZLIB_VERSION
 632     ZLIB_VERNUM
 633
 634
 635
 636 =head1 DESCRIPTION
 637
 638 The I<Compress::Zlib> module provides a Perl interface to the I<zlib>
 639 compression library (see L</AUTHOR> for details about where to get
 640 I<zlib>).
 641
 642 The C<Compress::Zlib> module can be split into two general areas of
 643 functionality, namely a simple read/write interface to I<gzip> files
 644 and a low-level in-memory compression/decompression interface.
 645
 646 Each of these areas will be discussed in the following sections.
 647
 648 =head2 Notes for users of Compress::Zlib version 1
 649
 650 The main change in C<Compress::Zlib> version 2.x is that it does not now
 651 interface directly to the zlib library. Instead it uses the
 652 C<IO::Compress::Gzip> and C<IO::Uncompress::Gunzip> modules for
 653 reading/writing gzip files, and the C<Compress::Raw::Zlib> module for some
 654 low-level zlib access.
 655
 656 The interface provided by version 2 should be 100% backward compatible with
 657 version 1. If you find a difference in the expected behaviour please
 658 contact the author (See L</AUTHOR>). See L<GZIP INTERFACE>
 659
 660 If you are writing new code, your first port of call should be to use one
 661 these new modules.
 662
 663 =head1 GZIP INTERFACE
 664
 665 A number of functions are supplied in I<zlib> for reading and writing
 666 I<gzip> files that conform to RFC 1952. This module provides an interface
 667 to most of them.
 668
 669 If you have previously used C<Compress::Zlib> 1.x, the following
 670 enhancements/changes have been made to the C<gzopen> interface:
 671
 672 =over 5
 673
 674 =item 1
 675
 676 If you want to to open either STDIN or STDOUT with C<gzopen>, you can now
 677 optionally use the special filename "C<->" as a synonym for C<\*STDIN> and
 678 C<\*STDOUT>.
 679
 680 =item 2
 681
 682 In C<Compress::Zlib> version 1.x, C<gzopen> used the zlib library to open
 683 the underlying file. This made things especially tricky when a Perl
 684 filehandle was passed to C<gzopen>. Behind the scenes the numeric C file
 685 descriptor had to be extracted from the Perl filehandle and this passed to
 686 the zlib library.
 687
 688 Apart from being non-portable to some operating systems, this made it
 689 difficult to use C<gzopen> in situations where you wanted to extract/create
 690 a gzip data stream that is embedded in a larger file, without having to
 691 resort to opening and closing the file multiple times.
 692
 693 It also made it impossible to pass a perl filehandle that wasn't associated
 694 with a real filesystem file, like, say, an C<IO::String>.
 695
 696 In C<Compress::Zlib> version 2.x, the C<gzopen> interface has been
 697 completely rewritten to use the L<IO::Compress::Gzip|IO::Compress::Gzip>
 698 for writing gzip files and L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>
 699 for reading gzip files. None of the limitations mentioned above apply.
 700
 701 =item 3
 702
 703 Addition of C<gzseek> to provide a restricted C<seek> interface.
 704
 705 =item 4.
 706
 707 Added C<gztell>.
 708
 709 =back
 710
 711 A more complete and flexible interface for reading/writing gzip
 712 files/buffers is included with the module C<IO-Compress-Zlib>. See
 713 L<IO::Compress::Gzip|IO::Compress::Gzip> and
 714 L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for more details.
 715
 716 =over 5
 717
 718 =item B<$gz = gzopen($filename, $mode)>
 719
 720 =item B<$gz = gzopen($filehandle, $mode)>
 721
 722 This function opens either the I<gzip> file C<$filename> for reading or
 723 writing or attaches to the opened filehandle, C<$filehandle>.
 724 It returns an object on success and C<undef> on failure.
 725
 726 When writing a gzip file this interface will I<always> create the smallest
 727 possible gzip header (exactly 10 bytes). If you want greater control over
 728 what gets stored in the gzip header (like the original filename or a
 729 comment) use L<IO::Compress::Gzip|IO::Compress::Gzip> instead. Similarly if
 730 you want to read the contents of the gzip header use
 731 L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
 732
 733 The second parameter, C<$mode>, is used to specify whether the file is
 734 opened for reading or writing and to optionally specify a compression
 735 level and compression strategy when writing. The format of the C<$mode>
 736 parameter is similar to the mode parameter to the 'C' function C<fopen>,
 737 so "rb" is used to open for reading, "wb" for writing and "ab" for
 738 appending (writing at the end of the file).
 739
 740 To specify a compression level when writing, append a digit between 0
 741 and 9 to the mode string -- 0 means no compression and 9 means maximum
 742 compression.
 743 If no compression level is specified Z_DEFAULT_COMPRESSION is used.
 744
 745 To specify the compression strategy when writing, append 'f' for filtered
 746 data, 'h' for Huffman only compression, or 'R' for run-length encoding.
 747 If no strategy is specified Z_DEFAULT_STRATEGY is used.
 748
 749 So, for example, "wb9" means open for writing with the maximum compression
 750 using the default strategy and "wb4R" means open for writing with compression
 751 level 4 and run-length encoding.
 752
 753 Refer to the I<zlib> documentation for the exact format of the C<$mode>
 754 parameter.
 755
 756 =item B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>
 757
 758 Reads C<$size> bytes from the compressed file into C<$buffer>. If
 759 C<$size> is not specified, it will default to 4096. If the scalar
 760 C<$buffer> is not large enough, it will be extended automatically.
 761
 762 Returns the number of bytes actually read. On EOF it returns 0 and in
 763 the case of an error, -1.
 764
 765 =item B<$bytesread = $gz-E<gt>gzreadline($line) ;>
 766
 767 Reads the next line from the compressed file into C<$line>.
 768
 769 Returns the number of bytes actually read. On EOF it returns 0 and in
 770 the case of an error, -1.
 771
 772 It is legal to intermix calls to C<gzread> and C<gzreadline>.
 773
 774 In addition, C<gzreadline> fully supports the use of of the variable C<$/>
 775 (C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
 776 determine what constitutes an end of line. Both paragraph mode and file
 777 slurp mode are supported.
 778
 779
 780 =item B<$byteswritten = $gz-E<gt>gzwrite($buffer) ;>
 781
 782 Writes the contents of C<$buffer> to the compressed file. Returns the
 783 number of bytes actually written, or 0 on error.
 784
 785 =item B<$status = $gz-E<gt>gzflush($flush_type) ;>
 786
 787 Flushes all pending output into the compressed file.
 788
 789 This method takes an optional parameter, C<$flush_type>, that controls
 790 how the flushing will be carried out. By default the C<$flush_type>
 791 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
 792 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
 793 strongly recommended that you only set the C<flush_type> parameter if
 794 you fully understand the implications of what it does - overuse of C<flush>
 795 can seriously degrade the level of compression achieved. See the C<zlib>
 796 documentation for details.
 797
 798 Returns 1 on success, 0 on failure.
 799
 800
 801 =item B<$offset = $gz-E<gt>gztell() ;>
 802
 803 Returns the uncompressed file offset.
 804
 805 =item B<$status = $gz-E<gt>gzseek($offset, $whence) ;>
 806
 807 Provides a sub-set of the C<seek> functionality, with the restriction
 808 that it is only legal to seek forward in the compressed file.
 809 It is a fatal error to attempt to seek backward.
 810
 811 When opened for writing, empty parts of the file will have NULL (0x00)
 812 bytes written to them.
 813
 814 The C<$whence> parameter should be one of SEEK_SET, SEEK_CUR or SEEK_END.
 815
 816 Returns 1 on success, 0 on failure.
 817
 818 =item B<$gz-E<gt>gzclose>
 819
 820 Closes the compressed file. Any pending data is flushed to the file
 821 before it is closed.
 822
 823 Returns 1 on success, 0 on failure.
 824
 825 =item B<$gz-E<gt>gzsetparams($level, $strategy>
 826
 827 Change settings for the deflate stream C<$gz>.
 828
 829 The list of the valid options is shown below. Options not specified
 830 will remain unchanged.
 831
 832 Note: This method is only available if you are running zlib 1.0.6 or better.
 833
 834 =over 5
 835
 836 =item B<$level>
 837
 838 Defines the compression level. Valid values are 0 through 9,
 839 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
 840 C<Z_DEFAULT_COMPRESSION>.
 841
 842 =item B<$strategy>
 843
 844 Defines the strategy used to tune the compression. The valid values are
 845 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
 846
 847 =back
 848
 849 =item B<$gz-E<gt>gzerror>
 850
 851 Returns the I<zlib> error message or number for the last operation
 852 associated with C<$gz>. The return value will be the I<zlib> error
 853 number when used in a numeric context and the I<zlib> error message
 854 when used in a string context. The I<zlib> error number constants,
 855 shown below, are available for use.
 856
 857     Z_OK
 858     Z_STREAM_END
 859     Z_ERRNO
 860     Z_STREAM_ERROR
 861     Z_DATA_ERROR
 862     Z_MEM_ERROR
 863     Z_BUF_ERROR
 864
 865 =item B<$gzerrno>
 866
 867 The C<$gzerrno> scalar holds the error code associated with the most
 868 recent I<gzip> routine. Note that unlike C<gzerror()>, the error is
 869 I<not> associated with a particular file.
 870
 871 As with C<gzerror()> it returns an error number in numeric context and
 872 an error message in string context. Unlike C<gzerror()> though, the
 873 error message will correspond to the I<zlib> message when the error is
 874 associated with I<zlib> itself, or the UNIX error message when it is
 875 not (i.e. I<zlib> returned C<Z_ERRORNO>).
 876
 877 As there is an overlap between the error numbers used by I<zlib> and
 878 UNIX, C<$gzerrno> should only be used to check for the presence of
 879 I<an> error in numeric context. Use C<gzerror()> to check for specific
 880 I<zlib> errors. The I<gzcat> example below shows how the variable can
 881 be used safely.
 882
 883 =back
 884
 885
 886 =head2 Examples
 887
 888 Here is an example script which uses the interface. It implements a
 889 I<gzcat> function.
 890
 891     use strict ;
 892     use warnings ;
 893
 894     use Compress::Zlib ;
 895
 896     # use stdin if no files supplied
 897     @ARGV = '-' unless @ARGV ;
 898
 899     foreach my $file (@ARGV) {
 900         my $buffer ;
 901
 902         my $gz = gzopen($file, "rb")
 903              or die "Cannot open $file: $gzerrno\n" ;
 904
 905         print $buffer while $gz->gzread($buffer) > 0 ;
 906
 907         die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n"
 908             if $gzerrno != Z_STREAM_END ;
 909
 910         $gz->gzclose() ;
 911     }
 912
 913 Below is a script which makes use of C<gzreadline>. It implements a
 914 very simple I<grep> like script.
 915
 916     use strict ;
 917     use warnings ;
 918
 919     use Compress::Zlib ;
 920
 921     die "Usage: gzgrep pattern [file...]\n"
 922         unless @ARGV >= 1;
 923
 924     my $pattern = shift ;
 925
 926     # use stdin if no files supplied
 927     @ARGV = '-' unless @ARGV ;
 928
 929     foreach my $file (@ARGV) {
 930         my $gz = gzopen($file, "rb")
 931              or die "Cannot open $file: $gzerrno\n" ;
 932
 933         while ($gz->gzreadline($_) > 0) {
 934             print if /$pattern/ ;
 935         }
 936
 937         die "Error reading from $file: $gzerrno\n"
 938             if $gzerrno != Z_STREAM_END ;
 939
 940         $gz->gzclose() ;
 941     }
 942
 943 This script, I<gzstream>, does the opposite of the I<gzcat> script
 944 above. It reads from standard input and writes a gzip data stream to
 945 standard output.
 946
 947     use strict ;
 948     use warnings ;
 949
 950     use Compress::Zlib ;
 951
 952     binmode STDOUT;  # gzopen only sets it on the fd
 953
 954     my $gz = gzopen(\*STDOUT, "wb")
 955           or die "Cannot open stdout: $gzerrno\n" ;
 956
 957     while (<>) {
 958         $gz->gzwrite($_)
 959           or die "error writing: $gzerrno\n" ;
 960     }
 961
 962     $gz->gzclose ;
 963
 964 =head2 Compress::Zlib::memGzip
 965
 966 This function is used to create an in-memory gzip file with the minimum
 967 possible gzip header (exactly 10 bytes).
 968
 969     $dest = Compress::Zlib::memGzip($buffer) ;
 970
 971 If successful, it returns the in-memory gzip file, otherwise it returns
 972 undef.
 973
 974 The C<$buffer> parameter can either be a scalar or a scalar reference.
 975
 976 See L<IO::Compress::Gzip|IO::Compress::Gzip> for an alternative way to
 977 carry out in-memory gzip compression.
 978
 979 =head2 Compress::Zlib::memGunzip
 980
 981 This function is used to uncompress an in-memory gzip file.
 982
 983     $dest = Compress::Zlib::memGunzip($buffer) ;
 984
 985 If successful, it returns the uncompressed gzip file, otherwise it
 986 returns undef.
 987
 988 The C<$buffer> parameter can either be a scalar or a scalar reference. The
 989 contents of the C<$buffer> parameter are destroyed after calling this function.
 990
 991 See L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for an alternative way
 992 to carry out in-memory gzip uncompression.
 993
 994 =head1 COMPRESS/UNCOMPRESS
 995
 996 Two functions are provided to perform in-memory compression/uncompression of
 997 RFC 1950 data streams. They are called C<compress> and C<uncompress>.
 998
 999 =over 5
1000
1001 =item B<$dest = compress($source [, $level] ) ;>
1002
1003 Compresses C<$source>. If successful it returns the compressed
1004 data. Otherwise it returns I<undef>.
1005
1006 The source buffer, C<$source>, can either be a scalar or a scalar
1007 reference.
1008
1009 The C<$level> parameter defines the compression level. Valid values are
1010 0 through 9, C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>,
1011 C<Z_BEST_COMPRESSION>, and C<Z_DEFAULT_COMPRESSION>.
1012 If C<$level> is not specified C<Z_DEFAULT_COMPRESSION> will be used.
1013
1014
1015 =item B<$dest = uncompress($source) ;>
1016
1017 Uncompresses C<$source>. If successful it returns the uncompressed
1018 data. Otherwise it returns I<undef>.
1019
1020 The source buffer can either be a scalar or a scalar reference.
1021
1022 =back
1023
1024 Please note: the two functions defined above are I<not> compatible with
1025 the Unix commands of the same name.
1026
1027 See L<IO::Deflate|IO::Deflate> and L<IO::Inflate|IO::Inflate> included with
1028 this distribution for an alternative interface for reading/writing RFC 1950
1029 files/buffers.
1030
1031
1032 =head1 Deflate Interface
1033
1034 This section defines an interface that allows in-memory compression using
1035 the I<deflate> interface provided by zlib.
1036
1037 Here is a definition of the interface available:
1038
1039
1040 =head2 B<($d, $status) = deflateInit( [OPT] )>
1041
1042 Initialises a deflation stream.
1043
1044 It combines the features of the I<zlib> functions C<deflateInit>,
1045 C<deflateInit2> and C<deflateSetDictionary>.
1046
1047 If successful, it will return the initialised deflation stream, C<$d>
1048 and C<$status> of C<Z_OK> in a list context. In scalar context it
1049 returns the deflation stream, C<$d>, only.
1050
1051 If not successful, the returned deflation stream (C<$d>) will be
1052 I<undef> and C<$status> will hold the exact I<zlib> error code.
1053
1054 The function optionally takes a number of named options specified as
1055 C<< -Name=>value >> pairs. This allows individual options to be
1056 tailored without having to specify them all in the parameter list.
1057
1058 For backward compatibility, it is also possible to pass the parameters
1059 as a reference to a hash containing the name=>value pairs.
1060
1061 The function takes one optional parameter, a reference to a hash.  The
1062 contents of the hash allow the deflation interface to be tailored.
1063
1064 Here is a list of the valid options:
1065
1066 =over 5
1067
1068 =item B<-Level>
1069
1070 Defines the compression level. Valid values are 0 through 9,
1071 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1072 C<Z_DEFAULT_COMPRESSION>.
1073
1074 The default is Z_DEFAULT_COMPRESSION.
1075
1076 =item B<-Method>
1077
1078 Defines the compression method. The only valid value at present (and
1079 the default) is Z_DEFLATED.
1080
1081 =item B<-WindowBits>
1082
1083 To create an RFC 1950 data stream, set C<WindowBits> to a positive number.
1084
1085 To create an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
1086
1087 For a full definition of the meaning and valid values for C<WindowBits> refer
1088 to the I<zlib> documentation for I<deflateInit2>.
1089
1090 Defaults to MAX_WBITS.
1091
1092 =item B<-MemLevel>
1093
1094 For a definition of the meaning and valid values for C<MemLevel>
1095 refer to the I<zlib> documentation for I<deflateInit2>.
1096
1097 Defaults to MAX_MEM_LEVEL.
1098
1099 =item B<-Strategy>
1100
1101 Defines the strategy used to tune the compression. The valid values are
1102 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1103
1104 The default is Z_DEFAULT_STRATEGY.
1105
1106 =item B<-Dictionary>
1107
1108 When a dictionary is specified I<Compress::Zlib> will automatically
1109 call C<deflateSetDictionary> directly after calling C<deflateInit>. The
1110 Adler32 value for the dictionary can be obtained by calling the method
1111 C<$d->dict_adler()>.
1112
1113 The default is no dictionary.
1114
1115 =item B<-Bufsize>
1116
1117 Sets the initial size for the deflation buffer. If the buffer has to be
1118 reallocated to increase the size, it will grow in increments of
1119 C<Bufsize>.
1120
1121 The default is 4096.
1122
1123 =back
1124
1125 Here is an example of using the C<deflateInit> optional parameter list
1126 to override the default buffer size and compression level. All other
1127 options will take their default values.
1128
1129     deflateInit( -Bufsize => 300,
1130                  -Level => Z_BEST_SPEED  ) ;
1131
1132
1133 =head2 B<($out, $status) = $d-E<gt>deflate($buffer)>
1134
1135
1136 Deflates the contents of C<$buffer>. The buffer can either be a scalar
1137 or a scalar reference.  When finished, C<$buffer> will be
1138 completely processed (assuming there were no errors). If the deflation
1139 was successful it returns the deflated output, C<$out>, and a status
1140 value, C<$status>, of C<Z_OK>.
1141
1142 On error, C<$out> will be I<undef> and C<$status> will contain the
1143 I<zlib> error code.
1144
1145 In a scalar context C<deflate> will return C<$out> only.
1146
1147 As with the I<deflate> function in I<zlib>, it is not necessarily the
1148 case that any output will be produced by this method. So don't rely on
1149 the fact that C<$out> is empty for an error test.
1150
1151
1152 =head2 B<($out, $status) = $d-E<gt>flush([flush_type])>
1153
1154 Typically used to finish the deflation. Any pending output will be
1155 returned via C<$out>.
1156 C<$status> will have a value C<Z_OK> if successful.
1157
1158 In a scalar context C<flush> will return C<$out> only.
1159
1160 Note that flushing can seriously degrade the compression ratio, so it
1161 should only be used to terminate a decompression (using C<Z_FINISH>) or
1162 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
1163
1164 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
1165 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
1166 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
1167 C<flush_type> parameter if you fully understand the implications of
1168 what it does. See the C<zlib> documentation for details.
1169
1170 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
1171
1172 Change settings for the deflate stream C<$d>.
1173
1174 The list of the valid options is shown below. Options not specified
1175 will remain unchanged.
1176
1177 =over 5
1178
1179 =item B<-Level>
1180
1181 Defines the compression level. Valid values are 0 through 9,
1182 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1183 C<Z_DEFAULT_COMPRESSION>.
1184
1185 =item B<-Strategy>
1186
1187 Defines the strategy used to tune the compression. The valid values are
1188 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1189
1190 =back
1191
1192 =head2 B<$d-E<gt>dict_adler()>
1193
1194 Returns the adler32 value for the dictionary.
1195
1196 =head2 B<$d-E<gt>msg()>
1197
1198 Returns the last error message generated by zlib.
1199
1200 =head2 B<$d-E<gt>total_in()>
1201
1202 Returns the total number of bytes uncompressed bytes input to deflate.
1203
1204 =head2 B<$d-E<gt>total_out()>
1205
1206 Returns the total number of compressed bytes output from deflate.
1207
1208 =head2 Example
1209
1210
1211 Here is a trivial example of using C<deflate>. It simply reads standard
1212 input, deflates it and writes it to standard output.
1213
1214     use strict ;
1215     use warnings ;
1216
1217     use Compress::Zlib ;
1218
1219     binmode STDIN;
1220     binmode STDOUT;
1221     my $x = deflateInit()
1222        or die "Cannot create a deflation stream\n" ;
1223
1224     my ($output, $status) ;
1225     while (<>)
1226     {
1227         ($output, $status) = $x->deflate($_) ;
1228
1229         $status == Z_OK
1230             or die "deflation failed\n" ;
1231
1232         print $output ;
1233     }
1234
1235     ($output, $status) = $x->flush() ;
1236
1237     $status == Z_OK
1238         or die "deflation failed\n" ;
1239
1240     print $output ;
1241
1242 =head1 Inflate Interface
1243
1244 This section defines the interface available that allows in-memory
1245 uncompression using the I<deflate> interface provided by zlib.
1246
1247 Here is a definition of the interface:
1248
1249
1250 =head2 B<($i, $status) = inflateInit()>
1251
1252 Initialises an inflation stream.
1253
1254 In a list context it returns the inflation stream, C<$i>, and the
1255 I<zlib> status code in C<$status>. In a scalar context it returns the
1256 inflation stream only.
1257
1258 If successful, C<$i> will hold the inflation stream and C<$status> will
1259 be C<Z_OK>.
1260
1261 If not successful, C<$i> will be I<undef> and C<$status> will hold the
1262 I<zlib> error code.
1263
1264 The function optionally takes a number of named options specified as
1265 C<< -Name=>value >> pairs. This allows individual options to be
1266 tailored without having to specify them all in the parameter list.
1267
1268 For backward compatibility, it is also possible to pass the parameters
1269 as a reference to a hash containing the name=>value pairs.
1270
1271 The function takes one optional parameter, a reference to a hash.  The
1272 contents of the hash allow the deflation interface to be tailored.
1273
1274 Here is a list of the valid options:
1275
1276 =over 5
1277
1278 =item B<-WindowBits>
1279
1280 To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive number.
1281
1282 To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
1283
1284 For a full definition of the meaning and valid values for C<WindowBits> refer
1285 to the I<zlib> documentation for I<inflateInit2>.
1286
1287 Defaults to MAX_WBITS.
1288
1289 =item B<-Bufsize>
1290
1291 Sets the initial size for the inflation buffer. If the buffer has to be
1292 reallocated to increase the size, it will grow in increments of
1293 C<Bufsize>.
1294
1295 Default is 4096.
1296
1297 =item B<-Dictionary>
1298
1299 The default is no dictionary.
1300
1301 =back
1302
1303 Here is an example of using the C<inflateInit> optional parameter to
1304 override the default buffer size.
1305
1306     inflateInit( -Bufsize => 300 ) ;
1307
1308 =head2 B<($out, $status) = $i-E<gt>inflate($buffer)>
1309
1310 Inflates the complete contents of C<$buffer>. The buffer can either be
1311 a scalar or a scalar reference.
1312
1313 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
1314 compressed data has been successfully reached.
1315 If not successful, C<$out> will be I<undef> and C<$status> will hold
1316 the I<zlib> error code.
1317
1318 The C<$buffer> parameter is modified by C<inflate>. On completion it
1319 will contain what remains of the input buffer after inflation. This
1320 means that C<$buffer> will be an empty string when the return status is
1321 C<Z_OK>. When the return status is C<Z_STREAM_END> the C<$buffer>
1322 parameter will contains what (if anything) was stored in the input
1323 buffer after the deflated data stream.
1324
1325 This feature is useful when processing a file format that encapsulates
1326 a  compressed data stream (e.g. gzip, zip).
1327
1328 =head2 B<$status = $i-E<gt>inflateSync($buffer)>
1329
1330 Scans C<$buffer> until it reaches either a I<full flush point> or the
1331 end of the buffer.
1332
1333 If a I<full flush point> is found, C<Z_OK> is returned and C<$buffer>
1334 will be have all data up to the flush point removed. This can then be
1335 passed to the C<deflate> method.
1336
1337 Any other return code means that a flush point was not found. If more
1338 data is available, C<inflateSync> can be called repeatedly with more
1339 compressed data until the flush point is found.
1340
1341
1342 =head2 B<$i-E<gt>dict_adler()>
1343
1344 Returns the adler32 value for the dictionary.
1345
1346 =head2 B<$i-E<gt>msg()>
1347
1348 Returns the last error message generated by zlib.
1349
1350 =head2 B<$i-E<gt>total_in()>
1351
1352 Returns the total number of bytes compressed bytes input to inflate.
1353
1354 =head2 B<$i-E<gt>total_out()>
1355
1356 Returns the total number of uncompressed bytes output from inflate.
1357
1358 =head2 Example
1359
1360 Here is an example of using C<inflate>.
1361
1362     use strict ;
1363     use warnings ;
1364
1365     use Compress::Zlib ;
1366
1367     my $x = inflateInit()
1368        or die "Cannot create a inflation stream\n" ;
1369
1370     my $input = '' ;
1371     binmode STDIN;
1372     binmode STDOUT;
1373
1374     my ($output, $status) ;
1375     while (read(STDIN, $input, 4096))
1376     {
1377         ($output, $status) = $x->inflate(\$input) ;
1378
1379         print $output
1380             if $status == Z_OK or $status == Z_STREAM_END ;
1381
1382         last if $status != Z_OK ;
1383     }
1384
1385     die "inflation failed\n"
1386         unless $status == Z_STREAM_END ;
1387
1388 =head1 CHECKSUM FUNCTIONS
1389
1390 Two functions are provided by I<zlib> to calculate checksums. For the
1391 Perl interface, the order of the two parameters in both functions has
1392 been reversed. This allows both running checksums and one off
1393 calculations to be done.
1394
1395     $crc = adler32($buffer [,$crc]) ;
1396     $crc = crc32($buffer [,$crc]) ;
1397
1398 The buffer parameters can either be a scalar or a scalar reference.
1399
1400 If the $crc parameters is C<undef>, the crc value will be reset.
1401
1402 If you have built this module with zlib 1.2.3 or better, two more
1403 CRC-related functions are available.
1404
1405     $crc = adler32_combine($crc1, $crc2, $len2)l
1406     $crc = crc32_combine($adler1, $adler2, $len2)
1407
1408 These functions allow checksums to be merged.
1409
1410 =head1 CONSTANTS
1411
1412 All the I<zlib> constants are automatically imported when you make use
1413 of I<Compress::Zlib>.
1414
1415
1416 =head1 SEE ALSO
1417
1418 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>
1419
1420 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1421
1422 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1423 L<Archive::Tar|Archive::Tar>,
1424 L<IO::Zlib|IO::Zlib>
1425
1426
1427 For RFC 1950, 1951 and 1952 see
1428 F<http://www.faqs.org/rfcs/rfc1950.html>,
1429 F<http://www.faqs.org/rfcs/rfc1951.html> and
1430 F<http://www.faqs.org/rfcs/rfc1952.html>
1431
1432 The I<zlib> compression library was written by Jean-loup Gailly
1433 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1434
1435 The primary site for the I<zlib> compression library is
1436 F<http://www.zlib.org>.
1437
1438 The primary site for gzip is F<http://www.gzip.org>.
1439
1440
1441
1442
1443 =head1 AUTHOR
1444
1445 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1446
1447
1448
1449 =head1 MODIFICATION HISTORY
1450
1451 See the Changes file.
1452
1453 =head1 COPYRIGHT AND LICENSE
1454
1455 Copyright (c) 1995-2007 Paul Marquess. All rights reserved.
1456
1457 This program is free software; you can redistribute it and/or
1458 modify it under the same terms as Perl itself.
1459
1460
1461