Debian Codegraph @

upstream/debian-unstable/man3/Compress::Raw::Zlib.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 "Compress::Raw::Zlib 3perl"
58 .TH Compress::Raw::Zlib 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 Compress::Raw::Zlib \- Low\-Level Interface to zlib or zlib\-ng compression library
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use Compress::Raw::Zlib ;
69 \&
70 \& ($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) ;
71 \& $status = $d\->deflate($input, $output) ;
72 \& $status = $d\->flush($output [, $flush_type]) ;
73 \& $d\->deflateReset() ;
74 \& $d\->deflateParams(OPTS) ;
75 \& $d\->deflateTune(OPTS) ;
76 \& $d\->dict_adler() ;
77 \& $d\->crc32() ;
78 \& $d\->adler32() ;
79 \& $d\->total_in() ;
80 \& $d\->total_out() ;
81 \& $d\->msg() ;
82 \& $d\->get_Strategy();
83 \& $d\->get_Level();
84 \& $d\->get_BufSize();
85 \&
86 \& ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) ;
87 \& $status = $i\->inflate($input, $output [, $eof]) ;
88 \& $status = $i\->inflateSync($input) ;
89 \& $i\->inflateReset() ;
90 \& $i\->dict_adler() ;
91 \& $d\->crc32() ;
92 \& $d\->adler32() ;
93 \& $i\->total_in() ;
94 \& $i\->total_out() ;
95 \& $i\->msg() ;
96 \& $d\->get_BufSize();
97 \&
98 \& $crc = adler32($buffer [,$crc]) ;
99 \& $crc = crc32($buffer [,$crc]) ;
100 \&
101 \& $crc = crc32_combine($crc1, $crc2, $len2);
102 \& $adler = adler32_combine($adler1, $adler2, $len2);
103 \&
104 \& my $version = Compress::Raw::Zlib::zlib_version();
105 \& my $flags = Compress::Raw::Zlib::zlibCompileFlags();
106 \&
107 \& is_zlib_native();
108 \& is_zlibng_native();
109 \& is_zlibng_compat();
110 \& is_zlibng();
111 .Ve
112 .SH DESCRIPTION
113 .IX Header "DESCRIPTION"
114 The \fICompress::Raw::Zlib\fR module provides a Perl interface to the \fIzlib\fR or \fIzlib-ng\fR
115 compression libraries (see "SEE ALSO" for details about where to get
116 \&\fIzlib\fR or \fIzlib-ng\fR).
117 .PP
118 In the text below all references to \fIzlib\fR are also applicable to \fIzlib-ng\fR unless otherwise stated.
119 .SH Compress::Raw::Zlib::Deflate
120 .IX Header "Compress::Raw::Zlib::Deflate"
121 This section defines an interface that allows in-memory compression using
122 the \fIdeflate\fR interface provided by zlib.
123 .PP
124 Here is a definition of the interface available:
125 .ie n .SS "\fB($d, \fP\fB$status\fP\fB) = new Compress::Raw::Zlib::Deflate( [OPT] ) \fP"
126 .el .SS "\fB($d, \fP\f(CB$status\fP\fB) = new Compress::Raw::Zlib::Deflate( [OPT] ) \fP"
127 .IX Subsection "($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) "
128 Initialises a deflation object.
129 .PP
130 If you are familiar with the \fIzlib\fR library, it combines the
131 features of the \fIzlib\fR functions \f(CW\*(C`deflateInit\*(C'\fR, \f(CW\*(C`deflateInit2\*(C'\fR
132 and \f(CW\*(C`deflateSetDictionary\*(C'\fR.
133 .PP
134 If successful, it will return the initialised deflation object, \f(CW$d\fR
135 and a \f(CW$status\fR of \f(CW\*(C`Z_OK\*(C'\fR in a list context. In scalar context it
136 returns the deflation object, \f(CW$d\fR, only.
137 .PP
138 If not successful, the returned deflation object, \f(CW$d\fR, will be
139 \&\fIundef\fR and \f(CW$status\fR will hold the a \fIzlib\fR error code.
140 .PP
141 The function optionally takes a number of named options specified as
142 \&\f(CW\*(C`Name => value\*(C'\fR pairs. This allows individual options to be
143 tailored without having to specify them all in the parameter list.
144 .PP
145 For backward compatibility, it is also possible to pass the parameters
146 as a reference to a hash containing the name=>value pairs.
147 .PP
148 Below is a list of the valid options:
149 .IP \fB\-Level\fR 5
150 .IX Item "-Level"
151 Defines the compression level. Valid values are 0 through 9,
152 \&\f(CW\*(C`Z_NO_COMPRESSION\*(C'\fR, \f(CW\*(C`Z_BEST_SPEED\*(C'\fR, \f(CW\*(C`Z_BEST_COMPRESSION\*(C'\fR, and
153 \&\f(CW\*(C`Z_DEFAULT_COMPRESSION\*(C'\fR.
154 .Sp
155 The default is \f(CW\*(C`Z_DEFAULT_COMPRESSION\*(C'\fR.
156 .IP \fB\-Method\fR 5
157 .IX Item "-Method"
158 Defines the compression method. The only valid value at present (and
159 the default) is \f(CW\*(C`Z_DEFLATED\*(C'\fR.
160 .IP \fB\-WindowBits\fR 5
161 .IX Item "-WindowBits"
162 To compress an RFC 1950 data stream, set \f(CW\*(C`WindowBits\*(C'\fR to a positive
163 number between 8 and 15.
164 .Sp
165 To compress an RFC 1951 data stream, set \f(CW\*(C`WindowBits\*(C'\fR to \f(CW\*(C`\-MAX_WBITS\*(C'\fR.
166 .Sp
167 To compress an RFC 1952 data stream (i.e. gzip), set \f(CW\*(C`WindowBits\*(C'\fR to
168 \&\f(CW\*(C`WANT_GZIP\*(C'\fR.
169 .Sp
170 For a definition of the meaning and valid values for \f(CW\*(C`WindowBits\*(C'\fR
171 refer to the \fIzlib\fR documentation for \fIdeflateInit2\fR.
172 .Sp
173 Defaults to \f(CW\*(C`MAX_WBITS\*(C'\fR.
174 .IP \fB\-MemLevel\fR 5
175 .IX Item "-MemLevel"
176 For a definition of the meaning and valid values for \f(CW\*(C`MemLevel\*(C'\fR
177 refer to the \fIzlib\fR documentation for \fIdeflateInit2\fR.
178 .Sp
179 Defaults to MAX_MEM_LEVEL.
180 .IP \fB\-Strategy\fR 5
181 .IX Item "-Strategy"
182 Defines the strategy used to tune the compression. The valid values are
183 \&\f(CW\*(C`Z_DEFAULT_STRATEGY\*(C'\fR, \f(CW\*(C`Z_FILTERED\*(C'\fR, \f(CW\*(C`Z_RLE\*(C'\fR, \f(CW\*(C`Z_FIXED\*(C'\fR and
184 \&\f(CW\*(C`Z_HUFFMAN_ONLY\*(C'\fR.
185 .Sp
186 The default is \f(CW\*(C`Z_DEFAULT_STRATEGY\*(C'\fR.
187 .IP \fB\-Dictionary\fR 5
188 .IX Item "-Dictionary"
189 When a dictionary is specified \fICompress::Raw::Zlib\fR will automatically
190 call \f(CW\*(C`deflateSetDictionary\*(C'\fR directly after calling \f(CW\*(C`deflateInit\*(C'\fR. The
191 Adler32 value for the dictionary can be obtained by calling the method
192 \&\f(CW\*(C`$d\->dict_adler()\*(C'\fR.
193 .Sp
194 The default is no dictionary.
195 .IP \fB\-Bufsize\fR 5
196 .IX Item "-Bufsize"
197 Sets the initial size for the output buffer used by the \f(CW\*(C`$d\->deflate\*(C'\fR
198 and \f(CW\*(C`$d\->flush\*(C'\fR methods. If the buffer has to be
199 reallocated to increase the size, it will grow in increments of
200 \&\f(CW\*(C`Bufsize\*(C'\fR.
201 .Sp
202 The default buffer size is 4096.
203 .IP \fB\-AppendOutput\fR 5
204 .IX Item "-AppendOutput"
205 This option controls how data is written to the output buffer by the
206 \&\f(CW\*(C`$d\->deflate\*(C'\fR and \f(CW\*(C`$d\->flush\*(C'\fR methods.
207 .Sp
208 If the \f(CW\*(C`AppendOutput\*(C'\fR option is set to false, the output buffers in the
209 \&\f(CW\*(C`$d\->deflate\*(C'\fR and \f(CW\*(C`$d\->flush\*(C'\fR methods will be truncated before
210 uncompressed data is written to them.
211 .Sp
212 If the option is set to true, uncompressed data will be appended to the
213 output buffer in the \f(CW\*(C`$d\->deflate\*(C'\fR and \f(CW\*(C`$d\->flush\*(C'\fR methods.
214 .Sp
215 This option defaults to false.
216 .IP \fB\-CRC32\fR 5
217 .IX Item "-CRC32"
218 If set to true, a crc32 checksum of the uncompressed data will be
219 calculated. Use the \f(CW\*(C`$d\->crc32\*(C'\fR method to retrieve this value.
220 .Sp
221 This option defaults to false.
222 .IP \fB\-ADLER32\fR 5
223 .IX Item "-ADLER32"
224 If set to true, an adler32 checksum of the uncompressed data will be
225 calculated. Use the \f(CW\*(C`$d\->adler32\*(C'\fR method to retrieve this value.
226 .Sp
227 This option defaults to false.
228 .PP
229 Here is an example of using the \f(CW\*(C`Compress::Raw::Zlib::Deflate\*(C'\fR optional
230 parameter list to override the default buffer size and compression
231 level. All other options will take their default values.
232 .PP
233 .Vb 2
234 \& my $d = new Compress::Raw::Zlib::Deflate ( \-Bufsize => 300,
235 \& \-Level => Z_BEST_SPEED ) ;
236 .Ve
237 .ie n .SS "\fB\fP\fB$status\fP\fB = \fP\fB$d\fP\fB\->deflate($input, \fP\fB$output\fP\fB)\fP"
238 .el .SS "\fB\fP\f(CB$status\fP\fB = \fP\f(CB$d\fP\fB\->deflate($input, \fP\f(CB$output\fP\fB)\fP"
239 .IX Subsection "$status = $d->deflate($input, $output)"
240 Deflates the contents of \f(CW$input\fR and writes the compressed data to
241 \&\f(CW$output\fR.
242 .PP
243 The \f(CW$input\fR and \f(CW$output\fR parameters can be either scalars or scalar
244 references.
245 .PP
246 When finished, \f(CW$input\fR will be completely processed (assuming there
247 were no errors). If the deflation was successful it writes the deflated
248 data to \f(CW$output\fR and returns a status value of \f(CW\*(C`Z_OK\*(C'\fR.
249 .PP
250 On error, it returns a \fIzlib\fR error code.
251 .PP
252 If the \f(CW\*(C`AppendOutput\*(C'\fR option is set to true in the constructor for
253 the \f(CW$d\fR object, the compressed data will be appended to \f(CW$output\fR. If
254 it is false, \f(CW$output\fR will be truncated before any compressed data is
255 written to it.
256 .PP
257 \&\fBNote\fR: This method will not necessarily write compressed data to
258 \&\f(CW$output\fR every time it is called. So do not assume that there has been
259 an error if the contents of \f(CW$output\fR is empty on returning from
260 this method. As long as the return code from the method is \f(CW\*(C`Z_OK\*(C'\fR,
261 the deflate has succeeded.
262 .ie n .SS "\fB\fP\fB$status\fP\fB = \fP\fB$d\fP\fB\->flush($output [, \fP\fB$flush_type\fP\fB]) \fP"
263 .el .SS "\fB\fP\f(CB$status\fP\fB = \fP\f(CB$d\fP\fB\->flush($output [, \fP\f(CB$flush_type\fP\fB]) \fP"
264 .IX Subsection "$status = $d->flush($output [, $flush_type]) "
265 Typically used to finish the deflation. Any pending output will be
266 written to \f(CW$output\fR.
267 .PP
268 Returns \f(CW\*(C`Z_OK\*(C'\fR if successful.
269 .PP
270 Note that flushing can seriously degrade the compression ratio, so it
271 should only be used to terminate a decompression (using \f(CW\*(C`Z_FINISH\*(C'\fR) or
272 when you want to create a \fIfull flush point\fR (using \f(CW\*(C`Z_FULL_FLUSH\*(C'\fR).
273 .PP
274 By default the \f(CW\*(C`flush_type\*(C'\fR used is \f(CW\*(C`Z_FINISH\*(C'\fR. Other valid values
275 for \f(CW\*(C`flush_type\*(C'\fR are \f(CW\*(C`Z_NO_FLUSH\*(C'\fR, \f(CW\*(C`Z_PARTIAL_FLUSH\*(C'\fR, \f(CW\*(C`Z_SYNC_FLUSH\*(C'\fR
276 and \f(CW\*(C`Z_FULL_FLUSH\*(C'\fR. It is strongly recommended that you only set the
277 \&\f(CW\*(C`flush_type\*(C'\fR parameter if you fully understand the implications of
278 what it does. See the \f(CW\*(C`zlib\*(C'\fR documentation for details.
279 .PP
280 If the \f(CW\*(C`AppendOutput\*(C'\fR option is set to true in the constructor for
281 the \f(CW$d\fR object, the compressed data will be appended to \f(CW$output\fR. If
282 it is false, \f(CW$output\fR will be truncated before any compressed data is
283 written to it.
284 .ie n .SS "\fB\fP\fB$status\fP\fB = \fP\fB$d\fP\fB\->deflateReset() \fP"
285 .el .SS "\fB\fP\f(CB$status\fP\fB = \fP\f(CB$d\fP\fB\->deflateReset() \fP"
286 .IX Subsection "$status = $d->deflateReset() "
287 This method will reset the deflation object \f(CW$d\fR. It can be used when you
288 are compressing multiple data streams and want to use the same object to
289 compress each of them. It should only be used once the previous data stream
290 has been flushed successfully, i.e. a call to \f(CW\*(C`$d\->flush(Z_FINISH)\*(C'\fR has
291 returned \f(CW\*(C`Z_OK\*(C'\fR.
292 .PP
293 Returns \f(CW\*(C`Z_OK\*(C'\fR if successful.
294 .ie n .SS "\fB\fP\fB$status\fP\fB = \fP\fB$d\fP\fB\->deflateParams([OPT])\fP"
295 .el .SS "\fB\fP\f(CB$status\fP\fB = \fP\f(CB$d\fP\fB\->deflateParams([OPT])\fP"
296 .IX Subsection "$status = $d->deflateParams([OPT])"
297 Change settings for the deflate object \f(CW$d\fR.
298 .PP
299 The list of the valid options is shown below. Options not specified
300 will remain unchanged.
301 .IP \fB\-Level\fR 5
302 .IX Item "-Level"
303 Defines the compression level. Valid values are 0 through 9,
304 \&\f(CW\*(C`Z_NO_COMPRESSION\*(C'\fR, \f(CW\*(C`Z_BEST_SPEED\*(C'\fR, \f(CW\*(C`Z_BEST_COMPRESSION\*(C'\fR, and
305 \&\f(CW\*(C`Z_DEFAULT_COMPRESSION\*(C'\fR.
306 .IP \fB\-Strategy\fR 5
307 .IX Item "-Strategy"
308 Defines the strategy used to tune the compression. The valid values are
309 \&\f(CW\*(C`Z_DEFAULT_STRATEGY\*(C'\fR, \f(CW\*(C`Z_FILTERED\*(C'\fR and \f(CW\*(C`Z_HUFFMAN_ONLY\*(C'\fR.
310 .IP \fB\-BufSize\fR 5
311 .IX Item "-BufSize"
312 Sets the initial size for the output buffer used by the \f(CW\*(C`$d\->deflate\*(C'\fR
313 and \f(CW\*(C`$d\->flush\*(C'\fR methods. If the buffer has to be
314 reallocated to increase the size, it will grow in increments of
315 \&\f(CW\*(C`Bufsize\*(C'\fR.
316 .ie n .SS "\fB\fP\fB$status\fP\fB = \fP\fB$d\fP\fB\->deflateTune($good_length, \fP\fB$max_lazy\fP\fB, \fP\fB$nice_length\fP\fB, \fP\fB$max_chain\fP\fB)\fP"
317 .el .SS "\fB\fP\f(CB$status\fP\fB = \fP\f(CB$d\fP\fB\->deflateTune($good_length, \fP\f(CB$max_lazy\fP\fB, \fP\f(CB$nice_length\fP\fB, \fP\f(CB$max_chain\fP\fB)\fP"
318 .IX Subsection "$status = $d->deflateTune($good_length, $max_lazy, $nice_length, $max_chain)"
319 Tune the internal settings for the deflate object \f(CW$d\fR. This option is
320 only available if you are running zlib 1.2.2.3 or better.
321 .PP
322 Refer to the documentation in zlib.h for instructions on how to fly
323 \&\f(CW\*(C`deflateTune\*(C'\fR.
324 .ie n .SS \fB\fP\fB$d\fP\fB\->dict_adler()\fP
325 .el .SS \fB\fP\f(CB$d\fP\fB\->dict_adler()\fP
326 .IX Subsection "$d->dict_adler()"
327 Returns the adler32 value for the dictionary.
328 .ie n .SS \fB\fP\fB$d\fP\fB\->crc32()\fP
329 .el .SS \fB\fP\f(CB$d\fP\fB\->crc32()\fP
330 .IX Subsection "$d->crc32()"
331 Returns the crc32 value for the uncompressed data to date.
332 .PP
333 If the \f(CW\*(C`CRC32\*(C'\fR option is not enabled in the constructor for this object,
334 this method will always return 0;
335 .ie n .SS \fB\fP\fB$d\fP\fB\->adler32()\fP
336 .el .SS \fB\fP\f(CB$d\fP\fB\->adler32()\fP
337 .IX Subsection "$d->adler32()"
338 Returns the adler32 value for the uncompressed data to date.
339 .ie n .SS \fB\fP\fB$d\fP\fB\->msg()\fP
340 .el .SS \fB\fP\f(CB$d\fP\fB\->msg()\fP
341 .IX Subsection "$d->msg()"
342 Returns the last error message generated by zlib.
343 .ie n .SS \fB\fP\fB$d\fP\fB\->total_in()\fP
344 .el .SS \fB\fP\f(CB$d\fP\fB\->total_in()\fP
345 .IX Subsection "$d->total_in()"
346 Returns the total number of bytes uncompressed bytes input to deflate.
347 .ie n .SS \fB\fP\fB$d\fP\fB\->total_out()\fP
348 .el .SS \fB\fP\f(CB$d\fP\fB\->total_out()\fP
349 .IX Subsection "$d->total_out()"
350 Returns the total number of compressed bytes output from deflate.
351 .ie n .SS \fB\fP\fB$d\fP\fB\->get_Strategy()\fP
352 .el .SS \fB\fP\f(CB$d\fP\fB\->get_Strategy()\fP
353 .IX Subsection "$d->get_Strategy()"
354 Returns the deflation strategy currently used. Valid values are
355 \&\f(CW\*(C`Z_DEFAULT_STRATEGY\*(C'\fR, \f(CW\*(C`Z_FILTERED\*(C'\fR and \f(CW\*(C`Z_HUFFMAN_ONLY\*(C'\fR.
356 .ie n .SS \fB\fP\fB$d\fP\fB\->get_Level()\fP
357 .el .SS \fB\fP\f(CB$d\fP\fB\->get_Level()\fP
358 .IX Subsection "$d->get_Level()"
359 Returns the compression level being used.
360 .ie n .SS \fB\fP\fB$d\fP\fB\->get_BufSize()\fP
361 .el .SS \fB\fP\f(CB$d\fP\fB\->get_BufSize()\fP
362 .IX Subsection "$d->get_BufSize()"
363 Returns the buffer size used to carry out the compression.
364 .SS Example
365 .IX Subsection "Example"
366 Here is a trivial example of using \f(CW\*(C`deflate\*(C'\fR. It simply reads standard
367 input, deflates it and writes it to standard output.
368 .PP
369 .Vb 2
370 \& use strict ;
371 \& use warnings ;
372 \&
373 \& use Compress::Raw::Zlib ;
374 \&
375 \& binmode STDIN;
376 \& binmode STDOUT;
377 \& my $x = new Compress::Raw::Zlib::Deflate
378 \& or die "Cannot create a deflation stream\en" ;
379 \&
380 \& my ($output, $status) ;
381 \& while (<>)
382 \& {
383 \& $status = $x\->deflate($_, $output) ;
384 \&
385 \& $status == Z_OK
386 \& or die "deflation failed\en" ;
387 \&
388 \& print $output ;
389 \& }
390 \&
391 \& $status = $x\->flush($output) ;
392 \&
393 \& $status == Z_OK
394 \& or die "deflation failed\en" ;
395 \&
396 \& print $output ;
397 .Ve
398 .SH Compress::Raw::Zlib::Inflate
399 .IX Header "Compress::Raw::Zlib::Inflate"
400 This section defines an interface that allows in-memory uncompression using
401 the \fIinflate\fR interface provided by zlib.
402 .PP
403 Here is a definition of the interface:
404 .ie n .SS "\fB ($i, \fP\fB$status\fP\fB) = new Compress::Raw::Zlib::Inflate( [OPT] ) \fP"
405 .el .SS "\fB ($i, \fP\f(CB$status\fP\fB) = new Compress::Raw::Zlib::Inflate( [OPT] ) \fP"
406 .IX Subsection " ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) "
407 Initialises an inflation object.
408 .PP
409 In a list context it returns the inflation object, \f(CW$i\fR, and the
410 \&\fIzlib\fR status code (\f(CW$status\fR). In a scalar context it returns the
411 inflation object only.
412 .PP
413 If successful, \f(CW$i\fR will hold the inflation object and \f(CW$status\fR will
414 be \f(CW\*(C`Z_OK\*(C'\fR.
415 .PP
416 If not successful, \f(CW$i\fR will be \fIundef\fR and \f(CW$status\fR will hold the
417 \&\fIzlib\fR error code.
418 .PP
419 The function optionally takes a number of named options specified as
420 \&\f(CW\*(C`\-Name => value\*(C'\fR pairs. This allows individual options to be
421 tailored without having to specify them all in the parameter list.
422 .PP
423 For backward compatibility, it is also possible to pass the parameters
424 as a reference to a hash containing the \f(CW\*(C`name=>value\*(C'\fR pairs.
425 .PP
426 Here is a list of the valid options:
427 .IP \fB\-WindowBits\fR 5
428 .IX Item "-WindowBits"
429 To uncompress an RFC 1950 data stream, set \f(CW\*(C`WindowBits\*(C'\fR to a positive
430 number between 8 and 15.
431 .Sp
432 To uncompress an RFC 1951 data stream, set \f(CW\*(C`WindowBits\*(C'\fR to \f(CW\*(C`\-MAX_WBITS\*(C'\fR.
433 .Sp
434 To uncompress an RFC 1952 data stream (i.e. gzip), set \f(CW\*(C`WindowBits\*(C'\fR to
435 \&\f(CW\*(C`WANT_GZIP\*(C'\fR.
436 .Sp
437 To auto-detect and uncompress an RFC 1950 or RFC 1952 data stream (i.e.
438 gzip), set \f(CW\*(C`WindowBits\*(C'\fR to \f(CW\*(C`WANT_GZIP_OR_ZLIB\*(C'\fR.
439 .Sp
440 For a full definition of the meaning and valid values for \f(CW\*(C`WindowBits\*(C'\fR
441 refer to the \fIzlib\fR documentation for \fIinflateInit2\fR.
442 .Sp
443 Defaults to \f(CW\*(C`MAX_WBITS\*(C'\fR.
444 .IP \fB\-Bufsize\fR 5
445 .IX Item "-Bufsize"
446 Sets the initial size for the output buffer used by the \f(CW\*(C`$i\->inflate\*(C'\fR
447 method. If the output buffer in this method has to be reallocated to
448 increase the size, it will grow in increments of \f(CW\*(C`Bufsize\*(C'\fR.
449 .Sp
450 Default is 4096.
451 .IP \fB\-Dictionary\fR 5
452 .IX Item "-Dictionary"
453 The default is no dictionary.
454 .IP \fB\-AppendOutput\fR 5
455 .IX Item "-AppendOutput"
456 This option controls how data is written to the output buffer by the
457 \&\f(CW\*(C`$i\->inflate\*(C'\fR method.
458 .Sp
459 If the option is set to false, the output buffer in the \f(CW\*(C`$i\->inflate\*(C'\fR
460 method will be truncated before uncompressed data is written to it.
461 .Sp
462 If the option is set to true, uncompressed data will be appended to the
463 output buffer by the \f(CW\*(C`$i\->inflate\*(C'\fR method.
464 .Sp
465 This option defaults to false.
466 .IP \fB\-CRC32\fR 5
467 .IX Item "-CRC32"
468 If set to true, a crc32 checksum of the uncompressed data will be
469 calculated. Use the \f(CW\*(C`$i\->crc32\*(C'\fR method to retrieve this value.
470 .Sp
471 This option defaults to false.
472 .IP \fB\-ADLER32\fR 5
473 .IX Item "-ADLER32"
474 If set to true, an adler32 checksum of the uncompressed data will be
475 calculated. Use the \f(CW\*(C`$i\->adler32\*(C'\fR method to retrieve this value.
476 .Sp
477 This option defaults to false.
478 .IP \fB\-ConsumeInput\fR 5
479 .IX Item "-ConsumeInput"
480 If set to true, this option will remove compressed data from the input
481 buffer of the \f(CW\*(C`$i\->inflate\*(C'\fR method as the inflate progresses.
482 .Sp
483 This option can be useful when you are processing compressed data that is
484 embedded in another file/buffer. In this case the data that immediately
485 follows the compressed stream will be left in the input buffer.
486 .Sp
487 This option defaults to true.
488 .IP \fB\-LimitOutput\fR 5
489 .IX Item "-LimitOutput"
490 The \f(CW\*(C`LimitOutput\*(C'\fR option changes the behavior of the \f(CW\*(C`$i\->inflate\*(C'\fR
491 method so that the amount of memory used by the output buffer can be
492 limited.
493 .Sp
494 When \f(CW\*(C`LimitOutput\*(C'\fR is used the size of the output buffer used will either
495 be the value of the \f(CW\*(C`Bufsize\*(C'\fR option or the amount of memory already
496 allocated to \f(CW$output\fR, whichever is larger. Predicting the output size
497 available is tricky, so don't rely on getting an exact output buffer size.
498 .Sp
499 When \f(CW\*(C`LimitOutout\*(C'\fR is not specified \f(CW\*(C`$i\->inflate\*(C'\fR will use as much
500 memory as it takes to write all the uncompressed data it creates by
501 uncompressing the input buffer.
502 .Sp
503 If \f(CW\*(C`LimitOutput\*(C'\fR is enabled, the \f(CW\*(C`ConsumeInput\*(C'\fR option will also be
504 enabled.
505 .Sp
506 This option defaults to false.
507 .Sp
508 See "The LimitOutput option" for a discussion on why \f(CW\*(C`LimitOutput\*(C'\fR is
509 needed and how to use it.
510 .PP
511 Here is an example of using an optional parameter to override the default
512 buffer size.
513 .PP
514 .Vb 1
515 \& my ($i, $status) = new Compress::Raw::Zlib::Inflate( \-Bufsize => 300 ) ;
516 .Ve
517 .ie n .SS "\fB \fP\fB$status\fP\fB = \fP\fB$i\fP\fB\->inflate($input, \fP\fB$output\fP\fB [,$eof]) \fP"
518 .el .SS "\fB \fP\f(CB$status\fP\fB = \fP\f(CB$i\fP\fB\->inflate($input, \fP\f(CB$output\fP\fB [,$eof]) \fP"
519 .IX Subsection " $status = $i->inflate($input, $output [,$eof]) "
520 Inflates the complete contents of \f(CW$input\fR and writes the uncompressed
521 data to \f(CW$output\fR. The \f(CW$input\fR and \f(CW$output\fR parameters can either be
522 scalars or scalar references.
523 .PP
524 Returns \f(CW\*(C`Z_OK\*(C'\fR if successful and \f(CW\*(C`Z_STREAM_END\*(C'\fR if the end of the
525 compressed data has been successfully reached.
526 .PP
527 If not successful \f(CW$status\fR will hold the \fIzlib\fR error code.
528 .PP
529 If the \f(CW\*(C`ConsumeInput\*(C'\fR option has been set to true when the
530 \&\f(CW\*(C`Compress::Raw::Zlib::Inflate\*(C'\fR object is created, the \f(CW$input\fR parameter
531 is modified by \f(CW\*(C`inflate\*(C'\fR. On completion it will contain what remains
532 of the input buffer after inflation. In practice, this means that when
533 the return status is \f(CW\*(C`Z_OK\*(C'\fR the \f(CW$input\fR parameter will contain an
534 empty string, and when the return status is \f(CW\*(C`Z_STREAM_END\*(C'\fR the \f(CW$input\fR
535 parameter will contains what (if anything) was stored in the input buffer
536 after the deflated data stream.
537 .PP
538 This feature is useful when processing a file format that encapsulates
539 a compressed data stream (e.g. gzip, zip) and there is useful data
540 immediately after the deflation stream.
541 .PP
542 If the \f(CW\*(C`AppendOutput\*(C'\fR option is set to true in the constructor for
543 this object, the uncompressed data will be appended to \f(CW$output\fR. If
544 it is false, \f(CW$output\fR will be truncated before any uncompressed data
545 is written to it.
546 .PP
547 The \f(CW$eof\fR parameter needs a bit of explanation.
548 .PP
549 Prior to version 1.2.0, zlib assumed that there was at least one trailing
550 byte immediately after the compressed data stream when it was carrying out
551 decompression. This normally isn't a problem because the majority of zlib
552 applications guarantee that there will be data directly after the
553 compressed data stream. For example, both gzip (RFC 1950) and zip both
554 define trailing data that follows the compressed data stream.
555 .PP
556 The \f(CW$eof\fR parameter only needs to be used if \fBall\fR of the following
557 conditions apply
558 .IP 1. 5
559 You are either using a copy of zlib that is older than version 1.2.0 or you
560 want your application code to be able to run with as many different
561 versions of zlib as possible.
562 .IP 2. 5
563 You have set the \f(CW\*(C`WindowBits\*(C'\fR parameter to \f(CW\*(C`\-MAX_WBITS\*(C'\fR in the constructor
564 for this object, i.e. you are uncompressing a raw deflated data stream
565 (RFC 1951).
566 .IP 3. 5
567 There is no data immediately after the compressed data stream.
568 .PP
569 If \fBall\fR of these are the case, then you need to set the \f(CW$eof\fR parameter
570 to true on the final call (and only the final call) to \f(CW\*(C`$i\->inflate\*(C'\fR.
571 .PP
572 If you have built this module with zlib >= 1.2.0, the \f(CW$eof\fR parameter is
573 ignored. You can still set it if you want, but it won't be used behind the
574 scenes.
575 .ie n .SS "\fB\fP\fB$status\fP\fB = \fP\fB$i\fP\fB\->inflateSync($input)\fP"
576 .el .SS "\fB\fP\f(CB$status\fP\fB = \fP\f(CB$i\fP\fB\->inflateSync($input)\fP"
577 .IX Subsection "$status = $i->inflateSync($input)"
578 This method can be used to attempt to recover good data from a compressed
579 data stream that is partially corrupt.
580 It scans \f(CW$input\fR until it reaches either a \fIfull flush point\fR or the
581 end of the buffer.
582 .PP
583 If a \fIfull flush point\fR is found, \f(CW\*(C`Z_OK\*(C'\fR is returned and \f(CW$input\fR
584 will be have all data up to the flush point removed. This data can then be
585 passed to the \f(CW\*(C`$i\->inflate\*(C'\fR method to be uncompressed.
586 .PP
587 Any other return code means that a flush point was not found. If more
588 data is available, \f(CW\*(C`inflateSync\*(C'\fR can be called repeatedly with more
589 compressed data until the flush point is found.
590 .PP
591 Note \fIfull flush points\fR are not present by default in compressed
592 data streams. They must have been added explicitly when the data stream
593 was created by calling \f(CW\*(C`Compress::Deflate::flush\*(C'\fR with \f(CW\*(C`Z_FULL_FLUSH\*(C'\fR.
594 .ie n .SS "\fB\fP\fB$status\fP\fB = \fP\fB$i\fP\fB\->inflateReset() \fP"
595 .el .SS "\fB\fP\f(CB$status\fP\fB = \fP\f(CB$i\fP\fB\->inflateReset() \fP"
596 .IX Subsection "$status = $i->inflateReset() "
597 This method will reset the inflation object \f(CW$i\fR. It can be used when you
598 are uncompressing multiple data streams and want to use the same object to
599 uncompress each of them.
600 .PP
601 Returns \f(CW\*(C`Z_OK\*(C'\fR if successful.
602 .ie n .SS \fB\fP\fB$i\fP\fB\->dict_adler()\fP
603 .el .SS \fB\fP\f(CB$i\fP\fB\->dict_adler()\fP
604 .IX Subsection "$i->dict_adler()"
605 Returns the adler32 value for the dictionary.
606 .ie n .SS \fB\fP\fB$i\fP\fB\->crc32()\fP
607 .el .SS \fB\fP\f(CB$i\fP\fB\->crc32()\fP
608 .IX Subsection "$i->crc32()"
609 Returns the crc32 value for the uncompressed data to date.
610 .PP
611 If the \f(CW\*(C`CRC32\*(C'\fR option is not enabled in the constructor for this object,
612 this method will always return 0;
613 .ie n .SS \fB\fP\fB$i\fP\fB\->adler32()\fP
614 .el .SS \fB\fP\f(CB$i\fP\fB\->adler32()\fP
615 .IX Subsection "$i->adler32()"
616 Returns the adler32 value for the uncompressed data to date.
617 .PP
618 If the \f(CW\*(C`ADLER32\*(C'\fR option is not enabled in the constructor for this object,
619 this method will always return 0;
620 .ie n .SS \fB\fP\fB$i\fP\fB\->msg()\fP
621 .el .SS \fB\fP\f(CB$i\fP\fB\->msg()\fP
622 .IX Subsection "$i->msg()"
623 Returns the last error message generated by zlib.
624 .ie n .SS \fB\fP\fB$i\fP\fB\->total_in()\fP
625 .el .SS \fB\fP\f(CB$i\fP\fB\->total_in()\fP
626 .IX Subsection "$i->total_in()"
627 Returns the total number of bytes compressed bytes input to inflate.
628 .ie n .SS \fB\fP\fB$i\fP\fB\->total_out()\fP
629 .el .SS \fB\fP\f(CB$i\fP\fB\->total_out()\fP
630 .IX Subsection "$i->total_out()"
631 Returns the total number of uncompressed bytes output from inflate.
632 .ie n .SS \fB\fP\fB$d\fP\fB\->get_BufSize()\fP
633 .el .SS \fB\fP\f(CB$d\fP\fB\->get_BufSize()\fP
634 .IX Subsection "$d->get_BufSize()"
635 Returns the buffer size used to carry out the decompression.
636 .SS Examples
637 .IX Subsection "Examples"
638 Here is an example of using \f(CW\*(C`inflate\*(C'\fR.
639 .PP
640 .Vb 2
641 \& use strict ;
642 \& use warnings ;
643 \&
644 \& use Compress::Raw::Zlib;
645 \&
646 \& my $x = new Compress::Raw::Zlib::Inflate()
647 \& or die "Cannot create a inflation stream\en" ;
648 \&
649 \& my $input = \*(Aq\*(Aq ;
650 \& binmode STDIN;
651 \& binmode STDOUT;
652 \&
653 \& my ($output, $status) ;
654 \& while (read(STDIN, $input, 4096))
655 \& {
656 \& $status = $x\->inflate($input, $output) ;
657 \&
658 \& print $output ;
659 \&
660 \& last if $status != Z_OK ;
661 \& }
662 \&
663 \& die "inflation failed\en"
664 \& unless $status == Z_STREAM_END ;
665 .Ve
666 .PP
667 The next example show how to use the \f(CW\*(C`LimitOutput\*(C'\fR option. Notice the use
668 of two nested loops in this case. The outer loop reads the data from the
669 input source \- STDIN and the inner loop repeatedly calls \f(CW\*(C`inflate\*(C'\fR until
670 \&\f(CW$input\fR is exhausted, we get an error, or the end of the stream is
671 reached. One point worth remembering is by using the \f(CW\*(C`LimitOutput\*(C'\fR option
672 you also get \f(CW\*(C`ConsumeInput\*(C'\fR set as well \- this makes the code below much
673 simpler.
674 .PP
675 .Vb 2
676 \& use strict ;
677 \& use warnings ;
678 \&
679 \& use Compress::Raw::Zlib;
680 \&
681 \& my $x = new Compress::Raw::Zlib::Inflate(LimitOutput => 1)
682 \& or die "Cannot create a inflation stream\en" ;
683 \&
684 \& my $input = \*(Aq\*(Aq ;
685 \& binmode STDIN;
686 \& binmode STDOUT;
687 \&
688 \& my ($output, $status) ;
689 \&
690 \& OUTER:
691 \& while (read(STDIN, $input, 4096))
692 \& {
693 \& do
694 \& {
695 \& $status = $x\->inflate($input, $output) ;
696 \&
697 \& print $output ;
698 \&
699 \& last OUTER
700 \& unless $status == Z_OK || $status == Z_BUF_ERROR ;
701 \& }
702 \& while length $input;
703 \& }
704 \&
705 \& die "inflation failed\en"
706 \& unless $status == Z_STREAM_END ;
707 .Ve
708 .SH "CHECKSUM FUNCTIONS"
709 .IX Header "CHECKSUM FUNCTIONS"
710 Two functions are provided by \fIzlib\fR to calculate checksums. For the
711 Perl interface, the order of the two parameters in both functions has
712 been reversed. This allows both running checksums and one off
713 calculations to be done.
714 .PP
715 .Vb 2
716 \& $crc = adler32($buffer [,$crc]) ;
717 \& $crc = crc32($buffer [,$crc]) ;
718 .Ve
719 .PP
720 The buffer parameters can either be a scalar or a scalar reference.
721 .PP
722 If the \f(CW$crc\fR parameters is \f(CW\*(C`undef\*(C'\fR, the crc value will be reset.
723 .PP
724 If you have built this module with zlib 1.2.3 or better, two more
725 CRC-related functions are available.
726 .PP
727 .Vb 2
728 \& $crc = crc32_combine($crc1, $crc2, $len2);
729 \& $adler = adler32_combine($adler1, $adler2, $len2);
730 .Ve
731 .PP
732 These functions allow checksums to be merged.
733 Refer to the \fIzlib\fR documentation for more details.
734 .SH Misc
735 .IX Header "Misc"
736 .ie n .SS "my $version = \fBCompress::Raw::Zlib::zlib_version()\fP;"
737 .el .SS "my \f(CW$version\fP = \fBCompress::Raw::Zlib::zlib_version()\fP;"
738 .IX Subsection "my $version = Compress::Raw::Zlib::zlib_version();"
739 Returns the version of the \fIzlib\fR library if this module has been built with the \fIzlib\fR library.
740 If this module has been built with \fIzlib-ng\fR in native mode, this function will return a empty string.
741 If this module has been built with \fIzlib-ng\fR in compat mode, this function will return the Izlib> API
742 verion that \fIzlib-ng\fR is supporting.
743 .ie n .SS "my $version = \fBCompress::Raw::Zlib::zlibng_version()\fP;"
744 .el .SS "my \f(CW$version\fP = \fBCompress::Raw::Zlib::zlibng_version()\fP;"
745 .IX Subsection "my $version = Compress::Raw::Zlib::zlibng_version();"
746 Returns the version of the zlib-ng library if this module has been built with the \fIzlib-ng\fR library.
747 If this module has been built with \fIzlib\fR, this function will return a empty string.
748 .ie n .SS "my $flags = \fBCompress::Raw::Zlib::zlibCompileFlags()\fP;"
749 .el .SS "my \f(CW$flags\fP = \fBCompress::Raw::Zlib::zlibCompileFlags()\fP;"
750 .IX Subsection "my $flags = Compress::Raw::Zlib::zlibCompileFlags();"
751 Returns the flags indicating compile-time options that were used to build
752 the zlib or zlib-ng library. See the zlib documentation for a description of the flags
753 returned by \f(CW\*(C`zlibCompileFlags\*(C'\fR.
754 .PP
755 Note that when the zlib sources are built along with this module the
756 \&\f(CW\*(C`sprintf\*(C'\fR flags (bits 24, 25 and 26) should be ignored.
757 .PP
758 If you are using zlib 1.2.0 or older, \f(CW\*(C`zlibCompileFlags\*(C'\fR will return 0.
759 .SS "\fBis_zlib_native()\fP; =head2 \fBis_zlibng_native()\fP; =head2 \fBis_zlibng_compat()\fP; =head2 \fBis_zlibng()\fP;"
760 .IX Subsection "is_zlib_native(); =head2 is_zlibng_native(); =head2 is_zlibng_compat(); =head2 is_zlibng();"
761 These function can use used to check if \f(CW\*(C`Compress::Raw::Zlib\*(C'\fR was been built with \fIzlib\fR or \fIzlib-ng\fR.
762 .PP
763 The function \f(CW\*(C`is_zlib_native\*(C'\fR returns true if \f(CW\*(C`Compress::Raw::Zlib\*(C'\fR was built with \fIzlib\fR.
764 The function \f(CW\*(C`is_zlibng\*(C'\fR returns true if \f(CW\*(C`Compress::Raw::Zlib\*(C'\fR was built with \fIzlib-ng\fR.
765 .PP
766 The \fIzlib-ng\fR library has an option to build with a zlib-compataible API.
767 The c<is_zlibng_compat> function retuens true if zlib-ng has ben built with this API.
768 .PP
769 Finally, \f(CW\*(C`is_zlibng_native\*(C'\fR returns true if \fIzlib-ng\fR was built with its native API.
770 .SH "The LimitOutput option."
771 .IX Header "The LimitOutput option."
772 By default \f(CW\*(C`$i\->inflate($input, $output)\*(C'\fR will uncompress \fIall\fR data
773 in \f(CW$input\fR and write \fIall\fR of the uncompressed data it has generated to
774 \&\f(CW$output\fR. This makes the interface to \f(CW\*(C`inflate\*(C'\fR much simpler \- if the
775 method has uncompressed \f(CW$input\fR successfully \fIall\fR compressed data in
776 \&\f(CW$input\fR will have been dealt with. So if you are reading from an input
777 source and uncompressing as you go the code will look something like this
778 .PP
779 .Vb 2
780 \& use strict ;
781 \& use warnings ;
782 \&
783 \& use Compress::Raw::Zlib;
784 \&
785 \& my $x = new Compress::Raw::Zlib::Inflate()
786 \& or die "Cannot create a inflation stream\en" ;
787 \&
788 \& my $input = \*(Aq\*(Aq ;
789 \&
790 \& my ($output, $status) ;
791 \& while (read(STDIN, $input, 4096))
792 \& {
793 \& $status = $x\->inflate($input, $output) ;
794 \&
795 \& print $output ;
796 \&
797 \& last if $status != Z_OK ;
798 \& }
799 \&
800 \& die "inflation failed\en"
801 \& unless $status == Z_STREAM_END ;
802 .Ve
803 .PP
804 The points to note are
805 .IP \(bu 5
806 The main processing loop in the code handles reading of compressed data
807 from STDIN.
808 .IP \(bu 5
809 The status code returned from \f(CW\*(C`inflate\*(C'\fR will only trigger termination of
810 the main processing loop if it isn't \f(CW\*(C`Z_OK\*(C'\fR. When \f(CW\*(C`LimitOutput\*(C'\fR has not
811 been used the \f(CW\*(C`Z_OK\*(C'\fR status means that the end of the compressed
812 data stream has been reached or there has been an error in uncompression.
813 .IP \(bu 5
814 After the call to \f(CW\*(C`inflate\*(C'\fR \fIall\fR of the uncompressed data in \f(CW$input\fR
815 will have been processed. This means the subsequent call to \f(CW\*(C`read\*(C'\fR can
816 overwrite it's contents without any problem.
817 .PP
818 For most use-cases the behavior described above is acceptable (this module
819 and it's predecessor, \f(CW\*(C`Compress::Zlib\*(C'\fR, have used it for over 10 years
820 without an issue), but in a few very specific use-cases the amount of
821 memory required for \f(CW$output\fR can prohibitively large. For example, if the
822 compressed data stream contains the same pattern repeated thousands of
823 times, a relatively small compressed data stream can uncompress into
824 hundreds of megabytes. Remember \f(CW\*(C`inflate\*(C'\fR will keep allocating memory
825 until \fIall\fR the uncompressed data has been written to the output buffer \-
826 the size of \f(CW$output\fR is unbounded.
827 .PP
828 The \f(CW\*(C`LimitOutput\*(C'\fR option is designed to help with this use-case.
829 .PP
830 The main difference in your code when using \f(CW\*(C`LimitOutput\*(C'\fR is having to
831 deal with cases where the \f(CW$input\fR parameter still contains some
832 uncompressed data that \f(CW\*(C`inflate\*(C'\fR hasn't processed yet. The status code
833 returned from \f(CW\*(C`inflate\*(C'\fR will be \f(CW\*(C`Z_OK\*(C'\fR if uncompression took place and
834 \&\f(CW\*(C`Z_BUF_ERROR\*(C'\fR if the output buffer is full.
835 .PP
836 Below is typical code that shows how to use \f(CW\*(C`LimitOutput\*(C'\fR.
837 .PP
838 .Vb 2
839 \& use strict ;
840 \& use warnings ;
841 \&
842 \& use Compress::Raw::Zlib;
843 \&
844 \& my $x = new Compress::Raw::Zlib::Inflate(LimitOutput => 1)
845 \& or die "Cannot create a inflation stream\en" ;
846 \&
847 \& my $input = \*(Aq\*(Aq ;
848 \& binmode STDIN;
849 \& binmode STDOUT;
850 \&
851 \& my ($output, $status) ;
852 \&
853 \& OUTER:
854 \& while (read(STDIN, $input, 4096))
855 \& {
856 \& do
857 \& {
858 \& $status = $x\->inflate($input, $output) ;
859 \&
860 \& print $output ;
861 \&
862 \& last OUTER
863 \& unless $status == Z_OK || $status == Z_BUF_ERROR ;
864 \& }
865 \& while length $input;
866 \& }
867 \&
868 \& die "inflation failed\en"
869 \& unless $status == Z_STREAM_END ;
870 .Ve
871 .PP
872 Points to note this time:
873 .IP \(bu 5
874 There are now two nested loops in the code: the outer loop for reading the
875 compressed data from STDIN, as before; and the inner loop to carry out the
876 uncompression.
877 .IP \(bu 5
878 There are two exit points from the inner uncompression loop.
879 .Sp
880 Firstly when \f(CW\*(C`inflate\*(C'\fR has returned a status other than \f(CW\*(C`Z_OK\*(C'\fR or
881 \&\f(CW\*(C`Z_BUF_ERROR\*(C'\fR. This means that either the end of the compressed data
882 stream has been reached (\f(CW\*(C`Z_STREAM_END\*(C'\fR) or there is an error in the
883 compressed data. In either of these cases there is no point in continuing
884 with reading the compressed data, so both loops are terminated.
885 .Sp
886 The second exit point tests if there is any data left in the input buffer,
887 \&\f(CW$input\fR \- remember that the \f(CW\*(C`ConsumeInput\*(C'\fR option is automatically
888 enabled when \f(CW\*(C`LimitOutput\*(C'\fR is used. When the input buffer has been
889 exhausted, the outer loop can run again and overwrite a now empty
890 \&\f(CW$input\fR.
891 .SH "ACCESSING ZIP FILES"
892 .IX Header "ACCESSING ZIP FILES"
893 Although it is possible (with some effort on your part) to use this module
894 to access .zip files, there are other perl modules available that will do
895 all the hard work for you. Check out \f(CW\*(C`Archive::Zip\*(C'\fR,
896 \&\f(CW\*(C`Archive::Zip::SimpleZip\*(C'\fR, \f(CW\*(C`IO::Compress::Zip\*(C'\fR and
897 \&\f(CW\*(C`IO::Uncompress::Unzip\*(C'\fR.
898 .SH FAQ
899 .IX Header "FAQ"
900 .SS "Compatibility with Unix compress/uncompress."
901 .IX Subsection "Compatibility with Unix compress/uncompress."
902 This module is not compatible with Unix \f(CW\*(C`compress\*(C'\fR.
903 .PP
904 If you have the \f(CW\*(C`uncompress\*(C'\fR program available, you can use this to read
905 compressed files
906 .PP
907 .Vb 4
908 \& open F, "uncompress \-c $filename |";
909 \& while (<F>)
910 \& {
911 \& ...
912 .Ve
913 .PP
914 Alternatively, if you have the \f(CW\*(C`gunzip\*(C'\fR program available, you can use
915 this to read compressed files
916 .PP
917 .Vb 4
918 \& open F, "gunzip \-c $filename |";
919 \& while (<F>)
920 \& {
921 \& ...
922 .Ve
923 .PP
924 and this to write compress files, if you have the \f(CW\*(C`compress\*(C'\fR program
925 available
926 .PP
927 .Vb 4
928 \& open F, "| compress \-c $filename ";
929 \& print F "data";
930 \& ...
931 \& close F ;
932 .Ve
933 .SS "Accessing .tar.Z files"
934 .IX Subsection "Accessing .tar.Z files"
935 See previous FAQ item.
936 .PP
937 If the \f(CW\*(C`Archive::Tar\*(C'\fR module is installed and either the \f(CW\*(C`uncompress\*(C'\fR or
938 \&\f(CW\*(C`gunzip\*(C'\fR programs are available, you can use one of these workarounds to
939 read \f(CW\*(C`.tar.Z\*(C'\fR files.
940 .PP
941 Firstly with \f(CW\*(C`uncompress\*(C'\fR
942 .PP
943 .Vb 3
944 \& use strict;
945 \& use warnings;
946 \& use Archive::Tar;
947 \&
948 \& open F, "uncompress \-c $filename |";
949 \& my $tar = Archive::Tar\->new(*F);
950 \& ...
951 .Ve
952 .PP
953 and this with \f(CW\*(C`gunzip\*(C'\fR
954 .PP
955 .Vb 3
956 \& use strict;
957 \& use warnings;
958 \& use Archive::Tar;
959 \&
960 \& open F, "gunzip \-c $filename |";
961 \& my $tar = Archive::Tar\->new(*F);
962 \& ...
963 .Ve
964 .PP
965 Similarly, if the \f(CW\*(C`compress\*(C'\fR program is available, you can use this to
966 write a \f(CW\*(C`.tar.Z\*(C'\fR file
967 .PP
968 .Vb 4
969 \& use strict;
970 \& use warnings;
971 \& use Archive::Tar;
972 \& use IO::File;
973 \&
974 \& my $fh = new IO::File "| compress \-c >$filename";
975 \& my $tar = Archive::Tar\->new();
976 \& ...
977 \& $tar\->write($fh);
978 \& $fh\->close ;
979 .Ve
980 .SS "Zlib Library Version Support"
981 .IX Subsection "Zlib Library Version Support"
982 By default \f(CW\*(C`Compress::Raw::Zlib\*(C'\fR will build with a private copy of version
983 1.2.5 of the zlib library. (See the \fIREADME\fR file for details of
984 how to override this behaviour)
985 .PP
986 If you decide to use a different version of the zlib library, you need to be
987 aware of the following issues
988 .IP \(bu 5
989 First off, you must have zlib 1.0.5 or better.
990 .IP \(bu 5
991 You need to have zlib 1.2.1 or better if you want to use the \f(CW\*(C`\-Merge\*(C'\fR
992 option with \f(CW\*(C`IO::Compress::Gzip\*(C'\fR, \f(CW\*(C`IO::Compress::Deflate\*(C'\fR and
993 \&\f(CW\*(C`IO::Compress::RawDeflate\*(C'\fR.
994 .SH CONSTANTS
995 .IX Header "CONSTANTS"
996 All the \fIzlib\fR constants are automatically imported when you make use
997 of \fICompress::Raw::Zlib\fR.
998 .SH SUPPORT
999 .IX Header "SUPPORT"
1000 General feedback/questions/bug reports should be sent to
1001 <https://github.com/pmqs/Compress\-Raw\-Zlib/issues> (preferred) or
1002 <https://rt.cpan.org/Public/Dist/Display.html?Name=Compress\-Raw\-Zlib>.
1003 .SH "SEE ALSO"
1004 .IX Header "SEE ALSO"
1005 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
1006 .PP
1007 IO::Compress::FAQ
1008 .PP
1009 File::GlobMapper, Archive::Zip,
1010 Archive::Tar,
1011 IO::Zlib
1012 .PP
1013 For RFC 1950, 1951 and 1952 see
1014 <https://datatracker.ietf.org/doc/html/rfc1950>,
1015 <https://datatracker.ietf.org/doc/html/rfc1951> and
1016 <https://datatracker.ietf.org/doc/html/rfc1952>
1017 .PP
1018 The \fIzlib\fR compression library was written by Jean-loup Gailly
1019 \&\f(CW\*(C`[email protected]\*(C'\fR and Mark Adler \f(CW\*(C`[email protected]\*(C'\fR.
1020 .PP
1021 The primary site for the \fIzlib\fR compression library is
1022 <http://www.zlib.org>.
1023 .PP
1024 The primary site for the \fIzlib-ng\fR compression library is
1025 <https://github.com/zlib\-ng/zlib\-ng>.
1026 .PP
1027 The primary site for gzip is <http://www.gzip.org>.
1028 .SH AUTHOR
1029 .IX Header "AUTHOR"
1030 This module was written by Paul Marquess, \f(CW\*(C`[email protected]\*(C'\fR.
1031 .SH "MODIFICATION HISTORY"
1032 .IX Header "MODIFICATION HISTORY"
1033 See the Changes file.
1034 .SH "COPYRIGHT AND LICENSE"
1035 .IX Header "COPYRIGHT AND LICENSE"
1036 Copyright (c) 2005\-2024 Paul Marquess. All rights reserved.
1037 .PP
1038 This program is free software; you can redistribute it and/or
1039 modify it under the same terms as Perl itself.