1 package IO::Compress::Zip ;
7 use IO::Compress::Base::Common 2.012 qw(:Status createSelfTiedObject);
8 use IO::Compress::RawDeflate 2.012 ;
9 use IO::Compress::Adapter::Deflate 2.012 ;
10 use IO::Compress::Adapter::Identity 2.012 ;
11 use IO::Compress::Zlib::Extra 2.012 ;
12 use IO::Compress::Zip::Constants 2.012 ;
15 use Compress::Raw::Zlib 2.012 qw(crc32) ;
18 eval { require IO::Compress::Adapter::Bzip2 ;
19 import IO::Compress::Adapter::Bzip2 2.012 ;
20 require IO::Compress::Bzip2 ;
21 import IO::Compress::Bzip2 2.012 ;
28 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $ZipError);
33 @ISA = qw(Exporter IO::Compress::RawDeflate);
34 @EXPORT_OK = qw( $ZipError zip ) ;
35 %EXPORT_TAGS = %IO::Compress::RawDeflate::DEFLATE_CONSTANTS ;
36 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
38 $EXPORT_TAGS{zip_method} = [qw( ZIP_CM_STORE ZIP_CM_DEFLATE ZIP_CM_BZIP2 )];
39 push @{ $EXPORT_TAGS{all} }, @{ $EXPORT_TAGS{zip_method} };
41 Exporter::export_ok_tags('all');
47 my $obj = createSelfTiedObject($class, \$ZipError);
48 $obj->_create(undef, @_);
53 my $obj = createSelfTiedObject(undef, \$ZipError);
54 return $obj->_def(@_);
62 my ($obj, $errstr, $errno) ;
64 if (*$self->{ZipData}{Method} == ZIP_CM_STORE) {
65 ($obj, $errstr, $errno) = IO::Compress::Adapter::Identity::mkCompObject(
67 $got->value('Strategy')
70 elsif (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
71 ($obj, $errstr, $errno) = IO::Compress::Adapter::Deflate::mkCompObject(
73 $got->value('Adler32'),
75 $got->value('Strategy')
78 elsif (*$self->{ZipData}{Method} == ZIP_CM_BZIP2) {
79 ($obj, $errstr, $errno) = IO::Compress::Adapter::Bzip2::mkCompObject(
80 $got->value('BlockSize100K'),
81 $got->value('WorkFactor'),
82 $got->value('Verbosity')
84 *$self->{ZipData}{CRC32} = crc32(undef);
87 return $self->saveErrorString(undef, $errstr, $errno)
90 if (! defined *$self->{ZipData}{StartOffset}) {
91 *$self->{ZipData}{StartOffset} = 0;
92 *$self->{ZipData}{Offset} = new U64 ;
102 *$self->{Compress}->reset();
103 *$self->{ZipData}{CRC32} = Compress::Raw::Zlib::crc32('');
108 sub filterUncompressed
112 if (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
113 *$self->{ZipData}{CRC32} = *$self->{Compress}->crc32();
116 *$self->{ZipData}{CRC32} = crc32(${$_[0]}, *$self->{ZipData}{CRC32});
126 *$self->{ZipData}{StartOffset} = *$self->{ZipData}{Offset}->get32bit() ;
129 $filename = $param->value('Name') || '';
132 $comment = $param->value('Comment') || '';
136 my $time = _unixToDosTime($param->value('Time'));
141 my $osCode = $param->value('OS_Code') ;
142 my $extFileAttr = 0 ;
144 # This code assumes Unix.
145 $extFileAttr = 0666 << 16
146 if $osCode == ZIP_OS_CODE_UNIX ;
148 if (*$self->{ZipData}{Zip64}) {
152 $x .= pack "V V", 0, 0 ; # uncompressedLength
153 $x .= pack "V V", 0, 0 ; # compressedLength
154 $x .= *$self->{ZipData}{Offset}->getPacked_V64() ; # offset to local hdr
155 #$x .= pack "V ", 0 ; # disk no
157 $x = IO::Compress::Zlib::Extra::mkSubField(ZIP_EXTRA_ID_ZIP64, $x);
162 if (! $param->value('Minimal')) {
163 if (defined $param->value('exTime'))
165 $extra .= mkExtendedTime($param->value('MTime'),
166 $param->value('ATime'),
167 $param->value('CTime'));
169 $ctlExtra .= mkExtendedTime($param->value('MTime'));
172 if ( $param->value('UID') && $osCode == ZIP_OS_CODE_UNIX)
174 $extra .= mkUnix2Extra( $param->value('UID'), $param->value('GID'));
175 $ctlExtra .= mkUnix2Extra();
178 $extFileAttr = $param->value('ExtAttr')
179 if defined $param->value('ExtAttr') ;
181 $extra .= $param->value('ExtraFieldLocal')
182 if defined $param->value('ExtraFieldLocal');
184 $ctlExtra .= $param->value('ExtraFieldCentral')
185 if defined $param->value('ExtraFieldCentral');
189 $gpFlag |= ZIP_GP_FLAG_STREAMING_MASK
190 if *$self->{ZipData}{Stream} ;
192 my $method = *$self->{ZipData}{Method} ;
194 my $version = $ZIP_CM_MIN_VERSIONS{$method};
195 $version = ZIP64_MIN_VERSION
196 if ZIP64_MIN_VERSION > $version && *$self->{ZipData}{Zip64};
197 my $madeBy = ($param->value('OS_Code') << 8) + $version;
198 my $extract = $version;
200 *$self->{ZipData}{Version} = $version;
201 *$self->{ZipData}{MadeBy} = $madeBy;
204 $ifa |= ZIP_IFA_TEXT_MASK
205 if $param->value('TextFlag');
207 $hdr .= pack "V", ZIP_LOCAL_HDR_SIG ; # signature
208 $hdr .= pack 'v', $extract ; # extract Version & OS
209 $hdr .= pack 'v', $gpFlag ; # general purpose flag (set streaming mode)
210 $hdr .= pack 'v', $method ; # compression method (deflate)
211 $hdr .= pack 'V', $time ; # last mod date/time
212 $hdr .= pack 'V', 0 ; # crc32 - 0 when streaming
213 $hdr .= pack 'V', $empty ; # compressed length - 0 when streaming
214 $hdr .= pack 'V', $empty ; # uncompressed length - 0 when streaming
215 $hdr .= pack 'v', length $filename ; # filename length
216 $hdr .= pack 'v', length $extra ; # extra length
224 $ctl .= pack "V", ZIP_CENTRAL_HDR_SIG ; # signature
225 $ctl .= pack 'v', $madeBy ; # version made by
226 $ctl .= pack 'v', $extract ; # extract Version
227 $ctl .= pack 'v', $gpFlag ; # general purpose flag (streaming mode)
228 $ctl .= pack 'v', $method ; # compression method (deflate)
229 $ctl .= pack 'V', $time ; # last mod date/time
230 $ctl .= pack 'V', 0 ; # crc32
231 $ctl .= pack 'V', $empty ; # compressed length
232 $ctl .= pack 'V', $empty ; # uncompressed length
233 $ctl .= pack 'v', length $filename ; # filename length
234 $ctl .= pack 'v', length $ctlExtra ; # extra length
235 $ctl .= pack 'v', length $comment ; # file comment length
236 $ctl .= pack 'v', 0 ; # disk number start
237 $ctl .= pack 'v', $ifa ; # internal file attributes
238 $ctl .= pack 'V', $extFileAttr ; # external file attributes
239 if (! *$self->{ZipData}{Zip64}) {
240 $ctl .= pack 'V', *$self->{ZipData}{Offset}->get32bit() ; # offset to local header
243 $ctl .= pack 'V', $empty ; # offset to local header
247 *$self->{ZipData}{StartOffset64} = 4 + length $ctl;
251 *$self->{ZipData}{Offset}->add(length $hdr) ;
253 *$self->{ZipData}{CentralHeader} = $ctl;
263 if (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
264 $crc32 = pack "V", *$self->{Compress}->crc32();
267 $crc32 = pack "V", *$self->{ZipData}{CRC32};
270 my $ctl = *$self->{ZipData}{CentralHeader} ;
273 if (! *$self->{ZipData}{Zip64}) {
274 $sizes .= *$self->{CompSize}->getPacked_V32() ; # Compressed size
275 $sizes .= *$self->{UnCompSize}->getPacked_V32() ; # Uncompressed size
278 $sizes .= *$self->{CompSize}->getPacked_V64() ; # Compressed size
279 $sizes .= *$self->{UnCompSize}->getPacked_V64() ; # Uncompressed size
282 my $data = $crc32 . $sizes ;
287 if (*$self->{ZipData}{Stream}) {
288 $hdr = pack "V", ZIP_DATA_HDR_SIG ; # signature
292 $self->writeAt(*$self->{ZipData}{StartOffset} + 14, $data)
296 if (! *$self->{ZipData}{Zip64})
297 { substr($ctl, 16, length $data) = $data }
299 substr($ctl, 16, length $crc32) = $crc32 ;
300 my $s = *$self->{UnCompSize}->getPacked_V64() ; # Uncompressed size
301 $s .= *$self->{CompSize}->getPacked_V64() ; # Compressed size
302 substr($ctl, *$self->{ZipData}{StartOffset64}, length $s) = $s ;
305 *$self->{ZipData}{Offset}->add(length($hdr));
306 *$self->{ZipData}{Offset}->add( *$self->{CompSize} );
307 push @{ *$self->{ZipData}{CentralDir} }, $ctl ;
317 $comment = *$self->{ZipData}{ZipComment} ;
319 my $cd_offset = *$self->{ZipData}{Offset}->get32bit() ; # offset to start central dir
321 my $entries = @{ *$self->{ZipData}{CentralDir} };
322 my $cd = join '', @{ *$self->{ZipData}{CentralDir} };
323 my $cd_len = length $cd ;
327 if ( *$self->{ZipData}{Zip64} ) {
329 my $v = *$self->{ZipData}{Version} ;
330 my $mb = *$self->{ZipData}{MadeBy} ;
331 $z64e .= pack 'v', $v ; # Version made by
332 $z64e .= pack 'v', $mb ; # Version to extract
333 $z64e .= pack 'V', 0 ; # number of disk
334 $z64e .= pack 'V', 0 ; # number of disk with central dir
335 $z64e .= U64::pack_V64 $entries ; # entries in central dir on this disk
336 $z64e .= U64::pack_V64 $entries ; # entries in central dir
337 $z64e .= U64::pack_V64 $cd_len ; # size of central dir
338 $z64e .= *$self->{ZipData}{Offset}->getPacked_V64() ; # offset to start central dir
340 $z64e = pack("V", ZIP64_END_CENTRAL_REC_HDR_SIG) # signature
341 . U64::pack_V64(length $z64e)
344 *$self->{ZipData}{Offset}->add(length $cd) ;
346 $z64e .= pack "V", ZIP64_END_CENTRAL_LOC_HDR_SIG; # signature
347 $z64e .= pack 'V', 0 ; # number of disk with central dir
348 $z64e .= *$self->{ZipData}{Offset}->getPacked_V64() ; # offset to end zip64 central dir
349 $z64e .= pack 'V', 1 ; # Total number of disks
351 # TODO - fix these when info-zip 3 is fixed.
358 $ecd .= pack "V", ZIP_END_CENTRAL_HDR_SIG ; # signature
359 $ecd .= pack 'v', 0 ; # number of disk
360 $ecd .= pack 'v', 0 ; # number of disk with central dir
361 $ecd .= pack 'v', $entries ; # entries in central dir on this disk
362 $ecd .= pack 'v', $entries ; # entries in central dir
363 $ecd .= pack 'V', $cd_len ; # size of central dir
364 $ecd .= pack 'V', $cd_offset ; # offset to start central dir
365 $ecd .= pack 'v', length $comment ; # zipfile comment length
368 return $cd . $z64e . $ecd ;
376 $got->value('CRC32' => 1);
378 if (! $got->parsed('Time') ) {
379 # Modification time defaults to now.
380 $got->value('Time' => time) ;
383 if (! $got->parsed('exTime') ) {
384 my $timeRef = $got->value('exTime');
385 if ( defined $timeRef) {
386 return $self->saveErrorString(undef, "exTime not a 3-element array ref")
387 if ref $timeRef ne 'ARRAY' || @$timeRef != 3;
390 $got->value("MTime", $timeRef->[1]);
391 $got->value("ATime", $timeRef->[0]);
392 $got->value("CTime", $timeRef->[2]);
395 # Unix2 Extended Attribute
396 if (! $got->parsed('exUnix2') ) {
397 my $timeRef = $got->value('exUnix2');
398 if ( defined $timeRef) {
399 return $self->saveErrorString(undef, "exUnix2 not a 2-element array ref")
400 if ref $timeRef ne 'ARRAY' || @$timeRef != 2;
403 $got->value("UID", $timeRef->[0]);
404 $got->value("GID", $timeRef->[1]);
407 *$self->{ZipData}{Zip64} = $got->value('Zip64');
408 *$self->{ZipData}{Stream} = $got->value('Stream');
410 return $self->saveErrorString(undef, "Zip64 only supported if Stream enabled")
411 if *$self->{ZipData}{Zip64} && ! *$self->{ZipData}{Stream} ;
413 my $method = $got->value('Method');
414 return $self->saveErrorString(undef, "Unknown Method '$method'")
415 if ! defined $ZIP_CM_MIN_VERSIONS{$method};
417 return $self->saveErrorString(undef, "Bzip2 not available")
418 if $method == ZIP_CM_BZIP2 and
419 ! defined $IO::Compress::Adapter::Bzip2::VERSION;
421 *$self->{ZipData}{Method} = $method;
423 *$self->{ZipData}{ZipComment} = $got->value('ZipComment') ;
425 for my $name (qw( ExtraFieldLocal ExtraFieldCentral ))
427 my $data = $got->value($name) ;
429 my $bad = IO::Compress::Zlib::Extra::parseExtraField($data, 1, 0) ;
430 return $self->saveErrorString(undef, "Error with $name Parameter: $bad")
433 $got->value($name, $data) ;
438 if defined $IO::Compress::Bzip2::VERSION
439 and ! IO::Compress::Bzip2::ckParams($self, $got);
448 # return $self->mkHeader(*$self->{Got});
455 use IO::Compress::Base::Common 2.012 qw(:Parse);
456 use Compress::Raw::Zlib 2.012 qw(Z_DEFLATED Z_DEFAULT_COMPRESSION Z_DEFAULT_STRATEGY);
460 @Bzip2 = IO::Compress::Bzip2::getExtraParams($self)
461 if defined $IO::Compress::Bzip2::VERSION;
465 $self->getZlibParams(),
467 'Stream' => [1, 1, Parse_boolean, 1],
468 #'Store' => [0, 1, Parse_boolean, 0],
469 'Method' => [0, 1, Parse_unsigned, ZIP_CM_DEFLATE],
471 # # Zip header fields
472 'Minimal' => [0, 1, Parse_boolean, 0],
473 'Zip64' => [0, 1, Parse_boolean, 0],
474 'Comment' => [0, 1, Parse_any, ''],
475 'ZipComment'=> [0, 1, Parse_any, ''],
476 'Name' => [0, 1, Parse_any, ''],
477 'Time' => [0, 1, Parse_any, undef],
478 'exTime' => [0, 1, Parse_any, undef],
479 'exUnix2' => [0, 1, Parse_any, undef],
480 'ExtAttr' => [0, 1, Parse_any, 0],
481 'OS_Code' => [0, 1, Parse_unsigned, $Compress::Raw::Zlib::gzip_os_code],
483 'TextFlag' => [0, 1, Parse_boolean, 0],
484 'ExtraFieldLocal' => [0, 1, Parse_any, undef],
485 'ExtraFieldCentral'=> [0, 1, Parse_any, undef],
493 return ('IO::Uncompress::Unzip',
494 \$IO::Uncompress::Unzip::UnzipError);
501 my $filename = shift ;
503 my ($mode, $uid, $gid, $atime, $mtime, $ctime)
504 = (stat($filename))[2, 4,5, 8,9,10] ;
506 $params->value('Name' => $filename)
507 if ! $params->parsed('Name') ;
509 $params->value('Time' => $mtime)
510 if ! $params->parsed('Time') ;
512 if ( ! $params->parsed('exTime'))
514 $params->value('MTime' => $mtime) ;
515 $params->value('ATime' => $atime) ;
516 $params->value('CTime' => undef) ; # No Creation time
519 # NOTE - Unix specific code alert
520 $params->value('ExtAttr' => $mode << 16)
521 if ! $params->parsed('ExtAttr');
523 $params->value('UID' => $uid) ;
524 $params->value('GID' => $gid) ;
530 # order expected is m, a, c
541 $times .= pack("V", $time);
547 return IO::Compress::Zlib::Extra::mkSubField(ZIP_EXTRA_ID_EXT_TIMESTAMP,
548 pack("C", $flags) . $times);
556 $ids .= pack("v", $id);
559 return IO::Compress::Zlib::Extra::mkSubField(ZIP_EXTRA_ID_INFO_ZIP_UNIX2,
565 sub _unixToDosTime # Archive::Zip::Member
568 # TODO - add something to cope with unix time < 1980
569 my ( $sec, $min, $hour, $mday, $mon, $year ) = localtime($time_t);
571 $dt += ( $sec >> 1 );
572 $dt += ( $min << 5 );
573 $dt += ( $hour << 11 );
574 $dt += ( $mday << 16 );
575 $dt += ( ( $mon + 1 ) << 21 );
576 $dt += ( ( $year - 80 ) << 25 );
586 IO::Compress::Zip - Write zip files/buffers
592 use IO::Compress::Zip qw(zip $ZipError) ;
594 my $status = zip $input => $output [,OPTS]
595 or die "zip failed: $ZipError\n";
597 my $z = new IO::Compress::Zip $output [,OPTS]
598 or die "zip failed: $ZipError\n";
601 $z->printf($format, $string);
603 $z->syswrite($string [, $length, $offset]);
607 $z->seek($position, $whence);
612 $z->input_line_number();
613 $z->newStream( [OPTS] );
624 printf $z $format, $string;
627 seek $z, $position, $whence
635 This module provides a Perl interface that allows writing zip
636 compressed data to files or buffer.
638 The primary purpose of this module is to provide streaming write access to
639 zip files and buffers. It is not a general-purpose file archiver. If that
640 is what you want, check out C<Archive::Zip>.
642 At present three compression methods are supported by IO::Compress::Zip,
643 namely Store (no compression at all), Deflate and Bzip2.
645 Note that to create Bzip2 content, the module C<IO::Compress::Bzip2> must
648 For reading zip files/buffers, see the companion module
649 L<IO::Uncompress::Unzip|IO::Uncompress::Unzip>.
651 =head1 Functional Interface
653 A top-level function, C<zip>, is provided to carry out
654 "one-shot" compression between buffers and/or files. For finer
655 control over the compression process, see the L</"OO Interface">
658 use IO::Compress::Zip qw(zip $ZipError) ;
660 zip $input => $output [,OPTS]
661 or die "zip failed: $ZipError\n";
663 The functional interface needs Perl5.005 or better.
665 =head2 zip $input => $output [, OPTS]
667 C<zip> expects at least two parameters, C<$input> and C<$output>.
669 =head3 The C<$input> parameter
671 The parameter, C<$input>, is used to define the source of
672 the uncompressed data.
674 It can take one of the following forms:
680 If the C<$input> parameter is a simple scalar, it is assumed to be a
681 filename. This file will be opened for reading and the input data
682 will be read from it.
686 If the C<$input> parameter is a filehandle, the input data will be
688 The string '-' can be used as an alias for standard input.
690 =item A scalar reference
692 If C<$input> is a scalar reference, the input data will be read
695 =item An array reference
697 If C<$input> is an array reference, each element in the array must be a
700 The input data will be read from each file in turn.
702 The complete array will be walked to ensure that it only
703 contains valid filenames before any data is compressed.
705 =item An Input FileGlob string
707 If C<$input> is a string that is delimited by the characters "<" and ">"
708 C<zip> will assume that it is an I<input fileglob string>. The
709 input is the list of files that match the fileglob.
711 If the fileglob does not match any files ...
713 See L<File::GlobMapper|File::GlobMapper> for more details.
717 If the C<$input> parameter is any other type, C<undef> will be returned.
719 In addition, if C<$input> is a simple filename, the default values for
720 the C<Name>, C<Time>, C<ExtAttr> and C<exTime> options will be sourced from that file.
722 If you do not want to use these defaults they can be overridden by
723 explicitly setting the C<Name>, C<Time>, C<ExtAttr> and C<exTime> options or by setting the
724 C<Minimal> parameter.
726 =head3 The C<$output> parameter
728 The parameter C<$output> is used to control the destination of the
729 compressed data. This parameter can take one of these forms.
735 If the C<$output> parameter is a simple scalar, it is assumed to be a
736 filename. This file will be opened for writing and the compressed
737 data will be written to it.
741 If the C<$output> parameter is a filehandle, the compressed data
742 will be written to it.
743 The string '-' can be used as an alias for standard output.
745 =item A scalar reference
747 If C<$output> is a scalar reference, the compressed data will be
748 stored in C<$$output>.
750 =item An Array Reference
752 If C<$output> is an array reference, the compressed data will be
753 pushed onto the array.
755 =item An Output FileGlob
757 If C<$output> is a string that is delimited by the characters "<" and ">"
758 C<zip> will assume that it is an I<output fileglob string>. The
759 output is the list of files that match the fileglob.
761 When C<$output> is an fileglob string, C<$input> must also be a fileglob
762 string. Anything else is an error.
766 If the C<$output> parameter is any other type, C<undef> will be returned.
770 When C<$input> maps to multiple files/buffers and C<$output> is a single
771 file/buffer the input files/buffers will each be stored
772 in C<$output> as a distinct entry.
774 =head2 Optional Parameters
776 Unless specified below, the optional parameters for C<zip>,
777 C<OPTS>, are the same as those used with the OO interface defined in the
778 L</"Constructor Options"> section below.
782 =item C<< AutoClose => 0|1 >>
784 This option applies to any input or output data streams to
785 C<zip> that are filehandles.
787 If C<AutoClose> is specified, and the value is true, it will result in all
788 input and/or output filehandles being closed once C<zip> has
791 This parameter defaults to 0.
793 =item C<< BinModeIn => 0|1 >>
795 When reading from a file or filehandle, set C<binmode> before reading.
799 =item C<< Append => 0|1 >>
807 To read the contents of the file C<file1.txt> and write the compressed
808 data to the file C<file1.txt.zip>.
812 use IO::Compress::Zip qw(zip $ZipError) ;
814 my $input = "file1.txt";
815 zip $input => "$input.zip"
816 or die "zip failed: $ZipError\n";
818 To read from an existing Perl filehandle, C<$input>, and write the
819 compressed data to a buffer, C<$buffer>.
823 use IO::Compress::Zip qw(zip $ZipError) ;
826 my $input = new IO::File "<file1.txt"
827 or die "Cannot open 'file1.txt': $!\n" ;
829 zip $input => \$buffer
830 or die "zip failed: $ZipError\n";
832 To compress all files in the directory "/my/home" that match "*.txt"
833 and store the compressed data in the same directory
837 use IO::Compress::Zip qw(zip $ZipError) ;
839 zip '</my/home/*.txt>' => '<*.zip>'
840 or die "zip failed: $ZipError\n";
842 and if you want to compress each file one at a time, this will do the trick
846 use IO::Compress::Zip qw(zip $ZipError) ;
848 for my $input ( glob "/my/home/*.txt" )
850 my $output = "$input.zip" ;
851 zip $input => $output
852 or die "Error compressing '$input': $ZipError\n";
859 The format of the constructor for C<IO::Compress::Zip> is shown below
861 my $z = new IO::Compress::Zip $output [,OPTS]
862 or die "IO::Compress::Zip failed: $ZipError\n";
864 It returns an C<IO::Compress::Zip> object on success and undef on failure.
865 The variable C<$ZipError> will contain an error message on failure.
867 If you are running Perl 5.005 or better the object, C<$z>, returned from
868 IO::Compress::Zip can be used exactly like an L<IO::File|IO::File> filehandle.
869 This means that all normal output file operations can be carried out
871 For example, to write to a compressed file/buffer you can use either of
874 $z->print("hello world\n");
875 print $z "hello world\n";
877 The mandatory parameter C<$output> is used to control the destination
878 of the compressed data. This parameter can take one of these forms.
884 If the C<$output> parameter is a simple scalar, it is assumed to be a
885 filename. This file will be opened for writing and the compressed data
886 will be written to it.
890 If the C<$output> parameter is a filehandle, the compressed data will be
892 The string '-' can be used as an alias for standard output.
894 =item A scalar reference
896 If C<$output> is a scalar reference, the compressed data will be stored
901 If the C<$output> parameter is any other type, C<IO::Compress::Zip>::new will
904 =head2 Constructor Options
906 C<OPTS> is any combination of the following options:
910 =item C<< AutoClose => 0|1 >>
912 This option is only valid when the C<$output> parameter is a filehandle. If
913 specified, and the value is true, it will result in the C<$output> being
914 closed once either the C<close> method is called or the C<IO::Compress::Zip>
917 This parameter defaults to 0.
919 =item C<< Append => 0|1 >>
921 Opens C<$output> in append mode.
923 The behaviour of this option is dependent on the type of C<$output>.
929 If C<$output> is a buffer and C<Append> is enabled, all compressed data
930 will be append to the end if C<$output>. Otherwise C<$output> will be
931 cleared before any data is written to it.
935 If C<$output> is a filename and C<Append> is enabled, the file will be
936 opened in append mode. Otherwise the contents of the file, if any, will be
937 truncated before any compressed data is written to it.
941 If C<$output> is a filehandle, the file pointer will be positioned to the
942 end of the file via a call to C<seek> before any compressed data is written
943 to it. Otherwise the file pointer will not be moved.
947 This parameter defaults to 0.
949 =item C<< Name => $string >>
951 Stores the contents of C<$string> in the zip filename header field. If
952 C<Name> is not specified, no zip filename field will be created.
954 =item C<< Time => $number >>
956 Sets the last modified time field in the zip header to $number.
958 This field defaults to the time the C<IO::Compress::Zip> object was created
959 if this option is not specified.
961 =item C<< ExtAttr => $attr >>
963 This option controls the "external file attributes" field in the central
964 header of the zip file. This is a 4 byte field.
966 If you are running a Unix derivative this value defaults to
970 This should allow read/write access to any files that are extracted from
973 For all other systems it defaults to 0.
975 =item C<< exTime => [$atime, $mtime, $ctime] >>
977 This option expects an array reference with exactly three elements:
978 C<$atime>, C<mtime> and C<$ctime>. These correspond to the last access
979 time, last modification time and creation time respectively.
981 It uses these values to set the extended timestamp field (ID is "UT") in
982 the local zip header using the three values, $atime, $mtime, $ctime. In
983 addition it sets the extended timestamp field in the central zip header
986 If any of the three values is C<undef> that time value will not be used.
987 So, for example, to set only the C<$mtime> you would use this
989 exTime => [undef, $mtime, undef]
991 If the C<Minimal> option is set to true, this option will be ignored.
993 By default no extended time field is created.
995 =item C<< exUnix2 => [$uid, $gid] >>
997 This option expects an array reference with exactly two elements: C<$uid>
998 and C<$gid>. These values correspond to the numeric user ID and group ID
999 of the owner of the files respectively.
1001 When the C<exUnix2> option is present it will trigger the creation of a
1002 Unix2 extra field (ID is "Ux") in the local zip. This will be populated
1003 with C<$uid> and C<$gid>. In addition an empty Unix2 extra field will also
1004 be created in the central zip header
1006 If the C<Minimal> option is set to true, this option will be ignored.
1008 By default no Unix2 extra field is created.
1010 =item C<< Comment => $comment >>
1012 Stores the contents of C<$comment> in the Central File Header of
1015 By default, no comment field is written to the zip file.
1017 =item C<< ZipComment => $comment >>
1019 Stores the contents of C<$comment> in the End of Central Directory record
1022 By default, no comment field is written to the zip file.
1024 =item C<< Method => $method >>
1026 Controls which compression method is used. At present three compression
1027 methods are supported, namely Store (no compression at all), Deflate and
1030 The symbols, ZIP_CM_STORE, ZIP_CM_DEFLATE and ZIP_CM_BZIP2 are used to
1031 select the compression method.
1033 These constants are not imported by C<IO::Compress::Zip> by default.
1035 use IO::Compress::Zip qw(:zip_method);
1036 use IO::Compress::Zip qw(:constants);
1037 use IO::Compress::Zip qw(:all);
1039 Note that to create Bzip2 content, the module C<IO::Compress::Bzip2> must
1040 be installed. A fatal error will be thrown if you attempt to create Bzip2
1041 content when C<IO::Compress::Bzip2> is not available.
1043 The default method is ZIP_CM_DEFLATE.
1045 =item C<< Stream => 0|1 >>
1047 This option controls whether the zip file/buffer output is created in
1050 Note that when outputting to a file with streaming mode disabled (C<Stream>
1051 is 0), the output file must be seekable.
1055 =item C<< Zip64 => 0|1 >>
1057 Create a Zip64 zip file/buffer. This option should only be used if you want
1058 to store files larger than 4 Gig.
1060 If you intend to manipulate the Zip64 zip files created with this module
1061 using an external zip/unzip make sure that it supports streaming Zip64.
1063 In particular, if you are using Info-Zip you need to have zip version 3.x
1064 or better to update a Zip64 archive and unzip version 6.x to read a zip64
1065 archive. At the time of writing both are beta status.
1067 When the C<Zip64> option is enabled, the C<Stream> option I<must> be
1072 =item C<< TextFlag => 0|1 >>
1074 This parameter controls the setting of a bit in the zip central header. It
1075 is used to signal that the data stored in the zip file/buffer is probably
1080 =item C<< ExtraFieldLocal => $data >>
1081 =item C<< ExtraFieldCentral => $data >>
1083 The C<ExtraFieldLocal> option is used to store additional metadata in the
1084 local header for the zip file/buffer. The C<ExtraFieldCentral> does the
1085 same for the matching central header.
1087 An extra field consists of zero or more subfields. Each subfield consists
1088 of a two byte header followed by the subfield data.
1090 The list of subfields can be supplied in any of the following formats
1092 ExtraFieldLocal => [$id1, $data1,
1097 ExtraFieldLocal => [ [$id1 => $data1],
1102 ExtraFieldLocal => { $id1 => $data1,
1107 Where C<$id1>, C<$id2> are two byte subfield ID's.
1109 If you use the hash syntax, you have no control over the order in which
1110 the ExtraSubFields are stored, plus you cannot have SubFields with
1113 Alternatively the list of subfields can by supplied as a scalar, thus
1115 ExtraField => $rawdata
1117 The Extended Time field (ID "UT"), set using the C<exTime> option, and the
1118 Unix2 extra field (ID "Ux), set using the C<exUnix2> option, are examples
1121 If the C<Minimal> option is set to true, this option will be ignored.
1123 The maximum size of an extra field 65535 bytes.
1125 =item C<< Minimal => 1|0 >>
1127 If specified, this option will disable the creation of all extra fields
1128 in the zip local and central headers. So the C<exTime>, C<exUnix2>,
1129 C<ExtraFieldLocal> and C<ExtraFieldCentral> options will be ignored.
1131 This parameter defaults to 0.
1133 =item C<< BlockSize100K => number >>
1135 Specify the number of 100K blocks bzip2 uses during compression.
1137 Valid values are from 1 to 9, where 9 is best compression.
1139 This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored
1144 =item C<< WorkFactor => number >>
1146 Specifies how much effort bzip2 should take before resorting to a slower
1147 fallback compression algorithm.
1149 Valid values range from 0 to 250, where 0 means use the default value 30.
1151 This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored
1158 Defines the compression level used by zlib. The value should either be
1159 a number between 0 and 9 (0 means no compression and 9 is maximum
1160 compression), or one of the symbolic constants defined below.
1165 Z_DEFAULT_COMPRESSION
1167 The default is Z_DEFAULT_COMPRESSION.
1169 Note, these constants are not imported by C<IO::Compress::Zip> by default.
1171 use IO::Compress::Zip qw(:strategy);
1172 use IO::Compress::Zip qw(:constants);
1173 use IO::Compress::Zip qw(:all);
1177 Defines the strategy used to tune the compression. Use one of the symbolic
1178 constants defined below.
1186 The default is Z_DEFAULT_STRATEGY.
1188 =item C<< Strict => 0|1 >>
1190 This is a placeholder option.
1207 Compresses and outputs the contents of the C<$data> parameter. This
1208 has the same behaviour as the C<print> built-in.
1210 Returns true if successful.
1216 $z->printf($format, $data)
1217 printf $z $format, $data
1219 Compresses and outputs the contents of the C<$data> parameter.
1221 Returns true if successful.
1228 $z->syswrite $data, $length
1229 $z->syswrite $data, $length, $offset
1231 Compresses and outputs the contents of the C<$data> parameter.
1233 Returns the number of uncompressed bytes written, or C<undef> if
1241 $z->write $data, $length
1242 $z->write $data, $length, $offset
1244 Compresses and outputs the contents of the C<$data> parameter.
1246 Returns the number of uncompressed bytes written, or C<undef> if
1254 $z->flush($flush_type);
1256 Flushes any pending compressed data to the output file/buffer.
1258 This method takes an optional parameter, C<$flush_type>, that controls
1259 how the flushing will be carried out. By default the C<$flush_type>
1260 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
1261 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
1262 strongly recommended that you only set the C<flush_type> parameter if
1263 you fully understand the implications of what it does - overuse of C<flush>
1264 can seriously degrade the level of compression achieved. See the C<zlib>
1265 documentation for details.
1267 Returns true on success.
1276 Returns the uncompressed file offset.
1285 Returns true if the C<close> method has been called.
1289 $z->seek($position, $whence);
1290 seek($z, $position, $whence);
1292 Provides a sub-set of the C<seek> functionality, with the restriction
1293 that it is only legal to seek forward in the output file/buffer.
1294 It is a fatal error to attempt to seek backward.
1296 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
1298 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1299 SEEK_CUR or SEEK_END.
1301 Returns 1 on success, 0 on failure.
1310 This is a noop provided for completeness.
1316 Returns true if the object currently refers to a opened file/buffer.
1320 my $prev = $z->autoflush()
1321 my $prev = $z->autoflush(EXPR)
1323 If the C<$z> object is associated with a file or a filehandle, this method
1324 returns the current autoflush setting for the underlying filehandle. If
1325 C<EXPR> is present, and is non-zero, it will enable flushing after every
1326 write/print operation.
1328 If C<$z> is associated with a buffer, this method has no effect and always
1331 B<Note> that the special variable C<$|> B<cannot> be used to set or
1332 retrieve the autoflush setting.
1334 =head2 input_line_number
1336 $z->input_line_number()
1337 $z->input_line_number(EXPR)
1339 This method always returns C<undef> when compressing.
1346 If the C<$z> object is associated with a file or a filehandle, C<fileno>
1347 will return the underlying file descriptor. Once the C<close> method is
1348 called C<fileno> will return C<undef>.
1350 If the C<$z> object is is associated with a buffer, this method will return
1358 Flushes any pending compressed data and then closes the output file/buffer.
1360 For most versions of Perl this method will be automatically invoked if
1361 the IO::Compress::Zip object is destroyed (either explicitly or by the
1362 variable with the reference to the object going out of scope). The
1363 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1364 these cases, the C<close> method will be called automatically, but
1365 not until global destruction of all live objects when the program is
1368 Therefore, if you want your scripts to be able to run on all versions
1369 of Perl, you should call C<close> explicitly and not rely on automatic
1372 Returns true on success, otherwise 0.
1374 If the C<AutoClose> option has been enabled when the IO::Compress::Zip
1375 object was created, and the object is associated with a file, the
1376 underlying file will also be closed.
1378 =head2 newStream([OPTS])
1382 $z->newStream( [OPTS] )
1384 Closes the current compressed data stream and starts a new one.
1386 OPTS consists of any of the the options that are available when creating
1389 See the L</"Constructor Options"> section for more details.
1391 =head2 deflateParams
1401 A number of symbolic constants are required by some methods in
1402 C<IO::Compress::Zip>. None are imported by default.
1408 Imports C<zip>, C<$ZipError> and all symbolic
1409 constants that can be used by C<IO::Compress::Zip>. Same as doing this
1411 use IO::Compress::Zip qw(zip $ZipError :constants) ;
1415 Import all symbolic constants. Same as doing this
1417 use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
1421 These symbolic constants are used by the C<flush> method.
1432 These symbolic constants are used by the C<Level> option in the constructor.
1437 Z_DEFAULT_COMPRESSION
1441 These symbolic constants are used by the C<Strategy> option in the constructor.
1451 These symbolic constants are used by the C<Method> option in the
1465 =head2 Apache::GZip Revisited
1467 See L<IO::Compress::Zlib::FAQ|IO::Compress::Zlib::FAQ/"Apache::GZip Revisited">
1471 =head2 Working with Net::FTP
1473 See L<IO::Compress::Zlib::FAQ|IO::Compress::Zlib::FAQ/"Compressed files and Net::FTP">
1477 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>
1479 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1481 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1482 L<Archive::Tar|Archive::Tar>,
1483 L<IO::Zlib|IO::Zlib>
1485 For RFC 1950, 1951 and 1952 see
1486 F<http://www.faqs.org/rfcs/rfc1950.html>,
1487 F<http://www.faqs.org/rfcs/rfc1951.html> and
1488 F<http://www.faqs.org/rfcs/rfc1952.html>
1490 The I<zlib> compression library was written by Jean-loup Gailly
1491 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1493 The primary site for the I<zlib> compression library is
1494 F<http://www.zlib.org>.
1496 The primary site for gzip is F<http://www.gzip.org>.
1500 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1502 =head1 MODIFICATION HISTORY
1504 See the Changes file.
1506 =head1 COPYRIGHT AND LICENSE
1508 Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
1510 This program is free software; you can redistribute it and/or
1511 modify it under the same terms as Perl itself.