d197a3478bd55f1b0625148ae69f9f0db3f2f97f
[perl.git] / cpan / IO-Compress / lib / Compress / Zlib.pm
1
2 package Compress::Zlib;
3
4 require 5.006 ;
5 require Exporter;
6 use Carp ;
7 use IO::Handle ;
8 use Scalar::Util qw(dualvar);
9
10 use IO::Compress::Base::Common 2.068 ;
11 use Compress::Raw::Zlib 2.068 ;
12 use IO::Compress::Gzip 2.068 ;
13 use IO::Uncompress::Gunzip 2.068 ;
14
15 use strict ;
16 use warnings ;
17 use bytes ;
18 our ($VERSION, $XS_VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
19
20 $VERSION = '2.068';
21 $XS_VERSION = $VERSION; 
22 $VERSION = eval $VERSION;
23
24 @ISA = qw(Exporter);
25 # Items to export into callers namespace by default. Note: do not export
26 # names by default without a very good reason. Use EXPORT_OK instead.
27 # Do not simply export all your public functions/methods/constants.
28 @EXPORT = qw(
29         deflateInit inflateInit
30
31         compress uncompress
32
33         gzopen $gzerrno
34     );
35
36 push @EXPORT, @Compress::Raw::Zlib::EXPORT ;
37
38 @EXPORT_OK = qw(memGunzip memGzip zlib_version);
39 %EXPORT_TAGS = (
40     ALL         => \@EXPORT
41 );
42
43 BEGIN
44 {
45     *zlib_version = \&Compress::Raw::Zlib::zlib_version;
46 }
47
48 use constant FLAG_APPEND             => 1 ;
49 use constant FLAG_CRC                => 2 ;
50 use constant FLAG_ADLER              => 4 ;
51 use constant FLAG_CONSUME_INPUT      => 8 ;
52
53 our (@my_z_errmsg);
54
55 @my_z_errmsg = (
56     "need dictionary",     # Z_NEED_DICT     2
57     "stream end",          # Z_STREAM_END    1
58     "",                    # Z_OK            0
59     "file error",          # Z_ERRNO        (-1)
60     "stream error",        # Z_STREAM_ERROR (-2)
61     "data error",          # Z_DATA_ERROR   (-3)
62     "insufficient memory", # Z_MEM_ERROR    (-4)
63     "buffer error",        # Z_BUF_ERROR    (-5)
64     "incompatible version",# Z_VERSION_ERROR(-6)
65     );
66
67
68 sub _set_gzerr
69 {
70     my $value = shift ;
71
72     if ($value == 0) {
73         $Compress::Zlib::gzerrno = 0 ;
74     }
75     elsif ($value == Z_ERRNO() || $value > 2) {
76         $Compress::Zlib::gzerrno = $! ;
77     }
78     else {
79         $Compress::Zlib::gzerrno = dualvar($value+0, $my_z_errmsg[2 - $value]);
80     }
81
82     return $value ;
83 }
84
85 sub _set_gzerr_undef
86 {
87     _set_gzerr(@_);
88     return undef;
89 }
90
91 sub _save_gzerr
92 {
93     my $gz = shift ;
94     my $test_eof = shift ;
95
96     my $value = $gz->errorNo() || 0 ;
97     my $eof = $gz->eof() ;
98
99     if ($test_eof) {
100         # gzread uses Z_STREAM_END to denote a successful end
101         $value = Z_STREAM_END() if $gz->eof() && $value == 0 ;
102     }
103
104     _set_gzerr($value) ;
105 }
106
107 sub gzopen($$)
108 {
109     my ($file, $mode) = @_ ;
110
111     my $gz ;
112     my %defOpts = (Level    => Z_DEFAULT_COMPRESSION(),
113                    Strategy => Z_DEFAULT_STRATEGY(),
114                   );
115
116     my $writing ;
117     $writing = ! ($mode =~ /r/i) ;
118     $writing = ($mode =~ /[wa]/i) ;
119
120     $defOpts{Level}    = $1               if $mode =~ /(\d)/;
121     $defOpts{Strategy} = Z_FILTERED()     if $mode =~ /f/i;
122     $defOpts{Strategy} = Z_HUFFMAN_ONLY() if $mode =~ /h/i;
123     $defOpts{Append}   = 1                if $mode =~ /a/i;
124
125     my $infDef = $writing ? 'deflate' : 'inflate';
126     my @params = () ;
127
128     croak "gzopen: file parameter is not a filehandle or filename"
129         unless isaFilehandle $file || isaFilename $file  || 
130                (ref $file && ref $file eq 'SCALAR');
131
132     return undef unless $mode =~ /[rwa]/i ;
133
134     _set_gzerr(0) ;
135
136     if ($writing) {
137         $gz = new IO::Compress::Gzip($file, Minimal => 1, AutoClose => 1, 
138                                      %defOpts) 
139             or $Compress::Zlib::gzerrno = $IO::Compress::Gzip::GzipError;
140     }
141     else {
142         $gz = new IO::Uncompress::Gunzip($file, 
143                                          Transparent => 1,
144                                          Append => 0, 
145                                          AutoClose => 1, 
146                                          MultiStream => 1,
147                                          Strict => 0) 
148             or $Compress::Zlib::gzerrno = $IO::Uncompress::Gunzip::GunzipError;
149     }
150
151     return undef
152         if ! defined $gz ;
153
154     bless [$gz, $infDef], 'Compress::Zlib::gzFile';
155 }
156
157 sub Compress::Zlib::gzFile::gzread
158 {
159     my $self = shift ;
160
161     return _set_gzerr(Z_STREAM_ERROR())
162         if $self->[1] ne 'inflate';
163
164     my $len = defined $_[1] ? $_[1] : 4096 ; 
165
166     my $gz = $self->[0] ;
167     if ($self->gzeof() || $len == 0) {
168         # Zap the output buffer to match ver 1 behaviour.
169         $_[0] = "" ;
170         _save_gzerr($gz, 1);
171         return 0 ;
172     }
173
174     my $status = $gz->read($_[0], $len) ; 
175     _save_gzerr($gz, 1);
176     return $status ;
177 }
178
179 sub Compress::Zlib::gzFile::gzreadline
180 {
181     my $self = shift ;
182
183     my $gz = $self->[0] ;
184     {
185         # Maintain backward compatibility with 1.x behaviour
186         # It didn't support $/, so this can't either.
187         local $/ = "\n" ;
188         $_[0] = $gz->getline() ; 
189     }
190     _save_gzerr($gz, 1);
191     return defined $_[0] ? length $_[0] : 0 ;
192 }
193
194 sub Compress::Zlib::gzFile::gzwrite
195 {
196     my $self = shift ;
197     my $gz = $self->[0] ;
198
199     return _set_gzerr(Z_STREAM_ERROR())
200         if $self->[1] ne 'deflate';
201
202     $] >= 5.008 and (utf8::downgrade($_[0], 1) 
203         or croak "Wide character in gzwrite");
204
205     my $status = $gz->write($_[0]) ;
206     _save_gzerr($gz);
207     return $status ;
208 }
209
210 sub Compress::Zlib::gzFile::gztell
211 {
212     my $self = shift ;
213     my $gz = $self->[0] ;
214     my $status = $gz->tell() ;
215     _save_gzerr($gz);
216     return $status ;
217 }
218
219 sub Compress::Zlib::gzFile::gzseek
220 {
221     my $self   = shift ;
222     my $offset = shift ;
223     my $whence = shift ;
224
225     my $gz = $self->[0] ;
226     my $status ;
227     eval { $status = $gz->seek($offset, $whence) ; };
228     if ($@)
229     {
230         my $error = $@;
231         $error =~ s/^.*: /gzseek: /;
232         $error =~ s/ at .* line \d+\s*$//;
233         croak $error;
234     }
235     _save_gzerr($gz);
236     return $status ;
237 }
238
239 sub Compress::Zlib::gzFile::gzflush
240 {
241     my $self = shift ;
242     my $f    = shift ;
243
244     my $gz = $self->[0] ;
245     my $status = $gz->flush($f) ;
246     my $err = _save_gzerr($gz);
247     return $status ? 0 : $err;
248 }
249
250 sub Compress::Zlib::gzFile::gzclose
251 {
252     my $self = shift ;
253     my $gz = $self->[0] ;
254
255     my $status = $gz->close() ;
256     my $err = _save_gzerr($gz);
257     return $status ? 0 : $err;
258 }
259
260 sub Compress::Zlib::gzFile::gzeof
261 {
262     my $self = shift ;
263     my $gz = $self->[0] ;
264
265     return 0
266         if $self->[1] ne 'inflate';
267
268     my $status = $gz->eof() ;
269     _save_gzerr($gz);
270     return $status ;
271 }
272
273 sub Compress::Zlib::gzFile::gzsetparams
274 {
275     my $self = shift ;
276     croak "Usage: Compress::Zlib::gzFile::gzsetparams(file, level, strategy)"
277         unless @_ eq 2 ;
278
279     my $gz = $self->[0] ;
280     my $level = shift ;
281     my $strategy = shift;
282
283     return _set_gzerr(Z_STREAM_ERROR())
284         if $self->[1] ne 'deflate';
285  
286     my $status = *$gz->{Compress}->deflateParams(-Level   => $level, 
287                                                 -Strategy => $strategy);
288     _save_gzerr($gz);
289     return $status ;
290 }
291
292 sub Compress::Zlib::gzFile::gzerror
293 {
294     my $self = shift ;
295     my $gz = $self->[0] ;
296     
297     return $Compress::Zlib::gzerrno ;
298 }
299
300
301 sub compress($;$)
302 {
303     my ($x, $output, $err, $in) =('', '', '', '') ;
304
305     if (ref $_[0] ) {
306         $in = $_[0] ;
307         croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
308     }
309     else {
310         $in = \$_[0] ;
311     }
312
313     $] >= 5.008 and (utf8::downgrade($$in, 1) 
314         or croak "Wide character in compress");
315
316     my $level = (@_ == 2 ? $_[1] : Z_DEFAULT_COMPRESSION() );
317
318     $x = Compress::Raw::Zlib::_deflateInit(FLAG_APPEND,
319                                            $level,
320                                            Z_DEFLATED,
321                                            MAX_WBITS,
322                                            MAX_MEM_LEVEL,
323                                            Z_DEFAULT_STRATEGY,
324                                            4096,
325                                            '') 
326             or return undef ;
327
328     $err = $x->deflate($in, $output) ;
329     return undef unless $err == Z_OK() ;
330
331     $err = $x->flush($output) ;
332     return undef unless $err == Z_OK() ;
333     
334     return $output ;
335 }
336
337 sub uncompress($)
338 {
339     my ($output, $in) =('', '') ;
340
341     if (ref $_[0] ) {
342         $in = $_[0] ;
343         croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
344     }
345     else {
346         $in = \$_[0] ;
347     }
348
349     $] >= 5.008 and (utf8::downgrade($$in, 1) 
350         or croak "Wide character in uncompress");    
351         
352     my ($obj, $status) = Compress::Raw::Zlib::_inflateInit(0,
353                                 MAX_WBITS, 4096, "") ;   
354                                 
355     $status == Z_OK 
356         or return undef;
357     
358     $obj->inflate($in, $output) == Z_STREAM_END 
359         or return undef;
360     
361     return $output;
362 }
363  
364 sub deflateInit(@)
365 {
366     my ($got) = ParseParameters(0,
367                 {
368                 'bufsize'       => [IO::Compress::Base::Common::Parse_unsigned, 4096],
369                 'level'         => [IO::Compress::Base::Common::Parse_signed,   Z_DEFAULT_COMPRESSION()],
370                 'method'        => [IO::Compress::Base::Common::Parse_unsigned, Z_DEFLATED()],
371                 'windowbits'    => [IO::Compress::Base::Common::Parse_signed,   MAX_WBITS()],
372                 'memlevel'      => [IO::Compress::Base::Common::Parse_unsigned, MAX_MEM_LEVEL()],
373                 'strategy'      => [IO::Compress::Base::Common::Parse_unsigned, Z_DEFAULT_STRATEGY()],
374                 'dictionary'    => [IO::Compress::Base::Common::Parse_any,      ""],
375                 }, @_ ) ;
376
377     croak "Compress::Zlib::deflateInit: Bufsize must be >= 1, you specified " . 
378             $got->getValue('bufsize')
379         unless $got->getValue('bufsize') >= 1;
380
381     my $obj ;
382  
383     my $status = 0 ;
384     ($obj, $status) = 
385       Compress::Raw::Zlib::_deflateInit(0,
386                 $got->getValue('level'), 
387                 $got->getValue('method'), 
388                 $got->getValue('windowbits'), 
389                 $got->getValue('memlevel'), 
390                 $got->getValue('strategy'), 
391                 $got->getValue('bufsize'),
392                 $got->getValue('dictionary')) ;
393
394     my $x = ($status == Z_OK() ? bless $obj, "Zlib::OldDeflate"  : undef) ;
395     return wantarray ? ($x, $status) : $x ;
396 }
397  
398 sub inflateInit(@)
399 {
400     my ($got) = ParseParameters(0,
401                 {
402                 'bufsize'       => [IO::Compress::Base::Common::Parse_unsigned, 4096],
403                 'windowbits'    => [IO::Compress::Base::Common::Parse_signed,   MAX_WBITS()],
404                 'dictionary'    => [IO::Compress::Base::Common::Parse_any,      ""],
405                 }, @_) ;
406
407
408     croak "Compress::Zlib::inflateInit: Bufsize must be >= 1, you specified " . 
409             $got->getValue('bufsize')
410         unless $got->getValue('bufsize') >= 1;
411
412     my $status = 0 ;
413     my $obj ;
414     ($obj, $status) = Compress::Raw::Zlib::_inflateInit(FLAG_CONSUME_INPUT,
415                                 $got->getValue('windowbits'), 
416                                 $got->getValue('bufsize'), 
417                                 $got->getValue('dictionary')) ;
418
419     my $x = ($status == Z_OK() ? bless $obj, "Zlib::OldInflate"  : undef) ;
420
421     wantarray ? ($x, $status) : $x ;
422 }
423
424 package Zlib::OldDeflate ;
425
426 our (@ISA);
427 @ISA = qw(Compress::Raw::Zlib::deflateStream);
428
429
430 sub deflate
431 {
432     my $self = shift ;
433     my $output ;
434
435     my $status = $self->SUPER::deflate($_[0], $output) ;
436     wantarray ? ($output, $status) : $output ;
437 }
438
439 sub flush
440 {
441     my $self = shift ;
442     my $output ;
443     my $flag = shift || Compress::Zlib::Z_FINISH();
444     my $status = $self->SUPER::flush($output, $flag) ;
445     
446     wantarray ? ($output, $status) : $output ;
447 }
448
449 package Zlib::OldInflate ;
450
451 our (@ISA);
452 @ISA = qw(Compress::Raw::Zlib::inflateStream);
453
454 sub inflate
455 {
456     my $self = shift ;
457     my $output ;
458     my $status = $self->SUPER::inflate($_[0], $output) ;
459     wantarray ? ($output, $status) : $output ;
460 }
461
462 package Compress::Zlib ;
463
464 use IO::Compress::Gzip::Constants 2.068 ;
465
466 sub memGzip($)
467 {
468     _set_gzerr(0);
469     my $x = Compress::Raw::Zlib::_deflateInit(FLAG_APPEND|FLAG_CRC,
470                                            Z_BEST_COMPRESSION,
471                                            Z_DEFLATED,
472                                            -MAX_WBITS(),
473                                            MAX_MEM_LEVEL,
474                                            Z_DEFAULT_STRATEGY,
475                                            4096,
476                                            '') 
477             or return undef ;
478  
479     # if the deflation buffer isn't a reference, make it one
480     my $string = (ref $_[0] ? $_[0] : \$_[0]) ;
481
482     $] >= 5.008 and (utf8::downgrade($$string, 1) 
483         or croak "Wide character in memGzip");
484
485     my $out;
486     my $status ;
487
488     $x->deflate($string, $out) == Z_OK
489         or return undef ;
490  
491     $x->flush($out) == Z_OK
492         or return undef ;
493  
494     return IO::Compress::Gzip::Constants::GZIP_MINIMUM_HEADER . 
495            $out . 
496            pack("V V", $x->crc32(), $x->total_in());
497 }
498
499
500 sub _removeGzipHeader($)
501 {
502     my $string = shift ;
503
504     return Z_DATA_ERROR() 
505         if length($$string) < GZIP_MIN_HEADER_SIZE ;
506
507     my ($magic1, $magic2, $method, $flags, $time, $xflags, $oscode) = 
508         unpack ('CCCCVCC', $$string);
509
510     return Z_DATA_ERROR()
511         unless $magic1 == GZIP_ID1 and $magic2 == GZIP_ID2 and
512            $method == Z_DEFLATED() and !($flags & GZIP_FLG_RESERVED) ;
513     substr($$string, 0, GZIP_MIN_HEADER_SIZE) = '' ;
514
515     # skip extra field
516     if ($flags & GZIP_FLG_FEXTRA)
517     {
518         return Z_DATA_ERROR()
519             if length($$string) < GZIP_FEXTRA_HEADER_SIZE ;
520
521         my ($extra_len) = unpack ('v', $$string);
522         $extra_len += GZIP_FEXTRA_HEADER_SIZE;
523         return Z_DATA_ERROR()
524             if length($$string) < $extra_len ;
525
526         substr($$string, 0, $extra_len) = '';
527     }
528
529     # skip orig name
530     if ($flags & GZIP_FLG_FNAME)
531     {
532         my $name_end = index ($$string, GZIP_NULL_BYTE);
533         return Z_DATA_ERROR()
534            if $name_end == -1 ;
535         substr($$string, 0, $name_end + 1) =  '';
536     }
537
538     # skip comment
539     if ($flags & GZIP_FLG_FCOMMENT)
540     {
541         my $comment_end = index ($$string, GZIP_NULL_BYTE);
542         return Z_DATA_ERROR()
543             if $comment_end == -1 ;
544         substr($$string, 0, $comment_end + 1) = '';
545     }
546
547     # skip header crc
548     if ($flags & GZIP_FLG_FHCRC)
549     {
550         return Z_DATA_ERROR()
551             if length ($$string) < GZIP_FHCRC_SIZE ;
552         substr($$string, 0, GZIP_FHCRC_SIZE) = '';
553     }
554     
555     return Z_OK();
556 }
557
558 sub _ret_gun_error
559 {
560     $Compress::Zlib::gzerrno = $IO::Uncompress::Gunzip::GunzipError;
561     return undef;
562 }
563
564
565 sub memGunzip($)
566 {
567     # if the buffer isn't a reference, make it one
568     my $string = (ref $_[0] ? $_[0] : \$_[0]);
569  
570     $] >= 5.008 and (utf8::downgrade($$string, 1) 
571         or croak "Wide character in memGunzip");
572
573     _set_gzerr(0);
574
575     my $status = _removeGzipHeader($string) ;
576     $status == Z_OK() 
577         or return _set_gzerr_undef($status);
578      
579     my $bufsize = length $$string > 4096 ? length $$string : 4096 ;
580     my $x = Compress::Raw::Zlib::_inflateInit(FLAG_CRC | FLAG_CONSUME_INPUT,
581                                 -MAX_WBITS(), $bufsize, '') 
582               or return _ret_gun_error();
583
584     my $output = '' ;
585     $status = $x->inflate($string, $output);
586     
587     if ( $status == Z_OK() )
588     {
589         _set_gzerr(Z_DATA_ERROR());
590         return undef;
591     }
592
593     return _ret_gun_error()
594         if ($status != Z_STREAM_END());
595
596     if (length $$string >= 8)
597     {
598         my ($crc, $len) = unpack ("VV", substr($$string, 0, 8));
599         substr($$string, 0, 8) = '';
600         return _set_gzerr_undef(Z_DATA_ERROR())
601             unless $len == length($output) and
602                    $crc == Compress::Raw::Zlib::crc32($output);
603     }
604     else
605     {
606         $$string = '';
607     }
608
609     return $output;   
610 }
611
612 # Autoload methods go after __END__, and are processed by the autosplit program.
613
614 1;
615 __END__
616
617
618 =head1 NAME
619
620 Compress::Zlib - Interface to zlib compression library
621
622 =head1 SYNOPSIS
623
624     use Compress::Zlib ;
625
626     ($d, $status) = deflateInit( [OPT] ) ;
627     $status = $d->deflate($input, $output) ;
628     $status = $d->flush([$flush_type]) ;
629     $d->deflateParams(OPTS) ;
630     $d->deflateTune(OPTS) ;
631     $d->dict_adler() ;
632     $d->crc32() ;
633     $d->adler32() ;
634     $d->total_in() ;
635     $d->total_out() ;
636     $d->msg() ;
637     $d->get_Strategy();
638     $d->get_Level();
639     $d->get_BufSize();
640
641     ($i, $status) = inflateInit( [OPT] ) ;
642     $status = $i->inflate($input, $output [, $eof]) ;
643     $status = $i->inflateSync($input) ;
644     $i->dict_adler() ;
645     $d->crc32() ;
646     $d->adler32() ;
647     $i->total_in() ;
648     $i->total_out() ;
649     $i->msg() ;
650     $d->get_BufSize();
651
652     $dest = compress($source) ;
653     $dest = uncompress($source) ;
654
655     $gz = gzopen($filename or filehandle, $mode) ;
656     $bytesread = $gz->gzread($buffer [,$size]) ;
657     $bytesread = $gz->gzreadline($line) ;
658     $byteswritten = $gz->gzwrite($buffer) ;
659     $status = $gz->gzflush($flush) ;
660     $offset = $gz->gztell() ;
661     $status = $gz->gzseek($offset, $whence) ;
662     $status = $gz->gzclose() ;
663     $status = $gz->gzeof() ;
664     $status = $gz->gzsetparams($level, $strategy) ;
665     $errstring = $gz->gzerror() ; 
666     $gzerrno
667
668     $dest = Compress::Zlib::memGzip($buffer) ;
669     $dest = Compress::Zlib::memGunzip($buffer) ;
670
671     $crc = adler32($buffer [,$crc]) ;
672     $crc = crc32($buffer [,$crc]) ;
673
674     $crc = crc32_combine($crc1, $crc2, $len2);
675     $adler = adler32_combine($adler1, $adler2, $len2);
676
677     my $version = Compress::Raw::Zlib::zlib_version();
678
679 =head1 DESCRIPTION
680
681 The I<Compress::Zlib> module provides a Perl interface to the I<zlib>
682 compression library (see L</AUTHOR> for details about where to get
683 I<zlib>). 
684
685 The C<Compress::Zlib> module can be split into two general areas of
686 functionality, namely a simple read/write interface to I<gzip> files
687 and a low-level in-memory compression/decompression interface.
688
689 Each of these areas will be discussed in the following sections.
690
691 =head2 Notes for users of Compress::Zlib version 1
692
693 The main change in C<Compress::Zlib> version 2.x is that it does not now
694 interface directly to the zlib library. Instead it uses the
695 C<IO::Compress::Gzip> and C<IO::Uncompress::Gunzip> modules for
696 reading/writing gzip files, and the C<Compress::Raw::Zlib> module for some
697 low-level zlib access. 
698
699 The interface provided by version 2 of this module should be 100% backward
700 compatible with version 1. If you find a difference in the expected
701 behaviour please contact the author (See L</AUTHOR>). See L<GZIP INTERFACE> 
702
703 With the creation of the C<IO::Compress> and C<IO::Uncompress> modules no
704 new features are planned for C<Compress::Zlib> - the new modules do
705 everything that C<Compress::Zlib> does and then some. Development on
706 C<Compress::Zlib> will be limited to bug fixes only.
707
708 If you are writing new code, your first port of call should be one of the
709 new C<IO::Compress> or C<IO::Uncompress> modules.
710
711 =head1 GZIP INTERFACE
712
713 A number of functions are supplied in I<zlib> for reading and writing
714 I<gzip> files that conform to RFC 1952. This module provides an interface
715 to most of them. 
716
717 If you have previously used C<Compress::Zlib> 1.x, the following
718 enhancements/changes have been made to the C<gzopen> interface:
719
720 =over 5
721
722 =item 1
723
724 If you want to open either STDIN or STDOUT with C<gzopen>, you can now
725 optionally use the special filename "C<->" as a synonym for C<\*STDIN> and
726 C<\*STDOUT>.
727
728 =item 2 
729
730 In C<Compress::Zlib> version 1.x, C<gzopen> used the zlib library to open
731 the underlying file. This made things especially tricky when a Perl
732 filehandle was passed to C<gzopen>. Behind the scenes the numeric C file
733 descriptor had to be extracted from the Perl filehandle and this passed to
734 the zlib library.
735
736 Apart from being non-portable to some operating systems, this made it
737 difficult to use C<gzopen> in situations where you wanted to extract/create
738 a gzip data stream that is embedded in a larger file, without having to
739 resort to opening and closing the file multiple times. 
740
741 It also made it impossible to pass a perl filehandle that wasn't associated
742 with a real filesystem file, like, say, an C<IO::String>.
743
744 In C<Compress::Zlib> version 2.x, the C<gzopen> interface has been
745 completely rewritten to use the L<IO::Compress::Gzip|IO::Compress::Gzip>
746 for writing gzip files and L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>
747 for reading gzip files. None of the limitations mentioned above apply.
748
749 =item 3
750
751 Addition of C<gzseek> to provide a restricted C<seek> interface.
752
753 =item 4.
754
755 Added C<gztell>.
756
757 =back
758
759 A more complete and flexible interface for reading/writing gzip
760 files/buffers is included with the module C<IO-Compress-Zlib>. See
761 L<IO::Compress::Gzip|IO::Compress::Gzip> and
762 L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for more details.
763
764 =over 5
765
766 =item B<$gz = gzopen($filename, $mode)>
767
768 =item B<$gz = gzopen($filehandle, $mode)>
769
770 This function opens either the I<gzip> file C<$filename> for reading or
771 writing or attaches to the opened filehandle, C<$filehandle>. 
772 It returns an object on success and C<undef> on failure.
773
774 When writing a gzip file this interface will I<always> create the smallest
775 possible gzip header (exactly 10 bytes). If you want greater control over
776 what gets stored in the gzip header (like the original filename or a
777 comment) use L<IO::Compress::Gzip|IO::Compress::Gzip> instead. Similarly if
778 you want to read the contents of the gzip header use
779 L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
780
781 The second parameter, C<$mode>, is used to specify whether the file is
782 opened for reading or writing and to optionally specify a compression
783 level and compression strategy when writing. The format of the C<$mode>
784 parameter is similar to the mode parameter to the 'C' function C<fopen>,
785 so "rb" is used to open for reading, "wb" for writing and "ab" for
786 appending (writing at the end of the file).
787
788 To specify a compression level when writing, append a digit between 0
789 and 9 to the mode string -- 0 means no compression and 9 means maximum
790 compression.
791 If no compression level is specified Z_DEFAULT_COMPRESSION is used.
792
793 To specify the compression strategy when writing, append 'f' for filtered
794 data, 'h' for Huffman only compression, or 'R' for run-length encoding.
795 If no strategy is specified Z_DEFAULT_STRATEGY is used.
796
797 So, for example, "wb9" means open for writing with the maximum compression
798 using the default strategy and "wb4R" means open for writing with compression
799 level 4 and run-length encoding.
800
801 Refer to the I<zlib> documentation for the exact format of the C<$mode>
802 parameter.
803
804 =item B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>
805
806 Reads C<$size> bytes from the compressed file into C<$buffer>. If
807 C<$size> is not specified, it will default to 4096. If the scalar
808 C<$buffer> is not large enough, it will be extended automatically.
809
810 Returns the number of bytes actually read. On EOF it returns 0 and in
811 the case of an error, -1.
812
813 =item B<$bytesread = $gz-E<gt>gzreadline($line) ;>
814
815 Reads the next line from the compressed file into C<$line>. 
816
817 Returns the number of bytes actually read. On EOF it returns 0 and in
818 the case of an error, -1.
819
820 It is legal to intermix calls to C<gzread> and C<gzreadline>.
821
822 To maintain backward compatibility with version 1.x of this module
823 C<gzreadline> ignores the C<$/> variable - it I<always> uses the string
824 C<"\n"> as the line delimiter.  
825
826 If you want to read a gzip file a line at a time and have it respect the
827 C<$/> variable (or C<$INPUT_RECORD_SEPARATOR>, or C<$RS> when C<English> is
828 in use) see L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
829
830 =item B<$byteswritten = $gz-E<gt>gzwrite($buffer) ;>
831
832 Writes the contents of C<$buffer> to the compressed file. Returns the
833 number of bytes actually written, or 0 on error.
834
835 =item B<$status = $gz-E<gt>gzflush($flush_type) ;>
836
837 Flushes all pending output into the compressed file.
838
839 This method takes an optional parameter, C<$flush_type>, that controls
840 how the flushing will be carried out. By default the C<$flush_type>
841 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
842 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
843 strongly recommended that you only set the C<flush_type> parameter if
844 you fully understand the implications of what it does - overuse of C<flush>
845 can seriously degrade the level of compression achieved. See the C<zlib>
846 documentation for details.
847
848 Returns 0 on success.
849
850 =item B<$offset = $gz-E<gt>gztell() ;>
851
852 Returns the uncompressed file offset.
853
854 =item B<$status = $gz-E<gt>gzseek($offset, $whence) ;>
855
856 Provides a sub-set of the C<seek> functionality, with the restriction
857 that it is only legal to seek forward in the compressed file.
858 It is a fatal error to attempt to seek backward.
859
860 When opened for writing, empty parts of the file will have NULL (0x00)
861 bytes written to them.
862
863 The C<$whence> parameter should be one of SEEK_SET, SEEK_CUR or SEEK_END.
864
865 Returns 1 on success, 0 on failure.
866
867 =item B<$gz-E<gt>gzclose>
868
869 Closes the compressed file. Any pending data is flushed to the file
870 before it is closed.
871
872 Returns 0 on success.
873
874 =item B<$gz-E<gt>gzsetparams($level, $strategy>
875
876 Change settings for the deflate stream C<$gz>.
877
878 The list of the valid options is shown below. Options not specified
879 will remain unchanged.
880
881 Note: This method is only available if you are running zlib 1.0.6 or better.
882
883 =over 5
884
885 =item B<$level>
886
887 Defines the compression level. Valid values are 0 through 9,
888 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
889 C<Z_DEFAULT_COMPRESSION>.
890
891 =item B<$strategy>
892
893 Defines the strategy used to tune the compression. The valid values are
894 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>. 
895
896 =back
897
898 =item B<$gz-E<gt>gzerror>
899
900 Returns the I<zlib> error message or number for the last operation
901 associated with C<$gz>. The return value will be the I<zlib> error
902 number when used in a numeric context and the I<zlib> error message
903 when used in a string context. The I<zlib> error number constants,
904 shown below, are available for use.
905
906     Z_OK
907     Z_STREAM_END
908     Z_ERRNO
909     Z_STREAM_ERROR
910     Z_DATA_ERROR
911     Z_MEM_ERROR
912     Z_BUF_ERROR
913
914 =item B<$gzerrno>
915
916 The C<$gzerrno> scalar holds the error code associated with the most
917 recent I<gzip> routine. Note that unlike C<gzerror()>, the error is
918 I<not> associated with a particular file.
919
920 As with C<gzerror()> it returns an error number in numeric context and
921 an error message in string context. Unlike C<gzerror()> though, the
922 error message will correspond to the I<zlib> message when the error is
923 associated with I<zlib> itself, or the UNIX error message when it is
924 not (i.e. I<zlib> returned C<Z_ERRORNO>).
925
926 As there is an overlap between the error numbers used by I<zlib> and
927 UNIX, C<$gzerrno> should only be used to check for the presence of
928 I<an> error in numeric context. Use C<gzerror()> to check for specific
929 I<zlib> errors. The I<gzcat> example below shows how the variable can
930 be used safely.
931
932 =back
933
934 =head2 Examples
935
936 Here is an example script which uses the interface. It implements a
937 I<gzcat> function.
938
939     use strict ;
940     use warnings ;
941     
942     use Compress::Zlib ;
943     
944     # use stdin if no files supplied
945     @ARGV = '-' unless @ARGV ;
946     
947     foreach my $file (@ARGV) {
948         my $buffer ;
949     
950         my $gz = gzopen($file, "rb") 
951              or die "Cannot open $file: $gzerrno\n" ;
952     
953         print $buffer while $gz->gzread($buffer) > 0 ;
954     
955         die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n" 
956             if $gzerrno != Z_STREAM_END ;
957         
958         $gz->gzclose() ;
959     }
960
961 Below is a script which makes use of C<gzreadline>. It implements a
962 very simple I<grep> like script.
963
964     use strict ;
965     use warnings ;
966     
967     use Compress::Zlib ;
968     
969     die "Usage: gzgrep pattern [file...]\n"
970         unless @ARGV >= 1;
971     
972     my $pattern = shift ;
973     
974     # use stdin if no files supplied
975     @ARGV = '-' unless @ARGV ;
976     
977     foreach my $file (@ARGV) {
978         my $gz = gzopen($file, "rb") 
979              or die "Cannot open $file: $gzerrno\n" ;
980     
981         while ($gz->gzreadline($_) > 0) {
982             print if /$pattern/ ;
983         }
984     
985         die "Error reading from $file: $gzerrno\n" 
986             if $gzerrno != Z_STREAM_END ;
987         
988         $gz->gzclose() ;
989     }
990
991 This script, I<gzstream>, does the opposite of the I<gzcat> script
992 above. It reads from standard input and writes a gzip data stream to
993 standard output.
994
995     use strict ;
996     use warnings ;
997     
998     use Compress::Zlib ;
999     
1000     binmode STDOUT;  # gzopen only sets it on the fd
1001     
1002     my $gz = gzopen(\*STDOUT, "wb")
1003           or die "Cannot open stdout: $gzerrno\n" ;
1004     
1005     while (<>) {
1006         $gz->gzwrite($_) 
1007           or die "error writing: $gzerrno\n" ;
1008     }
1009
1010     $gz->gzclose ;
1011
1012 =head2 Compress::Zlib::memGzip
1013
1014 This function is used to create an in-memory gzip file with the minimum
1015 possible gzip header (exactly 10 bytes).
1016
1017     $dest = Compress::Zlib::memGzip($buffer) 
1018         or die "Cannot compress: $gzerrno\n";
1019
1020 If successful, it returns the in-memory gzip file. Otherwise it returns
1021 C<undef> and the C<$gzerrno> variable will store the zlib error code.
1022
1023 The C<$buffer> parameter can either be a scalar or a scalar reference.
1024
1025 See L<IO::Compress::Gzip|IO::Compress::Gzip> for an alternative way to
1026 carry out in-memory gzip compression.
1027
1028 =head2 Compress::Zlib::memGunzip
1029
1030 This function is used to uncompress an in-memory gzip file.
1031
1032     $dest = Compress::Zlib::memGunzip($buffer) 
1033         or die "Cannot uncompress: $gzerrno\n";
1034
1035 If successful, it returns the uncompressed gzip file. Otherwise it
1036 returns C<undef> and the C<$gzerrno> variable will store the zlib error
1037 code.
1038
1039 The C<$buffer> parameter can either be a scalar or a scalar reference. The
1040 contents of the C<$buffer> parameter are destroyed after calling this function.
1041
1042 If C<$buffer> consists of multiple concatenated gzip data streams only the
1043 first will be uncompressed. Use C<gunzip> with the C<MultiStream> option in
1044 the C<IO::Uncompress::Gunzip> module if you need to deal with concatenated
1045 data streams.
1046
1047 See L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for an alternative way
1048 to carry out in-memory gzip uncompression.
1049
1050 =head1 COMPRESS/UNCOMPRESS
1051
1052 Two functions are provided to perform in-memory compression/uncompression of
1053 RFC 1950 data streams. They are called C<compress> and C<uncompress>.
1054
1055 =over 5
1056
1057 =item B<$dest = compress($source [, $level] ) ;>
1058
1059 Compresses C<$source>. If successful it returns the compressed
1060 data. Otherwise it returns I<undef>.
1061
1062 The source buffer, C<$source>, can either be a scalar or a scalar
1063 reference.
1064
1065 The C<$level> parameter defines the compression level. Valid values are
1066 0 through 9, C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>,
1067 C<Z_BEST_COMPRESSION>, and C<Z_DEFAULT_COMPRESSION>.
1068 If C<$level> is not specified C<Z_DEFAULT_COMPRESSION> will be used.
1069
1070 =item B<$dest = uncompress($source) ;>
1071
1072 Uncompresses C<$source>. If successful it returns the uncompressed
1073 data. Otherwise it returns I<undef>.
1074
1075 The source buffer can either be a scalar or a scalar reference.
1076
1077 =back
1078
1079 Please note: the two functions defined above are I<not> compatible with
1080 the Unix commands of the same name.
1081
1082 See L<IO::Deflate|IO::Deflate> and L<IO::Inflate|IO::Inflate> included with
1083 this distribution for an alternative interface for reading/writing RFC 1950
1084 files/buffers.
1085
1086 =head1 Deflate Interface
1087
1088 This section defines an interface that allows in-memory compression using
1089 the I<deflate> interface provided by zlib.
1090
1091 Here is a definition of the interface available:
1092
1093 =head2 B<($d, $status) = deflateInit( [OPT] )>
1094
1095 Initialises a deflation stream. 
1096
1097 It combines the features of the I<zlib> functions C<deflateInit>,
1098 C<deflateInit2> and C<deflateSetDictionary>.
1099
1100 If successful, it will return the initialised deflation stream, C<$d>
1101 and C<$status> of C<Z_OK> in a list context. In scalar context it
1102 returns the deflation stream, C<$d>, only.
1103
1104 If not successful, the returned deflation stream (C<$d>) will be
1105 I<undef> and C<$status> will hold the exact I<zlib> error code.
1106
1107 The function optionally takes a number of named options specified as
1108 C<< -Name=>value >> pairs. This allows individual options to be
1109 tailored without having to specify them all in the parameter list.
1110
1111 For backward compatibility, it is also possible to pass the parameters
1112 as a reference to a hash containing the name=>value pairs.
1113
1114 The function takes one optional parameter, a reference to a hash.  The
1115 contents of the hash allow the deflation interface to be tailored.
1116
1117 Here is a list of the valid options:
1118
1119 =over 5
1120
1121 =item B<-Level>
1122
1123 Defines the compression level. Valid values are 0 through 9,
1124 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1125 C<Z_DEFAULT_COMPRESSION>.
1126
1127 The default is Z_DEFAULT_COMPRESSION.
1128
1129 =item B<-Method>
1130
1131 Defines the compression method. The only valid value at present (and
1132 the default) is Z_DEFLATED.
1133
1134 =item B<-WindowBits>
1135
1136 To create an RFC 1950 data stream, set C<WindowBits> to a positive number.
1137
1138 To create an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
1139
1140 For a full definition of the meaning and valid values for C<WindowBits> refer
1141 to the I<zlib> documentation for I<deflateInit2>.
1142
1143 Defaults to MAX_WBITS.
1144
1145 =item B<-MemLevel>
1146
1147 For a definition of the meaning and valid values for C<MemLevel>
1148 refer to the I<zlib> documentation for I<deflateInit2>.
1149
1150 Defaults to MAX_MEM_LEVEL.
1151
1152 =item B<-Strategy>
1153
1154 Defines the strategy used to tune the compression. The valid values are
1155 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>. 
1156
1157 The default is Z_DEFAULT_STRATEGY.
1158
1159 =item B<-Dictionary>
1160
1161 When a dictionary is specified I<Compress::Zlib> will automatically
1162 call C<deflateSetDictionary> directly after calling C<deflateInit>. The
1163 Adler32 value for the dictionary can be obtained by calling the method 
1164 C<$d->dict_adler()>.
1165
1166 The default is no dictionary.
1167
1168 =item B<-Bufsize>
1169
1170 Sets the initial size for the deflation buffer. If the buffer has to be
1171 reallocated to increase the size, it will grow in increments of
1172 C<Bufsize>.
1173
1174 The default is 4096.
1175
1176 =back
1177
1178 Here is an example of using the C<deflateInit> optional parameter list
1179 to override the default buffer size and compression level. All other
1180 options will take their default values.
1181
1182     deflateInit( -Bufsize => 300, 
1183                  -Level => Z_BEST_SPEED  ) ;
1184
1185 =head2 B<($out, $status) = $d-E<gt>deflate($buffer)>
1186
1187 Deflates the contents of C<$buffer>. The buffer can either be a scalar
1188 or a scalar reference.  When finished, C<$buffer> will be
1189 completely processed (assuming there were no errors). If the deflation
1190 was successful it returns the deflated output, C<$out>, and a status
1191 value, C<$status>, of C<Z_OK>.
1192
1193 On error, C<$out> will be I<undef> and C<$status> will contain the
1194 I<zlib> error code.
1195
1196 In a scalar context C<deflate> will return C<$out> only.
1197
1198 As with the I<deflate> function in I<zlib>, it is not necessarily the
1199 case that any output will be produced by this method. So don't rely on
1200 the fact that C<$out> is empty for an error test.
1201
1202 =head2 B<($out, $status) = $d-E<gt>flush()>
1203 =head2 B<($out, $status) = $d-E<gt>flush($flush_type)>
1204
1205 Typically used to finish the deflation. Any pending output will be
1206 returned via C<$out>.
1207 C<$status> will have a value C<Z_OK> if successful.
1208
1209 In a scalar context C<flush> will return C<$out> only.
1210
1211 Note that flushing can seriously degrade the compression ratio, so it
1212 should only be used to terminate a decompression (using C<Z_FINISH>) or
1213 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
1214
1215 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
1216 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
1217 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
1218 C<flush_type> parameter if you fully understand the implications of
1219 what it does. See the C<zlib> documentation for details.
1220
1221 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
1222
1223 Change settings for the deflate stream C<$d>.
1224
1225 The list of the valid options is shown below. Options not specified
1226 will remain unchanged.
1227
1228 =over 5
1229
1230 =item B<-Level>
1231
1232 Defines the compression level. Valid values are 0 through 9,
1233 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1234 C<Z_DEFAULT_COMPRESSION>.
1235
1236 =item B<-Strategy>
1237
1238 Defines the strategy used to tune the compression. The valid values are
1239 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>. 
1240
1241 =back
1242
1243 =head2 B<$d-E<gt>dict_adler()>
1244
1245 Returns the adler32 value for the dictionary.
1246
1247 =head2 B<$d-E<gt>msg()>
1248
1249 Returns the last error message generated by zlib.
1250
1251 =head2 B<$d-E<gt>total_in()>
1252
1253 Returns the total number of bytes uncompressed bytes input to deflate.
1254
1255 =head2 B<$d-E<gt>total_out()>
1256
1257 Returns the total number of compressed bytes output from deflate.
1258
1259 =head2 Example
1260
1261 Here is a trivial example of using C<deflate>. It simply reads standard
1262 input, deflates it and writes it to standard output.
1263
1264     use strict ;
1265     use warnings ;
1266
1267     use Compress::Zlib ;
1268
1269     binmode STDIN;
1270     binmode STDOUT;
1271     my $x = deflateInit()
1272        or die "Cannot create a deflation stream\n" ;
1273
1274     my ($output, $status) ;
1275     while (<>)
1276     {
1277         ($output, $status) = $x->deflate($_) ;
1278     
1279         $status == Z_OK
1280             or die "deflation failed\n" ;
1281     
1282         print $output ;
1283     }
1284     
1285     ($output, $status) = $x->flush() ;
1286     
1287     $status == Z_OK
1288         or die "deflation failed\n" ;
1289     
1290     print $output ;
1291
1292 =head1 Inflate Interface
1293
1294 This section defines the interface available that allows in-memory
1295 uncompression using the I<deflate> interface provided by zlib.
1296
1297 Here is a definition of the interface:
1298
1299 =head2 B<($i, $status) = inflateInit()>
1300
1301 Initialises an inflation stream. 
1302
1303 In a list context it returns the inflation stream, C<$i>, and the
1304 I<zlib> status code in C<$status>. In a scalar context it returns the
1305 inflation stream only.
1306
1307 If successful, C<$i> will hold the inflation stream and C<$status> will
1308 be C<Z_OK>.
1309
1310 If not successful, C<$i> will be I<undef> and C<$status> will hold the
1311 I<zlib> error code.
1312
1313 The function optionally takes a number of named options specified as
1314 C<< -Name=>value >> pairs. This allows individual options to be
1315 tailored without having to specify them all in the parameter list.
1316  
1317 For backward compatibility, it is also possible to pass the parameters
1318 as a reference to a hash containing the name=>value pairs.
1319  
1320 The function takes one optional parameter, a reference to a hash.  The
1321 contents of the hash allow the deflation interface to be tailored.
1322  
1323 Here is a list of the valid options:
1324
1325 =over 5
1326
1327 =item B<-WindowBits>
1328
1329 To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive number.
1330
1331 To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
1332
1333 For a full definition of the meaning and valid values for C<WindowBits> refer
1334 to the I<zlib> documentation for I<inflateInit2>.
1335
1336 Defaults to MAX_WBITS.
1337
1338 =item B<-Bufsize>
1339
1340 Sets the initial size for the inflation buffer. If the buffer has to be
1341 reallocated to increase the size, it will grow in increments of
1342 C<Bufsize>. 
1343
1344 Default is 4096.
1345
1346 =item B<-Dictionary>
1347
1348 The default is no dictionary.
1349
1350 =back
1351
1352 Here is an example of using the C<inflateInit> optional parameter to
1353 override the default buffer size.
1354
1355     inflateInit( -Bufsize => 300 ) ;
1356
1357 =head2 B<($out, $status) = $i-E<gt>inflate($buffer)>
1358
1359 Inflates the complete contents of C<$buffer>. The buffer can either be
1360 a scalar or a scalar reference.
1361
1362 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
1363 compressed data has been successfully reached. 
1364 If not successful, C<$out> will be I<undef> and C<$status> will hold
1365 the I<zlib> error code.
1366
1367 The C<$buffer> parameter is modified by C<inflate>. On completion it
1368 will contain what remains of the input buffer after inflation. This
1369 means that C<$buffer> will be an empty string when the return status is
1370 C<Z_OK>. When the return status is C<Z_STREAM_END> the C<$buffer>
1371 parameter will contains what (if anything) was stored in the input
1372 buffer after the deflated data stream.
1373
1374 This feature is useful when processing a file format that encapsulates
1375 a  compressed data stream (e.g. gzip, zip).
1376
1377 =head2 B<$status = $i-E<gt>inflateSync($buffer)>
1378
1379 Scans C<$buffer> until it reaches either a I<full flush point> or the
1380 end of the buffer.
1381
1382 If a I<full flush point> is found, C<Z_OK> is returned and C<$buffer>
1383 will be have all data up to the flush point removed. This can then be
1384 passed to the C<deflate> method.
1385
1386 Any other return code means that a flush point was not found. If more
1387 data is available, C<inflateSync> can be called repeatedly with more
1388 compressed data until the flush point is found.
1389
1390 =head2 B<$i-E<gt>dict_adler()>
1391
1392 Returns the adler32 value for the dictionary.
1393
1394 =head2 B<$i-E<gt>msg()>
1395
1396 Returns the last error message generated by zlib.
1397
1398 =head2 B<$i-E<gt>total_in()>
1399
1400 Returns the total number of bytes compressed bytes input to inflate.
1401
1402 =head2 B<$i-E<gt>total_out()>
1403
1404 Returns the total number of uncompressed bytes output from inflate.
1405
1406 =head2 Example
1407
1408 Here is an example of using C<inflate>.
1409
1410     use strict ;
1411     use warnings ;
1412     
1413     use Compress::Zlib ;
1414     
1415     my $x = inflateInit()
1416        or die "Cannot create a inflation stream\n" ;
1417     
1418     my $input = '' ;
1419     binmode STDIN;
1420     binmode STDOUT;
1421     
1422     my ($output, $status) ;
1423     while (read(STDIN, $input, 4096))
1424     {
1425         ($output, $status) = $x->inflate(\$input) ;
1426     
1427         print $output 
1428             if $status == Z_OK or $status == Z_STREAM_END ;
1429     
1430         last if $status != Z_OK ;
1431     }
1432     
1433     die "inflation failed\n"
1434         unless $status == Z_STREAM_END ;
1435
1436 =head1 CHECKSUM FUNCTIONS
1437
1438 Two functions are provided by I<zlib> to calculate checksums. For the
1439 Perl interface, the order of the two parameters in both functions has
1440 been reversed. This allows both running checksums and one off
1441 calculations to be done.
1442
1443     $crc = adler32($buffer [,$crc]) ;
1444     $crc = crc32($buffer [,$crc]) ;
1445
1446 The buffer parameters can either be a scalar or a scalar reference.
1447
1448 If the $crc parameters is C<undef>, the crc value will be reset.
1449
1450 If you have built this module with zlib 1.2.3 or better, two more
1451 CRC-related functions are available.
1452
1453     $crc = crc32_combine($crc1, $crc2, $len2);
1454     $adler = adler32_combine($adler1, $adler2, $len2);
1455
1456 These functions allow checksums to be merged.
1457 Refer to the I<zlib> documentation for more details.
1458
1459 =head1 Misc
1460
1461 =head2 my $version = Compress::Zlib::zlib_version();
1462
1463 Returns the version of the zlib library.
1464
1465 =head1 CONSTANTS
1466
1467 All the I<zlib> constants are automatically imported when you make use
1468 of I<Compress::Zlib>.
1469
1470 =head1 SEE ALSO
1471
1472 L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1473
1474 L<IO::Compress::FAQ|IO::Compress::FAQ>
1475
1476 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1477 L<Archive::Tar|Archive::Tar>,
1478 L<IO::Zlib|IO::Zlib>
1479
1480 For RFC 1950, 1951 and 1952 see 
1481 F<http://www.faqs.org/rfcs/rfc1950.html>,
1482 F<http://www.faqs.org/rfcs/rfc1951.html> and
1483 F<http://www.faqs.org/rfcs/rfc1952.html>
1484
1485 The I<zlib> compression library was written by Jean-loup Gailly
1486 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1487
1488 The primary site for the I<zlib> compression library is
1489 F<http://www.zlib.org>.
1490
1491 The primary site for gzip is F<http://www.gzip.org>.
1492
1493 =head1 AUTHOR
1494
1495 This module was written by Paul Marquess, F<pmqs@cpan.org>. 
1496
1497 =head1 MODIFICATION HISTORY
1498
1499 See the Changes file.
1500
1501 =head1 COPYRIGHT AND LICENSE
1502
1503 Copyright (c) 1995-2014 Paul Marquess. All rights reserved.
1504
1505 This program is free software; you can redistribute it and/or
1506 modify it under the same terms as Perl itself.
1507