1IO::Uncompress::Gunzip(U3s)er Contributed Perl DocumentatIiOo:n:Uncompress::Gunzip(3)
2
6 IO::Uncompress::Gunzip - Read RFC 1952 files/buffers
7
9 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
10 my $status = gunzip $input => $output [,OPTS]
12 or die "gunzip failed: $GunzipError\n";
13 my $z = new IO::Uncompress::Gunzip $input [OPTS]
15 or die "gunzip failed: $GunzipError\n";
16 $status = $z->read($buffer)
18 $status = $z->read($buffer, $length)
19 $status = $z->read($buffer, $length, $offset)
20 $line = $z->getline()
21 $char = $z->getc()
22 $char = $z->ungetc()
23 $char = $z->opened()
24 $status = $z->inflateSync()
26 $data = $z->trailingData()
28 $status = $z->nextStream()
29 $data = $z->getHeaderInfo()
30 $z->tell()
31 $z->seek($position, $whence)
32 $z->binmode()
33 $z->fileno()
34 $z->eof()
35 $z->close()
36 $GunzipError ;
38 # IO::File mode
40 <$z>
42 read($z, $buffer);
43 read($z, $buffer, $length);
44 read($z, $buffer, $length, $offset);
45 tell($z)
46 seek($z, $position, $whence)
47 binmode($z)
48 fileno($z)
49 eof($z)
50 close($z)
51
53 This module provides a Perl interface that allows the reading of
54 files/buffers that conform to RFC 1952.
55 For writing RFC 1952 files/buffers, see the companion module
57 IO::Compress::Gzip.
58
60 A top-level function, "gunzip", is provided to carry out "one-shot"
61 uncompression between buffers and/or files. For finer control over the
62 uncompression process, see the "OO Interface" section.
63 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
65 gunzip $input_filename_or_reference => $output_filename_or_reference [,OPTS]
67 or die "gunzip failed: $GunzipError\n";
68 The functional interface needs Perl5.005 or better.
70 gunzip $input_filename_or_reference => $output_filename_or_reference [,
72 OPTS]
73 "gunzip" expects at least two parameters, $input_filename_or_reference
74 and $output_filename_or_reference.
75 The $input_filename_or_reference parameter
77 The parameter, $input_filename_or_reference, is used to define the
79 source of the compressed data.
80 It can take one of the following forms:
82 A filename
84 If the <$input_filename_or_reference> parameter is a simple
85 scalar, it is assumed to be a filename. This file will be opened
86 for reading and the input data will be read from it.
87 A filehandle
89 If the $input_filename_or_reference parameter is a filehandle, the
90 input data will be read from it. The string '-' can be used as an
91 alias for standard input.
92 A scalar reference
94 If $input_filename_or_reference is a scalar reference, the input
95 data will be read from $$input_filename_or_reference.
96 An array reference
98 If $input_filename_or_reference is an array reference, each
99 element in the array must be a filename.
100 The input data will be read from each file in turn.
102 The complete array will be walked to ensure that it only contains
104 valid filenames before any data is uncompressed.
105 An Input FileGlob string
107 If $input_filename_or_reference is a string that is delimited by
108 the characters "<" and ">" "gunzip" will assume that it is an
109 input fileglob string. The input is the list of files that match
110 the fileglob.
111 See File::GlobMapper for more details.
113 If the $input_filename_or_reference parameter is any other type,
115 "undef" will be returned.
116 The $output_filename_or_reference parameter
118 The parameter $output_filename_or_reference is used to control the
120 destination of the uncompressed data. This parameter can take one of
121 these forms.
122 A filename
124 If the $output_filename_or_reference parameter is a simple scalar,
125 it is assumed to be a filename. This file will be opened for
126 writing and the uncompressed data will be written to it.
127 A filehandle
129 If the $output_filename_or_reference parameter is a filehandle,
130 the uncompressed data will be written to it. The string '-' can
131 be used as an alias for standard output.
132 A scalar reference
134 If $output_filename_or_reference is a scalar reference, the
135 uncompressed data will be stored in
136 $$output_filename_or_reference.
137 An Array Reference
139 If $output_filename_or_reference is an array reference, the
140 uncompressed data will be pushed onto the array.
141 An Output FileGlob
143 If $output_filename_or_reference is a string that is delimited by
144 the characters "<" and ">" "gunzip" will assume that it is an
145 output fileglob string. The output is the list of files that match
146 the fileglob.
147 When $output_filename_or_reference is an fileglob string,
149 $input_filename_or_reference must also be a fileglob string.
150 Anything else is an error.
151 See File::GlobMapper for more details.
153 If the $output_filename_or_reference parameter is any other type,
155 "undef" will be returned.
156 Notes
158 When $input_filename_or_reference maps to multiple compressed
159 files/buffers and $output_filename_or_reference is a single
160 file/buffer, after uncompression $output_filename_or_reference will
161 contain a concatenation of all the uncompressed data from each of the
162 input files/buffers.
163 Optional Parameters
165 Unless specified below, the optional parameters for "gunzip", "OPTS",
166 are the same as those used with the OO interface defined in the
167 "Constructor Options" section below.
168 "AutoClose => 0|1"
170 This option applies to any input or output data streams to
171 "gunzip" that are filehandles.
172 If "AutoClose" is specified, and the value is true, it will result
174 in all input and/or output filehandles being closed once "gunzip"
175 has completed.
176 This parameter defaults to 0.
178 "BinModeOut => 0|1"
180 When writing to a file or filehandle, set "binmode" before writing
181 to the file.
182 Defaults to 0.
184 "Append => 0|1"
186 The behaviour of this option is dependent on the type of output
187 data stream.
188 · A Buffer
190 If "Append" is enabled, all uncompressed data will be append
192 to the end of the output buffer. Otherwise the output buffer
193 will be cleared before any uncompressed data is written to
194 it.
195 · A Filename
197 If "Append" is enabled, the file will be opened in append
199 mode. Otherwise the contents of the file, if any, will be
200 truncated before any uncompressed data is written to it.
201 · A Filehandle
203 If "Append" is enabled, the filehandle will be positioned to
205 the end of the file via a call to "seek" before any
206 uncompressed data is written to it. Otherwise the file
207 pointer will not be moved.
208 When "Append" is specified, and set to true, it will append all
210 uncompressed data to the output data stream.
211 So when the output is a filehandle it will carry out a seek to the
213 eof before writing any uncompressed data. If the output is a
214 filename, it will be opened for appending. If the output is a
215 buffer, all uncompressed data will be appended to the existing
216 buffer.
217 Conversely when "Append" is not specified, or it is present and is
219 set to false, it will operate as follows.
220 When the output is a filename, it will truncate the contents of
222 the file before writing any uncompressed data. If the output is a
223 filehandle its position will not be changed. If the output is a
224 buffer, it will be wiped before any uncompressed data is output.
225 Defaults to 0.
227 "MultiStream => 0|1"
229 If the input file/buffer contains multiple compressed data
230 streams, this option will uncompress the whole lot as a single
231 data stream.
232 Defaults to 0.
234 "TrailingData => $scalar"
236 Returns the data, if any, that is present immediately after the
237 compressed data stream once uncompression is complete.
238 This option can be used when there is useful information
240 immediately following the compressed data stream, and you don't
241 know the length of the compressed data stream.
242 If the input is a buffer, "trailingData" will return everything
244 from the end of the compressed data stream to the end of the
245 buffer.
246 If the input is a filehandle, "trailingData" will return the data
248 that is left in the filehandle input buffer once the end of the
249 compressed data stream has been reached. You can then use the
250 filehandle to read the rest of the input file.
251 Don't bother using "trailingData" if the input is a filename.
253 If you know the length of the compressed data stream before you
255 start uncompressing, you can avoid having to use "trailingData" by
256 setting the "InputLength" option.
257 Examples
259 To read the contents of the file "file1.txt.gz" and write the
260 uncompressed data to the file "file1.txt".
261 use strict ;
263 use warnings ;
264 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
265 my $input = "file1.txt.gz";
267 my $output = "file1.txt";
268 gunzip $input => $output
269 or die "gunzip failed: $GunzipError\n";
270 To read from an existing Perl filehandle, $input, and write the
272 uncompressed data to a buffer, $buffer.
273 use strict ;
275 use warnings ;
276 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
277 use IO::File ;
278 my $input = new IO::File "<file1.txt.gz"
280 or die "Cannot open 'file1.txt.gz': $!\n" ;
281 my $buffer ;
282 gunzip $input => \$buffer
283 or die "gunzip failed: $GunzipError\n";
284 To uncompress all files in the directory "/my/home" that match
286 "*.txt.gz" and store the compressed data in the same directory
287 use strict ;
289 use warnings ;
290 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
291 gunzip '</my/home/*.txt.gz>' => '</my/home/#1.txt>'
293 or die "gunzip failed: $GunzipError\n";
294 and if you want to compress each file one at a time, this will do the
296 trick
297 use strict ;
299 use warnings ;
300 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
301 for my $input ( glob "/my/home/*.txt.gz" )
303 {
304 my $output = $input;
305 $output =~ s/.gz// ;
306 gunzip $input => $output
307 or die "Error compressing '$input': $GunzipError\n";
308 }
309
311 Constructor
312 The format of the constructor for IO::Uncompress::Gunzip is shown below
313 my $z = new IO::Uncompress::Gunzip $input [OPTS]
315 or die "IO::Uncompress::Gunzip failed: $GunzipError\n";
316 Returns an "IO::Uncompress::Gunzip" object on success and undef on
318 failure. The variable $GunzipError will contain an error message on
319 failure.
320 If you are running Perl 5.005 or better the object, $z, returned from
322 IO::Uncompress::Gunzip can be used exactly like an IO::File filehandle.
323 This means that all normal input file operations can be carried out
324 with $z. For example, to read a line from a compressed file/buffer you
325 can use either of these forms
326 $line = $z->getline();
328 $line = <$z>;
329 The mandatory parameter $input is used to determine the source of the
331 compressed data. This parameter can take one of three forms.
332 A filename
334 If the $input parameter is a scalar, it is assumed to be a
335 filename. This file will be opened for reading and the compressed
336 data will be read from it.
337 A filehandle
339 If the $input parameter is a filehandle, the compressed data will
340 be read from it. The string '-' can be used as an alias for
341 standard input.
342 A scalar reference
344 If $input is a scalar reference, the compressed data will be read
345 from $$input.
346 Constructor Options
348 The option names defined below are case insensitive and can be
349 optionally prefixed by a '-'. So all of the following are valid
350 -AutoClose
352 -autoclose
353 AUTOCLOSE
354 autoclose
355 OPTS is a combination of the following options:
357 "AutoClose => 0|1"
359 This option is only valid when the $input parameter is a
360 filehandle. If specified, and the value is true, it will result in
361 the file being closed once either the "close" method is called or
362 the IO::Uncompress::Gunzip object is destroyed.
363 This parameter defaults to 0.
365 "MultiStream => 0|1"
367 Allows multiple concatenated compressed streams to be treated as a
368 single compressed stream. Decompression will stop once either the
369 end of the file/buffer is reached, an error is encountered
370 (premature eof, corrupt compressed data) or the end of a stream is
371 not immediately followed by the start of another stream.
372 This parameter defaults to 0.
374 "Prime => $string"
376 This option will uncompress the contents of $string before
377 processing the input file/buffer.
378 This option can be useful when the compressed data is embedded in
380 another file/data structure and it is not possible to work out
381 where the compressed data begins without having to read the first
382 few bytes. If this is the case, the uncompression can be primed
383 with these bytes using this option.
384 "Transparent => 0|1"
386 If this option is set and the input file/buffer is not compressed
387 data, the module will allow reading of it anyway.
388 In addition, if the input file/buffer does contain compressed data
390 and there is non-compressed data immediately following it, setting
391 this option will make this module treat the whole file/buffer as a
392 single data stream.
393 This option defaults to 1.
395 "BlockSize => $num"
397 When reading the compressed input data, IO::Uncompress::Gunzip
398 will read it in blocks of $num bytes.
399 This option defaults to 4096.
401 "InputLength => $size"
403 When present this option will limit the number of compressed bytes
404 read from the input file/buffer to $size. This option can be used
405 in the situation where there is useful data directly after the
406 compressed data stream and you know beforehand the exact length of
407 the compressed data stream.
408 This option is mostly used when reading from a filehandle, in
410 which case the file pointer will be left pointing to the first
411 byte directly after the compressed data stream.
412 This option defaults to off.
414 "Append => 0|1"
416 This option controls what the "read" method does with uncompressed
417 data.
418 If set to 1, all uncompressed data will be appended to the output
420 parameter of the "read" method.
421 If set to 0, the contents of the output parameter of the "read"
423 method will be overwritten by the uncompressed data.
424 Defaults to 0.
426 "Strict => 0|1"
428 This option controls whether the extra checks defined below are
429 used when carrying out the decompression. When Strict is on, the
430 extra tests are carried out, when Strict is off they are not.
431 The default for this option is off.
433 1. If the FHCRC bit is set in the gzip FLG header byte, the
435 CRC16 bytes in the header must match the crc16 value of the
436 gzip header actually read.
437 2. If the gzip header contains a name field (FNAME) it consists
439 solely of ISO 8859-1 characters.
440 3. If the gzip header contains a comment field (FCOMMENT) it
442 consists solely of ISO 8859-1 characters plus line-feed.
443 4. If the gzip FEXTRA header field is present it must conform to
445 the sub-field structure as defined in RFC 1952.
446 5. The CRC32 and ISIZE trailer fields must be present.
448 6. The value of the CRC32 field read must match the crc32 value
450 of the uncompressed data actually contained in the gzip file.
451 7. The value of the ISIZE fields read must match the length of
453 the uncompressed data actually read from the file.
454 "ParseExtra => 0|1" If the gzip FEXTRA header field is present and this
456 option is set, it will force the module to check that it conforms to
457 the sub-field structure as defined in RFC 1952.
458 If the "Strict" is on it will automatically enable this option.
459 Defaults to 0.
461 Examples
463 TODO
464
466 read
467 Usage is
468 $status = $z->read($buffer)
470 Reads a block of compressed data (the size the the compressed block is
472 determined by the "Buffer" option in the constructor), uncompresses it
473 and writes any uncompressed data into $buffer. If the "Append"
474 parameter is set in the constructor, the uncompressed data will be
475 appended to the $buffer parameter. Otherwise $buffer will be
476 overwritten.
477 Returns the number of uncompressed bytes written to $buffer, zero if
479 eof or a negative number on error.
480 read
482 Usage is
483 $status = $z->read($buffer, $length)
485 $status = $z->read($buffer, $length, $offset)
486 $status = read($z, $buffer, $length)
488 $status = read($z, $buffer, $length, $offset)
489 Attempt to read $length bytes of uncompressed data into $buffer.
491 The main difference between this form of the "read" method and the
493 previous one, is that this one will attempt to return exactly $length
494 bytes. The only circumstances that this function will not is if end-of-
495 file or an IO error is encountered.
496 Returns the number of uncompressed bytes written to $buffer, zero if
498 eof or a negative number on error.
499 getline
501 Usage is
502 $line = $z->getline()
504 $line = <$z>
505 Reads a single line.
507 This method fully supports the use of of the variable $/ (or
509 $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
510 what constitutes an end of line. Paragraph mode, record mode and file
511 slurp mode are all supported.
512 getc
514 Usage is
515 $char = $z->getc()
517 Read a single character.
519 ungetc
521 Usage is
522 $char = $z->ungetc($string)
524 inflateSync
526 Usage is
527 $status = $z->inflateSync()
529 TODO
531 getHeaderInfo
533 Usage is
534 $hdr = $z->getHeaderInfo();
536 @hdrs = $z->getHeaderInfo();
537 This method returns either a hash reference (in scalar context) or a
539 list or hash references (in array context) that contains information
540 about each of the header fields in the compressed data stream(s).
541 Name The contents of the Name header field, if present. If no name is
543 present, the value will be undef. Note this is different from a
544 zero length name, which will return an empty string.
545 Comment
547 The contents of the Comment header field, if present. If no
548 comment is present, the value will be undef. Note this is
549 different from a zero length comment, which will return an empty
550 string.
551 tell
553 Usage is
554 $z->tell()
556 tell $z
557 Returns the uncompressed file offset.
559 eof
561 Usage is
562 $z->eof();
564 eof($z);
565 Returns true if the end of the compressed input stream has been
567 reached.
568 seek
570 $z->seek($position, $whence);
571 seek($z, $position, $whence);
572 Provides a sub-set of the "seek" functionality, with the restriction
574 that it is only legal to seek forward in the input file/buffer. It is
575 a fatal error to attempt to seek backward.
576 Note that the implementation of "seek" in this module does not provide
578 true random access to a compressed file/buffer. It works by
579 uncompressing data from the current offset in the file/buffer until it
580 reaches the ucompressed offset specified in the parameters to "seek".
581 For very small files this may be acceptable behaviour. For large files
582 it may cause an unacceptable delay.
583 The $whence parameter takes one the usual values, namely SEEK_SET,
585 SEEK_CUR or SEEK_END.
586 Returns 1 on success, 0 on failure.
588 binmode
590 Usage is
591 $z->binmode
593 binmode $z ;
594 This is a noop provided for completeness.
596 opened
598 $z->opened()
599 Returns true if the object currently refers to a opened file/buffer.
601 autoflush
603 my $prev = $z->autoflush()
604 my $prev = $z->autoflush(EXPR)
605 If the $z object is associated with a file or a filehandle, this method
607 returns the current autoflush setting for the underlying filehandle. If
608 "EXPR" is present, and is non-zero, it will enable flushing after every
609 write/print operation.
610 If $z is associated with a buffer, this method has no effect and always
612 returns "undef".
613 Note that the special variable $| cannot be used to set or retrieve the
615 autoflush setting.
616 input_line_number
618 $z->input_line_number()
619 $z->input_line_number(EXPR)
620 Returns the current uncompressed line number. If "EXPR" is present it
622 has the effect of setting the line number. Note that setting the line
623 number does not change the current position within the file/buffer
624 being read.
625 The contents of $/ are used to to determine what constitutes a line
627 terminator.
628 fileno
630 $z->fileno()
631 fileno($z)
632 If the $z object is associated with a file or a filehandle, "fileno"
634 will return the underlying file descriptor. Once the "close" method is
635 called "fileno" will return "undef".
636 If the $z object is associated with a buffer, this method will return
638 "undef".
639 close
641 $z->close() ;
642 close $z ;
643 Closes the output file/buffer.
645 For most versions of Perl this method will be automatically invoked if
647 the IO::Uncompress::Gunzip object is destroyed (either explicitly or by
648 the variable with the reference to the object going out of scope). The
649 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
650 cases, the "close" method will be called automatically, but not until
651 global destruction of all live objects when the program is terminating.
652 Therefore, if you want your scripts to be able to run on all versions
654 of Perl, you should call "close" explicitly and not rely on automatic
655 closing.
656 Returns true on success, otherwise 0.
658 If the "AutoClose" option has been enabled when the
660 IO::Uncompress::Gunzip object was created, and the object is associated
661 with a file, the underlying file will also be closed.
662 nextStream
664 Usage is
665 my $status = $z->nextStream();
667 Skips to the next compressed data stream in the input file/buffer. If a
669 new compressed data stream is found, the eof marker will be cleared and
670 $. will be reset to 0.
671 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
673 error was encountered.
674 trailingData
676 Usage is
677 my $data = $z->trailingData();
679 Returns the data, if any, that is present immediately after the
681 compressed data stream once uncompression is complete. It only makes
682 sense to call this method once the end of the compressed data stream
683 has been encountered.
684 This option can be used when there is useful information immediately
686 following the compressed data stream, and you don't know the length of
687 the compressed data stream.
688 If the input is a buffer, "trailingData" will return everything from
690 the end of the compressed data stream to the end of the buffer.
691 If the input is a filehandle, "trailingData" will return the data that
693 is left in the filehandle input buffer once the end of the compressed
694 data stream has been reached. You can then use the filehandle to read
695 the rest of the input file.
696 Don't bother using "trailingData" if the input is a filename.
698 If you know the length of the compressed data stream before you start
700 uncompressing, you can avoid having to use "trailingData" by setting
701 the "InputLength" option in the constructor.
702
704 No symbolic constants are required by this IO::Uncompress::Gunzip at
705 present.
706 :all Imports "gunzip" and $GunzipError. Same as doing this
708 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
710
712 Working with Net::FTP
713 See IO::Compress::FAQ
714
716 Compress::Zlib, IO::Compress::Gzip, IO::Compress::Deflate,
717 IO::Uncompress::Inflate, IO::Compress::RawDeflate,
718 IO::Uncompress::RawInflate, IO::Compress::Bzip2,
719 IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma,
720 IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzop,
721 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
722 IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
723 IO::Compress::FAQ
725 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
727 For RFC 1950, 1951 and 1952 see http://www.faqs.org/rfcs/rfc1950.html,
729 http://www.faqs.org/rfcs/rfc1951.html and
730 http://www.faqs.org/rfcs/rfc1952.html
731 The zlib compression library was written by Jean-loup Gailly
733 gzip@prep.ai.mit.edu and Mark Adler madler@alumni.caltech.edu.
734 The primary site for the zlib compression library is
736 http://www.zlib.org.
737 The primary site for gzip is http://www.gzip.org.
739
741 This module was written by Paul Marquess, pmqs@cpan.org.
742
744 See the Changes file.
745
747 Copyright (c) 2005-2013 Paul Marquess. All rights reserved.
748 This program is free software; you can redistribute it and/or modify it
750 under the same terms as Perl itself.
751perl v5.16.3 2013-05-19 IO::Uncompress::Gunzip(3)