Debian Codegraph @

upstream/debian-unstable/man3/IO::Compress::Deflate.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::Deflate 3perl"
58 .TH IO::Compress::Deflate 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::Deflate \- Write RFC 1950 files/buffers
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use IO::Compress::Deflate qw(deflate $DeflateError) ;
69 \&
70 \& my $status = deflate $input => $output [,OPTS]
71 \& or die "deflate failed: $DeflateError\en";
72 \&
73 \& my $z = IO::Compress::Deflate\->new( $output [,OPTS] )
74 \& or die "deflate failed: $DeflateError\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 \& $DeflateError ;
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 compressed
111 data to files or buffer as defined in RFC 1950.
112 .PP
113 For reading RFC 1950 files/buffers, see the companion module
114 IO::Uncompress::Inflate.
115 .SH "Functional Interface"
116 .IX Header "Functional Interface"
117 A top-level function, \f(CW\*(C`deflate\*(C'\fR, is provided to carry out
118 "one-shot" compression between buffers and/or files. For finer
119 control over the compression process, see the "OO Interface"
120 section.
121 .PP
122 .Vb 1
123 \& use IO::Compress::Deflate qw(deflate $DeflateError) ;
124 \&
125 \& deflate $input_filename_or_reference => $output_filename_or_reference [,OPTS]
126 \& or die "deflate failed: $DeflateError\en";
127 .Ve
128 .PP
129 The functional interface needs Perl5.005 or better.
130 .ie n .SS "deflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
131 .el .SS "deflate \f(CW$input_filename_or_reference\fP => \f(CW$output_filename_or_reference\fP [, OPTS]"
132 .IX Subsection "deflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
133 \&\f(CW\*(C`deflate\*(C'\fR expects at least two parameters,
134 \&\f(CW$input_filename_or_reference\fR and \f(CW$output_filename_or_reference\fR
135 and zero or more optional parameters (see "Optional Parameters")
136 .PP
137 \fIThe \fR\f(CI$input_filename_or_reference\fR\fI parameter\fR
138 .IX Subsection "The $input_filename_or_reference parameter"
139 .PP
140 The parameter, \f(CW$input_filename_or_reference\fR, is used to define the
141 source of the uncompressed data.
142 .PP
143 It can take one of the following forms:
144 .IP "A filename" 5
145 .IX Item "A filename"
146 If the \f(CW$input_filename_or_reference\fR parameter is a simple scalar, it is
147 assumed to be a filename. This file will be opened for reading and the
148 input data will be read from it.
149 .IP "A filehandle" 5
150 .IX Item "A filehandle"
151 If the \f(CW$input_filename_or_reference\fR parameter is a filehandle, the input
152 data will be read from it. The string '\-' can be used as an alias for
153 standard input.
154 .IP "A scalar reference" 5
155 .IX Item "A scalar reference"
156 If \f(CW$input_filename_or_reference\fR is a scalar reference, the input data
157 will be read from \f(CW$$input_filename_or_reference\fR.
158 .IP "An array reference" 5
159 .IX Item "An array reference"
160 If \f(CW$input_filename_or_reference\fR is an array reference, each element in
161 the array must be a filename.
162 .Sp
163 The input data will be read from each file in turn.
164 .Sp
165 The complete array will be walked to ensure that it only
166 contains valid filenames before any data is compressed.
167 .IP "An Input FileGlob string" 5
168 .IX Item "An Input FileGlob string"
169 If \f(CW$input_filename_or_reference\fR is a string that is delimited by the
170 characters "<" and ">" \f(CW\*(C`deflate\*(C'\fR will assume that it is an
171 \&\fIinput fileglob string\fR. The input is the list of files that match the
172 fileglob.
173 .Sp
174 See File::GlobMapper for more details.
175 .PP
176 If the \f(CW$input_filename_or_reference\fR parameter is any other type,
177 \&\f(CW\*(C`undef\*(C'\fR will be returned.
178 .PP
179 \fIThe \fR\f(CI$output_filename_or_reference\fR\fI parameter\fR
180 .IX Subsection "The $output_filename_or_reference parameter"
181 .PP
182 The parameter \f(CW$output_filename_or_reference\fR is used to control the
183 destination of the compressed data. This parameter can take one of
184 these forms.
185 .IP "A filename" 5
186 .IX Item "A filename"
187 If the \f(CW$output_filename_or_reference\fR parameter is a simple scalar, it is
188 assumed to be a filename. This file will be opened for writing and the
189 compressed data will be written to it.
190 .IP "A filehandle" 5
191 .IX Item "A filehandle"
192 If the \f(CW$output_filename_or_reference\fR parameter is a filehandle, the
193 compressed data will be written to it. The string '\-' can be used as
194 an alias for standard output.
195 .IP "A scalar reference" 5
196 .IX Item "A scalar reference"
197 If \f(CW$output_filename_or_reference\fR is a scalar reference, the
198 compressed data will be stored in \f(CW$$output_filename_or_reference\fR.
199 .IP "An Array Reference" 5
200 .IX Item "An Array Reference"
201 If \f(CW$output_filename_or_reference\fR is an array reference,
202 the compressed data will be pushed onto the array.
203 .IP "An Output FileGlob" 5
204 .IX Item "An Output FileGlob"
205 If \f(CW$output_filename_or_reference\fR is a string that is delimited by the
206 characters "<" and ">" \f(CW\*(C`deflate\*(C'\fR will assume that it is an
207 \&\fIoutput fileglob string\fR. The output is the list of files that match the
208 fileglob.
209 .Sp
210 When \f(CW$output_filename_or_reference\fR is an fileglob string,
211 \&\f(CW$input_filename_or_reference\fR must also be a fileglob string. Anything
212 else is an error.
213 .Sp
214 See File::GlobMapper for more details.
215 .PP
216 If the \f(CW$output_filename_or_reference\fR parameter is any other type,
217 \&\f(CW\*(C`undef\*(C'\fR will be returned.
218 .SS Notes
219 .IX Subsection "Notes"
220 When \f(CW$input_filename_or_reference\fR maps to multiple files/buffers and
221 \&\f(CW$output_filename_or_reference\fR is a single
222 file/buffer the input files/buffers will be stored
223 in \f(CW$output_filename_or_reference\fR as a concatenated series of compressed data streams.
224 .SS "Optional Parameters"
225 .IX Subsection "Optional Parameters"
226 The optional parameters for the one-shot function \f(CW\*(C`deflate\*(C'\fR
227 are (for the most part) identical to those used with the OO interface defined in the
228 "Constructor Options" section. The exceptions are listed below
229 .ie n .IP """AutoClose => 0|1""" 5
230 .el .IP "\f(CWAutoClose => 0|1\fR" 5
231 .IX Item "AutoClose => 0|1"
232 This option applies to any input or output data streams to
233 \&\f(CW\*(C`deflate\*(C'\fR that are filehandles.
234 .Sp
235 If \f(CW\*(C`AutoClose\*(C'\fR is specified, and the value is true, it will result in all
236 input and/or output filehandles being closed once \f(CW\*(C`deflate\*(C'\fR has
237 completed.
238 .Sp
239 This parameter defaults to 0.
240 .ie n .IP """BinModeIn => 0|1""" 5
241 .el .IP "\f(CWBinModeIn => 0|1\fR" 5
242 .IX Item "BinModeIn => 0|1"
243 This option is now a no-op. All files will be read in binmode.
244 .ie n .IP """Append => 0|1""" 5
245 .el .IP "\f(CWAppend => 0|1\fR" 5
246 .IX Item "Append => 0|1"
247 The behaviour of this option is dependent on the type of output data
248 stream.
249 .RS 5
250 .IP \(bu 5
251 A Buffer
252 .Sp
253 If \f(CW\*(C`Append\*(C'\fR is enabled, all compressed data will be append to the end of
254 the output buffer. Otherwise the output buffer will be cleared before any
255 compressed data is written to it.
256 .IP \(bu 5
257 A Filename
258 .Sp
259 If \f(CW\*(C`Append\*(C'\fR is enabled, the file will be opened in append mode. Otherwise
260 the contents of the file, if any, will be truncated before any compressed
261 data is written to it.
262 .IP \(bu 5
263 A Filehandle
264 .Sp
265 If \f(CW\*(C`Append\*(C'\fR is enabled, the filehandle will be positioned to the end of
266 the file via a call to \f(CW\*(C`seek\*(C'\fR before any compressed data is
267 written to it. Otherwise the file pointer will not be moved.
268 .RE
269 .RS 5
270 .Sp
271 When \f(CW\*(C`Append\*(C'\fR is specified, and set to true, it will \fIappend\fR all compressed
272 data to the output data stream.
273 .Sp
274 So when the output is a filehandle it will carry out a seek to the eof
275 before writing any compressed data. If the output is a filename, it will be opened for
276 appending. If the output is a buffer, all compressed data will be
277 appended to the existing buffer.
278 .Sp
279 Conversely when \f(CW\*(C`Append\*(C'\fR is not specified, or it is present and is set to
280 false, it will operate as follows.
281 .Sp
282 When the output is a filename, it will truncate the contents of the file
283 before writing any compressed data. If the output is a filehandle
284 its position will not be changed. If the output is a buffer, it will be
285 wiped before any compressed data is output.
286 .Sp
287 Defaults to 0.
288 .RE
289 .SS "Oneshot Examples"
290 .IX Subsection "Oneshot Examples"
291 Here are a few example that show the capabilities of the module.
292 .PP
293 \fIStreaming\fR
294 .IX Subsection "Streaming"
295 .PP
296 This very simple command line example demonstrates the streaming capabilities of the module.
297 The code reads data from STDIN, compresses it, and writes the compressed data to STDOUT.
298 .PP
299 .Vb 1
300 \& $ echo hello world | perl \-MIO::Compress::Deflate=deflate \-e \*(Aqdeflate \e*STDIN => \e*STDOUT\*(Aq >output.1950
301 .Ve
302 .PP
303 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,
304 so the above can be rewritten as
305 .PP
306 .Vb 1
307 \& $ echo hello world | perl \-MIO::Compress::Deflate=deflate \-e \*(Aqdeflate "\-" => "\-"\*(Aq >output.1950
308 .Ve
309 .PP
310 \fICompressing a file from the filesystem\fR
311 .IX Subsection "Compressing a file from the filesystem"
312 .PP
313 To read the contents of the file \f(CW\*(C`file1.txt\*(C'\fR and write the compressed
314 data to the file \f(CW\*(C`file1.txt.1950\*(C'\fR.
315 .PP
316 .Vb 3
317 \& use strict ;
318 \& use warnings ;
319 \& use IO::Compress::Deflate qw(deflate $DeflateError) ;
320 \&
321 \& my $input = "file1.txt";
322 \& deflate $input => "$input.1950"
323 \& or die "deflate failed: $DeflateError\en";
324 .Ve
325 .PP
326 \fIReading from a Filehandle and writing to an in-memory buffer\fR
327 .IX Subsection "Reading from a Filehandle and writing to an in-memory buffer"
328 .PP
329 To read from an existing Perl filehandle, \f(CW$input\fR, and write the
330 compressed data to a buffer, \f(CW$buffer\fR.
331 .PP
332 .Vb 4
333 \& use strict ;
334 \& use warnings ;
335 \& use IO::Compress::Deflate qw(deflate $DeflateError) ;
336 \& use IO::File ;
337 \&
338 \& my $input = IO::File\->new( "<file1.txt" )
339 \& or die "Cannot open \*(Aqfile1.txt\*(Aq: $!\en" ;
340 \& my $buffer ;
341 \& deflate $input => \e$buffer
342 \& or die "deflate failed: $DeflateError\en";
343 .Ve
344 .PP
345 \fICompressing multiple files\fR
346 .IX Subsection "Compressing multiple files"
347 .PP
348 To compress all files in the directory "/my/home" that match "*.txt"
349 and store the compressed data in the same directory
350 .PP
351 .Vb 3
352 \& use strict ;
353 \& use warnings ;
354 \& use IO::Compress::Deflate qw(deflate $DeflateError) ;
355 \&
356 \& deflate \*(Aq</my/home/*.txt>\*(Aq => \*(Aq<*.1950>\*(Aq
357 \& or die "deflate failed: $DeflateError\en";
358 .Ve
359 .PP
360 and if you want to compress each file one at a time, this will do the trick
361 .PP
362 .Vb 3
363 \& use strict ;
364 \& use warnings ;
365 \& use IO::Compress::Deflate qw(deflate $DeflateError) ;
366 \&
367 \& for my $input ( glob "/my/home/*.txt" )
368 \& {
369 \& my $output = "$input.1950" ;
370 \& deflate $input => $output
371 \& or die "Error compressing \*(Aq$input\*(Aq: $DeflateError\en";
372 \& }
373 .Ve
374 .SH "OO Interface"
375 .IX Header "OO Interface"
376 .SS Constructor
377 .IX Subsection "Constructor"
378 The format of the constructor for \f(CW\*(C`IO::Compress::Deflate\*(C'\fR is shown below
379 .PP
380 .Vb 2
381 \& my $z = IO::Compress::Deflate\->new( $output [,OPTS] )
382 \& or die "IO::Compress::Deflate failed: $DeflateError\en";
383 .Ve
384 .PP
385 The constructor takes one mandatory parameter, \f(CW$output\fR, defined below and
386 zero or more \f(CW\*(C`OPTS\*(C'\fR, defined in "Constructor Options".
387 .PP
388 It returns an \f(CW\*(C`IO::Compress::Deflate\*(C'\fR object on success and \f(CW\*(C`undef\*(C'\fR on failure.
389 The variable \f(CW$DeflateError\fR will contain an error message on failure.
390 .PP
391 If you are running Perl 5.005 or better the object, \f(CW$z\fR, returned from
392 IO::Compress::Deflate can be used exactly like an IO::File filehandle.
393 This means that all normal output file operations can be carried out
394 with \f(CW$z\fR.
395 For example, to write to a compressed file/buffer you can use either of
396 these forms
397 .PP
398 .Vb 2
399 \& $z\->print("hello world\en");
400 \& print $z "hello world\en";
401 .Ve
402 .PP
403 Below is a simple exaple of using the OO interface to create an output file
404 \&\f(CW\*(C`myfile.1950\*(C'\fR and write some data to it.
405 .PP
406 .Vb 3
407 \& my $filename = "myfile.1950";
408 \& my $z = IO::Compress::Deflate\->new($filename)
409 \& or die "IO::Compress::Deflate failed: $DeflateError\en";
410 \&
411 \& $z\->print("abcde");
412 \& $z\->close();
413 .Ve
414 .PP
415 See the "Examples" for more.
416 .PP
417 The mandatory parameter \f(CW$output\fR is used to control the destination
418 of the compressed data. This parameter can take one of these forms.
419 .IP "A filename" 5
420 .IX Item "A filename"
421 If the \f(CW$output\fR parameter is a simple scalar, it is assumed to be a
422 filename. This file will be opened for writing and the compressed data
423 will be written to it.
424 .IP "A filehandle" 5
425 .IX Item "A filehandle"
426 If the \f(CW$output\fR parameter is a filehandle, the compressed data will be
427 written to it.
428 The string '\-' can be used as an alias for standard output.
429 .IP "A scalar reference" 5
430 .IX Item "A scalar reference"
431 If \f(CW$output\fR is a scalar reference, the compressed data will be stored
432 in \f(CW$$output\fR.
433 .PP
434 If the \f(CW$output\fR parameter is any other type, \f(CW\*(C`IO::Compress::Deflate\*(C'\fR::new will
435 return undef.
436 .SS "Constructor Options"
437 .IX Subsection "Constructor Options"
438 \&\f(CW\*(C`OPTS\*(C'\fR is any combination of zero or more the following options:
439 .ie n .IP """AutoClose => 0|1""" 5
440 .el .IP "\f(CWAutoClose => 0|1\fR" 5
441 .IX Item "AutoClose => 0|1"
442 This option is only valid when the \f(CW$output\fR parameter is a filehandle. If
443 specified, and the value is true, it will result in the \f(CW$output\fR being
444 closed once either the \f(CW\*(C`close\*(C'\fR method is called or the \f(CW\*(C`IO::Compress::Deflate\*(C'\fR
445 object is destroyed.
446 .Sp
447 This parameter defaults to 0.
448 .ie n .IP """Append => 0|1""" 5
449 .el .IP "\f(CWAppend => 0|1\fR" 5
450 .IX Item "Append => 0|1"
451 Opens \f(CW$output\fR in append mode.
452 .Sp
453 The behaviour of this option is dependent on the type of \f(CW$output\fR.
454 .RS 5
455 .IP \(bu 5
456 A Buffer
457 .Sp
458 If \f(CW$output\fR is a buffer and \f(CW\*(C`Append\*(C'\fR is enabled, all compressed data
459 will be append to the end of \f(CW$output\fR. Otherwise \f(CW$output\fR will be
460 cleared before any data is written to it.
461 .IP \(bu 5
462 A Filename
463 .Sp
464 If \f(CW$output\fR is a filename and \f(CW\*(C`Append\*(C'\fR is enabled, the file will be
465 opened in append mode. Otherwise the contents of the file, if any, will be
466 truncated before any compressed data is written to it.
467 .IP \(bu 5
468 A Filehandle
469 .Sp
470 If \f(CW$output\fR is a filehandle, the file pointer will be positioned to the
471 end of the file via a call to \f(CW\*(C`seek\*(C'\fR before any compressed data is written
472 to it. Otherwise the file pointer will not be moved.
473 .RE
474 .RS 5
475 .Sp
476 This parameter defaults to 0.
477 .RE
478 .ie n .IP """Merge => 0|1""" 5
479 .el .IP "\f(CWMerge => 0|1\fR" 5
480 .IX Item "Merge => 0|1"
481 This option is used to compress input data and append it to an existing
482 compressed data stream in \f(CW$output\fR. The end result is a single compressed
483 data stream stored in \f(CW$output\fR.
484 .Sp
485 It is a fatal error to attempt to use this option when \f(CW$output\fR is not an
486 RFC 1950 data stream.
487 .Sp
488 There are a number of other limitations with the \f(CW\*(C`Merge\*(C'\fR option:
489 .RS 5
490 .IP 1. 5
491 This module needs to have been built with zlib 1.2.1 or better to work. A
492 fatal error will be thrown if \f(CW\*(C`Merge\*(C'\fR is used with an older version of
493 zlib.
494 .IP 2. 5
495 If \f(CW$output\fR is a file or a filehandle, it must be seekable.
496 .RE
497 .RS 5
498 .Sp
499 This parameter defaults to 0.
500 .RE
501 .IP \-Level 5
502 .IX Item "-Level"
503 Defines the compression level used by zlib. The value should either be
504 a number between 0 and 9 (0 means no compression and 9 is maximum
505 compression), or one of the symbolic constants defined below.
506 .Sp
507 .Vb 4
508 \& Z_NO_COMPRESSION
509 \& Z_BEST_SPEED
510 \& Z_BEST_COMPRESSION
511 \& Z_DEFAULT_COMPRESSION
512 .Ve
513 .Sp
514 The default is Z_DEFAULT_COMPRESSION.
515 .Sp
516 Note, these constants are not imported by \f(CW\*(C`IO::Compress::Deflate\*(C'\fR by default.
517 .Sp
518 .Vb 3
519 \& use IO::Compress::Deflate qw(:strategy);
520 \& use IO::Compress::Deflate qw(:constants);
521 \& use IO::Compress::Deflate qw(:all);
522 .Ve
523 .IP \-Strategy 5
524 .IX Item "-Strategy"
525 Defines the strategy used to tune the compression. Use one of the symbolic
526 constants defined below.
527 .Sp
528 .Vb 5
529 \& Z_FILTERED
530 \& Z_HUFFMAN_ONLY
531 \& Z_RLE
532 \& Z_FIXED
533 \& Z_DEFAULT_STRATEGY
534 .Ve
535 .Sp
536 The default is Z_DEFAULT_STRATEGY.
537 .ie n .IP """Strict => 0|1""" 5
538 .el .IP "\f(CWStrict => 0|1\fR" 5
539 .IX Item "Strict => 0|1"
540 This is a placeholder option.
541 .SS Examples
542 .IX Subsection "Examples"
543 \fIStreaming\fR
544 .IX Subsection "Streaming"
545 .PP
546 This very simple command line example demonstrates the streaming capabilities
547 of the module. The code reads data from STDIN or all the files given on the
548 commandline, compresses it, and writes the compressed data to STDOUT.
549 .PP
550 .Vb 3
551 \& use strict ;
552 \& use warnings ;
553 \& use IO::Compress::Deflate qw(deflate $DeflateError) ;
554 \&
555 \& my $z = IO::Compress::Deflate\->new("\-", Stream => 1)
556 \& or die "IO::Compress::Deflate failed: $DeflateError\en";
557 \&
558 \& while (<>) {
559 \& $z\->print("abcde");
560 \& }
561 \& $z\->close();
562 .Ve
563 .PP
564 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.
565 .PP
566 \fICompressing a file from the filesystem\fR
567 .IX Subsection "Compressing a file from the filesystem"
568 .PP
569 To read the contents of the file \f(CW\*(C`file1.txt\*(C'\fR and write the compressed
570 data to the file \f(CW\*(C`file1.txt.1950\*(C'\fR there are a few options
571 .PP
572 Start by creating the compression object and opening the input file
573 .PP
574 .Vb 3
575 \& use strict ;
576 \& use warnings ;
577 \& use IO::Compress::Deflate qw(deflate $DeflateError) ;
578 \&
579 \& my $input = "file1.txt";
580 \& my $z = IO::Compress::Deflate\->new("file1.txt.1950")
581 \& or die "IO::Compress::Deflate failed: $DeflateError\en";
582 \&
583 \& # open the input file
584 \& open my $fh, "<", "file1.txt"
585 \& or die "Cannot open file1.txt: $!\en";
586 \&
587 \& # loop through the input file & write to the compressed file
588 \& while (<$fh>) {
589 \& $z\->print($_);
590 \& }
591 \&
592 \& # not forgetting to close the compressed file
593 \& $z\->close();
594 .Ve
595 .SH Methods
596 .IX Header "Methods"
597 .SS print
598 .IX Subsection "print"
599 Usage is
600 .PP
601 .Vb 2
602 \& $z\->print($data)
603 \& print $z $data
604 .Ve
605 .PP
606 Compresses and outputs the contents of the \f(CW$data\fR parameter. This
607 has the same behaviour as the \f(CW\*(C`print\*(C'\fR built-in.
608 .PP
609 Returns true if successful.
610 .SS printf
611 .IX Subsection "printf"
612 Usage is
613 .PP
614 .Vb 2
615 \& $z\->printf($format, $data)
616 \& printf $z $format, $data
617 .Ve
618 .PP
619 Compresses and outputs the contents of the \f(CW$data\fR parameter.
620 .PP
621 Returns true if successful.
622 .SS syswrite
623 .IX Subsection "syswrite"
624 Usage is
625 .PP
626 .Vb 3
627 \& $z\->syswrite $data
628 \& $z\->syswrite $data, $length
629 \& $z\->syswrite $data, $length, $offset
630 .Ve
631 .PP
632 Compresses and outputs the contents of the \f(CW$data\fR parameter.
633 .PP
634 Returns the number of uncompressed bytes written, or \f(CW\*(C`undef\*(C'\fR if
635 unsuccessful.
636 .SS write
637 .IX Subsection "write"
638 Usage is
639 .PP
640 .Vb 3
641 \& $z\->write $data
642 \& $z\->write $data, $length
643 \& $z\->write $data, $length, $offset
644 .Ve
645 .PP
646 Compresses and outputs the contents of the \f(CW$data\fR parameter.
647 .PP
648 Returns the number of uncompressed bytes written, or \f(CW\*(C`undef\*(C'\fR if
649 unsuccessful.
650 .SS flush
651 .IX Subsection "flush"
652 Usage is
653 .PP
654 .Vb 2
655 \& $z\->flush;
656 \& $z\->flush($flush_type);
657 .Ve
658 .PP
659 Flushes any pending compressed data to the output file/buffer.
660 .PP
661 This method takes an optional parameter, \f(CW$flush_type\fR, that controls
662 how the flushing will be carried out. By default the \f(CW$flush_type\fR
663 used is \f(CW\*(C`Z_FINISH\*(C'\fR. Other valid values for \f(CW$flush_type\fR are
664 \&\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
665 strongly recommended that you only set the \f(CW\*(C`flush_type\*(C'\fR parameter if
666 you fully understand the implications of what it does \- overuse of \f(CW\*(C`flush\*(C'\fR
667 can seriously degrade the level of compression achieved. See the \f(CW\*(C`zlib\*(C'\fR
668 documentation for details.
669 .PP
670 Returns true on success.
671 .SS tell
672 .IX Subsection "tell"
673 Usage is
674 .PP
675 .Vb 2
676 \& $z\->tell()
677 \& tell $z
678 .Ve
679 .PP
680 Returns the uncompressed file offset.
681 .SS eof
682 .IX Subsection "eof"
683 Usage is
684 .PP
685 .Vb 2
686 \& $z\->eof();
687 \& eof($z);
688 .Ve
689 .PP
690 Returns true if the \f(CW\*(C`close\*(C'\fR method has been called.
691 .SS seek
692 .IX Subsection "seek"
693 .Vb 2
694 \& $z\->seek($position, $whence);
695 \& seek($z, $position, $whence);
696 .Ve
697 .PP
698 Provides a sub-set of the \f(CW\*(C`seek\*(C'\fR functionality, with the restriction
699 that it is only legal to seek forward in the output file/buffer.
700 It is a fatal error to attempt to seek backward.
701 .PP
702 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
703 .PP
704 The \f(CW$whence\fR parameter takes one the usual values, namely SEEK_SET,
705 SEEK_CUR or SEEK_END.
706 .PP
707 Returns 1 on success, 0 on failure.
708 .SS binmode
709 .IX Subsection "binmode"
710 Usage is
711 .PP
712 .Vb 2
713 \& $z\->binmode
714 \& binmode $z ;
715 .Ve
716 .PP
717 This is a noop provided for completeness.
718 .SS opened
719 .IX Subsection "opened"
720 .Vb 1
721 \& $z\->opened()
722 .Ve
723 .PP
724 Returns true if the object currently refers to a opened file/buffer.
725 .SS autoflush
726 .IX Subsection "autoflush"
727 .Vb 2
728 \& my $prev = $z\->autoflush()
729 \& my $prev = $z\->autoflush(EXPR)
730 .Ve
731 .PP
732 If the \f(CW$z\fR object is associated with a file or a filehandle, this method
733 returns the current autoflush setting for the underlying filehandle. If
734 \&\f(CW\*(C`EXPR\*(C'\fR is present, and is non-zero, it will enable flushing after every
735 write/print operation.
736 .PP
737 If \f(CW$z\fR is associated with a buffer, this method has no effect and always
738 returns \f(CW\*(C`undef\*(C'\fR.
739 .PP
740 \&\fBNote\fR that the special variable \f(CW$|\fR \fBcannot\fR be used to set or
741 retrieve the autoflush setting.
742 .SS input_line_number
743 .IX Subsection "input_line_number"
744 .Vb 2
745 \& $z\->input_line_number()
746 \& $z\->input_line_number(EXPR)
747 .Ve
748 .PP
749 This method always returns \f(CW\*(C`undef\*(C'\fR when compressing.
750 .SS fileno
751 .IX Subsection "fileno"
752 .Vb 2
753 \& $z\->fileno()
754 \& fileno($z)
755 .Ve
756 .PP
757 If the \f(CW$z\fR object is associated with a file or a filehandle, \f(CW\*(C`fileno\*(C'\fR
758 will return the underlying file descriptor. Once the \f(CW\*(C`close\*(C'\fR method is
759 called \f(CW\*(C`fileno\*(C'\fR will return \f(CW\*(C`undef\*(C'\fR.
760 .PP
761 If the \f(CW$z\fR object is associated with a buffer, this method will return
762 \&\f(CW\*(C`undef\*(C'\fR.
763 .SS close
764 .IX Subsection "close"
765 .Vb 2
766 \& $z\->close() ;
767 \& close $z ;
768 .Ve
769 .PP
770 Flushes any pending compressed data and then closes the output file/buffer.
771 .PP
772 For most versions of Perl this method will be automatically invoked if
773 the IO::Compress::Deflate object is destroyed (either explicitly or by the
774 variable with the reference to the object going out of scope). The
775 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
776 these cases, the \f(CW\*(C`close\*(C'\fR method will be called automatically, but
777 not until global destruction of all live objects when the program is
778 terminating.
779 .PP
780 Therefore, if you want your scripts to be able to run on all versions
781 of Perl, you should call \f(CW\*(C`close\*(C'\fR explicitly and not rely on automatic
782 closing.
783 .PP
784 Returns true on success, otherwise 0.
785 .PP
786 If the \f(CW\*(C`AutoClose\*(C'\fR option has been enabled when the IO::Compress::Deflate
787 object was created, and the object is associated with a file, the
788 underlying file will also be closed.
789 .SS newStream([OPTS])
790 .IX Subsection "newStream([OPTS])"
791 Usage is
792 .PP
793 .Vb 1
794 \& $z\->newStream( [OPTS] )
795 .Ve
796 .PP
797 Closes the current compressed data stream and starts a new one.
798 .PP
799 OPTS consists of any of the options that are available when creating
800 the \f(CW$z\fR object.
801 .PP
802 See the "Constructor Options" section for more details.
803 .SS deflateParams
804 .IX Subsection "deflateParams"
805 Usage is
806 .PP
807 .Vb 1
808 \& $z\->deflateParams
809 .Ve
810 .PP
811 TODO
812 .SH Importing
813 .IX Header "Importing"
814 A number of symbolic constants are required by some methods in
815 \&\f(CW\*(C`IO::Compress::Deflate\*(C'\fR. None are imported by default.
816 .IP :all 5
817 .IX Item ":all"
818 Imports \f(CW\*(C`deflate\*(C'\fR, \f(CW$DeflateError\fR and all symbolic
819 constants that can be used by \f(CW\*(C`IO::Compress::Deflate\*(C'\fR. Same as doing this
820 .Sp
821 .Vb 1
822 \& use IO::Compress::Deflate qw(deflate $DeflateError :constants) ;
823 .Ve
824 .IP :constants 5
825 .IX Item ":constants"
826 Import all symbolic constants. Same as doing this
827 .Sp
828 .Vb 1
829 \& use IO::Compress::Deflate qw(:flush :level :strategy) ;
830 .Ve
831 .IP :flush 5
832 .IX Item ":flush"
833 These symbolic constants are used by the \f(CW\*(C`flush\*(C'\fR method.
834 .Sp
835 .Vb 6
836 \& Z_NO_FLUSH
837 \& Z_PARTIAL_FLUSH
838 \& Z_SYNC_FLUSH
839 \& Z_FULL_FLUSH
840 \& Z_FINISH
841 \& Z_BLOCK
842 .Ve
843 .IP :level 5
844 .IX Item ":level"
845 These symbolic constants are used by the \f(CW\*(C`Level\*(C'\fR option in the constructor.
846 .Sp
847 .Vb 4
848 \& Z_NO_COMPRESSION
849 \& Z_BEST_SPEED
850 \& Z_BEST_COMPRESSION
851 \& Z_DEFAULT_COMPRESSION
852 .Ve
853 .IP :strategy 5
854 .IX Item ":strategy"
855 These symbolic constants are used by the \f(CW\*(C`Strategy\*(C'\fR option in the constructor.
856 .Sp
857 .Vb 5
858 \& Z_FILTERED
859 \& Z_HUFFMAN_ONLY
860 \& Z_RLE
861 \& Z_FIXED
862 \& Z_DEFAULT_STRATEGY
863 .Ve
864 .SH EXAMPLES
865 .IX Header "EXAMPLES"
866 .SS "Apache::GZip Revisited"
867 .IX Subsection "Apache::GZip Revisited"
868 See IO::Compress::FAQ
869 .SS "Working with Net::FTP"
870 .IX Subsection "Working with Net::FTP"
871 See IO::Compress::FAQ
872 .SH SUPPORT
873 .IX Header "SUPPORT"
874 General feedback/questions/bug reports should be sent to
875 <https://github.com/pmqs/IO\-Compress/issues> (preferred) or
876 <https://rt.cpan.org/Public/Dist/Display.html?Name=IO\-Compress>.
877 .SH "SEE ALSO"
878 .IX Header "SEE ALSO"
879 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, 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
880 .PP
881 IO::Compress::FAQ
882 .PP
883 File::GlobMapper, Archive::Zip,
884 Archive::Tar,
885 IO::Zlib
886 .PP
887 For RFC 1950, 1951 and 1952 see
888 <https://datatracker.ietf.org/doc/html/rfc1950>,
889 <https://datatracker.ietf.org/doc/html/rfc1951> and
890 <https://datatracker.ietf.org/doc/html/rfc1952>
891 .PP
892 The \fIzlib\fR compression library was written by Jean-loup Gailly
893 \&\f(CW\*(C`[email protected]\*(C'\fR and Mark Adler \f(CW\*(C`[email protected]\*(C'\fR.
894 .PP
895 The primary site for the \fIzlib\fR compression library is
896 <http://www.zlib.org>.
897 .PP
898 The primary site for the \fIzlib-ng\fR compression library is
899 <https://github.com/zlib\-ng/zlib\-ng>.
900 .PP
901 The primary site for gzip is <http://www.gzip.org>.
902 .SH AUTHOR
903 .IX Header "AUTHOR"
904 This module was written by Paul Marquess, \f(CW\*(C`[email protected]\*(C'\fR.
905 .SH "MODIFICATION HISTORY"
906 .IX Header "MODIFICATION HISTORY"
907 See the Changes file.
908 .SH "COPYRIGHT AND LICENSE"
909 .IX Header "COPYRIGHT AND LICENSE"
910 Copyright (c) 2005\-2024 Paul Marquess. All rights reserved.
911 .PP
912 This program is free software; you can redistribute it and/or
913 modify it under the same terms as Perl itself.