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