Profile: /opt/wise/lib/perl5/5.10.0/x86_64-linux-thread-multi/Compress/Zlib.pm

File	/opt/wise/lib/perl5/5.10.0/x86_64-linux-thread-multi/Compress/Zlib.pm
Statements Executed	69
Total Time	0.004436 seconds

Subroutines — ordered by exclusive time
Calls	P	F	Exclusive Time	Inclusive Time	Subroutine
0	0	0	0	0	Compress::Zlib::	AUTOLOAD
0	0	0	0	0	Compress::Zlib::	BEGIN
0	0	0	0	0	Compress::Zlib::	__ANON__[:50]
0	0	0	0	0	Compress::Zlib::	_removeGzipHeader
0	0	0	0	0	Compress::Zlib::	_save_gzerr
0	0	0	0	0	Compress::Zlib::	_set_gzerr
0	0	0	0	0	Compress::Zlib::	compress
0	0	0	0	0	Compress::Zlib::	deflateInit
0	0	0	0	0	Compress::Zlib::gzFile::	gzclose
0	0	0	0	0	Compress::Zlib::gzFile::	gzeof
0	0	0	0	0	Compress::Zlib::gzFile::	gzerror
0	0	0	0	0	Compress::Zlib::gzFile::	gzflush
0	0	0	0	0	Compress::Zlib::gzFile::	gzread
0	0	0	0	0	Compress::Zlib::gzFile::	gzreadline
0	0	0	0	0	Compress::Zlib::gzFile::	gzseek
0	0	0	0	0	Compress::Zlib::gzFile::	gzsetparams
0	0	0	0	0	Compress::Zlib::gzFile::	gztell
0	0	0	0	0	Compress::Zlib::gzFile::	gzwrite
0	0	0	0	0	Compress::Zlib::	gzopen
0	0	0	0	0	Compress::Zlib::	inflateInit
0	0	0	0	0	Compress::Zlib::	memGunzip
0	0	0	0	0	Compress::Zlib::	memGzip
0	0	0	0	0	Compress::Zlib::	uncompress
0	0	0	0	0	Zlib::OldDeflate::	deflate
0	0	0	0	0	Zlib::OldDeflate::	flush
0	0	0	0	0	Zlib::OldInflate::	inflate

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