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->deflateParams(OPTS) ;
15           $d->deflateTune(OPTS) ;
16           $d->dict_adler() ;
17           $d->crc32() ;
18           $d->adler32() ;
19           $d->total_in() ;
20           $d->total_out() ;
21           $d->msg() ;
22           $d->get_Strategy();
23           $d->get_Level();
24           $d->get_BufSize();
25
26           ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) ;
27           $status = $i->inflate($input, $output [, $eof]) ;
28           $status = $i->inflateSync($input) ;
29           $i->dict_adler() ;
30           $d->crc32() ;
31           $d->adler32() ;
32           $i->total_in() ;
33           $i->total_out() ;
34           $i->msg() ;
35           $d->get_BufSize();
36
37           $crc = adler32($buffer [,$crc]) ;
38           $crc = crc32($buffer [,$crc]) ;
39
40           $crc = adler32_combine($crc1, $crc2, $len2)l
41           $crc = crc32_combine($adler1, $adler2, $len2)
42
43           ZLIB_VERSION
44           ZLIB_VERNUM
45

DESCRIPTION

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

Compress::Raw::Zlib::Deflate

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

Compress::Raw::Zlib::Inflate

311       This section defines an interface that allows in-memory uncompression
312       using the inflate interface provided by zlib.
313
314       Here is a definition of the interface:
315
316        ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] )
317
318       Initialises an inflation object.
319
320       In a list context it returns the inflation object, $i, and the zlib
321       status code ($status). In a scalar context it returns the inflation
322       object only.
323
324       If successful, $i will hold the inflation object and $status will be
325       "Z_OK".
326
327       If not successful, $i will be undef and $status will hold the zlib
328       error code.
329
330       The function optionally takes a number of named options specified as
331       "-Name => value" pairs. This allows individual options to be tailored
332       without having to specify them all in the parameter list.
333
334       For backward compatibility, it is also possible to pass the parameters
335       as a reference to a hash containing the "name=>value" pairs.
336
337       Here is a list of the valid options:
338
339       -WindowBits
340            To uncompress an RFC 1950 data stream, set "WindowBits" to a posi‐
341            tive number.
342
343            To uncompress an RFC 1951 data stream, set "WindowBits" to
344            "-MAX_WBITS".
345
346            For a full definition of the meaning and valid values for "Window‐
347            Bits" refer to the zlib documentation for inflateInit2.
348
349            Defaults to MAX_WBITS.
350
351       -Bufsize
352            Sets the initial size for the output buffer used by the
353            "$i->inflate" method. If the output buffer in this method has to
354            be reallocated to increase the size, it will grow in increments of
355            "Bufsize".
356
357            Default is 4096.
358
359       -Dictionary
360            The default is no dictionary.
361
362       -AppendOutput
363            This option controls how data is written to the output buffer by
364            the "$i->inflate" method.
365
366            If the option is set to false, the output buffer in the
367            "$i->inflate" method will be truncated before uncompressed data is
368            written to it.
369
370            If the option is set to true, uncompressed data will be appended
371            to the output buffer by the "$i->inflate" method.
372
373            This option defaults to false.
374
375       -CRC32
376            If set to true, a crc32 checksum of the uncompressed data will be
377            calculated. Use the "$i->crc32" method to retrieve this value.
378
379            This option defaults to false.
380
381       -ADLER32
382            If set to true, an adler32 checksum of the uncompressed data will
383            be calculated. Use the "$i->adler32" method to retrieve this
384            value.
385
386            This option defaults to false.
387
388       -ConsumeInput
389            If set to true, this option will remove compressed data from the
390            input buffer of the the " $i->inflate " method as the inflate pro‐
391            gresses.
392
393            This option can be useful when you are processing compressed data
394            that is embedded in another file/buffer. In this case the data
395            that immediately follows the compressed stream will be left in the
396            input buffer.
397
398            This option defaults to true.
399
400       Here is an example of using an optional parameter to override the
401       default buffer size.
402
403           my ($i, $status) = new Compress::Raw::Zlib::Inflate( -Bufsize => 300 ) ;
404
405        $status = $i->inflate($input, $output [,$eof])
406
407       Inflates the complete contents of $input and writes the uncompressed
408       data to $output. The $input and $output parameters can either be
409       scalars or scalar references.
410
411       Returns "Z_OK" if successful and "Z_STREAM_END" if the end of the com‐
412       pressed data has been successfully reached.
413
414       If not successful $status will hold the zlib error code.
415
416       If the "ConsumeInput" option has been set to true when the "Com‐
417       press::Raw::Zlib::Inflate" object is created, the $input parameter is
418       modified by "inflate". On completion it will contain what remains of
419       the input buffer after inflation. In practice, this means that when the
420       return status is "Z_OK" the $input parameter will contain an empty
421       string, and when the return status is "Z_STREAM_END" the $input parame‐
422       ter will contains what (if anything) was stored in the input buffer
423       after the deflated data stream.
424
425       This feature is useful when processing a file format that encapsulates
426       a compressed data stream (e.g. gzip, zip) and there is useful data
427       immediately after the deflation stream.
428
429       If the "AppendOutput" option is set to true in the constructor for this
430       object, the uncompressed data will be appended to $output. If it is
431       false, $output will be truncated before any uncompressed data is writ‐
432       ten to it.
433
434       The $eof parameter needs a bit of explanation.
435
436       Prior to version 1.2.0, zlib assumed that there was at least one trail‐
437       ing byte immediately after the compressed data stream when it was car‐
438       rying out decompression. This normally isn't a problem because the
439       majority of zlib applications guarantee that there will be data
440       directly after the compressed data stream.  For example, both gzip (RFC
441       1950) and zip both define trailing data that follows the compressed
442       data stream.
443
444       The $eof parameter only needs to be used if all of the following condi‐
445       tions apply
446
447       1    You are either using a copy of zlib that is older than version
448            1.2.0 or you want your application code to be able to run with as
449            many different versions of zlib as possible.
450
451       2    You have set the "WindowBits" parameter to "-MAX_WBITS" in the
452            constructor for this object, i.e. you are uncompressing a raw
453            deflated data stream (RFC 1951).
454
455       3    There is no data immediately after the compressed data stream.
456
457       If all of these are the case, then you need to set the $eof parameter
458       to true on the final call (and only the final call) to "$i->inflate".
459
460       If you have built this module with zlib >= 1.2.0, the $eof parameter is
461       ignored. You can still set it if you want, but it won't be used behind
462       the scenes.
463
464       $status = $i->inflateSync($input)
465
466       This method can be used to attempt to recover good data from a com‐
467       pressed data stream that is partially corrupt.  It scans $input until
468       it reaches either a full flush point or the end of the buffer.
469
470       If a full flush point is found, "Z_OK" is returned and $input will be
471       have all data up to the flush point removed. This data can then be
472       passed to the "$i->inflate" method to be uncompressed.
473
474       Any other return code means that a flush point was not found. If more
475       data is available, "inflateSync" can be called repeatedly with more
476       compressed data until the flush point is found.
477
478       Note full flush points are not present by default in compressed data
479       streams. They must have been added explicitly when the data stream was
480       created by calling "Compress::Deflate::flush"  with "Z_FULL_FLUSH".
481
482       $i->dict_adler()
483
484       Returns the adler32 value for the dictionary.
485
486       $i->crc32()
487
488       Returns the crc32 value for the uncompressed data to date.
489
490       If the "CRC32" option is not enabled in the constructor for this
491       object, this method will always return 0;
492
493       $i->adler32()
494
495       Returns the adler32 value for the uncompressed data to date.
496
497       If the "ADLER32" option is not enabled in the constructor for this
498       object, this method will always return 0;
499
500       $i->msg()
501
502       Returns the last error message generated by zlib.
503
504       $i->total_in()
505
506       Returns the total number of bytes compressed bytes input to inflate.
507
508       $i->total_out()
509
510       Returns the total number of uncompressed bytes output from inflate.
511
512       $d->get_BufSize()
513
514       Returns the buffer size used to carry out the decompression.
515
516       Example
517
518       Here is an example of using "inflate".
519
520           use strict ;
521           use warnings ;
522
523           use Compress::Raw::Zlib;
524
525           my $x = new Compress::Raw::Zlib::Inflate()
526              or die "Cannot create a inflation stream\n" ;
527
528           my $input = '' ;
529           binmode STDIN;
530           binmode STDOUT;
531
532           my ($output, $status) ;
533           while (read(STDIN, $input, 4096))
534           {
535               $status = $x->inflate(\$input, $output) ;
536
537               print $output
538                   if $status == Z_OK or $status == Z_STREAM_END ;
539
540               last if $status != Z_OK ;
541           }
542
543           die "inflation failed\n"
544               unless $status == Z_STREAM_END ;
545

CHECKSUM FUNCTIONS

547       Two functions are provided by zlib to calculate checksums. For the Perl
548       interface, the order of the two parameters in both functions has been
549       reversed. This allows both running checksums and one off calculations
550       to be done.
551
552           $crc = adler32($buffer [,$crc]) ;
553           $crc = crc32($buffer [,$crc]) ;
554
555       The buffer parameters can either be a scalar or a scalar reference.
556
557       If the $crc parameters is "undef", the crc value will be reset.
558
559       If you have built this module with zlib 1.2.3 or better, two more CRC-
560       related functions are available.
561
562           $crc = adler32_combine($crc1, $crc2, $len2)l
563           $crc = crc32_combine($adler1, $adler2, $len2)
564
565       These functions allow checksums to be merged.
566

ACCESSING ZIP FILES

568       Although it is possible (with some effort on your part) to use this
569       module to access .zip files, there is a module on CPAN that will do all
570       the hard work for you. Check out the "Archive::Zip" module on CPAN at
571
572           http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
573

CONSTANTS

575       All the zlib constants are automatically imported when you make use of
576       Compress::Raw::Zlib.
577

AUTHOR

603       This module was written by Paul Marquess, pmqs@cpan.org.
604

MODIFICATION HISTORY

606       See the Changes file.
607

COPYRIGHT AND LICENSE

609       Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
610
611       This program is free software; you can redistribute it and/or modify it
612       under the same terms as Perl itself.
613
614
615
616perl v5.8.8                       2007-06-18            Compress::Raw::Zlib(3)