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 = new IO::Uncompress::AnyInflate $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.
84 The $input_filename_or_reference parameter
86 The parameter, $input_filename_or_reference, is used to define the
88 source of the compressed data.
89 It can take one of the following forms:
91 A filename
93 If the <$input_filename_or_reference> parameter is a simple
94 scalar, it is assumed to be a filename. This file will be opened
95 for reading and the input data will be read from it.
96 A filehandle
98 If the $input_filename_or_reference parameter is a filehandle, the
99 input data will be read from it. The string '-' can be used as an
100 alias for standard input.
101 A scalar reference
103 If $input_filename_or_reference is a scalar reference, the input
104 data will be read from $$input_filename_or_reference.
105 An array reference
107 If $input_filename_or_reference is an array reference, each
108 element in the array must be a filename.
109 The input data will be read from each file in turn.
111 The complete array will be walked to ensure that it only contains
113 valid filenames before any data is uncompressed.
114 An Input FileGlob string
116 If $input_filename_or_reference is a string that is delimited by
117 the characters "<" and ">" "anyinflate" will assume that it is an
118 input fileglob string. The input is the list of files that match
119 the fileglob.
120 See File::GlobMapper for more details.
122 If the $input_filename_or_reference parameter is any other type,
124 "undef" will be returned.
125 The $output_filename_or_reference parameter
127 The parameter $output_filename_or_reference is used to control the
129 destination of the uncompressed data. This parameter can take one of
130 these forms.
131 A filename
133 If the $output_filename_or_reference parameter is a simple scalar,
134 it is assumed to be a filename. This file will be opened for
135 writing and the uncompressed data will be written to it.
136 A filehandle
138 If the $output_filename_or_reference parameter is a filehandle,
139 the uncompressed data will be written to it. The string '-' can
140 be used as an alias for standard output.
141 A scalar reference
143 If $output_filename_or_reference is a scalar reference, the
144 uncompressed data will be stored in
145 $$output_filename_or_reference.
146 An Array Reference
148 If $output_filename_or_reference is an array reference, the
149 uncompressed data will be pushed onto the array.
150 An Output FileGlob
152 If $output_filename_or_reference is a string that is delimited by
153 the characters "<" and ">" "anyinflate" will assume that it is an
154 output fileglob string. The output is the list of files that match
155 the fileglob.
156 When $output_filename_or_reference is an fileglob string,
158 $input_filename_or_reference must also be a fileglob string.
159 Anything else is an error.
160 See File::GlobMapper for more details.
162 If the $output_filename_or_reference parameter is any other type,
164 "undef" will be returned.
165 Notes
167 When $input_filename_or_reference maps to multiple compressed
168 files/buffers and $output_filename_or_reference is a single
169 file/buffer, after uncompression $output_filename_or_reference will
170 contain a concatenation of all the uncompressed data from each of the
171 input files/buffers.
172 Optional Parameters
174 Unless specified below, the optional parameters for "anyinflate",
175 "OPTS", are the same as those used with the OO interface defined in the
176 "Constructor Options" section below.
177 "AutoClose => 0|1"
179 This option applies to any input or output data streams to
180 "anyinflate" that are filehandles.
181 If "AutoClose" is specified, and the value is true, it will result
183 in all input and/or output filehandles being closed once
184 "anyinflate" has completed.
185 This parameter defaults to 0.
187 "BinModeOut => 0|1"
189 This option is now a no-op. All files will be written in binmode.
190 "Append => 0|1"
192 The behaviour of this option is dependent on the type of output
193 data stream.
194 · A Buffer
196 If "Append" is enabled, all uncompressed data will be append
198 to the end of the output buffer. Otherwise the output buffer
199 will be cleared before any uncompressed data is written to
200 it.
201 · A Filename
203 If "Append" is enabled, the file will be opened in append
205 mode. Otherwise the contents of the file, if any, will be
206 truncated before any uncompressed data is written to it.
207 · A Filehandle
209 If "Append" is enabled, the filehandle will be positioned to
211 the end of the file via a call to "seek" before any
212 uncompressed data is written to it. Otherwise the file
213 pointer will not be moved.
214 When "Append" is specified, and set to true, it will append all
216 uncompressed data to the output data stream.
217 So when the output is a filehandle it will carry out a seek to the
219 eof before writing any uncompressed data. If the output is a
220 filename, it will be opened for appending. If the output is a
221 buffer, all uncompressed data will be appended to the existing
222 buffer.
223 Conversely when "Append" is not specified, or it is present and is
225 set to false, it will operate as follows.
226 When the output is a filename, it will truncate the contents of
228 the file before writing any uncompressed data. If the output is a
229 filehandle its position will not be changed. If the output is a
230 buffer, it will be wiped before any uncompressed data is output.
231 Defaults to 0.
233 "MultiStream => 0|1"
235 If the input file/buffer contains multiple compressed data
236 streams, this option will uncompress the whole lot as a single
237 data stream.
238 Defaults to 0.
240 "TrailingData => $scalar"
242 Returns the data, if any, that is present immediately after the
243 compressed data stream once uncompression is complete.
244 This option can be used when there is useful information
246 immediately following the compressed data stream, and you don't
247 know the length of the compressed data stream.
248 If the input is a buffer, "trailingData" will return everything
250 from the end of the compressed data stream to the end of the
251 buffer.
252 If the input is a filehandle, "trailingData" will return the data
254 that is left in the filehandle input buffer once the end of the
255 compressed data stream has been reached. You can then use the
256 filehandle to read the rest of the input file.
257 Don't bother using "trailingData" if the input is a filename.
259 If you know the length of the compressed data stream before you
261 start uncompressing, you can avoid having to use "trailingData" by
262 setting the "InputLength" option.
263 Examples
265 To read the contents of the file "file1.txt.Compressed" and write the
266 uncompressed data to the file "file1.txt".
267 use strict ;
269 use warnings ;
270 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
271 my $input = "file1.txt.Compressed";
273 my $output = "file1.txt";
274 anyinflate $input => $output
275 or die "anyinflate failed: $AnyInflateError\n";
276 To read from an existing Perl filehandle, $input, and write the
278 uncompressed data to a buffer, $buffer.
279 use strict ;
281 use warnings ;
282 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
283 use IO::File ;
284 my $input = new IO::File "<file1.txt.Compressed"
286 or die "Cannot open 'file1.txt.Compressed': $!\n" ;
287 my $buffer ;
288 anyinflate $input => \$buffer
289 or die "anyinflate failed: $AnyInflateError\n";
290 To uncompress all files in the directory "/my/home" that match
292 "*.txt.Compressed" and store the compressed data in the same directory
293 use strict ;
295 use warnings ;
296 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
297 anyinflate '</my/home/*.txt.Compressed>' => '</my/home/#1.txt>'
299 or die "anyinflate failed: $AnyInflateError\n";
300 and if you want to compress each file one at a time, this will do the
302 trick
303 use strict ;
305 use warnings ;
306 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
307 for my $input ( glob "/my/home/*.txt.Compressed" )
309 {
310 my $output = $input;
311 $output =~ s/.Compressed// ;
312 anyinflate $input => $output
313 or die "Error compressing '$input': $AnyInflateError\n";
314 }
315
317 Constructor
318 The format of the constructor for IO::Uncompress::AnyInflate is shown
319 below
320 my $z = new IO::Uncompress::AnyInflate $input [OPTS]
322 or die "IO::Uncompress::AnyInflate failed: $AnyInflateError\n";
323 Returns an "IO::Uncompress::AnyInflate" object on success and undef on
325 failure. The variable $AnyInflateError will contain an error message
326 on failure.
327 If you are running Perl 5.005 or better the object, $z, returned from
329 IO::Uncompress::AnyInflate can be used exactly like an IO::File
330 filehandle. This means that all normal input file operations can be
331 carried out with $z. For example, to read a line from a compressed
332 file/buffer you can use either of these forms
333 $line = $z->getline();
335 $line = <$z>;
336 The mandatory parameter $input is used to determine the source of the
338 compressed data. This parameter can take one of three forms.
339 A filename
341 If the $input parameter is a scalar, it is assumed to be a
342 filename. This file will be opened for reading and the compressed
343 data will be read from it.
344 A filehandle
346 If the $input parameter is a filehandle, the compressed data will
347 be read from it. The string '-' can be used as an alias for
348 standard input.
349 A scalar reference
351 If $input is a scalar reference, the compressed data will be read
352 from $$input.
353 Constructor Options
355 The option names defined below are case insensitive and can be
356 optionally prefixed by a '-'. So all of the following are valid
357 -AutoClose
359 -autoclose
360 AUTOCLOSE
361 autoclose
362 OPTS is a combination of the following options:
364 "AutoClose => 0|1"
366 This option is only valid when the $input parameter is a
367 filehandle. If specified, and the value is true, it will result in
368 the file being closed once either the "close" method is called or
369 the IO::Uncompress::AnyInflate object is destroyed.
370 This parameter defaults to 0.
372 "MultiStream => 0|1"
374 Allows multiple concatenated compressed streams to be treated as a
375 single compressed stream. Decompression will stop once either the
376 end of the file/buffer is reached, an error is encountered
377 (premature eof, corrupt compressed data) or the end of a stream is
378 not immediately followed by the start of another stream.
379 This parameter defaults to 0.
381 "Prime => $string"
383 This option will uncompress the contents of $string before
384 processing the input file/buffer.
385 This option can be useful when the compressed data is embedded in
387 another file/data structure and it is not possible to work out
388 where the compressed data begins without having to read the first
389 few bytes. If this is the case, the uncompression can be primed
390 with these bytes using this option.
391 "Transparent => 0|1"
393 If this option is set and the input file/buffer is not compressed
394 data, the module will allow reading of it anyway.
395 In addition, if the input file/buffer does contain compressed data
397 and there is non-compressed data immediately following it, setting
398 this option will make this module treat the whole file/buffer as a
399 single data stream.
400 This option defaults to 1.
402 "BlockSize => $num"
404 When reading the compressed input data, IO::Uncompress::AnyInflate
405 will read it in blocks of $num bytes.
406 This option defaults to 4096.
408 "InputLength => $size"
410 When present this option will limit the number of compressed bytes
411 read from the input file/buffer to $size. This option can be used
412 in the situation where there is useful data directly after the
413 compressed data stream and you know beforehand the exact length of
414 the compressed data stream.
415 This option is mostly used when reading from a filehandle, in
417 which case the file pointer will be left pointing to the first
418 byte directly after the compressed data stream.
419 This option defaults to off.
421 "Append => 0|1"
423 This option controls what the "read" method does with uncompressed
424 data.
425 If set to 1, all uncompressed data will be appended to the output
427 parameter of the "read" method.
428 If set to 0, the contents of the output parameter of the "read"
430 method will be overwritten by the uncompressed data.
431 Defaults to 0.
433 "Strict => 0|1"
435 This option controls whether the extra checks defined below are
436 used when carrying out the decompression. When Strict is on, the
437 extra tests are carried out, when Strict is off they are not.
438 The default for this option is off.
440 If the input is an RFC 1950 data stream, the following will be
442 checked:
443 1. The ADLER32 checksum field must be present.
445 2. The value of the ADLER32 field read must match the adler32
447 value of the uncompressed data actually contained in the
448 file.
449 If the input is a gzip (RFC 1952) data stream, the following will
451 be checked:
452 1. If the FHCRC bit is set in the gzip FLG header byte, the
454 CRC16 bytes in the header must match the crc16 value of the
455 gzip header actually read.
456 2. If the gzip header contains a name field (FNAME) it consists
458 solely of ISO 8859-1 characters.
459 3. If the gzip header contains a comment field (FCOMMENT) it
461 consists solely of ISO 8859-1 characters plus line-feed.
462 4. If the gzip FEXTRA header field is present it must conform to
464 the sub-field structure as defined in RFC 1952.
465 5. The CRC32 and ISIZE trailer fields must be present.
467 6. The value of the CRC32 field read must match the crc32 value
469 of the uncompressed data actually contained in the gzip file.
470 7. The value of the ISIZE fields read must match the length of
472 the uncompressed data actually read from the file.
473 "RawInflate => 0|1"
475 When auto-detecting the compressed format, try to test for raw-
476 deflate (RFC 1951) content using the "IO::Uncompress::RawInflate"
477 module.
478 The reason this is not default behaviour is because RFC 1951
480 content can only be detected by attempting to uncompress it. This
481 process is error prone and can result is false positives.
482 Defaults to 0.
484 "ParseExtra => 0|1" If the gzip FEXTRA header field is present and this
486 option is set, it will force the module to check that it conforms to
487 the sub-field structure as defined in RFC 1952.
488 If the "Strict" is on it will automatically enable this option.
489 Defaults to 0.
491 Examples
493 TODO
494
496 read
497 Usage is
498 $status = $z->read($buffer)
500 Reads a block of compressed data (the size of the compressed block is
502 determined by the "Buffer" option in the constructor), uncompresses it
503 and writes any uncompressed data into $buffer. If the "Append"
504 parameter is set in the constructor, the uncompressed data will be
505 appended to the $buffer parameter. Otherwise $buffer will be
506 overwritten.
507 Returns the number of uncompressed bytes written to $buffer, zero if
509 eof or a negative number on error.
510 read
512 Usage is
513 $status = $z->read($buffer, $length)
515 $status = $z->read($buffer, $length, $offset)
516 $status = read($z, $buffer, $length)
518 $status = read($z, $buffer, $length, $offset)
519 Attempt to read $length bytes of uncompressed data into $buffer.
521 The main difference between this form of the "read" method and the
523 previous one, is that this one will attempt to return exactly $length
524 bytes. The only circumstances that this function will not is if end-of-
525 file or an IO error is encountered.
526 Returns the number of uncompressed bytes written to $buffer, zero if
528 eof or a negative number on error.
529 getline
531 Usage is
532 $line = $z->getline()
534 $line = <$z>
535 Reads a single line.
537 This method fully supports the use of the variable $/ (or
539 $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
540 what constitutes an end of line. Paragraph mode, record mode and file
541 slurp mode are all supported.
542 getc
544 Usage is
545 $char = $z->getc()
547 Read a single character.
549 ungetc
551 Usage is
552 $char = $z->ungetc($string)
554 inflateSync
556 Usage is
557 $status = $z->inflateSync()
559 TODO
561 getHeaderInfo
563 Usage is
564 $hdr = $z->getHeaderInfo();
566 @hdrs = $z->getHeaderInfo();
567 This method returns either a hash reference (in scalar context) or a
569 list or hash references (in array context) that contains information
570 about each of the header fields in the compressed data stream(s).
571 tell
573 Usage is
574 $z->tell()
576 tell $z
577 Returns the uncompressed file offset.
579 eof
581 Usage is
582 $z->eof();
584 eof($z);
585 Returns true if the end of the compressed input stream has been
587 reached.
588 seek
590 $z->seek($position, $whence);
591 seek($z, $position, $whence);
592 Provides a sub-set of the "seek" functionality, with the restriction
594 that it is only legal to seek forward in the input file/buffer. It is
595 a fatal error to attempt to seek backward.
596 Note that the implementation of "seek" in this module does not provide
598 true random access to a compressed file/buffer. It works by
599 uncompressing data from the current offset in the file/buffer until it
600 reaches the uncompressed offset specified in the parameters to "seek".
601 For very small files this may be acceptable behaviour. For large files
602 it may cause an unacceptable delay.
603 The $whence parameter takes one the usual values, namely SEEK_SET,
605 SEEK_CUR or SEEK_END.
606 Returns 1 on success, 0 on failure.
608 binmode
610 Usage is
611 $z->binmode
613 binmode $z ;
614 This is a noop provided for completeness.
616 opened
618 $z->opened()
619 Returns true if the object currently refers to a opened file/buffer.
621 autoflush
623 my $prev = $z->autoflush()
624 my $prev = $z->autoflush(EXPR)
625 If the $z object is associated with a file or a filehandle, this method
627 returns the current autoflush setting for the underlying filehandle. If
628 "EXPR" is present, and is non-zero, it will enable flushing after every
629 write/print operation.
630 If $z is associated with a buffer, this method has no effect and always
632 returns "undef".
633 Note that the special variable $| cannot be used to set or retrieve the
635 autoflush setting.
636 input_line_number
638 $z->input_line_number()
639 $z->input_line_number(EXPR)
640 Returns the current uncompressed line number. If "EXPR" is present it
642 has the effect of setting the line number. Note that setting the line
643 number does not change the current position within the file/buffer
644 being read.
645 The contents of $/ are used to determine what constitutes a line
647 terminator.
648 fileno
650 $z->fileno()
651 fileno($z)
652 If the $z object is associated with a file or a filehandle, "fileno"
654 will return the underlying file descriptor. Once the "close" method is
655 called "fileno" will return "undef".
656 If the $z object is associated with a buffer, this method will return
658 "undef".
659 close
661 $z->close() ;
662 close $z ;
663 Closes the output file/buffer.
665 For most versions of Perl this method will be automatically invoked if
667 the IO::Uncompress::AnyInflate object is destroyed (either explicitly
668 or by the variable with the reference to the object going out of
669 scope). The exceptions are Perl versions 5.005 through 5.00504 and
670 5.8.0. In these cases, the "close" method will be called automatically,
671 but not until global destruction of all live objects when the program
672 is terminating.
673 Therefore, if you want your scripts to be able to run on all versions
675 of Perl, you should call "close" explicitly and not rely on automatic
676 closing.
677 Returns true on success, otherwise 0.
679 If the "AutoClose" option has been enabled when the
681 IO::Uncompress::AnyInflate object was created, and the object is
682 associated with a file, the underlying file will also be closed.
683 nextStream
685 Usage is
686 my $status = $z->nextStream();
688 Skips to the next compressed data stream in the input file/buffer. If a
690 new compressed data stream is found, the eof marker will be cleared and
691 $. will be reset to 0.
692 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
694 error was encountered.
695 trailingData
697 Usage is
698 my $data = $z->trailingData();
700 Returns the data, if any, that is present immediately after the
702 compressed data stream once uncompression is complete. It only makes
703 sense to call this method once the end of the compressed data stream
704 has been encountered.
705 This option can be used when there is useful information immediately
707 following the compressed data stream, and you don't know the length of
708 the compressed data stream.
709 If the input is a buffer, "trailingData" will return everything from
711 the end of the compressed data stream to the end of the buffer.
712 If the input is a filehandle, "trailingData" will return the data that
714 is left in the filehandle input buffer once the end of the compressed
715 data stream has been reached. You can then use the filehandle to read
716 the rest of the input file.
717 Don't bother using "trailingData" if the input is a filename.
719 If you know the length of the compressed data stream before you start
721 uncompressing, you can avoid having to use "trailingData" by setting
722 the "InputLength" option in the constructor.
723
725 No symbolic constants are required by this IO::Uncompress::AnyInflate
726 at present.
727 :all Imports "anyinflate" and $AnyInflateError. Same as doing this
729 use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
731
733 Working with Net::FTP
734 See IO::Compress::FAQ
735
737 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
738 IO::Compress::Deflate, IO::Uncompress::Inflate,
739 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
740 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma,
741 IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz,
742 IO::Compress::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop,
743 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
744 IO::Compress::Zstd, IO::Uncompress::UnZstd,
745 IO::Uncompress::AnyUncompress
746 IO::Compress::FAQ
748 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
750 For RFC 1950, 1951 and 1952 see
752 <http://www.faqs.org/rfcs/rfc1950.html>,
753 <http://www.faqs.org/rfcs/rfc1951.html> and
754 <http://www.faqs.org/rfcs/rfc1952.html>
755 The zlib compression library was written by Jean-loup Gailly
757 "gzip@prep.ai.mit.edu" and Mark Adler "madler@alumni.caltech.edu".
758 The primary site for the zlib compression library is
760 <http://www.zlib.org>.
761 The primary site for gzip is <http://www.gzip.org>.
763
765 This module was written by Paul Marquess, "pmqs@cpan.org".
766
768 See the Changes file.
769
771 Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
772 This program is free software; you can redistribute it and/or modify it
774 under the same terms as Perl itself.
775perl v5.28.1 2019-01-05 IO::Uncompress::AnyInflate(3)