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