Debian Codegraph @

upstream/debian-unstable/man3/IO::Compress::Zip.3perl

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