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 is a simple filename, the
139 default values for the "Name", "Time", "TextFlag", "ExtAttr", "exUnixN"
140 and "exTime" options will be sourced from that file.
141 If you do not want to use these defaults they can be overridden by
143 explicitly setting the "Name", "Time", "TextFlag", "ExtAttr", "exUnixN"
144 and "exTime" options or by setting the "Minimal" parameter.
145 The $output_filename_or_reference parameter
147 The parameter $output_filename_or_reference is used to control the
149 destination of the compressed data. This parameter can take one of
150 these forms.
151 A filename
153 If the $output_filename_or_reference parameter is a simple scalar,
154 it is assumed to be a filename. This file will be opened for
155 writing and the compressed data will be written to it.
156 A filehandle
158 If the $output_filename_or_reference parameter is a filehandle,
159 the compressed data will be written to it. The string '-' can be
160 used as an alias for standard output.
161 A scalar reference
163 If $output_filename_or_reference is a scalar reference, the
164 compressed data will be stored in $$output_filename_or_reference.
165 An Array Reference
167 If $output_filename_or_reference is an array reference, the
168 compressed data will be pushed onto the array.
169 An Output FileGlob
171 If $output_filename_or_reference is a string that is delimited by
172 the characters "<" and ">" "zip" will assume that it is an output
173 fileglob string. The output is the list of files that match the
174 fileglob.
175 When $output_filename_or_reference is an fileglob string,
177 $input_filename_or_reference must also be a fileglob string.
178 Anything else is an error.
179 See File::GlobMapper for more details.
181 If the $output_filename_or_reference parameter is any other type,
183 "undef" will be returned.
184 Notes
186 When $input_filename_or_reference maps to multiple files/buffers and
187 $output_filename_or_reference is a single file/buffer the input
188 files/buffers will each be stored in $output_filename_or_reference as a
189 distinct entry.
190 Optional Parameters
192 The optional parameters for the one-shot function "zip" are (for the
193 most part) identical to those used with the OO interface defined in the
194 "Constructor Options" section. The exceptions are listed below
195 "AutoClose => 0|1"
197 This option applies to any input or output data streams to "zip"
198 that are filehandles.
199 If "AutoClose" is specified, and the value is true, it will result
201 in all input and/or output filehandles being closed once "zip" has
202 completed.
203 This parameter defaults to 0.
205 "BinModeIn => 0|1"
207 This option is now a no-op. All files will be read in binmode.
208 "Append => 0|1"
210 The behaviour of this option is dependent on the type of output
211 data stream.
212 • A Buffer
214 If "Append" is enabled, all compressed data will be append to
216 the end of the output buffer. Otherwise the output buffer
217 will be cleared before any compressed data is written to it.
218 • A Filename
220 If "Append" is enabled, the file will be opened in append
222 mode. Otherwise the contents of the file, if any, will be
223 truncated before any compressed data is written to it.
224 • A Filehandle
226 If "Append" is enabled, the filehandle will be positioned to
228 the end of the file via a call to "seek" before any
229 compressed data is written to it. Otherwise the file pointer
230 will not be moved.
231 When "Append" is specified, and set to true, it will append all
233 compressed data to the output data stream.
234 So when the output is a filehandle it will carry out a seek to the
236 eof before writing any compressed data. If the output is a
237 filename, it will be opened for appending. If the output is a
238 buffer, all compressed data will be appended to the existing
239 buffer.
240 Conversely when "Append" is not specified, or it is present and is
242 set to false, it will operate as follows.
243 When the output is a filename, it will truncate the contents of
245 the file before writing any compressed data. If the output is a
246 filehandle its position will not be changed. If the output is a
247 buffer, it will be wiped before any compressed data is output.
248 Defaults to 0.
250 Examples
252 Here are a few example that show the capabilities of the module.
253 Streaming
255 This very simple command line example demonstrates the streaming
257 capabilities of the module. The code reads data from STDIN, compresses
258 it, and writes the compressed data to STDOUT.
259 $ echo hello world | perl -MIO::Compress::Zip=zip -e 'zip \*STDIN => \*STDOUT' >output.zip
261 The special filename "-" can be used as a standin for both "\*STDIN"
263 and "\*STDOUT", so the above can be rewritten as
264 $ echo hello world | perl -MIO::Compress::Zip=zip -e 'zip "-" => "-"' >output.zip
266 One problem with creating a zip archive directly from STDIN can be
268 demonstrated by looking at the contents of the zip file, output.zip,
269 that we have just created.
270 $ unzip -l output.zip
272 Archive: output.zip
273 Length Date Time Name
274 --------- ---------- ----- ----
275 12 2019-08-16 22:21
276 --------- -------
277 12 1 file
278 The archive member (filename) used is the empty string.
280 If that doesn't suit your needs, you can explicitly set the filename
282 used in the zip archive by specifying the Name option, like so
283 echo hello world | perl -MIO::Compress::Zip=zip -e 'zip "-" => "-", Name => "hello.txt"' >output.zip
285 Now the contents of the zip file looks like this
287 $ unzip -l output.zip
289 Archive: output.zip
290 Length Date Time Name
291 --------- ---------- ----- ----
292 12 2019-08-16 22:22 hello.txt
293 --------- -------
294 12 1 file
295 Compressing a file from the filesystem
297 To read the contents of the file "file1.txt" and write the compressed
299 data to the file "file1.txt.zip".
300 use strict ;
302 use warnings ;
303 use IO::Compress::Zip qw(zip $ZipError) ;
304 my $input = "file1.txt";
306 zip $input => "$input.zip"
307 or die "zip failed: $ZipError\n";
308 Reading from a Filehandle and writing to an in-memory buffer
310 To read from an existing Perl filehandle, $input, and write the
312 compressed data to a buffer, $buffer.
313 use strict ;
315 use warnings ;
316 use IO::Compress::Zip qw(zip $ZipError) ;
317 use IO::File ;
318 my $input = IO::File->new( "<file1.txt" )
320 or die "Cannot open 'file1.txt': $!\n" ;
321 my $buffer ;
322 zip $input => \$buffer
323 or die "zip failed: $ZipError\n";
324 Compressing multiple files
326 To create a zip file, "output.zip", that contains the compressed
328 contents of the files "alpha.txt" and "beta.txt"
329 use strict ;
331 use warnings ;
332 use IO::Compress::Zip qw(zip $ZipError) ;
333 zip [ 'alpha.txt', 'beta.txt' ] => 'output.zip'
335 or die "zip failed: $ZipError\n";
336 Alternatively, rather than having to explicitly name each of the files
338 that you want to compress, you could use a fileglob to select all the
339 "txt" files in the current directory, as follows
340 use strict ;
342 use warnings ;
343 use IO::Compress::Zip qw(zip $ZipError) ;
344 my @files = <*.txt>;
346 zip \@files => 'output.zip'
347 or die "zip failed: $ZipError\n";
348 or more succinctly
350 zip [ <*.txt> ] => 'output.zip'
352 or die "zip failed: $ZipError\n";
353
355 Constructor
356 The format of the constructor for "IO::Compress::Zip" is shown below
357 my $z = IO::Compress::Zip->new( $output [,OPTS] )
359 or die "IO::Compress::Zip failed: $ZipError\n";
360 It returns an "IO::Compress::Zip" object on success and undef on
362 failure. The variable $ZipError will contain an error message on
363 failure.
364 If you are running Perl 5.005 or better the object, $z, returned from
366 IO::Compress::Zip can be used exactly like an IO::File filehandle.
367 This means that all normal output file operations can be carried out
368 with $z. For example, to write to a compressed file/buffer you can use
369 either of these forms
370 $z->print("hello world\n");
372 print $z "hello world\n";
373 The mandatory parameter $output is used to control the destination of
375 the compressed data. This parameter can take one of these forms.
376 A filename
378 If the $output parameter is a simple scalar, it is assumed to be a
379 filename. This file will be opened for writing and the compressed
380 data will be written to it.
381 A filehandle
383 If the $output parameter is a filehandle, the compressed data will
384 be written to it. The string '-' can be used as an alias for
385 standard output.
386 A scalar reference
388 If $output is a scalar reference, the compressed data will be
389 stored in $$output.
390 If the $output parameter is any other type, "IO::Compress::Zip"::new
392 will return undef.
393 Constructor Options
395 "OPTS" is any combination of zero or more the following options:
396 "AutoClose => 0|1"
398 This option is only valid when the $output parameter is a
399 filehandle. If specified, and the value is true, it will result in
400 the $output being closed once either the "close" method is called
401 or the "IO::Compress::Zip" object is destroyed.
402 This parameter defaults to 0.
404 "Append => 0|1"
406 Opens $output in append mode.
407 The behaviour of this option is dependent on the type of $output.
409 • A Buffer
411 If $output is a buffer and "Append" is enabled, all
413 compressed data will be append to the end of $output.
414 Otherwise $output will be cleared before any data is written
415 to it.
416 • A Filename
418 If $output is a filename and "Append" is enabled, the file
420 will be opened in append mode. Otherwise the contents of the
421 file, if any, will be truncated before any compressed data is
422 written to it.
423 • A Filehandle
425 If $output is a filehandle, the file pointer will be
427 positioned to the end of the file via a call to "seek" before
428 any compressed data is written to it. Otherwise the file
429 pointer will not be moved.
430 This parameter defaults to 0.
432 File Naming Options
434 A quick bit of zip file terminology -- A zip archive consists of one or
436 more archive members, where each member has an associated filename,
437 known as the archive member name.
438 The options listed in this section control how the archive member name
440 (or filename) is stored the zip archive.
441 "Name => $string"
443 This option is used to explicitly set the archive member name in
444 the zip archive to $string. Most of the time you don't need to
445 make use of this option. By default when adding a filename to the
446 zip archive, the archive member name will match the filename.
447 You should only need to use this option if you want the archive
449 member name to be different from the uncompressed filename or when
450 the input is a filehandle or a buffer.
451 The default behaviour for what archive member name is used when
453 the "Name" option is not specified depends on the form of the
454 $input parameter:
455 • If the $input parameter is a filename, the value of $input
457 will be used for the archive member name .
458 • If the $input parameter is not a filename, the archive member
460 name will be an empty string.
461 Note that both the "CanonicalName" and "FilterName" options can
463 modify the value used for the archive member name.
464 Also note that you should set the "Efs" option to true if you are
466 working with UTF8 filenames.
467 "CanonicalName => 0|1"
469 This option controls whether the archive member name is normalized
470 into Unix format before being written to the zip file.
471 It is recommended that you enable this option unless you really
473 need to create a non-standard Zip file.
474 This is what APPNOTE.TXT has to say on what should be stored in
476 the zip filename header field.
477 The name of the file, with optional relative path.
479 The path stored should not contain a drive or
480 device letter, or a leading slash. All slashes
481 should be forward slashes '/' as opposed to
482 backwards slashes '\' for compatibility with Amiga
483 and UNIX file systems etc.
484 This option defaults to false.
486 "FilterName => sub { ... }"
488 This option allow the archive member name to be modified before it
489 is written to the zip file.
490 This option takes a parameter that must be a reference to a sub.
492 On entry to the sub the $_ variable will contain the name to be
493 filtered. If no filename is available $_ will contain an empty
494 string.
495 The value of $_ when the sub returns will be used as the archive
497 member name.
498 Note that if "CanonicalName" is enabled, a normalized filename
500 will be passed to the sub.
501 If you use "FilterName" to modify the filename, it is your
503 responsibility to keep the filename in Unix format.
504 Although this option can be used with the OO interface, it is of
506 most use with the one-shot interface. For example, the code below
507 shows how "FilterName" can be used to remove the path component
508 from a series of filenames before they are stored in $zipfile.
509 sub compressTxtFiles
511 {
512 my $zipfile = shift ;
513 my $dir = shift ;
514 zip [ <$dir/*.txt> ] => $zipfile,
516 FilterName => sub { s[^$dir/][] } ;
517 }
518 "Efs => 0|1"
520 This option controls setting of the "Language Encoding Flag" (EFS)
521 in the zip archive. When set, the filename and comment fields for
522 the zip archive MUST be valid UTF-8.
523 If the string used for the filename and/or comment is not valid
525 UTF-8 when this option is true, the script will die with a "wide
526 character" error.
527 Note that this option only works with Perl 5.8.4 or better.
529 This option defaults to false.
531 Overall Zip Archive Structure
533 "Minimal => 1|0"
535 If specified, this option will disable the creation of all extra
536 fields in the zip local and central headers. So the "exTime",
537 "exUnix2", "exUnixN", "ExtraFieldLocal" and "ExtraFieldCentral"
538 options will be ignored.
539 This parameter defaults to 0.
541 "Stream => 0|1"
543 This option controls whether the zip file/buffer output is created
544 in streaming mode.
545 Note that when outputting to a file with streaming mode disabled
547 ("Stream" is 0), the output file must be seekable.
548 The default is 1.
550 "Zip64 => 0|1"
552 Create a Zip64 zip file/buffer. This option is used if you want to
553 store files larger than 4 Gig or store more than 64K files in a
554 single zip archive.
555 "Zip64" will be automatically set, as needed, if working with the
557 one-shot interface when the input is either a filename or a scalar
558 reference.
559 If you intend to manipulate the Zip64 zip files created with this
561 module using an external zip/unzip, make sure that it supports
562 Zip64.
563 In particular, if you are using Info-Zip you need to have zip
565 version 3.x or better to update a Zip64 archive and unzip version
566 6.x to read a zip64 archive.
567 The default is 0.
569 Deflate Compression Options
571 -Level
573 Defines the compression level used by zlib. The value should
574 either be a number between 0 and 9 (0 means no compression and 9
575 is maximum compression), or one of the symbolic constants defined
576 below.
577 Z_NO_COMPRESSION
579 Z_BEST_SPEED
580 Z_BEST_COMPRESSION
581 Z_DEFAULT_COMPRESSION
582 The default is Z_DEFAULT_COMPRESSION.
584 Note, these constants are not imported by "IO::Compress::Zip" by
586 default.
587 use IO::Compress::Zip qw(:strategy);
589 use IO::Compress::Zip qw(:constants);
590 use IO::Compress::Zip qw(:all);
591 -Strategy
593 Defines the strategy used to tune the compression. Use one of the
594 symbolic constants defined below.
595 Z_FILTERED
597 Z_HUFFMAN_ONLY
598 Z_RLE
599 Z_FIXED
600 Z_DEFAULT_STRATEGY
601 The default is Z_DEFAULT_STRATEGY.
603 Bzip2 Compression Options
605 "BlockSize100K => number"
607 Specify the number of 100K blocks bzip2 uses during compression.
608 Valid values are from 1 to 9, where 9 is best compression.
610 This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
612 ignored otherwise.
613 The default is 1.
615 "WorkFactor => number"
617 Specifies how much effort bzip2 should take before resorting to a
618 slower fallback compression algorithm.
619 Valid values range from 0 to 250, where 0 means use the default
621 value 30.
622 This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
624 ignored otherwise.
625 The default is 0.
627 Lzma and Xz Compression Options
629 "Preset => number"
631 Used to choose the LZMA compression preset.
632 Valid values are 0-9 and "LZMA_PRESET_DEFAULT".
634 0 is the fastest compression with the lowest memory usage and the
636 lowest compression.
637 9 is the slowest compression with the highest memory usage but
639 with the best compression.
640 This option is only valid if the "Method" is ZIP_CM_LZMA. It is
642 ignored otherwise.
643 Defaults to "LZMA_PRESET_DEFAULT" (6).
645 "Extreme => 0|1"
647 Makes LZMA compression a lot slower, but a small compression gain.
648 This option is only valid if the "Method" is ZIP_CM_LZMA. It is
650 ignored otherwise.
651 Defaults to 0.
653 Other Options
655 "Time => $number"
657 Sets the last modified time field in the zip header to $number.
658 This field defaults to the time the "IO::Compress::Zip" object was
660 created if this option is not specified and the $input parameter
661 is not a filename.
662 "ExtAttr => $attr"
664 This option controls the "external file attributes" field in the
665 central header of the zip file. This is a 4 byte field.
666 If you are running a Unix derivative this value defaults to
668 0100644 << 16
670 This should allow read/write access to any files that are
672 extracted from the zip file/buffer`.
673 For all other systems it defaults to 0.
675 "exTime => [$atime, $mtime, $ctime]"
677 This option expects an array reference with exactly three
678 elements: $atime, "mtime" and $ctime. These correspond to the last
679 access time, last modification time and creation time
680 respectively.
681 It uses these values to set the extended timestamp field (ID is
683 "UT") in the local zip header using the three values, $atime,
684 $mtime, $ctime. In addition it sets the extended timestamp field
685 in the central zip header using $mtime.
686 If any of the three values is "undef" that time value will not be
688 used. So, for example, to set only the $mtime you would use this
689 exTime => [undef, $mtime, undef]
691 If the "Minimal" option is set to true, this option will be
693 ignored.
694 By default no extended time field is created.
696 "exUnix2 => [$uid, $gid]"
698 This option expects an array reference with exactly two elements:
699 $uid and $gid. These values correspond to the numeric User ID
700 (UID) and Group ID (GID) of the owner of the files respectively.
701 When the "exUnix2" option is present it will trigger the creation
703 of a Unix2 extra field (ID is "Ux") in the local zip header. This
704 will be populated with $uid and $gid. An empty Unix2 extra field
705 will also be created in the central zip header.
706 Note - The UID & GID are stored as 16-bit integers in the "Ux"
708 field. Use "exUnixN" if your UID or GID are 32-bit.
709 If the "Minimal" option is set to true, this option will be
711 ignored.
712 By default no Unix2 extra field is created.
714 "exUnixN => [$uid, $gid]"
716 This option expects an array reference with exactly two elements:
717 $uid and $gid. These values correspond to the numeric User ID
718 (UID) and Group ID (GID) of the owner of the files respectively.
719 When the "exUnixN" option is present it will trigger the creation
721 of a UnixN extra field (ID is "ux") in both the local and central
722 zip headers. This will be populated with $uid and $gid. The UID
723 & GID are stored as 32-bit integers.
724 If the "Minimal" option is set to true, this option will be
726 ignored.
727 By default no UnixN extra field is created.
729 "Comment => $comment"
731 Stores the contents of $comment in the Central File Header of the
732 zip file.
733 Set the "Efs" option to true if you want to store a UTF8 comment.
735 By default, no comment field is written to the zip file.
737 "ZipComment => $comment"
739 Stores the contents of $comment in the End of Central Directory
740 record of the zip file.
741 By default, no comment field is written to the zip file.
743 "Method => $method"
745 Controls which compression method is used. At present the
746 compression methods supported are: Store (no compression at all),
747 Deflate, Bzip2, Zstd, Xz and Lzma.
748 The symbols ZIP_CM_STORE, ZIP_CM_DEFLATE, ZIP_CM_BZIP2,
750 ZIP_CM_ZSTD, ZIP_CM_XZ and ZIP_CM_LZMA are used to select the
751 compression method.
752 These constants are not imported by "IO::Compress::Zip" by
754 default.
755 use IO::Compress::Zip qw(:zip_method);
757 use IO::Compress::Zip qw(:constants);
758 use IO::Compress::Zip qw(:all);
759 Note that to create Bzip2 content, the module
761 "IO::Compress::Bzip2" must be installed. A fatal error will be
762 thrown if you attempt to create Bzip2 content when
763 "IO::Compress::Bzip2" is not available.
764 Note that to create Lzma content, the module "IO::Compress::Lzma"
766 must be installed. A fatal error will be thrown if you attempt to
767 create Lzma content when "IO::Compress::Lzma" is not available.
768 Note that to create Xz content, the module "IO::Compress::Xz" must
770 be installed. A fatal error will be thrown if you attempt to
771 create Xz content when "IO::Compress::Xz" is not available.
772 Note that to create Zstd content, the module "IO::Compress::Zstd"
774 must be installed. A fatal error will be thrown if you attempt to
775 create Zstd content when "IO::Compress::Zstd" is not available.
776 The default method is ZIP_CM_DEFLATE.
778 "TextFlag => 0|1"
780 This parameter controls the setting of a bit in the zip central
781 header. It is used to signal that the data stored in the zip
782 file/buffer is probably text.
783 In one-shot mode this flag will be set to true if the Perl "-T"
785 operator thinks the file contains text.
786 The default is 0.
788 "ExtraFieldLocal => $data"
790 "ExtraFieldCentral => $data"
791 The "ExtraFieldLocal" option is used to store additional metadata
792 in the local header for the zip file/buffer. The
793 "ExtraFieldCentral" does the same for the matching central header.
794 An extra field consists of zero or more subfields. Each subfield
796 consists of a two byte header followed by the subfield data.
797 The list of subfields can be supplied in any of the following
799 formats
800 ExtraFieldLocal => [$id1, $data1,
802 $id2, $data2,
803 ...
804 ]
805 ExtraFieldLocal => [ [$id1 => $data1],
807 [$id2 => $data2],
808 ...
809 ]
810 ExtraFieldLocal => { $id1 => $data1,
812 $id2 => $data2,
813 ...
814 }
815 Where $id1, $id2 are two byte subfield ID's.
817 If you use the hash syntax, you have no control over the order in
819 which the ExtraSubFields are stored, plus you cannot have
820 SubFields with duplicate ID.
821 Alternatively the list of subfields can by supplied as a scalar,
823 thus
824 ExtraField => $rawdata
826 In this case "IO::Compress::Zip" will check that $rawdata consists
828 of zero or more conformant sub-fields.
829 The Extended Time field (ID "UT"), set using the "exTime" option,
831 and the Unix2 extra field (ID "Ux), set using the "exUnix2"
832 option, are examples of extra fields.
833 If the "Minimal" option is set to true, this option will be
835 ignored.
836 The maximum size of an extra field 65535 bytes.
838 "Strict => 0|1"
840 This is a placeholder option.
841 Examples
843 TODO
844
846 print
847 Usage is
848 $z->print($data)
850 print $z $data
851 Compresses and outputs the contents of the $data parameter. This has
853 the same behaviour as the "print" built-in.
854 Returns true if successful.
856 printf
858 Usage is
859 $z->printf($format, $data)
861 printf $z $format, $data
862 Compresses and outputs the contents of the $data parameter.
864 Returns true if successful.
866 syswrite
868 Usage is
869 $z->syswrite $data
871 $z->syswrite $data, $length
872 $z->syswrite $data, $length, $offset
873 Compresses and outputs the contents of the $data parameter.
875 Returns the number of uncompressed bytes written, or "undef" if
877 unsuccessful.
878 write
880 Usage is
881 $z->write $data
883 $z->write $data, $length
884 $z->write $data, $length, $offset
885 Compresses and outputs the contents of the $data parameter.
887 Returns the number of uncompressed bytes written, or "undef" if
889 unsuccessful.
890 flush
892 Usage is
893 $z->flush;
895 $z->flush($flush_type);
896 Flushes any pending compressed data to the output file/buffer.
898 This method takes an optional parameter, $flush_type, that controls how
900 the flushing will be carried out. By default the $flush_type used is
901 "Z_FINISH". Other valid values for $flush_type are "Z_NO_FLUSH",
902 "Z_SYNC_FLUSH", "Z_FULL_FLUSH" and "Z_BLOCK". It is strongly
903 recommended that you only set the "flush_type" parameter if you fully
904 understand the implications of what it does - overuse of "flush" can
905 seriously degrade the level of compression achieved. See the "zlib"
906 documentation for details.
907 Returns true on success.
909 tell
911 Usage is
912 $z->tell()
914 tell $z
915 Returns the uncompressed file offset.
917 eof
919 Usage is
920 $z->eof();
922 eof($z);
923 Returns true if the "close" method has been called.
925 seek
927 $z->seek($position, $whence);
928 seek($z, $position, $whence);
929 Provides a sub-set of the "seek" functionality, with the restriction
931 that it is only legal to seek forward in the output file/buffer. It is
932 a fatal error to attempt to seek backward.
933 Empty parts of the file/buffer will have NULL (0x00) bytes written to
935 them.
936 The $whence parameter takes one the usual values, namely SEEK_SET,
938 SEEK_CUR or SEEK_END.
939 Returns 1 on success, 0 on failure.
941 binmode
943 Usage is
944 $z->binmode
946 binmode $z ;
947 This is a noop provided for completeness.
949 opened
951 $z->opened()
952 Returns true if the object currently refers to a opened file/buffer.
954 autoflush
956 my $prev = $z->autoflush()
957 my $prev = $z->autoflush(EXPR)
958 If the $z object is associated with a file or a filehandle, this method
960 returns the current autoflush setting for the underlying filehandle. If
961 "EXPR" is present, and is non-zero, it will enable flushing after every
962 write/print operation.
963 If $z is associated with a buffer, this method has no effect and always
965 returns "undef".
966 Note that the special variable $| cannot be used to set or retrieve the
968 autoflush setting.
969 input_line_number
971 $z->input_line_number()
972 $z->input_line_number(EXPR)
973 This method always returns "undef" when compressing.
975 fileno
977 $z->fileno()
978 fileno($z)
979 If the $z object is associated with a file or a filehandle, "fileno"
981 will return the underlying file descriptor. Once the "close" method is
982 called "fileno" will return "undef".
983 If the $z object is associated with a buffer, this method will return
985 "undef".
986 close
988 $z->close() ;
989 close $z ;
990 Flushes any pending compressed data and then closes the output
992 file/buffer.
993 For most versions of Perl this method will be automatically invoked if
995 the IO::Compress::Zip object is destroyed (either explicitly or by the
996 variable with the reference to the object going out of scope). The
997 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
998 cases, the "close" method will be called automatically, but not until
999 global destruction of all live objects when the program is terminating.
1000 Therefore, if you want your scripts to be able to run on all versions
1002 of Perl, you should call "close" explicitly and not rely on automatic
1003 closing.
1004 Returns true on success, otherwise 0.
1006 If the "AutoClose" option has been enabled when the IO::Compress::Zip
1008 object was created, and the object is associated with a file, the
1009 underlying file will also be closed.
1010 newStream([OPTS])
1012 Usage is
1013 $z->newStream( [OPTS] )
1015 Closes the current compressed data stream and starts a new one.
1017 OPTS consists of any of the options that are available when creating
1019 the $z object.
1020 See the "Constructor Options" section for more details.
1022 deflateParams
1024 Usage is
1025 $z->deflateParams
1027 TODO
1029
1031 A number of symbolic constants are required by some methods in
1032 "IO::Compress::Zip". None are imported by default.
1033 :all Imports "zip", $ZipError and all symbolic constants that can be
1035 used by "IO::Compress::Zip". Same as doing this
1036 use IO::Compress::Zip qw(zip $ZipError :constants) ;
1038 :constants
1040 Import all symbolic constants. Same as doing this
1041 use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
1043 :flush
1045 These symbolic constants are used by the "flush" method.
1046 Z_NO_FLUSH
1048 Z_PARTIAL_FLUSH
1049 Z_SYNC_FLUSH
1050 Z_FULL_FLUSH
1051 Z_FINISH
1052 Z_BLOCK
1053 :level
1055 These symbolic constants are used by the "Level" option in the
1056 constructor.
1057 Z_NO_COMPRESSION
1059 Z_BEST_SPEED
1060 Z_BEST_COMPRESSION
1061 Z_DEFAULT_COMPRESSION
1062 :strategy
1064 These symbolic constants are used by the "Strategy" option in the
1065 constructor.
1066 Z_FILTERED
1068 Z_HUFFMAN_ONLY
1069 Z_RLE
1070 Z_FIXED
1071 Z_DEFAULT_STRATEGY
1072 :zip_method
1074 These symbolic constants are used by the "Method" option in the
1075 constructor.
1076 ZIP_CM_STORE
1078 ZIP_CM_DEFLATE
1079 ZIP_CM_BZIP2
1080
1082 Apache::GZip Revisited
1083 See IO::Compress::FAQ
1084 Working with Net::FTP
1086 See IO::Compress::FAQ
1087
1089 General feedback/questions/bug reports should be sent to
1090 <https://github.com/pmqs/IO-Compress/issues> (preferred) or
1091 <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
1092
1094 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
1095 IO::Compress::Deflate, IO::Uncompress::Inflate,
1096 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
1097 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma,
1098 IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz,
1099 IO::Compress::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop,
1100 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
1101 IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate,
1102 IO::Uncompress::AnyUncompress
1103 IO::Compress::FAQ
1105 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
1107 For RFC 1950, 1951 and 1952 see
1109 <http://www.faqs.org/rfcs/rfc1950.html>,
1110 <http://www.faqs.org/rfcs/rfc1951.html> and
1111 <http://www.faqs.org/rfcs/rfc1952.html>
1112 The zlib compression library was written by Jean-loup Gailly
1114 "gzip@prep.ai.mit.edu" and Mark Adler "madler@alumni.caltech.edu".
1115 The primary site for the zlib compression library is
1117 <http://www.zlib.org>.
1118 The primary site for gzip is <http://www.gzip.org>.
1120
1122 This module was written by Paul Marquess, "pmqs@cpan.org".
1123
1125 See the Changes file.
1126
1128 Copyright (c) 2005-2021 Paul Marquess. All rights reserved.
1129 This program is free software; you can redistribute it and/or modify it
1131 under the same terms as Perl itself.
1132perl v5.32.1 2021-03-01 IO::Compress::Zip(3)