Debian Codegraph @

upstream/mageia-cauldron/man3pm/Compress::Raw::Zlib.3pm

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