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 = 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" or
56 "Archive::Zip::SimpleZip".
57 At present the following compression methods are supported by
59 IO::Compress::Zip, namely Store (no compression at all), Deflate, Bzip2
60 and LZMA.
61 Note
63 · To use Bzip2 compression, the module "IO::Compress::Bzip2" must be
65 installed.
66 · To use LZMA compression, the module "IO::Compress::Lzma" must be
68 installed.
69 For reading zip files/buffers, see the companion module
71 IO::Uncompress::Unzip.
72
74 A top-level function, "zip", is provided to carry out "one-shot"
75 compression between buffers and/or files. For finer control over the
76 compression process, see the "OO Interface" section.
77 use IO::Compress::Zip qw(zip $ZipError) ;
79 zip $input_filename_or_reference => $output_filename_or_reference [,OPTS]
81 or die "zip failed: $ZipError\n";
82 The functional interface needs Perl5.005 or better.
84 zip $input_filename_or_reference => $output_filename_or_reference [, OPTS]
86 "zip" expects at least two parameters, $input_filename_or_reference and
87 $output_filename_or_reference and zero or more optional parameters (see
88 "Optional Parameters")
89 The $input_filename_or_reference parameter
91 The parameter, $input_filename_or_reference, is used to define the
93 source of the uncompressed data.
94 It can take one of the following forms:
96 A filename
98 If the $input_filename_or_reference parameter is a simple scalar,
99 it is assumed to be a filename. This file will be opened for
100 reading and the input data will be read from it.
101 A filehandle
103 If the $input_filename_or_reference parameter is a filehandle, the
104 input data will be read from it. The string '-' can be used as an
105 alias for standard input.
106 A scalar reference
108 If $input_filename_or_reference is a scalar reference, the input
109 data will be read from $$input_filename_or_reference.
110 An array reference
112 If $input_filename_or_reference is an array reference, each
113 element in the array must be a filename.
114 The input data will be read from each file in turn.
116 The complete array will be walked to ensure that it only contains
118 valid filenames before any data is compressed.
119 An Input FileGlob string
121 If $input_filename_or_reference is a string that is delimited by
122 the characters "<" and ">" "zip" will assume that it is an input
123 fileglob string. The input is the list of files that match the
124 fileglob.
125 See File::GlobMapper for more details.
127 If the $input_filename_or_reference parameter is any other type,
129 "undef" will be returned.
130 In addition, if $input_filename_or_reference is a simple filename, the
132 default values for the "Name", "Time", "TextFlag", "ExtAttr", "exUnixN"
133 and "exTime" options will be sourced from that file.
134 If you do not want to use these defaults they can be overridden by
136 explicitly setting the "Name", "Time", "TextFlag", "ExtAttr", "exUnixN"
137 and "exTime" options or by setting the "Minimal" parameter.
138 The $output_filename_or_reference parameter
140 The parameter $output_filename_or_reference is used to control the
142 destination of the compressed data. This parameter can take one of
143 these forms.
144 A filename
146 If the $output_filename_or_reference parameter is a simple scalar,
147 it is assumed to be a filename. This file will be opened for
148 writing and the compressed data will be written to it.
149 A filehandle
151 If the $output_filename_or_reference parameter is a filehandle,
152 the compressed data will be written to it. The string '-' can be
153 used as an alias for standard output.
154 A scalar reference
156 If $output_filename_or_reference is a scalar reference, the
157 compressed data will be stored in $$output_filename_or_reference.
158 An Array Reference
160 If $output_filename_or_reference is an array reference, the
161 compressed data will be pushed onto the array.
162 An Output FileGlob
164 If $output_filename_or_reference is a string that is delimited by
165 the characters "<" and ">" "zip" will assume that it is an output
166 fileglob string. The output is the list of files that match the
167 fileglob.
168 When $output_filename_or_reference is an fileglob string,
170 $input_filename_or_reference must also be a fileglob string.
171 Anything else is an error.
172 See File::GlobMapper for more details.
174 If the $output_filename_or_reference parameter is any other type,
176 "undef" will be returned.
177 Notes
179 When $input_filename_or_reference maps to multiple files/buffers and
180 $output_filename_or_reference is a single file/buffer the input
181 files/buffers will each be stored in $output_filename_or_reference as a
182 distinct entry.
183 Optional Parameters
185 The optional parameters for the one-shot function "zip" are (for the
186 most part) identical to those used with the OO interface defined in the
187 "Constructor Options" section. The exceptions are listed below
188 "AutoClose => 0|1"
190 This option applies to any input or output data streams to "zip"
191 that are filehandles.
192 If "AutoClose" is specified, and the value is true, it will result
194 in all input and/or output filehandles being closed once "zip" has
195 completed.
196 This parameter defaults to 0.
198 "BinModeIn => 0|1"
200 This option is now a no-op. All files will be read in binmode.
201 "Append => 0|1"
203 The behaviour of this option is dependent on the type of output
204 data stream.
205 · A Buffer
207 If "Append" is enabled, all compressed data will be append to
209 the end of the output buffer. Otherwise the output buffer
210 will be cleared before any compressed data is written to it.
211 · A Filename
213 If "Append" is enabled, the file will be opened in append
215 mode. Otherwise the contents of the file, if any, will be
216 truncated before any compressed data is written to it.
217 · A Filehandle
219 If "Append" is enabled, the filehandle will be positioned to
221 the end of the file via a call to "seek" before any
222 compressed data is written to it. Otherwise the file pointer
223 will not be moved.
224 When "Append" is specified, and set to true, it will append all
226 compressed data to the output data stream.
227 So when the output is a filehandle it will carry out a seek to the
229 eof before writing any compressed data. If the output is a
230 filename, it will be opened for appending. If the output is a
231 buffer, all compressed data will be appended to the existing
232 buffer.
233 Conversely when "Append" is not specified, or it is present and is
235 set to false, it will operate as follows.
236 When the output is a filename, it will truncate the contents of
238 the file before writing any compressed data. If the output is a
239 filehandle its position will not be changed. If the output is a
240 buffer, it will be wiped before any compressed data is output.
241 Defaults to 0.
243 Examples
245 Here are a few example that show the capabilities of the module.
246 Streaming
248 This very simple command line example demonstrates the streaming
250 capabilities of the module. The code reads data from STDIN, compresses
251 it, and writes the compressed data to STDOUT.
252 $ echo hello world | perl -MIO::Compress::Zip=zip -e 'zip \*STDIN => \*STDOUT' >output.zip
254 The special filename "-" can be used as a standin for both "\*STDIN"
256 and "\*STDOUT", so the above can be rewritten as
257 $ echo hello world | perl -MIO::Compress::Zip=zip -e 'zip "-" => "-"' >output.zip
259 One problem with creating a zip archive directly from STDIN can be
261 demonstrated by looking at the contents of the zip file, output.zip,
262 that we have just created.
263 $ unzip -l output.zip
265 Archive: output.zip
266 Length Date Time Name
267 --------- ---------- ----- ----
268 12 2019-08-16 22:21
269 --------- -------
270 12 1 file
271 The archive member (filename) used is the empty string.
273 If that doesn't suit your needs, you can explicitly set the filename
275 used in the zip archive by specifying the Name option, like so
276 echo hello world | perl -MIO::Compress::Zip=zip -e 'zip "-" => "-", Name => "hello.txt"' >output.zip
278 Now the contents of the zip file looks like this
280 $ unzip -l output.zip
282 Archive: output.zip
283 Length Date Time Name
284 --------- ---------- ----- ----
285 12 2019-08-16 22:22 hello.txt
286 --------- -------
287 12 1 file
288 Compressing a file from the filesystem
290 To read the contents of the file "file1.txt" and write the compressed
292 data to the file "file1.txt.zip".
293 use strict ;
295 use warnings ;
296 use IO::Compress::Zip qw(zip $ZipError) ;
297 my $input = "file1.txt";
299 zip $input => "$input.zip"
300 or die "zip failed: $ZipError\n";
301 Reading from a Filehandle and writing to an in-memory buffer
303 To read from an existing Perl filehandle, $input, and write the
305 compressed data to a buffer, $buffer.
306 use strict ;
308 use warnings ;
309 use IO::Compress::Zip qw(zip $ZipError) ;
310 use IO::File ;
311 my $input = new IO::File "<file1.txt"
313 or die "Cannot open 'file1.txt': $!\n" ;
314 my $buffer ;
315 zip $input => \$buffer
316 or die "zip failed: $ZipError\n";
317 Compressing multiple files
319 To create a zip file, "output.zip", that contains the compressed
321 contents of the files "alpha.txt" and "beta.txt"
322 use strict ;
324 use warnings ;
325 use IO::Compress::Zip qw(zip $ZipError) ;
326 zip [ 'alpha.txt', 'beta.txt' ] => 'output.zip'
328 or die "zip failed: $ZipError\n";
329 Alternatively, rather than having to explicitly name each of the files
331 that you want to compress, you could use a fileglob to select all the
332 "txt" files in the current directory, as follows
333 use strict ;
335 use warnings ;
336 use IO::Compress::Zip qw(zip $ZipError) ;
337 my @files = <*.txt>;
339 zip \@files => 'output.zip'
340 or die "zip failed: $ZipError\n";
341 or more succinctly
343 zip [ <*.txt> ] => 'output.zip'
345 or die "zip failed: $ZipError\n";
346
348 Constructor
349 The format of the constructor for "IO::Compress::Zip" is shown below
350 my $z = new IO::Compress::Zip $output [,OPTS]
352 or die "IO::Compress::Zip failed: $ZipError\n";
353 It returns an "IO::Compress::Zip" object on success and undef on
355 failure. The variable $ZipError will contain an error message on
356 failure.
357 If you are running Perl 5.005 or better the object, $z, returned from
359 IO::Compress::Zip can be used exactly like an IO::File filehandle.
360 This means that all normal output file operations can be carried out
361 with $z. For example, to write to a compressed file/buffer you can use
362 either of these forms
363 $z->print("hello world\n");
365 print $z "hello world\n";
366 The mandatory parameter $output is used to control the destination of
368 the compressed data. This parameter can take one of these forms.
369 A filename
371 If the $output parameter is a simple scalar, it is assumed to be a
372 filename. This file will be opened for writing and the compressed
373 data will be written to it.
374 A filehandle
376 If the $output parameter is a filehandle, the compressed data will
377 be written to it. The string '-' can be used as an alias for
378 standard output.
379 A scalar reference
381 If $output is a scalar reference, the compressed data will be
382 stored in $$output.
383 If the $output parameter is any other type, "IO::Compress::Zip"::new
385 will return undef.
386 Constructor Options
388 "OPTS" is any combination of zero or more the following options:
389 "AutoClose => 0|1"
391 This option is only valid when the $output parameter is a
392 filehandle. If specified, and the value is true, it will result in
393 the $output being closed once either the "close" method is called
394 or the "IO::Compress::Zip" object is destroyed.
395 This parameter defaults to 0.
397 "Append => 0|1"
399 Opens $output in append mode.
400 The behaviour of this option is dependent on the type of $output.
402 · A Buffer
404 If $output is a buffer and "Append" is enabled, all
406 compressed data will be append to the end of $output.
407 Otherwise $output will be cleared before any data is written
408 to it.
409 · A Filename
411 If $output is a filename and "Append" is enabled, the file
413 will be opened in append mode. Otherwise the contents of the
414 file, if any, will be truncated before any compressed data is
415 written to it.
416 · A Filehandle
418 If $output is a filehandle, the file pointer will be
420 positioned to the end of the file via a call to "seek" before
421 any compressed data is written to it. Otherwise the file
422 pointer will not be moved.
423 This parameter defaults to 0.
425 File Naming Options
427 A quick bit of zip file terminology -- A zip archive consists of one or
429 more archive members, where each member has an associated filename,
430 known as the archive member name.
431 The options listed in this section control how the archive member name
433 (or filename) is stored the zip archive.
434 "Name => $string"
436 This option is used to explicitly set the archive member name in
437 the zip archive to $string. Most of the time you don't need to
438 make use of this option. By default when adding a filename to the
439 zip archive, the archive member name will match the filename.
440 You should only need to use this option if you want the archive
442 member name to be different from the uncompressed filename or when
443 the input is a filehandle or a buffer.
444 The default behaviour for what archive member name is used when
446 the "Name" option is not specified depends on the form of the
447 $input parameter:
448 · If the $input parameter is a filename, the value of $input
450 will be used for the archive member name .
451 · If the $input parameter is not a filename, the archive member
453 name will be an empty string.
454 Note that both the "CanonicalName" and "FilterName" options can
456 modify the value used for the archive member name.
457 Also note that you should set the "Efs" option to true if you are
459 working with UTF8 filenames.
460 "CanonicalName => 0|1"
462 This option controls whether the archive member name is normalized
463 into Unix format before being written to the zip file.
464 It is recommended that you enable this option unless you really
466 need to create a non-standard Zip file.
467 This is what APPNOTE.TXT has to say on what should be stored in
469 the zip filename header field.
470 The name of the file, with optional relative path.
472 The path stored should not contain a drive or
473 device letter, or a leading slash. All slashes
474 should be forward slashes '/' as opposed to
475 backwards slashes '\' for compatibility with Amiga
476 and UNIX file systems etc.
477 This option defaults to false.
479 "FilterName => sub { ... }"
481 This option allow the archive member name to be modified before it
482 is written to the zip file.
483 This option takes a parameter that must be a reference to a sub.
485 On entry to the sub the $_ variable will contain the name to be
486 filtered. If no filename is available $_ will contain an empty
487 string.
488 The value of $_ when the sub returns will be used as the archive
490 member name.
491 Note that if "CanonicalName" is enabled, a normalized filename
493 will be passed to the sub.
494 If you use "FilterName" to modify the filename, it is your
496 responsibility to keep the filename in Unix format.
497 Although this option can be used with the OO interface, it is of
499 most use with the one-shot interface. For example, the code below
500 shows how "FilterName" can be used to remove the path component
501 from a series of filenames before they are stored in $zipfile.
502 sub compressTxtFiles
504 {
505 my $zipfile = shift ;
506 my $dir = shift ;
507 zip [ <$dir/*.txt> ] => $zipfile,
509 FilterName => sub { s[^$dir/][] } ;
510 }
511 "Efs => 0|1"
513 This option controls setting of the "Language Encoding Flag" (EFS)
514 in the zip archive. When set, the filename and comment fields for
515 the zip archive MUST be valid UTF-8.
516 If the string used for the filename and/or comment is not valid
518 UTF-8 when this option is true, the script will die with a "wide
519 character" error.
520 Note that this option only works with Perl 5.8.4 or better.
522 This option defaults to false.
524 Overall Zip Archive Structure
526 "Minimal => 1|0"
528 If specified, this option will disable the creation of all extra
529 fields in the zip local and central headers. So the "exTime",
530 "exUnix2", "exUnixN", "ExtraFieldLocal" and "ExtraFieldCentral"
531 options will be ignored.
532 This parameter defaults to 0.
534 "Stream => 0|1"
536 This option controls whether the zip file/buffer output is created
537 in streaming mode.
538 Note that when outputting to a file with streaming mode disabled
540 ("Stream" is 0), the output file must be seekable.
541 The default is 1.
543 "Zip64 => 0|1"
545 Create a Zip64 zip file/buffer. This option is used if you want to
546 store files larger than 4 Gig or store more than 64K files in a
547 single zip archive.
548 "Zip64" will be automatically set, as needed, if working with the
550 one-shot interface when the input is either a filename or a scalar
551 reference.
552 If you intend to manipulate the Zip64 zip files created with this
554 module using an external zip/unzip, make sure that it supports
555 Zip64.
556 In particular, if you are using Info-Zip you need to have zip
558 version 3.x or better to update a Zip64 archive and unzip version
559 6.x to read a zip64 archive.
560 The default is 0.
562 Deflate Compression Options
564 -Level
566 Defines the compression level used by zlib. The value should
567 either be a number between 0 and 9 (0 means no compression and 9
568 is maximum compression), or one of the symbolic constants defined
569 below.
570 Z_NO_COMPRESSION
572 Z_BEST_SPEED
573 Z_BEST_COMPRESSION
574 Z_DEFAULT_COMPRESSION
575 The default is Z_DEFAULT_COMPRESSION.
577 Note, these constants are not imported by "IO::Compress::Zip" by
579 default.
580 use IO::Compress::Zip qw(:strategy);
582 use IO::Compress::Zip qw(:constants);
583 use IO::Compress::Zip qw(:all);
584 -Strategy
586 Defines the strategy used to tune the compression. Use one of the
587 symbolic constants defined below.
588 Z_FILTERED
590 Z_HUFFMAN_ONLY
591 Z_RLE
592 Z_FIXED
593 Z_DEFAULT_STRATEGY
594 The default is Z_DEFAULT_STRATEGY.
596 Bzip2 Compression Options
598 "BlockSize100K => number"
600 Specify the number of 100K blocks bzip2 uses during compression.
601 Valid values are from 1 to 9, where 9 is best compression.
603 This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
605 ignored otherwise.
606 The default is 1.
608 "WorkFactor => number"
610 Specifies how much effort bzip2 should take before resorting to a
611 slower fallback compression algorithm.
612 Valid values range from 0 to 250, where 0 means use the default
614 value 30.
615 This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
617 ignored otherwise.
618 The default is 0.
620 Lzma Compression Options
622 "Preset => number"
624 Used to choose the LZMA compression preset.
625 Valid values are 0-9 and "LZMA_PRESET_DEFAULT".
627 0 is the fastest compression with the lowest memory usage and the
629 lowest compression.
630 9 is the slowest compression with the highest memory usage but
632 with the best compression.
633 This option is only valid if the "Method" is ZIP_CM_LZMA. It is
635 ignored otherwise.
636 Defaults to "LZMA_PRESET_DEFAULT" (6).
638 "Extreme => 0|1"
640 Makes LZMA compression a lot slower, but a small compression gain.
641 This option is only valid if the "Method" is ZIP_CM_LZMA. It is
643 ignored otherwise.
644 Defaults to 0.
646 Other Options
648 "Time => $number"
650 Sets the last modified time field in the zip header to $number.
651 This field defaults to the time the "IO::Compress::Zip" object was
653 created if this option is not specified and the $input parameter
654 is not a filename.
655 "ExtAttr => $attr"
657 This option controls the "external file attributes" field in the
658 central header of the zip file. This is a 4 byte field.
659 If you are running a Unix derivative this value defaults to
661 0100644 << 16
663 This should allow read/write access to any files that are
665 extracted from the zip file/buffer`.
666 For all other systems it defaults to 0.
668 "exTime => [$atime, $mtime, $ctime]"
670 This option expects an array reference with exactly three
671 elements: $atime, "mtime" and $ctime. These correspond to the last
672 access time, last modification time and creation time
673 respectively.
674 It uses these values to set the extended timestamp field (ID is
676 "UT") in the local zip header using the three values, $atime,
677 $mtime, $ctime. In addition it sets the extended timestamp field
678 in the central zip header using $mtime.
679 If any of the three values is "undef" that time value will not be
681 used. So, for example, to set only the $mtime you would use this
682 exTime => [undef, $mtime, undef]
684 If the "Minimal" option is set to true, this option will be
686 ignored.
687 By default no extended time field is created.
689 "exUnix2 => [$uid, $gid]"
691 This option expects an array reference with exactly two elements:
692 $uid and $gid. These values correspond to the numeric User ID
693 (UID) and Group ID (GID) of the owner of the files respectively.
694 When the "exUnix2" option is present it will trigger the creation
696 of a Unix2 extra field (ID is "Ux") in the local zip header. This
697 will be populated with $uid and $gid. An empty Unix2 extra field
698 will also be created in the central zip header.
699 Note - The UID & GID are stored as 16-bit integers in the "Ux"
701 field. Use "exUnixN" if your UID or GID are 32-bit.
702 If the "Minimal" option is set to true, this option will be
704 ignored.
705 By default no Unix2 extra field is created.
707 "exUnixN => [$uid, $gid]"
709 This option expects an array reference with exactly two elements:
710 $uid and $gid. These values correspond to the numeric User ID
711 (UID) and Group ID (GID) of the owner of the files respectively.
712 When the "exUnixN" option is present it will trigger the creation
714 of a UnixN extra field (ID is "ux") in both the local and central
715 zip headers. This will be populated with $uid and $gid. The UID
716 & GID are stored as 32-bit integers.
717 If the "Minimal" option is set to true, this option will be
719 ignored.
720 By default no UnixN extra field is created.
722 "Comment => $comment"
724 Stores the contents of $comment in the Central File Header of the
725 zip file.
726 Set the "Efs" option to true if you want to store a UTF8 comment.
728 By default, no comment field is written to the zip file.
730 "ZipComment => $comment"
732 Stores the contents of $comment in the End of Central Directory
733 record of the zip file.
734 By default, no comment field is written to the zip file.
736 "Method => $method"
738 Controls which compression method is used. At present four
739 compression methods are supported, namely Store (no compression at
740 all), Deflate, Bzip2 and Lzma.
741 The symbols, ZIP_CM_STORE, ZIP_CM_DEFLATE, ZIP_CM_BZIP2 and
743 ZIP_CM_LZMA are used to select the compression method.
744 These constants are not imported by "IO::Compress::Zip" by
746 default.
747 use IO::Compress::Zip qw(:zip_method);
749 use IO::Compress::Zip qw(:constants);
750 use IO::Compress::Zip qw(:all);
751 Note that to create Bzip2 content, the module
753 "IO::Compress::Bzip2" must be installed. A fatal error will be
754 thrown if you attempt to create Bzip2 content when
755 "IO::Compress::Bzip2" is not available.
756 Note that to create Lzma content, the module "IO::Compress::Lzma"
758 must be installed. A fatal error will be thrown if you attempt to
759 create Lzma content when "IO::Compress::Lzma" is not available.
760 The default method is ZIP_CM_DEFLATE.
762 "TextFlag => 0|1"
764 This parameter controls the setting of a bit in the zip central
765 header. It is used to signal that the data stored in the zip
766 file/buffer is probably text.
767 In one-shot mode this flag will be set to true if the Perl "-T"
769 operator thinks the file contains text.
770 The default is 0.
772 "ExtraFieldLocal => $data"
774 "ExtraFieldCentral => $data"
775 The "ExtraFieldLocal" option is used to store additional metadata
776 in the local header for the zip file/buffer. The
777 "ExtraFieldCentral" does the same for the matching central header.
778 An extra field consists of zero or more subfields. Each subfield
780 consists of a two byte header followed by the subfield data.
781 The list of subfields can be supplied in any of the following
783 formats
784 ExtraFieldLocal => [$id1, $data1,
786 $id2, $data2,
787 ...
788 ]
789 ExtraFieldLocal => [ [$id1 => $data1],
791 [$id2 => $data2],
792 ...
793 ]
794 ExtraFieldLocal => { $id1 => $data1,
796 $id2 => $data2,
797 ...
798 }
799 Where $id1, $id2 are two byte subfield ID's.
801 If you use the hash syntax, you have no control over the order in
803 which the ExtraSubFields are stored, plus you cannot have
804 SubFields with duplicate ID.
805 Alternatively the list of subfields can by supplied as a scalar,
807 thus
808 ExtraField => $rawdata
810 In this case "IO::Compress::Zip" will check that $rawdata consists
812 of zero or more conformant sub-fields.
813 The Extended Time field (ID "UT"), set using the "exTime" option,
815 and the Unix2 extra field (ID "Ux), set using the "exUnix2"
816 option, are examples of extra fields.
817 If the "Minimal" option is set to true, this option will be
819 ignored.
820 The maximum size of an extra field 65535 bytes.
822 "Strict => 0|1"
824 This is a placeholder option.
825 Examples
827 TODO
828
830 print
831 Usage is
832 $z->print($data)
834 print $z $data
835 Compresses and outputs the contents of the $data parameter. This has
837 the same behaviour as the "print" built-in.
838 Returns true if successful.
840 printf
842 Usage is
843 $z->printf($format, $data)
845 printf $z $format, $data
846 Compresses and outputs the contents of the $data parameter.
848 Returns true if successful.
850 syswrite
852 Usage is
853 $z->syswrite $data
855 $z->syswrite $data, $length
856 $z->syswrite $data, $length, $offset
857 Compresses and outputs the contents of the $data parameter.
859 Returns the number of uncompressed bytes written, or "undef" if
861 unsuccessful.
862 write
864 Usage is
865 $z->write $data
867 $z->write $data, $length
868 $z->write $data, $length, $offset
869 Compresses and outputs the contents of the $data parameter.
871 Returns the number of uncompressed bytes written, or "undef" if
873 unsuccessful.
874 flush
876 Usage is
877 $z->flush;
879 $z->flush($flush_type);
880 Flushes any pending compressed data to the output file/buffer.
882 This method takes an optional parameter, $flush_type, that controls how
884 the flushing will be carried out. By default the $flush_type used is
885 "Z_FINISH". Other valid values for $flush_type are "Z_NO_FLUSH",
886 "Z_SYNC_FLUSH", "Z_FULL_FLUSH" and "Z_BLOCK". It is strongly
887 recommended that you only set the "flush_type" parameter if you fully
888 understand the implications of what it does - overuse of "flush" can
889 seriously degrade the level of compression achieved. See the "zlib"
890 documentation for details.
891 Returns true on success.
893 tell
895 Usage is
896 $z->tell()
898 tell $z
899 Returns the uncompressed file offset.
901 eof
903 Usage is
904 $z->eof();
906 eof($z);
907 Returns true if the "close" method has been called.
909 seek
911 $z->seek($position, $whence);
912 seek($z, $position, $whence);
913 Provides a sub-set of the "seek" functionality, with the restriction
915 that it is only legal to seek forward in the output file/buffer. It is
916 a fatal error to attempt to seek backward.
917 Empty parts of the file/buffer will have NULL (0x00) bytes written to
919 them.
920 The $whence parameter takes one the usual values, namely SEEK_SET,
922 SEEK_CUR or SEEK_END.
923 Returns 1 on success, 0 on failure.
925 binmode
927 Usage is
928 $z->binmode
930 binmode $z ;
931 This is a noop provided for completeness.
933 opened
935 $z->opened()
936 Returns true if the object currently refers to a opened file/buffer.
938 autoflush
940 my $prev = $z->autoflush()
941 my $prev = $z->autoflush(EXPR)
942 If the $z object is associated with a file or a filehandle, this method
944 returns the current autoflush setting for the underlying filehandle. If
945 "EXPR" is present, and is non-zero, it will enable flushing after every
946 write/print operation.
947 If $z is associated with a buffer, this method has no effect and always
949 returns "undef".
950 Note that the special variable $| cannot be used to set or retrieve the
952 autoflush setting.
953 input_line_number
955 $z->input_line_number()
956 $z->input_line_number(EXPR)
957 This method always returns "undef" when compressing.
959 fileno
961 $z->fileno()
962 fileno($z)
963 If the $z object is associated with a file or a filehandle, "fileno"
965 will return the underlying file descriptor. Once the "close" method is
966 called "fileno" will return "undef".
967 If the $z object is associated with a buffer, this method will return
969 "undef".
970 close
972 $z->close() ;
973 close $z ;
974 Flushes any pending compressed data and then closes the output
976 file/buffer.
977 For most versions of Perl this method will be automatically invoked if
979 the IO::Compress::Zip object is destroyed (either explicitly or by the
980 variable with the reference to the object going out of scope). The
981 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
982 cases, the "close" method will be called automatically, but not until
983 global destruction of all live objects when the program is terminating.
984 Therefore, if you want your scripts to be able to run on all versions
986 of Perl, you should call "close" explicitly and not rely on automatic
987 closing.
988 Returns true on success, otherwise 0.
990 If the "AutoClose" option has been enabled when the IO::Compress::Zip
992 object was created, and the object is associated with a file, the
993 underlying file will also be closed.
994 newStream([OPTS])
996 Usage is
997 $z->newStream( [OPTS] )
999 Closes the current compressed data stream and starts a new one.
1001 OPTS consists of any of the options that are available when creating
1003 the $z object.
1004 See the "Constructor Options" section for more details.
1006 deflateParams
1008 Usage is
1009 $z->deflateParams
1011 TODO
1013
1015 A number of symbolic constants are required by some methods in
1016 "IO::Compress::Zip". None are imported by default.
1017 :all Imports "zip", $ZipError and all symbolic constants that can be
1019 used by "IO::Compress::Zip". Same as doing this
1020 use IO::Compress::Zip qw(zip $ZipError :constants) ;
1022 :constants
1024 Import all symbolic constants. Same as doing this
1025 use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
1027 :flush
1029 These symbolic constants are used by the "flush" method.
1030 Z_NO_FLUSH
1032 Z_PARTIAL_FLUSH
1033 Z_SYNC_FLUSH
1034 Z_FULL_FLUSH
1035 Z_FINISH
1036 Z_BLOCK
1037 :level
1039 These symbolic constants are used by the "Level" option in the
1040 constructor.
1041 Z_NO_COMPRESSION
1043 Z_BEST_SPEED
1044 Z_BEST_COMPRESSION
1045 Z_DEFAULT_COMPRESSION
1046 :strategy
1048 These symbolic constants are used by the "Strategy" option in the
1049 constructor.
1050 Z_FILTERED
1052 Z_HUFFMAN_ONLY
1053 Z_RLE
1054 Z_FIXED
1055 Z_DEFAULT_STRATEGY
1056 :zip_method
1058 These symbolic constants are used by the "Method" option in the
1059 constructor.
1060 ZIP_CM_STORE
1062 ZIP_CM_DEFLATE
1063 ZIP_CM_BZIP2
1064
1066 Apache::GZip Revisited
1067 See IO::Compress::FAQ
1068 Working with Net::FTP
1070 See IO::Compress::FAQ
1071
1073 General feedback/questions/bug reports should be sent to
1074 <https://github.com/pmqs/IO-Compress/issues> (preferred) or
1075 <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
1076
1078 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
1079 IO::Compress::Deflate, IO::Uncompress::Inflate,
1080 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
1081 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma,
1082 IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz,
1083 IO::Compress::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop,
1084 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
1085 IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate,
1086 IO::Uncompress::AnyUncompress
1087 IO::Compress::FAQ
1089 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
1091 For RFC 1950, 1951 and 1952 see
1093 <http://www.faqs.org/rfcs/rfc1950.html>,
1094 <http://www.faqs.org/rfcs/rfc1951.html> and
1095 <http://www.faqs.org/rfcs/rfc1952.html>
1096 The zlib compression library was written by Jean-loup Gailly
1098 "gzip@prep.ai.mit.edu" and Mark Adler "madler@alumni.caltech.edu".
1099 The primary site for the zlib compression library is
1101 <http://www.zlib.org>.
1102 The primary site for gzip is <http://www.gzip.org>.
1104
1106 This module was written by Paul Marquess, "pmqs@cpan.org".
1107
1109 See the Changes file.
1110
1112 Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
1113 This program is free software; you can redistribute it and/or modify it
1115 under the same terms as Perl itself.
1116perl v5.30.1 2020-01-30 IO::Compress::Zip(3)