local-lib5/lib/perl5/Compress/Zlib.pm

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