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 = adler32_combine($crc1, $crc2, $len2)l
43           $crc = crc32_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 = adler32_combine($crc1, $crc2, $len2)l
633           $crc = crc32_combine($adler1, $adler2, $len2)
634
635       These functions allow checksums to be merged.
636

Misc

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

The LimitOutput option.

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

ACCESSING ZIP FILES

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

FAQ

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

CONSTANTS

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

AUTHOR

892       This module was written by Paul Marquess, pmqs@cpan.org.
893

MODIFICATION HISTORY

895       See the Changes file.
896

COPYRIGHT AND LICENSE

898       Copyright (c) 2005-2013 Paul Marquess. All rights reserved.
899
900       This program is free software; you can redistribute it and/or modify it
901       under the same terms as Perl itself.
902
903
904
905perl v5.16.3                      2013-05-19            Compress::Raw::Zlib(3)