1IO::Compress::Zip(3)  User Contributed Perl Documentation IO::Compress::Zip(3)
2
3
4

NAME

6       IO::Compress::Zip - Write zip files/buffers
7

SYNOPSIS

9           use IO::Compress::Zip qw(zip $ZipError) ;
10
11           my $status = zip $input => $output [,OPTS]
12               or die "zip failed: $ZipError\n";
13
14           my $z = IO::Compress::Zip->new( $output [,OPTS] )
15               or die "zip failed: $ZipError\n";
16
17           $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
32           $z->deflateParams();
33
34           $z->close() ;
35
36           $ZipError ;
37
38           # IO::File mode
39
40           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

DESCRIPTION

50       This module provides a Perl interface that allows writing zip
51       compressed data to files or buffer.
52
53       The primary purpose of this module is to provide streaming write access
54       to zip files and buffers.
55
56       At present the following compression methods are supported by
57       IO::Compress::Zip
58
59       Store (0)
60       Deflate (8)
61       Bzip2 (12)
62            To write Bzip2 content, the module "IO::Uncompress::Bunzip2" must
63            be installed.
64
65       Lzma (14)
66            To write LZMA content, the module "IO::Uncompress::UnLzma" must be
67            installed.
68
69       Zstandard (93)
70            To write Zstandard content, the module "IO::Compress::Zstd" must
71            be installed.
72
73       Xz (95)
74            To write Xz content, the module "IO::Uncompress::UnXz" must be
75            installed.
76
77       For reading zip files/buffers, see the companion module
78       IO::Uncompress::Unzip.
79

Functional Interface

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
85           use IO::Compress::Zip qw(zip $ZipError) ;
86
87           zip $input_filename_or_reference => $output_filename_or_reference [,OPTS]
88               or die "zip failed: $ZipError\n";
89
90       The functional interface needs Perl5.005 or better.
91
92   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
97       The $input_filename_or_reference parameter
98
99       The parameter, $input_filename_or_reference, is used to define the
100       source of the uncompressed data.
101
102       It can take one of the following forms:
103
104       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
109       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
114       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
118       An array reference
119            If $input_filename_or_reference is an array reference, each
120            element in the array must be a filename.
121
122            The input data will be read from each file in turn.
123
124            The complete array will be walked to ensure that it only contains
125            valid filenames before any data is compressed.
126
127       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
133            See File::GlobMapper for more details.
134
135       If the $input_filename_or_reference parameter is any other type,
136       "undef" will be returned.
137
138       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
142       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
146       The $output_filename_or_reference parameter
147
148       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
152       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
157       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
162       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
166       An Array Reference
167            If $output_filename_or_reference is an array reference, the
168            compressed data will be pushed onto the array.
169
170       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
176            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
180            See File::GlobMapper for more details.
181
182       If the $output_filename_or_reference parameter is any other type,
183       "undef" will be returned.
184
185   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
191   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
196       "AutoClose => 0|1"
197            This option applies to any input or output data streams to "zip"
198            that are filehandles.
199
200            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
204            This parameter defaults to 0.
205
206       "BinModeIn => 0|1"
207            This option is now a no-op. All files will be read in binmode.
208
209       "Append => 0|1"
210            The behaviour of this option is dependent on the type of output
211            data stream.
212
213            •    A Buffer
214
215                 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
219            •    A Filename
220
221                 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
225            •    A Filehandle
226
227                 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
232            When "Append" is specified, and set to true, it will append all
233            compressed data to the output data stream.
234
235            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
241            Conversely when "Append" is not specified, or it is present and is
242            set to false, it will operate as follows.
243
244            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
249            Defaults to 0.
250
251   Examples
252       Here are a few example that show the capabilities of the module.
253
254       Streaming
255
256       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
260           $ echo hello world | perl -MIO::Compress::Zip=zip -e 'zip \*STDIN => \*STDOUT' >output.zip
261
262       The special filename "-" can be used as a standin for both "\*STDIN"
263       and "\*STDOUT", so the above can be rewritten as
264
265           $ echo hello world | perl -MIO::Compress::Zip=zip -e 'zip "-" => "-"' >output.zip
266
267       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
271           $ 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
279       The archive member (filename) used is the empty string.
280
281       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
284           echo hello world | perl -MIO::Compress::Zip=zip -e 'zip "-" => "-", Name => "hello.txt"' >output.zip
285
286       Now the contents of the zip file looks like this
287
288           $ 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
296       Compressing a file from the filesystem
297
298       To read the contents of the file "file1.txt" and write the compressed
299       data to the file "file1.txt.zip".
300
301           use strict ;
302           use warnings ;
303           use IO::Compress::Zip qw(zip $ZipError) ;
304
305           my $input = "file1.txt";
306           zip $input => "$input.zip"
307               or die "zip failed: $ZipError\n";
308
309       Reading from a Filehandle and writing to an in-memory buffer
310
311       To read from an existing Perl filehandle, $input, and write the
312       compressed data to a buffer, $buffer.
313
314           use strict ;
315           use warnings ;
316           use IO::Compress::Zip qw(zip $ZipError) ;
317           use IO::File ;
318
319           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
325       Compressing multiple files
326
327       To create a zip file, "output.zip", that contains the compressed
328       contents of the files "alpha.txt" and "beta.txt"
329
330           use strict ;
331           use warnings ;
332           use IO::Compress::Zip qw(zip $ZipError) ;
333
334           zip [ 'alpha.txt', 'beta.txt' ] => 'output.zip'
335               or die "zip failed: $ZipError\n";
336
337       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
341           use strict ;
342           use warnings ;
343           use IO::Compress::Zip qw(zip $ZipError) ;
344
345           my @files = <*.txt>;
346           zip \@files => 'output.zip'
347               or die "zip failed: $ZipError\n";
348
349       or more succinctly
350
351           zip [ <*.txt> ] => 'output.zip'
352               or die "zip failed: $ZipError\n";
353

OO Interface

355   Constructor
356       The format of the constructor for "IO::Compress::Zip" is shown below
357
358           my $z = IO::Compress::Zip->new( $output [,OPTS] )
359               or die "IO::Compress::Zip failed: $ZipError\n";
360
361       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
365       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
371           $z->print("hello world\n");
372           print $z "hello world\n";
373
374       The mandatory parameter $output is used to control the destination of
375       the compressed data. This parameter can take one of these forms.
376
377       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
382       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
387       A scalar reference
388            If $output is a scalar reference, the compressed data will be
389            stored in $$output.
390
391       If the $output parameter is any other type, "IO::Compress::Zip"::new
392       will return undef.
393
394   Constructor Options
395       "OPTS" is any combination of zero or more the following options:
396
397       "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
403            This parameter defaults to 0.
404
405       "Append => 0|1"
406            Opens $output in append mode.
407
408            The behaviour of this option is dependent on the type of $output.
409
410            •    A Buffer
411
412                 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
417            •    A Filename
418
419                 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
424            •    A Filehandle
425
426                 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
431            This parameter defaults to 0.
432
433       File Naming Options
434
435       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
439       The options listed in this section control how the archive member name
440       (or filename) is stored the zip archive.
441
442       "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
448            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
452            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
456            •    If the $input parameter is a filename, the value of $input
457                 will be used for the archive member name .
458
459            •    If the $input parameter is not a filename, the archive member
460                 name will be an empty string.
461
462            Note that both the "CanonicalName" and "FilterName" options can
463            modify the value used for the archive member name.
464
465            Also note that you should set the "Efs" option to true if you are
466            working with UTF8 filenames.
467
468       "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
472            It is recommended that you enable this option unless you really
473            need to create a non-standard Zip file.
474
475            This is what APPNOTE.TXT has to say on what should be stored in
476            the zip filename header field.
477
478                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
485            This option defaults to false.
486
487       "FilterName => sub { ... }"
488            This option allow the archive member name to be modified before it
489            is written to the zip file.
490
491            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
496            The value of $_ when the sub returns will be  used as the archive
497            member name.
498
499            Note that if "CanonicalName" is enabled, a normalized filename
500            will be passed to the sub.
501
502            If you use "FilterName" to modify the filename, it is your
503            responsibility to keep the filename in Unix format.
504
505            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
510                sub compressTxtFiles
511                {
512                    my $zipfile = shift ;
513                    my $dir     = shift ;
514
515                    zip [ <$dir/*.txt> ] => $zipfile,
516                        FilterName => sub { s[^$dir/][] } ;
517                }
518
519       "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
524            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
528            Note that this option only works with Perl 5.8.4 or better.
529
530            This option defaults to false.
531
532       Overall Zip Archive Structure
533
534       "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
540            This parameter defaults to 0.
541
542       "Stream => 0|1"
543            This option controls whether the zip file/buffer output is created
544            in streaming mode.
545
546            Note that when outputting to a file with streaming mode disabled
547            ("Stream" is 0), the output file must be seekable.
548
549            The default is 1.
550
551       "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
556            "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
560            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
564            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
568            The default is 0.
569
570       Deflate Compression Options
571
572       -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
578               Z_NO_COMPRESSION
579               Z_BEST_SPEED
580               Z_BEST_COMPRESSION
581               Z_DEFAULT_COMPRESSION
582
583            The default is Z_DEFAULT_COMPRESSION.
584
585            Note, these constants are not imported by "IO::Compress::Zip" by
586            default.
587
588                use IO::Compress::Zip qw(:strategy);
589                use IO::Compress::Zip qw(:constants);
590                use IO::Compress::Zip qw(:all);
591
592       -Strategy
593            Defines the strategy used to tune the compression. Use one of the
594            symbolic constants defined below.
595
596               Z_FILTERED
597               Z_HUFFMAN_ONLY
598               Z_RLE
599               Z_FIXED
600               Z_DEFAULT_STRATEGY
601
602            The default is Z_DEFAULT_STRATEGY.
603
604       Bzip2 Compression Options
605
606       "BlockSize100K => number"
607            Specify the number of 100K blocks bzip2 uses during compression.
608
609            Valid values are from 1 to 9, where 9 is best compression.
610
611            This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
612            ignored otherwise.
613
614            The default is 1.
615
616       "WorkFactor => number"
617            Specifies how much effort bzip2 should take before resorting to a
618            slower fallback compression algorithm.
619
620            Valid values range from 0 to 250, where 0 means use the default
621            value 30.
622
623            This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
624            ignored otherwise.
625
626            The default is 0.
627
628       Lzma and Xz Compression Options
629
630       "Preset => number"
631            Used to choose the LZMA compression preset.
632
633            Valid values are 0-9 and "LZMA_PRESET_DEFAULT".
634
635            0 is the fastest compression with the lowest memory usage and the
636            lowest compression.
637
638            9 is the slowest compression with the highest memory usage but
639            with the best compression.
640
641            This option is only valid if the "Method" is ZIP_CM_LZMA. It is
642            ignored otherwise.
643
644            Defaults to "LZMA_PRESET_DEFAULT" (6).
645
646       "Extreme => 0|1"
647            Makes LZMA compression a lot slower, but a small compression gain.
648
649            This option is only valid if the "Method" is ZIP_CM_LZMA. It is
650            ignored otherwise.
651
652            Defaults to 0.
653
654       Other Options
655
656       "Time => $number"
657            Sets the last modified time field in the zip header to $number.
658
659            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
663       "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
667            If you are running a Unix derivative this value defaults to
668
669                0100644 << 16
670
671            This should allow read/write access to any files that are
672            extracted from the zip file/buffer`.
673
674            For all other systems it defaults to 0.
675
676       "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
682            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
687            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
690                exTime => [undef, $mtime, undef]
691
692            If the "Minimal" option is set to true, this option will be
693            ignored.
694
695            By default no extended time field is created.
696
697       "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
702            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
707            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
710            If the "Minimal" option is set to true, this option will be
711            ignored.
712
713            By default no Unix2 extra field is created.
714
715       "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
720            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
725            If the "Minimal" option is set to true, this option will be
726            ignored.
727
728            By default no UnixN extra field is created.
729
730       "Comment => $comment"
731            Stores the contents of $comment in the Central File Header of the
732            zip file.
733
734            Set the "Efs" option to true if you want to store a UTF8 comment.
735
736            By default, no comment field is written to the zip file.
737
738       "ZipComment => $comment"
739            Stores the contents of $comment in the End of Central Directory
740            record of the zip file.
741
742            By default, no comment field is written to the zip file.
743
744       "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
749            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
753            These constants are not imported by "IO::Compress::Zip" by
754            default.
755
756                use IO::Compress::Zip qw(:zip_method);
757                use IO::Compress::Zip qw(:constants);
758                use IO::Compress::Zip qw(:all);
759
760            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
765            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
769            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
773            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
777            The default method is ZIP_CM_DEFLATE.
778
779       "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
784            In one-shot mode this flag will be set to true if the Perl "-T"
785            operator thinks the file contains text.
786
787            The default is 0.
788
789       "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
795            An extra field consists of zero or more subfields. Each subfield
796            consists of a two byte header followed by the subfield data.
797
798            The list of subfields can be supplied in any of the following
799            formats
800
801                ExtraFieldLocal => [$id1, $data1,
802                                    $id2, $data2,
803                                     ...
804                                   ]
805
806                ExtraFieldLocal => [ [$id1 => $data1],
807                                     [$id2 => $data2],
808                                     ...
809                                   ]
810
811                ExtraFieldLocal => { $id1 => $data1,
812                                     $id2 => $data2,
813                                     ...
814                                   }
815
816            Where $id1, $id2 are two byte subfield ID's.
817
818            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
822            Alternatively the list of subfields can by supplied as a scalar,
823            thus
824
825                ExtraField => $rawdata
826
827            In this case "IO::Compress::Zip" will check that $rawdata consists
828            of zero or more conformant sub-fields.
829
830            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
834            If the "Minimal" option is set to true, this option will be
835            ignored.
836
837            The maximum size of an extra field 65535 bytes.
838
839       "Strict => 0|1"
840            This is a placeholder option.
841
842   Examples
843       TODO
844

Methods

846   print
847       Usage is
848
849           $z->print($data)
850           print $z $data
851
852       Compresses and outputs the contents of the $data parameter. This has
853       the same behaviour as the "print" built-in.
854
855       Returns true if successful.
856
857   printf
858       Usage is
859
860           $z->printf($format, $data)
861           printf $z $format, $data
862
863       Compresses and outputs the contents of the $data parameter.
864
865       Returns true if successful.
866
867   syswrite
868       Usage is
869
870           $z->syswrite $data
871           $z->syswrite $data, $length
872           $z->syswrite $data, $length, $offset
873
874       Compresses and outputs the contents of the $data parameter.
875
876       Returns the number of uncompressed bytes written, or "undef" if
877       unsuccessful.
878
879   write
880       Usage is
881
882           $z->write $data
883           $z->write $data, $length
884           $z->write $data, $length, $offset
885
886       Compresses and outputs the contents of the $data parameter.
887
888       Returns the number of uncompressed bytes written, or "undef" if
889       unsuccessful.
890
891   flush
892       Usage is
893
894           $z->flush;
895           $z->flush($flush_type);
896
897       Flushes any pending compressed data to the output file/buffer.
898
899       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
908       Returns true on success.
909
910   tell
911       Usage is
912
913           $z->tell()
914           tell $z
915
916       Returns the uncompressed file offset.
917
918   eof
919       Usage is
920
921           $z->eof();
922           eof($z);
923
924       Returns true if the "close" method has been called.
925
926   seek
927           $z->seek($position, $whence);
928           seek($z, $position, $whence);
929
930       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
934       Empty parts of the file/buffer will have NULL (0x00) bytes written to
935       them.
936
937       The $whence parameter takes one the usual values, namely SEEK_SET,
938       SEEK_CUR or SEEK_END.
939
940       Returns 1 on success, 0 on failure.
941
942   binmode
943       Usage is
944
945           $z->binmode
946           binmode $z ;
947
948       This is a noop provided for completeness.
949
950   opened
951           $z->opened()
952
953       Returns true if the object currently refers to a opened file/buffer.
954
955   autoflush
956           my $prev = $z->autoflush()
957           my $prev = $z->autoflush(EXPR)
958
959       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
964       If $z is associated with a buffer, this method has no effect and always
965       returns "undef".
966
967       Note that the special variable $| cannot be used to set or retrieve the
968       autoflush setting.
969
970   input_line_number
971           $z->input_line_number()
972           $z->input_line_number(EXPR)
973
974       This method always returns "undef" when compressing.
975
976   fileno
977           $z->fileno()
978           fileno($z)
979
980       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
984       If the $z object is associated with a buffer, this method will return
985       "undef".
986
987   close
988           $z->close() ;
989           close $z ;
990
991       Flushes any pending compressed data and then closes the output
992       file/buffer.
993
994       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
1001       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
1005       Returns true on success, otherwise 0.
1006
1007       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
1011   newStream([OPTS])
1012       Usage is
1013
1014           $z->newStream( [OPTS] )
1015
1016       Closes the current compressed data stream and starts a new one.
1017
1018       OPTS consists of any of the options that are available when creating
1019       the $z object.
1020
1021       See the "Constructor Options" section for more details.
1022
1023   deflateParams
1024       Usage is
1025
1026           $z->deflateParams
1027
1028       TODO
1029

Importing

1031       A number of symbolic constants are required by some methods in
1032       "IO::Compress::Zip". None are imported by default.
1033
1034       :all Imports "zip", $ZipError and all symbolic constants that can be
1035            used by "IO::Compress::Zip". Same as doing this
1036
1037                use IO::Compress::Zip qw(zip $ZipError :constants) ;
1038
1039       :constants
1040            Import all symbolic constants. Same as doing this
1041
1042                use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
1043
1044       :flush
1045            These symbolic constants are used by the "flush" method.
1046
1047                Z_NO_FLUSH
1048                Z_PARTIAL_FLUSH
1049                Z_SYNC_FLUSH
1050                Z_FULL_FLUSH
1051                Z_FINISH
1052                Z_BLOCK
1053
1054       :level
1055            These symbolic constants are used by the "Level" option in the
1056            constructor.
1057
1058                Z_NO_COMPRESSION
1059                Z_BEST_SPEED
1060                Z_BEST_COMPRESSION
1061                Z_DEFAULT_COMPRESSION
1062
1063       :strategy
1064            These symbolic constants are used by the "Strategy" option in the
1065            constructor.
1066
1067                Z_FILTERED
1068                Z_HUFFMAN_ONLY
1069                Z_RLE
1070                Z_FIXED
1071                Z_DEFAULT_STRATEGY
1072
1073       :zip_method
1074            These symbolic constants are used by the "Method" option in the
1075            constructor.
1076
1077                ZIP_CM_STORE
1078                ZIP_CM_DEFLATE
1079                ZIP_CM_BZIP2
1080

EXAMPLES

1082   Apache::GZip Revisited
1083       See IO::Compress::FAQ
1084
1085   Working with Net::FTP
1086       See IO::Compress::FAQ
1087

SUPPORT

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

SEE ALSO

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
1104       IO::Compress::FAQ
1105
1106       File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
1107
1108       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
1113       The zlib compression library was written by Jean-loup Gailly
1114       "gzip@prep.ai.mit.edu" and Mark Adler "madler@alumni.caltech.edu".
1115
1116       The primary site for the zlib compression library is
1117       <http://www.zlib.org>.
1118
1119       The primary site for gzip is <http://www.gzip.org>.
1120

AUTHOR

1122       This module was written by Paul Marquess, "pmqs@cpan.org".
1123

MODIFICATION HISTORY

1125       See the Changes file.
1126
1128       Copyright (c) 2005-2021 Paul Marquess. All rights reserved.
1129
1130       This program is free software; you can redistribute it and/or modify it
1131       under the same terms as Perl itself.
1132
1133
1134
1135perl v5.32.1                      2021-03-01              IO::Compress::Zip(3)
Impressum