1IO::Uncompress::Gunzip(U3s)er Contributed Perl DocumentatIiOo:n:Uncompress::Gunzip(3)
2
3
4
6 IO::Uncompress::Gunzip - Read RFC 1952 files/buffers
7
9 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
10
11 my $status = gunzip $input => $output [,OPTS]
12 or die "gunzip failed: $GunzipError\n";
13
14 my $z = new IO::Uncompress::Gunzip $input [OPTS]
15 or die "gunzip failed: $GunzipError\n";
16
17 $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
25 $status = $z->inflateSync()
26
27 $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
37 $GunzipError ;
38
39 # IO::File mode
40
41 <$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
56 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
64 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
65
66 gunzip $input_filename_or_reference => $output_filename_or_reference [,OPTS]
67 or die "gunzip failed: $GunzipError\n";
68
69 The functional interface needs Perl5.005 or better.
70
71 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
76 The $input_filename_or_reference parameter
77
78 The parameter, $input_filename_or_reference, is used to define the
79 source of the compressed data.
80
81 It can take one of the following forms:
82
83 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
88 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
93 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
97 An array reference
98 If $input_filename_or_reference is an array reference, each
99 element in the array must be a filename.
100
101 The input data will be read from each file in turn.
102
103 The complete array will be walked to ensure that it only contains
104 valid filenames before any data is uncompressed.
105
106 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
112 See File::GlobMapper for more details.
113
114 If the $input_filename_or_reference parameter is any other type,
115 "undef" will be returned.
116
117 The $output_filename_or_reference parameter
118
119 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
123 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
128 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
133 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
138 An Array Reference
139 If $output_filename_or_reference is an array reference, the
140 uncompressed data will be pushed onto the array.
141
142 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
148 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
152 See File::GlobMapper for more details.
153
154 If the $output_filename_or_reference parameter is any other type,
155 "undef" will be returned.
156
157 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
164 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
169 "AutoClose => 0|1"
170 This option applies to any input or output data streams to
171 "gunzip" that are filehandles.
172
173 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
177 This parameter defaults to 0.
178
179 "BinModeOut => 0|1"
180 This option is now a no-op. All files will be written in binmode.
181
182 "Append => 0|1"
183 The behaviour of this option is dependent on the type of output
184 data stream.
185
186 · A Buffer
187
188 If "Append" is enabled, all uncompressed data will be append
189 to the end of the output buffer. Otherwise the output buffer
190 will be cleared before any uncompressed data is written to
191 it.
192
193 · A Filename
194
195 If "Append" is enabled, the file will be opened in append
196 mode. Otherwise the contents of the file, if any, will be
197 truncated before any uncompressed data is written to it.
198
199 · A Filehandle
200
201 If "Append" is enabled, the filehandle will be positioned to
202 the end of the file via a call to "seek" before any
203 uncompressed data is written to it. Otherwise the file
204 pointer will not be moved.
205
206 When "Append" is specified, and set to true, it will append all
207 uncompressed data to the output data stream.
208
209 So when the output is a filehandle it will carry out a seek to the
210 eof before writing any uncompressed data. If the output is a
211 filename, it will be opened for appending. If the output is a
212 buffer, all uncompressed data will be appended to the existing
213 buffer.
214
215 Conversely when "Append" is not specified, or it is present and is
216 set to false, it will operate as follows.
217
218 When the output is a filename, it will truncate the contents of
219 the file before writing any uncompressed data. If the output is a
220 filehandle its position will not be changed. If the output is a
221 buffer, it will be wiped before any uncompressed data is output.
222
223 Defaults to 0.
224
225 "MultiStream => 0|1"
226 If the input file/buffer contains multiple compressed data
227 streams, this option will uncompress the whole lot as a single
228 data stream.
229
230 Defaults to 0.
231
232 "TrailingData => $scalar"
233 Returns the data, if any, that is present immediately after the
234 compressed data stream once uncompression is complete.
235
236 This option can be used when there is useful information
237 immediately following the compressed data stream, and you don't
238 know the length of the compressed data stream.
239
240 If the input is a buffer, "trailingData" will return everything
241 from the end of the compressed data stream to the end of the
242 buffer.
243
244 If the input is a filehandle, "trailingData" will return the data
245 that is left in the filehandle input buffer once the end of the
246 compressed data stream has been reached. You can then use the
247 filehandle to read the rest of the input file.
248
249 Don't bother using "trailingData" if the input is a filename.
250
251 If you know the length of the compressed data stream before you
252 start uncompressing, you can avoid having to use "trailingData" by
253 setting the "InputLength" option.
254
255 Examples
256 To read the contents of the file "file1.txt.gz" and write the
257 uncompressed data to the file "file1.txt".
258
259 use strict ;
260 use warnings ;
261 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
262
263 my $input = "file1.txt.gz";
264 my $output = "file1.txt";
265 gunzip $input => $output
266 or die "gunzip failed: $GunzipError\n";
267
268 To read from an existing Perl filehandle, $input, and write the
269 uncompressed data to a buffer, $buffer.
270
271 use strict ;
272 use warnings ;
273 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
274 use IO::File ;
275
276 my $input = new IO::File "<file1.txt.gz"
277 or die "Cannot open 'file1.txt.gz': $!\n" ;
278 my $buffer ;
279 gunzip $input => \$buffer
280 or die "gunzip failed: $GunzipError\n";
281
282 To uncompress all files in the directory "/my/home" that match
283 "*.txt.gz" and store the compressed data in the same directory
284
285 use strict ;
286 use warnings ;
287 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
288
289 gunzip '</my/home/*.txt.gz>' => '</my/home/#1.txt>'
290 or die "gunzip failed: $GunzipError\n";
291
292 and if you want to compress each file one at a time, this will do the
293 trick
294
295 use strict ;
296 use warnings ;
297 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
298
299 for my $input ( glob "/my/home/*.txt.gz" )
300 {
301 my $output = $input;
302 $output =~ s/.gz// ;
303 gunzip $input => $output
304 or die "Error compressing '$input': $GunzipError\n";
305 }
306
308 Constructor
309 The format of the constructor for IO::Uncompress::Gunzip is shown below
310
311 my $z = new IO::Uncompress::Gunzip $input [OPTS]
312 or die "IO::Uncompress::Gunzip failed: $GunzipError\n";
313
314 Returns an "IO::Uncompress::Gunzip" object on success and undef on
315 failure. The variable $GunzipError will contain an error message on
316 failure.
317
318 If you are running Perl 5.005 or better the object, $z, returned from
319 IO::Uncompress::Gunzip can be used exactly like an IO::File filehandle.
320 This means that all normal input file operations can be carried out
321 with $z. For example, to read a line from a compressed file/buffer you
322 can use either of these forms
323
324 $line = $z->getline();
325 $line = <$z>;
326
327 The mandatory parameter $input is used to determine the source of the
328 compressed data. This parameter can take one of three forms.
329
330 A filename
331 If the $input parameter is a scalar, it is assumed to be a
332 filename. This file will be opened for reading and the compressed
333 data will be read from it.
334
335 A filehandle
336 If the $input parameter is a filehandle, the compressed data will
337 be read from it. The string '-' can be used as an alias for
338 standard input.
339
340 A scalar reference
341 If $input is a scalar reference, the compressed data will be read
342 from $$input.
343
344 Constructor Options
345 The option names defined below are case insensitive and can be
346 optionally prefixed by a '-'. So all of the following are valid
347
348 -AutoClose
349 -autoclose
350 AUTOCLOSE
351 autoclose
352
353 OPTS is a combination of the following options:
354
355 "AutoClose => 0|1"
356 This option is only valid when the $input parameter is a
357 filehandle. If specified, and the value is true, it will result in
358 the file being closed once either the "close" method is called or
359 the IO::Uncompress::Gunzip object is destroyed.
360
361 This parameter defaults to 0.
362
363 "MultiStream => 0|1"
364 Allows multiple concatenated compressed streams to be treated as a
365 single compressed stream. Decompression will stop once either the
366 end of the file/buffer is reached, an error is encountered
367 (premature eof, corrupt compressed data) or the end of a stream is
368 not immediately followed by the start of another stream.
369
370 This parameter defaults to 0.
371
372 "Prime => $string"
373 This option will uncompress the contents of $string before
374 processing the input file/buffer.
375
376 This option can be useful when the compressed data is embedded in
377 another file/data structure and it is not possible to work out
378 where the compressed data begins without having to read the first
379 few bytes. If this is the case, the uncompression can be primed
380 with these bytes using this option.
381
382 "Transparent => 0|1"
383 If this option is set and the input file/buffer is not compressed
384 data, the module will allow reading of it anyway.
385
386 In addition, if the input file/buffer does contain compressed data
387 and there is non-compressed data immediately following it, setting
388 this option will make this module treat the whole file/buffer as a
389 single data stream.
390
391 This option defaults to 1.
392
393 "BlockSize => $num"
394 When reading the compressed input data, IO::Uncompress::Gunzip
395 will read it in blocks of $num bytes.
396
397 This option defaults to 4096.
398
399 "InputLength => $size"
400 When present this option will limit the number of compressed bytes
401 read from the input file/buffer to $size. This option can be used
402 in the situation where there is useful data directly after the
403 compressed data stream and you know beforehand the exact length of
404 the compressed data stream.
405
406 This option is mostly used when reading from a filehandle, in
407 which case the file pointer will be left pointing to the first
408 byte directly after the compressed data stream.
409
410 This option defaults to off.
411
412 "Append => 0|1"
413 This option controls what the "read" method does with uncompressed
414 data.
415
416 If set to 1, all uncompressed data will be appended to the output
417 parameter of the "read" method.
418
419 If set to 0, the contents of the output parameter of the "read"
420 method will be overwritten by the uncompressed data.
421
422 Defaults to 0.
423
424 "Strict => 0|1"
425 This option controls whether the extra checks defined below are
426 used when carrying out the decompression. When Strict is on, the
427 extra tests are carried out, when Strict is off they are not.
428
429 The default for this option is off.
430
431 1. If the FHCRC bit is set in the gzip FLG header byte, the
432 CRC16 bytes in the header must match the crc16 value of the
433 gzip header actually read.
434
435 2. If the gzip header contains a name field (FNAME) it consists
436 solely of ISO 8859-1 characters.
437
438 3. If the gzip header contains a comment field (FCOMMENT) it
439 consists solely of ISO 8859-1 characters plus line-feed.
440
441 4. If the gzip FEXTRA header field is present it must conform to
442 the sub-field structure as defined in RFC 1952.
443
444 5. The CRC32 and ISIZE trailer fields must be present.
445
446 6. The value of the CRC32 field read must match the crc32 value
447 of the uncompressed data actually contained in the gzip file.
448
449 7. The value of the ISIZE fields read must match the length of
450 the uncompressed data actually read from the file.
451
452 "ParseExtra => 0|1" If the gzip FEXTRA header field is present and this
453 option is set, it will force the module to check that it conforms to
454 the sub-field structure as defined in RFC 1952.
455 If the "Strict" is on it will automatically enable this option.
456
457 Defaults to 0.
458
459 Examples
460 TODO
461
463 read
464 Usage is
465
466 $status = $z->read($buffer)
467
468 Reads a block of compressed data (the size of the compressed block is
469 determined by the "Buffer" option in the constructor), uncompresses it
470 and writes any uncompressed data into $buffer. If the "Append"
471 parameter is set in the constructor, the uncompressed data will be
472 appended to the $buffer parameter. Otherwise $buffer will be
473 overwritten.
474
475 Returns the number of uncompressed bytes written to $buffer, zero if
476 eof or a negative number on error.
477
478 read
479 Usage is
480
481 $status = $z->read($buffer, $length)
482 $status = $z->read($buffer, $length, $offset)
483
484 $status = read($z, $buffer, $length)
485 $status = read($z, $buffer, $length, $offset)
486
487 Attempt to read $length bytes of uncompressed data into $buffer.
488
489 The main difference between this form of the "read" method and the
490 previous one, is that this one will attempt to return exactly $length
491 bytes. The only circumstances that this function will not is if end-of-
492 file or an IO error is encountered.
493
494 Returns the number of uncompressed bytes written to $buffer, zero if
495 eof or a negative number on error.
496
497 getline
498 Usage is
499
500 $line = $z->getline()
501 $line = <$z>
502
503 Reads a single line.
504
505 This method fully supports the use of the variable $/ (or
506 $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
507 what constitutes an end of line. Paragraph mode, record mode and file
508 slurp mode are all supported.
509
510 getc
511 Usage is
512
513 $char = $z->getc()
514
515 Read a single character.
516
517 ungetc
518 Usage is
519
520 $char = $z->ungetc($string)
521
522 inflateSync
523 Usage is
524
525 $status = $z->inflateSync()
526
527 TODO
528
529 getHeaderInfo
530 Usage is
531
532 $hdr = $z->getHeaderInfo();
533 @hdrs = $z->getHeaderInfo();
534
535 This method returns either a hash reference (in scalar context) or a
536 list or hash references (in array context) that contains information
537 about each of the header fields in the compressed data stream(s).
538
539 Name The contents of the Name header field, if present. If no name is
540 present, the value will be undef. Note this is different from a
541 zero length name, which will return an empty string.
542
543 Comment
544 The contents of the Comment header field, if present. If no
545 comment is present, the value will be undef. Note this is
546 different from a zero length comment, which will return an empty
547 string.
548
549 tell
550 Usage is
551
552 $z->tell()
553 tell $z
554
555 Returns the uncompressed file offset.
556
557 eof
558 Usage is
559
560 $z->eof();
561 eof($z);
562
563 Returns true if the end of the compressed input stream has been
564 reached.
565
566 seek
567 $z->seek($position, $whence);
568 seek($z, $position, $whence);
569
570 Provides a sub-set of the "seek" functionality, with the restriction
571 that it is only legal to seek forward in the input file/buffer. It is
572 a fatal error to attempt to seek backward.
573
574 Note that the implementation of "seek" in this module does not provide
575 true random access to a compressed file/buffer. It works by
576 uncompressing data from the current offset in the file/buffer until it
577 reaches the uncompressed offset specified in the parameters to "seek".
578 For very small files this may be acceptable behaviour. For large files
579 it may cause an unacceptable delay.
580
581 The $whence parameter takes one the usual values, namely SEEK_SET,
582 SEEK_CUR or SEEK_END.
583
584 Returns 1 on success, 0 on failure.
585
586 binmode
587 Usage is
588
589 $z->binmode
590 binmode $z ;
591
592 This is a noop provided for completeness.
593
594 opened
595 $z->opened()
596
597 Returns true if the object currently refers to a opened file/buffer.
598
599 autoflush
600 my $prev = $z->autoflush()
601 my $prev = $z->autoflush(EXPR)
602
603 If the $z object is associated with a file or a filehandle, this method
604 returns the current autoflush setting for the underlying filehandle. If
605 "EXPR" is present, and is non-zero, it will enable flushing after every
606 write/print operation.
607
608 If $z is associated with a buffer, this method has no effect and always
609 returns "undef".
610
611 Note that the special variable $| cannot be used to set or retrieve the
612 autoflush setting.
613
614 input_line_number
615 $z->input_line_number()
616 $z->input_line_number(EXPR)
617
618 Returns the current uncompressed line number. If "EXPR" is present it
619 has the effect of setting the line number. Note that setting the line
620 number does not change the current position within the file/buffer
621 being read.
622
623 The contents of $/ are used to determine what constitutes a line
624 terminator.
625
626 fileno
627 $z->fileno()
628 fileno($z)
629
630 If the $z object is associated with a file or a filehandle, "fileno"
631 will return the underlying file descriptor. Once the "close" method is
632 called "fileno" will return "undef".
633
634 If the $z object is associated with a buffer, this method will return
635 "undef".
636
637 close
638 $z->close() ;
639 close $z ;
640
641 Closes the output file/buffer.
642
643 For most versions of Perl this method will be automatically invoked if
644 the IO::Uncompress::Gunzip object is destroyed (either explicitly or by
645 the variable with the reference to the object going out of scope). The
646 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
647 cases, the "close" method will be called automatically, but not until
648 global destruction of all live objects when the program is terminating.
649
650 Therefore, if you want your scripts to be able to run on all versions
651 of Perl, you should call "close" explicitly and not rely on automatic
652 closing.
653
654 Returns true on success, otherwise 0.
655
656 If the "AutoClose" option has been enabled when the
657 IO::Uncompress::Gunzip object was created, and the object is associated
658 with a file, the underlying file will also be closed.
659
660 nextStream
661 Usage is
662
663 my $status = $z->nextStream();
664
665 Skips to the next compressed data stream in the input file/buffer. If a
666 new compressed data stream is found, the eof marker will be cleared and
667 $. will be reset to 0.
668
669 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
670 error was encountered.
671
672 trailingData
673 Usage is
674
675 my $data = $z->trailingData();
676
677 Returns the data, if any, that is present immediately after the
678 compressed data stream once uncompression is complete. It only makes
679 sense to call this method once the end of the compressed data stream
680 has been encountered.
681
682 This option can be used when there is useful information immediately
683 following the compressed data stream, and you don't know the length of
684 the compressed data stream.
685
686 If the input is a buffer, "trailingData" will return everything from
687 the end of the compressed data stream to the end of the buffer.
688
689 If the input is a filehandle, "trailingData" will return the data that
690 is left in the filehandle input buffer once the end of the compressed
691 data stream has been reached. You can then use the filehandle to read
692 the rest of the input file.
693
694 Don't bother using "trailingData" if the input is a filename.
695
696 If you know the length of the compressed data stream before you start
697 uncompressing, you can avoid having to use "trailingData" by setting
698 the "InputLength" option in the constructor.
699
701 No symbolic constants are required by this IO::Uncompress::Gunzip at
702 present.
703
704 :all Imports "gunzip" and $GunzipError. Same as doing this
705
706 use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
707
709 Working with Net::FTP
710 See IO::Compress::FAQ
711
713 Compress::Zlib, IO::Compress::Gzip, IO::Compress::Deflate,
714 IO::Uncompress::Inflate, IO::Compress::RawDeflate,
715 IO::Uncompress::RawInflate, IO::Compress::Bzip2,
716 IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma,
717 IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzip,
718 IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop,
719 IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd,
720 IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate,
721 IO::Uncompress::AnyUncompress
722
723 IO::Compress::FAQ
724
725 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
726
727 For RFC 1950, 1951 and 1952 see
728 <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
732 The zlib compression library was written by Jean-loup Gailly
733 "gzip@prep.ai.mit.edu" and Mark Adler "madler@alumni.caltech.edu".
734
735 The primary site for the zlib compression library is
736 <http://www.zlib.org>.
737
738 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-2019 Paul Marquess. All rights reserved.
748
749 This program is free software; you can redistribute it and/or modify it
750 under the same terms as Perl itself.
751
752
753
754perl v5.30.0 2019-08-12 IO::Uncompress::Gunzip(3)