[Summary view] [Print] [Text view]

   1  
   2  package IO::Uncompress::Gunzip ;
   3  
   4  require 5.004 ;
   5  
   6  # for RFC1952
   7  
   8  use strict ;
   9  use warnings;
  10  use bytes;
  11  
  12  use IO::Uncompress::RawInflate 2.008 ;
  13  
  14  use Compress::Raw::Zlib 2.008 qw( crc32 ) ;
  15  use IO::Compress::Base::Common 2.008 qw(:Status createSelfTiedObject);
  16  use IO::Compress::Gzip::Constants 2.008 ;
  17  use IO::Compress::Zlib::Extra 2.008 ;
  18  
  19  require Exporter ;
  20  
  21  our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $GunzipError);
  22  
  23  @ISA = qw( Exporter IO::Uncompress::RawInflate );
  24  @EXPORT_OK = qw( $GunzipError gunzip );
  25  %EXPORT_TAGS = %IO::Uncompress::RawInflate::DEFLATE_CONSTANTS ;
  26  push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
  27  Exporter::export_ok_tags('all');
  28  
  29  $GunzipError = '';
  30  
  31  $VERSION = '2.008';
  32  
  33  sub new
  34  {
  35      my $class = shift ;
  36      $GunzipError = '';
  37      my $obj = createSelfTiedObject($class, \$GunzipError);
  38  
  39      $obj->_create(undef, 0, @_);
  40  }
  41  
  42  sub gunzip
  43  {
  44      my $obj = createSelfTiedObject(undef, \$GunzipError);
  45      return $obj->_inf(@_) ;
  46  }
  47  
  48  sub getExtraParams
  49  {
  50      use IO::Compress::Base::Common  2.008 qw(:Parse);
  51      return ( 'ParseExtra' => [1, 1, Parse_boolean,  0] ) ;
  52  }
  53  
  54  sub ckParams
  55  {
  56      my $self = shift ;
  57      my $got = shift ;
  58  
  59      # gunzip always needs crc32
  60      $got->value('CRC32' => 1);
  61  
  62      return 1;
  63  }
  64  
  65  sub ckMagic
  66  {
  67      my $self = shift;
  68  
  69      my $magic ;
  70      $self->smartReadExact(\$magic, GZIP_ID_SIZE);
  71  
  72      *$self->{HeaderPending} = $magic ;
  73  
  74      return $self->HeaderError("Minimum header size is " . 
  75                                GZIP_MIN_HEADER_SIZE . " bytes") 
  76          if length $magic != GZIP_ID_SIZE ;                                    
  77  
  78      return $self->HeaderError("Bad Magic")
  79          if ! isGzipMagic($magic) ;
  80  
  81      *$self->{Type} = 'rfc1952';
  82  
  83      return $magic ;
  84  }
  85  
  86  sub readHeader
  87  {
  88      my $self = shift;
  89      my $magic = shift;
  90  
  91      return $self->_readGzipHeader($magic);
  92  }
  93  
  94  sub chkTrailer
  95  {
  96      my $self = shift;
  97      my $trailer = shift;
  98  
  99      # Check CRC & ISIZE 
 100      my ($CRC32, $ISIZE) = unpack("V V", $trailer) ;
 101      *$self->{Info}{CRC32} = $CRC32;    
 102      *$self->{Info}{ISIZE} = $ISIZE;    
 103  
 104      if (*$self->{Strict}) {
 105          return $self->TrailerError("CRC mismatch")
 106              if $CRC32 != *$self->{Uncomp}->crc32() ;
 107  
 108          my $exp_isize = *$self->{UnCompSize}->get32bit();
 109          return $self->TrailerError("ISIZE mismatch. Got $ISIZE"
 110                                    . ", expected $exp_isize")
 111              if $ISIZE != $exp_isize ;
 112      }
 113  
 114      return STATUS_OK;
 115  }
 116  
 117  sub isGzipMagic
 118  {
 119      my $buffer = shift ;
 120      return 0 if length $buffer < GZIP_ID_SIZE ;
 121      my ($id1, $id2) = unpack("C C", $buffer) ;
 122      return $id1 == GZIP_ID1 && $id2 == GZIP_ID2 ;
 123  }
 124  
 125  sub _readFullGzipHeader($)
 126  {
 127      my ($self) = @_ ;
 128      my $magic = '' ;
 129  
 130      $self->smartReadExact(\$magic, GZIP_ID_SIZE);
 131  
 132      *$self->{HeaderPending} = $magic ;
 133  
 134      return $self->HeaderError("Minimum header size is " . 
 135                                GZIP_MIN_HEADER_SIZE . " bytes") 
 136          if length $magic != GZIP_ID_SIZE ;                                    
 137  
 138  
 139      return $self->HeaderError("Bad Magic")
 140          if ! isGzipMagic($magic) ;
 141  
 142      my $status = $self->_readGzipHeader($magic);
 143      delete *$self->{Transparent} if ! defined $status ;
 144      return $status ;
 145  }
 146  
 147  sub _readGzipHeader($)
 148  {
 149      my ($self, $magic) = @_ ;
 150      my ($HeaderCRC) ;
 151      my ($buffer) = '' ;
 152  
 153      $self->smartReadExact(\$buffer, GZIP_MIN_HEADER_SIZE - GZIP_ID_SIZE)
 154          or return $self->HeaderError("Minimum header size is " . 
 155                                       GZIP_MIN_HEADER_SIZE . " bytes") ;
 156  
 157      my $keep = $magic . $buffer ;
 158      *$self->{HeaderPending} = $keep ;
 159  
 160      # now split out the various parts
 161      my ($cm, $flag, $mtime, $xfl, $os) = unpack("C C V C C", $buffer) ;
 162  
 163      $cm == GZIP_CM_DEFLATED 
 164          or return $self->HeaderError("Not Deflate (CM is $cm)") ;
 165  
 166      # check for use of reserved bits
 167      return $self->HeaderError("Use of Reserved Bits in FLG field.")
 168          if $flag & GZIP_FLG_RESERVED ; 
 169  
 170      my $EXTRA ;
 171      my @EXTRA = () ;
 172      if ($flag & GZIP_FLG_FEXTRA) {
 173          $EXTRA = "" ;
 174          $self->smartReadExact(\$buffer, GZIP_FEXTRA_HEADER_SIZE) 
 175              or return $self->TruncatedHeader("FEXTRA Length") ;
 176  
 177          my ($XLEN) = unpack("v", $buffer) ;
 178          $self->smartReadExact(\$EXTRA, $XLEN) 
 179              or return $self->TruncatedHeader("FEXTRA Body");
 180          $keep .= $buffer . $EXTRA ;
 181  
 182          if ($XLEN && *$self->{'ParseExtra'}) {
 183              my $bad = IO::Compress::Zlib::Extra::parseRawExtra($EXTRA,
 184                                                  \@EXTRA, 1, 1);
 185              return $self->HeaderError($bad)
 186                  if defined $bad;
 187          }
 188      }
 189  
 190      my $origname ;
 191      if ($flag & GZIP_FLG_FNAME) {
 192          $origname = "" ;
 193          while (1) {
 194              $self->smartReadExact(\$buffer, 1) 
 195                  or return $self->TruncatedHeader("FNAME");
 196              last if $buffer eq GZIP_NULL_BYTE ;
 197              $origname .= $buffer 
 198          }
 199          $keep .= $origname . GZIP_NULL_BYTE ;
 200  
 201          return $self->HeaderError("Non ISO 8859-1 Character found in Name")
 202              if *$self->{Strict} && $origname =~ /$GZIP_FNAME_INVALID_CHAR_RE/o ;
 203      }
 204  
 205      my $comment ;
 206      if ($flag & GZIP_FLG_FCOMMENT) {
 207          $comment = "";
 208          while (1) {
 209              $self->smartReadExact(\$buffer, 1) 
 210                  or return $self->TruncatedHeader("FCOMMENT");
 211              last if $buffer eq GZIP_NULL_BYTE ;
 212              $comment .= $buffer 
 213          }
 214          $keep .= $comment . GZIP_NULL_BYTE ;
 215  
 216          return $self->HeaderError("Non ISO 8859-1 Character found in Comment")
 217              if *$self->{Strict} && $comment =~ /$GZIP_FCOMMENT_INVALID_CHAR_RE/o ;
 218      }
 219  
 220      if ($flag & GZIP_FLG_FHCRC) {
 221          $self->smartReadExact(\$buffer, GZIP_FHCRC_SIZE) 
 222              or return $self->TruncatedHeader("FHCRC");
 223  
 224          $HeaderCRC = unpack("v", $buffer) ;
 225          my $crc16 = crc32($keep) & 0xFF ;
 226  
 227          return $self->HeaderError("CRC16 mismatch.")
 228              if *$self->{Strict} && $crc16 != $HeaderCRC;
 229  
 230          $keep .= $buffer ;
 231      }
 232  
 233      # Assume compression method is deflated for xfl tests
 234      #if ($xfl) {
 235      #}
 236  
 237      *$self->{Type} = 'rfc1952';
 238  
 239      return {
 240          'Type'          => 'rfc1952',
 241          'FingerprintLength'  => 2,
 242          'HeaderLength'  => length $keep,
 243          'TrailerLength' => GZIP_TRAILER_SIZE,
 244          'Header'        => $keep,
 245          'isMinimalHeader' => $keep eq GZIP_MINIMUM_HEADER ? 1 : 0,
 246  
 247          'MethodID'      => $cm,
 248          'MethodName'    => $cm == GZIP_CM_DEFLATED ? "Deflated" : "Unknown" ,
 249          'TextFlag'      => $flag & GZIP_FLG_FTEXT ? 1 : 0,
 250          'HeaderCRCFlag' => $flag & GZIP_FLG_FHCRC ? 1 : 0,
 251          'NameFlag'      => $flag & GZIP_FLG_FNAME ? 1 : 0,
 252          'CommentFlag'   => $flag & GZIP_FLG_FCOMMENT ? 1 : 0,
 253          'ExtraFlag'     => $flag & GZIP_FLG_FEXTRA ? 1 : 0,
 254          'Name'          => $origname,
 255          'Comment'       => $comment,
 256          'Time'          => $mtime,
 257          'OsID'          => $os,
 258          'OsName'        => defined $GZIP_OS_Names{$os} 
 259                                   ? $GZIP_OS_Names{$os} : "Unknown",
 260          'HeaderCRC'     => $HeaderCRC,
 261          'Flags'         => $flag,
 262          'ExtraFlags'    => $xfl,
 263          'ExtraFieldRaw' => $EXTRA,
 264          'ExtraField'    => [ @EXTRA ],
 265  
 266  
 267          #'CompSize'=> $compsize,
 268          #'CRC32'=> $CRC32,
 269          #'OrigSize'=> $ISIZE,
 270        }
 271  }
 272  
 273  
 274  1;
 275  
 276  __END__
 277  
 278  
 279  =head1 NAME
 280  
 281  
 282  
 283  IO::Uncompress::Gunzip - Read RFC 1952 files/buffers
 284  
 285  
 286  
 287  =head1 SYNOPSIS
 288  
 289      use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
 290  
 291      my $status = gunzip $input => $output [,OPTS]
 292          or die "gunzip failed: $GunzipError\n";
 293  
 294      my $z = new IO::Uncompress::Gunzip $input [OPTS] 
 295          or die "gunzip failed: $GunzipError\n";
 296  
 297      $status = $z->read($buffer)
 298      $status = $z->read($buffer, $length)
 299      $status = $z->read($buffer, $length, $offset)
 300      $line = $z->getline()
 301      $char = $z->getc()
 302      $char = $z->ungetc()
 303      $char = $z->opened()
 304  
 305      $status = $z->inflateSync()
 306  
 307      $data = $z->trailingData()
 308      $status = $z->nextStream()
 309      $data = $z->getHeaderInfo()
 310      $z->tell()
 311      $z->seek($position, $whence)
 312      $z->binmode()
 313      $z->fileno()
 314      $z->eof()
 315      $z->close()
 316  
 317      $GunzipError ;
 318  
 319      # IO::File mode
 320  
 321      <$z>
 322      read($z, $buffer);
 323      read($z, $buffer, $length);
 324      read($z, $buffer, $length, $offset);
 325      tell($z)
 326      seek($z, $position, $whence)
 327      binmode($z)
 328      fileno($z)
 329      eof($z)
 330      close($z)
 331  
 332  
 333  =head1 DESCRIPTION
 334  
 335  
 336  
 337  This module provides a Perl interface that allows the reading of
 338  files/buffers that conform to RFC 1952.
 339  
 340  For writing RFC 1952 files/buffers, see the companion module IO::Compress::Gzip.
 341  
 342  
 343  
 344  
 345  
 346  =head1 Functional Interface
 347  
 348  A top-level function, C<gunzip>, is provided to carry out
 349  "one-shot" uncompression between buffers and/or files. For finer
 350  control over the uncompression process, see the L</"OO Interface">
 351  section.
 352  
 353      use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
 354  
 355      gunzip $input => $output [,OPTS] 
 356          or die "gunzip failed: $GunzipError\n";
 357  
 358  
 359  
 360  The functional interface needs Perl5.005 or better.
 361  
 362  
 363  =head2 gunzip $input => $output [, OPTS]
 364  
 365  
 366  C<gunzip> expects at least two parameters, C<$input> and C<$output>.
 367  
 368  =head3 The C<$input> parameter
 369  
 370  The parameter, C<$input>, is used to define the source of
 371  the compressed data. 
 372  
 373  It can take one of the following forms:
 374  
 375  =over 5
 376  
 377  =item A filename
 378  
 379  If the C<$input> parameter is a simple scalar, it is assumed to be a
 380  filename. This file will be opened for reading and the input data
 381  will be read from it.
 382  
 383  =item A filehandle
 384  
 385  If the C<$input> parameter is a filehandle, the input data will be
 386  read from it.
 387  The string '-' can be used as an alias for standard input.
 388  
 389  =item A scalar reference 
 390  
 391  If C<$input> is a scalar reference, the input data will be read
 392  from C<$$input>.
 393  
 394  =item An array reference 
 395  
 396  If C<$input> is an array reference, each element in the array must be a
 397  filename.
 398  
 399  The input data will be read from each file in turn. 
 400  
 401  The complete array will be walked to ensure that it only
 402  contains valid filenames before any data is uncompressed.
 403  
 404  
 405  
 406  =item An Input FileGlob string
 407  
 408  If C<$input> is a string that is delimited by the characters "<" and ">"
 409  C<gunzip> will assume that it is an I<input fileglob string>. The
 410  input is the list of files that match the fileglob.
 411  
 412  If the fileglob does not match any files ...
 413  
 414  See L<File::GlobMapper|File::GlobMapper> for more details.
 415  
 416  
 417  =back
 418  
 419  If the C<$input> parameter is any other type, C<undef> will be returned.
 420  
 421  
 422  
 423  =head3 The C<$output> parameter
 424  
 425  The parameter C<$output> is used to control the destination of the
 426  uncompressed data. This parameter can take one of these forms.
 427  
 428  =over 5
 429  
 430  =item A filename
 431  
 432  If the C<$output> parameter is a simple scalar, it is assumed to be a
 433  filename.  This file will be opened for writing and the uncompressed
 434  data will be written to it.
 435  
 436  =item A filehandle
 437  
 438  If the C<$output> parameter is a filehandle, the uncompressed data
 439  will be written to it.
 440  The string '-' can be used as an alias for standard output.
 441  
 442  
 443  =item A scalar reference 
 444  
 445  If C<$output> is a scalar reference, the uncompressed data will be
 446  stored in C<$$output>.
 447  
 448  
 449  
 450  =item An Array Reference
 451  
 452  If C<$output> is an array reference, the uncompressed data will be
 453  pushed onto the array.
 454  
 455  =item An Output FileGlob
 456  
 457  If C<$output> is a string that is delimited by the characters "<" and ">"
 458  C<gunzip> will assume that it is an I<output fileglob string>. The
 459  output is the list of files that match the fileglob.
 460  
 461  When C<$output> is an fileglob string, C<$input> must also be a fileglob
 462  string. Anything else is an error.
 463  
 464  =back
 465  
 466  If the C<$output> parameter is any other type, C<undef> will be returned.
 467  
 468  
 469  
 470  =head2 Notes
 471  
 472  
 473  When C<$input> maps to multiple compressed files/buffers and C<$output> is
 474  a single file/buffer, after uncompression C<$output> will contain a
 475  concatenation of all the uncompressed data from each of the input
 476  files/buffers.
 477  
 478  
 479  
 480  
 481  
 482  =head2 Optional Parameters
 483  
 484  Unless specified below, the optional parameters for C<gunzip>,
 485  C<OPTS>, are the same as those used with the OO interface defined in the
 486  L</"Constructor Options"> section below.
 487  
 488  =over 5
 489  
 490  =item C<< AutoClose => 0|1 >>
 491  
 492  This option applies to any input or output data streams to 
 493  C<gunzip> that are filehandles.
 494  
 495  If C<AutoClose> is specified, and the value is true, it will result in all
 496  input and/or output filehandles being closed once C<gunzip> has
 497  completed.
 498  
 499  This parameter defaults to 0.
 500  
 501  
 502  =item C<< BinModeOut => 0|1 >>
 503  
 504  When writing to a file or filehandle, set C<binmode> before writing to the
 505  file.
 506  
 507  Defaults to 0.
 508  
 509  
 510  
 511  
 512  
 513  =item C<< Append => 0|1 >>
 514  
 515  TODO
 516  
 517  =item C<< MultiStream => 0|1 >>
 518  
 519  
 520  If the input file/buffer contains multiple compressed data streams, this
 521  option will uncompress the whole lot as a single data stream.
 522  
 523  Defaults to 0.
 524  
 525  
 526  
 527  
 528  
 529  =item C<< TrailingData => $scalar >>
 530  
 531  Returns the data, if any, that is present immediately after the compressed
 532  data stream once uncompression is complete. 
 533  
 534  This option can be used when there is useful information immediately
 535  following the compressed data stream, and you don't know the length of the
 536  compressed data stream.
 537  
 538  If the input is a buffer, C<trailingData> will return everything from the
 539  end of the compressed data stream to the end of the buffer.
 540  
 541  If the input is a filehandle, C<trailingData> will return the data that is
 542  left in the filehandle input buffer once the end of the compressed data
 543  stream has been reached. You can then use the filehandle to read the rest
 544  of the input file. 
 545  
 546  Don't bother using C<trailingData> if the input is a filename.
 547  
 548  
 549  
 550  If you know the length of the compressed data stream before you start
 551  uncompressing, you can avoid having to use C<trailingData> by setting the
 552  C<InputLength> option.
 553  
 554  
 555  
 556  =back
 557  
 558  
 559  
 560  
 561  =head2 Examples
 562  
 563  To read the contents of the file C<file1.txt.gz> and write the
 564  compressed data to the file C<file1.txt>.
 565  
 566      use strict ;
 567      use warnings ;
 568      use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
 569  
 570      my $input = "file1.txt.gz";
 571      my $output = "file1.txt";
 572      gunzip $input => $output
 573          or die "gunzip failed: $GunzipError\n";
 574  
 575  
 576  To read from an existing Perl filehandle, C<$input>, and write the
 577  uncompressed data to a buffer, C<$buffer>.
 578  
 579      use strict ;
 580      use warnings ;
 581      use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
 582      use IO::File ;
 583  
 584      my $input = new IO::File "<file1.txt.gz"
 585          or die "Cannot open 'file1.txt.gz': $!\n" ;
 586      my $buffer ;
 587      gunzip $input => \$buffer 
 588          or die "gunzip failed: $GunzipError\n";
 589  
 590  To uncompress all files in the directory "/my/home" that match "*.txt.gz" and store the compressed data in the same directory
 591  
 592      use strict ;
 593      use warnings ;
 594      use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
 595  
 596      gunzip '</my/home/*.txt.gz>' => '</my/home/#1.txt>'
 597          or die "gunzip failed: $GunzipError\n";
 598  
 599  and if you want to compress each file one at a time, this will do the trick
 600  
 601      use strict ;
 602      use warnings ;
 603      use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
 604  
 605      for my $input ( glob "/my/home/*.txt.gz" )
 606      {
 607          my $output = $input;
 608          $output =~ s/.gz// ;
 609          gunzip $input => $output 
 610              or die "Error compressing '$input': $GunzipError\n";
 611      }
 612  
 613  =head1 OO Interface
 614  
 615  =head2 Constructor
 616  
 617  The format of the constructor for IO::Uncompress::Gunzip is shown below
 618  
 619  
 620      my $z = new IO::Uncompress::Gunzip $input [OPTS]
 621          or die "IO::Uncompress::Gunzip failed: $GunzipError\n";
 622  
 623  Returns an C<IO::Uncompress::Gunzip> object on success and undef on failure.
 624  The variable C<$GunzipError> will contain an error message on failure.
 625  
 626  If you are running Perl 5.005 or better the object, C<$z>, returned from
 627  IO::Uncompress::Gunzip can be used exactly like an L<IO::File|IO::File> filehandle.
 628  This means that all normal input file operations can be carried out with
 629  C<$z>.  For example, to read a line from a compressed file/buffer you can
 630  use either of these forms
 631  
 632      $line = $z->getline();
 633      $line = <$z>;
 634  
 635  The mandatory parameter C<$input> is used to determine the source of the
 636  compressed data. This parameter can take one of three forms.
 637  
 638  =over 5
 639  
 640  =item A filename
 641  
 642  If the C<$input> parameter is a scalar, it is assumed to be a filename. This
 643  file will be opened for reading and the compressed data will be read from it.
 644  
 645  =item A filehandle
 646  
 647  If the C<$input> parameter is a filehandle, the compressed data will be
 648  read from it.
 649  The string '-' can be used as an alias for standard input.
 650  
 651  
 652  =item A scalar reference 
 653  
 654  If C<$input> is a scalar reference, the compressed data will be read from
 655  C<$$output>.
 656  
 657  =back
 658  
 659  =head2 Constructor Options
 660  
 661  
 662  The option names defined below are case insensitive and can be optionally
 663  prefixed by a '-'.  So all of the following are valid
 664  
 665      -AutoClose
 666      -autoclose
 667      AUTOCLOSE
 668      autoclose
 669  
 670  OPTS is a combination of the following options:
 671  
 672  =over 5
 673  
 674  =item C<< AutoClose => 0|1 >>
 675  
 676  This option is only valid when the C<$input> parameter is a filehandle. If
 677  specified, and the value is true, it will result in the file being closed once
 678  either the C<close> method is called or the IO::Uncompress::Gunzip object is
 679  destroyed.
 680  
 681  This parameter defaults to 0.
 682  
 683  =item C<< MultiStream => 0|1 >>
 684  
 685  
 686  
 687  Allows multiple concatenated compressed streams to be treated as a single
 688  compressed stream. Decompression will stop once either the end of the
 689  file/buffer is reached, an error is encountered (premature eof, corrupt
 690  compressed data) or the end of a stream is not immediately followed by the
 691  start of another stream.
 692  
 693  This parameter defaults to 0.
 694  
 695  
 696  =item C<< Prime => $string >>
 697  
 698  This option will uncompress the contents of C<$string> before processing the
 699  input file/buffer.
 700  
 701  This option can be useful when the compressed data is embedded in another
 702  file/data structure and it is not possible to work out where the compressed
 703  data begins without having to read the first few bytes. If this is the
 704  case, the uncompression can be I<primed> with these bytes using this
 705  option.
 706  
 707  =item C<< Transparent => 0|1 >>
 708  
 709  If this option is set and the input file/buffer is not compressed data,
 710  the module will allow reading of it anyway.
 711  
 712  In addition, if the input file/buffer does contain compressed data and
 713  there is non-compressed data immediately following it, setting this option
 714  will make this module treat the whole file/bufffer as a single data stream.
 715  
 716  This option defaults to 1.
 717  
 718  =item C<< BlockSize => $num >>
 719  
 720  When reading the compressed input data, IO::Uncompress::Gunzip will read it in
 721  blocks of C<$num> bytes.
 722  
 723  This option defaults to 4096.
 724  
 725  =item C<< InputLength => $size >>
 726  
 727  When present this option will limit the number of compressed bytes read
 728  from the input file/buffer to C<$size>. This option can be used in the
 729  situation where there is useful data directly after the compressed data
 730  stream and you know beforehand the exact length of the compressed data
 731  stream. 
 732  
 733  This option is mostly used when reading from a filehandle, in which case
 734  the file pointer will be left pointing to the first byte directly after the
 735  compressed data stream.
 736  
 737  
 738  
 739  This option defaults to off.
 740  
 741  =item C<< Append => 0|1 >>
 742  
 743  This option controls what the C<read> method does with uncompressed data.
 744  
 745  If set to 1, all uncompressed data will be appended to the output parameter
 746  of the C<read> method.
 747  
 748  If set to 0, the contents of the output parameter of the C<read> method
 749  will be overwritten by the uncompressed data.
 750  
 751  Defaults to 0.
 752  
 753  =item C<< Strict => 0|1 >>
 754  
 755  
 756  
 757  This option controls whether the extra checks defined below are used when
 758  carrying out the decompression. When Strict is on, the extra tests are
 759  carried out, when Strict is off they are not.
 760  
 761  The default for this option is off.
 762  
 763  
 764  
 765  
 766  
 767  
 768  
 769  
 770  
 771  =over 5
 772  
 773  =item 1 
 774  
 775  If the FHCRC bit is set in the gzip FLG header byte, the CRC16 bytes in the
 776  header must match the crc16 value of the gzip header actually read.
 777  
 778  =item 2
 779  
 780  If the gzip header contains a name field (FNAME) it consists solely of ISO
 781  8859-1 characters.
 782  
 783  =item 3
 784  
 785  If the gzip header contains a comment field (FCOMMENT) it consists solely
 786  of ISO 8859-1 characters plus line-feed.
 787  
 788  =item 4
 789  
 790  If the gzip FEXTRA header field is present it must conform to the sub-field
 791  structure as defined in RFC 1952.
 792  
 793  =item 5
 794  
 795  The CRC32 and ISIZE trailer fields must be present.
 796  
 797  =item 6
 798  
 799  The value of the CRC32 field read must match the crc32 value of the
 800  uncompressed data actually contained in the gzip file.
 801  
 802  =item 7
 803  
 804  The value of the ISIZE fields read must match the length of the
 805  uncompressed data actually read from the file.
 806  
 807  =back
 808  
 809  
 810  
 811  
 812  
 813  
 814  
 815  =item C<< ParseExtra => 0|1 >>
 816  If the gzip FEXTRA header field is present and this option is set, it will
 817  force the module to check that it conforms to the sub-field structure as
 818  defined in RFC 1952.
 819  
 820  If the C<Strict> is on it will automatically enable this option.
 821  
 822  Defaults to 0.
 823  
 824  
 825  
 826  
 827  =back
 828  
 829  =head2 Examples
 830  
 831  TODO
 832  
 833  =head1 Methods 
 834  
 835  =head2 read
 836  
 837  Usage is
 838  
 839      $status = $z->read($buffer)
 840  
 841  Reads a block of compressed data (the size the the compressed block is
 842  determined by the C<Buffer> option in the constructor), uncompresses it and
 843  writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
 844  set in the constructor, the uncompressed data will be appended to the
 845  C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
 846  
 847  Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 848  or a negative number on error.
 849  
 850  =head2 read
 851  
 852  Usage is
 853  
 854      $status = $z->read($buffer, $length)
 855      $status = $z->read($buffer, $length, $offset)
 856  
 857      $status = read($z, $buffer, $length)
 858      $status = read($z, $buffer, $length, $offset)
 859  
 860  Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
 861  
 862  The main difference between this form of the C<read> method and the
 863  previous one, is that this one will attempt to return I<exactly> C<$length>
 864  bytes. The only circumstances that this function will not is if end-of-file
 865  or an IO error is encountered.
 866  
 867  Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 868  or a negative number on error.
 869  
 870  
 871  =head2 getline
 872  
 873  Usage is
 874  
 875      $line = $z->getline()
 876      $line = <$z>
 877  
 878  Reads a single line. 
 879  
 880  This method fully supports the use of of the variable C<$/> (or
 881  C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
 882  determine what constitutes an end of line. Paragraph mode, record mode and
 883  file slurp mode are all supported. 
 884  
 885  
 886  =head2 getc
 887  
 888  Usage is 
 889  
 890      $char = $z->getc()
 891  
 892  Read a single character.
 893  
 894  =head2 ungetc
 895  
 896  Usage is
 897  
 898      $char = $z->ungetc($string)
 899  
 900  
 901  
 902  =head2 inflateSync
 903  
 904  Usage is
 905  
 906      $status = $z->inflateSync()
 907  
 908  TODO
 909  
 910  
 911  =head2 getHeaderInfo
 912  
 913  Usage is
 914  
 915      $hdr  = $z->getHeaderInfo();
 916      @hdrs = $z->getHeaderInfo();
 917  
 918  This method returns either a hash reference (in scalar context) or a list
 919  or hash references (in array context) that contains information about each
 920  of the header fields in the compressed data stream(s).
 921  
 922  
 923  
 924  =over 5
 925  
 926  =item Name
 927  
 928  The contents of the Name header field, if present. If no name is
 929  present, the value will be undef. Note this is different from a zero length
 930  name, which will return an empty string.
 931  
 932  =item Comment
 933  
 934  The contents of the Comment header field, if present. If no comment is
 935  present, the value will be undef. Note this is different from a zero length
 936  comment, which will return an empty string.
 937  
 938  =back
 939  
 940  
 941  
 942  
 943  =head2 tell
 944  
 945  Usage is
 946  
 947      $z->tell()
 948      tell $z
 949  
 950  Returns the uncompressed file offset.
 951  
 952  =head2 eof
 953  
 954  Usage is
 955  
 956      $z->eof();
 957      eof($z);
 958  
 959  
 960  
 961  Returns true if the end of the compressed input stream has been reached.
 962  
 963  
 964  
 965  =head2 seek
 966  
 967      $z->seek($position, $whence);
 968      seek($z, $position, $whence);
 969  
 970  
 971  
 972  
 973  Provides a sub-set of the C<seek> functionality, with the restriction
 974  that it is only legal to seek forward in the input file/buffer.
 975  It is a fatal error to attempt to seek backward.
 976  
 977  
 978  
 979  The C<$whence> parameter takes one the usual values, namely SEEK_SET,
 980  SEEK_CUR or SEEK_END.
 981  
 982  Returns 1 on success, 0 on failure.
 983  
 984  =head2 binmode
 985  
 986  Usage is
 987  
 988      $z->binmode
 989      binmode $z ;
 990  
 991  This is a noop provided for completeness.
 992  
 993  =head2 opened
 994  
 995      $z->opened()
 996  
 997  Returns true if the object currently refers to a opened file/buffer. 
 998  
 999  =head2 autoflush
1000  
1001      my $prev = $z->autoflush()
1002      my $prev = $z->autoflush(EXPR)
1003  
1004  If the C<$z> object is associated with a file or a filehandle, this method
1005  returns the current autoflush setting for the underlying filehandle. If
1006  C<EXPR> is present, and is non-zero, it will enable flushing after every
1007  write/print operation.
1008  
1009  If C<$z> is associated with a buffer, this method has no effect and always
1010  returns C<undef>.
1011  
1012  B<Note> that the special variable C<$|> B<cannot> be used to set or
1013  retrieve the autoflush setting.
1014  
1015  =head2 input_line_number
1016  
1017      $z->input_line_number()
1018      $z->input_line_number(EXPR)
1019  
1020  
1021  
1022  Returns the current uncompressed line number. If C<EXPR> is present it has
1023  the effect of setting the line number. Note that setting the line number
1024  does not change the current position within the file/buffer being read.
1025  
1026  The contents of C<$/> are used to to determine what constitutes a line
1027  terminator.
1028  
1029  
1030  
1031  =head2 fileno
1032  
1033      $z->fileno()
1034      fileno($z)
1035  
1036  If the C<$z> object is associated with a file or a filehandle, this method
1037  will return the underlying file descriptor.
1038  
1039  If the C<$z> object is is associated with a buffer, this method will
1040  return undef.
1041  
1042  =head2 close
1043  
1044      $z->close() ;
1045      close $z ;
1046  
1047  
1048  
1049  Closes the output file/buffer. 
1050  
1051  
1052  
1053  For most versions of Perl this method will be automatically invoked if
1054  the IO::Uncompress::Gunzip object is destroyed (either explicitly or by the
1055  variable with the reference to the object going out of scope). The
1056  exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1057  these cases, the C<close> method will be called automatically, but
1058  not until global destruction of all live objects when the program is
1059  terminating.
1060  
1061  Therefore, if you want your scripts to be able to run on all versions
1062  of Perl, you should call C<close> explicitly and not rely on automatic
1063  closing.
1064  
1065  Returns true on success, otherwise 0.
1066  
1067  If the C<AutoClose> option has been enabled when the IO::Uncompress::Gunzip
1068  object was created, and the object is associated with a file, the
1069  underlying file will also be closed.
1070  
1071  
1072  
1073  
1074  =head2 nextStream
1075  
1076  Usage is
1077  
1078      my $status = $z->nextStream();
1079  
1080  Skips to the next compressed data stream in the input file/buffer. If a new
1081  compressed data stream is found, the eof marker will be cleared and C<$.>
1082  will be reset to 0.
1083  
1084  Returns 1 if a new stream was found, 0 if none was found, and -1 if an
1085  error was encountered.
1086  
1087  =head2 trailingData
1088  
1089  Usage is
1090  
1091      my $data = $z->trailingData();
1092  
1093  Returns the data, if any, that is present immediately after the compressed
1094  data stream once uncompression is complete. It only makes sense to call
1095  this method once the end of the compressed data stream has been
1096  encountered.
1097  
1098  This option can be used when there is useful information immediately
1099  following the compressed data stream, and you don't know the length of the
1100  compressed data stream.
1101  
1102  If the input is a buffer, C<trailingData> will return everything from the
1103  end of the compressed data stream to the end of the buffer.
1104  
1105  If the input is a filehandle, C<trailingData> will return the data that is
1106  left in the filehandle input buffer once the end of the compressed data
1107  stream has been reached. You can then use the filehandle to read the rest
1108  of the input file. 
1109  
1110  Don't bother using C<trailingData> if the input is a filename.
1111  
1112  
1113  
1114  If you know the length of the compressed data stream before you start
1115  uncompressing, you can avoid having to use C<trailingData> by setting the
1116  C<InputLength> option in the constructor.
1117  
1118  =head1 Importing 
1119  
1120  No symbolic constants are required by this IO::Uncompress::Gunzip at present. 
1121  
1122  =over 5
1123  
1124  =item :all
1125  
1126  Imports C<gunzip> and C<$GunzipError>.
1127  Same as doing this
1128  
1129      use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
1130  
1131  =back
1132  
1133  =head1 EXAMPLES
1134  
1135  
1136  
1137  
1138  =head1 SEE ALSO
1139  
1140  L<Compress::Zlib>, L<IO::Compress::Gzip>, 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>
1141  
1142  L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1143  
1144  L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1145  L<Archive::Tar|Archive::Tar>,
1146  L<IO::Zlib|IO::Zlib>
1147  
1148  
1149  For RFC 1950, 1951 and 1952 see 
1150  F<http://www.faqs.org/rfcs/rfc1950.html>,
1151  F<http://www.faqs.org/rfcs/rfc1951.html> and
1152  F<http://www.faqs.org/rfcs/rfc1952.html>
1153  
1154  The I<zlib> compression library was written by Jean-loup Gailly
1155  F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1156  
1157  The primary site for the I<zlib> compression library is
1158  F<http://www.zlib.org>.
1159  
1160  The primary site for gzip is F<http://www.gzip.org>.
1161  
1162  
1163  
1164  
1165  =head1 AUTHOR
1166  
1167  This module was written by Paul Marquess, F<pmqs@cpan.org>. 
1168  
1169  
1170  
1171  =head1 MODIFICATION HISTORY
1172  
1173  See the Changes file.
1174  
1175  =head1 COPYRIGHT AND LICENSE
1176  
1177  Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1178  
1179  This program is free software; you can redistribute it and/or
1180  modify it under the same terms as Perl itself.
1181