[ Index ]

PHP Cross Reference of Unnamed Project

title

Body

[close]

/se3-unattended/var/se3/unattended/install/linuxaux/opt/perl/lib/5.10.0/i586-linux-thread-multi/Compress/ -> Zlib.pm (source)

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


Generated: Tue Mar 17 22:47:18 2015 Cross-referenced by PHPXref 0.7.1