ext/IO-Compress/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.020 ;
  12 use Compress::Raw::Zlib 2.020 ;
  13 use IO::Compress::Gzip 2.020 ;
  14 use IO::Uncompress::Gunzip 2.020 ;
  15
  16 use strict ;
  17 use warnings ;
  18 use bytes ;
  19 our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
  20
  21 $VERSION = '2.020';
  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.020 ;
 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 See L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for an alternative way
 998 to carry out in-memory gzip uncompression.
 999
1000 =head1 COMPRESS/UNCOMPRESS
1001
1002 Two functions are provided to perform in-memory compression/uncompression of
1003 RFC 1950 data streams. They are called C<compress> and C<uncompress>.
1004
1005 =over 5
1006
1007 =item B<$dest = compress($source [, $level] ) ;>
1008
1009 Compresses C<$source>. If successful it returns the compressed
1010 data. Otherwise it returns I<undef>.
1011
1012 The source buffer, C<$source>, can either be a scalar or a scalar
1013 reference.
1014
1015 The C<$level> parameter defines the compression level. Valid values are
1016 0 through 9, C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>,
1017 C<Z_BEST_COMPRESSION>, and C<Z_DEFAULT_COMPRESSION>.
1018 If C<$level> is not specified C<Z_DEFAULT_COMPRESSION> will be used.
1019
1020 =item B<$dest = uncompress($source) ;>
1021
1022 Uncompresses C<$source>. If successful it returns the uncompressed
1023 data. Otherwise it returns I<undef>.
1024
1025 The source buffer can either be a scalar or a scalar reference.
1026
1027 =back
1028
1029 Please note: the two functions defined above are I<not> compatible with
1030 the Unix commands of the same name.
1031
1032 See L<IO::Deflate|IO::Deflate> and L<IO::Inflate|IO::Inflate> included with
1033 this distribution for an alternative interface for reading/writing RFC 1950
1034 files/buffers.
1035
1036 =head1 Deflate Interface
1037
1038 This section defines an interface that allows in-memory compression using
1039 the I<deflate> interface provided by zlib.
1040
1041 Here is a definition of the interface available:
1042
1043 =head2 B<($d, $status) = deflateInit( [OPT] )>
1044
1045 Initialises a deflation stream.
1046
1047 It combines the features of the I<zlib> functions C<deflateInit>,
1048 C<deflateInit2> and C<deflateSetDictionary>.
1049
1050 If successful, it will return the initialised deflation stream, C<$d>
1051 and C<$status> of C<Z_OK> in a list context. In scalar context it
1052 returns the deflation stream, C<$d>, only.
1053
1054 If not successful, the returned deflation stream (C<$d>) will be
1055 I<undef> and C<$status> will hold the exact I<zlib> error code.
1056
1057 The function optionally takes a number of named options specified as
1058 C<< -Name=>value >> pairs. This allows individual options to be
1059 tailored without having to specify them all in the parameter list.
1060
1061 For backward compatibility, it is also possible to pass the parameters
1062 as a reference to a hash containing the name=>value pairs.
1063
1064 The function takes one optional parameter, a reference to a hash.  The
1065 contents of the hash allow the deflation interface to be tailored.
1066
1067 Here is a list of the valid options:
1068
1069 =over 5
1070
1071 =item B<-Level>
1072
1073 Defines the compression level. Valid values are 0 through 9,
1074 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1075 C<Z_DEFAULT_COMPRESSION>.
1076
1077 The default is Z_DEFAULT_COMPRESSION.
1078
1079 =item B<-Method>
1080
1081 Defines the compression method. The only valid value at present (and
1082 the default) is Z_DEFLATED.
1083
1084 =item B<-WindowBits>
1085
1086 To create an RFC 1950 data stream, set C<WindowBits> to a positive number.
1087
1088 To create an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
1089
1090 For a full definition of the meaning and valid values for C<WindowBits> refer
1091 to the I<zlib> documentation for I<deflateInit2>.
1092
1093 Defaults to MAX_WBITS.
1094
1095 =item B<-MemLevel>
1096
1097 For a definition of the meaning and valid values for C<MemLevel>
1098 refer to the I<zlib> documentation for I<deflateInit2>.
1099
1100 Defaults to MAX_MEM_LEVEL.
1101
1102 =item B<-Strategy>
1103
1104 Defines the strategy used to tune the compression. The valid values are
1105 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1106
1107 The default is Z_DEFAULT_STRATEGY.
1108
1109 =item B<-Dictionary>
1110
1111 When a dictionary is specified I<Compress::Zlib> will automatically
1112 call C<deflateSetDictionary> directly after calling C<deflateInit>. The
1113 Adler32 value for the dictionary can be obtained by calling the method
1114 C<$d->dict_adler()>.
1115
1116 The default is no dictionary.
1117
1118 =item B<-Bufsize>
1119
1120 Sets the initial size for the deflation buffer. If the buffer has to be
1121 reallocated to increase the size, it will grow in increments of
1122 C<Bufsize>.
1123
1124 The default is 4096.
1125
1126 =back
1127
1128 Here is an example of using the C<deflateInit> optional parameter list
1129 to override the default buffer size and compression level. All other
1130 options will take their default values.
1131
1132     deflateInit( -Bufsize => 300,
1133                  -Level => Z_BEST_SPEED  ) ;
1134
1135 =head2 B<($out, $status) = $d-E<gt>deflate($buffer)>
1136
1137 Deflates the contents of C<$buffer>. The buffer can either be a scalar
1138 or a scalar reference.  When finished, C<$buffer> will be
1139 completely processed (assuming there were no errors). If the deflation
1140 was successful it returns the deflated output, C<$out>, and a status
1141 value, C<$status>, of C<Z_OK>.
1142
1143 On error, C<$out> will be I<undef> and C<$status> will contain the
1144 I<zlib> error code.
1145
1146 In a scalar context C<deflate> will return C<$out> only.
1147
1148 As with the I<deflate> function in I<zlib>, it is not necessarily the
1149 case that any output will be produced by this method. So don't rely on
1150 the fact that C<$out> is empty for an error test.
1151
1152 =head2 B<($out, $status) = $d-E<gt>flush()>
1153 =head2 B<($out, $status) = $d-E<gt>flush($flush_type)>
1154
1155 Typically used to finish the deflation. Any pending output will be
1156 returned via C<$out>.
1157 C<$status> will have a value C<Z_OK> if successful.
1158
1159 In a scalar context C<flush> will return C<$out> only.
1160
1161 Note that flushing can seriously degrade the compression ratio, so it
1162 should only be used to terminate a decompression (using C<Z_FINISH>) or
1163 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
1164
1165 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
1166 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
1167 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
1168 C<flush_type> parameter if you fully understand the implications of
1169 what it does. See the C<zlib> documentation for details.
1170
1171 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
1172
1173 Change settings for the deflate stream C<$d>.
1174
1175 The list of the valid options is shown below. Options not specified
1176 will remain unchanged.
1177
1178 =over 5
1179
1180 =item B<-Level>
1181
1182 Defines the compression level. Valid values are 0 through 9,
1183 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1184 C<Z_DEFAULT_COMPRESSION>.
1185
1186 =item B<-Strategy>
1187
1188 Defines the strategy used to tune the compression. The valid values are
1189 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1190
1191 =back
1192
1193 =head2 B<$d-E<gt>dict_adler()>
1194
1195 Returns the adler32 value for the dictionary.
1196
1197 =head2 B<$d-E<gt>msg()>
1198
1199 Returns the last error message generated by zlib.
1200
1201 =head2 B<$d-E<gt>total_in()>
1202
1203 Returns the total number of bytes uncompressed bytes input to deflate.
1204
1205 =head2 B<$d-E<gt>total_out()>
1206
1207 Returns the total number of compressed bytes output from deflate.
1208
1209 =head2 Example
1210
1211 Here is a trivial example of using C<deflate>. It simply reads standard
1212 input, deflates it and writes it to standard output.
1213
1214     use strict ;
1215     use warnings ;
1216
1217     use Compress::Zlib ;
1218
1219     binmode STDIN;
1220     binmode STDOUT;
1221     my $x = deflateInit()
1222        or die "Cannot create a deflation stream\n" ;
1223
1224     my ($output, $status) ;
1225     while (<>)
1226     {
1227         ($output, $status) = $x->deflate($_) ;
1228
1229         $status == Z_OK
1230             or die "deflation failed\n" ;
1231
1232         print $output ;
1233     }
1234
1235     ($output, $status) = $x->flush() ;
1236
1237     $status == Z_OK
1238         or die "deflation failed\n" ;
1239
1240     print $output ;
1241
1242 =head1 Inflate Interface
1243
1244 This section defines the interface available that allows in-memory
1245 uncompression using the I<deflate> interface provided by zlib.
1246
1247 Here is a definition of the interface:
1248
1249 =head2 B<($i, $status) = inflateInit()>
1250
1251 Initialises an inflation stream.
1252
1253 In a list context it returns the inflation stream, C<$i>, and the
1254 I<zlib> status code in C<$status>. In a scalar context it returns the
1255 inflation stream only.
1256
1257 If successful, C<$i> will hold the inflation stream and C<$status> will
1258 be C<Z_OK>.
1259
1260 If not successful, C<$i> will be I<undef> and C<$status> will hold the
1261 I<zlib> error code.
1262
1263 The function optionally takes a number of named options specified as
1264 C<< -Name=>value >> pairs. This allows individual options to be
1265 tailored without having to specify them all in the parameter list.
1266
1267 For backward compatibility, it is also possible to pass the parameters
1268 as a reference to a hash containing the name=>value pairs.
1269
1270 The function takes one optional parameter, a reference to a hash.  The
1271 contents of the hash allow the deflation interface to be tailored.
1272
1273 Here is a list of the valid options:
1274
1275 =over 5
1276
1277 =item B<-WindowBits>
1278
1279 To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive number.
1280
1281 To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
1282
1283 For a full definition of the meaning and valid values for C<WindowBits> refer
1284 to the I<zlib> documentation for I<inflateInit2>.
1285
1286 Defaults to MAX_WBITS.
1287
1288 =item B<-Bufsize>
1289
1290 Sets the initial size for the inflation buffer. If the buffer has to be
1291 reallocated to increase the size, it will grow in increments of
1292 C<Bufsize>.
1293
1294 Default is 4096.
1295
1296 =item B<-Dictionary>
1297
1298 The default is no dictionary.
1299
1300 =back
1301
1302 Here is an example of using the C<inflateInit> optional parameter to
1303 override the default buffer size.
1304
1305     inflateInit( -Bufsize => 300 ) ;
1306
1307 =head2 B<($out, $status) = $i-E<gt>inflate($buffer)>
1308
1309 Inflates the complete contents of C<$buffer>. The buffer can either be
1310 a scalar or a scalar reference.
1311
1312 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
1313 compressed data has been successfully reached.
1314 If not successful, C<$out> will be I<undef> and C<$status> will hold
1315 the I<zlib> error code.
1316
1317 The C<$buffer> parameter is modified by C<inflate>. On completion it
1318 will contain what remains of the input buffer after inflation. This
1319 means that C<$buffer> will be an empty string when the return status is
1320 C<Z_OK>. When the return status is C<Z_STREAM_END> the C<$buffer>
1321 parameter will contains what (if anything) was stored in the input
1322 buffer after the deflated data stream.
1323
1324 This feature is useful when processing a file format that encapsulates
1325 a  compressed data stream (e.g. gzip, zip).
1326
1327 =head2 B<$status = $i-E<gt>inflateSync($buffer)>
1328
1329 Scans C<$buffer> until it reaches either a I<full flush point> or the
1330 end of the buffer.
1331
1332 If a I<full flush point> is found, C<Z_OK> is returned and C<$buffer>
1333 will be have all data up to the flush point removed. This can then be
1334 passed to the C<deflate> method.
1335
1336 Any other return code means that a flush point was not found. If more
1337 data is available, C<inflateSync> can be called repeatedly with more
1338 compressed data until the flush point is found.
1339
1340 =head2 B<$i-E<gt>dict_adler()>
1341
1342 Returns the adler32 value for the dictionary.
1343
1344 =head2 B<$i-E<gt>msg()>
1345
1346 Returns the last error message generated by zlib.
1347
1348 =head2 B<$i-E<gt>total_in()>
1349
1350 Returns the total number of bytes compressed bytes input to inflate.
1351
1352 =head2 B<$i-E<gt>total_out()>
1353
1354 Returns the total number of uncompressed bytes output from inflate.
1355
1356 =head2 Example
1357
1358 Here is an example of using C<inflate>.
1359
1360     use strict ;
1361     use warnings ;
1362
1363     use Compress::Zlib ;
1364
1365     my $x = inflateInit()
1366        or die "Cannot create a inflation stream\n" ;
1367
1368     my $input = '' ;
1369     binmode STDIN;
1370     binmode STDOUT;
1371
1372     my ($output, $status) ;
1373     while (read(STDIN, $input, 4096))
1374     {
1375         ($output, $status) = $x->inflate(\$input) ;
1376
1377         print $output
1378             if $status == Z_OK or $status == Z_STREAM_END ;
1379
1380         last if $status != Z_OK ;
1381     }
1382
1383     die "inflation failed\n"
1384         unless $status == Z_STREAM_END ;
1385
1386 =head1 CHECKSUM FUNCTIONS
1387
1388 Two functions are provided by I<zlib> to calculate checksums. For the
1389 Perl interface, the order of the two parameters in both functions has
1390 been reversed. This allows both running checksums and one off
1391 calculations to be done.
1392
1393     $crc = adler32($buffer [,$crc]) ;
1394     $crc = crc32($buffer [,$crc]) ;
1395
1396 The buffer parameters can either be a scalar or a scalar reference.
1397
1398 If the $crc parameters is C<undef>, the crc value will be reset.
1399
1400 If you have built this module with zlib 1.2.3 or better, two more
1401 CRC-related functions are available.
1402
1403     $crc = adler32_combine($crc1, $crc2, $len2)l
1404     $crc = crc32_combine($adler1, $adler2, $len2)
1405
1406 These functions allow checksums to be merged.
1407
1408 =head1 Misc
1409
1410 =head2 my $version = Compress::Zlib::zlib_version();
1411
1412 Returns the version of the zlib library.
1413
1414 =head1 CONSTANTS
1415
1416 All the I<zlib> constants are automatically imported when you make use
1417 of I<Compress::Zlib>.
1418
1419 =head1 SEE ALSO
1420
1421 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>
1422
1423 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1424
1425 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1426 L<Archive::Tar|Archive::Tar>,
1427 L<IO::Zlib|IO::Zlib>
1428
1429 For RFC 1950, 1951 and 1952 see
1430 F<http://www.faqs.org/rfcs/rfc1950.html>,
1431 F<http://www.faqs.org/rfcs/rfc1951.html> and
1432 F<http://www.faqs.org/rfcs/rfc1952.html>
1433
1434 The I<zlib> compression library was written by Jean-loup Gailly
1435 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1436
1437 The primary site for the I<zlib> compression library is
1438 F<http://www.zlib.org>.
1439
1440 The primary site for gzip is F<http://www.gzip.org>.
1441
1442 =head1 AUTHOR
1443
1444 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1445
1446 =head1 MODIFICATION HISTORY
1447
1448 See the Changes file.
1449
1450 =head1 COPYRIGHT AND LICENSE
1451
1452 Copyright (c) 1995-2009 Paul Marquess. All rights reserved.
1453
1454 This program is free software; you can redistribute it and/or
1455 modify it under the same terms as Perl itself.
1456