1 package IO::Compress::Zip ;
7 use IO::Compress::Base::Common 2.004 qw(:Status createSelfTiedObject);
8 use IO::Compress::RawDeflate 2.004 ;
9 use IO::Compress::Adapter::Deflate 2.004 ;
10 use IO::Compress::Adapter::Identity 2.004 ;
11 use IO::Compress::Zlib::Extra 2.004 ;
12 use IO::Compress::Zip::Constants 2.004 ;
15 use Compress::Raw::Zlib 2.004 qw(crc32) ;
18 eval { require IO::Compress::Adapter::Bzip2 ;
19 import IO::Compress::Adapter::Bzip2 2.004 ;
20 require IO::Compress::Bzip2 ;
21 import IO::Compress::Bzip2 2.004 ;
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(@_);
63 my ($obj, $errstr, $errno) ;
65 if (*$self->{ZipData}{Method} == ZIP_CM_STORE) {
66 ($obj, $errstr, $errno) = IO::Compress::Adapter::Identity::mkCompObject(
68 $got->value('Strategy')
71 elsif (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
72 ($obj, $errstr, $errno) = IO::Compress::Adapter::Deflate::mkCompObject(
74 $got->value('Adler32'),
76 $got->value('Strategy')
79 elsif (*$self->{ZipData}{Method} == ZIP_CM_BZIP2) {
80 ($obj, $errstr, $errno) = IO::Compress::Adapter::Bzip2::mkCompObject(
81 $got->value('BlockSize100K'),
82 $got->value('WorkFactor'),
83 $got->value('Verbosity')
85 *$self->{ZipData}{CRC32} = crc32(undef);
88 return $self->saveErrorString(undef, $errstr, $errno)
91 if (! defined *$self->{ZipData}{StartOffset}) {
92 *$self->{ZipData}{StartOffset} = 0;
93 *$self->{ZipData}{Offset} = new U64 ;
103 *$self->{Compress}->reset();
104 *$self->{ZipData}{CRC32} = Compress::Raw::Zlib::crc32('');
109 sub filterUncompressed
113 if (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
114 *$self->{ZipData}{CRC32} = *$self->{Compress}->crc32();
117 *$self->{ZipData}{CRC32} = crc32(${$_[0]}, *$self->{ZipData}{CRC32});
127 *$self->{ZipData}{StartOffset} = *$self->{ZipData}{Offset}->get32bit() ;
130 $filename = $param->value('Name') || '';
133 $comment = $param->value('Comment') || '';
137 my $time = _unixToDosTime($param->value('Time'));
142 my $osCode = $param->value('OS_Code') ;
143 my $extFileAttr = 0 ;
145 if (*$self->{ZipData}{Zip64}) {
149 $x .= pack "V V", 0, 0 ; # uncompressedLength
150 $x .= pack "V V", 0, 0 ; # compressedLength
151 $x .= *$self->{ZipData}{Offset}->getPacked_V64() ; # offset to local hdr
152 #$x .= pack "V ", 0 ; # disk no
154 $x = IO::Compress::Zlib::Extra::mkSubField(ZIP_EXTRA_ID_ZIP64, $x);
159 if (! $param->value('Minimal')) {
160 if (defined $param->value('exTime'))
162 $extra .= mkExtendedTime($param->value('MTime'),
163 $param->value('ATime'),
164 $param->value('CTime'));
166 $ctlExtra .= mkExtendedTime($param->value('MTime'));
169 if ( $param->value('UID') && $osCode == ZIP_OS_CODE_UNIX)
171 $extra .= mkUnix2Extra( $param->value('UID'), $param->value('GID'));
172 $ctlExtra .= mkUnix2Extra();
175 # TODO - this code assumes Unix.
176 #$extFileAttr = 0666 << 16
177 # if $osCode == ZIP_OS_CODE_UNIX ;
179 $extFileAttr = $param->value('ExtAttr')
180 if defined $param->value('ExtAttr') ;
182 $extra .= $param->value('ExtraFieldLocal')
183 if defined $param->value('ExtraFieldLocal');
185 $ctlExtra .= $param->value('ExtraFieldCentral')
186 if defined $param->value('ExtraFieldCentral');
190 $gpFlag |= ZIP_GP_FLAG_STREAMING_MASK
191 if *$self->{ZipData}{Stream} ;
193 my $method = *$self->{ZipData}{Method} ;
195 my $version = $ZIP_CM_MIN_VERSIONS{$method};
196 $version = ZIP64_MIN_VERSION
197 if ZIP64_MIN_VERSION > $version && *$self->{ZipData}{Zip64};
198 my $madeBy = ($param->value('OS_Code') << 8) + $version;
199 my $extract = $version;
201 *$self->{ZipData}{Version} = $version;
202 *$self->{ZipData}{MadeBy} = $madeBy;
205 $ifa |= ZIP_IFA_TEXT_MASK
206 if $param->value('TextFlag');
208 $hdr .= pack "V", ZIP_LOCAL_HDR_SIG ; # signature
209 $hdr .= pack 'v', $extract ; # extract Version & OS
210 $hdr .= pack 'v', $gpFlag ; # general purpose flag (set streaming mode)
211 $hdr .= pack 'v', $method ; # compression method (deflate)
212 $hdr .= pack 'V', $time ; # last mod date/time
213 $hdr .= pack 'V', 0 ; # crc32 - 0 when streaming
214 $hdr .= pack 'V', $empty ; # compressed length - 0 when streaming
215 $hdr .= pack 'V', $empty ; # uncompressed length - 0 when streaming
216 $hdr .= pack 'v', length $filename ; # filename length
217 $hdr .= pack 'v', length $extra ; # extra length
225 $ctl .= pack "V", ZIP_CENTRAL_HDR_SIG ; # signature
226 $ctl .= pack 'v', $madeBy ; # version made by
227 $ctl .= pack 'v', $extract ; # extract Version
228 $ctl .= pack 'v', $gpFlag ; # general purpose flag (streaming mode)
229 $ctl .= pack 'v', $method ; # compression method (deflate)
230 $ctl .= pack 'V', $time ; # last mod date/time
231 $ctl .= pack 'V', 0 ; # crc32
232 $ctl .= pack 'V', $empty ; # compressed length
233 $ctl .= pack 'V', $empty ; # uncompressed length
234 $ctl .= pack 'v', length $filename ; # filename length
235 $ctl .= pack 'v', length $ctlExtra ; # extra length
236 $ctl .= pack 'v', length $comment ; # file comment length
237 $ctl .= pack 'v', 0 ; # disk number start
238 $ctl .= pack 'v', $ifa ; # internal file attributes
239 $ctl .= pack 'V', $extFileAttr ; # external file attributes
240 if (! *$self->{ZipData}{Zip64}) {
241 $ctl .= pack 'V', *$self->{ZipData}{Offset}->get32bit() ; # offset to local header
244 $ctl .= pack 'V', $empty ; # offset to local header
248 *$self->{ZipData}{StartOffset64} = 4 + length $ctl;
252 *$self->{ZipData}{Offset}->add(length $hdr) ;
254 *$self->{ZipData}{CentralHeader} = $ctl;
264 if (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
265 $crc32 = pack "V", *$self->{Compress}->crc32();
268 $crc32 = pack "V", *$self->{ZipData}{CRC32};
271 my $ctl = *$self->{ZipData}{CentralHeader} ;
274 if (! *$self->{ZipData}{Zip64}) {
275 $sizes .= *$self->{CompSize}->getPacked_V32() ; # Compressed size
276 $sizes .= *$self->{UnCompSize}->getPacked_V32() ; # Uncompressed size
279 $sizes .= *$self->{CompSize}->getPacked_V64() ; # Compressed size
280 $sizes .= *$self->{UnCompSize}->getPacked_V64() ; # Uncompressed size
283 my $data = $crc32 . $sizes ;
288 if (*$self->{ZipData}{Stream}) {
289 $hdr = pack "V", ZIP_DATA_HDR_SIG ; # signature
293 $self->writeAt(*$self->{ZipData}{StartOffset} + 14, $data)
297 if (! *$self->{ZipData}{Zip64})
298 { substr($ctl, 16, length $data) = $data }
300 substr($ctl, 16, length $crc32) = $crc32 ;
301 my $s = *$self->{UnCompSize}->getPacked_V64() ; # Uncompressed size
302 $s .= *$self->{CompSize}->getPacked_V64() ; # Compressed size
303 substr($ctl, *$self->{ZipData}{StartOffset64}, length $s) = $s ;
306 *$self->{ZipData}{Offset}->add(length($hdr));
307 *$self->{ZipData}{Offset}->add( *$self->{CompSize} );
308 push @{ *$self->{ZipData}{CentralDir} }, $ctl ;
318 $comment = *$self->{ZipData}{ZipComment} ;
320 my $cd_offset = *$self->{ZipData}{Offset}->get32bit() ; # offset to start central dir
322 my $entries = @{ *$self->{ZipData}{CentralDir} };
323 my $cd = join '', @{ *$self->{ZipData}{CentralDir} };
324 my $cd_len = length $cd ;
328 if ( *$self->{ZipData}{Zip64} ) {
330 my $v = *$self->{ZipData}{Version} ;
331 my $mb = *$self->{ZipData}{MadeBy} ;
332 $z64e .= pack 'v', $v ; # Version made by
333 $z64e .= pack 'v', $mb ; # Version to extract
334 $z64e .= pack 'V', 0 ; # number of disk
335 $z64e .= pack 'V', 0 ; # number of disk with central dir
336 $z64e .= U64::pack_V64 $entries ; # entries in central dir on this disk
337 $z64e .= U64::pack_V64 $entries ; # entries in central dir
338 $z64e .= U64::pack_V64 $cd_len ; # size of central dir
339 $z64e .= *$self->{ZipData}{Offset}->getPacked_V64() ; # offset to start central dir
341 $z64e = pack("V", ZIP64_END_CENTRAL_REC_HDR_SIG) # signature
342 . U64::pack_V64(length $z64e)
345 *$self->{ZipData}{Offset}->add(length $cd) ;
347 $z64e .= pack "V", ZIP64_END_CENTRAL_LOC_HDR_SIG; # signature
348 $z64e .= pack 'V', 0 ; # number of disk with central dir
349 $z64e .= *$self->{ZipData}{Offset}->getPacked_V64() ; # offset to end zip64 central dir
350 $z64e .= pack 'V', 1 ; # Total number of disks
352 # TODO - fix these when info-zip 3 is fixed.
359 $ecd .= pack "V", ZIP_END_CENTRAL_HDR_SIG ; # signature
360 $ecd .= pack 'v', 0 ; # number of disk
361 $ecd .= pack 'v', 0 ; # number of disk with central dir
362 $ecd .= pack 'v', $entries ; # entries in central dir on this disk
363 $ecd .= pack 'v', $entries ; # entries in central dir
364 $ecd .= pack 'V', $cd_len ; # size of central dir
365 $ecd .= pack 'V', $cd_offset ; # offset to start central dir
366 $ecd .= pack 'v', length $comment ; # zipfile comment length
369 return $cd . $z64e . $ecd ;
377 $got->value('CRC32' => 1);
379 if (! $got->parsed('Time') ) {
380 # Modification time defaults to now.
381 $got->value('Time' => time) ;
384 if (! $got->parsed('exTime') ) {
385 my $timeRef = $got->value('exTime');
386 if ( defined $timeRef) {
387 return $self->saveErrorString(undef, "exTime not a 3-element array ref")
388 if ref $timeRef ne 'ARRAY' || @$timeRef != 3;
391 $got->value("MTime", $timeRef->[1]);
392 $got->value("ATime", $timeRef->[0]);
393 $got->value("CTime", $timeRef->[2]);
396 *$self->{ZipData}{Zip64} = $got->value('Zip64');
397 *$self->{ZipData}{Stream} = $got->value('Stream');
399 return $self->saveErrorString(undef, "Zip64 only supported if Stream enabled")
400 if *$self->{ZipData}{Zip64} && ! *$self->{ZipData}{Stream} ;
402 my $method = $got->value('Method');
403 return $self->saveErrorString(undef, "Unknown Method '$method'")
404 if ! defined $ZIP_CM_MIN_VERSIONS{$method};
406 return $self->saveErrorString(undef, "Bzip2 not available")
407 if $method == ZIP_CM_BZIP2 and
408 ! defined $IO::Compress::Adapter::Bzip2::VERSION;
410 *$self->{ZipData}{Method} = $method;
412 *$self->{ZipData}{ZipComment} = $got->value('ZipComment') ;
414 for my $name (qw( ExtraFieldLocal ExtraFieldCentral ))
416 my $data = $got->value($name) ;
418 my $bad = IO::Compress::Zlib::Extra::parseExtraField($data, 1, 0) ;
419 return $self->saveErrorString(undef, "Error with $name Parameter: $bad")
422 $got->value($name, $data) ;
427 if defined $IO::Compress::Bzip2::VERSION
428 and ! IO::Compress::Bzip2::ckParams($self, $got);
437 # return $self->mkHeader(*$self->{Got});
444 use IO::Compress::Base::Common 2.004 qw(:Parse);
445 use Compress::Raw::Zlib 2.004 qw(Z_DEFLATED Z_DEFAULT_COMPRESSION Z_DEFAULT_STRATEGY);
449 @Bzip2 = IO::Compress::Bzip2::getExtraParams($self)
450 if defined $IO::Compress::Bzip2::VERSION;
454 $self->getZlibParams(),
456 'Stream' => [1, 1, Parse_boolean, 1],
457 #'Store' => [0, 1, Parse_boolean, 0],
458 'Method' => [0, 1, Parse_unsigned, ZIP_CM_DEFLATE],
460 # # Zip header fields
461 'Minimal' => [0, 1, Parse_boolean, 0],
462 'Zip64' => [0, 1, Parse_boolean, 0],
463 'Comment' => [0, 1, Parse_any, ''],
464 'ZipComment'=> [0, 1, Parse_any, ''],
465 'Name' => [0, 1, Parse_any, ''],
466 'Time' => [0, 1, Parse_any, undef],
467 'exTime' => [0, 1, Parse_any, undef],
468 'ExtAttr' => [0, 1, Parse_any, 0],
469 'OS_Code' => [0, 1, Parse_unsigned, $Compress::Raw::Zlib::gzip_os_code],
471 'TextFlag' => [0, 1, Parse_boolean, 0],
472 'ExtraFieldLocal' => [0, 1, Parse_any, undef],
473 'ExtraFieldCentral'=> [0, 1, Parse_any, undef],
481 return ('IO::Uncompress::Unzip',
482 \$IO::Uncompress::Unzip::UnzipError);
489 my $filename = shift ;
491 my ($mode, $uid, $gid, $atime, $mtime, $ctime)
492 = (stat($filename))[2, 4,5, 8,9,10] ;
494 $params->value('Name' => $filename)
495 if ! $params->parsed('Name') ;
497 $params->value('Time' => $mtime)
498 if ! $params->parsed('Time') ;
500 if ( ! $params->parsed('exTime'))
502 $params->value('MTime' => $mtime) ;
503 $params->value('ATime' => $atime) ;
504 $params->value('CTime' => undef) ; # No Creation time
507 $params->value('ExtAttr' => $mode << 16)
508 if ! $params->parsed('ExtAttr');
510 $params->value('UID' => $uid) ;
511 $params->value('GID' => $gid) ;
517 # order expected is m, a, c
528 $times .= pack("V", $time);
534 return IO::Compress::Zlib::Extra::mkSubField(ZIP_EXTRA_ID_EXT_TIMESTAMP,
535 pack("C", $flags) . $times);
543 $ids .= pack("v", $id);
546 return IO::Compress::Zlib::Extra::mkSubField(ZIP_EXTRA_ID_INFO_ZIP_UNIX2,
552 sub _unixToDosTime # Archive::Zip::Member
555 # TODO - add something to cope with unix time < 1980
556 my ( $sec, $min, $hour, $mday, $mon, $year ) = localtime($time_t);
558 $dt += ( $sec >> 1 );
559 $dt += ( $min << 5 );
560 $dt += ( $hour << 11 );
561 $dt += ( $mday << 16 );
562 $dt += ( ( $mon + 1 ) << 21 );
563 $dt += ( ( $year - 80 ) << 25 );
575 IO::Compress::Zip - Write zip files/buffers
581 use IO::Compress::Zip qw(zip $ZipError) ;
584 my $status = zip $input => $output [,OPTS]
585 or die "zip failed: $ZipError\n";
587 my $z = new IO::Compress::Zip $output [,OPTS]
588 or die "zip failed: $ZipError\n";
591 $z->printf($format, $string);
593 $z->syswrite($string [, $length, $offset]);
597 $z->seek($position, $whence);
602 $z->input_line_number();
603 $z->newStream( [OPTS] );
614 printf $z $format, $string;
617 seek $z, $position, $whence
626 This module provides a Perl interface that allows writing zip
627 compressed data to files or buffer.
637 The primary purpose of this module is to provide streaming write access to
638 zip files and buffers. It is not a general-purpose file archiver. If that
639 is what you want, check out C<Archive::Zip>.
641 At present three compression methods are supported by IO::Compress::Zip,
642 namely Store (no compression at all), Deflate and Bzip2.
644 Note that to create Bzip2 content, the module C<IO::Compress::Bzip2> must
650 For reading zip files/buffers, see the companion module
651 L<IO::Uncompress::Unzip|IO::Uncompress::Unzip>.
654 =head1 Functional Interface
656 A top-level function, C<zip>, is provided to carry out
657 "one-shot" compression between buffers and/or files. For finer
658 control over the compression process, see the L</"OO Interface">
661 use IO::Compress::Zip qw(zip $ZipError) ;
663 zip $input => $output [,OPTS]
664 or die "zip failed: $ZipError\n";
668 The functional interface needs Perl5.005 or better.
671 =head2 zip $input => $output [, OPTS]
674 C<zip> expects at least two parameters, C<$input> and C<$output>.
676 =head3 The C<$input> parameter
678 The parameter, C<$input>, is used to define the source of
679 the uncompressed data.
681 It can take one of the following forms:
687 If the C<$input> parameter is a simple scalar, it is assumed to be a
688 filename. This file will be opened for reading and the input data
689 will be read from it.
693 If the C<$input> parameter is a filehandle, the input data will be
695 The string '-' can be used as an alias for standard input.
697 =item A scalar reference
699 If C<$input> is a scalar reference, the input data will be read
702 =item An array reference
704 If C<$input> is an array reference, each element in the array must be a
707 The input data will be read from each file in turn.
709 The complete array will be walked to ensure that it only
710 contains valid filenames before any data is compressed.
714 =item An Input FileGlob string
716 If C<$input> is a string that is delimited by the characters "<" and ">"
717 C<zip> will assume that it is an I<input fileglob string>. The
718 input is the list of files that match the fileglob.
720 If the fileglob does not match any files ...
722 See L<File::GlobMapper|File::GlobMapper> for more details.
727 If the C<$input> parameter is any other type, C<undef> will be returned.
730 In addition, if C<$input> is a simple filename, the default values for
731 the C<Name>, C<Time>, C<ExtAttr> and C<exTime> options will be sourced from that file.
733 If you do not want to use these defaults they can be overridden by
734 explicitly setting the C<Name>, C<Time>, C<ExtAttr> and C<exTime> options or by setting the
735 C<Minimal> parameter.
739 =head3 The C<$output> parameter
741 The parameter C<$output> is used to control the destination of the
742 compressed data. This parameter can take one of these forms.
748 If the C<$output> parameter is a simple scalar, it is assumed to be a
749 filename. This file will be opened for writing and the compressed
750 data will be written to it.
754 If the C<$output> parameter is a filehandle, the compressed data
755 will be written to it.
756 The string '-' can be used as an alias for standard output.
759 =item A scalar reference
761 If C<$output> is a scalar reference, the compressed data will be
762 stored in C<$$output>.
766 =item An Array Reference
768 If C<$output> is an array reference, the compressed data will be
769 pushed onto the array.
771 =item An Output FileGlob
773 If C<$output> is a string that is delimited by the characters "<" and ">"
774 C<zip> will assume that it is an I<output fileglob string>. The
775 output is the list of files that match the fileglob.
777 When C<$output> is an fileglob string, C<$input> must also be a fileglob
778 string. Anything else is an error.
782 If the C<$output> parameter is any other type, C<undef> will be returned.
790 When C<$input> maps to multiple files/buffers and C<$output> is a single
791 file/buffer the input files/buffers will each be stored
792 in C<$output> as a distinct entry.
799 =head2 Optional Parameters
801 Unless specified below, the optional parameters for C<zip>,
802 C<OPTS>, are the same as those used with the OO interface defined in the
803 L</"Constructor Options"> section below.
807 =item C<< AutoClose => 0|1 >>
809 This option applies to any input or output data streams to
810 C<zip> that are filehandles.
812 If C<AutoClose> is specified, and the value is true, it will result in all
813 input and/or output filehandles being closed once C<zip> has
816 This parameter defaults to 0.
819 =item C<< BinModeIn => 0|1 >>
821 When reading from a file or filehandle, set C<binmode> before reading.
829 =item C<< Append => 0|1 >>
841 To read the contents of the file C<file1.txt> and write the compressed
842 data to the file C<file1.txt.zip>.
846 use IO::Compress::Zip qw(zip $ZipError) ;
848 my $input = "file1.txt";
849 zip $input => "$input.zip"
850 or die "zip failed: $ZipError\n";
853 To read from an existing Perl filehandle, C<$input>, and write the
854 compressed data to a buffer, C<$buffer>.
858 use IO::Compress::Zip qw(zip $ZipError) ;
861 my $input = new IO::File "<file1.txt"
862 or die "Cannot open 'file1.txt': $!\n" ;
864 zip $input => \$buffer
865 or die "zip failed: $ZipError\n";
867 To compress all files in the directory "/my/home" that match "*.txt"
868 and store the compressed data in the same directory
872 use IO::Compress::Zip qw(zip $ZipError) ;
874 zip '</my/home/*.txt>' => '<*.zip>'
875 or die "zip failed: $ZipError\n";
877 and if you want to compress each file one at a time, this will do the trick
881 use IO::Compress::Zip qw(zip $ZipError) ;
883 for my $input ( glob "/my/home/*.txt" )
885 my $output = "$input.zip" ;
886 zip $input => $output
887 or die "Error compressing '$input': $ZipError\n";
895 The format of the constructor for C<IO::Compress::Zip> is shown below
897 my $z = new IO::Compress::Zip $output [,OPTS]
898 or die "IO::Compress::Zip failed: $ZipError\n";
900 It returns an C<IO::Compress::Zip> object on success and undef on failure.
901 The variable C<$ZipError> will contain an error message on failure.
903 If you are running Perl 5.005 or better the object, C<$z>, returned from
904 IO::Compress::Zip can be used exactly like an L<IO::File|IO::File> filehandle.
905 This means that all normal output file operations can be carried out
907 For example, to write to a compressed file/buffer you can use either of
910 $z->print("hello world\n");
911 print $z "hello world\n";
913 The mandatory parameter C<$output> is used to control the destination
914 of the compressed data. This parameter can take one of these forms.
920 If the C<$output> parameter is a simple scalar, it is assumed to be a
921 filename. This file will be opened for writing and the compressed data
922 will be written to it.
926 If the C<$output> parameter is a filehandle, the compressed data will be
928 The string '-' can be used as an alias for standard output.
931 =item A scalar reference
933 If C<$output> is a scalar reference, the compressed data will be stored
938 If the C<$output> parameter is any other type, C<IO::Compress::Zip>::new will
941 =head2 Constructor Options
943 C<OPTS> is any combination of the following options:
947 =item C<< AutoClose => 0|1 >>
949 This option is only valid when the C<$output> parameter is a filehandle. If
950 specified, and the value is true, it will result in the C<$output> being
951 closed once either the C<close> method is called or the C<IO::Compress::Zip>
954 This parameter defaults to 0.
956 =item C<< Append => 0|1 >>
958 Opens C<$output> in append mode.
960 The behaviour of this option is dependent on the type of C<$output>.
966 If C<$output> is a buffer and C<Append> is enabled, all compressed data
967 will be append to the end if C<$output>. Otherwise C<$output> will be
968 cleared before any data is written to it.
972 If C<$output> is a filename and C<Append> is enabled, the file will be
973 opened in append mode. Otherwise the contents of the file, if any, will be
974 truncated before any compressed data is written to it.
978 If C<$output> is a filehandle, the file pointer will be positioned to the
979 end of the file via a call to C<seek> before any compressed data is written
980 to it. Otherwise the file pointer will not be moved.
984 This parameter defaults to 0.
988 =item C<< Name => $string >>
990 Stores the contents of C<$string> in the zip filename header field. If
991 C<Name> is not specified, no zip filename field will be created.
993 =item C<< Time => $number >>
995 Sets the last modified time field in the zip header to $number.
997 This field defaults to the time the C<IO::Compress::Zip> object was created
998 if this option is not specified.
1000 =item C<< ExtAttr => $attr >>
1002 This option controls the "external file attributes" field in the central
1003 header of the zip file. This is a 4 byte field.
1005 This option defaults to 0.
1007 =item C<< exTime => [$atime, $mtime, $ctime] >>
1009 This option expects an array reference with exactly three elements:
1010 C<$atime>, C<mtime> and C<$ctime>. These correspond to the last access
1011 time, last modification time and creation time respectively.
1013 It uses these values to set the extended timestamp field in the local zip
1014 header to the three values, $atime, $mtime, $ctime and sets the extended
1015 timestamp field in the central zip header to C<$mtime>.
1017 If any of the three values is C<undef> that time value will not be used.
1018 So, for example, to set only the C<$mtime> you would use this
1020 exTime => [undef, $mtime, undef]
1022 If the C<Minimal> option is set to true, this option will be ignored.
1024 By default no extended time field is created.
1026 =item C<< Comment => $comment >>
1028 Stores the contents of C<$comment> in the Central File Header of
1031 By default, no comment field is written to the zip file.
1033 =item C<< ZipComment => $comment >>
1035 Stores the contents of C<$comment> in the End of Central Directory record
1038 By default, no comment field is written to the zip file.
1040 =item C<< Method => $method >>
1042 Controls which compression method is used. At present three compression
1043 methods are supported, namely Store (no compression at all), Deflate and
1046 The symbols, ZIP_CM_STORE, ZIP_CM_DEFLATE and ZIP_CM_BZIP2 are used to
1047 select the compression method.
1049 These constants are not imported by C<IO::Compress::Zip> by default.
1051 use IO::Compress::Zip qw(:zip_method);
1052 use IO::Compress::Zip qw(:constants);
1053 use IO::Compress::Zip qw(:all);
1055 Note that to create Bzip2 content, the module C<IO::Compress::Bzip2> must
1056 be installed. A fatal error will be thrown if you attempt to create Bzip2
1057 content when C<IO::Compress::Bzip2> is not available.
1059 The default method is ZIP_CM_DEFLATE.
1061 =item C<< Stream => 0|1 >>
1063 This option controls whether the zip file/buffer output is created in
1066 Note that when outputting to a file with streaming mode disabled (C<Stream>
1067 is 0), the output file must be seekable.
1071 =item C<< Zip64 => 0|1 >>
1073 Create a Zip64 zip file/buffer. This option should only be used if you want
1074 to store files larger than 4 Gig.
1076 If you intend to manipulate the Zip64 zip files created with this module
1077 using an external zip/unzip make sure that it supports streaming Zip64.
1079 In particular, if you are using Info-Zip you need to have zip version 3.x
1080 or better to update a Zip64 archive and unzip version 6.x to read a zip64
1081 archive. At the time of writing both are beta status.
1083 When the C<Zip64> option is enabled, the C<Stream> option I<must> be
1088 =item C<< TextFlag => 0|1 >>
1090 This parameter controls the setting of a bit in the zip central header. It
1091 is used to signal that the data stored in the zip file/buffer is probably
1096 =item C<< ExtraFieldLocal => $data >>
1097 =item C<< ExtraFieldCentral => $data >>
1099 These options allows additional metadata to be stored in the local and
1100 central headers in the zip file/buffer.
1102 An extra field consists of zero or more subfields. Each subfield consists
1103 of a two byte header followed by the subfield data.
1105 The list of subfields can be supplied in any of the following formats
1107 ExtraFieldLocal => [$id1, $data1,
1112 ExtraFieldLocal => [ [$id1 => $data1],
1117 ExtraFieldLocal => { $id1 => $data1,
1122 Where C<$id1>, C<$id2> are two byte subfield ID's.
1124 If you use the hash syntax, you have no control over the order in which
1125 the ExtraSubFields are stored, plus you cannot have SubFields with
1128 Alternatively the list of subfields can by supplied as a scalar, thus
1130 ExtraField => $rawdata
1132 The Extended Time field, set using the C<exTime> option, is an example of
1137 If the C<Minimal> option is set to true, this option will be ignored.
1139 The maximum size of an extra field 65535 bytes.
1141 =item C<< Minimal => 1|0 >>
1143 If specified, this option will disable the creation of all extended fields
1144 in the zip local and central headers. So the C<exTime>, C<ExtraFieldLocal>
1145 and C<ExtraFieldCentral> options will be ignored.
1147 This parameter defaults to 0.
1149 =item C<< BlockSize100K => number >>
1151 Specify the number of 100K blocks bzip2 uses during compression.
1153 Valid values are from 1 to 9, where 9 is best compression.
1155 This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored
1160 =item C<< WorkFactor => number >>
1162 Specifies how much effort bzip2 should take before resorting to a slower
1163 fallback compression algorithm.
1165 Valid values range from 0 to 250, where 0 means use the default value 30.
1167 This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored
1177 Defines the compression level used by zlib. The value should either be
1178 a number between 0 and 9 (0 means no compression and 9 is maximum
1179 compression), or one of the symbolic constants defined below.
1184 Z_DEFAULT_COMPRESSION
1186 The default is Z_DEFAULT_COMPRESSION.
1188 Note, these constants are not imported by C<IO::Compress::Zip> by default.
1190 use IO::Compress::Zip qw(:strategy);
1191 use IO::Compress::Zip qw(:constants);
1192 use IO::Compress::Zip qw(:all);
1196 Defines the strategy used to tune the compression. Use one of the symbolic
1197 constants defined below.
1205 The default is Z_DEFAULT_STRATEGY.
1212 =item C<< Strict => 0|1 >>
1216 This is a placeholder option.
1235 Compresses and outputs the contents of the C<$data> parameter. This
1236 has the same behaviour as the C<print> built-in.
1238 Returns true if successful.
1244 $z->printf($format, $data)
1245 printf $z $format, $data
1247 Compresses and outputs the contents of the C<$data> parameter.
1249 Returns true if successful.
1256 $z->syswrite $data, $length
1257 $z->syswrite $data, $length, $offset
1259 Compresses and outputs the contents of the C<$data> parameter.
1261 Returns the number of uncompressed bytes written, or C<undef> if
1269 $z->write $data, $length
1270 $z->write $data, $length, $offset
1272 Compresses and outputs the contents of the C<$data> parameter.
1274 Returns the number of uncompressed bytes written, or C<undef> if
1283 $z->flush($flush_type);
1286 Flushes any pending compressed data to the output file/buffer.
1289 This method takes an optional parameter, C<$flush_type>, that controls
1290 how the flushing will be carried out. By default the C<$flush_type>
1291 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
1292 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
1293 strongly recommended that you only set the C<flush_type> parameter if
1294 you fully understand the implications of what it does - overuse of C<flush>
1295 can seriously degrade the level of compression achieved. See the C<zlib>
1296 documentation for details.
1299 Returns true on success.
1309 Returns the uncompressed file offset.
1320 Returns true if the C<close> method has been called.
1326 $z->seek($position, $whence);
1327 seek($z, $position, $whence);
1332 Provides a sub-set of the C<seek> functionality, with the restriction
1333 that it is only legal to seek forward in the output file/buffer.
1334 It is a fatal error to attempt to seek backward.
1336 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
1340 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1341 SEEK_CUR or SEEK_END.
1343 Returns 1 on success, 0 on failure.
1352 This is a noop provided for completeness.
1358 Returns true if the object currently refers to a opened file/buffer.
1362 my $prev = $z->autoflush()
1363 my $prev = $z->autoflush(EXPR)
1365 If the C<$z> object is associated with a file or a filehandle, this method
1366 returns the current autoflush setting for the underlying filehandle. If
1367 C<EXPR> is present, and is non-zero, it will enable flushing after every
1368 write/print operation.
1370 If C<$z> is associated with a buffer, this method has no effect and always
1373 B<Note> that the special variable C<$|> B<cannot> be used to set or
1374 retrieve the autoflush setting.
1376 =head2 input_line_number
1378 $z->input_line_number()
1379 $z->input_line_number(EXPR)
1382 This method always returns C<undef> when compressing.
1391 If the C<$z> object is associated with a file or a filehandle, this method
1392 will return the underlying file descriptor.
1394 If the C<$z> object is is associated with a buffer, this method will
1404 Flushes any pending compressed data and then closes the output file/buffer.
1408 For most versions of Perl this method will be automatically invoked if
1409 the IO::Compress::Zip object is destroyed (either explicitly or by the
1410 variable with the reference to the object going out of scope). The
1411 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1412 these cases, the C<close> method will be called automatically, but
1413 not until global destruction of all live objects when the program is
1416 Therefore, if you want your scripts to be able to run on all versions
1417 of Perl, you should call C<close> explicitly and not rely on automatic
1420 Returns true on success, otherwise 0.
1422 If the C<AutoClose> option has been enabled when the IO::Compress::Zip
1423 object was created, and the object is associated with a file, the
1424 underlying file will also be closed.
1429 =head2 newStream([OPTS])
1433 $z->newStream( [OPTS] )
1435 Closes the current compressed data stream and starts a new one.
1437 OPTS consists of any of the the options that are available when creating
1440 See the L</"Constructor Options"> section for more details.
1443 =head2 deflateParams
1455 A number of symbolic constants are required by some methods in
1456 C<IO::Compress::Zip>. None are imported by default.
1465 Imports C<zip>, C<$ZipError> and all symbolic
1466 constants that can be used by C<IO::Compress::Zip>. Same as doing this
1468 use IO::Compress::Zip qw(zip $ZipError :constants) ;
1472 Import all symbolic constants. Same as doing this
1475 use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
1480 These symbolic constants are used by the C<flush> method.
1491 These symbolic constants are used by the C<Level> option in the constructor.
1496 Z_DEFAULT_COMPRESSION
1501 These symbolic constants are used by the C<Strategy> option in the constructor.
1512 These symbolic constants are used by the C<Method> option in the
1542 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>
1544 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1546 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1547 L<Archive::Tar|Archive::Tar>,
1548 L<IO::Zlib|IO::Zlib>
1551 For RFC 1950, 1951 and 1952 see
1552 F<http://www.faqs.org/rfcs/rfc1950.html>,
1553 F<http://www.faqs.org/rfcs/rfc1951.html> and
1554 F<http://www.faqs.org/rfcs/rfc1952.html>
1556 The I<zlib> compression library was written by Jean-loup Gailly
1557 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1559 The primary site for the I<zlib> compression library is
1560 F<http://www.zlib.org>.
1562 The primary site for gzip is F<http://www.gzip.org>.
1569 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1573 =head1 MODIFICATION HISTORY
1575 See the Changes file.
1577 =head1 COPYRIGHT AND LICENSE
1579 Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1581 This program is free software; you can redistribute it and/or
1582 modify it under the same terms as Perl itself.