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