1IO::Compress::Zip(3pm) Perl Programmers Reference Guide IO::Compress::Zip(3pm)
2
6 IO::Compress::Zip - Write zip files/buffers
7
9 use IO::Compress::Zip qw(zip $ZipError) ;
10 my $status = zip $input => $output [,OPTS]
12 or die "zip failed: $ZipError\n";
13 my $z = new IO::Compress::Zip $output [,OPTS]
15 or die "zip failed: $ZipError\n";
16 $z->print($string);
18 $z->printf($format, $string);
19 $z->write($string);
20 $z->syswrite($string [, $length, $offset]);
21 $z->flush();
22 $z->tell();
23 $z->eof();
24 $z->seek($position, $whence);
25 $z->binmode();
26 $z->fileno();
27 $z->opened();
28 $z->autoflush();
29 $z->input_line_number();
30 $z->newStream( [OPTS] );
31 $z->deflateParams();
33 $z->close() ;
35 $ZipError ;
37 # IO::File mode
39 print $z $string;
41 printf $z $format, $string;
42 tell $z
43 eof $z
44 seek $z, $position, $whence
45 binmode $z
46 fileno $z
47 close $z ;
48
50 This module provides a Perl interface that allows writing zip
51 compressed data to files or buffer.
52 The primary purpose of this module is to provide streaming write access
54 to zip files and buffers. It is not a general-purpose file archiver. If
55 that is what you want, check out "Archive::Zip".
56 At present three compression methods are supported by
58 IO::Compress::Zip, namely Store (no compression at all), Deflate and
59 Bzip2.
60 Note that to create Bzip2 content, the module "IO::Compress::Bzip2"
62 must be installed.
63 For reading zip files/buffers, see the companion module
65 IO::Uncompress::Unzip.
66
68 A top-level function, "zip", is provided to carry out "one-shot"
69 compression between buffers and/or files. For finer control over the
70 compression process, see the "OO Interface" section.
71 use IO::Compress::Zip qw(zip $ZipError) ;
73 zip $input => $output [,OPTS]
75 or die "zip failed: $ZipError\n";
76 The functional interface needs Perl5.005 or better.
78 zip $input => $output [, OPTS]
80 "zip" expects at least two parameters, $input and $output.
81 The $input parameter
83 The parameter, $input, is used to define the source of the uncompressed
85 data.
86 It can take one of the following forms:
88 A filename
90 If the $input parameter is a simple scalar, it is assumed to be a
91 filename. This file will be opened for reading and the input data
92 will be read from it.
93 A filehandle
95 If the $input parameter is a filehandle, the input data will be
96 read from it. The string '-' can be used as an alias for standard
97 input.
98 A scalar reference
100 If $input is a scalar reference, the input data will be read from
101 $$input.
102 An array reference
104 If $input is an array reference, each element in the array must be
105 a filename.
106 The input data will be read from each file in turn.
108 The complete array will be walked to ensure that it only contains
110 valid filenames before any data is compressed.
111 An Input FileGlob string
113 If $input is a string that is delimited by the characters "<" and
114 ">" "zip" will assume that it is an input fileglob string. The
115 input is the list of files that match the fileglob.
116 If the fileglob does not match any files ...
118 See File::GlobMapper for more details.
120 If the $input parameter is any other type, "undef" will be returned.
122 In addition, if $input is a simple filename, the default values for the
124 "Name", "Time", "ExtAttr" and "exTime" options will be sourced from
125 that file.
126 If you do not want to use these defaults they can be overridden by
128 explicitly setting the "Name", "Time", "ExtAttr" and "exTime" options
129 or by setting the "Minimal" parameter.
130 The $output parameter
132 The parameter $output is used to control the destination of the
134 compressed data. This parameter can take one of these forms.
135 A filename
137 If the $output parameter is a simple scalar, it is assumed to be a
138 filename. This file will be opened for writing and the compressed
139 data will be written to it.
140 A filehandle
142 If the $output parameter is a filehandle, the compressed data will
143 be written to it. The string '-' can be used as an alias for
144 standard output.
145 A scalar reference
147 If $output is a scalar reference, the compressed data will be
148 stored in $$output.
149 An Array Reference
151 If $output is an array reference, the compressed data will be
152 pushed onto the array.
153 An Output FileGlob
155 If $output is a string that is delimited by the characters "<" and
156 ">" "zip" will assume that it is an output fileglob string. The
157 output is the list of files that match the fileglob.
158 When $output is an fileglob string, $input must also be a fileglob
160 string. Anything else is an error.
161 If the $output parameter is any other type, "undef" will be returned.
163 Notes
165 When $input maps to multiple files/buffers and $output is a single
166 file/buffer the input files/buffers will each be stored in $output as a
167 distinct entry.
168 Optional Parameters
170 Unless specified below, the optional parameters for "zip", "OPTS", are
171 the same as those used with the OO interface defined in the
172 "Constructor Options" section below.
173 "AutoClose => 0|1"
175 This option applies to any input or output data streams to "zip"
176 that are filehandles.
177 If "AutoClose" is specified, and the value is true, it will result
179 in all input and/or output filehandles being closed once "zip" has
180 completed.
181 This parameter defaults to 0.
183 "BinModeIn => 0|1"
185 When reading from a file or filehandle, set "binmode" before
186 reading.
187 Defaults to 0.
189 "Append => 0|1"
191 TODO
192 Examples
194 To read the contents of the file "file1.txt" and write the compressed
195 data to the file "file1.txt.zip".
196 use strict ;
198 use warnings ;
199 use IO::Compress::Zip qw(zip $ZipError) ;
200 my $input = "file1.txt";
202 zip $input => "$input.zip"
203 or die "zip failed: $ZipError\n";
204 To read from an existing Perl filehandle, $input, and write the
206 compressed data to a buffer, $buffer.
207 use strict ;
209 use warnings ;
210 use IO::Compress::Zip qw(zip $ZipError) ;
211 use IO::File ;
212 my $input = new IO::File "<file1.txt"
214 or die "Cannot open 'file1.txt': $!\n" ;
215 my $buffer ;
216 zip $input => \$buffer
217 or die "zip failed: $ZipError\n";
218 To compress all files in the directory "/my/home" that match "*.txt"
220 and store the compressed data in the same directory
221 use strict ;
223 use warnings ;
224 use IO::Compress::Zip qw(zip $ZipError) ;
225 zip '</my/home/*.txt>' => '<*.zip>'
227 or die "zip failed: $ZipError\n";
228 and if you want to compress each file one at a time, this will do the
230 trick
231 use strict ;
233 use warnings ;
234 use IO::Compress::Zip qw(zip $ZipError) ;
235 for my $input ( glob "/my/home/*.txt" )
237 {
238 my $output = "$input.zip" ;
239 zip $input => $output
240 or die "Error compressing '$input': $ZipError\n";
241 }
242
244 Constructor
245 The format of the constructor for "IO::Compress::Zip" is shown below
246 my $z = new IO::Compress::Zip $output [,OPTS]
248 or die "IO::Compress::Zip failed: $ZipError\n";
249 It returns an "IO::Compress::Zip" object on success and undef on
251 failure. The variable $ZipError will contain an error message on
252 failure.
253 If you are running Perl 5.005 or better the object, $z, returned from
255 IO::Compress::Zip can be used exactly like an IO::File filehandle.
256 This means that all normal output file operations can be carried out
257 with $z. For example, to write to a compressed file/buffer you can use
258 either of these forms
259 $z->print("hello world\n");
261 print $z "hello world\n";
262 The mandatory parameter $output is used to control the destination of
264 the compressed data. This parameter can take one of these forms.
265 A filename
267 If the $output parameter is a simple scalar, it is assumed to be a
268 filename. This file will be opened for writing and the compressed
269 data will be written to it.
270 A filehandle
272 If the $output parameter is a filehandle, the compressed data will
273 be written to it. The string '-' can be used as an alias for
274 standard output.
275 A scalar reference
277 If $output is a scalar reference, the compressed data will be
278 stored in $$output.
279 If the $output parameter is any other type, "IO::Compress::Zip"::new
281 will return undef.
282 Constructor Options
284 "OPTS" is any combination of the following options:
285 "AutoClose => 0|1"
287 This option is only valid when the $output parameter is a
288 filehandle. If specified, and the value is true, it will result in
289 the $output being closed once either the "close" method is called
290 or the "IO::Compress::Zip" object is destroyed.
291 This parameter defaults to 0.
293 "Append => 0|1"
295 Opens $output in append mode.
296 The behaviour of this option is dependent on the type of $output.
298 · A Buffer
300 If $output is a buffer and "Append" is enabled, all
302 compressed data will be append to the end if $output.
303 Otherwise $output will be cleared before any data is written
304 to it.
305 · A Filename
307 If $output is a filename and "Append" is enabled, the file
309 will be opened in append mode. Otherwise the contents of the
310 file, if any, will be truncated before any compressed data is
311 written to it.
312 · A Filehandle
314 If $output is a filehandle, the file pointer will be
316 positioned to the end of the file via a call to "seek" before
317 any compressed data is written to it. Otherwise the file
318 pointer will not be moved.
319 This parameter defaults to 0.
321 "Name => $string"
323 Stores the contents of $string in the zip filename header field.
324 If "Name" is not specified, no zip filename field will be created.
325 "Time => $number"
327 Sets the last modified time field in the zip header to $number.
328 This field defaults to the time the "IO::Compress::Zip" object was
330 created if this option is not specified.
331 "ExtAttr => $attr"
333 This option controls the "external file attributes" field in the
334 central header of the zip file. This is a 4 byte field.
335 If you are running a Unix derivative this value defaults to
337 0666 << 16
339 This should allow read/write access to any files that are
341 extracted from the zip file/buffer.
342 For all other systems it defaults to 0.
344 "exTime => [$atime, $mtime, $ctime]"
346 This option expects an array reference with exactly three
347 elements: $atime, "mtime" and $ctime. These correspond to the last
348 access time, last modification time and creation time
349 respectively.
350 It uses these values to set the extended timestamp field (ID is
352 "UT") in the local zip header using the three values, $atime,
353 $mtime, $ctime. In addition it sets the extended timestamp field
354 in the central zip header using $mtime.
355 If any of the three values is "undef" that time value will not be
357 used. So, for example, to set only the $mtime you would use this
358 exTime => [undef, $mtime, undef]
360 If the "Minimal" option is set to true, this option will be
362 ignored.
363 By default no extended time field is created.
365 "exUnix2 => [$uid, $gid]"
367 This option expects an array reference with exactly two elements:
368 $uid and $gid. These values correspond to the numeric user ID and
369 group ID of the owner of the files respectively.
370 When the "exUnix2" option is present it will trigger the creation
372 of a Unix2 extra field (ID is "Ux") in the local zip. This will be
373 populated with $uid and $gid. In addition an empty Unix2 extra
374 field will also be created in the central zip header
375 If the "Minimal" option is set to true, this option will be
377 ignored.
378 By default no Unix2 extra field is created.
380 "Comment => $comment"
382 Stores the contents of $comment in the Central File Header of the
383 zip file.
384 By default, no comment field is written to the zip file.
386 "ZipComment => $comment"
388 Stores the contents of $comment in the End of Central Directory
389 record of the zip file.
390 By default, no comment field is written to the zip file.
392 "Method => $method"
394 Controls which compression method is used. At present three
395 compression methods are supported, namely Store (no compression at
396 all), Deflate and Bzip2.
397 The symbols, ZIP_CM_STORE, ZIP_CM_DEFLATE and ZIP_CM_BZIP2 are
399 used to select the compression method.
400 These constants are not imported by "IO::Compress::Zip" by
402 default.
403 use IO::Compress::Zip qw(:zip_method);
405 use IO::Compress::Zip qw(:constants);
406 use IO::Compress::Zip qw(:all);
407 Note that to create Bzip2 content, the module
409 "IO::Compress::Bzip2" must be installed. A fatal error will be
410 thrown if you attempt to create Bzip2 content when
411 "IO::Compress::Bzip2" is not available.
412 The default method is ZIP_CM_DEFLATE.
414 "Stream => 0|1"
416 This option controls whether the zip file/buffer output is created
417 in streaming mode.
418 Note that when outputting to a file with streaming mode disabled
420 ("Stream" is 0), the output file must be seekable.
421 The default is 1.
423 "Zip64 => 0|1"
425 Create a Zip64 zip file/buffer. This option should only be used if
426 you want to store files larger than 4 Gig.
427 If you intend to manipulate the Zip64 zip files created with this
429 module using an external zip/unzip make sure that it supports
430 Zip64.
431 In particular, if you are using Info-Zip you need to have zip
433 version 3.x or better to update a Zip64 archive and unzip version
434 6.x to read a zip64 archive.
435 The default is 0.
437 "TextFlag => 0|1"
439 This parameter controls the setting of a bit in the zip central
440 header. It is used to signal that the data stored in the zip
441 file/buffer is probably text.
442 The default is 0.
444 "ExtraFieldLocal => $data" =item "ExtraFieldCentral => $data"
446 The "ExtraFieldLocal" option is used to store additional metadata
447 in the local header for the zip file/buffer. The
448 "ExtraFieldCentral" does the same for the matching central header.
449 An extra field consists of zero or more subfields. Each subfield
451 consists of a two byte header followed by the subfield data.
452 The list of subfields can be supplied in any of the following
454 formats
455 ExtraFieldLocal => [$id1, $data1,
457 $id2, $data2,
458 ...
459 ]
460 ExtraFieldLocal => [ [$id1 => $data1],
462 [$id2 => $data2],
463 ...
464 ]
465 ExtraFieldLocal => { $id1 => $data1,
467 $id2 => $data2,
468 ...
469 }
470 Where $id1, $id2 are two byte subfield ID's.
472 If you use the hash syntax, you have no control over the order in
474 which the ExtraSubFields are stored, plus you cannot have
475 SubFields with duplicate ID.
476 Alternatively the list of subfields can by supplied as a scalar,
478 thus
479 ExtraField => $rawdata
481 The Extended Time field (ID "UT"), set using the "exTime" option,
483 and the Unix2 extra field (ID "Ux), set using the "exUnix2"
484 option, are examples of extra fields.
485 If the "Minimal" option is set to true, this option will be
487 ignored.
488 The maximum size of an extra field 65535 bytes.
490 "Minimal => 1|0"
492 If specified, this option will disable the creation of all extra
493 fields in the zip local and central headers. So the "exTime",
494 "exUnix2", "ExtraFieldLocal" and "ExtraFieldCentral" options will
495 be ignored.
496 This parameter defaults to 0.
498 "BlockSize100K => number"
500 Specify the number of 100K blocks bzip2 uses during compression.
501 Valid values are from 1 to 9, where 9 is best compression.
503 This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
505 ignored otherwise.
506 The default is 1.
508 "WorkFactor => number"
510 Specifies how much effort bzip2 should take before resorting to a
511 slower fallback compression algorithm.
512 Valid values range from 0 to 250, where 0 means use the default
514 value 30.
515 This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
517 ignored otherwise.
518 The default is 0.
520 -Level
522 Defines the compression level used by zlib. The value should
523 either be a number between 0 and 9 (0 means no compression and 9
524 is maximum compression), or one of the symbolic constants defined
525 below.
526 Z_NO_COMPRESSION
528 Z_BEST_SPEED
529 Z_BEST_COMPRESSION
530 Z_DEFAULT_COMPRESSION
531 The default is Z_DEFAULT_COMPRESSION.
533 Note, these constants are not imported by "IO::Compress::Zip" by
535 default.
536 use IO::Compress::Zip qw(:strategy);
538 use IO::Compress::Zip qw(:constants);
539 use IO::Compress::Zip qw(:all);
540 -Strategy
542 Defines the strategy used to tune the compression. Use one of the
543 symbolic constants defined below.
544 Z_FILTERED
546 Z_HUFFMAN_ONLY
547 Z_RLE
548 Z_FIXED
549 Z_DEFAULT_STRATEGY
550 The default is Z_DEFAULT_STRATEGY.
552 "Strict => 0|1"
554 This is a placeholder option.
555 Examples
557 TODO
558
560 print
561 Usage is
562 $z->print($data)
564 print $z $data
565 Compresses and outputs the contents of the $data parameter. This has
567 the same behaviour as the "print" built-in.
568 Returns true if successful.
570 printf
572 Usage is
573 $z->printf($format, $data)
575 printf $z $format, $data
576 Compresses and outputs the contents of the $data parameter.
578 Returns true if successful.
580 syswrite
582 Usage is
583 $z->syswrite $data
585 $z->syswrite $data, $length
586 $z->syswrite $data, $length, $offset
587 Compresses and outputs the contents of the $data parameter.
589 Returns the number of uncompressed bytes written, or "undef" if
591 unsuccessful.
592 write
594 Usage is
595 $z->write $data
597 $z->write $data, $length
598 $z->write $data, $length, $offset
599 Compresses and outputs the contents of the $data parameter.
601 Returns the number of uncompressed bytes written, or "undef" if
603 unsuccessful.
604 flush
606 Usage is
607 $z->flush;
609 $z->flush($flush_type);
610 Flushes any pending compressed data to the output file/buffer.
612 This method takes an optional parameter, $flush_type, that controls how
614 the flushing will be carried out. By default the $flush_type used is
615 "Z_FINISH". Other valid values for $flush_type are "Z_NO_FLUSH",
616 "Z_SYNC_FLUSH", "Z_FULL_FLUSH" and "Z_BLOCK". It is strongly
617 recommended that you only set the "flush_type" parameter if you fully
618 understand the implications of what it does - overuse of "flush" can
619 seriously degrade the level of compression achieved. See the "zlib"
620 documentation for details.
621 Returns true on success.
623 tell
625 Usage is
626 $z->tell()
628 tell $z
629 Returns the uncompressed file offset.
631 eof
633 Usage is
634 $z->eof();
636 eof($z);
637 Returns true if the "close" method has been called.
639 seek
641 $z->seek($position, $whence);
642 seek($z, $position, $whence);
643 Provides a sub-set of the "seek" functionality, with the restriction
645 that it is only legal to seek forward in the output file/buffer. It is
646 a fatal error to attempt to seek backward.
647 Empty parts of the file/buffer will have NULL (0x00) bytes written to
649 them.
650 The $whence parameter takes one the usual values, namely SEEK_SET,
652 SEEK_CUR or SEEK_END.
653 Returns 1 on success, 0 on failure.
655 binmode
657 Usage is
658 $z->binmode
660 binmode $z ;
661 This is a noop provided for completeness.
663 opened
665 $z->opened()
666 Returns true if the object currently refers to a opened file/buffer.
668 autoflush
670 my $prev = $z->autoflush()
671 my $prev = $z->autoflush(EXPR)
672 If the $z object is associated with a file or a filehandle, this method
674 returns the current autoflush setting for the underlying filehandle. If
675 "EXPR" is present, and is non-zero, it will enable flushing after every
676 write/print operation.
677 If $z is associated with a buffer, this method has no effect and always
679 returns "undef".
680 Note that the special variable $| cannot be used to set or retrieve the
682 autoflush setting.
683 input_line_number
685 $z->input_line_number()
686 $z->input_line_number(EXPR)
687 This method always returns "undef" when compressing.
689 fileno
691 $z->fileno()
692 fileno($z)
693 If the $z object is associated with a file or a filehandle, "fileno"
695 will return the underlying file descriptor. Once the "close" method is
696 called "fileno" will return "undef".
697 If the $z object is is associated with a buffer, this method will
699 return "undef".
700 close
702 $z->close() ;
703 close $z ;
704 Flushes any pending compressed data and then closes the output
706 file/buffer.
707 For most versions of Perl this method will be automatically invoked if
709 the IO::Compress::Zip object is destroyed (either explicitly or by the
710 variable with the reference to the object going out of scope). The
711 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
712 cases, the "close" method will be called automatically, but not until
713 global destruction of all live objects when the program is terminating.
714 Therefore, if you want your scripts to be able to run on all versions
716 of Perl, you should call "close" explicitly and not rely on automatic
717 closing.
718 Returns true on success, otherwise 0.
720 If the "AutoClose" option has been enabled when the IO::Compress::Zip
722 object was created, and the object is associated with a file, the
723 underlying file will also be closed.
724 newStream([OPTS])
726 Usage is
727 $z->newStream( [OPTS] )
729 Closes the current compressed data stream and starts a new one.
731 OPTS consists of any of the the options that are available when
733 creating the $z object.
734 See the "Constructor Options" section for more details.
736 deflateParams
738 Usage is
739 $z->deflateParams
741 TODO
743
745 A number of symbolic constants are required by some methods in
746 "IO::Compress::Zip". None are imported by default.
747 :all Imports "zip", $ZipError and all symbolic constants that can be
749 used by "IO::Compress::Zip". Same as doing this
750 use IO::Compress::Zip qw(zip $ZipError :constants) ;
752 :constants
754 Import all symbolic constants. Same as doing this
755 use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
757 :flush
759 These symbolic constants are used by the "flush" method.
760 Z_NO_FLUSH
762 Z_PARTIAL_FLUSH
763 Z_SYNC_FLUSH
764 Z_FULL_FLUSH
765 Z_FINISH
766 Z_BLOCK
767 :level
769 These symbolic constants are used by the "Level" option in the
770 constructor.
771 Z_NO_COMPRESSION
773 Z_BEST_SPEED
774 Z_BEST_COMPRESSION
775 Z_DEFAULT_COMPRESSION
776 :strategy
778 These symbolic constants are used by the "Strategy" option in the
779 constructor.
780 Z_FILTERED
782 Z_HUFFMAN_ONLY
783 Z_RLE
784 Z_FIXED
785 Z_DEFAULT_STRATEGY
786 :zip_method
788 These symbolic constants are used by the "Method" option in the
789 constructor.
790 ZIP_CM_STORE
792 ZIP_CM_DEFLATE
793 ZIP_CM_BZIP2
794
796 Apache::GZip Revisited
797 See IO::Compress::FAQ
798 Working with Net::FTP
800 See IO::Compress::FAQ
801
803 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
804 IO::Compress::Deflate, IO::Uncompress::Inflate,
805 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
806 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzop,
807 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
808 IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
809 Compress::Zlib::FAQ
811 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
813 For RFC 1950, 1951 and 1952 see http://www.faqs.org/rfcs/rfc1950.html,
815 http://www.faqs.org/rfcs/rfc1951.html and
816 http://www.faqs.org/rfcs/rfc1952.html
817 The zlib compression library was written by Jean-loup Gailly
819 gzip@prep.ai.mit.edu and Mark Adler madler@alumni.caltech.edu.
820 The primary site for the zlib compression library is
822 http://www.zlib.org.
823 The primary site for gzip is http://www.gzip.org.
825
827 This module was written by Paul Marquess, pmqs@cpan.org.
828
830 See the Changes file.
831
833 Copyright (c) 2005-2009 Paul Marquess. All rights reserved.
834 This program is free software; you can redistribute it and/or modify it
836 under the same terms as Perl itself.
837perl v5.10.1 2017-03-22 IO::Compress::Zip(3pm)