1Zlib(3) User Contributed Perl Documentation Zlib(3)
2
6 Compress::Zlib - Interface to zlib compression library
7
9 use Compress::Zlib ;
10 ($d, $status) = deflateInit( [OPT] ) ;
12 ($out, $status) = $d->deflate($buffer) ;
13 $status = $d->deflateParams([OPT]) ;
14 ($out, $status) = $d->flush() ;
15 $d->dict_adler() ;
16 $d->total_in() ;
17 $d->total_out() ;
18 $d->msg() ;
19 ($i, $status) = inflateInit( [OPT] ) ;
21 ($out, $status) = $i->inflate($buffer) ;
22 $status = $i->inflateSync($buffer) ;
23 $i->dict_adler() ;
24 $i->total_in() ;
25 $i->total_out() ;
26 $i->msg() ;
27 $dest = compress($source, [$level]) ;
29 $dest = uncompress($source) ;
30 $gz = gzopen($filename or filehandle, $mode) ;
32 $bytesread = $gz->gzread($buffer [,$size]) ;
33 $bytesread = $gz->gzreadline($line) ;
34 $byteswritten = $gz->gzwrite($buffer) ;
35 $status = $gz->gzflush($flush) ;
36 $status = $gz->gzclose() ;
37 $status = $gz->gzeof() ;
38 $status = $gz->gzsetparams($level, $strategy) ;
39 $errstring = $gz->gzerror() ;
40 $gzerrno
41 $dest = Compress::Zlib::memGzip($buffer) ;
43 $dest = Compress::Zlib::memGunzip($buffer) ;
44 $crc = adler32($buffer [,$crc]) ;
46 $crc = crc32($buffer [,$crc]) ;
47 ZLIB_VERSION
49
51 The Compress::Zlib module provides a Perl interface to the zlib com‐
52 pression library (see "AUTHOR" for details about where to get zlib).
53 Most of the functionality provided by zlib is available in Com‐
54 press::Zlib.
55 The module can be split into two general areas of functionality, namely
57 in-memory compression/decompression and read/write access to gzip
58 files. Each of these areas will be discussed separately below.
59
61 The interface Compress::Zlib provides to the in-memory deflate (and
62 inflate) functions has been modified to fit into a Perl model.
63 The main difference is that for both inflation and deflation, the Perl
65 interface will always consume the complete input buffer before return‐
66 ing. Also the output buffer returned will be automatically grown to fit
67 the amount of output available.
68 Here is a definition of the interface available:
70 ($d, $status) = deflateInit( [OPT] )
72 Initialises a deflation stream.
74 It combines the features of the zlib functions deflateInit,
76 deflateInit2 and deflateSetDictionary.
77 If successful, it will return the initialised deflation stream, $d and
79 $status of "Z_OK" in a list context. In scalar context it returns the
80 deflation stream, $d, only.
81 If not successful, the returned deflation stream ($d) will be undef and
83 $status will hold the exact zlib error code.
84 The function optionally takes a number of named options specified as
86 "-Name=>value" pairs. This allows individual options to be tailored
87 without having to specify them all in the parameter list.
88 For backward compatibility, it is also possible to pass the parameters
90 as a reference to a hash containing the name=>value pairs.
91 The function takes one optional parameter, a reference to a hash. The
93 contents of the hash allow the deflation interface to be tailored.
94 Here is a list of the valid options:
96 -Level
98 Defines the compression level. Valid values are 0 through 9,
99 "Z_NO_COMPRESSION", "Z_BEST_SPEED", "Z_BEST_COMPRESSION", and
100 "Z_DEFAULT_COMPRESSION".
101 The default is "-Level =>Z_DEFAULT_COMPRESSION".
103 -Method
105 Defines the compression method. The only valid value at present
106 (and the default) is "-Method =>Z_DEFLATED".
107 -WindowBits
109 For a definition of the meaning and valid values for WindowBits
110 refer to the zlib documentation for deflateInit2.
111 Defaults to "-WindowBits =>MAX_WBITS".
113 -MemLevel
115 For a definition of the meaning and valid values for MemLevel
116 refer to the zlib documentation for deflateInit2.
117 Defaults to "-MemLevel =>MAX_MEM_LEVEL".
119 -Strategy
121 Defines the strategy used to tune the compression. The valid val‐
122 ues are "Z_DEFAULT_STRATEGY", "Z_FILTERED" and "Z_HUFFMAN_ONLY".
123 The default is "-Strategy =>Z_DEFAULT_STRATEGY".
125 -Dictionary
127 When a dictionary is specified Compress::Zlib will automatically
128 call deflateSetDictionary directly after calling deflateInit. The
129 Adler32 value for the dictionary can be obtained by calling the
130 method "$d-"dict_adler()>.
131 The default is no dictionary.
133 -Bufsize
135 Sets the initial size for the deflation buffer. If the buffer has
136 to be reallocated to increase the size, it will grow in increments
137 of Bufsize.
138 The default is 4096.
140 Here is an example of using the deflateInit optional parameter list to
142 override the default buffer size and compression level. All other
143 options will take their default values.
144 deflateInit( -Bufsize => 300,
146 -Level => Z_BEST_SPEED ) ;
147 ($out, $status) = $d->deflate($buffer)
149 Deflates the contents of $buffer. The buffer can either be a scalar or
151 a scalar reference. When finished, $buffer will be completely pro‐
152 cessed (assuming there were no errors). If the deflation was successful
153 it returns the deflated output, $out, and a status value, $status, of
154 "Z_OK".
155 On error, $out will be undef and $status will contain the zlib error
157 code.
158 In a scalar context deflate will return $out only.
160 As with the deflate function in zlib, it is not necessarily the case
162 that any output will be produced by this method. So don't rely on the
163 fact that $out is empty for an error test.
164 ($out, $status) = $d->flush([flush_type])
166 Typically used to finish the deflation. Any pending output will be
168 returned via $out. $status will have a value "Z_OK" if successful.
169 In a scalar context flush will return $out only.
171 Note that flushing can seriously degrade the compression ratio, so it
173 should only be used to terminate a decompression (using "Z_FINISH") or
174 when you want to create a full flush point (using "Z_FULL_FLUSH").
175 By default the "flush_type" used is "Z_FINISH". Other valid values for
177 "flush_type" are "Z_NO_FLUSH", "Z_PARTIAL_FLUSH", "Z_SYNC_FLUSH" and
178 "Z_FULL_FLUSH". It is strongly recommended that you only set the
179 "flush_type" parameter if you fully understand the implications of what
180 it does. See the "zlib" documentation for details.
181 $status = $d->deflateParams([OPT])
183 Change settings for the deflate stream $d.
185 The list of the valid options is shown below. Options not specified
187 will remain unchanged.
188 -Level
190 Defines the compression level. Valid values are 0 through 9,
191 "Z_NO_COMPRESSION", "Z_BEST_SPEED", "Z_BEST_COMPRESSION", and
192 "Z_DEFAULT_COMPRESSION".
193 -Strategy
195 Defines the strategy used to tune the compression. The valid val‐
196 ues are "Z_DEFAULT_STRATEGY", "Z_FILTERED" and "Z_HUFFMAN_ONLY".
197 $d->dict_adler()
199 Returns the adler32 value for the dictionary.
201 $d->msg()
203 Returns the last error message generated by zlib.
205 $d->total_in()
207 Returns the total number of bytes uncompressed bytes input to deflate.
209 $d->total_out()
211 Returns the total number of compressed bytes output from deflate.
213 Example
215 Here is a trivial example of using deflate. It simply reads standard
217 input, deflates it and writes it to standard output.
218 use strict ;
220 use warnings ;
221 use Compress::Zlib ;
223 binmode STDIN;
225 binmode STDOUT;
226 my $x = deflateInit()
227 or die "Cannot create a deflation stream\n" ;
228 my ($output, $status) ;
230 while (<>)
231 {
232 ($output, $status) = $x->deflate($_) ;
233 $status == Z_OK
235 or die "deflation failed\n" ;
236 print $output ;
238 }
239 ($output, $status) = $x->flush() ;
241 $status == Z_OK
243 or die "deflation failed\n" ;
244 print $output ;
246
248 Here is a definition of the interface:
249 ($i, $status) = inflateInit()
251 Initialises an inflation stream.
253 In a list context it returns the inflation stream, $i, and the zlib
255 status code ($status). In a scalar context it returns the inflation
256 stream only.
257 If successful, $i will hold the inflation stream and $status will be
259 "Z_OK".
260 If not successful, $i will be undef and $status will hold the zlib
262 error code.
263 The function optionally takes a number of named options specified as
265 "-Name=>value" pairs. This allows individual options to be tailored
266 without having to specify them all in the parameter list.
267 For backward compatibility, it is also possible to pass the parameters
269 as a reference to a hash containing the name=>value pairs.
270 The function takes one optional parameter, a reference to a hash. The
272 contents of the hash allow the deflation interface to be tailored.
273 Here is a list of the valid options:
275 -WindowBits
277 For a definition of the meaning and valid values for WindowBits
278 refer to the zlib documentation for inflateInit2.
279 Defaults to "-WindowBits =>MAX_WBITS".
281 -Bufsize
283 Sets the initial size for the inflation buffer. If the buffer has
284 to be reallocated to increase the size, it will grow in increments
285 of Bufsize.
286 Default is 4096.
288 -Dictionary
290 The default is no dictionary.
291 Here is an example of using the inflateInit optional parameter to over‐
293 ride the default buffer size.
294 inflateInit( -Bufsize => 300 ) ;
296 ($out, $status) = $i->inflate($buffer)
298 Inflates the complete contents of $buffer. The buffer can either be a
300 scalar or a scalar reference.
301 Returns "Z_OK" if successful and "Z_STREAM_END" if the end of the com‐
303 pressed data has been successfully reached. If not successful, $out
304 will be undef and $status will hold the zlib error code.
305 The $buffer parameter is modified by "inflate". On completion it will
307 contain what remains of the input buffer after inflation. This means
308 that $buffer will be an empty string when the return status is "Z_OK".
309 When the return status is "Z_STREAM_END" the $buffer parameter will
310 contains what (if anything) was stored in the input buffer after the
311 deflated data stream.
312 This feature is useful when processing a file format that encapsulates
314 a compressed data stream (e.g. gzip, zip).
315 $status = $i->inflateSync($buffer)
317 Scans $buffer until it reaches either a full flush point or the end of
319 the buffer.
320 If a full flush point is found, "Z_OK" is returned and $buffer will be
322 have all data up to the flush point removed. This can then be passed to
323 the "deflate" method.
324 Any other return code means that a flush point was not found. If more
326 data is available, "inflateSync" can be called repeatedly with more
327 compressed data until the flush point is found.
328 $i->dict_adler()
330 Returns the adler32 value for the dictionary.
332 $i->msg()
334 Returns the last error message generated by zlib.
336 $i->total_in()
338 Returns the total number of bytes compressed bytes input to inflate.
340 $i->total_out()
342 Returns the total number of uncompressed bytes output from inflate.
344 Example
346 Here is an example of using inflate.
348 use strict ;
350 use warnings ;
351 use Compress::Zlib ;
353 my $x = inflateInit()
355 or die "Cannot create a inflation stream\n" ;
356 my $input = '' ;
358 binmode STDIN;
359 binmode STDOUT;
360 my ($output, $status) ;
362 while (read(STDIN, $input, 4096))
363 {
364 ($output, $status) = $x->inflate(\$input) ;
365 print $output
367 if $status == Z_OK or $status == Z_STREAM_END ;
368 last if $status != Z_OK ;
370 }
371 die "inflation failed\n"
373 unless $status == Z_STREAM_END ;
374
376 Two high-level functions are provided by zlib to perform in-memory com‐
377 pression/uncompression of RFC1950 data streams. They are called com‐
378 press and uncompress.
379 The two Perl subs defined below provide the equivalent functionality.
381 $dest = compress($source [, $level] ) ;
383 Compresses $source. If successful it returns the compressed data.
384 Otherwise it returns undef.
385 The source buffer can either be a scalar or a scalar reference.
387 The $level paramter defines the compression level. Valid values
389 are 0 through 9, "Z_NO_COMPRESSION", "Z_BEST_SPEED", "Z_BEST_COM‐
390 PRESSION", and "Z_DEFAULT_COMPRESSION". If $level is not speci‐
391 fied "Z_DEFAULT_COMPRESSION" will be used.
392 $dest = uncompress($source) ;
394 Uncompresses $source. If successful it returns the uncompressed
395 data. Otherwise it returns undef.
396 The source buffer can either be a scalar or a scalar reference.
398 Please note: the two functions defined above are not compatible with
400 the Unix commands of the same name.
401
403 A number of functions are supplied in zlib for reading and writing gzip
404 files. This module provides an interface to most of them. In general
405 the interface provided by this module operates identically to the func‐
406 tions provided by zlib. Any differences are explained below.
407 $gz = gzopen(filename or filehandle, mode)
409 This function operates identically to the zlib equivalent except
410 that it returns an object which is used to access the other gzip
411 methods.
412 As with the zlib equivalent, the mode parameter is used to specify
414 both whether the file is opened for reading or writing and to
415 optionally specify a a compression level. Refer to the zlib docu‐
416 mentation for the exact format of the mode parameter.
417 If a reference to an open filehandle is passed in place of the
419 filename, gzdopen will be called behind the scenes. The third
420 example at the end of this section, gzstream, uses this feature.
421 $bytesread = $gz->gzread($buffer [, $size]) ;
423 Reads $size bytes from the compressed file into $buffer. If $size
424 is not specified, it will default to 4096. If the scalar $buffer
425 is not large enough, it will be extended automatically.
426 Returns the number of bytes actually read. On EOF it returns 0 and
428 in the case of an error, -1.
429 $bytesread = $gz->gzreadline($line) ;
431 Reads the next line from the compressed file into $line.
432 Returns the number of bytes actually read. On EOF it returns 0 and
434 in the case of an error, -1.
435 It is legal to intermix calls to gzread and gzreadline.
437 At this time gzreadline ignores the variable $/
439 ($INPUT_RECORD_SEPARATOR or $RS when "English" is in use). The end
440 of a line is denoted by the C character '\n'.
441 $byteswritten = $gz->gzwrite($buffer) ;
443 Writes the contents of $buffer to the compressed file. Returns the
444 number of bytes actually written, or 0 on error.
445 $status = $gz->gzflush($flush) ;
447 Flushes all pending output to the compressed file. Works identi‐
448 cally to the zlib function it interfaces to. Note that the use of
449 gzflush can degrade compression.
450 Returns "Z_OK" if $flush is "Z_FINISH" and all output could be
452 flushed. Otherwise the zlib error code is returned.
453 Refer to the zlib documentation for the valid values of $flush.
455 $status = $gz->gzeof() ;
457 Returns 1 if the end of file has been detected while reading the
458 input file, otherwise returns 0.
459 $gz->gzclose
461 Closes the compressed file. Any pending data is flushed to the
462 file before it is closed.
463 $gz->gzsetparams($level, $strategy
465 Change settings for the deflate stream $gz.
466 The list of the valid options is shown below. Options not speci‐
468 fied will remain unchanged.
469 Note: This method is only available if you are running zlib 1.0.6
471 or better.
472 $level
474 Defines the compression level. Valid values are 0 through 9,
475 "Z_NO_COMPRESSION", "Z_BEST_SPEED", "Z_BEST_COMPRESSION", and
476 "Z_DEFAULT_COMPRESSION".
477 $strategy
479 Defines the strategy used to tune the compression. The valid
480 values are "Z_DEFAULT_STRATEGY", "Z_FILTERED" and "Z_HUFF‐
481 MAN_ONLY".
482 $gz->gzerror
484 Returns the zlib error message or number for the last operation
485 associated with $gz. The return value will be the zlib error num‐
486 ber when used in a numeric context and the zlib error message when
487 used in a string context. The zlib error number constants, shown
488 below, are available for use.
489 Z_OK
491 Z_STREAM_END
492 Z_ERRNO
493 Z_STREAM_ERROR
494 Z_DATA_ERROR
495 Z_MEM_ERROR
496 Z_BUF_ERROR
497 $gzerrno
499 The $gzerrno scalar holds the error code associated with the most
500 recent gzip routine. Note that unlike gzerror(), the error is not
501 associated with a particular file.
502 As with gzerror() it returns an error number in numeric context
504 and an error message in string context. Unlike gzerror() though,
505 the error message will correspond to the zlib message when the
506 error is associated with zlib itself, or the UNIX error message
507 when it is not (i.e. zlib returned "Z_ERRORNO").
508 As there is an overlap between the error numbers used by zlib and
510 UNIX, $gzerrno should only be used to check for the presence of an
511 error in numeric context. Use gzerror() to check for specific zlib
512 errors. The gzcat example below shows how the variable can be used
513 safely.
514 Examples
516 Here is an example script which uses the interface. It implements a
518 gzcat function.
519 use strict ;
521 use warnings ;
522 use Compress::Zlib ;
524 die "Usage: gzcat file...\n"
526 unless @ARGV ;
527 my $file ;
529 foreach $file (@ARGV) {
531 my $buffer ;
532 my $gz = gzopen($file, "rb")
534 or die "Cannot open $file: $gzerrno\n" ;
535 print $buffer while $gz->gzread($buffer) > 0 ;
537 die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n"
539 if $gzerrno != Z_STREAM_END ;
540 $gz->gzclose() ;
542 }
543 Below is a script which makes use of gzreadline. It implements a very
545 simple grep like script.
546 use strict ;
548 use warnings ;
549 use Compress::Zlib ;
551 die "Usage: gzgrep pattern file...\n"
553 unless @ARGV >= 2;
554 my $pattern = shift ;
556 my $file ;
558 foreach $file (@ARGV) {
560 my $gz = gzopen($file, "rb")
561 or die "Cannot open $file: $gzerrno\n" ;
562 while ($gz->gzreadline($_) > 0) {
564 print if /$pattern/ ;
565 }
566 die "Error reading from $file: $gzerrno\n"
568 if $gzerrno != Z_STREAM_END ;
569 $gz->gzclose() ;
571 }
572 This script, gzstream, does the opposite of the gzcat script above. It
574 reads from standard input and writes a gzip file to standard output.
575 use strict ;
577 use warnings ;
578 use Compress::Zlib ;
580 binmode STDOUT; # gzopen only sets it on the fd
582 my $gz = gzopen(\*STDOUT, "wb")
584 or die "Cannot open stdout: $gzerrno\n" ;
585 while (<>) {
587 $gz->gzwrite($_)
588 or die "error writing: $gzerrno\n" ;
589 }
590 $gz->gzclose ;
592 Compress::Zlib::memGzip
594 This function is used to create an in-memory gzip file. It creates a
596 minimal gzip header.
597 $dest = Compress::Zlib::memGzip($buffer) ;
599 If successful, it returns the in-memory gzip file, otherwise it returns
601 undef.
602 The buffer parameter can either be a scalar or a scalar reference.
604 Compress::Zlib::memGunzip
606 This function is used to uncompress an in-memory gzip file.
608 $dest = Compress::Zlib::memGunzip($buffer) ;
610 If successful, it returns the uncompressed gzip file, otherwise it
612 returns undef.
613 The buffer parameter can either be a scalar or a scalar reference. The
615 contents of the buffer parameter are destroyed after calling this func‐
616 tion.
617
619 Two functions are provided by zlib to calculate a checksum. For the
620 Perl interface, the order of the two parameters in both functions has
621 been reversed. This allows both running checksums and one off calcula‐
622 tions to be done.
623 $crc = adler32($buffer [,$crc]) ;
625 $crc = crc32($buffer [,$crc]) ;
626 The buffer parameters can either be a scalar or a scalar reference.
628 If the $crc parameters is "undef", the crc value will be reset.
630
632 Compatibility with Unix compress/uncompress.
633 Although "Compress::Zlib" has a pair of functions called "compress" and
635 "uncompress", they are not the same as the Unix programs of the same
636 name. The "Compress::Zlib" library is not compatable with Unix "com‐
637 press".
638 If you have the "uncompress" program available, you can use this to
640 read compressed files
641 open F, "uncompress -c $filename ⎪";
643 while (<F>)
644 {
645 ...
646 If you have the "gunzip" program available, you can use this to read
648 compressed files
649 open F, "gunzip -c $filename ⎪";
651 while (<F>)
652 {
653 ...
654 and this to write compress files if you have the "compress" program
656 available
657 open F, "⎪ compress -c $filename ";
659 print F "data";
660 ...
661 close F ;
662 Accessing .tar.Z files
664 The "Archive::Tar" module can optionally use "Compress::Zlib" (via the
666 "IO::Zlib" module) to access tar files that have been compressed with
667 "gzip". Unfortunately tar files compressed with the Unix "compress"
668 utility cannot be read by "Compress::Zlib" and so cannot be directly
669 accesses by "Archive::Tar".
670 If the "uncompress" or "gunzip" programs are available, you can use one
672 of these workarounds to read ".tar.Z" files from "Archive::Tar"
673 Firstly with "uncompress"
675 use strict;
677 use warnings;
678 use Archive::Tar;
679 open F, "uncompress -c $filename ⎪";
681 my $tar = Archive::Tar->new(*F);
682 ...
683 and this with "gunzip"
685 use strict;
687 use warnings;
688 use Archive::Tar;
689 open F, "gunzip -c $filename ⎪";
691 my $tar = Archive::Tar->new(*F);
692 ...
693 Similarly, if the "compress" program is available, you can use this to
695 write a ".tar.Z" file
696 use strict;
698 use warnings;
699 use Archive::Tar;
700 use IO::File;
701 my $fh = newIO::File "⎪ compress -c >$filename";
703 my $tar = Archive::Tar->new();
704 ...
705 $tar->write($fh);
706 $fh->close ;
707 Accessing ZIP Files
709 Although it is possible to use this module to access .zip files, there
711 is a module on CPAN that will do all the hard work for you. Check out
712 http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
714 Assuming you don't want to use this module to access zip files there
716 are a number of undocumented features in the zlib library you need to
717 be aware of.
718 1. When calling inflateInit or deflateInit the WindowBits parameter
720 must be set to "-MAX_WBITS". This disables the creation of the
721 zlib header.
722 2. The zlib function inflate, and so the inflate method supplied in
724 this module, assume that there is at least one trailing byte after
725 the compressed data stream. Normally this isn't a problem because
726 both the gzip and zip file formats will guarantee that there is
727 data directly after the compressed data stream.
728
730 All the zlib constants are automatically imported when you make use of
731 Compress::Zlib.
732
734 The Compress::Zlib module was written by Paul Marquess, pmqs@cpan.org.
735 The latest copy of the module can be found on CPAN in modules/by-mod‐
736 ule/Compress/Compress-Zlib-x.x.tar.gz.
737 The primary site for the zlib compression library is
739 http://www.zlib.org.
740
742 See the Changes file.
743perl v5.8.8 2006-07-17 Zlib(3)