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 = 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 corresponds to a filename
139       from the filesystem, a number of zip file header fields will be
140       populated by default using the following attributes from the input file
141
142       •    the full filename contained in $input_filename_or_reference
143
144       •    the file protection attributes
145
146       •    the UID/GID for the file
147
148       •    the file timestamps
149
150       If you do not want to use these defaults they can be overridden by
151       explicitly setting one, or more, of the "Name", "Time", "TextFlag",
152       "ExtAttr", "exUnixN" and "exTime" options or by setting the "Minimal"
153       parameter.
154
155       The $output_filename_or_reference parameter
156
157       The parameter $output_filename_or_reference is used to control the
158       destination of the compressed data. This parameter can take one of
159       these forms.
160
161       A filename
162            If the $output_filename_or_reference parameter is a simple scalar,
163            it is assumed to be a filename.  This file will be opened for
164            writing and the compressed data will be written to it.
165
166       A filehandle
167            If the $output_filename_or_reference parameter is a filehandle,
168            the compressed data will be written to it.  The string '-' can be
169            used as an alias for standard output.
170
171       A scalar reference
172            If $output_filename_or_reference is a scalar reference, the
173            compressed data will be stored in $$output_filename_or_reference.
174
175       An Array Reference
176            If $output_filename_or_reference is an array reference, the
177            compressed data will be pushed onto the array.
178
179       An Output FileGlob
180            If $output_filename_or_reference is a string that is delimited by
181            the characters "<" and ">" "zip" will assume that it is an output
182            fileglob string. The output is the list of files that match the
183            fileglob.
184
185            When $output_filename_or_reference is an fileglob string,
186            $input_filename_or_reference must also be a fileglob string.
187            Anything else is an error.
188
189            See File::GlobMapper for more details.
190
191       If the $output_filename_or_reference parameter is any other type,
192       "undef" will be returned.
193
194   Notes
195       When $input_filename_or_reference maps to multiple files/buffers and
196       $output_filename_or_reference is a single file/buffer the input
197       files/buffers will each be stored in $output_filename_or_reference as a
198       distinct entry.
199
200   Optional Parameters
201       The optional parameters for the one-shot function "zip" are (for the
202       most part) identical to those used with the OO interface defined in the
203       "Constructor Options" section. The exceptions are listed below
204
205       "AutoClose => 0|1"
206            This option applies to any input or output data streams to "zip"
207            that are filehandles.
208
209            If "AutoClose" is specified, and the value is true, it will result
210            in all input and/or output filehandles being closed once "zip" has
211            completed.
212
213            This parameter defaults to 0.
214
215       "BinModeIn => 0|1"
216            This option is now a no-op. All files will be read in binmode.
217
218       "Append => 0|1"
219            The behaviour of this option is dependent on the type of output
220            data stream.
221
222            •    A Buffer
223
224                 If "Append" is enabled, all compressed data will be append to
225                 the end of the output buffer. Otherwise the output buffer
226                 will be cleared before any compressed data is written to it.
227
228            •    A Filename
229
230                 If "Append" is enabled, the file will be opened in append
231                 mode. Otherwise the contents of the file, if any, will be
232                 truncated before any compressed data is written to it.
233
234            •    A Filehandle
235
236                 If "Append" is enabled, the filehandle will be positioned to
237                 the end of the file via a call to "seek" before any
238                 compressed data is written to it.  Otherwise the file pointer
239                 will not be moved.
240
241            When "Append" is specified, and set to true, it will append all
242            compressed data to the output data stream.
243
244            So when the output is a filehandle it will carry out a seek to the
245            eof before writing any compressed data. If the output is a
246            filename, it will be opened for appending. If the output is a
247            buffer, all compressed data will be appended to the existing
248            buffer.
249
250            Conversely when "Append" is not specified, or it is present and is
251            set to false, it will operate as follows.
252
253            When the output is a filename, it will truncate the contents of
254            the file before writing any compressed data. If the output is a
255            filehandle its position will not be changed. If the output is a
256            buffer, it will be wiped before any compressed data is output.
257
258            Defaults to 0.
259
260   Examples
261       Here are a few example that show the capabilities of the module.
262
263       Streaming
264
265       This very simple command line example demonstrates the streaming
266       capabilities of the module.  The code reads data from STDIN, compresses
267       it, and writes the compressed data to STDOUT.
268
269           $ echo hello world | perl -MIO::Compress::Zip=zip -e 'zip \*STDIN => \*STDOUT' >output.zip
270
271       The special filename "-" can be used as a standin for both "\*STDIN"
272       and "\*STDOUT", so the above can be rewritten as
273
274           $ echo hello world | perl -MIO::Compress::Zip=zip -e 'zip "-" => "-"' >output.zip
275
276       One problem with creating a zip archive directly from STDIN can be
277       demonstrated by looking at the contents of the zip file, output.zip,
278       that we have just created.
279
280           $ unzip -l output.zip
281           Archive:  output.zip
282           Length      Date    Time    Name
283           ---------  ---------- -----   ----
284               12  2019-08-16 22:21
285           ---------                     -------
286               12                     1 file
287
288       The archive member (filename) used is the empty string.
289
290       If that doesn't suit your needs, you can explicitly set the filename
291       used in the zip archive by specifying the Name option, like so
292
293           echo hello world | perl -MIO::Compress::Zip=zip -e 'zip "-" => "-", Name => "hello.txt"' >output.zip
294
295       Now the contents of the zip file looks like this
296
297           $ unzip -l output.zip
298           Archive:  output.zip
299           Length      Date    Time    Name
300           ---------  ---------- -----   ----
301               12  2019-08-16 22:22   hello.txt
302           ---------                     -------
303               12                     1 file
304
305       Compressing a file from the filesystem
306
307       To read the contents of the file "file1.txt" and write the compressed
308       data to the file "file1.txt.zip".
309
310           use strict ;
311           use warnings ;
312           use IO::Compress::Zip qw(zip $ZipError) ;
313
314           my $input = "file1.txt";
315           zip $input => "$input.zip"
316               or die "zip failed: $ZipError\n";
317
318       Reading from a Filehandle and writing to an in-memory buffer
319
320       To read from an existing Perl filehandle, $input, and write the
321       compressed data to a buffer, $buffer.
322
323           use strict ;
324           use warnings ;
325           use IO::Compress::Zip qw(zip $ZipError) ;
326           use IO::File ;
327
328           my $input = IO::File->new( "<file1.txt" )
329               or die "Cannot open 'file1.txt': $!\n" ;
330           my $buffer ;
331           zip $input => \$buffer
332               or die "zip failed: $ZipError\n";
333
334       Compressing multiple files
335
336       To create a zip file, "output.zip", that contains the compressed
337       contents of the files "alpha.txt" and "beta.txt"
338
339           use strict ;
340           use warnings ;
341           use IO::Compress::Zip qw(zip $ZipError) ;
342
343           zip [ 'alpha.txt', 'beta.txt' ] => 'output.zip'
344               or die "zip failed: $ZipError\n";
345
346       Alternatively, rather than having to explicitly name each of the files
347       that you want to compress, you could use a fileglob to select all the
348       "txt" files in the current directory, as follows
349
350           use strict ;
351           use warnings ;
352           use IO::Compress::Zip qw(zip $ZipError) ;
353
354           my @files = <*.txt>;
355           zip \@files => 'output.zip'
356               or die "zip failed: $ZipError\n";
357
358       or more succinctly
359
360           zip [ <*.txt> ] => 'output.zip'
361               or die "zip failed: $ZipError\n";
362

OO Interface

364   Constructor
365       The format of the constructor for "IO::Compress::Zip" is shown below
366
367           my $z = IO::Compress::Zip->new( $output [,OPTS] )
368               or die "IO::Compress::Zip failed: $ZipError\n";
369
370       It returns an "IO::Compress::Zip" object on success and undef on
371       failure.  The variable $ZipError will contain an error message on
372       failure.
373
374       If you are running Perl 5.005 or better the object, $z, returned from
375       IO::Compress::Zip can be used exactly like an IO::File filehandle.
376       This means that all normal output file operations can be carried out
377       with $z.  For example, to write to a compressed file/buffer you can use
378       either of these forms
379
380           $z->print("hello world\n");
381           print $z "hello world\n";
382
383       The mandatory parameter $output is used to control the destination of
384       the compressed data. This parameter can take one of these forms.
385
386       A filename
387            If the $output parameter is a simple scalar, it is assumed to be a
388            filename. This file will be opened for writing and the compressed
389            data will be written to it.
390
391       A filehandle
392            If the $output parameter is a filehandle, the compressed data will
393            be written to it.  The string '-' can be used as an alias for
394            standard output.
395
396       A scalar reference
397            If $output is a scalar reference, the compressed data will be
398            stored in $$output.
399
400       If the $output parameter is any other type, "IO::Compress::Zip"::new
401       will return undef.
402
403   Constructor Options
404       "OPTS" is any combination of zero or more the following options:
405
406       "AutoClose => 0|1"
407            This option is only valid when the $output parameter is a
408            filehandle. If specified, and the value is true, it will result in
409            the $output being closed once either the "close" method is called
410            or the "IO::Compress::Zip" object is destroyed.
411
412            This parameter defaults to 0.
413
414       "Append => 0|1"
415            Opens $output in append mode.
416
417            The behaviour of this option is dependent on the type of $output.
418
419            •    A Buffer
420
421                 If $output is a buffer and "Append" is enabled, all
422                 compressed data will be append to the end of $output.
423                 Otherwise $output will be cleared before any data is written
424                 to it.
425
426            •    A Filename
427
428                 If $output is a filename and "Append" is enabled, the file
429                 will be opened in append mode. Otherwise the contents of the
430                 file, if any, will be truncated before any compressed data is
431                 written to it.
432
433            •    A Filehandle
434
435                 If $output is a filehandle, the file pointer will be
436                 positioned to the end of the file via a call to "seek" before
437                 any compressed data is written to it.  Otherwise the file
438                 pointer will not be moved.
439
440            This parameter defaults to 0.
441
442       File Naming Options
443
444       A quick bit of zip file terminology -- A zip archive consists of one or
445       more archive members, where each member has an associated filename,
446       known as the archive member name.
447
448       The options listed in this section control how the archive member name
449       (or filename) is stored the zip archive.
450
451       "Name => $string"
452            This option is used to explicitly set the archive member name in
453            the zip archive to $string.  Most of the time you don't need to
454            make use of this option.  By default when adding a filename to the
455            zip archive, the archive member name will match the filename.
456
457            You should only need to use this option if you want the archive
458            member name to be different from the uncompressed filename or when
459            the input is a filehandle or a buffer.
460
461            The default behaviour for what archive member name is used when
462            the "Name" option is not specified depends on the form of the
463            $input parameter:
464
465            •    If the $input parameter is a filename, the value of $input
466                 will be used for the archive member name .
467
468            •    If the $input parameter is not a filename, the archive member
469                 name will be an empty string.
470
471            Note that both the "CanonicalName" and "FilterName" options can
472            modify the value used for the archive member name.
473
474            Also note that you should set the "Efs" option to true if you are
475            working with UTF8 filenames.
476
477       "CanonicalName => 0|1"
478            This option controls whether the archive member name is normalized
479            into Unix format before being written to the zip file.
480
481            It is recommended that you enable this option unless you really
482            need to create a non-standard Zip file.
483
484            This is what APPNOTE.TXT has to say on what should be stored in
485            the zip filename header field.
486
487                The name of the file, with optional relative path.
488                The path stored should not contain a drive or
489                device letter, or a leading slash.  All slashes
490                should be forward slashes '/' as opposed to
491                backwards slashes '\' for compatibility with Amiga
492                and UNIX file systems etc.
493
494            This option defaults to false.
495
496       "FilterName => sub { ... }"
497            This option allow the archive member name to be modified before it
498            is written to the zip file.
499
500            This option takes a parameter that must be a reference to a sub.
501            On entry to the sub the $_ variable will contain the name to be
502            filtered. If no filename is available $_ will contain an empty
503            string.
504
505            The value of $_ when the sub returns will be  used as the archive
506            member name.
507
508            Note that if "CanonicalName" is enabled, a normalized filename
509            will be passed to the sub.
510
511            If you use "FilterName" to modify the filename, it is your
512            responsibility to keep the filename in Unix format.
513
514            Although this option can be used with the OO interface, it is of
515            most use with the one-shot interface. For example, the code below
516            shows how "FilterName" can be used to remove the path component
517            from a series of filenames before they are stored in $zipfile.
518
519                sub compressTxtFiles
520                {
521                    my $zipfile = shift ;
522                    my $dir     = shift ;
523
524                    zip [ <$dir/*.txt> ] => $zipfile,
525                        FilterName => sub { s[^$dir/][] } ;
526                }
527
528       "Efs => 0|1"
529            This option controls setting of the "Language Encoding Flag" (EFS)
530            in the zip archive. When set, the filename and comment fields for
531            the zip archive MUST be valid UTF-8.
532
533            If the string used for the filename and/or comment is not valid
534            UTF-8 when this option is true, the script will die with a "wide
535            character" error.
536
537            Note that this option only works with Perl 5.8.4 or better.
538
539            This option defaults to false.
540
541       Overall Zip Archive Structure
542
543       "Minimal => 1|0"
544            If specified, this option will disable the creation of all extra
545            fields in the zip local and central headers. So the "exTime",
546            "exUnix2", "exUnixN", "ExtraFieldLocal" and "ExtraFieldCentral"
547            options will be ignored.
548
549            This parameter defaults to 0.
550
551       "Stream => 0|1"
552            This option controls whether the zip file/buffer output is created
553            in streaming mode.
554
555            Note that when outputting to a file with streaming mode disabled
556            ("Stream" is 0), the output file must be seekable.
557
558            The default is 1.
559
560       "Zip64 => 0|1"
561            Create a Zip64 zip file/buffer. This option is used if you want to
562            store files larger than 4 Gig or store more than 64K files in a
563            single zip archive.
564
565            "Zip64" will be automatically set, as needed, if working with the
566            one-shot interface when the input is either a filename or a scalar
567            reference.
568
569            If you intend to manipulate the Zip64 zip files created with this
570            module using an external zip/unzip, make sure that it supports
571            Zip64.
572
573            In particular, if you are using Info-Zip you need to have zip
574            version 3.x or better to update a Zip64 archive and unzip version
575            6.x to read a zip64 archive.
576
577            The default is 0.
578
579       Deflate Compression Options
580
581       -Level
582            Defines the compression level used by zlib. The value should
583            either be a number between 0 and 9 (0 means no compression and 9
584            is maximum compression), or one of the symbolic constants defined
585            below.
586
587               Z_NO_COMPRESSION
588               Z_BEST_SPEED
589               Z_BEST_COMPRESSION
590               Z_DEFAULT_COMPRESSION
591
592            The default is Z_DEFAULT_COMPRESSION.
593
594            Note, these constants are not imported by "IO::Compress::Zip" by
595            default.
596
597                use IO::Compress::Zip qw(:strategy);
598                use IO::Compress::Zip qw(:constants);
599                use IO::Compress::Zip qw(:all);
600
601       -Strategy
602            Defines the strategy used to tune the compression. Use one of the
603            symbolic constants defined below.
604
605               Z_FILTERED
606               Z_HUFFMAN_ONLY
607               Z_RLE
608               Z_FIXED
609               Z_DEFAULT_STRATEGY
610
611            The default is Z_DEFAULT_STRATEGY.
612
613       Bzip2 Compression Options
614
615       "BlockSize100K => number"
616            Specify the number of 100K blocks bzip2 uses during compression.
617
618            Valid values are from 1 to 9, where 9 is best compression.
619
620            This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
621            ignored otherwise.
622
623            The default is 1.
624
625       "WorkFactor => number"
626            Specifies how much effort bzip2 should take before resorting to a
627            slower fallback compression algorithm.
628
629            Valid values range from 0 to 250, where 0 means use the default
630            value 30.
631
632            This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
633            ignored otherwise.
634
635            The default is 0.
636
637       Lzma and Xz Compression Options
638
639       "Preset => number"
640            Used to choose the LZMA compression preset.
641
642            Valid values are 0-9 and "LZMA_PRESET_DEFAULT".
643
644            0 is the fastest compression with the lowest memory usage and the
645            lowest compression.
646
647            9 is the slowest compression with the highest memory usage but
648            with the best compression.
649
650            This option is only valid if the "Method" is ZIP_CM_LZMA. It is
651            ignored otherwise.
652
653            Defaults to "LZMA_PRESET_DEFAULT" (6).
654
655       "Extreme => 0|1"
656            Makes LZMA compression a lot slower, but a small compression gain.
657
658            This option is only valid if the "Method" is ZIP_CM_LZMA. It is
659            ignored otherwise.
660
661            Defaults to 0.
662
663       Other Options
664
665       "Time => $number"
666            Sets the last modified time field in the zip header to $number.
667
668            This field defaults to the time the "IO::Compress::Zip" object was
669            created if this option is not specified and the $input parameter
670            is not a filename.
671
672       "ExtAttr => $attr"
673            This option controls the "external file attributes" field in the
674            central header of the zip file. This is a 4 byte field.
675
676            If you are running a Unix derivative this value defaults to
677
678                0100644 << 16
679
680            This should allow read/write access to any files that are
681            extracted from the zip file/buffer`.
682
683            For all other systems it defaults to 0.
684
685       "exTime => [$atime, $mtime, $ctime]"
686            This option expects an array reference with exactly three
687            elements: $atime, "mtime" and $ctime. These correspond to the last
688            access time, last modification time and creation time
689            respectively.
690
691            It uses these values to set the extended timestamp field (ID is
692            "UT") in the local zip header using the three values, $atime,
693            $mtime, $ctime. In addition it sets the extended timestamp field
694            in the central zip header using $mtime.
695
696            If any of the three values is "undef" that time value will not be
697            used.  So, for example, to set only the $mtime you would use this
698
699                exTime => [undef, $mtime, undef]
700
701            If the "Minimal" option is set to true, this option will be
702            ignored.
703
704            By default no extended time field is created.
705
706       "exUnix2 => [$uid, $gid]"
707            This option expects an array reference with exactly two elements:
708            $uid and $gid. These values correspond to the numeric User ID
709            (UID) and Group ID (GID) of the owner of the files respectively.
710
711            When the "exUnix2" option is present it will trigger the creation
712            of a Unix2 extra field (ID is "Ux") in the local zip header. This
713            will be populated with $uid and $gid. An empty Unix2 extra field
714            will also be created in the central zip header.
715
716            Note - The UID & GID are stored as 16-bit integers in the "Ux"
717            field. Use "exUnixN" if your UID or GID are 32-bit.
718
719            If the "Minimal" option is set to true, this option will be
720            ignored.
721
722            By default no Unix2 extra field is created.
723
724       "exUnixN => [$uid, $gid]"
725            This option expects an array reference with exactly two elements:
726            $uid and $gid. These values correspond to the numeric User ID
727            (UID) and Group ID (GID) of the owner of the files respectively.
728
729            When the "exUnixN" option is present it will trigger the creation
730            of a UnixN extra field (ID is "ux") in both the local and central
731            zip headers.  This will be populated with $uid and $gid.  The UID
732            & GID are stored as 32-bit integers.
733
734            If the "Minimal" option is set to true, this option will be
735            ignored.
736
737            By default no UnixN extra field is created.
738
739       "Comment => $comment"
740            Stores the contents of $comment in the Central File Header of the
741            zip file.
742
743            Set the "Efs" option to true if you want to store a UTF8 comment.
744
745            By default, no comment field is written to the zip file.
746
747       "ZipComment => $comment"
748            Stores the contents of $comment in the End of Central Directory
749            record of the zip file.
750
751            By default, no comment field is written to the zip file.
752
753       "Method => $method"
754            Controls which compression method is used. At present the
755            compression methods supported are: Store (no compression at all),
756            Deflate, Bzip2, Zstd, Xz and Lzma.
757
758            The symbols ZIP_CM_STORE, ZIP_CM_DEFLATE, ZIP_CM_BZIP2,
759            ZIP_CM_ZSTD, ZIP_CM_XZ and ZIP_CM_LZMA are used to select the
760            compression method.
761
762            These constants are not imported by "IO::Compress::Zip" by
763            default.
764
765                use IO::Compress::Zip qw(:zip_method);
766                use IO::Compress::Zip qw(:constants);
767                use IO::Compress::Zip qw(:all);
768
769            Note that to create Bzip2 content, the module
770            "IO::Compress::Bzip2" must be installed. A fatal error will be
771            thrown if you attempt to create Bzip2 content when
772            "IO::Compress::Bzip2" is not available.
773
774            Note that to create Lzma content, the module "IO::Compress::Lzma"
775            must be installed. A fatal error will be thrown if you attempt to
776            create Lzma content when "IO::Compress::Lzma" is not available.
777
778            Note that to create Xz content, the module "IO::Compress::Xz" must
779            be installed. A fatal error will be thrown if you attempt to
780            create Xz content when "IO::Compress::Xz" is not available.
781
782            Note that to create Zstd content, the module "IO::Compress::Zstd"
783            must be installed. A fatal error will be thrown if you attempt to
784            create Zstd content when "IO::Compress::Zstd" is not available.
785
786            The default method is ZIP_CM_DEFLATE.
787
788       "TextFlag => 0|1"
789            This parameter controls the setting of a bit in the zip central
790            header. It is used to signal that the data stored in the zip
791            file/buffer is probably text.
792
793            In one-shot mode this flag will be set to true if the Perl "-T"
794            operator thinks the file contains text.
795
796            The default is 0.
797
798       "ExtraFieldLocal => $data"
799       "ExtraFieldCentral => $data"
800            The "ExtraFieldLocal" option is used to store additional metadata
801            in the local header for the zip file/buffer. The
802            "ExtraFieldCentral" does the same for the matching central header.
803
804            An extra field consists of zero or more subfields. Each subfield
805            consists of a two byte header followed by the subfield data.
806
807            The list of subfields can be supplied in any of the following
808            formats
809
810                ExtraFieldLocal => [$id1, $data1,
811                                    $id2, $data2,
812                                     ...
813                                   ]
814
815                ExtraFieldLocal => [ [$id1 => $data1],
816                                     [$id2 => $data2],
817                                     ...
818                                   ]
819
820                ExtraFieldLocal => { $id1 => $data1,
821                                     $id2 => $data2,
822                                     ...
823                                   }
824
825            Where $id1, $id2 are two byte subfield ID's.
826
827            If you use the hash syntax, you have no control over the order in
828            which the ExtraSubFields are stored, plus you cannot have
829            SubFields with duplicate ID.
830
831            Alternatively the list of subfields can by supplied as a scalar,
832            thus
833
834                ExtraField => $rawdata
835
836            In this case "IO::Compress::Zip" will check that $rawdata consists
837            of zero or more conformant sub-fields.
838
839            The Extended Time field (ID "UT"), set using the "exTime" option,
840            and the Unix2 extra field (ID "Ux), set using the "exUnix2"
841            option, are examples of extra fields.
842
843            If the "Minimal" option is set to true, this option will be
844            ignored.
845
846            The maximum size of an extra field 65535 bytes.
847
848       "Strict => 0|1"
849            This is a placeholder option.
850
851   Examples
852       TODO
853

Methods

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

Importing

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

EXAMPLES

1091   Apache::GZip Revisited
1092       See IO::Compress::FAQ
1093
1094   Working with Net::FTP
1095       See IO::Compress::FAQ
1096

SUPPORT

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

AUTHOR

1134       This module was written by Paul Marquess, "pmqs@cpan.org".
1135

MODIFICATION HISTORY

1137       See the Changes file.
1138

COPYRIGHT AND LICENSE

1140       Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
1141
1142       This program is free software; you can redistribute it and/or modify it
1143       under the same terms as Perl itself.
1144
1145
1146
1147perl v5.36.0                      2023-02-09              IO::Compress::Zip(3)