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