1 package IO::Uncompress::Unzip;
11 use IO::Uncompress::RawInflate 2.021 ;
12 use IO::Compress::Base::Common 2.021 qw(:Status createSelfTiedObject);
13 use IO::Uncompress::Adapter::Inflate 2.021 ;
14 use IO::Uncompress::Adapter::Identity 2.021 ;
15 use IO::Compress::Zlib::Extra 2.021 ;
16 use IO::Compress::Zip::Constants 2.021 ;
18 use Compress::Raw::Zlib 2.021 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.021 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 >>
984 =item C<< MultiStream => 0|1 >>
986 If the input file/buffer contains multiple compressed data streams, this
987 option will uncompress the whole lot as a single data stream.
991 =item C<< TrailingData => $scalar >>
993 Returns the data, if any, that is present immediately after the compressed
994 data stream once uncompression is complete.
996 This option can be used when there is useful information immediately
997 following the compressed data stream, and you don't know the length of the
998 compressed data stream.
1000 If the input is a buffer, C<trailingData> will return everything from the
1001 end of the compressed data stream to the end of the buffer.
1003 If the input is a filehandle, C<trailingData> will return the data that is
1004 left in the filehandle input buffer once the end of the compressed data
1005 stream has been reached. You can then use the filehandle to read the rest
1008 Don't bother using C<trailingData> if the input is a filename.
1010 If you know the length of the compressed data stream before you start
1011 uncompressing, you can avoid having to use C<trailingData> by setting the
1012 C<InputLength> option.
1018 To read the contents of the file C<file1.txt.zip> and write the
1019 uncompressed data to the file C<file1.txt>.
1023 use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
1025 my $input = "file1.txt.zip";
1026 my $output = "file1.txt";
1027 unzip $input => $output
1028 or die "unzip failed: $UnzipError\n";
1030 To read from an existing Perl filehandle, C<$input>, and write the
1031 uncompressed data to a buffer, C<$buffer>.
1035 use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
1038 my $input = new IO::File "<file1.txt.zip"
1039 or die "Cannot open 'file1.txt.zip': $!\n" ;
1041 unzip $input => \$buffer
1042 or die "unzip failed: $UnzipError\n";
1044 To uncompress all files in the directory "/my/home" that match "*.txt.zip" and store the compressed data in the same directory
1048 use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
1050 unzip '</my/home/*.txt.zip>' => '</my/home/#1.txt>'
1051 or die "unzip failed: $UnzipError\n";
1053 and if you want to compress each file one at a time, this will do the trick
1057 use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
1059 for my $input ( glob "/my/home/*.txt.zip" )
1061 my $output = $input;
1062 $output =~ s/.zip// ;
1063 unzip $input => $output
1064 or die "Error compressing '$input': $UnzipError\n";
1071 The format of the constructor for IO::Uncompress::Unzip is shown below
1073 my $z = new IO::Uncompress::Unzip $input [OPTS]
1074 or die "IO::Uncompress::Unzip failed: $UnzipError\n";
1076 Returns an C<IO::Uncompress::Unzip> object on success and undef on failure.
1077 The variable C<$UnzipError> will contain an error message on failure.
1079 If you are running Perl 5.005 or better the object, C<$z>, returned from
1080 IO::Uncompress::Unzip can be used exactly like an L<IO::File|IO::File> filehandle.
1081 This means that all normal input file operations can be carried out with
1082 C<$z>. For example, to read a line from a compressed file/buffer you can
1083 use either of these forms
1085 $line = $z->getline();
1088 The mandatory parameter C<$input> is used to determine the source of the
1089 compressed data. This parameter can take one of three forms.
1095 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
1096 file will be opened for reading and the compressed data will be read from it.
1100 If the C<$input> parameter is a filehandle, the compressed data will be
1102 The string '-' can be used as an alias for standard input.
1104 =item A scalar reference
1106 If C<$input> is a scalar reference, the compressed data will be read from
1111 =head2 Constructor Options
1113 The option names defined below are case insensitive and can be optionally
1114 prefixed by a '-'. So all of the following are valid
1121 OPTS is a combination of the following options:
1125 =item C<< AutoClose => 0|1 >>
1127 This option is only valid when the C<$input> parameter is a filehandle. If
1128 specified, and the value is true, it will result in the file being closed once
1129 either the C<close> method is called or the IO::Uncompress::Unzip object is
1132 This parameter defaults to 0.
1134 =item C<< MultiStream => 0|1 >>
1136 Treats the complete zip file/buffer as a single compressed data
1137 stream. When reading in multi-stream mode each member of the zip
1138 file/buffer will be uncompressed in turn until the end of the file/buffer
1141 This parameter defaults to 0.
1143 =item C<< Prime => $string >>
1145 This option will uncompress the contents of C<$string> before processing the
1148 This option can be useful when the compressed data is embedded in another
1149 file/data structure and it is not possible to work out where the compressed
1150 data begins without having to read the first few bytes. If this is the
1151 case, the uncompression can be I<primed> with these bytes using this
1154 =item C<< Transparent => 0|1 >>
1156 If this option is set and the input file/buffer is not compressed data,
1157 the module will allow reading of it anyway.
1159 In addition, if the input file/buffer does contain compressed data and
1160 there is non-compressed data immediately following it, setting this option
1161 will make this module treat the whole file/bufffer as a single data stream.
1163 This option defaults to 1.
1165 =item C<< BlockSize => $num >>
1167 When reading the compressed input data, IO::Uncompress::Unzip will read it in
1168 blocks of C<$num> bytes.
1170 This option defaults to 4096.
1172 =item C<< InputLength => $size >>
1174 When present this option will limit the number of compressed bytes read
1175 from the input file/buffer to C<$size>. This option can be used in the
1176 situation where there is useful data directly after the compressed data
1177 stream and you know beforehand the exact length of the compressed data
1180 This option is mostly used when reading from a filehandle, in which case
1181 the file pointer will be left pointing to the first byte directly after the
1182 compressed data stream.
1184 This option defaults to off.
1186 =item C<< Append => 0|1 >>
1188 This option controls what the C<read> method does with uncompressed data.
1190 If set to 1, all uncompressed data will be appended to the output parameter
1191 of the C<read> method.
1193 If set to 0, the contents of the output parameter of the C<read> method
1194 will be overwritten by the uncompressed data.
1198 =item C<< Strict => 0|1 >>
1200 This option controls whether the extra checks defined below are used when
1201 carrying out the decompression. When Strict is on, the extra tests are
1202 carried out, when Strict is off they are not.
1204 The default for this option is off.
1218 $status = $z->read($buffer)
1220 Reads a block of compressed data (the size the the compressed block is
1221 determined by the C<Buffer> option in the constructor), uncompresses it and
1222 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
1223 set in the constructor, the uncompressed data will be appended to the
1224 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
1226 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
1227 or a negative number on error.
1233 $status = $z->read($buffer, $length)
1234 $status = $z->read($buffer, $length, $offset)
1236 $status = read($z, $buffer, $length)
1237 $status = read($z, $buffer, $length, $offset)
1239 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
1241 The main difference between this form of the C<read> method and the
1242 previous one, is that this one will attempt to return I<exactly> C<$length>
1243 bytes. The only circumstances that this function will not is if end-of-file
1244 or an IO error is encountered.
1246 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
1247 or a negative number on error.
1253 $line = $z->getline()
1256 Reads a single line.
1258 This method fully supports the use of of the variable C<$/> (or
1259 C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
1260 determine what constitutes an end of line. Paragraph mode, record mode and
1261 file slurp mode are all supported.
1269 Read a single character.
1275 $char = $z->ungetc($string)
1281 $status = $z->inflateSync()
1285 =head2 getHeaderInfo
1289 $hdr = $z->getHeaderInfo();
1290 @hdrs = $z->getHeaderInfo();
1292 This method returns either a hash reference (in scalar context) or a list
1293 or hash references (in array context) that contains information about each
1294 of the header fields in the compressed data stream(s).
1303 Returns the uncompressed file offset.
1312 Returns true if the end of the compressed input stream has been reached.
1316 $z->seek($position, $whence);
1317 seek($z, $position, $whence);
1319 Provides a sub-set of the C<seek> functionality, with the restriction
1320 that it is only legal to seek forward in the input file/buffer.
1321 It is a fatal error to attempt to seek backward.
1323 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1324 SEEK_CUR or SEEK_END.
1326 Returns 1 on success, 0 on failure.
1335 This is a noop provided for completeness.
1341 Returns true if the object currently refers to a opened file/buffer.
1345 my $prev = $z->autoflush()
1346 my $prev = $z->autoflush(EXPR)
1348 If the C<$z> object is associated with a file or a filehandle, this method
1349 returns the current autoflush setting for the underlying filehandle. If
1350 C<EXPR> is present, and is non-zero, it will enable flushing after every
1351 write/print operation.
1353 If C<$z> is associated with a buffer, this method has no effect and always
1356 B<Note> that the special variable C<$|> B<cannot> be used to set or
1357 retrieve the autoflush setting.
1359 =head2 input_line_number
1361 $z->input_line_number()
1362 $z->input_line_number(EXPR)
1364 Returns the current uncompressed line number. If C<EXPR> is present it has
1365 the effect of setting the line number. Note that setting the line number
1366 does not change the current position within the file/buffer being read.
1368 The contents of C<$/> are used to to determine what constitutes a line
1376 If the C<$z> object is associated with a file or a filehandle, C<fileno>
1377 will return the underlying file descriptor. Once the C<close> method is
1378 called C<fileno> will return C<undef>.
1380 If the C<$z> object is is associated with a buffer, this method will return
1388 Closes the output file/buffer.
1390 For most versions of Perl this method will be automatically invoked if
1391 the IO::Uncompress::Unzip object is destroyed (either explicitly or by the
1392 variable with the reference to the object going out of scope). The
1393 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1394 these cases, the C<close> method will be called automatically, but
1395 not until global destruction of all live objects when the program is
1398 Therefore, if you want your scripts to be able to run on all versions
1399 of Perl, you should call C<close> explicitly and not rely on automatic
1402 Returns true on success, otherwise 0.
1404 If the C<AutoClose> option has been enabled when the IO::Uncompress::Unzip
1405 object was created, and the object is associated with a file, the
1406 underlying file will also be closed.
1412 my $status = $z->nextStream();
1414 Skips to the next compressed data stream in the input file/buffer. If a new
1415 compressed data stream is found, the eof marker will be cleared and C<$.>
1418 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
1419 error was encountered.
1425 my $data = $z->trailingData();
1427 Returns the data, if any, that is present immediately after the compressed
1428 data stream once uncompression is complete. It only makes sense to call
1429 this method once the end of the compressed data stream has been
1432 This option can be used when there is useful information immediately
1433 following the compressed data stream, and you don't know the length of the
1434 compressed data stream.
1436 If the input is a buffer, C<trailingData> will return everything from the
1437 end of the compressed data stream to the end of the buffer.
1439 If the input is a filehandle, C<trailingData> will return the data that is
1440 left in the filehandle input buffer once the end of the compressed data
1441 stream has been reached. You can then use the filehandle to read the rest
1444 Don't bother using C<trailingData> if the input is a filename.
1446 If you know the length of the compressed data stream before you start
1447 uncompressing, you can avoid having to use C<trailingData> by setting the
1448 C<InputLength> option in the constructor.
1452 No symbolic constants are required by this IO::Uncompress::Unzip at present.
1458 Imports C<unzip> and C<$UnzipError>.
1461 use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
1467 =head2 Working with Net::FTP
1469 See L<IO::Uncompress::Unzip::FAQ|IO::Uncompress::Unzip::FAQ/"Compressed files and Net::FTP">
1473 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::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1475 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1477 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1478 L<Archive::Tar|Archive::Tar>,
1479 L<IO::Zlib|IO::Zlib>
1481 For RFC 1950, 1951 and 1952 see
1482 F<http://www.faqs.org/rfcs/rfc1950.html>,
1483 F<http://www.faqs.org/rfcs/rfc1951.html> and
1484 F<http://www.faqs.org/rfcs/rfc1952.html>
1486 The I<zlib> compression library was written by Jean-loup Gailly
1487 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1489 The primary site for the I<zlib> compression library is
1490 F<http://www.zlib.org>.
1492 The primary site for gzip is F<http://www.gzip.org>.
1496 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1498 =head1 MODIFICATION HISTORY
1500 See the Changes file.
1502 =head1 COPYRIGHT AND LICENSE
1504 Copyright (c) 2005-2009 Paul Marquess. All rights reserved.
1506 This program is free software; you can redistribute it and/or
1507 modify it under the same terms as Perl itself.