← Index
NYTProf Performance Profile   « block view • line view • sub view »
For ddd2.pl
  Run on Tue May 25 16:52:24 2010
Reported on Tue May 25 16:57:04 2010

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