1 package IO::Uncompress::Unzip;
11 use IO::Uncompress::RawInflate 2.023 ;
12 use IO::Compress::Base::Common 2.023 qw(:Status createSelfTiedObject);
13 use IO::Uncompress::Adapter::Inflate 2.023 ;
14 use IO::Uncompress::Adapter::Identity 2.023 ;
15 use IO::Compress::Zlib::Extra 2.023 ;
16 use IO::Compress::Zip::Constants 2.023 ;
18 use Compress::Raw::Zlib 2.023 qw(crc32) ;
22 eval { require IO::Uncompress::Adapter::Bunzip2 ;
23 import IO::Uncompress::Adapter::Bunzip2 } ;
24 # eval { require IO::Uncompress::Adapter::UnLzma ;
25 # import IO::Uncompress::Adapter::UnLzma } ;
31 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $UnzipError, %headerLookup);
36 @ISA = qw(Exporter IO::Uncompress::RawInflate);
37 @EXPORT_OK = qw( $UnzipError unzip );
38 %EXPORT_TAGS = %IO::Uncompress::RawInflate::EXPORT_TAGS ;
39 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
40 Exporter::export_ok_tags('all');
43 ZIP_CENTRAL_HDR_SIG, \&skipCentralDirectory,
44 ZIP_END_CENTRAL_HDR_SIG, \&skipEndCentralDirectory,
45 ZIP64_END_CENTRAL_REC_HDR_SIG, \&skipCentralDirectory64Rec,
46 ZIP64_END_CENTRAL_LOC_HDR_SIG, \&skipCentralDirectory64Loc,
47 ZIP64_ARCHIVE_EXTRA_SIG, \&skipArchiveExtra,
48 ZIP64_DIGITAL_SIGNATURE_SIG, \&skipDigitalSignature,
54 my $obj = createSelfTiedObject($class, \$UnzipError);
55 $obj->_create(undef, 0, @_);
60 my $obj = createSelfTiedObject(undef, \$UnzipError);
61 return $obj->_inf(@_) ;
66 use IO::Compress::Base::Common 2.023 qw(:Parse);
71 'Name' => [1, 1, Parse_any, undef],
73 # 'Stream' => [1, 1, Parse_boolean, 1],
74 # This means reading the central directory to get
75 # 1. the local header offsets
76 # 2. The compressed data length
85 # unzip always needs crc32
86 $got->value('CRC32' => 1);
88 *$self->{UnzipData}{Name} = $got->value('Name');
98 my $magic = $self->ckMagic()
101 *$self->{Info} = $self->readHeader($magic)
113 $self->smartReadExact(\$magic, 4);
115 *$self->{HeaderPending} = $magic ;
117 return $self->HeaderError("Minimum header size is " .
119 if length $magic != 4 ;
121 return $self->HeaderError("Bad Magic")
122 if ! _isZipMagic($magic) ;
124 *$self->{Type} = 'zip';
135 # TODO - if Stream isn't enabled & reading from file, use seek
143 if length $offset < $c ;
147 $self->smartReadExact(\$buffer, $c)
160 my $name = *$self->{UnzipData}{Name} ;
161 my $hdr = $self->_readZipHeader($magic) ;
165 if (! defined $name || $hdr->{Name} eq $name)
171 # TODO - when Stream is off, use seek
173 if (*$self->{ZipData}{Streaming}) {
178 my $status = $self->smartRead(\$b, 1024 * 16);
184 $status = *$self->{Uncomp}->uncompr(\$b, \$temp_buf, 0, $out);
186 return $self->saveErrorString(undef, *$self->{Uncomp}{Error},
187 *$self->{Uncomp}{ErrorNo})
188 if $self->saveStatus($status) == STATUS_ERROR;
190 if ($status == STATUS_ENDSTREAM) {
191 *$self->{Uncomp}->reset();
192 $self->pushBack($b) ;
198 $self->smartReadExact(\$buffer, $hdr->{TrailerLength})
199 or return $self->saveErrorString(undef, "Truncated file");
202 my $c = $hdr->{CompressedLength}->get64bit();
203 $self->fastForward($c)
204 or return $self->saveErrorString(undef, "Truncated file");
208 $self->chkTrailer($buffer) == STATUS_OK
209 or return $self->saveErrorString(undef, "Truncated file");
211 $hdr = $self->_readFullZipHeader();
213 return $self->saveErrorString(undef, "Cannot find '$name'")
214 if $self->smartEof();
225 my ($sig, $CRC32, $cSize, $uSize) ;
226 my ($cSizeHi, $uSizeHi) = (0, 0);
227 if (*$self->{ZipData}{Streaming}) {
228 $sig = unpack ("V", substr($trailer, 0, 4));
229 $CRC32 = unpack ("V", substr($trailer, 4, 4));
231 if (*$self->{ZipData}{Zip64} ) {
232 $cSize = U64::newUnpack_V64 substr($trailer, 8, 8);
233 $uSize = U64::newUnpack_V64 substr($trailer, 16, 8);
236 $cSize = U64::newUnpack_V32 substr($trailer, 8, 4);
237 $uSize = U64::newUnpack_V32 substr($trailer, 12, 4);
240 return $self->TrailerError("Data Descriptor signature, got $sig")
241 if $sig != ZIP_DATA_HDR_SIG;
244 ($CRC32, $cSize, $uSize) =
245 (*$self->{ZipData}{Crc32},
246 *$self->{ZipData}{CompressedLen},
247 *$self->{ZipData}{UnCompressedLen});
250 *$self->{Info}{CRC32} = *$self->{ZipData}{CRC32} ;
251 *$self->{Info}{CompressedLength} = $cSize->get64bit();
252 *$self->{Info}{UncompressedLength} = $uSize->get64bit();
254 if (*$self->{Strict}) {
255 return $self->TrailerError("CRC mismatch")
256 if $CRC32 != *$self->{ZipData}{CRC32} ;
258 return $self->TrailerError("CSIZE mismatch.")
259 if ! $cSize->equal(*$self->{CompSize});
261 return $self->TrailerError("USIZE mismatch.")
262 if ! $uSize->equal(*$self->{UnCompSize});
265 my $reachedEnd = STATUS_ERROR ;
266 # check for central directory or end of central directory
270 my $got = $self->smartRead(\$magic, 4);
272 return $self->saveErrorString(STATUS_ERROR, "Truncated file")
273 if $got != 4 && *$self->{Strict};
279 return STATUS_ERROR ;
282 $self->pushBack($magic) ;
286 my $sig = unpack("V", $magic) ;
289 if ($hdr = $headerLookup{$sig})
291 if (&$hdr($self, $magic) != STATUS_OK ) {
292 if (*$self->{Strict}) {
293 return STATUS_ERROR ;
301 if ($sig == ZIP_END_CENTRAL_HDR_SIG)
307 elsif ($sig == ZIP_LOCAL_HDR_SIG)
309 $self->pushBack($magic) ;
315 $self->pushBack($magic) ;
323 sub skipCentralDirectory
329 $self->smartReadExact(\$buffer, 46 - 4)
330 or return $self->TrailerError("Minimum header size is " .
333 my $keep = $magic . $buffer ;
334 *$self->{HeaderPending} = $keep ;
336 #my $versionMadeBy = unpack ("v", substr($buffer, 4-4, 2));
337 #my $extractVersion = unpack ("v", substr($buffer, 6-4, 2));
338 #my $gpFlag = unpack ("v", substr($buffer, 8-4, 2));
339 #my $compressedMethod = unpack ("v", substr($buffer, 10-4, 2));
340 #my $lastModTime = unpack ("V", substr($buffer, 12-4, 4));
341 #my $crc32 = unpack ("V", substr($buffer, 16-4, 4));
342 my $compressedLength = unpack ("V", substr($buffer, 20-4, 4));
343 my $uncompressedLength = unpack ("V", substr($buffer, 24-4, 4));
344 my $filename_length = unpack ("v", substr($buffer, 28-4, 2));
345 my $extra_length = unpack ("v", substr($buffer, 30-4, 2));
346 my $comment_length = unpack ("v", substr($buffer, 32-4, 2));
347 #my $disk_start = unpack ("v", substr($buffer, 34-4, 2));
348 #my $int_file_attrib = unpack ("v", substr($buffer, 36-4, 2));
349 #my $ext_file_attrib = unpack ("V", substr($buffer, 38-4, 2));
350 #my $lcl_hdr_offset = unpack ("V", substr($buffer, 42-4, 2));
356 if ($filename_length)
358 $self->smartReadExact(\$filename, $filename_length)
359 or return $self->TruncatedTrailer("filename");
365 $self->smartReadExact(\$extraField, $extra_length)
366 or return $self->TruncatedTrailer("extra");
367 $keep .= $extraField ;
372 $self->smartReadExact(\$comment, $comment_length)
373 or return $self->TruncatedTrailer("comment");
386 $self->smartReadExact(\$buffer, 4)
387 or return $self->TrailerError("Minimum header size is " .
390 my $keep = $magic . $buffer ;
392 my $size = unpack ("V", $buffer);
394 $self->smartReadExact(\$buffer, $size)
395 or return $self->TrailerError("Minimum header size is " .
399 *$self->{HeaderPending} = $keep ;
405 sub skipCentralDirectory64Rec
411 $self->smartReadExact(\$buffer, 8)
412 or return $self->TrailerError("Minimum header size is " .
415 my $keep = $magic . $buffer ;
417 my ($sizeLo, $sizeHi) = unpack ("V V", $buffer);
418 my $size = $sizeHi * 0xFFFFFFFF + $sizeLo;
420 $self->fastForward($size)
421 or return $self->TrailerError("Minimum header size is " .
425 #*$self->{HeaderPending} = $keep ;
427 #my $versionMadeBy = unpack ("v", substr($buffer, 0, 2));
428 #my $extractVersion = unpack ("v", substr($buffer, 2, 2));
429 #my $diskNumber = unpack ("V", substr($buffer, 4, 4));
430 #my $cntrlDirDiskNo = unpack ("V", substr($buffer, 8, 4));
431 #my $entriesInThisCD = unpack ("V V", substr($buffer, 12, 8));
432 #my $entriesInCD = unpack ("V V", substr($buffer, 20, 8));
433 #my $sizeOfCD = unpack ("V V", substr($buffer, 28, 8));
434 #my $offsetToCD = unpack ("V V", substr($buffer, 36, 8));
439 sub skipCentralDirectory64Loc
445 $self->smartReadExact(\$buffer, 20 - 4)
446 or return $self->TrailerError("Minimum header size is " .
449 my $keep = $magic . $buffer ;
450 *$self->{HeaderPending} = $keep ;
452 #my $startCdDisk = unpack ("V", substr($buffer, 4-4, 4));
453 #my $offsetToCD = unpack ("V V", substr($buffer, 8-4, 8));
454 #my $diskCount = unpack ("V", substr($buffer, 16-4, 4));
459 sub skipEndCentralDirectory
465 $self->smartReadExact(\$buffer, 22 - 4)
466 or return $self->TrailerError("Minimum header size is " .
469 my $keep = $magic . $buffer ;
470 *$self->{HeaderPending} = $keep ;
472 #my $diskNumber = unpack ("v", substr($buffer, 4-4, 2));
473 #my $cntrlDirDiskNo = unpack ("v", substr($buffer, 6-4, 2));
474 #my $entriesInThisCD = unpack ("v", substr($buffer, 8-4, 2));
475 #my $entriesInCD = unpack ("v", substr($buffer, 10-4, 2));
476 #my $sizeOfCD = unpack ("V", substr($buffer, 12-4, 2));
477 #my $offsetToCD = unpack ("V", substr($buffer, 16-4, 2));
478 my $comment_length = unpack ("v", substr($buffer, 20-4, 2));
484 $self->smartReadExact(\$comment, $comment_length)
485 or return $self->TruncatedTrailer("comment");
496 return 0 if length $buffer < 4 ;
497 my $sig = unpack("V", $buffer) ;
498 return $sig == ZIP_LOCAL_HDR_SIG ;
502 sub _readFullZipHeader($)
507 $self->smartReadExact(\$magic, 4);
509 *$self->{HeaderPending} = $magic ;
511 return $self->HeaderError("Minimum header size is " .
513 if length $magic != 4 ;
516 return $self->HeaderError("Bad Magic")
517 if ! _isZipMagic($magic) ;
519 my $status = $self->_readZipHeader($magic);
520 delete *$self->{Transparent} if ! defined $status ;
524 sub _readZipHeader($)
526 my ($self, $magic) = @_ ;
530 $self->smartReadExact(\$buffer, 30 - 4)
531 or return $self->HeaderError("Minimum header size is " .
534 my $keep = $magic . $buffer ;
535 *$self->{HeaderPending} = $keep ;
537 my $extractVersion = unpack ("v", substr($buffer, 4-4, 2));
538 my $gpFlag = unpack ("v", substr($buffer, 6-4, 2));
539 my $compressedMethod = unpack ("v", substr($buffer, 8-4, 2));
540 my $lastModTime = unpack ("V", substr($buffer, 10-4, 4));
541 my $crc32 = unpack ("V", substr($buffer, 14-4, 4));
542 my $compressedLength = U64::newUnpack_V32 substr($buffer, 18-4, 4);
543 my $uncompressedLength = U64::newUnpack_V32 substr($buffer, 22-4, 4);
544 my $filename_length = unpack ("v", substr($buffer, 26-4, 2));
545 my $extra_length = unpack ("v", substr($buffer, 28-4, 2));
550 my $streamingMode = ($gpFlag & ZIP_GP_FLAG_STREAMING_MASK) ? 1 : 0 ;
552 return $self->HeaderError("Streamed Stored content not supported")
553 if $streamingMode && $compressedMethod == 0 ;
555 return $self->HeaderError("Encrypted content not supported")
556 if $gpFlag & (ZIP_GP_FLAG_ENCRYPTED_MASK|ZIP_GP_FLAG_STRONG_ENCRYPTED_MASK);
558 return $self->HeaderError("Patch content not supported")
559 if $gpFlag & ZIP_GP_FLAG_PATCHED_MASK;
561 *$self->{ZipData}{Streaming} = $streamingMode;
564 if ($filename_length)
566 $self->smartReadExact(\$filename, $filename_length)
567 or return $self->TruncatedHeader("Filename");
575 $self->smartReadExact(\$extraField, $extra_length)
576 or return $self->TruncatedHeader("Extra Field");
578 my $bad = IO::Compress::Zlib::Extra::parseRawExtra($extraField,
580 return $self->HeaderError($bad)
583 $keep .= $extraField ;
588 $Extra{$_->[0]} = \$_->[1];
591 if (defined $Extra{ZIP_EXTRA_ID_ZIP64()})
595 my $buff = ${ $Extra{ZIP_EXTRA_ID_ZIP64()} };
597 # This code assumes that all the fields in the Zip64
598 # extra field aren't necessarily present. The spec says that
599 # they only exist if the equivalent local headers are -1.
601 if (! $streamingMode) {
604 if ($uncompressedLength->get32bit() == 0xFFFFFFFF ) {
606 = U64::newUnpack_V64 substr($buff, 0, 8);
611 if ($compressedLength->get32bit() == 0xFFFFFFFF) {
614 = U64::newUnpack_V64 substr($buff, $offset, 8);
622 *$self->{ZipData}{Zip64} = $zip64;
624 if (! $streamingMode) {
625 *$self->{ZipData}{Streaming} = 0;
626 *$self->{ZipData}{Crc32} = $crc32;
627 *$self->{ZipData}{CompressedLen} = $compressedLength;
628 *$self->{ZipData}{UnCompressedLen} = $uncompressedLength;
629 *$self->{CompressedInputLengthRemaining} =
630 *$self->{CompressedInputLength} = $compressedLength->get64bit();
633 *$self->{ZipData}{CRC32} = crc32(undef);
634 *$self->{ZipData}{Method} = $compressedMethod;
635 if ($compressedMethod == ZIP_CM_DEFLATE)
637 *$self->{Type} = 'zip-deflate';
638 my $obj = IO::Uncompress::Adapter::Inflate::mkUncompObject(1,0,0);
640 *$self->{Uncomp} = $obj;
642 elsif ($compressedMethod == ZIP_CM_BZIP2)
644 return $self->HeaderError("Unsupported Compression format $compressedMethod")
645 if ! defined $IO::Uncompress::Adapter::Bunzip2::VERSION ;
647 *$self->{Type} = 'zip-bzip2';
649 my $obj = IO::Uncompress::Adapter::Bunzip2::mkUncompObject();
651 *$self->{Uncomp} = $obj;
653 # elsif ($compressedMethod == ZIP_CM_LZMA)
655 # return $self->HeaderError("Unsupported Compression format $compressedMethod")
656 # if ! defined $IO::Uncompress::Adapter::UnLzma::VERSION ;
658 # *$self->{Type} = 'zip-lzma';
660 # $self->smartReadExact(\$LzmaHeader, 4)
661 # or return $self->saveErrorString(undef, "Truncated file");
662 # my ($verHi, $verLo) = unpack ("CC", substr($LzmaHeader, 0, 2));
663 # my $LzmaPropertiesSize = unpack ("v", substr($LzmaHeader, 2, 2));
666 # my $LzmaPropertyData;
667 # $self->smartReadExact(\$LzmaPropertyData, $LzmaPropertiesSize)
668 # or return $self->saveErrorString(undef, "Truncated file");
669 # #my $LzmaInfo = unpack ("C", substr($LzmaPropertyData, 0, 1));
670 # #my $LzmaDictSize = unpack ("V", substr($LzmaPropertyData, 1, 4));
672 # # Create an LZMA_Alone header
673 # $self->pushBack($LzmaPropertyData .
674 # $uncompressedLength->getPacked_V64());
677 # IO::Uncompress::Adapter::UnLzma::mkUncompObject();
679 # *$self->{Uncomp} = $obj;
681 elsif ($compressedMethod == ZIP_CM_STORE)
683 # TODO -- add support for reading uncompressed
685 *$self->{Type} = 'zip-stored';
687 my $obj = IO::Uncompress::Adapter::Identity::mkUncompObject();
689 *$self->{Uncomp} = $obj;
693 return $self->HeaderError("Unsupported Compression format $compressedMethod");
698 'FingerprintLength' => 4,
699 #'HeaderLength' => $compressedMethod == 8 ? length $keep : 0,
700 'HeaderLength' => length $keep,
702 'TrailerLength' => ! $streamingMode ? 0 : $zip64 ? 24 : 16,
704 'CompressedLength' => $compressedLength ,
705 'UncompressedLength' => $uncompressedLength ,
708 'Time' => _dosToUnixTime($lastModTime),
709 'Stream' => $streamingMode,
711 'MethodID' => $compressedMethod,
712 'MethodName' => $compressedMethod == ZIP_CM_DEFLATE
714 : $compressedMethod == ZIP_CM_BZIP2
716 : $compressedMethod == ZIP_CM_LZMA
718 : $compressedMethod == ZIP_CM_STORE
722 # 'TextFlag' => $flag & GZIP_FLG_FTEXT ? 1 : 0,
723 # 'HeaderCRCFlag' => $flag & GZIP_FLG_FHCRC ? 1 : 0,
724 # 'NameFlag' => $flag & GZIP_FLG_FNAME ? 1 : 0,
725 # 'CommentFlag' => $flag & GZIP_FLG_FCOMMENT ? 1 : 0,
726 # 'ExtraFlag' => $flag & GZIP_FLG_FEXTRA ? 1 : 0,
727 # 'Comment' => $comment,
729 # 'OsName' => defined $GZIP_OS_Names{$os}
730 # ? $GZIP_OS_Names{$os} : "Unknown",
731 # 'HeaderCRC' => $HeaderCRC,
733 # 'ExtraFlags' => $xfl,
734 'ExtraFieldRaw' => $extraField,
735 'ExtraField' => [ @EXTRA ],
741 sub filterUncompressed
745 if (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
746 *$self->{ZipData}{CRC32} = *$self->{Uncomp}->crc32() ;
749 *$self->{ZipData}{CRC32} = crc32(${$_[0]}, *$self->{ZipData}{CRC32});
754 # from Archive::Zip & info-zip
759 my $year = ( ( $dt >> 25 ) & 0x7f ) + 80;
760 my $mon = ( ( $dt >> 21 ) & 0x0f ) - 1;
761 my $mday = ( ( $dt >> 16 ) & 0x1f );
763 my $hour = ( ( $dt >> 11 ) & 0x1f );
764 my $min = ( ( $dt >> 5 ) & 0x3f );
765 my $sec = ( ( $dt << 1 ) & 0x3e );
770 my $time_t = mktime( $sec, $min, $hour, $mday, $mon, $year, 0, 0, -1 );
771 return 0 if ! defined $time_t;
783 IO::Uncompress::Unzip - Read zip files/buffers
787 use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
789 my $status = unzip $input => $output [,OPTS]
790 or die "unzip failed: $UnzipError\n";
792 my $z = new IO::Uncompress::Unzip $input [OPTS]
793 or die "unzip failed: $UnzipError\n";
795 $status = $z->read($buffer)
796 $status = $z->read($buffer, $length)
797 $status = $z->read($buffer, $length, $offset)
798 $line = $z->getline()
803 $status = $z->inflateSync()
805 $data = $z->trailingData()
806 $status = $z->nextStream()
807 $data = $z->getHeaderInfo()
809 $z->seek($position, $whence)
821 read($z, $buffer, $length);
822 read($z, $buffer, $length, $offset);
824 seek($z, $position, $whence)
832 This module provides a Perl interface that allows the reading of
835 For writing zip files/buffers, see the companion module IO::Compress::Zip.
837 =head1 Functional Interface
839 A top-level function, C<unzip>, is provided to carry out
840 "one-shot" uncompression between buffers and/or files. For finer
841 control over the uncompression process, see the L</"OO Interface">
844 use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
846 unzip $input => $output [,OPTS]
847 or die "unzip failed: $UnzipError\n";
849 The functional interface needs Perl5.005 or better.
851 =head2 unzip $input => $output [, OPTS]
853 C<unzip> expects at least two parameters, C<$input> and C<$output>.
855 =head3 The C<$input> parameter
857 The parameter, C<$input>, is used to define the source of
860 It can take one of the following forms:
866 If the C<$input> parameter is a simple scalar, it is assumed to be a
867 filename. This file will be opened for reading and the input data
868 will be read from it.
872 If the C<$input> parameter is a filehandle, the input data will be
874 The string '-' can be used as an alias for standard input.
876 =item A scalar reference
878 If C<$input> is a scalar reference, the input data will be read
881 =item An array reference
883 If C<$input> is an array reference, each element in the array must be a
886 The input data will be read from each file in turn.
888 The complete array will be walked to ensure that it only
889 contains valid filenames before any data is uncompressed.
891 =item An Input FileGlob string
893 If C<$input> is a string that is delimited by the characters "<" and ">"
894 C<unzip> will assume that it is an I<input fileglob string>. The
895 input is the list of files that match the fileglob.
897 If the fileglob does not match any files ...
899 See L<File::GlobMapper|File::GlobMapper> for more details.
903 If the C<$input> parameter is any other type, C<undef> will be returned.
905 =head3 The C<$output> parameter
907 The parameter C<$output> is used to control the destination of the
908 uncompressed data. This parameter can take one of these forms.
914 If the C<$output> parameter is a simple scalar, it is assumed to be a
915 filename. This file will be opened for writing and the uncompressed
916 data will be written to it.
920 If the C<$output> parameter is a filehandle, the uncompressed data
921 will be written to it.
922 The string '-' can be used as an alias for standard output.
924 =item A scalar reference
926 If C<$output> is a scalar reference, the uncompressed data will be
927 stored in C<$$output>.
929 =item An Array Reference
931 If C<$output> is an array reference, the uncompressed data will be
932 pushed onto the array.
934 =item An Output FileGlob
936 If C<$output> is a string that is delimited by the characters "<" and ">"
937 C<unzip> will assume that it is an I<output fileglob string>. The
938 output is the list of files that match the fileglob.
940 When C<$output> is an fileglob string, C<$input> must also be a fileglob
941 string. Anything else is an error.
945 If the C<$output> parameter is any other type, C<undef> will be returned.
949 When C<$input> maps to multiple compressed files/buffers and C<$output> is
950 a single file/buffer, after uncompression C<$output> will contain a
951 concatenation of all the uncompressed data from each of the input
954 =head2 Optional Parameters
956 Unless specified below, the optional parameters for C<unzip>,
957 C<OPTS>, are the same as those used with the OO interface defined in the
958 L</"Constructor Options"> section below.
962 =item C<< AutoClose => 0|1 >>
964 This option applies to any input or output data streams to
965 C<unzip> that are filehandles.
967 If C<AutoClose> is specified, and the value is true, it will result in all
968 input and/or output filehandles being closed once C<unzip> has
971 This parameter defaults to 0.
973 =item C<< BinModeOut => 0|1 >>
975 When writing to a file or filehandle, set C<binmode> before writing to the
980 =item C<< Append => 0|1 >>
982 The behaviour of this option is dependent on the type of output data
989 If C<Append> is enabled, all uncompressed data will be append to the end of
990 the output buffer. Otherwise the output buffer will be cleared before any
991 uncompressed data is written to it.
995 If C<Append> is enabled, the file will be opened in append mode. Otherwise
996 the contents of the file, if any, will be truncated before any uncompressed
997 data is written to it.
1001 If C<Append> is enabled, the filehandle will be positioned to the end of
1002 the file via a call to C<seek> before any uncompressed data is
1003 written to it. Otherwise the file pointer will not be moved.
1007 When C<Append> is specified, and set to true, it will I<append> all uncompressed
1008 data to the output data stream.
1010 So when the output is a filehandle it will carry out a seek to the eof
1011 before writing any uncompressed data. If the output is a filename, it will be opened for
1012 appending. If the output is a buffer, all uncompressed data will be appened to
1013 the existing buffer.
1015 Conversely when C<Append> is not specified, or it is present and is set to
1016 false, it will operate as follows.
1018 When the output is a filename, it will truncate the contents of the file
1019 before writing any uncompressed data. If the output is a filehandle
1020 its position will not be changed. If the output is a buffer, it will be
1021 wiped before any uncompressed data is output.
1025 =item C<< MultiStream => 0|1 >>
1027 If the input file/buffer contains multiple compressed data streams, this
1028 option will uncompress the whole lot as a single data stream.
1032 =item C<< TrailingData => $scalar >>
1034 Returns the data, if any, that is present immediately after the compressed
1035 data stream once uncompression is complete.
1037 This option can be used when there is useful information immediately
1038 following the compressed data stream, and you don't know the length of the
1039 compressed data stream.
1041 If the input is a buffer, C<trailingData> will return everything from the
1042 end of the compressed data stream to the end of the buffer.
1044 If the input is a filehandle, C<trailingData> will return the data that is
1045 left in the filehandle input buffer once the end of the compressed data
1046 stream has been reached. You can then use the filehandle to read the rest
1049 Don't bother using C<trailingData> if the input is a filename.
1051 If you know the length of the compressed data stream before you start
1052 uncompressing, you can avoid having to use C<trailingData> by setting the
1053 C<InputLength> option.
1059 To read the contents of the file C<file1.txt.zip> and write the
1060 uncompressed data to the file C<file1.txt>.
1064 use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
1066 my $input = "file1.txt.zip";
1067 my $output = "file1.txt";
1068 unzip $input => $output
1069 or die "unzip failed: $UnzipError\n";
1071 To read from an existing Perl filehandle, C<$input>, and write the
1072 uncompressed data to a buffer, C<$buffer>.
1076 use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
1079 my $input = new IO::File "<file1.txt.zip"
1080 or die "Cannot open 'file1.txt.zip': $!\n" ;
1082 unzip $input => \$buffer
1083 or die "unzip failed: $UnzipError\n";
1085 To uncompress all files in the directory "/my/home" that match "*.txt.zip" and store the compressed data in the same directory
1089 use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
1091 unzip '</my/home/*.txt.zip>' => '</my/home/#1.txt>'
1092 or die "unzip failed: $UnzipError\n";
1094 and if you want to compress each file one at a time, this will do the trick
1098 use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
1100 for my $input ( glob "/my/home/*.txt.zip" )
1102 my $output = $input;
1103 $output =~ s/.zip// ;
1104 unzip $input => $output
1105 or die "Error compressing '$input': $UnzipError\n";
1112 The format of the constructor for IO::Uncompress::Unzip is shown below
1114 my $z = new IO::Uncompress::Unzip $input [OPTS]
1115 or die "IO::Uncompress::Unzip failed: $UnzipError\n";
1117 Returns an C<IO::Uncompress::Unzip> object on success and undef on failure.
1118 The variable C<$UnzipError> will contain an error message on failure.
1120 If you are running Perl 5.005 or better the object, C<$z>, returned from
1121 IO::Uncompress::Unzip can be used exactly like an L<IO::File|IO::File> filehandle.
1122 This means that all normal input file operations can be carried out with
1123 C<$z>. For example, to read a line from a compressed file/buffer you can
1124 use either of these forms
1126 $line = $z->getline();
1129 The mandatory parameter C<$input> is used to determine the source of the
1130 compressed data. This parameter can take one of three forms.
1136 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
1137 file will be opened for reading and the compressed data will be read from it.
1141 If the C<$input> parameter is a filehandle, the compressed data will be
1143 The string '-' can be used as an alias for standard input.
1145 =item A scalar reference
1147 If C<$input> is a scalar reference, the compressed data will be read from
1152 =head2 Constructor Options
1154 The option names defined below are case insensitive and can be optionally
1155 prefixed by a '-'. So all of the following are valid
1162 OPTS is a combination of the following options:
1166 =item C<< AutoClose => 0|1 >>
1168 This option is only valid when the C<$input> parameter is a filehandle. If
1169 specified, and the value is true, it will result in the file being closed once
1170 either the C<close> method is called or the IO::Uncompress::Unzip object is
1173 This parameter defaults to 0.
1175 =item C<< MultiStream => 0|1 >>
1177 Treats the complete zip file/buffer as a single compressed data
1178 stream. When reading in multi-stream mode each member of the zip
1179 file/buffer will be uncompressed in turn until the end of the file/buffer
1182 This parameter defaults to 0.
1184 =item C<< Prime => $string >>
1186 This option will uncompress the contents of C<$string> before processing the
1189 This option can be useful when the compressed data is embedded in another
1190 file/data structure and it is not possible to work out where the compressed
1191 data begins without having to read the first few bytes. If this is the
1192 case, the uncompression can be I<primed> with these bytes using this
1195 =item C<< Transparent => 0|1 >>
1197 If this option is set and the input file/buffer is not compressed data,
1198 the module will allow reading of it anyway.
1200 In addition, if the input file/buffer does contain compressed data and
1201 there is non-compressed data immediately following it, setting this option
1202 will make this module treat the whole file/bufffer as a single data stream.
1204 This option defaults to 1.
1206 =item C<< BlockSize => $num >>
1208 When reading the compressed input data, IO::Uncompress::Unzip will read it in
1209 blocks of C<$num> bytes.
1211 This option defaults to 4096.
1213 =item C<< InputLength => $size >>
1215 When present this option will limit the number of compressed bytes read
1216 from the input file/buffer to C<$size>. This option can be used in the
1217 situation where there is useful data directly after the compressed data
1218 stream and you know beforehand the exact length of the compressed data
1221 This option is mostly used when reading from a filehandle, in which case
1222 the file pointer will be left pointing to the first byte directly after the
1223 compressed data stream.
1225 This option defaults to off.
1227 =item C<< Append => 0|1 >>
1229 This option controls what the C<read> method does with uncompressed data.
1231 If set to 1, all uncompressed data will be appended to the output parameter
1232 of the C<read> method.
1234 If set to 0, the contents of the output parameter of the C<read> method
1235 will be overwritten by the uncompressed data.
1239 =item C<< Strict => 0|1 >>
1241 This option controls whether the extra checks defined below are used when
1242 carrying out the decompression. When Strict is on, the extra tests are
1243 carried out, when Strict is off they are not.
1245 The default for this option is off.
1259 $status = $z->read($buffer)
1261 Reads a block of compressed data (the size the the compressed block is
1262 determined by the C<Buffer> option in the constructor), uncompresses it and
1263 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
1264 set in the constructor, the uncompressed data will be appended to the
1265 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
1267 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
1268 or a negative number on error.
1274 $status = $z->read($buffer, $length)
1275 $status = $z->read($buffer, $length, $offset)
1277 $status = read($z, $buffer, $length)
1278 $status = read($z, $buffer, $length, $offset)
1280 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
1282 The main difference between this form of the C<read> method and the
1283 previous one, is that this one will attempt to return I<exactly> C<$length>
1284 bytes. The only circumstances that this function will not is if end-of-file
1285 or an IO error is encountered.
1287 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
1288 or a negative number on error.
1294 $line = $z->getline()
1297 Reads a single line.
1299 This method fully supports the use of of the variable C<$/> (or
1300 C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
1301 determine what constitutes an end of line. Paragraph mode, record mode and
1302 file slurp mode are all supported.
1310 Read a single character.
1316 $char = $z->ungetc($string)
1322 $status = $z->inflateSync()
1326 =head2 getHeaderInfo
1330 $hdr = $z->getHeaderInfo();
1331 @hdrs = $z->getHeaderInfo();
1333 This method returns either a hash reference (in scalar context) or a list
1334 or hash references (in array context) that contains information about each
1335 of the header fields in the compressed data stream(s).
1344 Returns the uncompressed file offset.
1353 Returns true if the end of the compressed input stream has been reached.
1357 $z->seek($position, $whence);
1358 seek($z, $position, $whence);
1360 Provides a sub-set of the C<seek> functionality, with the restriction
1361 that it is only legal to seek forward in the input file/buffer.
1362 It is a fatal error to attempt to seek backward.
1364 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1365 SEEK_CUR or SEEK_END.
1367 Returns 1 on success, 0 on failure.
1376 This is a noop provided for completeness.
1382 Returns true if the object currently refers to a opened file/buffer.
1386 my $prev = $z->autoflush()
1387 my $prev = $z->autoflush(EXPR)
1389 If the C<$z> object is associated with a file or a filehandle, this method
1390 returns the current autoflush setting for the underlying filehandle. If
1391 C<EXPR> is present, and is non-zero, it will enable flushing after every
1392 write/print operation.
1394 If C<$z> is associated with a buffer, this method has no effect and always
1397 B<Note> that the special variable C<$|> B<cannot> be used to set or
1398 retrieve the autoflush setting.
1400 =head2 input_line_number
1402 $z->input_line_number()
1403 $z->input_line_number(EXPR)
1405 Returns the current uncompressed line number. If C<EXPR> is present it has
1406 the effect of setting the line number. Note that setting the line number
1407 does not change the current position within the file/buffer being read.
1409 The contents of C<$/> are used to to determine what constitutes a line
1417 If the C<$z> object is associated with a file or a filehandle, C<fileno>
1418 will return the underlying file descriptor. Once the C<close> method is
1419 called C<fileno> will return C<undef>.
1421 If the C<$z> object is is associated with a buffer, this method will return
1429 Closes the output file/buffer.
1431 For most versions of Perl this method will be automatically invoked if
1432 the IO::Uncompress::Unzip object is destroyed (either explicitly or by the
1433 variable with the reference to the object going out of scope). The
1434 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1435 these cases, the C<close> method will be called automatically, but
1436 not until global destruction of all live objects when the program is
1439 Therefore, if you want your scripts to be able to run on all versions
1440 of Perl, you should call C<close> explicitly and not rely on automatic
1443 Returns true on success, otherwise 0.
1445 If the C<AutoClose> option has been enabled when the IO::Uncompress::Unzip
1446 object was created, and the object is associated with a file, the
1447 underlying file will also be closed.
1453 my $status = $z->nextStream();
1455 Skips to the next compressed data stream in the input file/buffer. If a new
1456 compressed data stream is found, the eof marker will be cleared and C<$.>
1459 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
1460 error was encountered.
1466 my $data = $z->trailingData();
1468 Returns the data, if any, that is present immediately after the compressed
1469 data stream once uncompression is complete. It only makes sense to call
1470 this method once the end of the compressed data stream has been
1473 This option can be used when there is useful information immediately
1474 following the compressed data stream, and you don't know the length of the
1475 compressed data stream.
1477 If the input is a buffer, C<trailingData> will return everything from the
1478 end of the compressed data stream to the end of the buffer.
1480 If the input is a filehandle, C<trailingData> will return the data that is
1481 left in the filehandle input buffer once the end of the compressed data
1482 stream has been reached. You can then use the filehandle to read the rest
1485 Don't bother using C<trailingData> if the input is a filename.
1487 If you know the length of the compressed data stream before you start
1488 uncompressing, you can avoid having to use C<trailingData> by setting the
1489 C<InputLength> option in the constructor.
1493 No symbolic constants are required by this IO::Uncompress::Unzip at present.
1499 Imports C<unzip> and C<$UnzipError>.
1502 use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
1508 =head2 Working with Net::FTP
1510 See L<IO::Uncompress::Unzip::FAQ|IO::Uncompress::Unzip::FAQ/"Compressed files and Net::FTP">
1514 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1516 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1518 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1519 L<Archive::Tar|Archive::Tar>,
1520 L<IO::Zlib|IO::Zlib>
1522 For RFC 1950, 1951 and 1952 see
1523 F<http://www.faqs.org/rfcs/rfc1950.html>,
1524 F<http://www.faqs.org/rfcs/rfc1951.html> and
1525 F<http://www.faqs.org/rfcs/rfc1952.html>
1527 The I<zlib> compression library was written by Jean-loup Gailly
1528 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1530 The primary site for the I<zlib> compression library is
1531 F<http://www.zlib.org>.
1533 The primary site for gzip is F<http://www.gzip.org>.
1537 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1539 =head1 MODIFICATION HISTORY
1541 See the Changes file.
1543 =head1 COPYRIGHT AND LICENSE
1545 Copyright (c) 2005-2009 Paul Marquess. All rights reserved.
1547 This program is free software; you can redistribute it and/or
1548 modify it under the same terms as Perl itself.