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