"Fossies" - the Fresh Open Source Software Archive

Member "IO-Compress-2.093/lib/IO/Uncompress/Gunzip.pm" (7 Dec 2019, 32243 Bytes) of package /linux/privat/IO-Compress-2.093.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "Gunzip.pm" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 2.092_vs_2.093.

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