cpan/IO-Compress/lib/IO/Uncompress/Gunzip.pm

   1
   2 package IO::Uncompress::Gunzip ;
   3
   4 require 5.006 ;
   5
   6 # for RFC1952
   7
   8 use strict ;
   9 use warnings;
  10 use bytes;
  11
  12 use IO::Uncompress::RawInflate 2.048 ;
  13
  14 use Compress::Raw::Zlib 2.048 () ;
  15 use IO::Compress::Base::Common 2.048 qw(:Status createSelfTiedObject);
  16 use IO::Compress::Gzip::Constants 2.048 ;
  17 use IO::Compress::Zlib::Extra 2.048 ;
  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.048';
  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.048 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 = Compress::Raw::Zlib::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 IO::Uncompress::Gunzip - Read RFC 1952 files/buffers
 282
 283 =head1 SYNOPSIS
 284
 285     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
 286
 287     my $status = gunzip $input => $output [,OPTS]
 288         or die "gunzip failed: $GunzipError\n";
 289
 290     my $z = new IO::Uncompress::Gunzip $input [OPTS]
 291         or die "gunzip failed: $GunzipError\n";
 292
 293     $status = $z->read($buffer)
 294     $status = $z->read($buffer, $length)
 295     $status = $z->read($buffer, $length, $offset)
 296     $line = $z->getline()
 297     $char = $z->getc()
 298     $char = $z->ungetc()
 299     $char = $z->opened()
 300
 301     $status = $z->inflateSync()
 302
 303     $data = $z->trailingData()
 304     $status = $z->nextStream()
 305     $data = $z->getHeaderInfo()
 306     $z->tell()
 307     $z->seek($position, $whence)
 308     $z->binmode()
 309     $z->fileno()
 310     $z->eof()
 311     $z->close()
 312
 313     $GunzipError ;
 314
 315     # IO::File mode
 316
 317     <$z>
 318     read($z, $buffer);
 319     read($z, $buffer, $length);
 320     read($z, $buffer, $length, $offset);
 321     tell($z)
 322     seek($z, $position, $whence)
 323     binmode($z)
 324     fileno($z)
 325     eof($z)
 326     close($z)
 327
 328 =head1 DESCRIPTION
 329
 330 This module provides a Perl interface that allows the reading of
 331 files/buffers that conform to RFC 1952.
 332
 333 For writing RFC 1952 files/buffers, see the companion module IO::Compress::Gzip.
 334
 335 =head1 Functional Interface
 336
 337 A top-level function, C<gunzip>, is provided to carry out
 338 "one-shot" uncompression between buffers and/or files. For finer
 339 control over the uncompression process, see the L</"OO Interface">
 340 section.
 341
 342     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
 343
 344     gunzip $input => $output [,OPTS]
 345         or die "gunzip failed: $GunzipError\n";
 346
 347 The functional interface needs Perl5.005 or better.
 348
 349 =head2 gunzip $input => $output [, OPTS]
 350
 351 C<gunzip> expects at least two parameters, C<$input> and C<$output>.
 352
 353 =head3 The C<$input> parameter
 354
 355 The parameter, C<$input>, is used to define the source of
 356 the compressed data.
 357
 358 It can take one of the following forms:
 359
 360 =over 5
 361
 362 =item A filename
 363
 364 If the C<$input> parameter is a simple scalar, it is assumed to be a
 365 filename. This file will be opened for reading and the input data
 366 will be read from it.
 367
 368 =item A filehandle
 369
 370 If the C<$input> parameter is a filehandle, the input data will be
 371 read from it.
 372 The string '-' can be used as an alias for standard input.
 373
 374 =item A scalar reference
 375
 376 If C<$input> is a scalar reference, the input data will be read
 377 from C<$$input>.
 378
 379 =item An array reference
 380
 381 If C<$input> is an array reference, each element in the array must be a
 382 filename.
 383
 384 The input data will be read from each file in turn.
 385
 386 The complete array will be walked to ensure that it only
 387 contains valid filenames before any data is uncompressed.
 388
 389 =item An Input FileGlob string
 390
 391 If C<$input> is a string that is delimited by the characters "<" and ">"
 392 C<gunzip> will assume that it is an I<input fileglob string>. The
 393 input is the list of files that match the fileglob.
 394
 395 See L<File::GlobMapper|File::GlobMapper> for more details.
 396
 397 =back
 398
 399 If the C<$input> parameter is any other type, C<undef> will be returned.
 400
 401 =head3 The C<$output> parameter
 402
 403 The parameter C<$output> is used to control the destination of the
 404 uncompressed data. This parameter can take one of these forms.
 405
 406 =over 5
 407
 408 =item A filename
 409
 410 If the C<$output> parameter is a simple scalar, it is assumed to be a
 411 filename.  This file will be opened for writing and the uncompressed
 412 data will be written to it.
 413
 414 =item A filehandle
 415
 416 If the C<$output> parameter is a filehandle, the uncompressed data
 417 will be written to it.
 418 The string '-' can be used as an alias for standard output.
 419
 420 =item A scalar reference
 421
 422 If C<$output> is a scalar reference, the uncompressed data will be
 423 stored in C<$$output>.
 424
 425 =item An Array Reference
 426
 427 If C<$output> is an array reference, the uncompressed data will be
 428 pushed onto the array.
 429
 430 =item An Output FileGlob
 431
 432 If C<$output> is a string that is delimited by the characters "<" and ">"
 433 C<gunzip> will assume that it is an I<output fileglob string>. The
 434 output is the list of files that match the fileglob.
 435
 436 When C<$output> is an fileglob string, C<$input> must also be a fileglob
 437 string. Anything else is an error.
 438
 439 See L<File::GlobMapper|File::GlobMapper> for more details.
 440
 441 =back
 442
 443 If the C<$output> parameter is any other type, C<undef> will be returned.
 444
 445 =head2 Notes
 446
 447 When C<$input> maps to multiple compressed files/buffers and C<$output> is
 448 a single file/buffer, after uncompression C<$output> will contain a
 449 concatenation of all the uncompressed data from each of the input
 450 files/buffers.
 451
 452 =head2 Optional Parameters
 453
 454 Unless specified below, the optional parameters for C<gunzip>,
 455 C<OPTS>, are the same as those used with the OO interface defined in the
 456 L</"Constructor Options"> section below.
 457
 458 =over 5
 459
 460 =item C<< AutoClose => 0|1 >>
 461
 462 This option applies to any input or output data streams to
 463 C<gunzip> that are filehandles.
 464
 465 If C<AutoClose> is specified, and the value is true, it will result in all
 466 input and/or output filehandles being closed once C<gunzip> has
 467 completed.
 468
 469 This parameter defaults to 0.
 470
 471 =item C<< BinModeOut => 0|1 >>
 472
 473 When writing to a file or filehandle, set C<binmode> before writing to the
 474 file.
 475
 476 Defaults to 0.
 477
 478 =item C<< Append => 0|1 >>
 479
 480 The behaviour of this option is dependent on the type of output data
 481 stream.
 482
 483 =over 5
 484
 485 =item * A Buffer
 486
 487 If C<Append> is enabled, all uncompressed data will be append to the end of
 488 the output buffer. Otherwise the output buffer will be cleared before any
 489 uncompressed data is written to it.
 490
 491 =item * A Filename
 492
 493 If C<Append> is enabled, the file will be opened in append mode. Otherwise
 494 the contents of the file, if any, will be truncated before any uncompressed
 495 data is written to it.
 496
 497 =item * A Filehandle
 498
 499 If C<Append> is enabled, the filehandle will be positioned to the end of
 500 the file via a call to C<seek> before any uncompressed data is
 501 written to it.  Otherwise the file pointer will not be moved.
 502
 503 =back
 504
 505 When C<Append> is specified, and set to true, it will I<append> all uncompressed
 506 data to the output data stream.
 507
 508 So when the output is a filehandle it will carry out a seek to the eof
 509 before writing any uncompressed data. If the output is a filename, it will be opened for
 510 appending. If the output is a buffer, all uncompressed data will be
 511 appended to the existing buffer.
 512
 513 Conversely when C<Append> is not specified, or it is present and is set to
 514 false, it will operate as follows.
 515
 516 When the output is a filename, it will truncate the contents of the file
 517 before writing any uncompressed data. If the output is a filehandle
 518 its position will not be changed. If the output is a buffer, it will be
 519 wiped before any uncompressed data is output.
 520
 521 Defaults to 0.
 522
 523 =item C<< MultiStream => 0|1 >>
 524
 525 If the input file/buffer contains multiple compressed data streams, this
 526 option will uncompress the whole lot as a single data stream.
 527
 528 Defaults to 0.
 529
 530 =item C<< TrailingData => $scalar >>
 531
 532 Returns the data, if any, that is present immediately after the compressed
 533 data stream once uncompression is complete.
 534
 535 This option can be used when there is useful information immediately
 536 following the compressed data stream, and you don't know the length of the
 537 compressed data stream.
 538
 539 If the input is a buffer, C<trailingData> will return everything from the
 540 end of the compressed data stream to the end of the buffer.
 541
 542 If the input is a filehandle, C<trailingData> will return the data that is
 543 left in the filehandle input buffer once the end of the compressed data
 544 stream has been reached. You can then use the filehandle to read the rest
 545 of the input file.
 546
 547 Don't bother using C<trailingData> if the input is a filename.
 548
 549 If you know the length of the compressed data stream before you start
 550 uncompressing, you can avoid having to use C<trailingData> by setting the
 551 C<InputLength> option.
 552
 553 =back
 554
 555 =head2 Examples
 556
 557 To read the contents of the file C<file1.txt.gz> and write the
 558 uncompressed data to the file C<file1.txt>.
 559
 560     use strict ;
 561     use warnings ;
 562     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
 563
 564     my $input = "file1.txt.gz";
 565     my $output = "file1.txt";
 566     gunzip $input => $output
 567         or die "gunzip failed: $GunzipError\n";
 568
 569 To read from an existing Perl filehandle, C<$input>, and write the
 570 uncompressed data to a buffer, C<$buffer>.
 571
 572     use strict ;
 573     use warnings ;
 574     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
 575     use IO::File ;
 576
 577     my $input = new IO::File "<file1.txt.gz"
 578         or die "Cannot open 'file1.txt.gz': $!\n" ;
 579     my $buffer ;
 580     gunzip $input => \$buffer
 581         or die "gunzip failed: $GunzipError\n";
 582
 583 To uncompress all files in the directory "/my/home" that match "*.txt.gz" and store the compressed data in the same directory
 584
 585     use strict ;
 586     use warnings ;
 587     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
 588
 589     gunzip '</my/home/*.txt.gz>' => '</my/home/#1.txt>'
 590         or die "gunzip failed: $GunzipError\n";
 591
 592 and if you want to compress each file one at a time, this will do the trick
 593
 594     use strict ;
 595     use warnings ;
 596     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
 597
 598     for my $input ( glob "/my/home/*.txt.gz" )
 599     {
 600         my $output = $input;
 601         $output =~ s/.gz// ;
 602         gunzip $input => $output
 603             or die "Error compressing '$input': $GunzipError\n";
 604     }
 605
 606 =head1 OO Interface
 607
 608 =head2 Constructor
 609
 610 The format of the constructor for IO::Uncompress::Gunzip is shown below
 611
 612     my $z = new IO::Uncompress::Gunzip $input [OPTS]
 613         or die "IO::Uncompress::Gunzip failed: $GunzipError\n";
 614
 615 Returns an C<IO::Uncompress::Gunzip> object on success and undef on failure.
 616 The variable C<$GunzipError> will contain an error message on failure.
 617
 618 If you are running Perl 5.005 or better the object, C<$z>, returned from
 619 IO::Uncompress::Gunzip can be used exactly like an L<IO::File|IO::File> filehandle.
 620 This means that all normal input file operations can be carried out with
 621 C<$z>.  For example, to read a line from a compressed file/buffer you can
 622 use either of these forms
 623
 624     $line = $z->getline();
 625     $line = <$z>;
 626
 627 The mandatory parameter C<$input> is used to determine the source of the
 628 compressed data. This parameter can take one of three forms.
 629
 630 =over 5
 631
 632 =item A filename
 633
 634 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
 635 file will be opened for reading and the compressed data will be read from it.
 636
 637 =item A filehandle
 638
 639 If the C<$input> parameter is a filehandle, the compressed data will be
 640 read from it.
 641 The string '-' can be used as an alias for standard input.
 642
 643 =item A scalar reference
 644
 645 If C<$input> is a scalar reference, the compressed data will be read from
 646 C<$$output>.
 647
 648 =back
 649
 650 =head2 Constructor Options
 651
 652 The option names defined below are case insensitive and can be optionally
 653 prefixed by a '-'.  So all of the following are valid
 654
 655     -AutoClose
 656     -autoclose
 657     AUTOCLOSE
 658     autoclose
 659
 660 OPTS is a combination of the following options:
 661
 662 =over 5
 663
 664 =item C<< AutoClose => 0|1 >>
 665
 666 This option is only valid when the C<$input> parameter is a filehandle. If
 667 specified, and the value is true, it will result in the file being closed once
 668 either the C<close> method is called or the IO::Uncompress::Gunzip object is
 669 destroyed.
 670
 671 This parameter defaults to 0.
 672
 673 =item C<< MultiStream => 0|1 >>
 674
 675 Allows multiple concatenated compressed streams to be treated as a single
 676 compressed stream. Decompression will stop once either the end of the
 677 file/buffer is reached, an error is encountered (premature eof, corrupt
 678 compressed data) or the end of a stream is not immediately followed by the
 679 start of another stream.
 680
 681 This parameter defaults to 0.
 682
 683 =item C<< Prime => $string >>
 684
 685 This option will uncompress the contents of C<$string> before processing the
 686 input file/buffer.
 687
 688 This option can be useful when the compressed data is embedded in another
 689 file/data structure and it is not possible to work out where the compressed
 690 data begins without having to read the first few bytes. If this is the
 691 case, the uncompression can be I<primed> with these bytes using this
 692 option.
 693
 694 =item C<< Transparent => 0|1 >>
 695
 696 If this option is set and the input file/buffer is not compressed data,
 697 the module will allow reading of it anyway.
 698
 699 In addition, if the input file/buffer does contain compressed data and
 700 there is non-compressed data immediately following it, setting this option
 701 will make this module treat the whole file/buffer as a single data stream.
 702
 703 This option defaults to 1.
 704
 705 =item C<< BlockSize => $num >>
 706
 707 When reading the compressed input data, IO::Uncompress::Gunzip will read it in
 708 blocks of C<$num> bytes.
 709
 710 This option defaults to 4096.
 711
 712 =item C<< InputLength => $size >>
 713
 714 When present this option will limit the number of compressed bytes read
 715 from the input file/buffer to C<$size>. This option can be used in the
 716 situation where there is useful data directly after the compressed data
 717 stream and you know beforehand the exact length of the compressed data
 718 stream.
 719
 720 This option is mostly used when reading from a filehandle, in which case
 721 the file pointer will be left pointing to the first byte directly after the
 722 compressed data stream.
 723
 724 This option defaults to off.
 725
 726 =item C<< Append => 0|1 >>
 727
 728 This option controls what the C<read> method does with uncompressed data.
 729
 730 If set to 1, all uncompressed data will be appended to the output parameter
 731 of the C<read> method.
 732
 733 If set to 0, the contents of the output parameter of the C<read> method
 734 will be overwritten by the uncompressed data.
 735
 736 Defaults to 0.
 737
 738 =item C<< Strict => 0|1 >>
 739
 740 This option controls whether the extra checks defined below are used when
 741 carrying out the decompression. When Strict is on, the extra tests are
 742 carried out, when Strict is off they are not.
 743
 744 The default for this option is off.
 745
 746 =over 5
 747
 748 =item 1
 749
 750 If the FHCRC bit is set in the gzip FLG header byte, the CRC16 bytes in the
 751 header must match the crc16 value of the gzip header actually read.
 752
 753 =item 2
 754
 755 If the gzip header contains a name field (FNAME) it consists solely of ISO
 756 8859-1 characters.
 757
 758 =item 3
 759
 760 If the gzip header contains a comment field (FCOMMENT) it consists solely
 761 of ISO 8859-1 characters plus line-feed.
 762
 763 =item 4
 764
 765 If the gzip FEXTRA header field is present it must conform to the sub-field
 766 structure as defined in RFC 1952.
 767
 768 =item 5
 769
 770 The CRC32 and ISIZE trailer fields must be present.
 771
 772 =item 6
 773
 774 The value of the CRC32 field read must match the crc32 value of the
 775 uncompressed data actually contained in the gzip file.
 776
 777 =item 7
 778
 779 The value of the ISIZE fields read must match the length of the
 780 uncompressed data actually read from the file.
 781
 782 =back
 783
 784 =item C<< ParseExtra => 0|1 >>
 785 If the gzip FEXTRA header field is present and this option is set, it will
 786 force the module to check that it conforms to the sub-field structure as
 787 defined in RFC 1952.
 788
 789 If the C<Strict> is on it will automatically enable this option.
 790
 791 Defaults to 0.
 792
 793 =back
 794
 795 =head2 Examples
 796
 797 TODO
 798
 799 =head1 Methods
 800
 801 =head2 read
 802
 803 Usage is
 804
 805     $status = $z->read($buffer)
 806
 807 Reads a block of compressed data (the size the the compressed block is
 808 determined by the C<Buffer> option in the constructor), uncompresses it and
 809 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
 810 set in the constructor, the uncompressed data will be appended to the
 811 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
 812
 813 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 814 or a negative number on error.
 815
 816 =head2 read
 817
 818 Usage is
 819
 820     $status = $z->read($buffer, $length)
 821     $status = $z->read($buffer, $length, $offset)
 822
 823     $status = read($z, $buffer, $length)
 824     $status = read($z, $buffer, $length, $offset)
 825
 826 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
 827
 828 The main difference between this form of the C<read> method and the
 829 previous one, is that this one will attempt to return I<exactly> C<$length>
 830 bytes. The only circumstances that this function will not is if end-of-file
 831 or an IO error is encountered.
 832
 833 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 834 or a negative number on error.
 835
 836 =head2 getline
 837
 838 Usage is
 839
 840     $line = $z->getline()
 841     $line = <$z>
 842
 843 Reads a single line.
 844
 845 This method fully supports the use of of the variable C<$/> (or
 846 C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
 847 determine what constitutes an end of line. Paragraph mode, record mode and
 848 file slurp mode are all supported.
 849
 850 =head2 getc
 851
 852 Usage is
 853
 854     $char = $z->getc()
 855
 856 Read a single character.
 857
 858 =head2 ungetc
 859
 860 Usage is
 861
 862     $char = $z->ungetc($string)
 863
 864 =head2 inflateSync
 865
 866 Usage is
 867
 868     $status = $z->inflateSync()
 869
 870 TODO
 871
 872 =head2 getHeaderInfo
 873
 874 Usage is
 875
 876     $hdr  = $z->getHeaderInfo();
 877     @hdrs = $z->getHeaderInfo();
 878
 879 This method returns either a hash reference (in scalar context) or a list
 880 or hash references (in array context) that contains information about each
 881 of the header fields in the compressed data stream(s).
 882
 883 =over 5
 884
 885 =item Name
 886
 887 The contents of the Name header field, if present. If no name is
 888 present, the value will be undef. Note this is different from a zero length
 889 name, which will return an empty string.
 890
 891 =item Comment
 892
 893 The contents of the Comment header field, if present. If no comment is
 894 present, the value will be undef. Note this is different from a zero length
 895 comment, which will return an empty string.
 896
 897 =back
 898
 899 =head2 tell
 900
 901 Usage is
 902
 903     $z->tell()
 904     tell $z
 905
 906 Returns the uncompressed file offset.
 907
 908 =head2 eof
 909
 910 Usage is
 911
 912     $z->eof();
 913     eof($z);
 914
 915 Returns true if the end of the compressed input stream has been reached.
 916
 917 =head2 seek
 918
 919     $z->seek($position, $whence);
 920     seek($z, $position, $whence);
 921
 922 Provides a sub-set of the C<seek> functionality, with the restriction
 923 that it is only legal to seek forward in the input file/buffer.
 924 It is a fatal error to attempt to seek backward.
 925
 926 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
 927 SEEK_CUR or SEEK_END.
 928
 929 Returns 1 on success, 0 on failure.
 930
 931 =head2 binmode
 932
 933 Usage is
 934
 935     $z->binmode
 936     binmode $z ;
 937
 938 This is a noop provided for completeness.
 939
 940 =head2 opened
 941
 942     $z->opened()
 943
 944 Returns true if the object currently refers to a opened file/buffer.
 945
 946 =head2 autoflush
 947
 948     my $prev = $z->autoflush()
 949     my $prev = $z->autoflush(EXPR)
 950
 951 If the C<$z> object is associated with a file or a filehandle, this method
 952 returns the current autoflush setting for the underlying filehandle. If
 953 C<EXPR> is present, and is non-zero, it will enable flushing after every
 954 write/print operation.
 955
 956 If C<$z> is associated with a buffer, this method has no effect and always
 957 returns C<undef>.
 958
 959 B<Note> that the special variable C<$|> B<cannot> be used to set or
 960 retrieve the autoflush setting.
 961
 962 =head2 input_line_number
 963
 964     $z->input_line_number()
 965     $z->input_line_number(EXPR)
 966
 967 Returns the current uncompressed line number. If C<EXPR> is present it has
 968 the effect of setting the line number. Note that setting the line number
 969 does not change the current position within the file/buffer being read.
 970
 971 The contents of C<$/> are used to to determine what constitutes a line
 972 terminator.
 973
 974 =head2 fileno
 975
 976     $z->fileno()
 977     fileno($z)
 978
 979 If the C<$z> object is associated with a file or a filehandle, C<fileno>
 980 will return the underlying file descriptor. Once the C<close> method is
 981 called C<fileno> will return C<undef>.
 982
 983 If the C<$z> object is associated with a buffer, this method will return
 984 C<undef>.
 985
 986 =head2 close
 987
 988     $z->close() ;
 989     close $z ;
 990
 991 Closes the output file/buffer.
 992
 993 For most versions of Perl this method will be automatically invoked if
 994 the IO::Uncompress::Gunzip object is destroyed (either explicitly or by the
 995 variable with the reference to the object going out of scope). The
 996 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
 997 these cases, the C<close> method will be called automatically, but
 998 not until global destruction of all live objects when the program is
 999 terminating.
1000
1001 Therefore, if you want your scripts to be able to run on all versions
1002 of Perl, you should call C<close> explicitly and not rely on automatic
1003 closing.
1004
1005 Returns true on success, otherwise 0.
1006
1007 If the C<AutoClose> option has been enabled when the IO::Uncompress::Gunzip
1008 object was created, and the object is associated with a file, the
1009 underlying file will also be closed.
1010
1011 =head2 nextStream
1012
1013 Usage is
1014
1015     my $status = $z->nextStream();
1016
1017 Skips to the next compressed data stream in the input file/buffer. If a new
1018 compressed data stream is found, the eof marker will be cleared and C<$.>
1019 will be reset to 0.
1020
1021 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
1022 error was encountered.
1023
1024 =head2 trailingData
1025
1026 Usage is
1027
1028     my $data = $z->trailingData();
1029
1030 Returns the data, if any, that is present immediately after the compressed
1031 data stream once uncompression is complete. It only makes sense to call
1032 this method once the end of the compressed data stream has been
1033 encountered.
1034
1035 This option can be used when there is useful information immediately
1036 following the compressed data stream, and you don't know the length of the
1037 compressed data stream.
1038
1039 If the input is a buffer, C<trailingData> will return everything from the
1040 end of the compressed data stream to the end of the buffer.
1041
1042 If the input is a filehandle, C<trailingData> will return the data that is
1043 left in the filehandle input buffer once the end of the compressed data
1044 stream has been reached. You can then use the filehandle to read the rest
1045 of the input file.
1046
1047 Don't bother using C<trailingData> if the input is a filename.
1048
1049 If you know the length of the compressed data stream before you start
1050 uncompressing, you can avoid having to use C<trailingData> by setting the
1051 C<InputLength> option in the constructor.
1052
1053 =head1 Importing
1054
1055 No symbolic constants are required by this IO::Uncompress::Gunzip at present.
1056
1057 =over 5
1058
1059 =item :all
1060
1061 Imports C<gunzip> and C<$GunzipError>.
1062 Same as doing this
1063
1064     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
1065
1066 =back
1067
1068 =head1 EXAMPLES
1069
1070 =head2 Working with Net::FTP
1071
1072 See L<IO::Uncompress::Gunzip::FAQ|IO::Uncompress::Gunzip::FAQ/"Compressed files and Net::FTP">
1073
1074 =head1 SEE ALSO
1075
1076 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::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1077
1078 L<IO::Compress::FAQ|IO::Compress::FAQ>
1079
1080 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1081 L<Archive::Tar|Archive::Tar>,
1082 L<IO::Zlib|IO::Zlib>
1083
1084 For RFC 1950, 1951 and 1952 see
1085 F<http://www.faqs.org/rfcs/rfc1950.html>,
1086 F<http://www.faqs.org/rfcs/rfc1951.html> and
1087 F<http://www.faqs.org/rfcs/rfc1952.html>
1088
1089 The I<zlib> compression library was written by Jean-loup Gailly
1090 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1091
1092 The primary site for the I<zlib> compression library is
1093 F<http://www.zlib.org>.
1094
1095 The primary site for gzip is F<http://www.gzip.org>.
1096
1097 =head1 AUTHOR
1098
1099 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1100
1101 =head1 MODIFICATION HISTORY
1102
1103 See the Changes file.
1104
1105 =head1 COPYRIGHT AND LICENSE
1106
1107 Copyright (c) 2005-2012 Paul Marquess. All rights reserved.
1108
1109 This program is free software; you can redistribute it and/or
1110 modify it under the same terms as Perl itself.
1111