Debian Codegraph @

upstream/opensuse-tumbleweed/man3/IO::Compress::Zip.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "IO::Compress::Zip 3pm"
61 .TH IO::Compress::Zip 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 IO::Compress::Zip \- Write zip files/buffers
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use IO::Compress::Zip qw(zip $ZipError) ;
72 \&
73 \& my $status = zip $input => $output [,OPTS]
74 \& or die "zip failed: $ZipError\en";
75 \&
76 \& my $z = IO::Compress::Zip\->new( $output [,OPTS] )
77 \& or die "zip failed: $ZipError\en";
78 \&
79 \& $z\->print($string);
80 \& $z\->printf($format, $string);
81 \& $z\->write($string);
82 \& $z\->syswrite($string [, $length, $offset]);
83 \& $z\->flush();
84 \& $z\->tell();
85 \& $z\->eof();
86 \& $z\->seek($position, $whence);
87 \& $z\->binmode();
88 \& $z\->fileno();
89 \& $z\->opened();
90 \& $z\->autoflush();
91 \& $z\->input_line_number();
92 \& $z\->newStream( [OPTS] );
93 \&
94 \& $z\->deflateParams();
95 \&
96 \& $z\->close() ;
97 \&
98 \& $ZipError ;
99 \&
100 \& # IO::File mode
101 \&
102 \& print $z $string;
103 \& printf $z $format, $string;
104 \& tell $z
105 \& eof $z
106 \& seek $z, $position, $whence
107 \& binmode $z
108 \& fileno $z
109 \& close $z ;
110 .Ve
111 .SH DESCRIPTION
112 .IX Header "DESCRIPTION"
113 This module provides a Perl interface that allows writing zip
114 compressed data to files or buffer.
115 .PP
116 The primary purpose of this module is to provide streaming write access to
117 zip files and buffers.
118 .PP
119 At present the following compression methods are supported by IO::Compress::Zip
120 .IP "Store (0)" 5
121 .IX Item "Store (0)"
122 .PD 0
123 .IP "Deflate (8)" 5
124 .IX Item "Deflate (8)"
125 .IP "Bzip2 (12)" 5
126 .IX Item "Bzip2 (12)"
127 .PD
128 To write Bzip2 content, the module \f(CW\*(C`IO::Uncompress::Bunzip2\*(C'\fR must
129 be installed.
130 .IP "Lzma (14)" 5
131 .IX Item "Lzma (14)"
132 To write LZMA content, the module \f(CW\*(C`IO::Uncompress::UnLzma\*(C'\fR must
133 be installed.
134 .IP "Zstandard (93)" 5
135 .IX Item "Zstandard (93)"
136 To write Zstandard content, the module \f(CW\*(C`IO::Compress::Zstd\*(C'\fR must
137 be installed.
138 .IP "Xz (95)" 5
139 .IX Item "Xz (95)"
140 To write Xz content, the module \f(CW\*(C`IO::Uncompress::UnXz\*(C'\fR must
141 be installed.
142 .PP
143 For reading zip files/buffers, see the companion module
144 IO::Uncompress::Unzip.
145 .SH "Functional Interface"
146 .IX Header "Functional Interface"
147 A top\-level function, \f(CW\*(C`zip\*(C'\fR, is provided to carry out
148 "one\-shot" compression between buffers and/or files. For finer
149 control over the compression process, see the "OO Interface"
150 section.
151 .PP
152 .Vb 1
153 \& use IO::Compress::Zip qw(zip $ZipError) ;
154 \&
155 \& zip $input_filename_or_reference => $output_filename_or_reference [,OPTS]
156 \& or die "zip failed: $ZipError\en";
157 .Ve
158 .PP
159 The functional interface needs Perl5.005 or better.
160 .ie n .SS "zip $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
161 .el .SS "zip \f(CW$input_filename_or_reference\fP => \f(CW$output_filename_or_reference\fP [, OPTS]"
162 .IX Subsection "zip $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
163 \&\f(CW\*(C`zip\*(C'\fR expects at least two parameters,
164 \&\f(CW$input_filename_or_reference\fR and \f(CW$output_filename_or_reference\fR
165 and zero or more optional parameters (see "Optional Parameters")
166 .PP
167 \fIThe \fR\f(CI$input_filename_or_reference\fR\fI parameter\fR
168 .IX Subsection "The $input_filename_or_reference parameter"
169 .PP
170 The parameter, \f(CW$input_filename_or_reference\fR, is used to define the
171 source of the uncompressed data.
172 .PP
173 It can take one of the following forms:
174 .IP "A filename" 5
175 .IX Item "A filename"
176 If the \f(CW$input_filename_or_reference\fR parameter is a simple scalar, it is
177 assumed to be a filename. This file will be opened for reading and the
178 input data will be read from it.
179 .IP "A filehandle" 5
180 .IX Item "A filehandle"
181 If the \f(CW$input_filename_or_reference\fR parameter is a filehandle, the input
182 data will be read from it. The string \*(Aq\-\*(Aq can be used as an alias for
183 standard input.
184 .IP "A scalar reference" 5
185 .IX Item "A scalar reference"
186 If \f(CW$input_filename_or_reference\fR is a scalar reference, the input data
187 will be read from \f(CW$$input_filename_or_reference\fR.
188 .IP "An array reference" 5
189 .IX Item "An array reference"
190 If \f(CW$input_filename_or_reference\fR is an array reference, each element in
191 the array must be a filename.
192 .Sp
193 The input data will be read from each file in turn.
194 .Sp
195 The complete array will be walked to ensure that it only
196 contains valid filenames before any data is compressed.
197 .IP "An Input FileGlob string" 5
198 .IX Item "An Input FileGlob string"
199 If \f(CW$input_filename_or_reference\fR is a string that is delimited by the
200 characters "<" and ">" \f(CW\*(C`zip\*(C'\fR will assume that it is an
201 \&\fIinput fileglob string\fR. The input is the list of files that match the
202 fileglob.
203 .Sp
204 See File::GlobMapper for more details.
205 .PP
206 If the \f(CW$input_filename_or_reference\fR parameter is any other type,
207 \&\f(CW\*(C`undef\*(C'\fR will be returned.
208 .PP
209 In addition, if \f(CW$input_filename_or_reference\fR corresponds to a filename
210 from the filesystem, a number of zip file header fields will be populated by default
211 using the following attributes from the input file
212 .IP \(bu 5
213 the full filename contained in \f(CW$input_filename_or_reference\fR
214 .IP \(bu 5
215 the file protection attributes
216 .IP \(bu 5
217 the UID/GID for the file
218 .IP \(bu 5
219 the file timestamps
220 .PP
221 If you do not want to use these defaults they can be overridden by
222 explicitly setting one, or more, of the \f(CW\*(C`Name\*(C'\fR, \f(CW\*(C`Time\*(C'\fR, \f(CW\*(C`TextFlag\*(C'\fR, \f(CW\*(C`ExtAttr\*(C'\fR, \f(CW\*(C`exUnixN\*(C'\fR and \f(CW\*(C`exTime\*(C'\fR options or by setting the
223 \&\f(CW\*(C`Minimal\*(C'\fR parameter.
224 .PP
225 \fIThe \fR\f(CI$output_filename_or_reference\fR\fI parameter\fR
226 .IX Subsection "The $output_filename_or_reference parameter"
227 .PP
228 The parameter \f(CW$output_filename_or_reference\fR is used to control the
229 destination of the compressed data. This parameter can take one of
230 these forms.
231 .IP "A filename" 5
232 .IX Item "A filename"
233 If the \f(CW$output_filename_or_reference\fR parameter is a simple scalar, it is
234 assumed to be a filename. This file will be opened for writing and the
235 compressed data will be written to it.
236 .IP "A filehandle" 5
237 .IX Item "A filehandle"
238 If the \f(CW$output_filename_or_reference\fR parameter is a filehandle, the
239 compressed data will be written to it. The string \*(Aq\-\*(Aq can be used as
240 an alias for standard output.
241 .IP "A scalar reference" 5
242 .IX Item "A scalar reference"
243 If \f(CW$output_filename_or_reference\fR is a scalar reference, the
244 compressed data will be stored in \f(CW$$output_filename_or_reference\fR.
245 .IP "An Array Reference" 5
246 .IX Item "An Array Reference"
247 If \f(CW$output_filename_or_reference\fR is an array reference,
248 the compressed data will be pushed onto the array.
249 .IP "An Output FileGlob" 5
250 .IX Item "An Output FileGlob"
251 If \f(CW$output_filename_or_reference\fR is a string that is delimited by the
252 characters "<" and ">" \f(CW\*(C`zip\*(C'\fR will assume that it is an
253 \&\fIoutput fileglob string\fR. The output is the list of files that match the
254 fileglob.
255 .Sp
256 When \f(CW$output_filename_or_reference\fR is an fileglob string,
257 \&\f(CW$input_filename_or_reference\fR must also be a fileglob string. Anything
258 else is an error.
259 .Sp
260 See File::GlobMapper for more details.
261 .PP
262 If the \f(CW$output_filename_or_reference\fR parameter is any other type,
263 \&\f(CW\*(C`undef\*(C'\fR will be returned.
264 .SS Notes
265 .IX Subsection "Notes"
266 When \f(CW$input_filename_or_reference\fR maps to multiple files/buffers and
267 \&\f(CW$output_filename_or_reference\fR is a single
268 file/buffer the input files/buffers will each be stored
269 in \f(CW$output_filename_or_reference\fR as a distinct entry.
270 .SS "Optional Parameters"
271 .IX Subsection "Optional Parameters"
272 The optional parameters for the one\-shot function \f(CW\*(C`zip\*(C'\fR
273 are (for the most part) identical to those used with the OO interface defined in the
274 "Constructor Options" section. The exceptions are listed below
275 .ie n .IP """AutoClose => 0|1""" 5
276 .el .IP "\f(CWAutoClose => 0|1\fR" 5
277 .IX Item "AutoClose => 0|1"
278 This option applies to any input or output data streams to
279 \&\f(CW\*(C`zip\*(C'\fR that are filehandles.
280 .Sp
281 If \f(CW\*(C`AutoClose\*(C'\fR is specified, and the value is true, it will result in all
282 input and/or output filehandles being closed once \f(CW\*(C`zip\*(C'\fR has
283 completed.
284 .Sp
285 This parameter defaults to 0.
286 .ie n .IP """BinModeIn => 0|1""" 5
287 .el .IP "\f(CWBinModeIn => 0|1\fR" 5
288 .IX Item "BinModeIn => 0|1"
289 This option is now a no\-op. All files will be read in binmode.
290 .ie n .IP """Append => 0|1""" 5
291 .el .IP "\f(CWAppend => 0|1\fR" 5
292 .IX Item "Append => 0|1"
293 The behaviour of this option is dependent on the type of output data
294 stream.
295 .RS 5
296 .IP \(bu 5
297 A Buffer
298 .Sp
299 If \f(CW\*(C`Append\*(C'\fR is enabled, all compressed data will be append to the end of
300 the output buffer. Otherwise the output buffer will be cleared before any
301 compressed data is written to it.
302 .IP \(bu 5
303 A Filename
304 .Sp
305 If \f(CW\*(C`Append\*(C'\fR is enabled, the file will be opened in append mode. Otherwise
306 the contents of the file, if any, will be truncated before any compressed
307 data is written to it.
308 .IP \(bu 5
309 A Filehandle
310 .Sp
311 If \f(CW\*(C`Append\*(C'\fR is enabled, the filehandle will be positioned to the end of
312 the file via a call to \f(CW\*(C`seek\*(C'\fR before any compressed data is
313 written to it. Otherwise the file pointer will not be moved.
314 .RE
315 .RS 5
316 .Sp
317 When \f(CW\*(C`Append\*(C'\fR is specified, and set to true, it will \fIappend\fR all compressed
318 data to the output data stream.
319 .Sp
320 So when the output is a filehandle it will carry out a seek to the eof
321 before writing any compressed data. If the output is a filename, it will be opened for
322 appending. If the output is a buffer, all compressed data will be
323 appended to the existing buffer.
324 .Sp
325 Conversely when \f(CW\*(C`Append\*(C'\fR is not specified, or it is present and is set to
326 false, it will operate as follows.
327 .Sp
328 When the output is a filename, it will truncate the contents of the file
329 before writing any compressed data. If the output is a filehandle
330 its position will not be changed. If the output is a buffer, it will be
331 wiped before any compressed data is output.
332 .Sp
333 Defaults to 0.
334 .RE
335 .SS "Oneshot Examples"
336 .IX Subsection "Oneshot Examples"
337 Here are a few example that show the capabilities of the module.
338 .PP
339 \fIStreaming\fR
340 .IX Subsection "Streaming"
341 .PP
342 This very simple command line example demonstrates the streaming capabilities of the module.
343 The code reads data from STDIN, compresses it, and writes the compressed data to STDOUT.
344 .PP
345 .Vb 1
346 \& $ echo hello world | perl \-MIO::Compress::Zip=zip \-e \*(Aqzip \e*STDIN => \e*STDOUT\*(Aq >output.zip
347 .Ve
348 .PP
349 The special filename "\-" can be used as a standin for both \f(CW\*(C`\e*STDIN\*(C'\fR and \f(CW\*(C`\e*STDOUT\*(C'\fR,
350 so the above can be rewritten as
351 .PP
352 .Vb 1
353 \& $ echo hello world | perl \-MIO::Compress::Zip=zip \-e \*(Aqzip "\-" => "\-"\*(Aq >output.zip
354 .Ve
355 .PP
356 One problem with creating a zip archive directly from STDIN can be demonstrated by looking at
357 the contents of the zip file, output.zip, that we have just created.
358 .PP
359 .Vb 7
360 \& $ unzip \-l output.zip
361 \& Archive: output.zip
362 \& Length Date Time Name
363 \& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\- \-\-\-\-
364 \& 12 2019\-08\-16 22:21
365 \& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
366 \& 12 1 file
367 .Ve
368 .PP
369 The archive member (filename) used is the empty string.
370 .PP
371 If that doesn\*(Aqt suit your needs, you can explicitly set the filename used
372 in the zip archive by specifying the Name option, like so
373 .PP
374 .Vb 1
375 \& echo hello world | perl \-MIO::Compress::Zip=zip \-e \*(Aqzip "\-" => "\-", Name => "hello.txt"\*(Aq >output.zip
376 .Ve
377 .PP
378 Now the contents of the zip file looks like this
379 .PP
380 .Vb 7
381 \& $ unzip \-l output.zip
382 \& Archive: output.zip
383 \& Length Date Time Name
384 \& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\- \-\-\-\-
385 \& 12 2019\-08\-16 22:22 hello.txt
386 \& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
387 \& 12 1 file
388 .Ve
389 .PP
390 \fICompressing a file from the filesystem\fR
391 .IX Subsection "Compressing a file from the filesystem"
392 .PP
393 To read the contents of the file \f(CW\*(C`file1.txt\*(C'\fR and write the compressed
394 data to the file \f(CW\*(C`file1.txt.zip\*(C'\fR.
395 .PP
396 .Vb 3
397 \& use strict ;
398 \& use warnings ;
399 \& use IO::Compress::Zip qw(zip $ZipError) ;
400 \&
401 \& my $input = "file1.txt";
402 \& zip $input => "$input.zip"
403 \& or die "zip failed: $ZipError\en";
404 .Ve
405 .PP
406 \fIReading from a Filehandle and writing to an in\-memory buffer\fR
407 .IX Subsection "Reading from a Filehandle and writing to an in-memory buffer"
408 .PP
409 To read from an existing Perl filehandle, \f(CW$input\fR, and write the
410 compressed data to a buffer, \f(CW$buffer\fR.
411 .PP
412 .Vb 4
413 \& use strict ;
414 \& use warnings ;
415 \& use IO::Compress::Zip qw(zip $ZipError) ;
416 \& use IO::File ;
417 \&
418 \& my $input = IO::File\->new( "<file1.txt" )
419 \& or die "Cannot open \*(Aqfile1.txt\*(Aq: $!\en" ;
420 \& my $buffer ;
421 \& zip $input => \e$buffer
422 \& or die "zip failed: $ZipError\en";
423 .Ve
424 .PP
425 \fICompressing multiple files\fR
426 .IX Subsection "Compressing multiple files"
427 .PP
428 To create a zip file, \f(CW\*(C`output.zip\*(C'\fR, that contains the compressed contents
429 of the files \f(CW\*(C`alpha.txt\*(C'\fR and \f(CW\*(C`beta.txt\*(C'\fR
430 .PP
431 .Vb 3
432 \& use strict ;
433 \& use warnings ;
434 \& use IO::Compress::Zip qw(zip $ZipError) ;
435 \&
436 \& zip [ \*(Aqalpha.txt\*(Aq, \*(Aqbeta.txt\*(Aq ] => \*(Aqoutput.zip\*(Aq
437 \& or die "zip failed: $ZipError\en";
438 .Ve
439 .PP
440 Alternatively, rather than having to explicitly name each of the files that
441 you want to compress, you could use a fileglob to select all the \f(CW\*(C`txt\*(C'\fR
442 files in the current directory, as follows
443 .PP
444 .Vb 3
445 \& use strict ;
446 \& use warnings ;
447 \& use IO::Compress::Zip qw(zip $ZipError) ;
448 \&
449 \& my @files = <*.txt>;
450 \& zip \e@files => \*(Aqoutput.zip\*(Aq
451 \& or die "zip failed: $ZipError\en";
452 .Ve
453 .PP
454 or more succinctly
455 .PP
456 .Vb 2
457 \& zip [ <*.txt> ] => \*(Aqoutput.zip\*(Aq
458 \& or die "zip failed: $ZipError\en";
459 .Ve
460 .SH "OO Interface"
461 .IX Header "OO Interface"
462 .SS Constructor
463 .IX Subsection "Constructor"
464 The format of the constructor for \f(CW\*(C`IO::Compress::Zip\*(C'\fR is shown below
465 .PP
466 .Vb 2
467 \& my $z = IO::Compress::Zip\->new( $output [,OPTS] )
468 \& or die "IO::Compress::Zip failed: $ZipError\en";
469 .Ve
470 .PP
471 The constructor takes one mandatory parameter, \f(CW$output\fR, defined below and
472 zero or more \f(CW\*(C`OPTS\*(C'\fR, defined in "Constructor Options".
473 .PP
474 It returns an \f(CW\*(C`IO::Compress::Zip\*(C'\fR object on success and \f(CW\*(C`undef\*(C'\fR on failure.
475 The variable \f(CW$ZipError\fR will contain an error message on failure.
476 .PP
477 If you are running Perl 5.005 or better the object, \f(CW$z\fR, returned from
478 IO::Compress::Zip can be used exactly like an IO::File filehandle.
479 This means that all normal output file operations can be carried out
480 with \f(CW$z\fR.
481 For example, to write to a compressed file/buffer you can use either of
482 these forms
483 .PP
484 .Vb 2
485 \& $z\->print("hello world\en");
486 \& print $z "hello world\en";
487 .Ve
488 .PP
489 Below is a simple exaple of using the OO interface to create an output file
490 \&\f(CW\*(C`myfile.zip\*(C'\fR and write some data to it.
491 .PP
492 .Vb 3
493 \& my $filename = "myfile.zip";
494 \& my $z = IO::Compress::Zip\->new($filename)
495 \& or die "IO::Compress::Zip failed: $ZipError\en";
496 \&
497 \& $z\->print("abcde");
498 \& $z\->close();
499 .Ve
500 .PP
501 See the "Examples" for more.
502 .PP
503 The mandatory parameter \f(CW$output\fR is used to control the destination
504 of the compressed data. This parameter can take one of these forms.
505 .IP "A filename" 5
506 .IX Item "A filename"
507 If the \f(CW$output\fR parameter is a simple scalar, it is assumed to be a
508 filename. This file will be opened for writing and the compressed data
509 will be written to it.
510 .IP "A filehandle" 5
511 .IX Item "A filehandle"
512 If the \f(CW$output\fR parameter is a filehandle, the compressed data will be
513 written to it.
514 The string \*(Aq\-\*(Aq can be used as an alias for standard output.
515 .IP "A scalar reference" 5
516 .IX Item "A scalar reference"
517 If \f(CW$output\fR is a scalar reference, the compressed data will be stored
518 in \f(CW$$output\fR.
519 .PP
520 If the \f(CW$output\fR parameter is any other type, \f(CW\*(C`IO::Compress::Zip\*(C'\fR::new will
521 return undef.
522 .SS "Constructor Options"
523 .IX Subsection "Constructor Options"
524 \&\f(CW\*(C`OPTS\*(C'\fR is any combination of zero or more the following options:
525 .ie n .IP """AutoClose => 0|1""" 5
526 .el .IP "\f(CWAutoClose => 0|1\fR" 5
527 .IX Item "AutoClose => 0|1"
528 This option is only valid when the \f(CW$output\fR parameter is a filehandle. If
529 specified, and the value is true, it will result in the \f(CW$output\fR being
530 closed once either the \f(CW\*(C`close\*(C'\fR method is called or the \f(CW\*(C`IO::Compress::Zip\*(C'\fR
531 object is destroyed.
532 .Sp
533 This parameter defaults to 0.
534 .ie n .IP """Append => 0|1""" 5
535 .el .IP "\f(CWAppend => 0|1\fR" 5
536 .IX Item "Append => 0|1"
537 Opens \f(CW$output\fR in append mode.
538 .Sp
539 The behaviour of this option is dependent on the type of \f(CW$output\fR.
540 .RS 5
541 .IP \(bu 5
542 A Buffer
543 .Sp
544 If \f(CW$output\fR is a buffer and \f(CW\*(C`Append\*(C'\fR is enabled, all compressed data
545 will be append to the end of \f(CW$output\fR. Otherwise \f(CW$output\fR will be
546 cleared before any data is written to it.
547 .IP \(bu 5
548 A Filename
549 .Sp
550 If \f(CW$output\fR is a filename and \f(CW\*(C`Append\*(C'\fR is enabled, the file will be
551 opened in append mode. Otherwise the contents of the file, if any, will be
552 truncated before any compressed data is written to it.
553 .IP \(bu 5
554 A Filehandle
555 .Sp
556 If \f(CW$output\fR is a filehandle, the file pointer will be positioned to the
557 end of the file via a call to \f(CW\*(C`seek\*(C'\fR before any compressed data is written
558 to it. Otherwise the file pointer will not be moved.
559 .RE
560 .RS 5
561 .Sp
562 This parameter defaults to 0.
563 .RE
564 .PP
565 \fIFile Naming Options\fR
566 .IX Subsection "File Naming Options"
567 .PP
568 A quick bit of zip file terminology \-\- A zip archive consists of one or more \fIarchive members\fR, where each member has an associated
569 filename, known as the \fIarchive member name\fR.
570 .PP
571 The options listed in this section control how the \fIarchive member name\fR (or filename) is stored the zip archive.
572 .ie n .IP """Name => $string""" 5
573 .el .IP "\f(CWName => $string\fR" 5
574 .IX Item "Name => $string"
575 This option is used to explicitly set the \fIarchive member name\fR in
576 the zip archive to \f(CW$string\fR.
577 Most of the time you don\*(Aqt need to make use of this option.
578 By default when adding a filename to the zip archive, the \fIarchive member name\fR will match the filename.
579 .Sp
580 You should only need to use this option if you want the \fIarchive member name\fR
581 to be different from the uncompressed filename or when the input is a filehandle or a buffer.
582 .Sp
583 The default behaviour for what \fIarchive member name\fR is used when the \f(CW\*(C`Name\*(C'\fR option
584 is \fInot\fR specified depends on the form of the \f(CW$input\fR parameter:
585 .RS 5
586 .IP \(bu 5
587 If the \f(CW$input\fR parameter is a filename, the
588 value of \f(CW$input\fR will be used for the \fIarchive member name\fR .
589 .IP \(bu 5
590 If the \f(CW$input\fR parameter is not a filename,
591 the \fIarchive member name\fR will be an empty string.
592 .RE
593 .RS 5
594 .Sp
595 Note that both the \f(CW\*(C`CanonicalName\*(C'\fR and \f(CW\*(C`FilterName\*(C'\fR options
596 can modify the value used for the \fIarchive member name\fR.
597 .Sp
598 Also note that you should set the \f(CW\*(C`Efs\*(C'\fR option to true if you are working
599 with UTF8 filenames.
600 .RE
601 .ie n .IP """CanonicalName => 0|1""" 5
602 .el .IP "\f(CWCanonicalName => 0|1\fR" 5
603 .IX Item "CanonicalName => 0|1"
604 This option controls whether the \fIarchive member name\fR is
605 \&\fInormalized\fR into Unix format before being written to the zip file.
606 .Sp
607 It is recommended that you enable this option unless you really need
608 to create a non\-standard Zip file.
609 .Sp
610 This is what APPNOTE.TXT has to say on what should be stored in the zip
611 filename header field.
612 .Sp
613 .Vb 6
614 \& The name of the file, with optional relative path.
615 \& The path stored should not contain a drive or
616 \& device letter, or a leading slash. All slashes
617 \& should be forward slashes \*(Aq/\*(Aq as opposed to
618 \& backwards slashes \*(Aq\e\*(Aq for compatibility with Amiga
619 \& and UNIX file systems etc.
620 .Ve
621 .Sp
622 This option defaults to \fBfalse\fR.
623 .ie n .IP """FilterName => sub { ... }""" 5
624 .el .IP "\f(CWFilterName => sub { ... }\fR" 5
625 .IX Item "FilterName => sub { ... }"
626 This option allow the \fIarchive member\fR name to be modified
627 before it is written to the zip file.
628 .Sp
629 This option takes a parameter that must be a reference to a sub. On entry
630 to the sub the \f(CW$_\fR variable will contain the name to be filtered. If no
631 filename is available \f(CW$_\fR will contain an empty string.
632 .Sp
633 The value of \f(CW$_\fR when the sub returns will be used as the \fIarchive member name\fR.
634 .Sp
635 Note that if \f(CW\*(C`CanonicalName\*(C'\fR is enabled, a
636 normalized filename will be passed to the sub.
637 .Sp
638 If you use \f(CW\*(C`FilterName\*(C'\fR to modify the filename, it is your responsibility
639 to keep the filename in Unix format.
640 .Sp
641 Although this option can be used with the OO interface, it is of most use
642 with the one\-shot interface. For example, the code below shows how
643 \&\f(CW\*(C`FilterName\*(C'\fR can be used to remove the path component from a series of
644 filenames before they are stored in \f(CW$zipfile\fR.
645 .Sp
646 .Vb 4
647 \& sub compressTxtFiles
648 \& {
649 \& my $zipfile = shift ;
650 \& my $dir = shift ;
651 \&
652 \& zip [ <$dir/*.txt> ] => $zipfile,
653 \& FilterName => sub { s[^$dir/][] } ;
654 \& }
655 .Ve
656 .ie n .IP """Efs => 0|1""" 5
657 .el .IP "\f(CWEfs => 0|1\fR" 5
658 .IX Item "Efs => 0|1"
659 This option controls setting of the "Language Encoding Flag" (EFS) in the zip
660 archive. When set, the filename and comment fields for the zip archive MUST
661 be valid UTF\-8.
662 .Sp
663 If the string used for the filename and/or comment is not valid UTF\-8 when this option
664 is true, the script will die with a "wide character" error.
665 .Sp
666 Note that this option only works with Perl 5.8.4 or better.
667 .Sp
668 This option defaults to \fBfalse\fR.
669 .PP
670 \fIOverall Zip Archive Structure\fR
671 .IX Subsection "Overall Zip Archive Structure"
672 .ie n .IP """Minimal => 1|0""" 5
673 .el .IP "\f(CWMinimal => 1|0\fR" 5
674 .IX Item "Minimal => 1|0"
675 If specified, this option will disable the creation of all extra fields
676 in the zip local and central headers. So the \f(CW\*(C`exTime\*(C'\fR, \f(CW\*(C`exUnix2\*(C'\fR,
677 \&\f(CW\*(C`exUnixN\*(C'\fR, \f(CW\*(C`ExtraFieldLocal\*(C'\fR and \f(CW\*(C`ExtraFieldCentral\*(C'\fR options will
678 be ignored.
679 .Sp
680 This parameter defaults to 0.
681 .ie n .IP """Stream => 0|1""" 5
682 .el .IP "\f(CWStream => 0|1\fR" 5
683 .IX Item "Stream => 0|1"
684 This option controls whether the zip file/buffer output is created in
685 streaming mode.
686 .Sp
687 Note that when outputting to a file with streaming mode disabled (\f(CW\*(C`Stream\*(C'\fR
688 is 0), the output file must be seekable.
689 .Sp
690 The default is 1.
691 .ie n .IP """Zip64 => 0|1""" 5
692 .el .IP "\f(CWZip64 => 0|1\fR" 5
693 .IX Item "Zip64 => 0|1"
694 Create a Zip64 zip file/buffer. This option is used if you want
695 to store files larger than 4 Gig or store more than 64K files in a single
696 zip archive.
697 .Sp
698 \&\f(CW\*(C`Zip64\*(C'\fR will be automatically set, as needed, if working with the one\-shot
699 interface when the input is either a filename or a scalar reference.
700 .Sp
701 If you intend to manipulate the Zip64 zip files created with this module
702 using an external zip/unzip, make sure that it supports Zip64.
703 .Sp
704 In particular, if you are using Info\-Zip you need to have zip version 3.x
705 or better to update a Zip64 archive and unzip version 6.x to read a zip64
706 archive.
707 .Sp
708 The default is 0.
709 .PP
710 \fIDeflate Compression Options\fR
711 .IX Subsection "Deflate Compression Options"
712 .IP \-Level 5
713 .IX Item "-Level"
714 Defines the compression level used by zlib. The value should either be
715 a number between 0 and 9 (0 means no compression and 9 is maximum
716 compression), or one of the symbolic constants defined below.
717 .Sp
718 .Vb 4
719 \& Z_NO_COMPRESSION
720 \& Z_BEST_SPEED
721 \& Z_BEST_COMPRESSION
722 \& Z_DEFAULT_COMPRESSION
723 .Ve
724 .Sp
725 The default is Z_DEFAULT_COMPRESSION.
726 .Sp
727 Note, these constants are not imported by \f(CW\*(C`IO::Compress::Zip\*(C'\fR by default.
728 .Sp
729 .Vb 3
730 \& use IO::Compress::Zip qw(:strategy);
731 \& use IO::Compress::Zip qw(:constants);
732 \& use IO::Compress::Zip qw(:all);
733 .Ve
734 .IP \-Strategy 5
735 .IX Item "-Strategy"
736 Defines the strategy used to tune the compression. Use one of the symbolic
737 constants defined below.
738 .Sp
739 .Vb 5
740 \& Z_FILTERED
741 \& Z_HUFFMAN_ONLY
742 \& Z_RLE
743 \& Z_FIXED
744 \& Z_DEFAULT_STRATEGY
745 .Ve
746 .Sp
747 The default is Z_DEFAULT_STRATEGY.
748 .PP
749 \fIBzip2 Compression Options\fR
750 .IX Subsection "Bzip2 Compression Options"
751 .ie n .IP """BlockSize100K => number""" 5
752 .el .IP "\f(CWBlockSize100K => number\fR" 5
753 .IX Item "BlockSize100K => number"
754 Specify the number of 100K blocks bzip2 uses during compression.
755 .Sp
756 Valid values are from 1 to 9, where 9 is best compression.
757 .Sp
758 This option is only valid if the \f(CW\*(C`Method\*(C'\fR is ZIP_CM_BZIP2. It is ignored
759 otherwise.
760 .Sp
761 The default is 1.
762 .ie n .IP """WorkFactor => number""" 5
763 .el .IP "\f(CWWorkFactor => number\fR" 5
764 .IX Item "WorkFactor => number"
765 Specifies how much effort bzip2 should take before resorting to a slower
766 fallback compression algorithm.
767 .Sp
768 Valid values range from 0 to 250, where 0 means use the default value 30.
769 .Sp
770 This option is only valid if the \f(CW\*(C`Method\*(C'\fR is ZIP_CM_BZIP2. It is ignored
771 otherwise.
772 .Sp
773 The default is 0.
774 .PP
775 \fILzma and Xz Compression Options\fR
776 .IX Subsection "Lzma and Xz Compression Options"
777 .ie n .IP """Preset => number""" 5
778 .el .IP "\f(CWPreset => number\fR" 5
779 .IX Item "Preset => number"
780 Used to choose the LZMA compression preset.
781 .Sp
782 Valid values are 0\-9 and \f(CW\*(C`LZMA_PRESET_DEFAULT\*(C'\fR.
783 .Sp
784 0 is the fastest compression with the lowest memory usage and the lowest
785 compression.
786 .Sp
787 9 is the slowest compression with the highest memory usage but with the best
788 compression.
789 .Sp
790 This option is only valid if the \f(CW\*(C`Method\*(C'\fR is ZIP_CM_LZMA. It is ignored
791 otherwise.
792 .Sp
793 Defaults to \f(CW\*(C`LZMA_PRESET_DEFAULT\*(C'\fR (6).
794 .ie n .IP """Extreme => 0|1""" 5
795 .el .IP "\f(CWExtreme => 0|1\fR" 5
796 .IX Item "Extreme => 0|1"
797 Makes LZMA compression a lot slower, but a small compression gain.
798 .Sp
799 This option is only valid if the \f(CW\*(C`Method\*(C'\fR is ZIP_CM_LZMA. It is ignored
800 otherwise.
801 .Sp
802 Defaults to 0.
803 .PP
804 \fIOther Options\fR
805 .IX Subsection "Other Options"
806 .ie n .IP """Time => $number""" 5
807 .el .IP "\f(CWTime => $number\fR" 5
808 .IX Item "Time => $number"
809 Sets the last modified time field in the zip header to \f(CW$number\fR.
810 .Sp
811 This field defaults to the time the \f(CW\*(C`IO::Compress::Zip\*(C'\fR object was created
812 if this option is not specified and the \f(CW$input\fR parameter is not a
813 filename.
814 .ie n .IP """ExtAttr => $attr""" 5
815 .el .IP "\f(CWExtAttr => $attr\fR" 5
816 .IX Item "ExtAttr => $attr"
817 This option controls the "external file attributes" field in the central
818 header of the zip file. This is a 4 byte field.
819 .Sp
820 If you are running a Unix derivative this value defaults to
821 .Sp
822 .Vb 1
823 \& 0100644 << 16
824 .Ve
825 .Sp
826 This should allow read/write access to any files that are extracted from
827 the zip file/buffer\`.
828 .Sp
829 For all other systems it defaults to 0.
830 .ie n .IP """exTime => [$atime, $mtime, $ctime]""" 5
831 .el .IP "\f(CWexTime => [$atime, $mtime, $ctime]\fR" 5
832 .IX Item "exTime => [$atime, $mtime, $ctime]"
833 This option expects an array reference with exactly three elements:
834 \&\f(CW$atime\fR, \f(CW\*(C`mtime\*(C'\fR and \f(CW$ctime\fR. These correspond to the last access
835 time, last modification time and creation time respectively.
836 .Sp
837 It uses these values to set the extended timestamp field (ID is "UT") in
838 the local zip header using the three values, \f(CW$atime\fR, \f(CW$mtime\fR, \f(CW$ctime\fR. In
839 addition it sets the extended timestamp field in the central zip header
840 using \f(CW$mtime\fR.
841 .Sp
842 If any of the three values is \f(CW\*(C`undef\*(C'\fR that time value will not be used.
843 So, for example, to set only the \f(CW$mtime\fR you would use this
844 .Sp
845 .Vb 1
846 \& exTime => [undef, $mtime, undef]
847 .Ve
848 .Sp
849 If the \f(CW\*(C`Minimal\*(C'\fR option is set to true, this option will be ignored.
850 .Sp
851 By default no extended time field is created.
852 .ie n .IP """exUnix2 => [$uid, $gid]""" 5
853 .el .IP "\f(CWexUnix2 => [$uid, $gid]\fR" 5
854 .IX Item "exUnix2 => [$uid, $gid]"
855 This option expects an array reference with exactly two elements: \f(CW$uid\fR
856 and \f(CW$gid\fR. These values correspond to the numeric User ID (UID) and Group ID
857 (GID) of the owner of the files respectively.
858 .Sp
859 When the \f(CW\*(C`exUnix2\*(C'\fR option is present it will trigger the creation of a
860 Unix2 extra field (ID is "Ux") in the local zip header. This will be populated
861 with \f(CW$uid\fR and \f(CW$gid\fR. An empty Unix2 extra field will also
862 be created in the central zip header.
863 .Sp
864 Note \- The UID & GID are stored as 16\-bit
865 integers in the "Ux" field. Use \f(CW\*(C`exUnixN\*(C'\fR if your UID or GID are
866 32\-bit.
867 .Sp
868 If the \f(CW\*(C`Minimal\*(C'\fR option is set to true, this option will be ignored.
869 .Sp
870 By default no Unix2 extra field is created.
871 .ie n .IP """exUnixN => [$uid, $gid]""" 5
872 .el .IP "\f(CWexUnixN => [$uid, $gid]\fR" 5
873 .IX Item "exUnixN => [$uid, $gid]"
874 This option expects an array reference with exactly two elements: \f(CW$uid\fR
875 and \f(CW$gid\fR. These values correspond to the numeric User ID (UID) and Group ID
876 (GID) of the owner of the files respectively.
877 .Sp
878 When the \f(CW\*(C`exUnixN\*(C'\fR option is present it will trigger the creation of a
879 UnixN extra field (ID is "ux") in both the local and central zip headers.
880 This will be populated with \f(CW$uid\fR and \f(CW$gid\fR.
881 The UID & GID are stored as 32\-bit integers.
882 .Sp
883 If the \f(CW\*(C`Minimal\*(C'\fR option is set to true, this option will be ignored.
884 .Sp
885 By default no UnixN extra field is created.
886 .ie n .IP """Comment => $comment""" 5
887 .el .IP "\f(CWComment => $comment\fR" 5
888 .IX Item "Comment => $comment"
889 Stores the contents of \f(CW$comment\fR in the Central File Header of
890 the zip file.
891 .Sp
892 Set the \f(CW\*(C`Efs\*(C'\fR option to true if you want to store a UTF8 comment.
893 .Sp
894 By default, no comment field is written to the zip file.
895 .ie n .IP """ZipComment => $comment""" 5
896 .el .IP "\f(CWZipComment => $comment\fR" 5
897 .IX Item "ZipComment => $comment"
898 Stores the contents of \f(CW$comment\fR in the End of Central Directory record
899 of the zip file.
900 .Sp
901 By default, no comment field is written to the zip file.
902 .ie n .IP """Method => $method""" 5
903 .el .IP "\f(CWMethod => $method\fR" 5
904 .IX Item "Method => $method"
905 Controls which compression method is used. At present the compression
906 methods supported are: Store (no compression at all), Deflate,
907 Bzip2, Zstd, Xz and Lzma.
908 .Sp
909 The symbols ZIP_CM_STORE, ZIP_CM_DEFLATE, ZIP_CM_BZIP2, ZIP_CM_ZSTD, ZIP_CM_XZ and ZIP_CM_LZMA
910 are used to select the compression method.
911 .Sp
912 These constants are not imported by \f(CW\*(C`IO::Compress::Zip\*(C'\fR by default.
913 .Sp
914 .Vb 3
915 \& use IO::Compress::Zip qw(:zip_method);
916 \& use IO::Compress::Zip qw(:constants);
917 \& use IO::Compress::Zip qw(:all);
918 .Ve
919 .Sp
920 Note that to create Bzip2 content, the module \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR must
921 be installed. A fatal error will be thrown if you attempt to create Bzip2
922 content when \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR is not available.
923 .Sp
924 Note that to create Lzma content, the module \f(CW\*(C`IO::Compress::Lzma\*(C'\fR must
925 be installed. A fatal error will be thrown if you attempt to create Lzma
926 content when \f(CW\*(C`IO::Compress::Lzma\*(C'\fR is not available.
927 .Sp
928 Note that to create Xz content, the module \f(CW\*(C`IO::Compress::Xz\*(C'\fR must
929 be installed. A fatal error will be thrown if you attempt to create Xz
930 content when \f(CW\*(C`IO::Compress::Xz\*(C'\fR is not available.
931 .Sp
932 Note that to create Zstd content, the module \f(CW\*(C`IO::Compress::Zstd\*(C'\fR must
933 be installed. A fatal error will be thrown if you attempt to create Zstd
934 content when \f(CW\*(C`IO::Compress::Zstd\*(C'\fR is not available.
935 .Sp
936 The default method is ZIP_CM_DEFLATE.
937 .ie n .IP """TextFlag => 0|1""" 5
938 .el .IP "\f(CWTextFlag => 0|1\fR" 5
939 .IX Item "TextFlag => 0|1"
940 This parameter controls the setting of a bit in the zip central header. It
941 is used to signal that the data stored in the zip file/buffer is probably
942 text.
943 .Sp
944 In one\-shot mode this flag will be set to true if the Perl \f(CW\*(C`\-T\*(C'\fR operator thinks
945 the file contains text.
946 .Sp
947 The default is 0.
948 .ie n .IP """ExtraFieldLocal => $data""" 5
949 .el .IP "\f(CWExtraFieldLocal => $data\fR" 5
950 .IX Item "ExtraFieldLocal => $data"
951 .PD 0
952 .ie n .IP """ExtraFieldCentral => $data""" 5
953 .el .IP "\f(CWExtraFieldCentral => $data\fR" 5
954 .IX Item "ExtraFieldCentral => $data"
955 .PD
956 The \f(CW\*(C`ExtraFieldLocal\*(C'\fR option is used to store additional metadata in the
957 local header for the zip file/buffer. The \f(CW\*(C`ExtraFieldCentral\*(C'\fR does the
958 same for the matching central header.
959 .Sp
960 An extra field consists of zero or more subfields. Each subfield consists
961 of a two byte header followed by the subfield data.
962 .Sp
963 The list of subfields can be supplied in any of the following formats
964 .Sp
965 .Vb 4
966 \& ExtraFieldLocal => [$id1, $data1,
967 \& $id2, $data2,
968 \& ...
969 \& ]
970 \&
971 \& ExtraFieldLocal => [ [$id1 => $data1],
972 \& [$id2 => $data2],
973 \& ...
974 \& ]
975 \&
976 \& ExtraFieldLocal => { $id1 => $data1,
977 \& $id2 => $data2,
978 \& ...
979 \& }
980 .Ve
981 .Sp
982 Where \f(CW$id1\fR, \f(CW$id2\fR are two byte subfield ID\*(Aqs.
983 .Sp
984 If you use the hash syntax, you have no control over the order in which
985 the ExtraSubFields are stored, plus you cannot have SubFields with
986 duplicate ID.
987 .Sp
988 Alternatively the list of subfields can by supplied as a scalar, thus
989 .Sp
990 .Vb 1
991 \& ExtraField => $rawdata
992 .Ve
993 .Sp
994 In this case \f(CW\*(C`IO::Compress::Zip\*(C'\fR will check that \f(CW$rawdata\fR consists of
995 zero or more conformant sub\-fields.
996 .Sp
997 The Extended Time field (ID "UT"), set using the \f(CW\*(C`exTime\*(C'\fR option, and the
998 Unix2 extra field (ID "Ux), set using the \f(CW\*(C`exUnix2\*(C'\fR option, are examples
999 of extra fields.
1000 .Sp
1001 If the \f(CW\*(C`Minimal\*(C'\fR option is set to true, this option will be ignored.
1002 .Sp
1003 The maximum size of an extra field 65535 bytes.
1004 .ie n .IP """Strict => 0|1""" 5
1005 .el .IP "\f(CWStrict => 0|1\fR" 5
1006 .IX Item "Strict => 0|1"
1007 This is a placeholder option.
1008 .SS Examples
1009 .IX Subsection "Examples"
1010 \fIStreaming\fR
1011 .IX Subsection "Streaming"
1012 .PP
1013 This very simple command line example demonstrates the streaming capabilities
1014 of the module. The code reads data from STDIN or all the files given on the
1015 commandline, compresses it, and writes the compressed data to STDOUT.
1016 .PP
1017 .Vb 3
1018 \& use strict ;
1019 \& use warnings ;
1020 \& use IO::Compress::Zip qw(zip $ZipError) ;
1021 \&
1022 \& my $z = IO::Compress::Zip\->new("\-", Stream => 1)
1023 \& or die "IO::Compress::Zip failed: $ZipError\en";
1024 \&
1025 \& while (<>) {
1026 \& $z\->print("abcde");
1027 \& }
1028 \& $z\->close();
1029 .Ve
1030 .PP
1031 Note the use of \f(CW"\-"\fR to means \f(CW\*(C`STDOUT\*(C'\fR. Alternatively you can use \f(CW\*(C`\e*STDOUT\*(C'\fR.
1032 .PP
1033 One problem with creating a zip archive directly from STDIN can be demonstrated by looking at
1034 the contents of the zip file, output.zip, that we have just created
1035 (assumg you have redirected it to a file called \f(CW\*(C`output.zip\*(C'\fR).
1036 .PP
1037 .Vb 7
1038 \& $ unzip \-l output.zip
1039 \& Archive: output.zip
1040 \& Length Date Time Name
1041 \& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\- \-\-\-\-
1042 \& 12 2019\-08\-16 22:21
1043 \& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
1044 \& 12 1 file
1045 .Ve
1046 .PP
1047 The archive member (filename) used is the empty string.
1048 .PP
1049 If that doesn\*(Aqt suit your needs, you can explicitly set the filename used
1050 in the zip archive by specifying the Name option, like so
1051 .PP
1052 .Vb 1
1053 \& my $z = IO::Compress::Zip\->new("\-", Name => "hello.txt", Stream => 1)
1054 .Ve
1055 .PP
1056 Now the contents of the zip file looks like this
1057 .PP
1058 .Vb 7
1059 \& $ unzip \-l output.zip
1060 \& Archive: output.zip
1061 \& Length Date Time Name
1062 \& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\- \-\-\-\-
1063 \& 12 2019\-08\-16 22:22 hello.txt
1064 \& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
1065 \& 12 1 file
1066 .Ve
1067 .PP
1068 \fICompressing a file from the filesystem\fR
1069 .IX Subsection "Compressing a file from the filesystem"
1070 .PP
1071 To read the contents of the file \f(CW\*(C`file1.txt\*(C'\fR and write the compressed
1072 data to the file \f(CW\*(C`file1.txt.zip\*(C'\fR there are a few options
1073 .PP
1074 Start by creating the compression object and opening the input file
1075 .PP
1076 .Vb 3
1077 \& use strict ;
1078 \& use warnings ;
1079 \& use IO::Compress::Zip qw(zip $ZipError) ;
1080 \&
1081 \& my $input = "file1.txt";
1082 \& my $z = IO::Compress::Zip\->new("file1.txt.zip")
1083 \& or die "IO::Compress::Zip failed: $ZipError\en";
1084 \&
1085 \& # open the input file
1086 \& open my $fh, "<", "file1.txt"
1087 \& or die "Cannot open file1.txt: $!\en";
1088 \&
1089 \& # loop through the input file & write to the compressed file
1090 \& while (<$fh>) {
1091 \& $z\->print($_);
1092 \& }
1093 \&
1094 \& # not forgetting to close the compressed file
1095 \& $z\->close();
1096 .Ve
1097 .PP
1098 \fICompressing multiple files\fR
1099 .IX Subsection "Compressing multiple files"
1100 .PP
1101 To create a zip file, \f(CW\*(C`output.zip\*(C'\fR, that contains the compressed contents
1102 of the files \f(CW\*(C`alpha.txt\*(C'\fR and \f(CW\*(C`beta.txt\*(C'\fR
1103 .PP
1104 .Vb 3
1105 \& use strict ;
1106 \& use warnings ;
1107 \& use IO::Compress::Zip qw(zip $ZipError) ;
1108 \&
1109 \& my $z = IO::Compress::Zip\->new("output.zip", Name => "alpha.txt")
1110 \& or die "IO::Compress::Zip failed: $ZipError\en";
1111 \&
1112 \& # open the input file
1113 \& open my $fh, "<", "file1.txt"
1114 \& or die "Cannot open file1.txt: $!\en";
1115 \&
1116 \& # loop through the input file & write to the compressed file
1117 \& while (<$fh>) {
1118 \& $z\->print($_);
1119 \& }
1120 \&
1121 \& # move to next file
1122 \& $z\->newStream(Name => "beta.txt")
1123 \&
1124 \& while (<$fh>) {
1125 \& $z\->print($_);
1126 \& }
1127 \&
1128 \& $z\->close();
1129 .Ve
1130 .SH Methods
1131 .IX Header "Methods"
1132 .SS print
1133 .IX Subsection "print"
1134 Usage is
1135 .PP
1136 .Vb 2
1137 \& $z\->print($data)
1138 \& print $z $data
1139 .Ve
1140 .PP
1141 Compresses and outputs the contents of the \f(CW$data\fR parameter. This
1142 has the same behaviour as the \f(CW\*(C`print\*(C'\fR built\-in.
1143 .PP
1144 Returns true if successful.
1145 .SS printf
1146 .IX Subsection "printf"
1147 Usage is
1148 .PP
1149 .Vb 2
1150 \& $z\->printf($format, $data)
1151 \& printf $z $format, $data
1152 .Ve
1153 .PP
1154 Compresses and outputs the contents of the \f(CW$data\fR parameter.
1155 .PP
1156 Returns true if successful.
1157 .SS syswrite
1158 .IX Subsection "syswrite"
1159 Usage is
1160 .PP
1161 .Vb 3
1162 \& $z\->syswrite $data
1163 \& $z\->syswrite $data, $length
1164 \& $z\->syswrite $data, $length, $offset
1165 .Ve
1166 .PP
1167 Compresses and outputs the contents of the \f(CW$data\fR parameter.
1168 .PP
1169 Returns the number of uncompressed bytes written, or \f(CW\*(C`undef\*(C'\fR if
1170 unsuccessful.
1171 .SS write
1172 .IX Subsection "write"
1173 Usage is
1174 .PP
1175 .Vb 3
1176 \& $z\->write $data
1177 \& $z\->write $data, $length
1178 \& $z\->write $data, $length, $offset
1179 .Ve
1180 .PP
1181 Compresses and outputs the contents of the \f(CW$data\fR parameter.
1182 .PP
1183 Returns the number of uncompressed bytes written, or \f(CW\*(C`undef\*(C'\fR if
1184 unsuccessful.
1185 .SS flush
1186 .IX Subsection "flush"
1187 Usage is
1188 .PP
1189 .Vb 2
1190 \& $z\->flush;
1191 \& $z\->flush($flush_type);
1192 .Ve
1193 .PP
1194 Flushes any pending compressed data to the output file/buffer.
1195 .PP
1196 This method takes an optional parameter, \f(CW$flush_type\fR, that controls
1197 how the flushing will be carried out. By default the \f(CW$flush_type\fR
1198 used is \f(CW\*(C`Z_FINISH\*(C'\fR. Other valid values for \f(CW$flush_type\fR are
1199 \&\f(CW\*(C`Z_NO_FLUSH\*(C'\fR, \f(CW\*(C`Z_SYNC_FLUSH\*(C'\fR, \f(CW\*(C`Z_FULL_FLUSH\*(C'\fR and \f(CW\*(C`Z_BLOCK\*(C'\fR. It is
1200 strongly recommended that you only set the \f(CW\*(C`flush_type\*(C'\fR parameter if
1201 you fully understand the implications of what it does \- overuse of \f(CW\*(C`flush\*(C'\fR
1202 can seriously degrade the level of compression achieved. See the \f(CW\*(C`zlib\*(C'\fR
1203 documentation for details.
1204 .PP
1205 Returns true on success.
1206 .SS tell
1207 .IX Subsection "tell"
1208 Usage is
1209 .PP
1210 .Vb 2
1211 \& $z\->tell()
1212 \& tell $z
1213 .Ve
1214 .PP
1215 Returns the uncompressed file offset.
1216 .SS eof
1217 .IX Subsection "eof"
1218 Usage is
1219 .PP
1220 .Vb 2
1221 \& $z\->eof();
1222 \& eof($z);
1223 .Ve
1224 .PP
1225 Returns true if the \f(CW\*(C`close\*(C'\fR method has been called.
1226 .SS seek
1227 .IX Subsection "seek"
1228 .Vb 2
1229 \& $z\->seek($position, $whence);
1230 \& seek($z, $position, $whence);
1231 .Ve
1232 .PP
1233 Provides a sub\-set of the \f(CW\*(C`seek\*(C'\fR functionality, with the restriction
1234 that it is only legal to seek forward in the output file/buffer.
1235 It is a fatal error to attempt to seek backward.
1236 .PP
1237 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
1238 .PP
1239 The \f(CW$whence\fR parameter takes one the usual values, namely SEEK_SET,
1240 SEEK_CUR or SEEK_END.
1241 .PP
1242 Returns 1 on success, 0 on failure.
1243 .SS binmode
1244 .IX Subsection "binmode"
1245 Usage is
1246 .PP
1247 .Vb 2
1248 \& $z\->binmode
1249 \& binmode $z ;
1250 .Ve
1251 .PP
1252 This is a noop provided for completeness.
1253 .SS opened
1254 .IX Subsection "opened"
1255 .Vb 1
1256 \& $z\->opened()
1257 .Ve
1258 .PP
1259 Returns true if the object currently refers to a opened file/buffer.
1260 .SS autoflush
1261 .IX Subsection "autoflush"
1262 .Vb 2
1263 \& my $prev = $z\->autoflush()
1264 \& my $prev = $z\->autoflush(EXPR)
1265 .Ve
1266 .PP
1267 If the \f(CW$z\fR object is associated with a file or a filehandle, this method
1268 returns the current autoflush setting for the underlying filehandle. If
1269 \&\f(CW\*(C`EXPR\*(C'\fR is present, and is non\-zero, it will enable flushing after every
1270 write/print operation.
1271 .PP
1272 If \f(CW$z\fR is associated with a buffer, this method has no effect and always
1273 returns \f(CW\*(C`undef\*(C'\fR.
1274 .PP
1275 \&\fBNote\fR that the special variable \f(CW$|\fR \fBcannot\fR be used to set or
1276 retrieve the autoflush setting.
1277 .SS input_line_number
1278 .IX Subsection "input_line_number"
1279 .Vb 2
1280 \& $z\->input_line_number()
1281 \& $z\->input_line_number(EXPR)
1282 .Ve
1283 .PP
1284 This method always returns \f(CW\*(C`undef\*(C'\fR when compressing.
1285 .SS fileno
1286 .IX Subsection "fileno"
1287 .Vb 2
1288 \& $z\->fileno()
1289 \& fileno($z)
1290 .Ve
1291 .PP
1292 If the \f(CW$z\fR object is associated with a file or a filehandle, \f(CW\*(C`fileno\*(C'\fR
1293 will return the underlying file descriptor. Once the \f(CW\*(C`close\*(C'\fR method is
1294 called \f(CW\*(C`fileno\*(C'\fR will return \f(CW\*(C`undef\*(C'\fR.
1295 .PP
1296 If the \f(CW$z\fR object is associated with a buffer, this method will return
1297 \&\f(CW\*(C`undef\*(C'\fR.
1298 .SS close
1299 .IX Subsection "close"
1300 .Vb 2
1301 \& $z\->close() ;
1302 \& close $z ;
1303 .Ve
1304 .PP
1305 Flushes any pending compressed data and then closes the output file/buffer.
1306 .PP
1307 For most versions of Perl this method will be automatically invoked if
1308 the IO::Compress::Zip object is destroyed (either explicitly or by the
1309 variable with the reference to the object going out of scope). The
1310 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1311 these cases, the \f(CW\*(C`close\*(C'\fR method will be called automatically, but
1312 not until global destruction of all live objects when the program is
1313 terminating.
1314 .PP
1315 Therefore, if you want your scripts to be able to run on all versions
1316 of Perl, you should call \f(CW\*(C`close\*(C'\fR explicitly and not rely on automatic
1317 closing.
1318 .PP
1319 Returns true on success, otherwise 0.
1320 .PP
1321 If the \f(CW\*(C`AutoClose\*(C'\fR option has been enabled when the IO::Compress::Zip
1322 object was created, and the object is associated with a file, the
1323 underlying file will also be closed.
1324 .SS newStream([OPTS])
1325 .IX Subsection "newStream([OPTS])"
1326 Usage is
1327 .PP
1328 .Vb 1
1329 \& $z\->newStream( [OPTS] )
1330 .Ve
1331 .PP
1332 Closes the current compressed data stream and starts a new one.
1333 .PP
1334 OPTS consists of any of the options that are available when creating
1335 the \f(CW$z\fR object.
1336 .PP
1337 See the "Constructor Options" section for more details.
1338 .SS deflateParams
1339 .IX Subsection "deflateParams"
1340 Usage is
1341 .PP
1342 .Vb 1
1343 \& $z\->deflateParams
1344 .Ve
1345 .PP
1346 TODO
1347 .SH Importing
1348 .IX Header "Importing"
1349 A number of symbolic constants are required by some methods in
1350 \&\f(CW\*(C`IO::Compress::Zip\*(C'\fR. None are imported by default.
1351 .IP :all 5
1352 .IX Item ":all"
1353 Imports \f(CW\*(C`zip\*(C'\fR, \f(CW$ZipError\fR and all symbolic
1354 constants that can be used by \f(CW\*(C`IO::Compress::Zip\*(C'\fR. Same as doing this
1355 .Sp
1356 .Vb 1
1357 \& use IO::Compress::Zip qw(zip $ZipError :constants) ;
1358 .Ve
1359 .IP :constants 5
1360 .IX Item ":constants"
1361 Import all symbolic constants. Same as doing this
1362 .Sp
1363 .Vb 1
1364 \& use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
1365 .Ve
1366 .IP :flush 5
1367 .IX Item ":flush"
1368 These symbolic constants are used by the \f(CW\*(C`flush\*(C'\fR method.
1369 .Sp
1370 .Vb 6
1371 \& Z_NO_FLUSH
1372 \& Z_PARTIAL_FLUSH
1373 \& Z_SYNC_FLUSH
1374 \& Z_FULL_FLUSH
1375 \& Z_FINISH
1376 \& Z_BLOCK
1377 .Ve
1378 .IP :level 5
1379 .IX Item ":level"
1380 These symbolic constants are used by the \f(CW\*(C`Level\*(C'\fR option in the constructor.
1381 .Sp
1382 .Vb 4
1383 \& Z_NO_COMPRESSION
1384 \& Z_BEST_SPEED
1385 \& Z_BEST_COMPRESSION
1386 \& Z_DEFAULT_COMPRESSION
1387 .Ve
1388 .IP :strategy 5
1389 .IX Item ":strategy"
1390 These symbolic constants are used by the \f(CW\*(C`Strategy\*(C'\fR option in the constructor.
1391 .Sp
1392 .Vb 5
1393 \& Z_FILTERED
1394 \& Z_HUFFMAN_ONLY
1395 \& Z_RLE
1396 \& Z_FIXED
1397 \& Z_DEFAULT_STRATEGY
1398 .Ve
1399 .IP :zip_method 5
1400 .IX Item ":zip_method"
1401 These symbolic constants are used by the \f(CW\*(C`Method\*(C'\fR option in the
1402 constructor.
1403 .Sp
1404 .Vb 3
1405 \& ZIP_CM_STORE
1406 \& ZIP_CM_DEFLATE
1407 \& ZIP_CM_BZIP2
1408 .Ve
1409 .SH EXAMPLES
1410 .IX Header "EXAMPLES"
1411 .SS "Apache::GZip Revisited"
1412 .IX Subsection "Apache::GZip Revisited"
1413 See IO::Compress::FAQ
1414 .SS "Working with Net::FTP"
1415 .IX Subsection "Working with Net::FTP"
1416 See IO::Compress::FAQ
1417 .SH SUPPORT
1418 .IX Header "SUPPORT"
1419 General feedback/questions/bug reports should be sent to
1420 <https://github.com/pmqs/IO\-Compress/issues> (preferred) or
1421 <https://rt.cpan.org/Public/Dist/Display.html?Name=IO\-Compress>.
1422 .SH "SEE ALSO"
1423 .IX Header "SEE ALSO"
1424 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, IO::Compress::Deflate, IO::Uncompress::Inflate, IO::Compress::RawDeflate, IO::Uncompress::RawInflate, IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
1425 .PP
1426 IO::Compress::FAQ
1427 .PP
1428 File::GlobMapper, Archive::Zip,
1429 Archive::Tar,
1430 IO::Zlib
1431 .PP
1432 For RFC 1950, 1951 and 1952 see
1433 <https://datatracker.ietf.org/doc/html/rfc1950>,
1434 <https://datatracker.ietf.org/doc/html/rfc1951> and
1435 <https://datatracker.ietf.org/doc/html/rfc1952>
1436 .PP
1437 The \fIzlib\fR compression library was written by Jean\-loup Gailly
1438 \&\f(CW\*(C`[email protected]\*(C'\fR and Mark Adler \f(CW\*(C`[email protected]\*(C'\fR.
1439 .PP
1440 The primary site for the \fIzlib\fR compression library is
1441 <http://www.zlib.org>.
1442 .PP
1443 The primary site for the \fIzlib\-ng\fR compression library is
1444 <https://github.com/zlib\-ng/zlib\-ng>.
1445 .PP
1446 The primary site for gzip is <http://www.gzip.org>.
1447 .SH AUTHOR
1448 .IX Header "AUTHOR"
1449 This module was written by Paul Marquess, \f(CW\*(C`[email protected]\*(C'\fR.
1450 .SH "MODIFICATION HISTORY"
1451 .IX Header "MODIFICATION HISTORY"
1452 See the Changes file.
1453 .SH "COPYRIGHT AND LICENSE"
1454 .IX Header "COPYRIGHT AND LICENSE"
1455 Copyright (c) 2005\-2024 Paul Marquess. All rights reserved.
1456 .PP
1457 This program is free software; you can redistribute it and/or
1458 modify it under the same terms as Perl itself.