1IO::Uncompress::AnyInflUasteer(3C)ontributed Perl DocumeInOt:a:tUinocnompress::AnyInflate(3)
2
6 IO::Uncompress::AnyInflate - Uncompress zlib-based (zip, gzip)
7 file/buffer
8
10 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
11 my $status = anyinflate $input => $output [,OPTS]
13 or die "anyinflate failed: $AnyInflateError\n";
14 my $z = IO::Uncompress::AnyInflate->new( $input [OPTS] )
16 or die "anyinflate failed: $AnyInflateError\n";
17 $status = $z->read($buffer)
19 $status = $z->read($buffer, $length)
20 $status = $z->read($buffer, $length, $offset)
21 $line = $z->getline()
22 $char = $z->getc()
23 $char = $z->ungetc()
24 $char = $z->opened()
25 $status = $z->inflateSync()
27 $data = $z->trailingData()
29 $status = $z->nextStream()
30 $data = $z->getHeaderInfo()
31 $z->tell()
32 $z->seek($position, $whence)
33 $z->binmode()
34 $z->fileno()
35 $z->eof()
36 $z->close()
37 $AnyInflateError ;
39 # IO::File mode
41 <$z>
43 read($z, $buffer);
44 read($z, $buffer, $length);
45 read($z, $buffer, $length, $offset);
46 tell($z)
47 seek($z, $position, $whence)
48 binmode($z)
49 fileno($z)
50 eof($z)
51 close($z)
52
54 This module provides a Perl interface that allows the reading of
55 files/buffers that have been compressed in a number of formats that use
56 the zlib compression library.
57 The formats supported are
59 RFC 1950
61 RFC 1951 (optionally)
62 gzip (RFC 1952)
63 zip
64 The module will auto-detect which, if any, of the supported compression
66 formats is being used.
67
69 A top-level function, "anyinflate", is provided to carry out "one-shot"
70 uncompression between buffers and/or files. For finer control over the
71 uncompression process, see the "OO Interface" section.
72 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
74 anyinflate $input_filename_or_reference => $output_filename_or_reference [,OPTS]
76 or die "anyinflate failed: $AnyInflateError\n";
77 The functional interface needs Perl5.005 or better.
79 anyinflate $input_filename_or_reference => $output_filename_or_reference [,
81 OPTS]
82 "anyinflate" expects at least two parameters,
83 $input_filename_or_reference and $output_filename_or_reference and zero
84 or more optional parameters (see "Optional Parameters")
85 The $input_filename_or_reference parameter
87 The parameter, $input_filename_or_reference, is used to define the
89 source of the compressed data.
90 It can take one of the following forms:
92 A filename
94 If the $input_filename_or_reference parameter is a simple scalar,
95 it is assumed to be a filename. This file will be opened for
96 reading and the input data will be read from it.
97 A filehandle
99 If the $input_filename_or_reference parameter is a filehandle, the
100 input data will be read from it. The string '-' can be used as an
101 alias for standard input.
102 A scalar reference
104 If $input_filename_or_reference is a scalar reference, the input
105 data will be read from $$input_filename_or_reference.
106 An array reference
108 If $input_filename_or_reference is an array reference, each
109 element in the array must be a filename.
110 The input data will be read from each file in turn.
112 The complete array will be walked to ensure that it only contains
114 valid filenames before any data is uncompressed.
115 An Input FileGlob string
117 If $input_filename_or_reference is a string that is delimited by
118 the characters "<" and ">" "anyinflate" will assume that it is an
119 input fileglob string. The input is the list of files that match
120 the fileglob.
121 See File::GlobMapper for more details.
123 If the $input_filename_or_reference parameter is any other type,
125 "undef" will be returned.
126 The $output_filename_or_reference parameter
128 The parameter $output_filename_or_reference is used to control the
130 destination of the uncompressed data. This parameter can take one of
131 these forms.
132 A filename
134 If the $output_filename_or_reference parameter is a simple scalar,
135 it is assumed to be a filename. This file will be opened for
136 writing and the uncompressed data will be written to it.
137 A filehandle
139 If the $output_filename_or_reference parameter is a filehandle,
140 the uncompressed data will be written to it. The string '-' can
141 be used as an alias for standard output.
142 A scalar reference
144 If $output_filename_or_reference is a scalar reference, the
145 uncompressed data will be stored in
146 $$output_filename_or_reference.
147 An Array Reference
149 If $output_filename_or_reference is an array reference, the
150 uncompressed data will be pushed onto the array.
151 An Output FileGlob
153 If $output_filename_or_reference is a string that is delimited by
154 the characters "<" and ">" "anyinflate" will assume that it is an
155 output fileglob string. The output is the list of files that match
156 the fileglob.
157 When $output_filename_or_reference is an fileglob string,
159 $input_filename_or_reference must also be a fileglob string.
160 Anything else is an error.
161 See File::GlobMapper for more details.
163 If the $output_filename_or_reference parameter is any other type,
165 "undef" will be returned.
166 Notes
168 When $input_filename_or_reference maps to multiple compressed
169 files/buffers and $output_filename_or_reference is a single
170 file/buffer, after uncompression $output_filename_or_reference will
171 contain a concatenation of all the uncompressed data from each of the
172 input files/buffers.
173 Optional Parameters
175 The optional parameters for the one-shot function "anyinflate" are (for
176 the most part) identical to those used with the OO interface defined in
177 the "Constructor Options" section. The exceptions are listed below
178 "AutoClose => 0|1"
180 This option applies to any input or output data streams to
181 "anyinflate" that are filehandles.
182 If "AutoClose" is specified, and the value is true, it will result
184 in all input and/or output filehandles being closed once
185 "anyinflate" has completed.
186 This parameter defaults to 0.
188 "BinModeOut => 0|1"
190 This option is now a no-op. All files will be written in binmode.
191 "Append => 0|1"
193 The behaviour of this option is dependent on the type of output
194 data stream.
195 • A Buffer
197 If "Append" is enabled, all uncompressed data will be append
199 to the end of the output buffer. Otherwise the output buffer
200 will be cleared before any uncompressed data is written to
201 it.
202 • A Filename
204 If "Append" is enabled, the file will be opened in append
206 mode. Otherwise the contents of the file, if any, will be
207 truncated before any uncompressed data is written to it.
208 • A Filehandle
210 If "Append" is enabled, the filehandle will be positioned to
212 the end of the file via a call to "seek" before any
213 uncompressed data is written to it. Otherwise the file
214 pointer will not be moved.
215 When "Append" is specified, and set to true, it will append all
217 uncompressed data to the output data stream.
218 So when the output is a filehandle it will carry out a seek to the
220 eof before writing any uncompressed data. If the output is a
221 filename, it will be opened for appending. If the output is a
222 buffer, all uncompressed data will be appended to the existing
223 buffer.
224 Conversely when "Append" is not specified, or it is present and is
226 set to false, it will operate as follows.
227 When the output is a filename, it will truncate the contents of
229 the file before writing any uncompressed data. If the output is a
230 filehandle its position will not be changed. If the output is a
231 buffer, it will be wiped before any uncompressed data is output.
232 Defaults to 0.
234 "MultiStream => 0|1"
236 If the input file/buffer contains multiple compressed data
237 streams, this option will uncompress the whole lot as a single
238 data stream.
239 Defaults to 0.
241 "TrailingData => $scalar"
243 Returns the data, if any, that is present immediately after the
244 compressed data stream once uncompression is complete.
245 This option can be used when there is useful information
247 immediately following the compressed data stream, and you don't
248 know the length of the compressed data stream.
249 If the input is a buffer, "trailingData" will return everything
251 from the end of the compressed data stream to the end of the
252 buffer.
253 If the input is a filehandle, "trailingData" will return the data
255 that is left in the filehandle input buffer once the end of the
256 compressed data stream has been reached. You can then use the
257 filehandle to read the rest of the input file.
258 Don't bother using "trailingData" if the input is a filename.
260 If you know the length of the compressed data stream before you
262 start uncompressing, you can avoid having to use "trailingData" by
263 setting the "InputLength" option.
264 Examples
266 To read the contents of the file "file1.txt.Compressed" and write the
267 uncompressed data to the file "file1.txt".
268 use strict ;
270 use warnings ;
271 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
272 my $input = "file1.txt.Compressed";
274 my $output = "file1.txt";
275 anyinflate $input => $output
276 or die "anyinflate failed: $AnyInflateError\n";
277 To read from an existing Perl filehandle, $input, and write the
279 uncompressed data to a buffer, $buffer.
280 use strict ;
282 use warnings ;
283 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
284 use IO::File ;
285 my $input = IO::File->new( "<file1.txt.Compressed" )
287 or die "Cannot open 'file1.txt.Compressed': $!\n" ;
288 my $buffer ;
289 anyinflate $input => \$buffer
290 or die "anyinflate failed: $AnyInflateError\n";
291 To uncompress all files in the directory "/my/home" that match
293 "*.txt.Compressed" and store the compressed data in the same directory
294 use strict ;
296 use warnings ;
297 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
298 anyinflate '</my/home/*.txt.Compressed>' => '</my/home/#1.txt>'
300 or die "anyinflate failed: $AnyInflateError\n";
301 and if you want to compress each file one at a time, this will do the
303 trick
304 use strict ;
306 use warnings ;
307 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
308 for my $input ( glob "/my/home/*.txt.Compressed" )
310 {
311 my $output = $input;
312 $output =~ s/.Compressed// ;
313 anyinflate $input => $output
314 or die "Error compressing '$input': $AnyInflateError\n";
315 }
316
318 Constructor
319 The format of the constructor for IO::Uncompress::AnyInflate is shown
320 below
321 my $z = IO::Uncompress::AnyInflate->new( $input [OPTS] )
323 or die "IO::Uncompress::AnyInflate failed: $AnyInflateError\n";
324 Returns an "IO::Uncompress::AnyInflate" object on success and undef on
326 failure. The variable $AnyInflateError will contain an error message
327 on failure.
328 If you are running Perl 5.005 or better the object, $z, returned from
330 IO::Uncompress::AnyInflate can be used exactly like an IO::File
331 filehandle. This means that all normal input file operations can be
332 carried out with $z. For example, to read a line from a compressed
333 file/buffer you can use either of these forms
334 $line = $z->getline();
336 $line = <$z>;
337 The mandatory parameter $input is used to determine the source of the
339 compressed data. This parameter can take one of three forms.
340 A filename
342 If the $input parameter is a scalar, it is assumed to be a
343 filename. This file will be opened for reading and the compressed
344 data will be read from it.
345 A filehandle
347 If the $input parameter is a filehandle, the compressed data will
348 be read from it. The string '-' can be used as an alias for
349 standard input.
350 A scalar reference
352 If $input is a scalar reference, the compressed data will be read
353 from $$input.
354 Constructor Options
356 The option names defined below are case insensitive and can be
357 optionally prefixed by a '-'. So all of the following are valid
358 -AutoClose
360 -autoclose
361 AUTOCLOSE
362 autoclose
363 OPTS is a combination of the following options:
365 "AutoClose => 0|1"
367 This option is only valid when the $input parameter is a
368 filehandle. If specified, and the value is true, it will result in
369 the file being closed once either the "close" method is called or
370 the IO::Uncompress::AnyInflate object is destroyed.
371 This parameter defaults to 0.
373 "MultiStream => 0|1"
375 Allows multiple concatenated compressed streams to be treated as a
376 single compressed stream. Decompression will stop once either the
377 end of the file/buffer is reached, an error is encountered
378 (premature eof, corrupt compressed data) or the end of a stream is
379 not immediately followed by the start of another stream.
380 This parameter defaults to 0.
382 "Prime => $string"
384 This option will uncompress the contents of $string before
385 processing the input file/buffer.
386 This option can be useful when the compressed data is embedded in
388 another file/data structure and it is not possible to work out
389 where the compressed data begins without having to read the first
390 few bytes. If this is the case, the uncompression can be primed
391 with these bytes using this option.
392 "Transparent => 0|1"
394 If this option is set and the input file/buffer is not compressed
395 data, the module will allow reading of it anyway.
396 In addition, if the input file/buffer does contain compressed data
398 and there is non-compressed data immediately following it, setting
399 this option will make this module treat the whole file/buffer as a
400 single data stream.
401 This option defaults to 1.
403 "BlockSize => $num"
405 When reading the compressed input data, IO::Uncompress::AnyInflate
406 will read it in blocks of $num bytes.
407 This option defaults to 4096.
409 "InputLength => $size"
411 When present this option will limit the number of compressed bytes
412 read from the input file/buffer to $size. This option can be used
413 in the situation where there is useful data directly after the
414 compressed data stream and you know beforehand the exact length of
415 the compressed data stream.
416 This option is mostly used when reading from a filehandle, in
418 which case the file pointer will be left pointing to the first
419 byte directly after the compressed data stream.
420 This option defaults to off.
422 "Append => 0|1"
424 This option controls what the "read" method does with uncompressed
425 data.
426 If set to 1, all uncompressed data will be appended to the output
428 parameter of the "read" method.
429 If set to 0, the contents of the output parameter of the "read"
431 method will be overwritten by the uncompressed data.
432 Defaults to 0.
434 "Strict => 0|1"
436 This option controls whether the extra checks defined below are
437 used when carrying out the decompression. When Strict is on, the
438 extra tests are carried out, when Strict is off they are not.
439 The default for this option is off.
441 If the input is an RFC 1950 data stream, the following will be
443 checked:
444 1. The ADLER32 checksum field must be present.
446 2. The value of the ADLER32 field read must match the adler32
448 value of the uncompressed data actually contained in the
449 file.
450 If the input is a gzip (RFC 1952) data stream, the following will
452 be checked:
453 1. If the FHCRC bit is set in the gzip FLG header byte, the
455 CRC16 bytes in the header must match the crc16 value of the
456 gzip header actually read.
457 2. If the gzip header contains a name field (FNAME) it consists
459 solely of ISO 8859-1 characters.
460 3. If the gzip header contains a comment field (FCOMMENT) it
462 consists solely of ISO 8859-1 characters plus line-feed.
463 4. If the gzip FEXTRA header field is present it must conform to
465 the sub-field structure as defined in RFC 1952.
466 5. The CRC32 and ISIZE trailer fields must be present.
468 6. The value of the CRC32 field read must match the crc32 value
470 of the uncompressed data actually contained in the gzip file.
471 7. The value of the ISIZE fields read must match the length of
473 the uncompressed data actually read from the file.
474 "RawInflate => 0|1"
476 When auto-detecting the compressed format, try to test for raw-
477 deflate (RFC 1951) content using the "IO::Uncompress::RawInflate"
478 module.
479 The reason this is not default behaviour is because RFC 1951
481 content can only be detected by attempting to uncompress it. This
482 process is error prone and can result is false positives.
483 Defaults to 0.
485 "ParseExtra => 0|1" If the gzip FEXTRA header field is present and this
487 option is set, it will force the module to check that it conforms to
488 the sub-field structure as defined in RFC 1952.
489 If the "Strict" is on it will automatically enable this option.
490 Defaults to 0.
492 Examples
494 TODO
495
497 read
498 Usage is
499 $status = $z->read($buffer)
501 Reads a block of compressed data (the size of the compressed block is
503 determined by the "Buffer" option in the constructor), uncompresses it
504 and writes any uncompressed data into $buffer. If the "Append"
505 parameter is set in the constructor, the uncompressed data will be
506 appended to the $buffer parameter. Otherwise $buffer will be
507 overwritten.
508 Returns the number of uncompressed bytes written to $buffer, zero if
510 eof or a negative number on error.
511 read
513 Usage is
514 $status = $z->read($buffer, $length)
516 $status = $z->read($buffer, $length, $offset)
517 $status = read($z, $buffer, $length)
519 $status = read($z, $buffer, $length, $offset)
520 Attempt to read $length bytes of uncompressed data into $buffer.
522 The main difference between this form of the "read" method and the
524 previous one, is that this one will attempt to return exactly $length
525 bytes. The only circumstances that this function will not is if end-of-
526 file or an IO error is encountered.
527 Returns the number of uncompressed bytes written to $buffer, zero if
529 eof or a negative number on error.
530 getline
532 Usage is
533 $line = $z->getline()
535 $line = <$z>
536 Reads a single line.
538 This method fully supports the use of the variable $/ (or
540 $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
541 what constitutes an end of line. Paragraph mode, record mode and file
542 slurp mode are all supported.
543 getc
545 Usage is
546 $char = $z->getc()
548 Read a single character.
550 ungetc
552 Usage is
553 $char = $z->ungetc($string)
555 inflateSync
557 Usage is
558 $status = $z->inflateSync()
560 TODO
562 getHeaderInfo
564 Usage is
565 $hdr = $z->getHeaderInfo();
567 @hdrs = $z->getHeaderInfo();
568 This method returns either a hash reference (in scalar context) or a
570 list or hash references (in array context) that contains information
571 about each of the header fields in the compressed data stream(s).
572 tell
574 Usage is
575 $z->tell()
577 tell $z
578 Returns the uncompressed file offset.
580 eof
582 Usage is
583 $z->eof();
585 eof($z);
586 Returns true if the end of the compressed input stream has been
588 reached.
589 seek
591 $z->seek($position, $whence);
592 seek($z, $position, $whence);
593 Provides a sub-set of the "seek" functionality, with the restriction
595 that it is only legal to seek forward in the input file/buffer. It is
596 a fatal error to attempt to seek backward.
597 Note that the implementation of "seek" in this module does not provide
599 true random access to a compressed file/buffer. It works by
600 uncompressing data from the current offset in the file/buffer until it
601 reaches the uncompressed offset specified in the parameters to "seek".
602 For very small files this may be acceptable behaviour. For large files
603 it may cause an unacceptable delay.
604 The $whence parameter takes one the usual values, namely SEEK_SET,
606 SEEK_CUR or SEEK_END.
607 Returns 1 on success, 0 on failure.
609 binmode
611 Usage is
612 $z->binmode
614 binmode $z ;
615 This is a noop provided for completeness.
617 opened
619 $z->opened()
620 Returns true if the object currently refers to a opened file/buffer.
622 autoflush
624 my $prev = $z->autoflush()
625 my $prev = $z->autoflush(EXPR)
626 If the $z object is associated with a file or a filehandle, this method
628 returns the current autoflush setting for the underlying filehandle. If
629 "EXPR" is present, and is non-zero, it will enable flushing after every
630 write/print operation.
631 If $z is associated with a buffer, this method has no effect and always
633 returns "undef".
634 Note that the special variable $| cannot be used to set or retrieve the
636 autoflush setting.
637 input_line_number
639 $z->input_line_number()
640 $z->input_line_number(EXPR)
641 Returns the current uncompressed line number. If "EXPR" is present it
643 has the effect of setting the line number. Note that setting the line
644 number does not change the current position within the file/buffer
645 being read.
646 The contents of $/ are used to determine what constitutes a line
648 terminator.
649 fileno
651 $z->fileno()
652 fileno($z)
653 If the $z object is associated with a file or a filehandle, "fileno"
655 will return the underlying file descriptor. Once the "close" method is
656 called "fileno" will return "undef".
657 If the $z object is associated with a buffer, this method will return
659 "undef".
660 close
662 $z->close() ;
663 close $z ;
664 Closes the output file/buffer.
666 For most versions of Perl this method will be automatically invoked if
668 the IO::Uncompress::AnyInflate object is destroyed (either explicitly
669 or by the variable with the reference to the object going out of
670 scope). The exceptions are Perl versions 5.005 through 5.00504 and
671 5.8.0. In these cases, the "close" method will be called automatically,
672 but not until global destruction of all live objects when the program
673 is terminating.
674 Therefore, if you want your scripts to be able to run on all versions
676 of Perl, you should call "close" explicitly and not rely on automatic
677 closing.
678 Returns true on success, otherwise 0.
680 If the "AutoClose" option has been enabled when the
682 IO::Uncompress::AnyInflate object was created, and the object is
683 associated with a file, the underlying file will also be closed.
684 nextStream
686 Usage is
687 my $status = $z->nextStream();
689 Skips to the next compressed data stream in the input file/buffer. If a
691 new compressed data stream is found, the eof marker will be cleared and
692 $. will be reset to 0.
693 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
695 error was encountered.
696 trailingData
698 Usage is
699 my $data = $z->trailingData();
701 Returns the data, if any, that is present immediately after the
703 compressed data stream once uncompression is complete. It only makes
704 sense to call this method once the end of the compressed data stream
705 has been encountered.
706 This option can be used when there is useful information immediately
708 following the compressed data stream, and you don't know the length of
709 the compressed data stream.
710 If the input is a buffer, "trailingData" will return everything from
712 the end of the compressed data stream to the end of the buffer.
713 If the input is a filehandle, "trailingData" will return the data that
715 is left in the filehandle input buffer once the end of the compressed
716 data stream has been reached. You can then use the filehandle to read
717 the rest of the input file.
718 Don't bother using "trailingData" if the input is a filename.
720 If you know the length of the compressed data stream before you start
722 uncompressing, you can avoid having to use "trailingData" by setting
723 the "InputLength" option in the constructor.
724
726 No symbolic constants are required by IO::Uncompress::AnyInflate at
727 present.
728 :all Imports "anyinflate" and $AnyInflateError. Same as doing this
730 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
732
734 Working with Net::FTP
735 See IO::Compress::FAQ
736
738 General feedback/questions/bug reports should be sent to
739 <https://github.com/pmqs/IO-Compress/issues> (preferred) or
740 <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
741
743 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
744 IO::Compress::Deflate, IO::Uncompress::Inflate,
745 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
746 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma,
747 IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz,
748 IO::Compress::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop,
749 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
750 IO::Compress::Zstd, IO::Uncompress::UnZstd,
751 IO::Uncompress::AnyUncompress
752 IO::Compress::FAQ
754 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
756 For RFC 1950, 1951 and 1952 see
758 <https://datatracker.ietf.org/doc/html/rfc1950>,
759 <https://datatracker.ietf.org/doc/html/rfc1951> and
760 <https://datatracker.ietf.org/doc/html/rfc1952>
761 The zlib compression library was written by Jean-loup Gailly
763 "gzip@prep.ai.mit.edu" and Mark Adler "madler@alumni.caltech.edu".
764 The primary site for the zlib compression library is
766 <http://www.zlib.org>.
767 The primary site for the zlib-ng compression library is
769 <https://github.com/zlib-ng/zlib-ng>.
770 The primary site for gzip is <http://www.gzip.org>.
772
774 This module was written by Paul Marquess, "pmqs@cpan.org".
775
777 See the Changes file.
778
780 Copyright (c) 2005-2022 Paul Marquess. All rights reserved.
781 This program is free software; you can redistribute it and/or modify it
783 under the same terms as Perl itself.
784perl v5.36.0 2022-07-22 IO::Uncompress::AnyInflate(3)