IO::Compress::Zip(3pm)

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 = new IO::Compress::Zip $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 = new IO::File "<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 = new IO::Compress::Zip $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 are supported are: Store (no compression at
747            all), Deflate, Bzip2, Xz and Lzma.
748
749            The symbols, ZIP_CM_STORE, ZIP_CM_DEFLATE, ZIP_CM_BZIP2, ZIP_CM_XZ
750            and ZIP_CM_LZMA are used to select the compression method.
751
752            These constants are not imported by "IO::Compress::Zip" by
753            default.
754
755                use IO::Compress::Zip qw(:zip_method);
756                use IO::Compress::Zip qw(:constants);
757                use IO::Compress::Zip qw(:all);
758
759            Note that to create Bzip2 content, the module
760            "IO::Compress::Bzip2" must be installed. A fatal error will be
761            thrown if you attempt to create Bzip2 content when
762            "IO::Compress::Bzip2" is not available.
763
764            Note that to create Lzma content, the module "IO::Compress::Lzma"
765            must be installed. A fatal error will be thrown if you attempt to
766            create Lzma content when "IO::Compress::Lzma" is not available.
767
768            Note that to create Xz content, the module "IO::Compress::Xz" must
769            be installed. A fatal error will be thrown if you attempt to
770            create Xz content when "IO::Compress::Xz" is not available.
771
772            The default method is ZIP_CM_DEFLATE.
773
774       "TextFlag => 0|1"
775            This parameter controls the setting of a bit in the zip central
776            header. It is used to signal that the data stored in the zip
777            file/buffer is probably text.
778
779            In one-shot mode this flag will be set to true if the Perl "-T"
780            operator thinks the file contains text.
781
782            The default is 0.
783
784       "ExtraFieldLocal => $data"
785       "ExtraFieldCentral => $data"
786            The "ExtraFieldLocal" option is used to store additional metadata
787            in the local header for the zip file/buffer. The
788            "ExtraFieldCentral" does the same for the matching central header.
789
790            An extra field consists of zero or more subfields. Each subfield
791            consists of a two byte header followed by the subfield data.
792
793            The list of subfields can be supplied in any of the following
794            formats
795
796                ExtraFieldLocal => [$id1, $data1,
797                                    $id2, $data2,
798                                     ...
799                                   ]
800
801                ExtraFieldLocal => [ [$id1 => $data1],
802                                     [$id2 => $data2],
803                                     ...
804                                   ]
805
806                ExtraFieldLocal => { $id1 => $data1,
807                                     $id2 => $data2,
808                                     ...
809                                   }
810
811            Where $id1, $id2 are two byte subfield ID's.
812
813            If you use the hash syntax, you have no control over the order in
814            which the ExtraSubFields are stored, plus you cannot have
815            SubFields with duplicate ID.
816
817            Alternatively the list of subfields can by supplied as a scalar,
818            thus
819
820                ExtraField => $rawdata
821
822            In this case "IO::Compress::Zip" will check that $rawdata consists
823            of zero or more conformant sub-fields.
824
825            The Extended Time field (ID "UT"), set using the "exTime" option,
826            and the Unix2 extra field (ID "Ux), set using the "exUnix2"
827            option, are examples of extra fields.
828
829            If the "Minimal" option is set to true, this option will be
830            ignored.
831
832            The maximum size of an extra field 65535 bytes.
833
834       "Strict => 0|1"
835            This is a placeholder option.
836
837   Examples
838       TODO
839

Methods

841   print
842       Usage is
843
844           $z->print($data)
845           print $z $data
846
847       Compresses and outputs the contents of the $data parameter. This has
848       the same behaviour as the "print" built-in.
849
850       Returns true if successful.
851
852   printf
853       Usage is
854
855           $z->printf($format, $data)
856           printf $z $format, $data
857
858       Compresses and outputs the contents of the $data parameter.
859
860       Returns true if successful.
861
862   syswrite
863       Usage is
864
865           $z->syswrite $data
866           $z->syswrite $data, $length
867           $z->syswrite $data, $length, $offset
868
869       Compresses and outputs the contents of the $data parameter.
870
871       Returns the number of uncompressed bytes written, or "undef" if
872       unsuccessful.
873
874   write
875       Usage is
876
877           $z->write $data
878           $z->write $data, $length
879           $z->write $data, $length, $offset
880
881       Compresses and outputs the contents of the $data parameter.
882
883       Returns the number of uncompressed bytes written, or "undef" if
884       unsuccessful.
885
886   flush
887       Usage is
888
889           $z->flush;
890           $z->flush($flush_type);
891
892       Flushes any pending compressed data to the output file/buffer.
893
894       This method takes an optional parameter, $flush_type, that controls how
895       the flushing will be carried out. By default the $flush_type used is
896       "Z_FINISH". Other valid values for $flush_type are "Z_NO_FLUSH",
897       "Z_SYNC_FLUSH", "Z_FULL_FLUSH" and "Z_BLOCK". It is strongly
898       recommended that you only set the "flush_type" parameter if you fully
899       understand the implications of what it does - overuse of "flush" can
900       seriously degrade the level of compression achieved. See the "zlib"
901       documentation for details.
902
903       Returns true on success.
904
905   tell
906       Usage is
907
908           $z->tell()
909           tell $z
910
911       Returns the uncompressed file offset.
912
913   eof
914       Usage is
915
916           $z->eof();
917           eof($z);
918
919       Returns true if the "close" method has been called.
920
921   seek
922           $z->seek($position, $whence);
923           seek($z, $position, $whence);
924
925       Provides a sub-set of the "seek" functionality, with the restriction
926       that it is only legal to seek forward in the output file/buffer.  It is
927       a fatal error to attempt to seek backward.
928
929       Empty parts of the file/buffer will have NULL (0x00) bytes written to
930       them.
931
932       The $whence parameter takes one the usual values, namely SEEK_SET,
933       SEEK_CUR or SEEK_END.
934
935       Returns 1 on success, 0 on failure.
936
937   binmode
938       Usage is
939
940           $z->binmode
941           binmode $z ;
942
943       This is a noop provided for completeness.
944
945   opened
946           $z->opened()
947
948       Returns true if the object currently refers to a opened file/buffer.
949
950   autoflush
951           my $prev = $z->autoflush()
952           my $prev = $z->autoflush(EXPR)
953
954       If the $z object is associated with a file or a filehandle, this method
955       returns the current autoflush setting for the underlying filehandle. If
956       "EXPR" is present, and is non-zero, it will enable flushing after every
957       write/print operation.
958
959       If $z is associated with a buffer, this method has no effect and always
960       returns "undef".
961
962       Note that the special variable $| cannot be used to set or retrieve the
963       autoflush setting.
964
965   input_line_number
966           $z->input_line_number()
967           $z->input_line_number(EXPR)
968
969       This method always returns "undef" when compressing.
970
971   fileno
972           $z->fileno()
973           fileno($z)
974
975       If the $z object is associated with a file or a filehandle, "fileno"
976       will return the underlying file descriptor. Once the "close" method is
977       called "fileno" will return "undef".
978
979       If the $z object is associated with a buffer, this method will return
980       "undef".
981
982   close
983           $z->close() ;
984           close $z ;
985
986       Flushes any pending compressed data and then closes the output
987       file/buffer.
988
989       For most versions of Perl this method will be automatically invoked if
990       the IO::Compress::Zip object is destroyed (either explicitly or by the
991       variable with the reference to the object going out of scope). The
992       exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
993       cases, the "close" method will be called automatically, but not until
994       global destruction of all live objects when the program is terminating.
995
996       Therefore, if you want your scripts to be able to run on all versions
997       of Perl, you should call "close" explicitly and not rely on automatic
998       closing.
999
1000       Returns true on success, otherwise 0.
1001
1002       If the "AutoClose" option has been enabled when the IO::Compress::Zip
1003       object was created, and the object is associated with a file, the
1004       underlying file will also be closed.
1005
1006   newStream([OPTS])
1007       Usage is
1008
1009           $z->newStream( [OPTS] )
1010
1011       Closes the current compressed data stream and starts a new one.
1012
1013       OPTS consists of any of the options that are available when creating
1014       the $z object.
1015
1016       See the "Constructor Options" section for more details.
1017
1018   deflateParams
1019       Usage is
1020
1021           $z->deflateParams
1022
1023       TODO
1024

Importing

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

EXAMPLES

1077   Apache::GZip Revisited
1078       See IO::Compress::FAQ
1079
1080   Working with Net::FTP
1081       See IO::Compress::FAQ
1082

SUPPORT

1084       General feedback/questions/bug reports should be sent to
1085       <https://github.com/pmqs/IO-Compress/issues> (preferred) or
1086       <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
1087

AUTHOR

1117       This module was written by Paul Marquess, "pmqs@cpan.org".
1118

MODIFICATION HISTORY

1120       See the Changes file.
1121

COPYRIGHT AND LICENSE

1123       Copyright (c) 2005-2020 Paul Marquess. All rights reserved.
1124
1125       This program is free software; you can redistribute it and/or modify it
1126       under the same terms as Perl itself.
1127
1128
1129
1130perl v5.32.0                      2020-08-01              IO::Compress::Zip(3)