1IO::Uncompress::Gunzip(3Ppemr)l Programmers Reference GuIiOd:e:Uncompress::Gunzip(3pm)
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 => $output [,OPTS]
67 or die "gunzip failed: $GunzipError\n";
68 The functional interface needs Perl5.005 or better.
70 gunzip $input => $output [, OPTS]
72 "gunzip" expects at least two parameters, $input and $output.
73 The $input parameter
75 The parameter, $input, is used to define the source of the compressed
77 data.
78 It can take one of the following forms:
80 A filename
82 If the $input parameter is a simple scalar, it is assumed to be a
83 filename. This file will be opened for reading and the input data
84 will be read from it.
85 A filehandle
87 If the $input parameter is a filehandle, the input data will be
88 read from it. The string '-' can be used as an alias for standard
89 input.
90 A scalar reference
92 If $input is a scalar reference, the input data will be read from
93 $$input.
94 An array reference
96 If $input is an array reference, each element in the array must be
97 a filename.
98 The input data will be read from each file in turn.
100 The complete array will be walked to ensure that it only contains
102 valid filenames before any data is uncompressed.
103 An Input FileGlob string
105 If $input is a string that is delimited by the characters "<" and
106 ">" "gunzip" will assume that it is an input fileglob string. The
107 input is the list of files that match the fileglob.
108 If the fileglob does not match any files ...
110 See File::GlobMapper for more details.
112 If the $input parameter is any other type, "undef" will be returned.
114 The $output parameter
116 The parameter $output is used to control the destination of the
118 uncompressed data. This parameter can take one of these forms.
119 A filename
121 If the $output parameter is a simple scalar, it is assumed to be a
122 filename. This file will be opened for writing and the
123 uncompressed data will be written to it.
124 A filehandle
126 If the $output parameter is a filehandle, the uncompressed data
127 will be written to it. The string '-' can be used as an alias for
128 standard output.
129 A scalar reference
131 If $output is a scalar reference, the uncompressed data will be
132 stored in $$output.
133 An Array Reference
135 If $output is an array reference, the uncompressed data will be
136 pushed onto the array.
137 An Output FileGlob
139 If $output is a string that is delimited by the characters "<" and
140 ">" "gunzip" will assume that it is an output fileglob string. The
141 output is the list of files that match the fileglob.
142 When $output is an fileglob string, $input must also be a fileglob
144 string. Anything else is an error.
145 If the $output parameter is any other type, "undef" will be returned.
147 Notes
149 When $input maps to multiple compressed files/buffers and $output is a
150 single file/buffer, after uncompression $output will contain a
151 concatenation of all the uncompressed data from each of the input
152 files/buffers.
153 Optional Parameters
155 Unless specified below, the optional parameters for "gunzip", "OPTS",
156 are the same as those used with the OO interface defined in the
157 "Constructor Options" section below.
158 "AutoClose => 0|1"
160 This option applies to any input or output data streams to
161 "gunzip" that are filehandles.
162 If "AutoClose" is specified, and the value is true, it will result
164 in all input and/or output filehandles being closed once "gunzip"
165 has completed.
166 This parameter defaults to 0.
168 "BinModeOut => 0|1"
170 When writing to a file or filehandle, set "binmode" before writing
171 to the file.
172 Defaults to 0.
174 "Append => 0|1"
176 TODO
177 "MultiStream => 0|1"
179 If the input file/buffer contains multiple compressed data
180 streams, this option will uncompress the whole lot as a single
181 data stream.
182 Defaults to 0.
184 "TrailingData => $scalar"
186 Returns the data, if any, that is present immediately after the
187 compressed data stream once uncompression is complete.
188 This option can be used when there is useful information
190 immediately following the compressed data stream, and you don't
191 know the length of the compressed data stream.
192 If the input is a buffer, "trailingData" will return everything
194 from the end of the compressed data stream to the end of the
195 buffer.
196 If the input is a filehandle, "trailingData" will return the data
198 that is left in the filehandle input buffer once the end of the
199 compressed data stream has been reached. You can then use the
200 filehandle to read the rest of the input file.
201 Don't bother using "trailingData" if the input is a filename.
203 If you know the length of the compressed data stream before you
205 start uncompressing, you can avoid having to use "trailingData" by
206 setting the "InputLength" option.
207 Examples
209 To read the contents of the file "file1.txt.gz" and write the
210 uncompressed data to the file "file1.txt".
211 use strict ;
213 use warnings ;
214 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
215 my $input = "file1.txt.gz";
217 my $output = "file1.txt";
218 gunzip $input => $output
219 or die "gunzip failed: $GunzipError\n";
220 To read from an existing Perl filehandle, $input, and write the
222 uncompressed data to a buffer, $buffer.
223 use strict ;
225 use warnings ;
226 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
227 use IO::File ;
228 my $input = new IO::File "<file1.txt.gz"
230 or die "Cannot open 'file1.txt.gz': $!\n" ;
231 my $buffer ;
232 gunzip $input => \$buffer
233 or die "gunzip failed: $GunzipError\n";
234 To uncompress all files in the directory "/my/home" that match
236 "*.txt.gz" and store the compressed data in the same directory
237 use strict ;
239 use warnings ;
240 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
241 gunzip '</my/home/*.txt.gz>' => '</my/home/#1.txt>'
243 or die "gunzip failed: $GunzipError\n";
244 and if you want to compress each file one at a time, this will do the
246 trick
247 use strict ;
249 use warnings ;
250 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
251 for my $input ( glob "/my/home/*.txt.gz" )
253 {
254 my $output = $input;
255 $output =~ s/.gz// ;
256 gunzip $input => $output
257 or die "Error compressing '$input': $GunzipError\n";
258 }
259
261 Constructor
262 The format of the constructor for IO::Uncompress::Gunzip is shown below
263 my $z = new IO::Uncompress::Gunzip $input [OPTS]
265 or die "IO::Uncompress::Gunzip failed: $GunzipError\n";
266 Returns an "IO::Uncompress::Gunzip" object on success and undef on
268 failure. The variable $GunzipError will contain an error message on
269 failure.
270 If you are running Perl 5.005 or better the object, $z, returned from
272 IO::Uncompress::Gunzip can be used exactly like an IO::File filehandle.
273 This means that all normal input file operations can be carried out
274 with $z. For example, to read a line from a compressed file/buffer you
275 can use either of these forms
276 $line = $z->getline();
278 $line = <$z>;
279 The mandatory parameter $input is used to determine the source of the
281 compressed data. This parameter can take one of three forms.
282 A filename
284 If the $input parameter is a scalar, it is assumed to be a
285 filename. This file will be opened for reading and the compressed
286 data will be read from it.
287 A filehandle
289 If the $input parameter is a filehandle, the compressed data will
290 be read from it. The string '-' can be used as an alias for
291 standard input.
292 A scalar reference
294 If $input is a scalar reference, the compressed data will be read
295 from $$output.
296 Constructor Options
298 The option names defined below are case insensitive and can be
299 optionally prefixed by a '-'. So all of the following are valid
300 -AutoClose
302 -autoclose
303 AUTOCLOSE
304 autoclose
305 OPTS is a combination of the following options:
307 "AutoClose => 0|1"
309 This option is only valid when the $input parameter is a
310 filehandle. If specified, and the value is true, it will result in
311 the file being closed once either the "close" method is called or
312 the IO::Uncompress::Gunzip object is destroyed.
313 This parameter defaults to 0.
315 "MultiStream => 0|1"
317 Allows multiple concatenated compressed streams to be treated as a
318 single compressed stream. Decompression will stop once either the
319 end of the file/buffer is reached, an error is encountered
320 (premature eof, corrupt compressed data) or the end of a stream is
321 not immediately followed by the start of another stream.
322 This parameter defaults to 0.
324 "Prime => $string"
326 This option will uncompress the contents of $string before
327 processing the input file/buffer.
328 This option can be useful when the compressed data is embedded in
330 another file/data structure and it is not possible to work out
331 where the compressed data begins without having to read the first
332 few bytes. If this is the case, the uncompression can be primed
333 with these bytes using this option.
334 "Transparent => 0|1"
336 If this option is set and the input file/buffer is not compressed
337 data, the module will allow reading of it anyway.
338 In addition, if the input file/buffer does contain compressed data
340 and there is non-compressed data immediately following it, setting
341 this option will make this module treat the whole file/bufffer as
342 a single data stream.
343 This option defaults to 1.
345 "BlockSize => $num"
347 When reading the compressed input data, IO::Uncompress::Gunzip
348 will read it in blocks of $num bytes.
349 This option defaults to 4096.
351 "InputLength => $size"
353 When present this option will limit the number of compressed bytes
354 read from the input file/buffer to $size. This option can be used
355 in the situation where there is useful data directly after the
356 compressed data stream and you know beforehand the exact length of
357 the compressed data stream.
358 This option is mostly used when reading from a filehandle, in
360 which case the file pointer will be left pointing to the first
361 byte directly after the compressed data stream.
362 This option defaults to off.
364 "Append => 0|1"
366 This option controls what the "read" method does with uncompressed
367 data.
368 If set to 1, all uncompressed data will be appended to the output
370 parameter of the "read" method.
371 If set to 0, the contents of the output parameter of the "read"
373 method will be overwritten by the uncompressed data.
374 Defaults to 0.
376 "Strict => 0|1"
378 This option controls whether the extra checks defined below are
379 used when carrying out the decompression. When Strict is on, the
380 extra tests are carried out, when Strict is off they are not.
381 The default for this option is off.
383 1. If the FHCRC bit is set in the gzip FLG header byte, the
385 CRC16 bytes in the header must match the crc16 value of the
386 gzip header actually read.
387 2. If the gzip header contains a name field (FNAME) it consists
389 solely of ISO 8859-1 characters.
390 3. If the gzip header contains a comment field (FCOMMENT) it
392 consists solely of ISO 8859-1 characters plus line-feed.
393 4. If the gzip FEXTRA header field is present it must conform to
395 the sub-field structure as defined in RFC 1952.
396 5. The CRC32 and ISIZE trailer fields must be present.
398 6. The value of the CRC32 field read must match the crc32 value
400 of the uncompressed data actually contained in the gzip file.
401 7. The value of the ISIZE fields read must match the length of
403 the uncompressed data actually read from the file.
404 "ParseExtra => 0|1" If the gzip FEXTRA header field is present and this
406 option is set, it will force the module to check that it conforms to
407 the sub-field structure as defined in RFC 1952.
408 If the "Strict" is on it will automatically enable this option.
409 Defaults to 0.
411 Examples
413 TODO
414
416 read
417 Usage is
418 $status = $z->read($buffer)
420 Reads a block of compressed data (the size the the compressed block is
422 determined by the "Buffer" option in the constructor), uncompresses it
423 and writes any uncompressed data into $buffer. If the "Append"
424 parameter is set in the constructor, the uncompressed data will be
425 appended to the $buffer parameter. Otherwise $buffer will be
426 overwritten.
427 Returns the number of uncompressed bytes written to $buffer, zero if
429 eof or a negative number on error.
430 read
432 Usage is
433 $status = $z->read($buffer, $length)
435 $status = $z->read($buffer, $length, $offset)
436 $status = read($z, $buffer, $length)
438 $status = read($z, $buffer, $length, $offset)
439 Attempt to read $length bytes of uncompressed data into $buffer.
441 The main difference between this form of the "read" method and the
443 previous one, is that this one will attempt to return exactly $length
444 bytes. The only circumstances that this function will not is if end-of-
445 file or an IO error is encountered.
446 Returns the number of uncompressed bytes written to $buffer, zero if
448 eof or a negative number on error.
449 getline
451 Usage is
452 $line = $z->getline()
454 $line = <$z>
455 Reads a single line.
457 This method fully supports the use of of the variable $/ (or
459 $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
460 what constitutes an end of line. Paragraph mode, record mode and file
461 slurp mode are all supported.
462 getc
464 Usage is
465 $char = $z->getc()
467 Read a single character.
469 ungetc
471 Usage is
472 $char = $z->ungetc($string)
474 inflateSync
476 Usage is
477 $status = $z->inflateSync()
479 TODO
481 getHeaderInfo
483 Usage is
484 $hdr = $z->getHeaderInfo();
486 @hdrs = $z->getHeaderInfo();
487 This method returns either a hash reference (in scalar context) or a
489 list or hash references (in array context) that contains information
490 about each of the header fields in the compressed data stream(s).
491 Name The contents of the Name header field, if present. If no name is
493 present, the value will be undef. Note this is different from a
494 zero length name, which will return an empty string.
495 Comment
497 The contents of the Comment header field, if present. If no
498 comment is present, the value will be undef. Note this is
499 different from a zero length comment, which will return an empty
500 string.
501 tell
503 Usage is
504 $z->tell()
506 tell $z
507 Returns the uncompressed file offset.
509 eof
511 Usage is
512 $z->eof();
514 eof($z);
515 Returns true if the end of the compressed input stream has been
517 reached.
518 seek
520 $z->seek($position, $whence);
521 seek($z, $position, $whence);
522 Provides a sub-set of the "seek" functionality, with the restriction
524 that it is only legal to seek forward in the input file/buffer. It is
525 a fatal error to attempt to seek backward.
526 The $whence parameter takes one the usual values, namely SEEK_SET,
528 SEEK_CUR or SEEK_END.
529 Returns 1 on success, 0 on failure.
531 binmode
533 Usage is
534 $z->binmode
536 binmode $z ;
537 This is a noop provided for completeness.
539 opened
541 $z->opened()
542 Returns true if the object currently refers to a opened file/buffer.
544 autoflush
546 my $prev = $z->autoflush()
547 my $prev = $z->autoflush(EXPR)
548 If the $z object is associated with a file or a filehandle, this method
550 returns the current autoflush setting for the underlying filehandle. If
551 "EXPR" is present, and is non-zero, it will enable flushing after every
552 write/print operation.
553 If $z is associated with a buffer, this method has no effect and always
555 returns "undef".
556 Note that the special variable $| cannot be used to set or retrieve the
558 autoflush setting.
559 input_line_number
561 $z->input_line_number()
562 $z->input_line_number(EXPR)
563 Returns the current uncompressed line number. If "EXPR" is present it
565 has the effect of setting the line number. Note that setting the line
566 number does not change the current position within the file/buffer
567 being read.
568 The contents of $/ are used to to determine what constitutes a line
570 terminator.
571 fileno
573 $z->fileno()
574 fileno($z)
575 If the $z object is associated with a file or a filehandle, "fileno"
577 will return the underlying file descriptor. Once the "close" method is
578 called "fileno" will return "undef".
579 If the $z object is is associated with a buffer, this method will
581 return "undef".
582 close
584 $z->close() ;
585 close $z ;
586 Closes the output file/buffer.
588 For most versions of Perl this method will be automatically invoked if
590 the IO::Uncompress::Gunzip object is destroyed (either explicitly or by
591 the variable with the reference to the object going out of scope). The
592 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
593 cases, the "close" method will be called automatically, but not until
594 global destruction of all live objects when the program is terminating.
595 Therefore, if you want your scripts to be able to run on all versions
597 of Perl, you should call "close" explicitly and not rely on automatic
598 closing.
599 Returns true on success, otherwise 0.
601 If the "AutoClose" option has been enabled when the
603 IO::Uncompress::Gunzip object was created, and the object is associated
604 with a file, the underlying file will also be closed.
605 nextStream
607 Usage is
608 my $status = $z->nextStream();
610 Skips to the next compressed data stream in the input file/buffer. If a
612 new compressed data stream is found, the eof marker will be cleared and
613 $. will be reset to 0.
614 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
616 error was encountered.
617 trailingData
619 Usage is
620 my $data = $z->trailingData();
622 Returns the data, if any, that is present immediately after the
624 compressed data stream once uncompression is complete. It only makes
625 sense to call this method once the end of the compressed data stream
626 has been encountered.
627 This option can be used when there is useful information immediately
629 following the compressed data stream, and you don't know the length of
630 the compressed data stream.
631 If the input is a buffer, "trailingData" will return everything from
633 the end of the compressed data stream to the end of the buffer.
634 If the input is a filehandle, "trailingData" will return the data that
636 is left in the filehandle input buffer once the end of the compressed
637 data stream has been reached. You can then use the filehandle to read
638 the rest of the input file.
639 Don't bother using "trailingData" if the input is a filename.
641 If you know the length of the compressed data stream before you start
643 uncompressing, you can avoid having to use "trailingData" by setting
644 the "InputLength" option in the constructor.
645
647 No symbolic constants are required by this IO::Uncompress::Gunzip at
648 present.
649 :all Imports "gunzip" and $GunzipError. Same as doing this
651 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
653
655 Working with Net::FTP
656 See IO::Uncompress::Gunzip::FAQ
657
659 Compress::Zlib, IO::Compress::Gzip, IO::Compress::Deflate,
660 IO::Uncompress::Inflate, IO::Compress::RawDeflate,
661 IO::Uncompress::RawInflate, IO::Compress::Bzip2,
662 IO::Uncompress::Bunzip2, IO::Compress::Lzop, IO::Uncompress::UnLzop,
663 IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Uncompress::AnyInflate,
664 IO::Uncompress::AnyUncompress
665 Compress::Zlib::FAQ
667 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
669 For RFC 1950, 1951 and 1952 see http://www.faqs.org/rfcs/rfc1950.html,
671 http://www.faqs.org/rfcs/rfc1951.html and
672 http://www.faqs.org/rfcs/rfc1952.html
673 The zlib compression library was written by Jean-loup Gailly
675 gzip@prep.ai.mit.edu and Mark Adler madler@alumni.caltech.edu.
676 The primary site for the zlib compression library is
678 http://www.zlib.org.
679 The primary site for gzip is http://www.gzip.org.
681
683 This module was written by Paul Marquess, pmqs@cpan.org.
684
686 See the Changes file.
687
689 Copyright (c) 2005-2009 Paul Marquess. All rights reserved.
690 This program is free software; you can redistribute it and/or modify it
692 under the same terms as Perl itself.
693perl v5.10.1 2017-03-22 IO::Uncompress::Gunzip(3pm)