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

   1
   2 package Compress::Zlib;
   3
   4 require 5.004 ;
   5 require Exporter;
   6 use AutoLoader;
   7 use Carp ;
   8 use IO::Handle ;
   9 use Scalar::Util qw(dualvar);
  10
  11 use IO::Compress::Base::Common 2.008 ;
  12 use Compress::Raw::Zlib 2.008 ;
  13 use IO::Compress::Gzip 2.008 ;
  14 use IO::Uncompress::Gunzip 2.008 ;
  15
  16 use strict ;
  17 use warnings ;
  18 use bytes ;
  19 our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
  20
  21 $VERSION = '2.008';
  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.008 ;
 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($output [, $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     ZLIB_VERSION
 636     ZLIB_VERNUM
 637
 638
 639
 640 =head1 DESCRIPTION
 641
 642 The I<Compress::Zlib> module provides a Perl interface to the I<zlib>
 643 compression library (see L</AUTHOR> for details about where to get
 644 I<zlib>).
 645
 646 The C<Compress::Zlib> module can be split into two general areas of
 647 functionality, namely a simple read/write interface to I<gzip> files
 648 and a low-level in-memory compression/decompression interface.
 649
 650 Each of these areas will be discussed in the following sections.
 651
 652 =head2 Notes for users of Compress::Zlib version 1
 653
 654 The main change in C<Compress::Zlib> version 2.x is that it does not now
 655 interface directly to the zlib library. Instead it uses the
 656 C<IO::Compress::Gzip> and C<IO::Uncompress::Gunzip> modules for
 657 reading/writing gzip files, and the C<Compress::Raw::Zlib> module for some
 658 low-level zlib access.
 659
 660 The interface provided by version 2 of this module should be 100% backward
 661 compatible with version 1. If you find a difference in the expected
 662 behaviour please contact the author (See L</AUTHOR>). See L<GZIP INTERFACE>
 663
 664 With the creation of the C<IO::Compress> and C<IO::Uncompress> modules no
 665 new features are planned for C<Compress::Zlib> - the new modules do
 666 everything that C<Compress::Zlib> does and then some. Development on
 667 C<Compress::Zlib> will be limited to bug fixes only.
 668
 669 If you are writing new code, your first port of call should be one of the
 670 new C<IO::Compress> or C<IO::Uncompress> modules.
 671
 672 =head1 GZIP INTERFACE
 673
 674 A number of functions are supplied in I<zlib> for reading and writing
 675 I<gzip> files that conform to RFC 1952. This module provides an interface
 676 to most of them.
 677
 678 If you have previously used C<Compress::Zlib> 1.x, the following
 679 enhancements/changes have been made to the C<gzopen> interface:
 680
 681 =over 5
 682
 683 =item 1
 684
 685 If you want to to open either STDIN or STDOUT with C<gzopen>, you can now
 686 optionally use the special filename "C<->" as a synonym for C<\*STDIN> and
 687 C<\*STDOUT>.
 688
 689 =item 2
 690
 691 In C<Compress::Zlib> version 1.x, C<gzopen> used the zlib library to open
 692 the underlying file. This made things especially tricky when a Perl
 693 filehandle was passed to C<gzopen>. Behind the scenes the numeric C file
 694 descriptor had to be extracted from the Perl filehandle and this passed to
 695 the zlib library.
 696
 697 Apart from being non-portable to some operating systems, this made it
 698 difficult to use C<gzopen> in situations where you wanted to extract/create
 699 a gzip data stream that is embedded in a larger file, without having to
 700 resort to opening and closing the file multiple times.
 701
 702 It also made it impossible to pass a perl filehandle that wasn't associated
 703 with a real filesystem file, like, say, an C<IO::String>.
 704
 705 In C<Compress::Zlib> version 2.x, the C<gzopen> interface has been
 706 completely rewritten to use the L<IO::Compress::Gzip|IO::Compress::Gzip>
 707 for writing gzip files and L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>
 708 for reading gzip files. None of the limitations mentioned above apply.
 709
 710 =item 3
 711
 712 Addition of C<gzseek> to provide a restricted C<seek> interface.
 713
 714 =item 4.
 715
 716 Added C<gztell>.
 717
 718 =back
 719
 720 A more complete and flexible interface for reading/writing gzip
 721 files/buffers is included with the module C<IO-Compress-Zlib>. See
 722 L<IO::Compress::Gzip|IO::Compress::Gzip> and
 723 L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for more details.
 724
 725 =over 5
 726
 727 =item B<$gz = gzopen($filename, $mode)>
 728
 729 =item B<$gz = gzopen($filehandle, $mode)>
 730
 731 This function opens either the I<gzip> file C<$filename> for reading or
 732 writing or attaches to the opened filehandle, C<$filehandle>.
 733 It returns an object on success and C<undef> on failure.
 734
 735 When writing a gzip file this interface will I<always> create the smallest
 736 possible gzip header (exactly 10 bytes). If you want greater control over
 737 what gets stored in the gzip header (like the original filename or a
 738 comment) use L<IO::Compress::Gzip|IO::Compress::Gzip> instead. Similarly if
 739 you want to read the contents of the gzip header use
 740 L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
 741
 742 The second parameter, C<$mode>, is used to specify whether the file is
 743 opened for reading or writing and to optionally specify a compression
 744 level and compression strategy when writing. The format of the C<$mode>
 745 parameter is similar to the mode parameter to the 'C' function C<fopen>,
 746 so "rb" is used to open for reading, "wb" for writing and "ab" for
 747 appending (writing at the end of the file).
 748
 749 To specify a compression level when writing, append a digit between 0
 750 and 9 to the mode string -- 0 means no compression and 9 means maximum
 751 compression.
 752 If no compression level is specified Z_DEFAULT_COMPRESSION is used.
 753
 754 To specify the compression strategy when writing, append 'f' for filtered
 755 data, 'h' for Huffman only compression, or 'R' for run-length encoding.
 756 If no strategy is specified Z_DEFAULT_STRATEGY is used.
 757
 758 So, for example, "wb9" means open for writing with the maximum compression
 759 using the default strategy and "wb4R" means open for writing with compression
 760 level 4 and run-length encoding.
 761
 762 Refer to the I<zlib> documentation for the exact format of the C<$mode>
 763 parameter.
 764
 765 =item B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>
 766
 767 Reads C<$size> bytes from the compressed file into C<$buffer>. If
 768 C<$size> is not specified, it will default to 4096. If the scalar
 769 C<$buffer> is not large enough, it will be extended automatically.
 770
 771 Returns the number of bytes actually read. On EOF it returns 0 and in
 772 the case of an error, -1.
 773
 774 =item B<$bytesread = $gz-E<gt>gzreadline($line) ;>
 775
 776 Reads the next line from the compressed file into C<$line>.
 777
 778 Returns the number of bytes actually read. On EOF it returns 0 and in
 779 the case of an error, -1.
 780
 781 It is legal to intermix calls to C<gzread> and C<gzreadline>.
 782
 783 To maintain backward compatibility with version 1.x of this module
 784 C<gzreadline> ignores the C<$/> variable - it I<always> uses the string
 785 C<"\n"> as the line delimiter.
 786
 787 If you want to read a gzip file a line at a time and have it respect the
 788 C<$/> variable (or C<$INPUT_RECORD_SEPARATOR>, or C<$RS> when C<English> is
 789 in use) see L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
 790
 791 =item B<$byteswritten = $gz-E<gt>gzwrite($buffer) ;>
 792
 793 Writes the contents of C<$buffer> to the compressed file. Returns the
 794 number of bytes actually written, or 0 on error.
 795
 796 =item B<$status = $gz-E<gt>gzflush($flush_type) ;>
 797
 798 Flushes all pending output into the compressed file.
 799
 800 This method takes an optional parameter, C<$flush_type>, that controls
 801 how the flushing will be carried out. By default the C<$flush_type>
 802 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
 803 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
 804 strongly recommended that you only set the C<flush_type> parameter if
 805 you fully understand the implications of what it does - overuse of C<flush>
 806 can seriously degrade the level of compression achieved. See the C<zlib>
 807 documentation for details.
 808
 809 Returns 0 on success.
 810
 811
 812 =item B<$offset = $gz-E<gt>gztell() ;>
 813
 814 Returns the uncompressed file offset.
 815
 816 =item B<$status = $gz-E<gt>gzseek($offset, $whence) ;>
 817
 818 Provides a sub-set of the C<seek> functionality, with the restriction
 819 that it is only legal to seek forward in the compressed file.
 820 It is a fatal error to attempt to seek backward.
 821
 822 When opened for writing, empty parts of the file will have NULL (0x00)
 823 bytes written to them.
 824
 825 The C<$whence> parameter should be one of SEEK_SET, SEEK_CUR or SEEK_END.
 826
 827 Returns 1 on success, 0 on failure.
 828
 829 =item B<$gz-E<gt>gzclose>
 830
 831 Closes the compressed file. Any pending data is flushed to the file
 832 before it is closed.
 833
 834 Returns 0 on success.
 835
 836 =item B<$gz-E<gt>gzsetparams($level, $strategy>
 837
 838 Change settings for the deflate stream C<$gz>.
 839
 840 The list of the valid options is shown below. Options not specified
 841 will remain unchanged.
 842
 843 Note: This method is only available if you are running zlib 1.0.6 or better.
 844
 845 =over 5
 846
 847 =item B<$level>
 848
 849 Defines the compression level. Valid values are 0 through 9,
 850 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
 851 C<Z_DEFAULT_COMPRESSION>.
 852
 853 =item B<$strategy>
 854
 855 Defines the strategy used to tune the compression. The valid values are
 856 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
 857
 858 =back
 859
 860 =item B<$gz-E<gt>gzerror>
 861
 862 Returns the I<zlib> error message or number for the last operation
 863 associated with C<$gz>. The return value will be the I<zlib> error
 864 number when used in a numeric context and the I<zlib> error message
 865 when used in a string context. The I<zlib> error number constants,
 866 shown below, are available for use.
 867
 868     Z_OK
 869     Z_STREAM_END
 870     Z_ERRNO
 871     Z_STREAM_ERROR
 872     Z_DATA_ERROR
 873     Z_MEM_ERROR
 874     Z_BUF_ERROR
 875
 876 =item B<$gzerrno>
 877
 878 The C<$gzerrno> scalar holds the error code associated with the most
 879 recent I<gzip> routine. Note that unlike C<gzerror()>, the error is
 880 I<not> associated with a particular file.
 881
 882 As with C<gzerror()> it returns an error number in numeric context and
 883 an error message in string context. Unlike C<gzerror()> though, the
 884 error message will correspond to the I<zlib> message when the error is
 885 associated with I<zlib> itself, or the UNIX error message when it is
 886 not (i.e. I<zlib> returned C<Z_ERRORNO>).
 887
 888 As there is an overlap between the error numbers used by I<zlib> and
 889 UNIX, C<$gzerrno> should only be used to check for the presence of
 890 I<an> error in numeric context. Use C<gzerror()> to check for specific
 891 I<zlib> errors. The I<gzcat> example below shows how the variable can
 892 be used safely.
 893
 894 =back
 895
 896
 897 =head2 Examples
 898
 899 Here is an example script which uses the interface. It implements a
 900 I<gzcat> function.
 901
 902     use strict ;
 903     use warnings ;
 904
 905     use Compress::Zlib ;
 906
 907     # use stdin if no files supplied
 908     @ARGV = '-' unless @ARGV ;
 909
 910     foreach my $file (@ARGV) {
 911         my $buffer ;
 912
 913         my $gz = gzopen($file, "rb")
 914              or die "Cannot open $file: $gzerrno\n" ;
 915
 916         print $buffer while $gz->gzread($buffer) > 0 ;
 917
 918         die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n"
 919             if $gzerrno != Z_STREAM_END ;
 920
 921         $gz->gzclose() ;
 922     }
 923
 924 Below is a script which makes use of C<gzreadline>. It implements a
 925 very simple I<grep> like script.
 926
 927     use strict ;
 928     use warnings ;
 929
 930     use Compress::Zlib ;
 931
 932     die "Usage: gzgrep pattern [file...]\n"
 933         unless @ARGV >= 1;
 934
 935     my $pattern = shift ;
 936
 937     # use stdin if no files supplied
 938     @ARGV = '-' unless @ARGV ;
 939
 940     foreach my $file (@ARGV) {
 941         my $gz = gzopen($file, "rb")
 942              or die "Cannot open $file: $gzerrno\n" ;
 943
 944         while ($gz->gzreadline($_) > 0) {
 945             print if /$pattern/ ;
 946         }
 947
 948         die "Error reading from $file: $gzerrno\n"
 949             if $gzerrno != Z_STREAM_END ;
 950
 951         $gz->gzclose() ;
 952     }
 953
 954 This script, I<gzstream>, does the opposite of the I<gzcat> script
 955 above. It reads from standard input and writes a gzip data stream to
 956 standard output.
 957
 958     use strict ;
 959     use warnings ;
 960
 961     use Compress::Zlib ;
 962
 963     binmode STDOUT;  # gzopen only sets it on the fd
 964
 965     my $gz = gzopen(\*STDOUT, "wb")
 966           or die "Cannot open stdout: $gzerrno\n" ;
 967
 968     while (<>) {
 969         $gz->gzwrite($_)
 970           or die "error writing: $gzerrno\n" ;
 971     }
 972
 973     $gz->gzclose ;
 974
 975 =head2 Compress::Zlib::memGzip
 976
 977 This function is used to create an in-memory gzip file with the minimum
 978 possible gzip header (exactly 10 bytes).
 979
 980     $dest = Compress::Zlib::memGzip($buffer) ;
 981
 982 If successful, it returns the in-memory gzip file, otherwise it returns
 983 undef.
 984
 985 The C<$buffer> parameter can either be a scalar or a scalar reference.
 986
 987 See L<IO::Compress::Gzip|IO::Compress::Gzip> for an alternative way to
 988 carry out in-memory gzip compression.
 989
 990 =head2 Compress::Zlib::memGunzip
 991
 992 This function is used to uncompress an in-memory gzip file.
 993
 994     $dest = Compress::Zlib::memGunzip($buffer) ;
 995
 996 If successful, it returns the uncompressed gzip file, otherwise it
 997 returns undef.
 998
 999 The C<$buffer> parameter can either be a scalar or a scalar reference. The
1000 contents of the C<$buffer> parameter are destroyed after calling this function.
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
1026 =item B<$dest = uncompress($source) ;>
1027
1028 Uncompresses C<$source>. If successful it returns the uncompressed
1029 data. Otherwise it returns I<undef>.
1030
1031 The source buffer can either be a scalar or a scalar reference.
1032
1033 =back
1034
1035 Please note: the two functions defined above are I<not> compatible with
1036 the Unix commands of the same name.
1037
1038 See L<IO::Deflate|IO::Deflate> and L<IO::Inflate|IO::Inflate> included with
1039 this distribution for an alternative interface for reading/writing RFC 1950
1040 files/buffers.
1041
1042
1043 =head1 Deflate Interface
1044
1045 This section defines an interface that allows in-memory compression using
1046 the I<deflate> interface provided by zlib.
1047
1048 Here is a definition of the interface available:
1049
1050
1051 =head2 B<($d, $status) = deflateInit( [OPT] )>
1052
1053 Initialises a deflation stream.
1054
1055 It combines the features of the I<zlib> functions C<deflateInit>,
1056 C<deflateInit2> and C<deflateSetDictionary>.
1057
1058 If successful, it will return the initialised deflation stream, C<$d>
1059 and C<$status> of C<Z_OK> in a list context. In scalar context it
1060 returns the deflation stream, C<$d>, only.
1061
1062 If not successful, the returned deflation stream (C<$d>) will be
1063 I<undef> and C<$status> will hold the exact I<zlib> error code.
1064
1065 The function optionally takes a number of named options specified as
1066 C<< -Name=>value >> pairs. This allows individual options to be
1067 tailored without having to specify them all in the parameter list.
1068
1069 For backward compatibility, it is also possible to pass the parameters
1070 as a reference to a hash containing the name=>value pairs.
1071
1072 The function takes one optional parameter, a reference to a hash.  The
1073 contents of the hash allow the deflation interface to be tailored.
1074
1075 Here is a list of the valid options:
1076
1077 =over 5
1078
1079 =item B<-Level>
1080
1081 Defines the compression level. Valid values are 0 through 9,
1082 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1083 C<Z_DEFAULT_COMPRESSION>.
1084
1085 The default is Z_DEFAULT_COMPRESSION.
1086
1087 =item B<-Method>
1088
1089 Defines the compression method. The only valid value at present (and
1090 the default) is Z_DEFLATED.
1091
1092 =item B<-WindowBits>
1093
1094 To create an RFC 1950 data stream, set C<WindowBits> to a positive number.
1095
1096 To create an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
1097
1098 For a full definition of the meaning and valid values for C<WindowBits> refer
1099 to the I<zlib> documentation for I<deflateInit2>.
1100
1101 Defaults to MAX_WBITS.
1102
1103 =item B<-MemLevel>
1104
1105 For a definition of the meaning and valid values for C<MemLevel>
1106 refer to the I<zlib> documentation for I<deflateInit2>.
1107
1108 Defaults to MAX_MEM_LEVEL.
1109
1110 =item B<-Strategy>
1111
1112 Defines the strategy used to tune the compression. The valid values are
1113 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1114
1115 The default is Z_DEFAULT_STRATEGY.
1116
1117 =item B<-Dictionary>
1118
1119 When a dictionary is specified I<Compress::Zlib> will automatically
1120 call C<deflateSetDictionary> directly after calling C<deflateInit>. The
1121 Adler32 value for the dictionary can be obtained by calling the method
1122 C<$d->dict_adler()>.
1123
1124 The default is no dictionary.
1125
1126 =item B<-Bufsize>
1127
1128 Sets the initial size for the deflation buffer. If the buffer has to be
1129 reallocated to increase the size, it will grow in increments of
1130 C<Bufsize>.
1131
1132 The default is 4096.
1133
1134 =back
1135
1136 Here is an example of using the C<deflateInit> optional parameter list
1137 to override the default buffer size and compression level. All other
1138 options will take their default values.
1139
1140     deflateInit( -Bufsize => 300,
1141                  -Level => Z_BEST_SPEED  ) ;
1142
1143
1144 =head2 B<($out, $status) = $d-E<gt>deflate($buffer)>
1145
1146
1147 Deflates the contents of C<$buffer>. The buffer can either be a scalar
1148 or a scalar reference.  When finished, C<$buffer> will be
1149 completely processed (assuming there were no errors). If the deflation
1150 was successful it returns the deflated output, C<$out>, and a status
1151 value, C<$status>, of C<Z_OK>.
1152
1153 On error, C<$out> will be I<undef> and C<$status> will contain the
1154 I<zlib> error code.
1155
1156 In a scalar context C<deflate> will return C<$out> only.
1157
1158 As with the I<deflate> function in I<zlib>, it is not necessarily the
1159 case that any output will be produced by this method. So don't rely on
1160 the fact that C<$out> is empty for an error test.
1161
1162
1163 =head2 B<($out, $status) = $d-E<gt>flush([flush_type])>
1164
1165 Typically used to finish the deflation. Any pending output will be
1166 returned via C<$out>.
1167 C<$status> will have a value C<Z_OK> if successful.
1168
1169 In a scalar context C<flush> will return C<$out> only.
1170
1171 Note that flushing can seriously degrade the compression ratio, so it
1172 should only be used to terminate a decompression (using C<Z_FINISH>) or
1173 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
1174
1175 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
1176 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
1177 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
1178 C<flush_type> parameter if you fully understand the implications of
1179 what it does. See the C<zlib> documentation for details.
1180
1181 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
1182
1183 Change settings for the deflate stream C<$d>.
1184
1185 The list of the valid options is shown below. Options not specified
1186 will remain unchanged.
1187
1188 =over 5
1189
1190 =item B<-Level>
1191
1192 Defines the compression level. Valid values are 0 through 9,
1193 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1194 C<Z_DEFAULT_COMPRESSION>.
1195
1196 =item B<-Strategy>
1197
1198 Defines the strategy used to tune the compression. The valid values are
1199 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1200
1201 =back
1202
1203 =head2 B<$d-E<gt>dict_adler()>
1204
1205 Returns the adler32 value for the dictionary.
1206
1207 =head2 B<$d-E<gt>msg()>
1208
1209 Returns the last error message generated by zlib.
1210
1211 =head2 B<$d-E<gt>total_in()>
1212
1213 Returns the total number of bytes uncompressed bytes input to deflate.
1214
1215 =head2 B<$d-E<gt>total_out()>
1216
1217 Returns the total number of compressed bytes output from deflate.
1218
1219 =head2 Example
1220
1221
1222 Here is a trivial example of using C<deflate>. It simply reads standard
1223 input, deflates it and writes it to standard output.
1224
1225     use strict ;
1226     use warnings ;
1227
1228     use Compress::Zlib ;
1229
1230     binmode STDIN;
1231     binmode STDOUT;
1232     my $x = deflateInit()
1233        or die "Cannot create a deflation stream\n" ;
1234
1235     my ($output, $status) ;
1236     while (<>)
1237     {
1238         ($output, $status) = $x->deflate($_) ;
1239
1240         $status == Z_OK
1241             or die "deflation failed\n" ;
1242
1243         print $output ;
1244     }
1245
1246     ($output, $status) = $x->flush() ;
1247
1248     $status == Z_OK
1249         or die "deflation failed\n" ;
1250
1251     print $output ;
1252
1253 =head1 Inflate Interface
1254
1255 This section defines the interface available that allows in-memory
1256 uncompression using the I<deflate> interface provided by zlib.
1257
1258 Here is a definition of the interface:
1259
1260
1261 =head2 B<($i, $status) = inflateInit()>
1262
1263 Initialises an inflation stream.
1264
1265 In a list context it returns the inflation stream, C<$i>, and the
1266 I<zlib> status code in C<$status>. In a scalar context it returns the
1267 inflation stream only.
1268
1269 If successful, C<$i> will hold the inflation stream and C<$status> will
1270 be C<Z_OK>.
1271
1272 If not successful, C<$i> will be I<undef> and C<$status> will hold the
1273 I<zlib> error code.
1274
1275 The function optionally takes a number of named options specified as
1276 C<< -Name=>value >> pairs. This allows individual options to be
1277 tailored without having to specify them all in the parameter list.
1278
1279 For backward compatibility, it is also possible to pass the parameters
1280 as a reference to a hash containing the name=>value pairs.
1281
1282 The function takes one optional parameter, a reference to a hash.  The
1283 contents of the hash allow the deflation interface to be tailored.
1284
1285 Here is a list of the valid options:
1286
1287 =over 5
1288
1289 =item B<-WindowBits>
1290
1291 To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive number.
1292
1293 To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
1294
1295 For a full definition of the meaning and valid values for C<WindowBits> refer
1296 to the I<zlib> documentation for I<inflateInit2>.
1297
1298 Defaults to MAX_WBITS.
1299
1300 =item B<-Bufsize>
1301
1302 Sets the initial size for the inflation buffer. If the buffer has to be
1303 reallocated to increase the size, it will grow in increments of
1304 C<Bufsize>.
1305
1306 Default is 4096.
1307
1308 =item B<-Dictionary>
1309
1310 The default is no dictionary.
1311
1312 =back
1313
1314 Here is an example of using the C<inflateInit> optional parameter to
1315 override the default buffer size.
1316
1317     inflateInit( -Bufsize => 300 ) ;
1318
1319 =head2 B<($out, $status) = $i-E<gt>inflate($buffer)>
1320
1321 Inflates the complete contents of C<$buffer>. The buffer can either be
1322 a scalar or a scalar reference.
1323
1324 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
1325 compressed data has been successfully reached.
1326 If not successful, C<$out> will be I<undef> and C<$status> will hold
1327 the I<zlib> error code.
1328
1329 The C<$buffer> parameter is modified by C<inflate>. On completion it
1330 will contain what remains of the input buffer after inflation. This
1331 means that C<$buffer> will be an empty string when the return status is
1332 C<Z_OK>. When the return status is C<Z_STREAM_END> the C<$buffer>
1333 parameter will contains what (if anything) was stored in the input
1334 buffer after the deflated data stream.
1335
1336 This feature is useful when processing a file format that encapsulates
1337 a  compressed data stream (e.g. gzip, zip).
1338
1339 =head2 B<$status = $i-E<gt>inflateSync($buffer)>
1340
1341 Scans C<$buffer> until it reaches either a I<full flush point> or the
1342 end of the buffer.
1343
1344 If a I<full flush point> is found, C<Z_OK> is returned and C<$buffer>
1345 will be have all data up to the flush point removed. This can then be
1346 passed to the C<deflate> method.
1347
1348 Any other return code means that a flush point was not found. If more
1349 data is available, C<inflateSync> can be called repeatedly with more
1350 compressed data until the flush point is found.
1351
1352
1353 =head2 B<$i-E<gt>dict_adler()>
1354
1355 Returns the adler32 value for the dictionary.
1356
1357 =head2 B<$i-E<gt>msg()>
1358
1359 Returns the last error message generated by zlib.
1360
1361 =head2 B<$i-E<gt>total_in()>
1362
1363 Returns the total number of bytes compressed bytes input to inflate.
1364
1365 =head2 B<$i-E<gt>total_out()>
1366
1367 Returns the total number of uncompressed bytes output from inflate.
1368
1369 =head2 Example
1370
1371 Here is an example of using C<inflate>.
1372
1373     use strict ;
1374     use warnings ;
1375
1376     use Compress::Zlib ;
1377
1378     my $x = inflateInit()
1379        or die "Cannot create a inflation stream\n" ;
1380
1381     my $input = '' ;
1382     binmode STDIN;
1383     binmode STDOUT;
1384
1385     my ($output, $status) ;
1386     while (read(STDIN, $input, 4096))
1387     {
1388         ($output, $status) = $x->inflate(\$input) ;
1389
1390         print $output
1391             if $status == Z_OK or $status == Z_STREAM_END ;
1392
1393         last if $status != Z_OK ;
1394     }
1395
1396     die "inflation failed\n"
1397         unless $status == Z_STREAM_END ;
1398
1399 =head1 CHECKSUM FUNCTIONS
1400
1401 Two functions are provided by I<zlib> to calculate checksums. For the
1402 Perl interface, the order of the two parameters in both functions has
1403 been reversed. This allows both running checksums and one off
1404 calculations to be done.
1405
1406     $crc = adler32($buffer [,$crc]) ;
1407     $crc = crc32($buffer [,$crc]) ;
1408
1409 The buffer parameters can either be a scalar or a scalar reference.
1410
1411 If the $crc parameters is C<undef>, the crc value will be reset.
1412
1413 If you have built this module with zlib 1.2.3 or better, two more
1414 CRC-related functions are available.
1415
1416     $crc = adler32_combine($crc1, $crc2, $len2)l
1417     $crc = crc32_combine($adler1, $adler2, $len2)
1418
1419 These functions allow checksums to be merged.
1420
1421 =head1 CONSTANTS
1422
1423 All the I<zlib> constants are automatically imported when you make use
1424 of I<Compress::Zlib>.
1425
1426
1427 =head1 SEE ALSO
1428
1429 L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1430
1431 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1432
1433 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1434 L<Archive::Tar|Archive::Tar>,
1435 L<IO::Zlib|IO::Zlib>
1436
1437
1438 For RFC 1950, 1951 and 1952 see
1439 F<http://www.faqs.org/rfcs/rfc1950.html>,
1440 F<http://www.faqs.org/rfcs/rfc1951.html> and
1441 F<http://www.faqs.org/rfcs/rfc1952.html>
1442
1443 The I<zlib> compression library was written by Jean-loup Gailly
1444 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1445
1446 The primary site for the I<zlib> compression library is
1447 F<http://www.zlib.org>.
1448
1449 The primary site for gzip is F<http://www.gzip.org>.
1450
1451
1452
1453
1454 =head1 AUTHOR
1455
1456 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1457
1458
1459
1460 =head1 MODIFICATION HISTORY
1461
1462 See the Changes file.
1463
1464 =head1 COPYRIGHT AND LICENSE
1465
1466 Copyright (c) 1995-2007 Paul Marquess. All rights reserved.
1467
1468 This program is free software; you can redistribute it and/or
1469 modify it under the same terms as Perl itself.
1470
1471
1472