IO::Uncompress::Unzip(3pm)

1IO::Uncompress::Unzip(3U)ser Contributed Perl DocumentatiIoOn::Uncompress::Unzip(3)
2
3
4

NAME

6       IO::Uncompress::Unzip - Read zip files/buffers
7

SYNOPSIS

9           use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
10
11           my $status = unzip $input => $output [,OPTS]
12               or die "unzip failed: $UnzipError\n";
13
14           my $z = IO::Uncompress::Unzip->new( $input [OPTS] )
15               or die "unzip failed: $UnzipError\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           $UnzipError ;
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

DESCRIPTION

53       This module provides a Perl interface that allows the reading of zlib
54       files/buffers.
55
56       For writing zip files/buffers, see the companion module
57       IO::Compress::Zip.
58
59       The primary purpose of this module is to provide streaming read access
60       to zip files and buffers.
61
62       At present the following compression methods are supported by
63       IO::Uncompress::Unzip
64
65       Store (0)
66       Deflate (8)
67       Bzip2 (12)
68            To read Bzip2 content, the module "IO::Uncompress::Bunzip2" must
69            be installed.
70
71       Lzma (14)
72            To read LZMA content, the module "IO::Uncompress::UnLzma" must be
73            installed.
74
75       Xz (95)
76            To read Xz content, the module "IO::Uncompress::UnXz" must be
77            installed.
78
79       Zstandard (93)
80            To read Zstandard content, the module "IO::Uncompress::UnZstd"
81            must be installed.
82

Functional Interface

84       A top-level function, "unzip", is provided to carry out "one-shot"
85       uncompression between buffers and/or files. For finer control over the
86       uncompression process, see the "OO Interface" section.
87
88           use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
89
90           unzip $input_filename_or_reference => $output_filename_or_reference [,OPTS]
91               or die "unzip failed: $UnzipError\n";
92
93       The functional interface needs Perl5.005 or better.
94
95   unzip $input_filename_or_reference => $output_filename_or_reference [,
96       OPTS]
97       "unzip" expects at least two parameters, $input_filename_or_reference
98       and $output_filename_or_reference and zero or more optional parameters
99       (see "Optional Parameters")
100
101       The $input_filename_or_reference parameter
102
103       The parameter, $input_filename_or_reference, is used to define the
104       source of the compressed data.
105
106       It can take one of the following forms:
107
108       A filename
109            If the $input_filename_or_reference parameter is a simple scalar,
110            it is assumed to be a filename. This file will be opened for
111            reading and the input data will be read from it.
112
113       A filehandle
114            If the $input_filename_or_reference parameter is a filehandle, the
115            input data will be read from it.  The string '-' can be used as an
116            alias for standard input.
117
118       A scalar reference
119            If $input_filename_or_reference is a scalar reference, the input
120            data will be read from $$input_filename_or_reference.
121
122       An array reference
123            If $input_filename_or_reference is an array reference, each
124            element in the array must be a filename.
125
126            The input data will be read from each file in turn.
127
128            The complete array will be walked to ensure that it only contains
129            valid filenames before any data is uncompressed.
130
131       An Input FileGlob string
132            If $input_filename_or_reference is a string that is delimited by
133            the characters "<" and ">" "unzip" will assume that it is an input
134            fileglob string. The input is the list of files that match the
135            fileglob.
136
137            See File::GlobMapper for more details.
138
139       If the $input_filename_or_reference parameter is any other type,
140       "undef" will be returned.
141
142       The $output_filename_or_reference parameter
143
144       The parameter $output_filename_or_reference is used to control the
145       destination of the uncompressed data. This parameter can take one of
146       these forms.
147
148       A filename
149            If the $output_filename_or_reference parameter is a simple scalar,
150            it is assumed to be a filename.  This file will be opened for
151            writing and the uncompressed data will be written to it.
152
153       A filehandle
154            If the $output_filename_or_reference parameter is a filehandle,
155            the uncompressed data will be written to it.  The string '-' can
156            be used as an alias for standard output.
157
158       A scalar reference
159            If $output_filename_or_reference is a scalar reference, the
160            uncompressed data will be stored in
161            $$output_filename_or_reference.
162
163       An Array Reference
164            If $output_filename_or_reference is an array reference, the
165            uncompressed data will be pushed onto the array.
166
167       An Output FileGlob
168            If $output_filename_or_reference is a string that is delimited by
169            the characters "<" and ">" "unzip" will assume that it is an
170            output fileglob string. The output is the list of files that match
171            the fileglob.
172
173            When $output_filename_or_reference is an fileglob string,
174            $input_filename_or_reference must also be a fileglob string.
175            Anything else is an error.
176
177            See File::GlobMapper for more details.
178
179       If the $output_filename_or_reference parameter is any other type,
180       "undef" will be returned.
181
182   Notes
183       When $input_filename_or_reference maps to multiple compressed
184       files/buffers and $output_filename_or_reference is a single
185       file/buffer, after uncompression $output_filename_or_reference will
186       contain a concatenation of all the uncompressed data from each of the
187       input files/buffers.
188
189   Optional Parameters
190       The optional parameters for the one-shot function "unzip" are (for the
191       most part) identical to those used with the OO interface defined in the
192       "Constructor Options" section. The exceptions are listed below
193
194       "AutoClose => 0|1"
195            This option applies to any input or output data streams to "unzip"
196            that are filehandles.
197
198            If "AutoClose" is specified, and the value is true, it will result
199            in all input and/or output filehandles being closed once "unzip"
200            has completed.
201
202            This parameter defaults to 0.
203
204       "BinModeOut => 0|1"
205            This option is now a no-op. All files will be written  in binmode.
206
207       "Append => 0|1"
208            The behaviour of this option is dependent on the type of output
209            data stream.
210
211            •    A Buffer
212
213                 If "Append" is enabled, all uncompressed data will be append
214                 to the end of the output buffer. Otherwise the output buffer
215                 will be cleared before any uncompressed data is written to
216                 it.
217
218            •    A Filename
219
220                 If "Append" is enabled, the file will be opened in append
221                 mode. Otherwise the contents of the file, if any, will be
222                 truncated before any uncompressed data is written to it.
223
224            •    A Filehandle
225
226                 If "Append" is enabled, the filehandle will be positioned to
227                 the end of the file via a call to "seek" before any
228                 uncompressed data is written to it.  Otherwise the file
229                 pointer will not be moved.
230
231            When "Append" is specified, and set to true, it will append all
232            uncompressed data to the output data stream.
233
234            So when the output is a filehandle it will carry out a seek to the
235            eof before writing any uncompressed data. If the output is a
236            filename, it will be opened for appending. If the output is a
237            buffer, all uncompressed data will be appended to the existing
238            buffer.
239
240            Conversely when "Append" is not specified, or it is present and is
241            set to false, it will operate as follows.
242
243            When the output is a filename, it will truncate the contents of
244            the file before writing any uncompressed data. If the output is a
245            filehandle its position will not be changed. If the output is a
246            buffer, it will be wiped before any uncompressed data is output.
247
248            Defaults to 0.
249
250       "MultiStream => 0|1"
251            If the input file/buffer contains multiple compressed data
252            streams, this option will uncompress the whole lot as a single
253            data stream.
254
255            Defaults to 0.
256
257       "TrailingData => $scalar"
258            Returns the data, if any, that is present immediately after the
259            compressed data stream once uncompression is complete.
260
261            This option can be used when there is useful information
262            immediately following the compressed data stream, and you don't
263            know the length of the compressed data stream.
264
265            If the input is a buffer, "trailingData" will return everything
266            from the end of the compressed data stream to the end of the
267            buffer.
268
269            If the input is a filehandle, "trailingData" will return the data
270            that is left in the filehandle input buffer once the end of the
271            compressed data stream has been reached. You can then use the
272            filehandle to read the rest of the input file.
273
274            Don't bother using "trailingData" if the input is a filename.
275
276            If you know the length of the compressed data stream before you
277            start uncompressing, you can avoid having to use "trailingData" by
278            setting the "InputLength" option.
279
280   Examples
281       Say you have a zip file, "file1.zip", that only contains a single
282       member, you can read it and write the uncompressed data to the file
283       "file1.txt" like this.
284
285           use strict ;
286           use warnings ;
287           use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
288
289           my $input = "file1.zip";
290           my $output = "file1.txt";
291           unzip $input => $output
292               or die "unzip failed: $UnzipError\n";
293
294       If you have a zip file that contains multiple members and want to read
295       a specific member from the file, say "data1", use the "Name" option
296
297           use strict ;
298           use warnings ;
299           use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
300
301           my $input = "file1.zip";
302           my $output = "file1.txt";
303           unzip $input => $output, Name => "data1"
304               or die "unzip failed: $UnzipError\n";
305
306       Alternatively, if you want to read the  "data1" member into memory, use
307       a scalar reference for the "output" parameter.
308
309           use strict ;
310           use warnings ;
311           use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
312
313           my $input = "file1.zip";
314           my $output ;
315           unzip $input => \$output, Name => "data1"
316               or die "unzip failed: $UnzipError\n";
317           # $output now contains the uncompressed data
318
319       To read from an existing Perl filehandle, $input, and write the
320       uncompressed data to a buffer, $buffer.
321
322           use strict ;
323           use warnings ;
324           use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
325           use IO::File ;
326
327           my $input = IO::File->new( "<file1.zip" )
328               or die "Cannot open 'file1.zip': $!\n" ;
329           my $buffer ;
330           unzip $input => \$buffer
331               or die "unzip failed: $UnzipError\n";
332

OO Interface

334   Constructor
335       The format of the constructor for IO::Uncompress::Unzip is shown below
336
337           my $z = IO::Uncompress::Unzip->new( $input [OPTS] )
338               or die "IO::Uncompress::Unzip failed: $UnzipError\n";
339
340       Returns an "IO::Uncompress::Unzip" object on success and undef on
341       failure.  The variable $UnzipError will contain an error message on
342       failure.
343
344       If you are running Perl 5.005 or better the object, $z, returned from
345       IO::Uncompress::Unzip can be used exactly like an IO::File filehandle.
346       This means that all normal input file operations can be carried out
347       with $z.  For example, to read a line from a compressed file/buffer you
348       can use either of these forms
349
350           $line = $z->getline();
351           $line = <$z>;
352
353       The mandatory parameter $input is used to determine the source of the
354       compressed data. This parameter can take one of three forms.
355
356       A filename
357            If the $input parameter is a scalar, it is assumed to be a
358            filename. This file will be opened for reading and the compressed
359            data will be read from it.
360
361       A filehandle
362            If the $input parameter is a filehandle, the compressed data will
363            be read from it.  The string '-' can be used as an alias for
364            standard input.
365
366       A scalar reference
367            If $input is a scalar reference, the compressed data will be read
368            from $$input.
369
370   Constructor Options
371       The option names defined below are case insensitive and can be
372       optionally prefixed by a '-'.  So all of the following are valid
373
374           -AutoClose
375           -autoclose
376           AUTOCLOSE
377           autoclose
378
379       OPTS is a combination of the following options:
380
381       "Name => "membername""
382            Open "membername" from the zip file for reading.
383
384       "Efs => 0| 1"
385            When this option is set to true AND the zip archive being read has
386            the "Language Encoding Flag" (EFS) set, the member name is assumed
387            to be encoded in UTF-8.
388
389            If the member name in the zip archive is not valid UTF-8 when this
390            optionn is true, the script will die with an error message.
391
392            Note that this option only works with Perl 5.8.4 or better.
393
394            This option defaults to false.
395
396       "AutoClose => 0|1"
397            This option is only valid when the $input parameter is a
398            filehandle. If specified, and the value is true, it will result in
399            the file being closed once either the "close" method is called or
400            the IO::Uncompress::Unzip object is destroyed.
401
402            This parameter defaults to 0.
403
404       "MultiStream => 0|1"
405            Treats the complete zip file/buffer as a single compressed data
406            stream. When reading in multi-stream mode each member of the zip
407            file/buffer will be uncompressed in turn until the end of the
408            file/buffer is encountered.
409
410            This parameter defaults to 0.
411
412       "Prime => $string"
413            This option will uncompress the contents of $string before
414            processing the input file/buffer.
415
416            This option can be useful when the compressed data is embedded in
417            another file/data structure and it is not possible to work out
418            where the compressed data begins without having to read the first
419            few bytes. If this is the case, the uncompression can be primed
420            with these bytes using this option.
421
422       "Transparent => 0|1"
423            If this option is set and the input file/buffer is not compressed
424            data, the module will allow reading of it anyway.
425
426            In addition, if the input file/buffer does contain compressed data
427            and there is non-compressed data immediately following it, setting
428            this option will make this module treat the whole file/buffer as a
429            single data stream.
430
431            This option defaults to 1.
432
433       "BlockSize => $num"
434            When reading the compressed input data, IO::Uncompress::Unzip will
435            read it in blocks of $num bytes.
436
437            This option defaults to 4096.
438
439       "InputLength => $size"
440            When present this option will limit the number of compressed bytes
441            read from the input file/buffer to $size. This option can be used
442            in the situation where there is useful data directly after the
443            compressed data stream and you know beforehand the exact length of
444            the compressed data stream.
445
446            This option is mostly used when reading from a filehandle, in
447            which case the file pointer will be left pointing to the first
448            byte directly after the compressed data stream.
449
450            This option defaults to off.
451
452       "Append => 0|1"
453            This option controls what the "read" method does with uncompressed
454            data.
455
456            If set to 1, all uncompressed data will be appended to the output
457            parameter of the "read" method.
458
459            If set to 0, the contents of the output parameter of the "read"
460            method will be overwritten by the uncompressed data.
461
462            Defaults to 0.
463
464       "Strict => 0|1"
465            This option controls whether the extra checks defined below are
466            used when carrying out the decompression. When Strict is on, the
467            extra tests are carried out, when Strict is off they are not.
468
469            The default for this option is off.
470
471   Examples
472       TODO
473

Methods

475   read
476       Usage is
477
478           $status = $z->read($buffer)
479
480       Reads a block of compressed data (the size of the compressed block is
481       determined by the "Buffer" option in the constructor), uncompresses it
482       and writes any uncompressed data into $buffer. If the "Append"
483       parameter is set in the constructor, the uncompressed data will be
484       appended to the $buffer parameter. Otherwise $buffer will be
485       overwritten.
486
487       Returns the number of uncompressed bytes written to $buffer, zero if
488       eof or a negative number on error.
489
490   read
491       Usage is
492
493           $status = $z->read($buffer, $length)
494           $status = $z->read($buffer, $length, $offset)
495
496           $status = read($z, $buffer, $length)
497           $status = read($z, $buffer, $length, $offset)
498
499       Attempt to read $length bytes of uncompressed data into $buffer.
500
501       The main difference between this form of the "read" method and the
502       previous one, is that this one will attempt to return exactly $length
503       bytes. The only circumstances that this function will not is if end-of-
504       file or an IO error is encountered.
505
506       Returns the number of uncompressed bytes written to $buffer, zero if
507       eof or a negative number on error.
508
509   getline
510       Usage is
511
512           $line = $z->getline()
513           $line = <$z>
514
515       Reads a single line.
516
517       This method fully supports the use of the variable $/ (or
518       $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
519       what constitutes an end of line. Paragraph mode, record mode and file
520       slurp mode are all supported.
521
522   getc
523       Usage is
524
525           $char = $z->getc()
526
527       Read a single character.
528
529   ungetc
530       Usage is
531
532           $char = $z->ungetc($string)
533
534   inflateSync
535       Usage is
536
537           $status = $z->inflateSync()
538
539       TODO
540
541   getHeaderInfo
542       Usage is
543
544           $hdr  = $z->getHeaderInfo();
545           @hdrs = $z->getHeaderInfo();
546
547       This method returns either a hash reference (in scalar context) or a
548       list or hash references (in array context) that contains information
549       about each of the header fields in the compressed data stream(s).
550
551   tell
552       Usage is
553
554           $z->tell()
555           tell $z
556
557       Returns the uncompressed file offset.
558
559   eof
560       Usage is
561
562           $z->eof();
563           eof($z);
564
565       Returns true if the end of the compressed input stream has been
566       reached.
567
568   seek
569           $z->seek($position, $whence);
570           seek($z, $position, $whence);
571
572       Provides a sub-set of the "seek" functionality, with the restriction
573       that it is only legal to seek forward in the input file/buffer.  It is
574       a fatal error to attempt to seek backward.
575
576       Note that the implementation of "seek" in this module does not provide
577       true random access to a compressed file/buffer. It  works by
578       uncompressing data from the current offset in the file/buffer until it
579       reaches the uncompressed offset specified in the parameters to "seek".
580       For very small files this may be acceptable behaviour. For large files
581       it may cause an unacceptable delay.
582
583       The $whence parameter takes one the usual values, namely SEEK_SET,
584       SEEK_CUR or SEEK_END.
585
586       Returns 1 on success, 0 on failure.
587
588   binmode
589       Usage is
590
591           $z->binmode
592           binmode $z ;
593
594       This is a noop provided for completeness.
595
596   opened
597           $z->opened()
598
599       Returns true if the object currently refers to a opened file/buffer.
600
601   autoflush
602           my $prev = $z->autoflush()
603           my $prev = $z->autoflush(EXPR)
604
605       If the $z object is associated with a file or a filehandle, this method
606       returns the current autoflush setting for the underlying filehandle. If
607       "EXPR" is present, and is non-zero, it will enable flushing after every
608       write/print operation.
609
610       If $z is associated with a buffer, this method has no effect and always
611       returns "undef".
612
613       Note that the special variable $| cannot be used to set or retrieve the
614       autoflush setting.
615
616   input_line_number
617           $z->input_line_number()
618           $z->input_line_number(EXPR)
619
620       Returns the current uncompressed line number. If "EXPR" is present it
621       has the effect of setting the line number. Note that setting the line
622       number does not change the current position within the file/buffer
623       being read.
624
625       The contents of $/ are used to determine what constitutes a line
626       terminator.
627
628   fileno
629           $z->fileno()
630           fileno($z)
631
632       If the $z object is associated with a file or a filehandle, "fileno"
633       will return the underlying file descriptor. Once the "close" method is
634       called "fileno" will return "undef".
635
636       If the $z object is associated with a buffer, this method will return
637       "undef".
638
639   close
640           $z->close() ;
641           close $z ;
642
643       Closes the output file/buffer.
644
645       For most versions of Perl this method will be automatically invoked if
646       the IO::Uncompress::Unzip object is destroyed (either explicitly or by
647       the variable with the reference to the object going out of scope). The
648       exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
649       cases, the "close" method will be called automatically, but not until
650       global destruction of all live objects when the program is terminating.
651
652       Therefore, if you want your scripts to be able to run on all versions
653       of Perl, you should call "close" explicitly and not rely on automatic
654       closing.
655
656       Returns true on success, otherwise 0.
657
658       If the "AutoClose" option has been enabled when the
659       IO::Uncompress::Unzip object was created, and the object is associated
660       with a file, the underlying file will also be closed.
661
662   nextStream
663       Usage is
664
665           my $status = $z->nextStream();
666
667       Skips to the next compressed data stream in the input file/buffer. If a
668       new compressed data stream is found, the eof marker will be cleared and
669       $.  will be reset to 0.
670
671       If trailing data is present immediately after the zip archive and the
672       "Transparent" option is enabled, this method will consider that
673       trailing data to be another member of the zip archive.
674
675       Returns 1 if a new stream was found, 0 if none was found, and -1 if an
676       error was encountered.
677
678   trailingData
679       Usage is
680
681           my $data = $z->trailingData();
682
683       Returns the data, if any, that is present immediately after the
684       compressed data stream once uncompression is complete. It only makes
685       sense to call this method once the end of the compressed data stream
686       has been encountered.
687
688       This option can be used when there is useful information immediately
689       following the compressed data stream, and you don't know the length of
690       the compressed data stream.
691
692       If the input is a buffer, "trailingData" will return everything from
693       the end of the compressed data stream to the end of the buffer.
694
695       If the input is a filehandle, "trailingData" will return the data that
696       is left in the filehandle input buffer once the end of the compressed
697       data stream has been reached. You can then use the filehandle to read
698       the rest of the input file.
699
700       Don't bother using "trailingData" if the input is a filename.
701
702       If you know the length of the compressed data stream before you start
703       uncompressing, you can avoid having to use "trailingData" by setting
704       the "InputLength" option in the constructor.
705

Importing

707       No symbolic constants are required by IO::Uncompress::Unzip at present.
708
709       :all Imports "unzip" and $UnzipError.  Same as doing this
710
711                use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
712

EXAMPLES

714   Working with Net::FTP
715       See IO::Compress::FAQ
716
717   Walking through a zip file
718       The code below can be used to traverse a zip file, one compressed data
719       stream at a time.
720
721           use IO::Uncompress::Unzip qw($UnzipError);
722
723           my $zipfile = "somefile.zip";
724           my $u = IO::Uncompress::Unzip->new( $zipfile )
725               or die "Cannot open $zipfile: $UnzipError";
726
727           my $status;
728           for ($status = 1; $status > 0; $status = $u->nextStream())
729           {
730
731               my $name = $u->getHeaderInfo()->{Name};
732               warn "Processing member $name\n" ;
733
734               my $buff;
735               while (($status = $u->read($buff)) > 0) {
736                   # Do something here
737               }
738
739               last if $status < 0;
740           }
741
742           die "Error processing $zipfile: $!\n"
743               if $status < 0 ;
744
745       Each individual compressed data stream is read until the logical end-
746       of-file is reached. Then "nextStream" is called. This will skip to the
747       start of the next compressed data stream and clear the end-of-file
748       flag.
749
750       It is also worth noting that "nextStream" can be called at any time --
751       you don't have to wait until you have exhausted a compressed data
752       stream before skipping to the next one.
753
754   Unzipping a complete zip file to disk
755       Daniel S. Sterling has written a script that uses
756       "IO::Uncompress::UnZip" to read a zip file and unzip its contents to
757       disk.
758
759       The script is available from <https://gist.github.com/eqhmcow/5389877>
760

SUPPORT

762       General feedback/questions/bug reports should be sent to
763       <https://github.com/pmqs/IO-Compress/issues> (preferred) or
764       <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
765

AUTHOR

798       This module was written by Paul Marquess, "pmqs@cpan.org".
799

MODIFICATION HISTORY

801       See the Changes file.
802

COPYRIGHT AND LICENSE

804       Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
805
806       This program is free software; you can redistribute it and/or modify it
807       under the same terms as Perl itself.
808
809
810
811perl v5.36.0                      2023-02-09          IO::Uncompress::Unzip(3)