1 package IO::Compress::Zip ;
7 use IO::Compress::Base::Common 2.003 qw(:Status createSelfTiedObject);
8 use IO::Compress::RawDeflate 2.003 ;
9 use IO::Compress::Adapter::Deflate 2.003 ;
10 use IO::Compress::Adapter::Identity 2.003 ;
11 use IO::Compress::Zlib::Extra 2.003 ;
12 use IO::Compress::Zip::Constants 2.003 ;
15 use Compress::Raw::Zlib 2.003 qw(crc32) ;
18 eval { require IO::Compress::Adapter::Bzip2 ;
19 import IO::Compress::Adapter::Bzip2 2.003 ;
20 require IO::Compress::Bzip2 ;
21 import IO::Compress::Bzip2 2.003 ;
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'));
143 if (*$self->{ZipData}{Zip64}) {
147 $x .= pack "V V", 0, 0 ; # uncompressedLength
148 $x .= pack "V V", 0, 0 ; # compressedLength
149 $x .= *$self->{ZipData}{Offset}->getPacked_V64() ; # offset to local hdr
150 #$x .= pack "V ", 0 ; # disk no
152 $x = IO::Compress::Zlib::Extra::mkSubField(ZIP_EXTRA_ID_ZIP64, $x);
157 if (! $param->value('Minimal')) {
158 if (defined $param->value('exTime'))
160 $extra .= mkExtendedTime($param->value('MTime'),
161 $param->value('ATime'),
162 $param->value('CTime'));
164 $ctlExtra .= mkExtendedTime($param->value('MTime'));
167 # if ( $param->value('UID'))
169 # $extra .= mkUnixExtra( $param->value('UID'), $param->value('GID'));
170 # $ctlExtra .= mkUnixExtra();
173 $extra .= $param->value('ExtraFieldLocal')
174 if defined $param->value('ExtraFieldLocal');
176 $ctlExtra .= $param->value('ExtraFieldCentral')
177 if defined $param->value('ExtraFieldCentral');
181 # TODO - this code assumes Unix.
183 $extAttr = $param->value('Mode') << 16
184 if defined $param->value('Mode') ;
187 $gpFlag |= ZIP_GP_FLAG_STREAMING_MASK
188 if *$self->{ZipData}{Stream} ;
190 my $method = *$self->{ZipData}{Method} ;
192 my $version = $ZIP_CM_MIN_VERSIONS{$method};
193 $version = ZIP64_MIN_VERSION
194 if ZIP64_MIN_VERSION > $version && *$self->{ZipData}{Zip64};
195 my $madeBy = ($param->value('OS_Code') << 8) + $version;
196 my $extract = $version;
198 *$self->{ZipData}{Version} = $version;
199 *$self->{ZipData}{MadeBy} = $madeBy;
202 $ifa |= ZIP_IFA_TEXT_MASK
203 if $param->value('TextFlag');
205 $hdr .= pack "V", ZIP_LOCAL_HDR_SIG ; # signature
206 $hdr .= pack 'v', $extract ; # extract Version & OS
207 $hdr .= pack 'v', $gpFlag ; # general purpose flag (set streaming mode)
208 $hdr .= pack 'v', $method ; # compression method (deflate)
209 $hdr .= pack 'V', $time ; # last mod date/time
210 $hdr .= pack 'V', 0 ; # crc32 - 0 when streaming
211 $hdr .= pack 'V', $empty ; # compressed length - 0 when streaming
212 $hdr .= pack 'V', $empty ; # uncompressed length - 0 when streaming
213 $hdr .= pack 'v', length $filename ; # filename length
214 $hdr .= pack 'v', length $extra ; # extra length
222 $ctl .= pack "V", ZIP_CENTRAL_HDR_SIG ; # signature
223 $ctl .= pack 'v', $madeBy ; # version made by
224 $ctl .= pack 'v', $extract ; # extract Version
225 $ctl .= pack 'v', $gpFlag ; # general purpose flag (streaming mode)
226 $ctl .= pack 'v', $method ; # compression method (deflate)
227 $ctl .= pack 'V', $time ; # last mod date/time
228 $ctl .= pack 'V', 0 ; # crc32
229 $ctl .= pack 'V', $empty ; # compressed length
230 $ctl .= pack 'V', $empty ; # uncompressed length
231 $ctl .= pack 'v', length $filename ; # filename length
232 $ctl .= pack 'v', length $ctlExtra ; # extra length
233 $ctl .= pack 'v', length $comment ; # file comment length
234 $ctl .= pack 'v', 0 ; # disk number start
235 $ctl .= pack 'v', $ifa ; # internal file attributes
236 $ctl .= pack 'V', $extAttr ; # external file attributes
237 if (! *$self->{ZipData}{Zip64}) {
238 $ctl .= pack 'V', *$self->{ZipData}{Offset}->get32bit() ; # offset to local header
241 $ctl .= pack 'V', $empty ; # offset to local header
245 *$self->{ZipData}{StartOffset64} = 4 + length $ctl;
249 *$self->{ZipData}{Offset}->add(length $hdr) ;
251 *$self->{ZipData}{CentralHeader} = $ctl;
261 if (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
262 $crc32 = pack "V", *$self->{Compress}->crc32();
265 $crc32 = pack "V", *$self->{ZipData}{CRC32};
268 my $ctl = *$self->{ZipData}{CentralHeader} ;
271 if (! *$self->{ZipData}{Zip64}) {
272 $sizes .= *$self->{CompSize}->getPacked_V32() ; # Compressed size
273 $sizes .= *$self->{UnCompSize}->getPacked_V32() ; # Uncompressed size
276 $sizes .= *$self->{CompSize}->getPacked_V64() ; # Compressed size
277 $sizes .= *$self->{UnCompSize}->getPacked_V64() ; # Uncompressed size
280 my $data = $crc32 . $sizes ;
285 if (*$self->{ZipData}{Stream}) {
286 $hdr = pack "V", ZIP_DATA_HDR_SIG ; # signature
290 $self->writeAt(*$self->{ZipData}{StartOffset} + 14, $data)
294 if (! *$self->{ZipData}{Zip64})
295 { substr($ctl, 16, length $data) = $data }
297 substr($ctl, 16, length $crc32) = $crc32 ;
298 my $s = *$self->{UnCompSize}->getPacked_V64() ; # Uncompressed size
299 $s .= *$self->{CompSize}->getPacked_V64() ; # Compressed size
300 substr($ctl, *$self->{ZipData}{StartOffset64}, length $s) = $s ;
303 *$self->{ZipData}{Offset}->add(length($hdr));
304 *$self->{ZipData}{Offset}->add( *$self->{CompSize} );
305 push @{ *$self->{ZipData}{CentralDir} }, $ctl ;
315 $comment = *$self->{ZipData}{ZipComment} ;
317 my $cd_offset = *$self->{ZipData}{Offset}->get32bit() ; # offset to start central dir
319 my $entries = @{ *$self->{ZipData}{CentralDir} };
320 my $cd = join '', @{ *$self->{ZipData}{CentralDir} };
321 my $cd_len = length $cd ;
325 if ( *$self->{ZipData}{Zip64} ) {
327 my $v = *$self->{ZipData}{Version} ;
328 my $mb = *$self->{ZipData}{MadeBy} ;
329 $z64e .= pack 'v', $v ; # Version made by
330 $z64e .= pack 'v', $mb ; # Version to extract
331 $z64e .= pack 'V', 0 ; # number of disk
332 $z64e .= pack 'V', 0 ; # number of disk with central dir
333 $z64e .= U64::pack_V64 $entries ; # entries in central dir on this disk
334 $z64e .= U64::pack_V64 $entries ; # entries in central dir
335 $z64e .= U64::pack_V64 $cd_len ; # size of central dir
336 $z64e .= *$self->{ZipData}{Offset}->getPacked_V64() ; # offset to start central dir
338 $z64e = pack("V", ZIP64_END_CENTRAL_REC_HDR_SIG) # signature
339 . U64::pack_V64(length $z64e)
342 *$self->{ZipData}{Offset}->add(length $cd) ;
344 $z64e .= pack "V", ZIP64_END_CENTRAL_LOC_HDR_SIG; # signature
345 $z64e .= pack 'V', 0 ; # number of disk with central dir
346 $z64e .= *$self->{ZipData}{Offset}->getPacked_V64() ; # offset to end zip64 central dir
347 $z64e .= pack 'V', 1 ; # Total number of disks
349 # TODO - fix these when info-zip 3 is fixed.
356 $ecd .= pack "V", ZIP_END_CENTRAL_HDR_SIG ; # signature
357 $ecd .= pack 'v', 0 ; # number of disk
358 $ecd .= pack 'v', 0 ; # number of disk with central dir
359 $ecd .= pack 'v', $entries ; # entries in central dir on this disk
360 $ecd .= pack 'v', $entries ; # entries in central dir
361 $ecd .= pack 'V', $cd_len ; # size of central dir
362 $ecd .= pack 'V', $cd_offset ; # offset to start central dir
363 $ecd .= pack 'v', length $comment ; # zipfile comment length
366 return $cd . $z64e . $ecd ;
374 $got->value('CRC32' => 1);
376 if (! $got->parsed('Time') ) {
377 # Modification time defaults to now.
378 $got->value('Time' => time) ;
381 if (! $got->parsed('exTime') ) {
382 my $timeRef = $got->value('exTime');
383 if ( defined $timeRef) {
384 return $self->saveErrorString(undef, "exTime not a 3-element array ref")
385 if ref $timeRef ne 'ARRAY' || @$timeRef != 3;
388 $got->value("MTime", $timeRef->[1]);
389 $got->value("ATime", $timeRef->[0]);
390 $got->value("CTime", $timeRef->[2]);
393 *$self->{ZipData}{Zip64} = $got->value('Zip64');
394 *$self->{ZipData}{Stream} = $got->value('Stream');
396 return $self->saveErrorString(undef, "Zip64 only supported if Stream enabled")
397 if *$self->{ZipData}{Zip64} && ! *$self->{ZipData}{Stream} ;
399 my $method = $got->value('Method');
400 return $self->saveErrorString(undef, "Unknown Method '$method'")
401 if ! defined $ZIP_CM_MIN_VERSIONS{$method};
403 return $self->saveErrorString(undef, "Bzip2 not available")
404 if $method == ZIP_CM_BZIP2 and
405 ! defined $IO::Compress::Adapter::Bzip2::VERSION;
407 *$self->{ZipData}{Method} = $method;
409 *$self->{ZipData}{ZipComment} = $got->value('ZipComment') ;
411 for my $name (qw( ExtraFieldLocal ExtraFieldCentral ))
413 my $data = $got->value($name) ;
415 my $bad = IO::Compress::Zlib::Extra::parseExtraField($data, 1, 0) ;
416 return $self->saveErrorString(undef, "Error with $name Parameter: $bad")
419 $got->value($name, $data) ;
424 if defined $IO::Compress::Bzip2::VERSION
425 and ! IO::Compress::Bzip2::ckParams($self, $got);
434 # return $self->mkHeader(*$self->{Got});
441 use IO::Compress::Base::Common 2.003 qw(:Parse);
442 use Compress::Raw::Zlib 2.003 qw(Z_DEFLATED Z_DEFAULT_COMPRESSION Z_DEFAULT_STRATEGY);
446 @Bzip2 = IO::Compress::Bzip2::getExtraParams($self)
447 if defined $IO::Compress::Bzip2::VERSION;
451 $self->getZlibParams(),
453 'Stream' => [1, 1, Parse_boolean, 1],
454 #'Store' => [0, 1, Parse_boolean, 0],
455 'Method' => [0, 1, Parse_unsigned, ZIP_CM_DEFLATE],
457 # # Zip header fields
458 'Minimal' => [0, 1, Parse_boolean, 0],
459 'Zip64' => [0, 1, Parse_boolean, 0],
460 'Comment' => [0, 1, Parse_any, ''],
461 'ZipComment'=> [0, 1, Parse_any, ''],
462 'Name' => [0, 1, Parse_any, ''],
463 'Time' => [0, 1, Parse_any, undef],
464 'exTime' => [0, 1, Parse_any, undef],
465 'OS_Code' => [0, 1, Parse_unsigned, $Compress::Raw::Zlib::gzip_os_code],
467 'TextFlag' => [0, 1, Parse_boolean, 0],
468 'ExtraFieldLocal' => [0, 1, Parse_any, undef],
469 'ExtraFieldCentral'=> [0, 1, Parse_any, undef],
477 return ('IO::Uncompress::Unzip',
478 \$IO::Uncompress::Unzip::UnzipError);
485 my $filename = shift ;
487 my ($mode, $uid, $gid, $atime, $mtime, $ctime)
488 = (stat($filename))[2, 4,5, 8,9,10] ;
490 $params->value('Name' => $filename)
491 if ! $params->parsed('Name') ;
493 $params->value('Time' => $mtime)
494 if ! $params->parsed('Time') ;
496 if ( ! $params->parsed('exTime'))
498 $params->value('MTime' => $mtime) ;
499 $params->value('ATime' => $atime) ;
500 $params->value('CTime' => $ctime) ;
503 $params->value('Mode' => $mode) ;
505 $params->value('UID' => $uid) ;
506 $params->value('GID' => $gid) ;
512 # order expected is m, a, c
523 $times .= pack("V", $time);
529 #return "UT" . pack("v C", length($times) + 1, $flags) . $times;
530 return IO::Compress::Zlib::Extra::mkSubField(ZIP_EXTRA_ID_EXT_TIMESTAMP,
531 pack("C", $flags) . $times);
539 $ids .= pack("v", $id);
542 #return "Ux" . pack("v", length $ids) . $ids;
543 return IO::Compress::Zlib::Extra::mkSubField(ZIP_EXTRA_ID_INFO_ZIP_UNIX, $ids);
548 sub _unixToDosTime # Archive::Zip::Member
551 # TODO - add something to cope with unix time < 1980
552 my ( $sec, $min, $hour, $mday, $mon, $year ) = localtime($time_t);
554 $dt += ( $sec >> 1 );
555 $dt += ( $min << 5 );
556 $dt += ( $hour << 11 );
557 $dt += ( $mday << 16 );
558 $dt += ( ( $mon + 1 ) << 21 );
559 $dt += ( ( $year - 80 ) << 25 );
571 IO::Compress::Zip - Write zip files/buffers
577 use IO::Compress::Zip qw(zip $ZipError) ;
580 my $status = zip $input => $output [,OPTS]
581 or die "zip failed: $ZipError\n";
583 my $z = new IO::Compress::Zip $output [,OPTS]
584 or die "zip failed: $ZipError\n";
587 $z->printf($format, $string);
589 $z->syswrite($string [, $length, $offset]);
593 $z->seek($position, $whence);
598 $z->input_line_number();
599 $z->newStream( [OPTS] );
610 printf $z $format, $string;
613 seek $z, $position, $whence
622 This module provides a Perl interface that allows writing zip
623 compressed data to files or buffer.
634 The primary purpose of this module is to provide streaming write access to
635 zip files and buffers. It is not a general-purpose file archiver. If that
636 is what you want, check out C<Archive::Zip>.
641 For reading zip files/buffers, see the companion module
642 L<IO::Uncompress::Unzip|IO::Uncompress::Unzip>.
645 =head1 Functional Interface
647 A top-level function, C<zip>, is provided to carry out
648 "one-shot" compression between buffers and/or files. For finer
649 control over the compression process, see the L</"OO Interface">
652 use IO::Compress::Zip qw(zip $ZipError) ;
654 zip $input => $output [,OPTS]
655 or die "zip failed: $ZipError\n";
659 The functional interface needs Perl5.005 or better.
662 =head2 zip $input => $output [, OPTS]
665 C<zip> expects at least two parameters, C<$input> and C<$output>.
667 =head3 The C<$input> parameter
669 The parameter, C<$input>, is used to define the source of
670 the uncompressed data.
672 It can take one of the following forms:
678 If the C<$input> parameter is a simple scalar, it is assumed to be a
679 filename. This file will be opened for reading and the input data
680 will be read from it.
684 If the C<$input> parameter is a filehandle, the input data will be
686 The string '-' can be used as an alias for standard input.
688 =item A scalar reference
690 If C<$input> is a scalar reference, the input data will be read
693 =item An array reference
695 If C<$input> is an array reference, each element in the array must be a
698 The input data will be read from each file in turn.
700 The complete array will be walked to ensure that it only
701 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.
718 If the C<$input> parameter is any other type, C<undef> will be returned.
721 In addition, if C<$input> is a simple filename, the default values for
722 the C<Name>, C<Time> and C<exTime> options will be sourced from that file.
724 If you do not want to use these defaults they can be overridden by
725 explicitly setting the C<Name>, C<Time> and C<exTime> options or by setting the
726 C<Minimal> parameter.
730 =head3 The C<$output> parameter
732 The parameter C<$output> is used to control the destination of the
733 compressed data. This parameter can take one of these forms.
739 If the C<$output> parameter is a simple scalar, it is assumed to be a
740 filename. This file will be opened for writing and the compressed
741 data will be written to it.
745 If the C<$output> parameter is a filehandle, the compressed data
746 will be written to it.
747 The string '-' can be used as an alias for standard output.
750 =item A scalar reference
752 If C<$output> is a scalar reference, the compressed data will be
753 stored in C<$$output>.
757 =item An Array Reference
759 If C<$output> is an array reference, the compressed data will be
760 pushed onto the array.
762 =item An Output FileGlob
764 If C<$output> is a string that is delimited by the characters "<" and ">"
765 C<zip> will assume that it is an I<output fileglob string>. The
766 output is the list of files that match the fileglob.
768 When C<$output> is an fileglob string, C<$input> must also be a fileglob
769 string. Anything else is an error.
773 If the C<$output> parameter is any other type, C<undef> will be returned.
781 When C<$input> maps to multiple files/buffers and C<$output> is a single
782 file/buffer the input files/buffers will each be stored
783 in C<$output> as a distinct entry.
790 =head2 Optional Parameters
792 Unless specified below, the optional parameters for C<zip>,
793 C<OPTS>, are the same as those used with the OO interface defined in the
794 L</"Constructor Options"> section below.
798 =item C<< AutoClose => 0|1 >>
800 This option applies to any input or output data streams to
801 C<zip> that are filehandles.
803 If C<AutoClose> is specified, and the value is true, it will result in all
804 input and/or output filehandles being closed once C<zip> has
807 This parameter defaults to 0.
810 =item C<< BinModeIn => 0|1 >>
812 When reading from a file or filehandle, set C<binmode> before reading.
820 =item C<< Append => 0|1 >>
832 To read the contents of the file C<file1.txt> and write the compressed
833 data to the file C<file1.txt.zip>.
837 use IO::Compress::Zip qw(zip $ZipError) ;
839 my $input = "file1.txt";
840 zip $input => "$input.zip"
841 or die "zip failed: $ZipError\n";
844 To read from an existing Perl filehandle, C<$input>, and write the
845 compressed data to a buffer, C<$buffer>.
849 use IO::Compress::Zip qw(zip $ZipError) ;
852 my $input = new IO::File "<file1.txt"
853 or die "Cannot open 'file1.txt': $!\n" ;
855 zip $input => \$buffer
856 or die "zip failed: $ZipError\n";
858 To compress all files in the directory "/my/home" that match "*.txt"
859 and store the compressed data in the same directory
863 use IO::Compress::Zip qw(zip $ZipError) ;
865 zip '</my/home/*.txt>' => '<*.zip>'
866 or die "zip failed: $ZipError\n";
868 and if you want to compress each file one at a time, this will do the trick
872 use IO::Compress::Zip qw(zip $ZipError) ;
874 for my $input ( glob "/my/home/*.txt" )
876 my $output = "$input.zip" ;
877 zip $input => $output
878 or die "Error compressing '$input': $ZipError\n";
886 The format of the constructor for C<IO::Compress::Zip> is shown below
888 my $z = new IO::Compress::Zip $output [,OPTS]
889 or die "IO::Compress::Zip failed: $ZipError\n";
891 It returns an C<IO::Compress::Zip> object on success and undef on failure.
892 The variable C<$ZipError> will contain an error message on failure.
894 If you are running Perl 5.005 or better the object, C<$z>, returned from
895 IO::Compress::Zip can be used exactly like an L<IO::File|IO::File> filehandle.
896 This means that all normal output file operations can be carried out
898 For example, to write to a compressed file/buffer you can use either of
901 $z->print("hello world\n");
902 print $z "hello world\n";
904 The mandatory parameter C<$output> is used to control the destination
905 of the compressed data. This parameter can take one of these forms.
911 If the C<$output> parameter is a simple scalar, it is assumed to be a
912 filename. This file will be opened for writing and the compressed data
913 will be written to it.
917 If the C<$output> parameter is a filehandle, the compressed data will be
919 The string '-' can be used as an alias for standard output.
922 =item A scalar reference
924 If C<$output> is a scalar reference, the compressed data will be stored
929 If the C<$output> parameter is any other type, C<IO::Compress::Zip>::new will
932 =head2 Constructor Options
934 C<OPTS> is any combination of the following options:
938 =item C<< AutoClose => 0|1 >>
940 This option is only valid when the C<$output> parameter is a filehandle. If
941 specified, and the value is true, it will result in the C<$output> being
942 closed once either the C<close> method is called or the C<IO::Compress::Zip>
945 This parameter defaults to 0.
947 =item C<< Append => 0|1 >>
949 Opens C<$output> in append mode.
951 The behaviour of this option is dependent on the type of C<$output>.
957 If C<$output> is a buffer and C<Append> is enabled, all compressed data
958 will be append to the end if C<$output>. Otherwise C<$output> will be
959 cleared before any data is written to it.
963 If C<$output> is a filename and C<Append> is enabled, the file will be
964 opened in append mode. Otherwise the contents of the file, if any, will be
965 truncated before any compressed data is written to it.
969 If C<$output> is a filehandle, the file pointer will be positioned to the
970 end of the file via a call to C<seek> before any compressed data is written
971 to it. Otherwise the file pointer will not be moved.
975 This parameter defaults to 0.
979 =item C<< Name => $string >>
981 Stores the contents of C<$string> in the zip filename header field. If
982 C<Name> is not specified, no zip filename field will be created.
984 =item C<< Time => $number >>
986 Sets the last modified time field in the zip header to $number.
988 This field defaults to the time the C<IO::Compress::Zip> object was created
989 if this option is not specified.
991 =item C<< exTime => [$atime, $mtime, $ctime] >>
993 This option expects an array reference with exactly three elements:
994 C<$atime>, C<mtime> and C<$ctime>. These correspond to the last access
995 time, last modification time and creation time respectively.
997 It uses these values to set the extended timestamp field in the local zip
998 header to the three values, $atime, $mtime, $ctime and sets the extended
999 timestamp field in the central zip header to C<$mtime>.
1001 If the C<Minimal> option is set to true, this option will be ignored.
1003 By default no extended time field is created.
1005 =item C<< Comment => $comment >>
1007 Stores the contents of C<$comment> in the Central File Header of
1010 By default, no comment field is written to the zip file.
1012 =item C<< ZipComment => $comment >>
1014 Stores the contents of C<$comment> in the End of Central Directory record
1017 By default, no comment field is written to the zip file.
1019 =item C<< Method => $method >>
1021 Controls which compression method is used. At present three compression
1022 methods are supported, namely Store (no compression at all), Deflate and
1025 The symbols, ZIP_CM_STORE, ZIP_CM_DEFLATE and ZIP_CM_BZIP2 are used to
1026 select the compression method.
1028 These constants are not imported by C<IO::Compress::Zip> by default.
1030 use IO::Compress::Zip qw(:zip_method);
1031 use IO::Compress::Zip qw(:constants);
1032 use IO::Compress::Zip qw(:all);
1034 Note that to create Bzip2 content, the module C<IO::Compress::Bzip2> must
1035 be installed. A fatal error will be thrown if you attempt to create Bzip2
1036 content when C<IO::Compress::Bzip2> is not available.
1038 The default method is ZIP_CM_DEFLATE.
1040 =item C<< Stream => 0|1 >>
1042 This option controls whether the zip file/buffer output is created in
1045 Note that when outputting to a file with streaming mode disabled (C<Stream>
1046 is 0), the output file must be seekable.
1052 =item C<< TextFlag => 0|1 >>
1054 This parameter controls the setting of a bit in the zip central header. It
1055 is used to signal that the data stored in the zip file/buffer is probably
1060 =item C<< ExtraFieldLocal => $data >>
1061 =item C<< ExtraFieldCentral => $data >>
1063 These options allows additional metadata to be stored in the local and
1064 central headers in the zip file/buffer.
1066 An extra field consists of zero or more subfields. Each subfield consists
1067 of a two byte header followed by the subfield data.
1069 The list of subfields can be supplied in any of the following formats
1071 ExtraFieldLocal => [$id1, $data1,
1076 ExtraFieldLocal => [ [$id1 => $data1],
1081 ExtraFieldLocal => { $id1 => $data1,
1086 Where C<$id1>, C<$id2> are two byte subfield ID's.
1088 If you use the hash syntax, you have no control over the order in which
1089 the ExtraSubFields are stored, plus you cannot have SubFields with
1092 Alternatively the list of subfields can by supplied as a scalar, thus
1094 ExtraField => $rawdata
1098 If the C<Minimal> option is set to true, this option will be ignored.
1100 The maximum size of an extra field 65535 bytes.
1102 =item C<< Minimal => 1|0 >>
1104 If specified, this option will disable the creation of all extended fields
1105 in the zip local and central headers.
1107 This parameter defaults to 0.
1109 =item C<< BlockSize100K => number >>
1111 Specify the number of 100K blocks bzip2 uses during compression.
1113 Valid values are from 1 to 9, where 9 is best compression.
1115 This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored
1120 =item C<< WorkFactor => number >>
1122 Specifies how much effort bzip2 should take before resorting to a slower
1123 fallback compression algorithm.
1125 Valid values range from 0 to 250, where 0 means use the default value 30.
1127 This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored
1137 Defines the compression level used by zlib. The value should either be
1138 a number between 0 and 9 (0 means no compression and 9 is maximum
1139 compression), or one of the symbolic constants defined below.
1144 Z_DEFAULT_COMPRESSION
1146 The default is Z_DEFAULT_COMPRESSION.
1148 Note, these constants are not imported by C<IO::Compress::Zip> by default.
1150 use IO::Compress::Zip qw(:strategy);
1151 use IO::Compress::Zip qw(:constants);
1152 use IO::Compress::Zip qw(:all);
1156 Defines the strategy used to tune the compression. Use one of the symbolic
1157 constants defined below.
1165 The default is Z_DEFAULT_STRATEGY.
1172 =item C<< Strict => 0|1 >>
1176 This is a placeholder option.
1195 Compresses and outputs the contents of the C<$data> parameter. This
1196 has the same behaviour as the C<print> built-in.
1198 Returns true if successful.
1204 $z->printf($format, $data)
1205 printf $z $format, $data
1207 Compresses and outputs the contents of the C<$data> parameter.
1209 Returns true if successful.
1216 $z->syswrite $data, $length
1217 $z->syswrite $data, $length, $offset
1219 Compresses and outputs the contents of the C<$data> parameter.
1221 Returns the number of uncompressed bytes written, or C<undef> if
1229 $z->write $data, $length
1230 $z->write $data, $length, $offset
1232 Compresses and outputs the contents of the C<$data> parameter.
1234 Returns the number of uncompressed bytes written, or C<undef> if
1243 $z->flush($flush_type);
1246 Flushes any pending compressed data to the output file/buffer.
1249 This method takes an optional parameter, C<$flush_type>, that controls
1250 how the flushing will be carried out. By default the C<$flush_type>
1251 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
1252 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
1253 strongly recommended that you only set the C<flush_type> parameter if
1254 you fully understand the implications of what it does - overuse of C<flush>
1255 can seriously degrade the level of compression achieved. See the C<zlib>
1256 documentation for details.
1259 Returns true on success.
1269 Returns the uncompressed file offset.
1280 Returns true if the C<close> method has been called.
1286 $z->seek($position, $whence);
1287 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.
1300 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1301 SEEK_CUR or SEEK_END.
1303 Returns 1 on success, 0 on failure.
1312 This is a noop provided for completeness.
1318 Returns true if the object currently refers to a opened file/buffer.
1322 my $prev = $z->autoflush()
1323 my $prev = $z->autoflush(EXPR)
1325 If the C<$z> object is associated with a file or a filehandle, this method
1326 returns the current autoflush setting for the underlying filehandle. If
1327 C<EXPR> is present, and is non-zero, it will enable flushing after every
1328 write/print operation.
1330 If C<$z> is associated with a buffer, this method has no effect and always
1333 B<Note> that the special variable C<$|> B<cannot> be used to set or
1334 retrieve the autoflush setting.
1336 =head2 input_line_number
1338 $z->input_line_number()
1339 $z->input_line_number(EXPR)
1342 This method always returns C<undef> when compressing.
1351 If the C<$z> object is associated with a file or a filehandle, this method
1352 will return the underlying file descriptor.
1354 If the C<$z> object is is associated with a buffer, this method will
1364 Flushes any pending compressed data and then closes the output file/buffer.
1368 For most versions of Perl this method will be automatically invoked if
1369 the IO::Compress::Zip object is destroyed (either explicitly or by the
1370 variable with the reference to the object going out of scope). The
1371 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1372 these cases, the C<close> method will be called automatically, but
1373 not until global destruction of all live objects when the program is
1376 Therefore, if you want your scripts to be able to run on all versions
1377 of Perl, you should call C<close> explicitly and not rely on automatic
1380 Returns true on success, otherwise 0.
1382 If the C<AutoClose> option has been enabled when the IO::Compress::Zip
1383 object was created, and the object is associated with a file, the
1384 underlying file will also be closed.
1389 =head2 newStream([OPTS])
1393 $z->newStream( [OPTS] )
1395 Closes the current compressed data stream and starts a new one.
1397 OPTS consists of any of the the options that are available when creating
1400 See the L</"Constructor Options"> section for more details.
1403 =head2 deflateParams
1415 A number of symbolic constants are required by some methods in
1416 C<IO::Compress::Zip>. None are imported by default.
1425 Imports C<zip>, C<$ZipError> and all symbolic
1426 constants that can be used by C<IO::Compress::Zip>. Same as doing this
1428 use IO::Compress::Zip qw(zip $ZipError :constants) ;
1432 Import all symbolic constants. Same as doing this
1435 use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
1440 These symbolic constants are used by the C<flush> method.
1451 These symbolic constants are used by the C<Level> option in the constructor.
1456 Z_DEFAULT_COMPRESSION
1461 These symbolic constants are used by the C<Strategy> option in the constructor.
1472 These symbolic constants are used by the C<Method> option in the
1502 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>
1504 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1506 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1507 L<Archive::Tar|Archive::Tar>,
1508 L<IO::Zlib|IO::Zlib>
1511 For RFC 1950, 1951 and 1952 see
1512 F<http://www.faqs.org/rfcs/rfc1950.html>,
1513 F<http://www.faqs.org/rfcs/rfc1951.html> and
1514 F<http://www.faqs.org/rfcs/rfc1952.html>
1516 The I<zlib> compression library was written by Jean-loup Gailly
1517 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1519 The primary site for the I<zlib> compression library is
1520 F<http://www.zlib.org>.
1522 The primary site for gzip is F<http://www.gzip.org>.
1529 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1533 =head1 MODIFICATION HISTORY
1535 See the Changes file.
1537 =head1 COPYRIGHT AND LICENSE
1539 Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1541 This program is free software; you can redistribute it and/or
1542 modify it under the same terms as Perl itself.