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 compression library
7

SYNOPSIS

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

DESCRIPTION

49       The Compress::Raw::Zlib module provides a Perl interface to the zlib
50       compression library (see "AUTHOR" for details about where to get zlib).
51

Compress::Raw::Zlib::Deflate

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

Compress::Raw::Zlib::Inflate

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

CHECKSUM FUNCTIONS

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

Misc

639   my $version = Compress::Raw::Zlib::zlib_version();
640       Returns the version of the zlib library.
641
642   my $flags = Compress::Raw::Zlib::zlibCompileFlags();
643       Returns the flags indicating compile-time options that were used to
644       build the zlib library. See the zlib documentation for a description of
645       the flags returned by "zlibCompileFlags".
646
647       Note that when the zlib sources are built along with this module the
648       "sprintf" flags (bits 24, 25 and 26) should be ignored.
649
650       If you are using zlib 1.2.0 or older, "zlibCompileFlags" will return 0.
651

The LimitOutput option.

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

ACCESSING ZIP FILES

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

FAQ

780   Compatibility with Unix compress/uncompress.
781       This module is not compatible with Unix "compress".
782
783       If you have the "uncompress" program available, you can use this to
784       read compressed files
785
786           open F, "uncompress -c $filename |";
787           while (<F>)
788           {
789               ...
790
791       Alternatively, if you have the "gunzip" program available, you can use
792       this to read compressed files
793
794           open F, "gunzip -c $filename |";
795           while (<F>)
796           {
797               ...
798
799       and this to write compress files, if you have the "compress" program
800       available
801
802           open F, "| compress -c $filename ";
803           print F "data";
804           ...
805           close F ;
806
807   Accessing .tar.Z files
808       See previous FAQ item.
809
810       If the "Archive::Tar" module is installed and either the "uncompress"
811       or "gunzip" programs are available, you can use one of these
812       workarounds to read ".tar.Z" files.
813
814       Firstly with "uncompress"
815
816           use strict;
817           use warnings;
818           use Archive::Tar;
819
820           open F, "uncompress -c $filename |";
821           my $tar = Archive::Tar->new(*F);
822           ...
823
824       and this with "gunzip"
825
826           use strict;
827           use warnings;
828           use Archive::Tar;
829
830           open F, "gunzip -c $filename |";
831           my $tar = Archive::Tar->new(*F);
832           ...
833
834       Similarly, if the "compress" program is available, you can use this to
835       write a ".tar.Z" file
836
837           use strict;
838           use warnings;
839           use Archive::Tar;
840           use IO::File;
841
842           my $fh = new IO::File "| compress -c >$filename";
843           my $tar = Archive::Tar->new();
844           ...
845           $tar->write($fh);
846           $fh->close ;
847
848   Zlib Library Version Support
849       By default "Compress::Raw::Zlib" will build with a private copy of
850       version 1.2.5 of the zlib library. (See the README file for details of
851       how to override this behaviour)
852
853       If you decide to use a different version of the zlib library, you need
854       to be aware of the following issues
855
856       ·    First off, you must have zlib 1.0.5 or better.
857
858       ·    You need to have zlib 1.2.1 or better if you want to use the
859            "-Merge" option with "IO::Compress::Gzip", "IO::Compress::Deflate"
860            and "IO::Compress::RawDeflate".
861

CONSTANTS

863       All the zlib constants are automatically imported when you make use of
864       Compress::Raw::Zlib.
865

SUPPORT

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

AUTHOR

900       This module was written by Paul Marquess, "pmqs@cpan.org".
901

MODIFICATION HISTORY

903       See the Changes file.
904

COPYRIGHT AND LICENSE

906       Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
907
908       This program is free software; you can redistribute it and/or modify it
909       under the same terms as Perl itself.
910
911
912
913perl v5.30.1                      2020-01-29            Compress::Raw::Zlib(3)