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