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