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