1IO::Compress::Zip(3) User Contributed Perl Documentation IO::Compress::Zip(3)
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 = IO::Compress::Zip->new( $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.
55 At present the following compression methods are supported by
57 IO::Compress::Zip
58 Store (0)
60 Deflate (8)
61 Bzip2 (12)
62 To write Bzip2 content, the module "IO::Uncompress::Bunzip2" must
63 be installed.
64 Lzma (14)
66 To write LZMA content, the module "IO::Uncompress::UnLzma" must be
67 installed.
68 Zstandard (93)
70 To write Zstandard content, the module "IO::Compress::Zstd" must
71 be installed.
72 Xz (95)
74 To write Xz content, the module "IO::Uncompress::UnXz" must be
75 installed.
76 For reading zip files/buffers, see the companion module
78 IO::Uncompress::Unzip.
79
81 A top-level function, "zip", is provided to carry out "one-shot"
82 compression between buffers and/or files. For finer control over the
83 compression process, see the "OO Interface" section.
84 use IO::Compress::Zip qw(zip $ZipError) ;
86 zip $input_filename_or_reference => $output_filename_or_reference [,OPTS]
88 or die "zip failed: $ZipError\n";
89 The functional interface needs Perl5.005 or better.
91 zip $input_filename_or_reference => $output_filename_or_reference [, OPTS]
93 "zip" expects at least two parameters, $input_filename_or_reference and
94 $output_filename_or_reference and zero or more optional parameters (see
95 "Optional Parameters")
96 The $input_filename_or_reference parameter
98 The parameter, $input_filename_or_reference, is used to define the
100 source of the uncompressed data.
101 It can take one of the following forms:
103 A filename
105 If the $input_filename_or_reference parameter is a simple scalar,
106 it is assumed to be a filename. This file will be opened for
107 reading and the input data will be read from it.
108 A filehandle
110 If the $input_filename_or_reference parameter is a filehandle, the
111 input data will be read from it. The string '-' can be used as an
112 alias for standard input.
113 A scalar reference
115 If $input_filename_or_reference is a scalar reference, the input
116 data will be read from $$input_filename_or_reference.
117 An array reference
119 If $input_filename_or_reference is an array reference, each
120 element in the array must be a filename.
121 The input data will be read from each file in turn.
123 The complete array will be walked to ensure that it only contains
125 valid filenames before any data is compressed.
126 An Input FileGlob string
128 If $input_filename_or_reference is a string that is delimited by
129 the characters "<" and ">" "zip" will assume that it is an input
130 fileglob string. The input is the list of files that match the
131 fileglob.
132 See File::GlobMapper for more details.
134 If the $input_filename_or_reference parameter is any other type,
136 "undef" will be returned.
137 In addition, if $input_filename_or_reference corresponds to a filename
139 from the filesystem, a number of zip file header fields will be
140 populated by default using the following attributes from the input file
141 • the full filename contained in $input_filename_or_reference
143 • the file protection attributes
145 • the UID/GID for the file
147 • the file timestamps
149 If you do not want to use these defaults they can be overridden by
151 explicitly setting one, or more, of the "Name", "Time", "TextFlag",
152 "ExtAttr", "exUnixN" and "exTime" options or by setting the "Minimal"
153 parameter.
154 The $output_filename_or_reference parameter
156 The parameter $output_filename_or_reference is used to control the
158 destination of the compressed data. This parameter can take one of
159 these forms.
160 A filename
162 If the $output_filename_or_reference parameter is a simple scalar,
163 it is assumed to be a filename. This file will be opened for
164 writing and the compressed data will be written to it.
165 A filehandle
167 If the $output_filename_or_reference parameter is a filehandle,
168 the compressed data will be written to it. The string '-' can be
169 used as an alias for standard output.
170 A scalar reference
172 If $output_filename_or_reference is a scalar reference, the
173 compressed data will be stored in $$output_filename_or_reference.
174 An Array Reference
176 If $output_filename_or_reference is an array reference, the
177 compressed data will be pushed onto the array.
178 An Output FileGlob
180 If $output_filename_or_reference is a string that is delimited by
181 the characters "<" and ">" "zip" will assume that it is an output
182 fileglob string. The output is the list of files that match the
183 fileglob.
184 When $output_filename_or_reference is an fileglob string,
186 $input_filename_or_reference must also be a fileglob string.
187 Anything else is an error.
188 See File::GlobMapper for more details.
190 If the $output_filename_or_reference parameter is any other type,
192 "undef" will be returned.
193 Notes
195 When $input_filename_or_reference maps to multiple files/buffers and
196 $output_filename_or_reference is a single file/buffer the input
197 files/buffers will each be stored in $output_filename_or_reference as a
198 distinct entry.
199 Optional Parameters
201 The optional parameters for the one-shot function "zip" are (for the
202 most part) identical to those used with the OO interface defined in the
203 "Constructor Options" section. The exceptions are listed below
204 "AutoClose => 0|1"
206 This option applies to any input or output data streams to "zip"
207 that are filehandles.
208 If "AutoClose" is specified, and the value is true, it will result
210 in all input and/or output filehandles being closed once "zip" has
211 completed.
212 This parameter defaults to 0.
214 "BinModeIn => 0|1"
216 This option is now a no-op. All files will be read in binmode.
217 "Append => 0|1"
219 The behaviour of this option is dependent on the type of output
220 data stream.
221 • A Buffer
223 If "Append" is enabled, all compressed data will be append to
225 the end of the output buffer. Otherwise the output buffer
226 will be cleared before any compressed data is written to it.
227 • A Filename
229 If "Append" is enabled, the file will be opened in append
231 mode. Otherwise the contents of the file, if any, will be
232 truncated before any compressed data is written to it.
233 • A Filehandle
235 If "Append" is enabled, the filehandle will be positioned to
237 the end of the file via a call to "seek" before any
238 compressed data is written to it. Otherwise the file pointer
239 will not be moved.
240 When "Append" is specified, and set to true, it will append all
242 compressed data to the output data stream.
243 So when the output is a filehandle it will carry out a seek to the
245 eof before writing any compressed data. If the output is a
246 filename, it will be opened for appending. If the output is a
247 buffer, all compressed data will be appended to the existing
248 buffer.
249 Conversely when "Append" is not specified, or it is present and is
251 set to false, it will operate as follows.
252 When the output is a filename, it will truncate the contents of
254 the file before writing any compressed data. If the output is a
255 filehandle its position will not be changed. If the output is a
256 buffer, it will be wiped before any compressed data is output.
257 Defaults to 0.
259 Oneshot Examples
261 Here are a few example that show the capabilities of the module.
262 Streaming
264 This very simple command line example demonstrates the streaming
266 capabilities of the module. The code reads data from STDIN, compresses
267 it, and writes the compressed data to STDOUT.
268 $ echo hello world | perl -MIO::Compress::Zip=zip -e 'zip \*STDIN => \*STDOUT' >output.zip
270 The special filename "-" can be used as a standin for both "\*STDIN"
272 and "\*STDOUT", so the above can be rewritten as
273 $ echo hello world | perl -MIO::Compress::Zip=zip -e 'zip "-" => "-"' >output.zip
275 One problem with creating a zip archive directly from STDIN can be
277 demonstrated by looking at the contents of the zip file, output.zip,
278 that we have just created.
279 $ unzip -l output.zip
281 Archive: output.zip
282 Length Date Time Name
283 --------- ---------- ----- ----
284 12 2019-08-16 22:21
285 --------- -------
286 12 1 file
287 The archive member (filename) used is the empty string.
289 If that doesn't suit your needs, you can explicitly set the filename
291 used in the zip archive by specifying the Name option, like so
292 echo hello world | perl -MIO::Compress::Zip=zip -e 'zip "-" => "-", Name => "hello.txt"' >output.zip
294 Now the contents of the zip file looks like this
296 $ unzip -l output.zip
298 Archive: output.zip
299 Length Date Time Name
300 --------- ---------- ----- ----
301 12 2019-08-16 22:22 hello.txt
302 --------- -------
303 12 1 file
304 Compressing a file from the filesystem
306 To read the contents of the file "file1.txt" and write the compressed
308 data to the file "file1.txt.zip".
309 use strict ;
311 use warnings ;
312 use IO::Compress::Zip qw(zip $ZipError) ;
313 my $input = "file1.txt";
315 zip $input => "$input.zip"
316 or die "zip failed: $ZipError\n";
317 Reading from a Filehandle and writing to an in-memory buffer
319 To read from an existing Perl filehandle, $input, and write the
321 compressed data to a buffer, $buffer.
322 use strict ;
324 use warnings ;
325 use IO::Compress::Zip qw(zip $ZipError) ;
326 use IO::File ;
327 my $input = IO::File->new( "<file1.txt" )
329 or die "Cannot open 'file1.txt': $!\n" ;
330 my $buffer ;
331 zip $input => \$buffer
332 or die "zip failed: $ZipError\n";
333 Compressing multiple files
335 To create a zip file, "output.zip", that contains the compressed
337 contents of the files "alpha.txt" and "beta.txt"
338 use strict ;
340 use warnings ;
341 use IO::Compress::Zip qw(zip $ZipError) ;
342 zip [ 'alpha.txt', 'beta.txt' ] => 'output.zip'
344 or die "zip failed: $ZipError\n";
345 Alternatively, rather than having to explicitly name each of the files
347 that you want to compress, you could use a fileglob to select all the
348 "txt" files in the current directory, as follows
349 use strict ;
351 use warnings ;
352 use IO::Compress::Zip qw(zip $ZipError) ;
353 my @files = <*.txt>;
355 zip \@files => 'output.zip'
356 or die "zip failed: $ZipError\n";
357 or more succinctly
359 zip [ <*.txt> ] => 'output.zip'
361 or die "zip failed: $ZipError\n";
362
364 Constructor
365 The format of the constructor for "IO::Compress::Zip" is shown below
366 my $z = IO::Compress::Zip->new( $output [,OPTS] )
368 or die "IO::Compress::Zip failed: $ZipError\n";
369 The constructor takes one mandatory parameter, $output, defined below
371 and zero or more "OPTS", defined in "Constructor Options".
372 It returns an "IO::Compress::Zip" object on success and "undef" on
374 failure. The variable $ZipError will contain an error message on
375 failure.
376 If you are running Perl 5.005 or better the object, $z, returned from
378 IO::Compress::Zip can be used exactly like an IO::File filehandle.
379 This means that all normal output file operations can be carried out
380 with $z. For example, to write to a compressed file/buffer you can use
381 either of these forms
382 $z->print("hello world\n");
384 print $z "hello world\n";
385 Below is a simple exaple of using the OO interface to create an output
387 file "myfile.zip" and write some data to it.
388 my $filename = "myfile.zip";
390 my $z = IO::Compress::Zip->new($filename)
391 or die "IO::Compress::Zip failed: $ZipError\n";
392 $z->print("abcde");
394 $z->close();
395 See the "Examples" for more.
397 The mandatory parameter $output is used to control the destination of
399 the compressed data. This parameter can take one of these forms.
400 A filename
402 If the $output parameter is a simple scalar, it is assumed to be a
403 filename. This file will be opened for writing and the compressed
404 data will be written to it.
405 A filehandle
407 If the $output parameter is a filehandle, the compressed data will
408 be written to it. The string '-' can be used as an alias for
409 standard output.
410 A scalar reference
412 If $output is a scalar reference, the compressed data will be
413 stored in $$output.
414 If the $output parameter is any other type, "IO::Compress::Zip"::new
416 will return undef.
417 Constructor Options
419 "OPTS" is any combination of zero or more the following options:
420 "AutoClose => 0|1"
422 This option is only valid when the $output parameter is a
423 filehandle. If specified, and the value is true, it will result in
424 the $output being closed once either the "close" method is called
425 or the "IO::Compress::Zip" object is destroyed.
426 This parameter defaults to 0.
428 "Append => 0|1"
430 Opens $output in append mode.
431 The behaviour of this option is dependent on the type of $output.
433 • A Buffer
435 If $output is a buffer and "Append" is enabled, all
437 compressed data will be append to the end of $output.
438 Otherwise $output will be cleared before any data is written
439 to it.
440 • A Filename
442 If $output is a filename and "Append" is enabled, the file
444 will be opened in append mode. Otherwise the contents of the
445 file, if any, will be truncated before any compressed data is
446 written to it.
447 • A Filehandle
449 If $output is a filehandle, the file pointer will be
451 positioned to the end of the file via a call to "seek" before
452 any compressed data is written to it. Otherwise the file
453 pointer will not be moved.
454 This parameter defaults to 0.
456 File Naming Options
458 A quick bit of zip file terminology -- A zip archive consists of one or
460 more archive members, where each member has an associated filename,
461 known as the archive member name.
462 The options listed in this section control how the archive member name
464 (or filename) is stored the zip archive.
465 "Name => $string"
467 This option is used to explicitly set the archive member name in
468 the zip archive to $string. Most of the time you don't need to
469 make use of this option. By default when adding a filename to the
470 zip archive, the archive member name will match the filename.
471 You should only need to use this option if you want the archive
473 member name to be different from the uncompressed filename or when
474 the input is a filehandle or a buffer.
475 The default behaviour for what archive member name is used when
477 the "Name" option is not specified depends on the form of the
478 $input parameter:
479 • If the $input parameter is a filename, the value of $input
481 will be used for the archive member name .
482 • If the $input parameter is not a filename, the archive member
484 name will be an empty string.
485 Note that both the "CanonicalName" and "FilterName" options can
487 modify the value used for the archive member name.
488 Also note that you should set the "Efs" option to true if you are
490 working with UTF8 filenames.
491 "CanonicalName => 0|1"
493 This option controls whether the archive member name is normalized
494 into Unix format before being written to the zip file.
495 It is recommended that you enable this option unless you really
497 need to create a non-standard Zip file.
498 This is what APPNOTE.TXT has to say on what should be stored in
500 the zip filename header field.
501 The name of the file, with optional relative path.
503 The path stored should not contain a drive or
504 device letter, or a leading slash. All slashes
505 should be forward slashes '/' as opposed to
506 backwards slashes '\' for compatibility with Amiga
507 and UNIX file systems etc.
508 This option defaults to false.
510 "FilterName => sub { ... }"
512 This option allow the archive member name to be modified before it
513 is written to the zip file.
514 This option takes a parameter that must be a reference to a sub.
516 On entry to the sub the $_ variable will contain the name to be
517 filtered. If no filename is available $_ will contain an empty
518 string.
519 The value of $_ when the sub returns will be used as the archive
521 member name.
522 Note that if "CanonicalName" is enabled, a normalized filename
524 will be passed to the sub.
525 If you use "FilterName" to modify the filename, it is your
527 responsibility to keep the filename in Unix format.
528 Although this option can be used with the OO interface, it is of
530 most use with the one-shot interface. For example, the code below
531 shows how "FilterName" can be used to remove the path component
532 from a series of filenames before they are stored in $zipfile.
533 sub compressTxtFiles
535 {
536 my $zipfile = shift ;
537 my $dir = shift ;
538 zip [ <$dir/*.txt> ] => $zipfile,
540 FilterName => sub { s[^$dir/][] } ;
541 }
542 "Efs => 0|1"
544 This option controls setting of the "Language Encoding Flag" (EFS)
545 in the zip archive. When set, the filename and comment fields for
546 the zip archive MUST be valid UTF-8.
547 If the string used for the filename and/or comment is not valid
549 UTF-8 when this option is true, the script will die with a "wide
550 character" error.
551 Note that this option only works with Perl 5.8.4 or better.
553 This option defaults to false.
555 Overall Zip Archive Structure
557 "Minimal => 1|0"
559 If specified, this option will disable the creation of all extra
560 fields in the zip local and central headers. So the "exTime",
561 "exUnix2", "exUnixN", "ExtraFieldLocal" and "ExtraFieldCentral"
562 options will be ignored.
563 This parameter defaults to 0.
565 "Stream => 0|1"
567 This option controls whether the zip file/buffer output is created
568 in streaming mode.
569 Note that when outputting to a file with streaming mode disabled
571 ("Stream" is 0), the output file must be seekable.
572 The default is 1.
574 "Zip64 => 0|1"
576 Create a Zip64 zip file/buffer. This option is used if you want to
577 store files larger than 4 Gig or store more than 64K files in a
578 single zip archive.
579 "Zip64" will be automatically set, as needed, if working with the
581 one-shot interface when the input is either a filename or a scalar
582 reference.
583 If you intend to manipulate the Zip64 zip files created with this
585 module using an external zip/unzip, make sure that it supports
586 Zip64.
587 In particular, if you are using Info-Zip you need to have zip
589 version 3.x or better to update a Zip64 archive and unzip version
590 6.x to read a zip64 archive.
591 The default is 0.
593 Deflate Compression Options
595 -Level
597 Defines the compression level used by zlib. The value should
598 either be a number between 0 and 9 (0 means no compression and 9
599 is maximum compression), or one of the symbolic constants defined
600 below.
601 Z_NO_COMPRESSION
603 Z_BEST_SPEED
604 Z_BEST_COMPRESSION
605 Z_DEFAULT_COMPRESSION
606 The default is Z_DEFAULT_COMPRESSION.
608 Note, these constants are not imported by "IO::Compress::Zip" by
610 default.
611 use IO::Compress::Zip qw(:strategy);
613 use IO::Compress::Zip qw(:constants);
614 use IO::Compress::Zip qw(:all);
615 -Strategy
617 Defines the strategy used to tune the compression. Use one of the
618 symbolic constants defined below.
619 Z_FILTERED
621 Z_HUFFMAN_ONLY
622 Z_RLE
623 Z_FIXED
624 Z_DEFAULT_STRATEGY
625 The default is Z_DEFAULT_STRATEGY.
627 Bzip2 Compression Options
629 "BlockSize100K => number"
631 Specify the number of 100K blocks bzip2 uses during compression.
632 Valid values are from 1 to 9, where 9 is best compression.
634 This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
636 ignored otherwise.
637 The default is 1.
639 "WorkFactor => number"
641 Specifies how much effort bzip2 should take before resorting to a
642 slower fallback compression algorithm.
643 Valid values range from 0 to 250, where 0 means use the default
645 value 30.
646 This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
648 ignored otherwise.
649 The default is 0.
651 Lzma and Xz Compression Options
653 "Preset => number"
655 Used to choose the LZMA compression preset.
656 Valid values are 0-9 and "LZMA_PRESET_DEFAULT".
658 0 is the fastest compression with the lowest memory usage and the
660 lowest compression.
661 9 is the slowest compression with the highest memory usage but
663 with the best compression.
664 This option is only valid if the "Method" is ZIP_CM_LZMA. It is
666 ignored otherwise.
667 Defaults to "LZMA_PRESET_DEFAULT" (6).
669 "Extreme => 0|1"
671 Makes LZMA compression a lot slower, but a small compression gain.
672 This option is only valid if the "Method" is ZIP_CM_LZMA. It is
674 ignored otherwise.
675 Defaults to 0.
677 Other Options
679 "Time => $number"
681 Sets the last modified time field in the zip header to $number.
682 This field defaults to the time the "IO::Compress::Zip" object was
684 created if this option is not specified and the $input parameter
685 is not a filename.
686 "ExtAttr => $attr"
688 This option controls the "external file attributes" field in the
689 central header of the zip file. This is a 4 byte field.
690 If you are running a Unix derivative this value defaults to
692 0100644 << 16
694 This should allow read/write access to any files that are
696 extracted from the zip file/buffer`.
697 For all other systems it defaults to 0.
699 "exTime => [$atime, $mtime, $ctime]"
701 This option expects an array reference with exactly three
702 elements: $atime, "mtime" and $ctime. These correspond to the last
703 access time, last modification time and creation time
704 respectively.
705 It uses these values to set the extended timestamp field (ID is
707 "UT") in the local zip header using the three values, $atime,
708 $mtime, $ctime. In addition it sets the extended timestamp field
709 in the central zip header using $mtime.
710 If any of the three values is "undef" that time value will not be
712 used. So, for example, to set only the $mtime you would use this
713 exTime => [undef, $mtime, undef]
715 If the "Minimal" option is set to true, this option will be
717 ignored.
718 By default no extended time field is created.
720 "exUnix2 => [$uid, $gid]"
722 This option expects an array reference with exactly two elements:
723 $uid and $gid. These values correspond to the numeric User ID
724 (UID) and Group ID (GID) of the owner of the files respectively.
725 When the "exUnix2" option is present it will trigger the creation
727 of a Unix2 extra field (ID is "Ux") in the local zip header. This
728 will be populated with $uid and $gid. An empty Unix2 extra field
729 will also be created in the central zip header.
730 Note - The UID & GID are stored as 16-bit integers in the "Ux"
732 field. Use "exUnixN" if your UID or GID are 32-bit.
733 If the "Minimal" option is set to true, this option will be
735 ignored.
736 By default no Unix2 extra field is created.
738 "exUnixN => [$uid, $gid]"
740 This option expects an array reference with exactly two elements:
741 $uid and $gid. These values correspond to the numeric User ID
742 (UID) and Group ID (GID) of the owner of the files respectively.
743 When the "exUnixN" option is present it will trigger the creation
745 of a UnixN extra field (ID is "ux") in both the local and central
746 zip headers. This will be populated with $uid and $gid. The UID
747 & GID are stored as 32-bit integers.
748 If the "Minimal" option is set to true, this option will be
750 ignored.
751 By default no UnixN extra field is created.
753 "Comment => $comment"
755 Stores the contents of $comment in the Central File Header of the
756 zip file.
757 Set the "Efs" option to true if you want to store a UTF8 comment.
759 By default, no comment field is written to the zip file.
761 "ZipComment => $comment"
763 Stores the contents of $comment in the End of Central Directory
764 record of the zip file.
765 By default, no comment field is written to the zip file.
767 "Method => $method"
769 Controls which compression method is used. At present the
770 compression methods supported are: Store (no compression at all),
771 Deflate, Bzip2, Zstd, Xz and Lzma.
772 The symbols ZIP_CM_STORE, ZIP_CM_DEFLATE, ZIP_CM_BZIP2,
774 ZIP_CM_ZSTD, ZIP_CM_XZ and ZIP_CM_LZMA are used to select the
775 compression method.
776 These constants are not imported by "IO::Compress::Zip" by
778 default.
779 use IO::Compress::Zip qw(:zip_method);
781 use IO::Compress::Zip qw(:constants);
782 use IO::Compress::Zip qw(:all);
783 Note that to create Bzip2 content, the module
785 "IO::Compress::Bzip2" must be installed. A fatal error will be
786 thrown if you attempt to create Bzip2 content when
787 "IO::Compress::Bzip2" is not available.
788 Note that to create Lzma content, the module "IO::Compress::Lzma"
790 must be installed. A fatal error will be thrown if you attempt to
791 create Lzma content when "IO::Compress::Lzma" is not available.
792 Note that to create Xz content, the module "IO::Compress::Xz" must
794 be installed. A fatal error will be thrown if you attempt to
795 create Xz content when "IO::Compress::Xz" is not available.
796 Note that to create Zstd content, the module "IO::Compress::Zstd"
798 must be installed. A fatal error will be thrown if you attempt to
799 create Zstd content when "IO::Compress::Zstd" is not available.
800 The default method is ZIP_CM_DEFLATE.
802 "TextFlag => 0|1"
804 This parameter controls the setting of a bit in the zip central
805 header. It is used to signal that the data stored in the zip
806 file/buffer is probably text.
807 In one-shot mode this flag will be set to true if the Perl "-T"
809 operator thinks the file contains text.
810 The default is 0.
812 "ExtraFieldLocal => $data"
814 "ExtraFieldCentral => $data"
815 The "ExtraFieldLocal" option is used to store additional metadata
816 in the local header for the zip file/buffer. The
817 "ExtraFieldCentral" does the same for the matching central header.
818 An extra field consists of zero or more subfields. Each subfield
820 consists of a two byte header followed by the subfield data.
821 The list of subfields can be supplied in any of the following
823 formats
824 ExtraFieldLocal => [$id1, $data1,
826 $id2, $data2,
827 ...
828 ]
829 ExtraFieldLocal => [ [$id1 => $data1],
831 [$id2 => $data2],
832 ...
833 ]
834 ExtraFieldLocal => { $id1 => $data1,
836 $id2 => $data2,
837 ...
838 }
839 Where $id1, $id2 are two byte subfield ID's.
841 If you use the hash syntax, you have no control over the order in
843 which the ExtraSubFields are stored, plus you cannot have
844 SubFields with duplicate ID.
845 Alternatively the list of subfields can by supplied as a scalar,
847 thus
848 ExtraField => $rawdata
850 In this case "IO::Compress::Zip" will check that $rawdata consists
852 of zero or more conformant sub-fields.
853 The Extended Time field (ID "UT"), set using the "exTime" option,
855 and the Unix2 extra field (ID "Ux), set using the "exUnix2"
856 option, are examples of extra fields.
857 If the "Minimal" option is set to true, this option will be
859 ignored.
860 The maximum size of an extra field 65535 bytes.
862 "Strict => 0|1"
864 This is a placeholder option.
865 Examples
867 Streaming
868 This very simple command line example demonstrates the streaming
870 capabilities of the module. The code reads data from STDIN or all the
871 files given on the commandline, compresses it, and writes the
872 compressed data to STDOUT.
873 use strict ;
875 use warnings ;
876 use IO::Compress::Zip qw(zip $ZipError) ;
877 my $z = IO::Compress::Zip->new("-", Stream => 1)
879 or die "IO::Compress::Zip failed: $ZipError\n";
880 while (<>) {
882 $z->print("abcde");
883 }
884 $z->close();
885 Note the use of "-" to means "STDOUT". Alternatively you can use
887 "\*STDOUT".
888 One problem with creating a zip archive directly from STDIN can be
890 demonstrated by looking at the contents of the zip file, output.zip,
891 that we have just created (assumg you have redirected it to a file
892 called "output.zip").
893 $ unzip -l output.zip
895 Archive: output.zip
896 Length Date Time Name
897 --------- ---------- ----- ----
898 12 2019-08-16 22:21
899 --------- -------
900 12 1 file
901 The archive member (filename) used is the empty string.
903 If that doesn't suit your needs, you can explicitly set the filename
905 used in the zip archive by specifying the Name option, like so
906 my $z = IO::Compress::Zip->new("-", Name => "hello.txt", Stream => 1)
908 Now the contents of the zip file looks like this
910 $ unzip -l output.zip
912 Archive: output.zip
913 Length Date Time Name
914 --------- ---------- ----- ----
915 12 2019-08-16 22:22 hello.txt
916 --------- -------
917 12 1 file
918 Compressing a file from the filesystem
920 To read the contents of the file "file1.txt" and write the compressed
922 data to the file "file1.txt.zip" there are a few options
923 Start by creating the compression object and opening the input file
925 use strict ;
927 use warnings ;
928 use IO::Compress::Zip qw(zip $ZipError) ;
929 my $input = "file1.txt";
931 my $z = IO::Compress::Zip->new("file1.txt.zip")
932 or die "IO::Compress::Zip failed: $ZipError\n";
933 # open the input file
935 open my $fh, "<", "file1.txt"
936 or die "Cannot open file1.txt: $!\n";
937 # loop through the input file & write to the compressed file
939 while (<$fh>) {
940 $z->print($_);
941 }
942 # not forgetting to close the compressed file
944 $z->close();
945 Compressing multiple files
947 To create a zip file, "output.zip", that contains the compressed
949 contents of the files "alpha.txt" and "beta.txt"
950 use strict ;
952 use warnings ;
953 use IO::Compress::Zip qw(zip $ZipError) ;
954 my $z = IO::Compress::Zip->new("output.zip", Name => "alpha.txt")
956 or die "IO::Compress::Zip failed: $ZipError\n";
957 # open the input file
959 open my $fh, "<", "file1.txt"
960 or die "Cannot open file1.txt: $!\n";
961 # loop through the input file & write to the compressed file
963 while (<$fh>) {
964 $z->print($_);
965 }
966 # move to next file
968 $z->newStream(Name => "beta.txt")
969 while (<$fh>) {
971 $z->print($_);
972 }
973 $z->close();
975
977 print
978 Usage is
979 $z->print($data)
981 print $z $data
982 Compresses and outputs the contents of the $data parameter. This has
984 the same behaviour as the "print" built-in.
985 Returns true if successful.
987 printf
989 Usage is
990 $z->printf($format, $data)
992 printf $z $format, $data
993 Compresses and outputs the contents of the $data parameter.
995 Returns true if successful.
997 syswrite
999 Usage is
1000 $z->syswrite $data
1002 $z->syswrite $data, $length
1003 $z->syswrite $data, $length, $offset
1004 Compresses and outputs the contents of the $data parameter.
1006 Returns the number of uncompressed bytes written, or "undef" if
1008 unsuccessful.
1009 write
1011 Usage is
1012 $z->write $data
1014 $z->write $data, $length
1015 $z->write $data, $length, $offset
1016 Compresses and outputs the contents of the $data parameter.
1018 Returns the number of uncompressed bytes written, or "undef" if
1020 unsuccessful.
1021 flush
1023 Usage is
1024 $z->flush;
1026 $z->flush($flush_type);
1027 Flushes any pending compressed data to the output file/buffer.
1029 This method takes an optional parameter, $flush_type, that controls how
1031 the flushing will be carried out. By default the $flush_type used is
1032 "Z_FINISH". Other valid values for $flush_type are "Z_NO_FLUSH",
1033 "Z_SYNC_FLUSH", "Z_FULL_FLUSH" and "Z_BLOCK". It is strongly
1034 recommended that you only set the "flush_type" parameter if you fully
1035 understand the implications of what it does - overuse of "flush" can
1036 seriously degrade the level of compression achieved. See the "zlib"
1037 documentation for details.
1038 Returns true on success.
1040 tell
1042 Usage is
1043 $z->tell()
1045 tell $z
1046 Returns the uncompressed file offset.
1048 eof
1050 Usage is
1051 $z->eof();
1053 eof($z);
1054 Returns true if the "close" method has been called.
1056 seek
1058 $z->seek($position, $whence);
1059 seek($z, $position, $whence);
1060 Provides a sub-set of the "seek" functionality, with the restriction
1062 that it is only legal to seek forward in the output file/buffer. It is
1063 a fatal error to attempt to seek backward.
1064 Empty parts of the file/buffer will have NULL (0x00) bytes written to
1066 them.
1067 The $whence parameter takes one the usual values, namely SEEK_SET,
1069 SEEK_CUR or SEEK_END.
1070 Returns 1 on success, 0 on failure.
1072 binmode
1074 Usage is
1075 $z->binmode
1077 binmode $z ;
1078 This is a noop provided for completeness.
1080 opened
1082 $z->opened()
1083 Returns true if the object currently refers to a opened file/buffer.
1085 autoflush
1087 my $prev = $z->autoflush()
1088 my $prev = $z->autoflush(EXPR)
1089 If the $z object is associated with a file or a filehandle, this method
1091 returns the current autoflush setting for the underlying filehandle. If
1092 "EXPR" is present, and is non-zero, it will enable flushing after every
1093 write/print operation.
1094 If $z is associated with a buffer, this method has no effect and always
1096 returns "undef".
1097 Note that the special variable $| cannot be used to set or retrieve the
1099 autoflush setting.
1100 input_line_number
1102 $z->input_line_number()
1103 $z->input_line_number(EXPR)
1104 This method always returns "undef" when compressing.
1106 fileno
1108 $z->fileno()
1109 fileno($z)
1110 If the $z object is associated with a file or a filehandle, "fileno"
1112 will return the underlying file descriptor. Once the "close" method is
1113 called "fileno" will return "undef".
1114 If the $z object is associated with a buffer, this method will return
1116 "undef".
1117 close
1119 $z->close() ;
1120 close $z ;
1121 Flushes any pending compressed data and then closes the output
1123 file/buffer.
1124 For most versions of Perl this method will be automatically invoked if
1126 the IO::Compress::Zip object is destroyed (either explicitly or by the
1127 variable with the reference to the object going out of scope). The
1128 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
1129 cases, the "close" method will be called automatically, but not until
1130 global destruction of all live objects when the program is terminating.
1131 Therefore, if you want your scripts to be able to run on all versions
1133 of Perl, you should call "close" explicitly and not rely on automatic
1134 closing.
1135 Returns true on success, otherwise 0.
1137 If the "AutoClose" option has been enabled when the IO::Compress::Zip
1139 object was created, and the object is associated with a file, the
1140 underlying file will also be closed.
1141 newStream([OPTS])
1143 Usage is
1144 $z->newStream( [OPTS] )
1146 Closes the current compressed data stream and starts a new one.
1148 OPTS consists of any of the options that are available when creating
1150 the $z object.
1151 See the "Constructor Options" section for more details.
1153 deflateParams
1155 Usage is
1156 $z->deflateParams
1158 TODO
1160
1162 A number of symbolic constants are required by some methods in
1163 "IO::Compress::Zip". None are imported by default.
1164 :all Imports "zip", $ZipError and all symbolic constants that can be
1166 used by "IO::Compress::Zip". Same as doing this
1167 use IO::Compress::Zip qw(zip $ZipError :constants) ;
1169 :constants
1171 Import all symbolic constants. Same as doing this
1172 use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
1174 :flush
1176 These symbolic constants are used by the "flush" method.
1177 Z_NO_FLUSH
1179 Z_PARTIAL_FLUSH
1180 Z_SYNC_FLUSH
1181 Z_FULL_FLUSH
1182 Z_FINISH
1183 Z_BLOCK
1184 :level
1186 These symbolic constants are used by the "Level" option in the
1187 constructor.
1188 Z_NO_COMPRESSION
1190 Z_BEST_SPEED
1191 Z_BEST_COMPRESSION
1192 Z_DEFAULT_COMPRESSION
1193 :strategy
1195 These symbolic constants are used by the "Strategy" option in the
1196 constructor.
1197 Z_FILTERED
1199 Z_HUFFMAN_ONLY
1200 Z_RLE
1201 Z_FIXED
1202 Z_DEFAULT_STRATEGY
1203 :zip_method
1205 These symbolic constants are used by the "Method" option in the
1206 constructor.
1207 ZIP_CM_STORE
1209 ZIP_CM_DEFLATE
1210 ZIP_CM_BZIP2
1211
1213 Apache::GZip Revisited
1214 See IO::Compress::FAQ
1215 Working with Net::FTP
1217 See IO::Compress::FAQ
1218
1220 General feedback/questions/bug reports should be sent to
1221 <https://github.com/pmqs/IO-Compress/issues> (preferred) or
1222 <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
1223
1225 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
1226 IO::Compress::Deflate, IO::Uncompress::Inflate,
1227 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
1228 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma,
1229 IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz,
1230 IO::Compress::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop,
1231 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
1232 IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate,
1233 IO::Uncompress::AnyUncompress
1234 IO::Compress::FAQ
1236 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
1238 For RFC 1950, 1951 and 1952 see
1240 <https://datatracker.ietf.org/doc/html/rfc1950>,
1241 <https://datatracker.ietf.org/doc/html/rfc1951> and
1242 <https://datatracker.ietf.org/doc/html/rfc1952>
1243 The zlib compression library was written by Jean-loup Gailly
1245 "gzip@prep.ai.mit.edu" and Mark Adler "madler@alumni.caltech.edu".
1246 The primary site for the zlib compression library is
1248 <http://www.zlib.org>.
1249 The primary site for the zlib-ng compression library is
1251 <https://github.com/zlib-ng/zlib-ng>.
1252 The primary site for gzip is <http://www.gzip.org>.
1254
1256 This module was written by Paul Marquess, "pmqs@cpan.org".
1257
1259 See the Changes file.
1260
1262 Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
1263 This program is free software; you can redistribute it and/or modify it
1265 under the same terms as Perl itself.
1266perl v5.38.0 2023-07-26 IO::Compress::Zip(3)