Compress::Raw::Zlib(3pm)

1Compress::Raw::Zlib(3)User Contributed Perl DocumentationCompress::Raw::Zlib(3)
2
3
4

NAME

6       Compress::Raw::Zlib - Low-Level Interface to zlib or zlib-ng
7       compression library
8

SYNOPSIS

10           use Compress::Raw::Zlib ;
11
12           ($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) ;
13           $status = $d->deflate($input, $output) ;
14           $status = $d->flush($output [, $flush_type]) ;
15           $d->deflateReset() ;
16           $d->deflateParams(OPTS) ;
17           $d->deflateTune(OPTS) ;
18           $d->dict_adler() ;
19           $d->crc32() ;
20           $d->adler32() ;
21           $d->total_in() ;
22           $d->total_out() ;
23           $d->msg() ;
24           $d->get_Strategy();
25           $d->get_Level();
26           $d->get_BufSize();
27
28           ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) ;
29           $status = $i->inflate($input, $output [, $eof]) ;
30           $status = $i->inflateSync($input) ;
31           $i->inflateReset() ;
32           $i->dict_adler() ;
33           $d->crc32() ;
34           $d->adler32() ;
35           $i->total_in() ;
36           $i->total_out() ;
37           $i->msg() ;
38           $d->get_BufSize();
39
40           $crc = adler32($buffer [,$crc]) ;
41           $crc = crc32($buffer [,$crc]) ;
42
43           $crc = crc32_combine($crc1, $crc2, $len2);
44           $adler = adler32_combine($adler1, $adler2, $len2);
45
46           my $version = Compress::Raw::Zlib::zlib_version();
47           my $flags = Compress::Raw::Zlib::zlibCompileFlags();
48
49           is_zlib_native();
50           is_zlibng_native();
51           is_zlibng_compat();
52           is_zlibng();
53

DESCRIPTION

55       The Compress::Raw::Zlib module provides a Perl interface to the zlib or
56       zlib-ng compression libraries (see "SEE ALSO" for details about where
57       to get zlib or zlib-ng).
58
59       In the text below all references to zlib are also applicable to zlib-ng
60       unless otherwise stated.
61

Compress::Raw::Zlib::Deflate

63       This section defines an interface that allows in-memory compression
64       using the deflate interface provided by zlib.
65
66       Here is a definition of the interface available:
67
68   ($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] )
69       Initialises a deflation object.
70
71       If you are familiar with the zlib library, it combines the features of
72       the zlib functions "deflateInit", "deflateInit2" and
73       "deflateSetDictionary".
74
75       If successful, it will return the initialised deflation object, $d and
76       a $status of "Z_OK" in a list context. In scalar context it returns the
77       deflation object, $d, only.
78
79       If not successful, the returned deflation object, $d, will be undef and
80       $status will hold the a zlib error code.
81
82       The function optionally takes a number of named options specified as
83       "Name => value" pairs. This allows individual options to be tailored
84       without having to specify them all in the parameter list.
85
86       For backward compatibility, it is also possible to pass the parameters
87       as a reference to a hash containing the name=>value pairs.
88
89       Below is a list of the valid options:
90
91       -Level
92            Defines the compression level. Valid values are 0 through 9,
93            "Z_NO_COMPRESSION", "Z_BEST_SPEED", "Z_BEST_COMPRESSION", and
94            "Z_DEFAULT_COMPRESSION".
95
96            The default is "Z_DEFAULT_COMPRESSION".
97
98       -Method
99            Defines the compression method. The only valid value at present
100            (and the default) is "Z_DEFLATED".
101
102       -WindowBits
103            To compress an RFC 1950 data stream, set "WindowBits" to a
104            positive number between 8 and 15.
105
106            To compress an RFC 1951 data stream, set "WindowBits" to
107            "-MAX_WBITS".
108
109            To compress an RFC 1952 data stream (i.e. gzip), set "WindowBits"
110            to "WANT_GZIP".
111
112            For a definition of the meaning and valid values for "WindowBits"
113            refer to the zlib documentation for deflateInit2.
114
115            Defaults to "MAX_WBITS".
116
117       -MemLevel
118            For a definition of the meaning and valid values for "MemLevel"
119            refer to the zlib documentation for deflateInit2.
120
121            Defaults to MAX_MEM_LEVEL.
122
123       -Strategy
124            Defines the strategy used to tune the compression. The valid
125            values are "Z_DEFAULT_STRATEGY", "Z_FILTERED", "Z_RLE", "Z_FIXED"
126            and "Z_HUFFMAN_ONLY".
127
128            The default is "Z_DEFAULT_STRATEGY".
129
130       -Dictionary
131            When a dictionary is specified Compress::Raw::Zlib will
132            automatically call "deflateSetDictionary" directly after calling
133            "deflateInit". The Adler32 value for the dictionary can be
134            obtained by calling the method "$d->dict_adler()".
135
136            The default is no dictionary.
137
138       -Bufsize
139            Sets the initial size for the output buffer used by the
140            "$d->deflate" and "$d->flush" methods. If the buffer has to be
141            reallocated to increase the size, it will grow in increments of
142            "Bufsize".
143
144            The default buffer size is 4096.
145
146       -AppendOutput
147            This option controls how data is written to the output buffer by
148            the "$d->deflate" and "$d->flush" methods.
149
150            If the "AppendOutput" option is set to false, the output buffers
151            in the "$d->deflate" and "$d->flush"  methods will be truncated
152            before uncompressed data is written to them.
153
154            If the option is set to true, uncompressed data will be appended
155            to the output buffer in the "$d->deflate" and "$d->flush" methods.
156
157            This option defaults to false.
158
159       -CRC32
160            If set to true, a crc32 checksum of the uncompressed data will be
161            calculated. Use the "$d->crc32" method to retrieve this value.
162
163            This option defaults to false.
164
165       -ADLER32
166            If set to true, an adler32 checksum of the uncompressed data will
167            be calculated. Use the "$d->adler32" method to retrieve this
168            value.
169
170            This option defaults to false.
171
172       Here is an example of using the "Compress::Raw::Zlib::Deflate" optional
173       parameter list to override the default buffer size and compression
174       level. All other options will take their default values.
175
176           my $d = new Compress::Raw::Zlib::Deflate ( -Bufsize => 300,
177                                                      -Level   => Z_BEST_SPEED ) ;
178
179   $status = $d->deflate($input, $output)
180       Deflates the contents of $input and writes the compressed data to
181       $output.
182
183       The $input and $output parameters can be either scalars or scalar
184       references.
185
186       When finished, $input will be completely processed (assuming there were
187       no errors). If the deflation was successful it writes the deflated data
188       to $output and returns a status value of "Z_OK".
189
190       On error, it returns a zlib error code.
191
192       If the "AppendOutput" option is set to true in the constructor for the
193       $d object, the compressed data will be appended to $output. If it is
194       false, $output will be truncated before any compressed data is written
195       to it.
196
197       Note: This method will not necessarily write compressed data to $output
198       every time it is called. So do not assume that there has been an error
199       if the contents of $output is empty on returning from this method. As
200       long as the return code from the method is "Z_OK", the deflate has
201       succeeded.
202
203   $status = $d->flush($output [, $flush_type])
204       Typically used to finish the deflation. Any pending output will be
205       written to $output.
206
207       Returns "Z_OK" if successful.
208
209       Note that flushing can seriously degrade the compression ratio, so it
210       should only be used to terminate a decompression (using "Z_FINISH") or
211       when you want to create a full flush point (using "Z_FULL_FLUSH").
212
213       By default the "flush_type" used is "Z_FINISH". Other valid values for
214       "flush_type" are "Z_NO_FLUSH", "Z_PARTIAL_FLUSH", "Z_SYNC_FLUSH" and
215       "Z_FULL_FLUSH". It is strongly recommended that you only set the
216       "flush_type" parameter if you fully understand the implications of what
217       it does. See the "zlib" documentation for details.
218
219       If the "AppendOutput" option is set to true in the constructor for the
220       $d object, the compressed data will be appended to $output. If it is
221       false, $output will be truncated before any compressed data is written
222       to it.
223
224   $status = $d->deflateReset()
225       This method will reset the deflation object $d. It can be used when you
226       are compressing multiple data streams and want to use the same object
227       to compress each of them. It should only be used once the previous data
228       stream has been flushed successfully, i.e. a call to
229       "$d->flush(Z_FINISH)" has returned "Z_OK".
230
231       Returns "Z_OK" if successful.
232
233   $status = $d->deflateParams([OPT])
234       Change settings for the deflate object $d.
235
236       The list of the valid options is shown below. Options not specified
237       will remain unchanged.
238
239       -Level
240            Defines the compression level. Valid values are 0 through 9,
241            "Z_NO_COMPRESSION", "Z_BEST_SPEED", "Z_BEST_COMPRESSION", and
242            "Z_DEFAULT_COMPRESSION".
243
244       -Strategy
245            Defines the strategy used to tune the compression. The valid
246            values are "Z_DEFAULT_STRATEGY", "Z_FILTERED" and
247            "Z_HUFFMAN_ONLY".
248
249       -BufSize
250            Sets the initial size for the output buffer used by the
251            "$d->deflate" and "$d->flush" methods. If the buffer has to be
252            reallocated to increase the size, it will grow in increments of
253            "Bufsize".
254
255   $status = $d->deflateTune($good_length, $max_lazy, $nice_length,
256       $max_chain)
257       Tune the internal settings for the deflate object $d. This option is
258       only available if you are running zlib 1.2.2.3 or better.
259
260       Refer to the documentation in zlib.h for instructions on how to fly
261       "deflateTune".
262
263   $d->dict_adler()
264       Returns the adler32 value for the dictionary.
265
266   $d->crc32()
267       Returns the crc32 value for the uncompressed data to date.
268
269       If the "CRC32" option is not enabled in the constructor for this
270       object, this method will always return 0;
271
272   $d->adler32()
273       Returns the adler32 value for the uncompressed data to date.
274
275   $d->msg()
276       Returns the last error message generated by zlib.
277
278   $d->total_in()
279       Returns the total number of bytes uncompressed bytes input to deflate.
280
281   $d->total_out()
282       Returns the total number of compressed bytes output from deflate.
283
284   $d->get_Strategy()
285       Returns the deflation strategy currently used. Valid values are
286       "Z_DEFAULT_STRATEGY", "Z_FILTERED" and "Z_HUFFMAN_ONLY".
287
288   $d->get_Level()
289       Returns the compression level being used.
290
291   $d->get_BufSize()
292       Returns the buffer size used to carry out the compression.
293
294   Example
295       Here is a trivial example of using "deflate". It simply reads standard
296       input, deflates it and writes it to standard output.
297
298           use strict ;
299           use warnings ;
300
301           use Compress::Raw::Zlib ;
302
303           binmode STDIN;
304           binmode STDOUT;
305           my $x = new Compress::Raw::Zlib::Deflate
306              or die "Cannot create a deflation stream\n" ;
307
308           my ($output, $status) ;
309           while (<>)
310           {
311               $status = $x->deflate($_, $output) ;
312
313               $status == Z_OK
314                   or die "deflation failed\n" ;
315
316               print $output ;
317           }
318
319           $status = $x->flush($output) ;
320
321           $status == Z_OK
322               or die "deflation failed\n" ;
323
324           print $output ;
325

Compress::Raw::Zlib::Inflate

327       This section defines an interface that allows in-memory uncompression
328       using the inflate interface provided by zlib.
329
330       Here is a definition of the interface:
331
332    ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] )
333       Initialises an inflation object.
334
335       In a list context it returns the inflation object, $i, and the zlib
336       status code ($status). In a scalar context it returns the inflation
337       object only.
338
339       If successful, $i will hold the inflation object and $status will be
340       "Z_OK".
341
342       If not successful, $i will be undef and $status will hold the zlib
343       error code.
344
345       The function optionally takes a number of named options specified as
346       "-Name => value" pairs. This allows individual options to be tailored
347       without having to specify them all in the parameter list.
348
349       For backward compatibility, it is also possible to pass the parameters
350       as a reference to a hash containing the "name=>value" pairs.
351
352       Here is a list of the valid options:
353
354       -WindowBits
355            To uncompress an RFC 1950 data stream, set "WindowBits" to a
356            positive number between 8 and 15.
357
358            To uncompress an RFC 1951 data stream, set "WindowBits" to
359            "-MAX_WBITS".
360
361            To uncompress an RFC 1952 data stream (i.e. gzip), set
362            "WindowBits" to "WANT_GZIP".
363
364            To auto-detect and uncompress an RFC 1950 or RFC 1952 data stream
365            (i.e.  gzip), set "WindowBits" to "WANT_GZIP_OR_ZLIB".
366
367            For a full definition of the meaning and valid values for
368            "WindowBits" refer to the zlib documentation for inflateInit2.
369
370            Defaults to "MAX_WBITS".
371
372       -Bufsize
373            Sets the initial size for the output buffer used by the
374            "$i->inflate" method. If the output buffer in this method has to
375            be reallocated to increase the size, it will grow in increments of
376            "Bufsize".
377
378            Default is 4096.
379
380       -Dictionary
381            The default is no dictionary.
382
383       -AppendOutput
384            This option controls how data is written to the output buffer by
385            the "$i->inflate" method.
386
387            If the option is set to false, the output buffer in the
388            "$i->inflate" method will be truncated before uncompressed data is
389            written to it.
390
391            If the option is set to true, uncompressed data will be appended
392            to the output buffer by the "$i->inflate" method.
393
394            This option defaults to false.
395
396       -CRC32
397            If set to true, a crc32 checksum of the uncompressed data will be
398            calculated. Use the "$i->crc32" method to retrieve this value.
399
400            This option defaults to false.
401
402       -ADLER32
403            If set to true, an adler32 checksum of the uncompressed data will
404            be calculated. Use the "$i->adler32" method to retrieve this
405            value.
406
407            This option defaults to false.
408
409       -ConsumeInput
410            If set to true, this option will remove compressed data from the
411            input buffer of the "$i->inflate" method as the inflate
412            progresses.
413
414            This option can be useful when you are processing compressed data
415            that is embedded in another file/buffer. In this case the data
416            that immediately follows the compressed stream will be left in the
417            input buffer.
418
419            This option defaults to true.
420
421       -LimitOutput
422            The "LimitOutput" option changes the behavior of the "$i->inflate"
423            method so that the amount of memory used by the output buffer can
424            be limited.
425
426            When "LimitOutput" is used the size of the output buffer used will
427            either be the value of the "Bufsize" option or the amount of
428            memory already allocated to $output, whichever is larger.
429            Predicting the output size available is tricky, so don't rely on
430            getting an exact output buffer size.
431
432            When "LimitOutout" is not specified "$i->inflate" will use as much
433            memory as it takes to write all the uncompressed data it creates
434            by uncompressing the input buffer.
435
436            If "LimitOutput" is enabled, the "ConsumeInput" option will also
437            be enabled.
438
439            This option defaults to false.
440
441            See "The LimitOutput option" for a discussion on why "LimitOutput"
442            is needed and how to use it.
443
444       Here is an example of using an optional parameter to override the
445       default buffer size.
446
447           my ($i, $status) = new Compress::Raw::Zlib::Inflate( -Bufsize => 300 ) ;
448
449    $status = $i->inflate($input, $output [,$eof])
450       Inflates the complete contents of $input and writes the uncompressed
451       data to $output. The $input and $output parameters can either be
452       scalars or scalar references.
453
454       Returns "Z_OK" if successful and "Z_STREAM_END" if the end of the
455       compressed data has been successfully reached.
456
457       If not successful $status will hold the zlib error code.
458
459       If the "ConsumeInput" option has been set to true when the
460       "Compress::Raw::Zlib::Inflate" object is created, the $input parameter
461       is modified by "inflate". On completion it will contain what remains of
462       the input buffer after inflation. In practice, this means that when the
463       return status is "Z_OK" the $input parameter will contain an empty
464       string, and when the return status is "Z_STREAM_END" the $input
465       parameter will contains what (if anything) was stored in the input
466       buffer after the deflated data stream.
467
468       This feature is useful when processing a file format that encapsulates
469       a compressed data stream (e.g. gzip, zip) and there is useful data
470       immediately after the deflation stream.
471
472       If the "AppendOutput" option is set to true in the constructor for this
473       object, the uncompressed data will be appended to $output. If it is
474       false, $output will be truncated before any uncompressed data is
475       written to it.
476
477       The $eof parameter needs a bit of explanation.
478
479       Prior to version 1.2.0, zlib assumed that there was at least one
480       trailing byte immediately after the compressed data stream when it was
481       carrying out decompression. This normally isn't a problem because the
482       majority of zlib applications guarantee that there will be data
483       directly after the compressed data stream.  For example, both gzip (RFC
484       1950) and zip both define trailing data that follows the compressed
485       data stream.
486
487       The $eof parameter only needs to be used if all of the following
488       conditions apply
489
490       1.   You are either using a copy of zlib that is older than version
491            1.2.0 or you want your application code to be able to run with as
492            many different versions of zlib as possible.
493
494       2.   You have set the "WindowBits" parameter to "-MAX_WBITS" in the
495            constructor for this object, i.e. you are uncompressing a raw
496            deflated data stream (RFC 1951).
497
498       3.   There is no data immediately after the compressed data stream.
499
500       If all of these are the case, then you need to set the $eof parameter
501       to true on the final call (and only the final call) to "$i->inflate".
502
503       If you have built this module with zlib >= 1.2.0, the $eof parameter is
504       ignored. You can still set it if you want, but it won't be used behind
505       the scenes.
506
507   $status = $i->inflateSync($input)
508       This method can be used to attempt to recover good data from a
509       compressed data stream that is partially corrupt.  It scans $input
510       until it reaches either a full flush point or the end of the buffer.
511
512       If a full flush point is found, "Z_OK" is returned and $input will be
513       have all data up to the flush point removed. This data can then be
514       passed to the "$i->inflate" method to be uncompressed.
515
516       Any other return code means that a flush point was not found. If more
517       data is available, "inflateSync" can be called repeatedly with more
518       compressed data until the flush point is found.
519
520       Note full flush points are not present by default in compressed data
521       streams. They must have been added explicitly when the data stream was
522       created by calling "Compress::Deflate::flush"  with "Z_FULL_FLUSH".
523
524   $status = $i->inflateReset()
525       This method will reset the inflation object $i. It can be used when you
526       are uncompressing multiple data streams and want to use the same object
527       to uncompress each of them.
528
529       Returns "Z_OK" if successful.
530
531   $i->dict_adler()
532       Returns the adler32 value for the dictionary.
533
534   $i->crc32()
535       Returns the crc32 value for the uncompressed data to date.
536
537       If the "CRC32" option is not enabled in the constructor for this
538       object, this method will always return 0;
539
540   $i->adler32()
541       Returns the adler32 value for the uncompressed data to date.
542
543       If the "ADLER32" option is not enabled in the constructor for this
544       object, this method will always return 0;
545
546   $i->msg()
547       Returns the last error message generated by zlib.
548
549   $i->total_in()
550       Returns the total number of bytes compressed bytes input to inflate.
551
552   $i->total_out()
553       Returns the total number of uncompressed bytes output from inflate.
554
555   $d->get_BufSize()
556       Returns the buffer size used to carry out the decompression.
557
558   Examples
559       Here is an example of using "inflate".
560
561           use strict ;
562           use warnings ;
563
564           use Compress::Raw::Zlib;
565
566           my $x = new Compress::Raw::Zlib::Inflate()
567              or die "Cannot create a inflation stream\n" ;
568
569           my $input = '' ;
570           binmode STDIN;
571           binmode STDOUT;
572
573           my ($output, $status) ;
574           while (read(STDIN, $input, 4096))
575           {
576               $status = $x->inflate($input, $output) ;
577
578               print $output ;
579
580               last if $status != Z_OK ;
581           }
582
583           die "inflation failed\n"
584               unless $status == Z_STREAM_END ;
585
586       The next example show how to use the "LimitOutput" option. Notice the
587       use of two nested loops in this case. The outer loop reads the data
588       from the input source - STDIN and the inner loop repeatedly calls
589       "inflate" until $input is exhausted, we get an error, or the end of the
590       stream is reached. One point worth remembering is by using the
591       "LimitOutput" option you also get "ConsumeInput" set as well - this
592       makes the code below much simpler.
593
594           use strict ;
595           use warnings ;
596
597           use Compress::Raw::Zlib;
598
599           my $x = new Compress::Raw::Zlib::Inflate(LimitOutput => 1)
600              or die "Cannot create a inflation stream\n" ;
601
602           my $input = '' ;
603           binmode STDIN;
604           binmode STDOUT;
605
606           my ($output, $status) ;
607
608         OUTER:
609           while (read(STDIN, $input, 4096))
610           {
611               do
612               {
613                   $status = $x->inflate($input, $output) ;
614
615                   print $output ;
616
617                   last OUTER
618                       unless $status == Z_OK || $status == Z_BUF_ERROR ;
619               }
620               while ($status == Z_OK && length $input);
621           }
622
623           die "inflation failed\n"
624               unless $status == Z_STREAM_END ;
625

CHECKSUM FUNCTIONS

627       Two functions are provided by zlib to calculate checksums. For the Perl
628       interface, the order of the two parameters in both functions has been
629       reversed. This allows both running checksums and one off calculations
630       to be done.
631
632           $crc = adler32($buffer [,$crc]) ;
633           $crc = crc32($buffer [,$crc]) ;
634
635       The buffer parameters can either be a scalar or a scalar reference.
636
637       If the $crc parameters is "undef", the crc value will be reset.
638
639       If you have built this module with zlib 1.2.3 or better, two more CRC-
640       related functions are available.
641
642           $crc = crc32_combine($crc1, $crc2, $len2);
643           $adler = adler32_combine($adler1, $adler2, $len2);
644
645       These functions allow checksums to be merged.  Refer to the zlib
646       documentation for more details.
647

Misc

649   my $version = Compress::Raw::Zlib::zlib_version();
650       Returns the version of the zlib library if this module has been built
651       with the zlib library.  If this module has been built with zlib-ng in
652       native mode, this function will return a empty string.  If this module
653       has been built with zlib-ng in compat mode, this function will return
654       the Izlib> API verion that zlib-ng is supporting.
655
656   my $version = Compress::Raw::Zlib::zlibng_version();
657       Returns the version of the zlib-ng library if this module has been
658       built with the zlib-ng library.  If this module has been built with
659       zlib, this function will return a empty string.
660
661   my $flags = Compress::Raw::Zlib::zlibCompileFlags();
662       Returns the flags indicating compile-time options that were used to
663       build the zlib or zlib-ng library. See the zlib documentation for a
664       description of the flags returned by "zlibCompileFlags".
665
666       Note that when the zlib sources are built along with this module the
667       "sprintf" flags (bits 24, 25 and 26) should be ignored.
668
669       If you are using zlib 1.2.0 or older, "zlibCompileFlags" will return 0.
670
671   is_zlib_native(); =head2 is_zlibng_native(); =head2 is_zlibng_compat();
672       =head2 is_zlibng();
673       These function can use used to check if "Compress::Raw::Zlib" was been
674       built with zlib or zlib-ng.
675
676       The function "is_zlib_native" returns true if "Compress::Raw::Zlib" was
677       built with zlib.  The function "is_zlibng" returns true if
678       "Compress::Raw::Zlib" was built with zlib-ng.
679
680       The zlib-ng library has an option to build with a zlib-compataible API.
681       The c<is_zlibng_compat> function retuens true if zlib-ng has ben built
682       with this API.
683
684       Finally, "is_zlibng_native" returns true if zlib-ng was built with its
685       native API.
686

The LimitOutput option.

688       By default "$i->inflate($input, $output)" will uncompress all data in
689       $input and write all of the uncompressed data it has generated to
690       $output. This makes the interface to "inflate" much simpler - if the
691       method has uncompressed $input successfully all compressed data in
692       $input will have been dealt with. So if you are reading from an input
693       source and uncompressing as you go the code will look something like
694       this
695
696           use strict ;
697           use warnings ;
698
699           use Compress::Raw::Zlib;
700
701           my $x = new Compress::Raw::Zlib::Inflate()
702              or die "Cannot create a inflation stream\n" ;
703
704           my $input = '' ;
705
706           my ($output, $status) ;
707           while (read(STDIN, $input, 4096))
708           {
709               $status = $x->inflate($input, $output) ;
710
711               print $output ;
712
713               last if $status != Z_OK ;
714           }
715
716           die "inflation failed\n"
717               unless $status == Z_STREAM_END ;
718
719       The points to note are
720
721       •    The main processing loop in the code handles reading of compressed
722            data from STDIN.
723
724       •    The status code returned from "inflate" will only trigger
725            termination of the main processing loop if it isn't "Z_OK". When
726            "LimitOutput" has not been used the "Z_OK" status means that the
727            end of the compressed data stream has been reached or there has
728            been an error in uncompression.
729
730       •    After the call to "inflate" all of the uncompressed data in $input
731            will have been processed. This means the subsequent call to "read"
732            can overwrite it's contents without any problem.
733
734       For most use-cases the behavior described above is acceptable (this
735       module and it's predecessor, "Compress::Zlib", have used it for over 10
736       years without an issue), but in a few very specific use-cases the
737       amount of memory required for $output can prohibitively large. For
738       example, if the compressed data stream contains the same pattern
739       repeated thousands of times, a relatively small compressed data stream
740       can uncompress into hundreds of megabytes.  Remember "inflate" will
741       keep allocating memory until all the uncompressed data has been written
742       to the output buffer - the size of $output is unbounded.
743
744       The "LimitOutput" option is designed to help with this use-case.
745
746       The main difference in your code when using "LimitOutput" is having to
747       deal with cases where the $input parameter still contains some
748       uncompressed data that "inflate" hasn't processed yet. The status code
749       returned from "inflate" will be "Z_OK" if uncompression took place and
750       "Z_BUF_ERROR" if the output buffer is full.
751
752       Below is typical code that shows how to use "LimitOutput".
753
754           use strict ;
755           use warnings ;
756
757           use Compress::Raw::Zlib;
758
759           my $x = new Compress::Raw::Zlib::Inflate(LimitOutput => 1)
760              or die "Cannot create a inflation stream\n" ;
761
762           my $input = '' ;
763           binmode STDIN;
764           binmode STDOUT;
765
766           my ($output, $status) ;
767
768         OUTER:
769           while (read(STDIN, $input, 4096))
770           {
771               do
772               {
773                   $status = $x->inflate($input, $output) ;
774
775                   print $output ;
776
777                   last OUTER
778                       unless $status == Z_OK || $status == Z_BUF_ERROR ;
779               }
780               while ($status == Z_OK && length $input);
781           }
782
783           die "inflation failed\n"
784               unless $status == Z_STREAM_END ;
785
786       Points to note this time:
787
788       •    There are now two nested loops in the code: the outer loop for
789            reading the compressed data from STDIN, as before; and the inner
790            loop to carry out the uncompression.
791
792       •    There are two exit points from the inner uncompression loop.
793
794            Firstly when "inflate" has returned a status other than "Z_OK" or
795            "Z_BUF_ERROR".  This means that either the end of the compressed
796            data stream has been reached ("Z_STREAM_END") or there is an error
797            in the compressed data. In either of these cases there is no point
798            in continuing with reading the compressed data, so both loops are
799            terminated.
800
801            The second exit point tests if there is any data left in the input
802            buffer, $input - remember that the "ConsumeInput" option is
803            automatically enabled when "LimitOutput" is used.  When the input
804            buffer has been exhausted, the outer loop can run again and
805            overwrite a now empty $input.
806

ACCESSING ZIP FILES

808       Although it is possible (with some effort on your part) to use this
809       module to access .zip files, there are other perl modules available
810       that will do all the hard work for you. Check out "Archive::Zip",
811       "Archive::Zip::SimpleZip", "IO::Compress::Zip" and
812       "IO::Uncompress::Unzip".
813

FAQ

815   Compatibility with Unix compress/uncompress.
816       This module is not compatible with Unix "compress".
817
818       If you have the "uncompress" program available, you can use this to
819       read compressed files
820
821           open F, "uncompress -c $filename |";
822           while (<F>)
823           {
824               ...
825
826       Alternatively, if you have the "gunzip" program available, you can use
827       this to read compressed files
828
829           open F, "gunzip -c $filename |";
830           while (<F>)
831           {
832               ...
833
834       and this to write compress files, if you have the "compress" program
835       available
836
837           open F, "| compress -c $filename ";
838           print F "data";
839           ...
840           close F ;
841
842   Accessing .tar.Z files
843       See previous FAQ item.
844
845       If the "Archive::Tar" module is installed and either the "uncompress"
846       or "gunzip" programs are available, you can use one of these
847       workarounds to read ".tar.Z" files.
848
849       Firstly with "uncompress"
850
851           use strict;
852           use warnings;
853           use Archive::Tar;
854
855           open F, "uncompress -c $filename |";
856           my $tar = Archive::Tar->new(*F);
857           ...
858
859       and this with "gunzip"
860
861           use strict;
862           use warnings;
863           use Archive::Tar;
864
865           open F, "gunzip -c $filename |";
866           my $tar = Archive::Tar->new(*F);
867           ...
868
869       Similarly, if the "compress" program is available, you can use this to
870       write a ".tar.Z" file
871
872           use strict;
873           use warnings;
874           use Archive::Tar;
875           use IO::File;
876
877           my $fh = new IO::File "| compress -c >$filename";
878           my $tar = Archive::Tar->new();
879           ...
880           $tar->write($fh);
881           $fh->close ;
882
883   Zlib Library Version Support
884       By default "Compress::Raw::Zlib" will build with a private copy of
885       version 1.2.5 of the zlib library. (See the README file for details of
886       how to override this behaviour)
887
888       If you decide to use a different version of the zlib library, you need
889       to be aware of the following issues
890
891       •    First off, you must have zlib 1.0.5 or better.
892
893       •    You need to have zlib 1.2.1 or better if you want to use the
894            "-Merge" option with "IO::Compress::Gzip", "IO::Compress::Deflate"
895            and "IO::Compress::RawDeflate".
896

CONSTANTS

898       All the zlib constants are automatically imported when you make use of
899       Compress::Raw::Zlib.
900

SUPPORT

902       General feedback/questions/bug reports should be sent to
903       <https://github.com/pmqs/Compress-Raw-Zlib/issues> (preferred) or
904       <https://rt.cpan.org/Public/Dist/Display.html?Name=Compress-Raw-Zlib>.
905

AUTHOR

938       This module was written by Paul Marquess, "pmqs@cpan.org".
939

MODIFICATION HISTORY

941       See the Changes file.
942

COPYRIGHT AND LICENSE

944       Copyright (c) 2005-2022 Paul Marquess. All rights reserved.
945
946       This program is free software; you can redistribute it and/or modify it
947       under the same terms as Perl itself.
948
949
950
951perl v5.36.0                      2022-07-22            Compress::Raw::Zlib(3)