This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Silence gcc complaints about comments in config.h
[perl5.git] / ext / Compress / Zlib / Zlib.pm
CommitLineData
f4c6fd49
RGS
1
2package Compress::Zlib;
3
4require 5.004 ;
5require Exporter;
f4c6fd49
RGS
6use AutoLoader;
7use Carp ;
8use IO::Handle ;
642e522c
RGS
9use Scalar::Util qw(dualvar);
10
11use Compress::Zlib::Common;
12use Compress::Zlib::ParseParameters;
f4c6fd49
RGS
13
14use strict ;
8aa25532 15use warnings ;
642e522c
RGS
16use bytes ;
17our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
f4c6fd49 18
68a72f3d 19$VERSION = '2.000_06';
642e522c
RGS
20$XS_VERSION = $VERSION;
21$VERSION = eval $VERSION;
f4c6fd49 22
06edba15 23@ISA = qw(Exporter);
f4c6fd49
RGS
24# Items to export into callers namespace by default. Note: do not export
25# names by default without a very good reason. Use EXPORT_OK instead.
26# Do not simply export all your public functions/methods/constants.
27@EXPORT = qw(
642e522c 28 deflateInit inflateInit
f4c6fd49 29
642e522c 30 compress uncompress
f4c6fd49 31
642e522c 32 gzopen $gzerrno
f4c6fd49 33
642e522c 34 adler32 crc32
f4c6fd49 35
642e522c
RGS
36 ZLIB_VERSION
37 ZLIB_VERNUM
f4c6fd49 38
642e522c
RGS
39 DEF_WBITS
40 OS_CODE
f4c6fd49
RGS
41
42 MAX_MEM_LEVEL
642e522c
RGS
43 MAX_WBITS
44
45 Z_ASCII
46 Z_BEST_COMPRESSION
47 Z_BEST_SPEED
48 Z_BINARY
49 Z_BLOCK
50 Z_BUF_ERROR
51 Z_DATA_ERROR
52 Z_DEFAULT_COMPRESSION
53 Z_DEFAULT_STRATEGY
f4c6fd49 54 Z_DEFLATED
642e522c
RGS
55 Z_ERRNO
56 Z_FILTERED
57 Z_FIXED
58 Z_FINISH
59 Z_FULL_FLUSH
60 Z_HUFFMAN_ONLY
61 Z_MEM_ERROR
62 Z_NEED_DICT
63 Z_NO_COMPRESSION
64 Z_NO_FLUSH
65 Z_NULL
66 Z_OK
67 Z_PARTIAL_FLUSH
68 Z_RLE
69 Z_STREAM_END
70 Z_STREAM_ERROR
71 Z_SYNC_FLUSH
72 Z_UNKNOWN
73 Z_VERSION_ERROR
f4c6fd49
RGS
74);
75
f4c6fd49
RGS
76sub AUTOLOAD {
77 my($constname);
78 ($constname = $AUTOLOAD) =~ s/.*:://;
79 my ($error, $val) = constant($constname);
80 Carp::croak $error if $error;
81 no strict 'refs';
82 *{$AUTOLOAD} = sub { $val };
83 goto &{$AUTOLOAD};
84}
85
642e522c
RGS
86use constant FLAG_APPEND => 1 ;
87use constant FLAG_CRC => 2 ;
88use constant FLAG_ADLER => 4 ;
89use constant FLAG_CONSUME_INPUT => 8 ;
90
06edba15
PM
91eval {
92 require XSLoader;
642e522c
RGS
93 XSLoader::load('Compress::Zlib', $XS_VERSION);
94 1;
95}
96or do {
06edba15
PM
97 require DynaLoader;
98 local @ISA = qw(DynaLoader);
642e522c
RGS
99 bootstrap Compress::Zlib $XS_VERSION ;
100};
101
f4c6fd49
RGS
102# Preloaded methods go here.
103
642e522c
RGS
104require IO::Compress::Gzip;
105require IO::Uncompress::Gunzip;
106
107our (@my_z_errmsg);
108
109@my_z_errmsg = (
110 "need dictionary", # Z_NEED_DICT 2
111 "stream end", # Z_STREAM_END 1
112 "", # Z_OK 0
113 "file error", # Z_ERRNO (-1)
114 "stream error", # Z_STREAM_ERROR (-2)
115 "data error", # Z_DATA_ERROR (-3)
116 "insufficient memory", # Z_MEM_ERROR (-4)
117 "buffer error", # Z_BUF_ERROR (-5)
118 "incompatible version",# Z_VERSION_ERROR(-6)
119 );
120
121
122sub _set_gzerr
f4c6fd49 123{
642e522c 124 my $value = shift ;
f4c6fd49 125
642e522c
RGS
126 if ($value == 0) {
127 $Compress::Zlib::gzerrno = 0 ;
128 }
129 elsif ($value == Z_ERRNO() || $value > 2) {
130 $Compress::Zlib::gzerrno = $! ;
131 }
132 else {
133 $Compress::Zlib::gzerrno = dualvar($value+0, $my_z_errmsg[2 - $value]);
134 }
f4c6fd49 135
642e522c 136 return $value ;
f4c6fd49
RGS
137}
138
642e522c 139sub _save_gzerr
f4c6fd49 140{
642e522c
RGS
141 my $gz = shift ;
142 my $test_eof = shift ;
f4c6fd49 143
642e522c
RGS
144 my $value = $gz->errorNo() || 0 ;
145
146 if ($test_eof) {
147 #my $gz = $self->[0] ;
148 # gzread uses Z_STREAM_END to denote a successful end
149 $value = Z_STREAM_END() if $gz->eof() && $value == 0 ;
150 }
151
152 _set_gzerr($value) ;
f4c6fd49
RGS
153}
154
155sub gzopen($$)
156{
157 my ($file, $mode) = @_ ;
642e522c
RGS
158
159 my $gz ;
160 my %defOpts = (Level => Z_DEFAULT_COMPRESSION(),
161 Strategy => Z_DEFAULT_STRATEGY(),
162 );
163
164 my $writing ;
165 $writing = ! ($mode =~ /r/i) ;
166 $writing = ($mode =~ /[wa]/i) ;
167
168 $defOpts{Level} = $1 if $mode =~ /(\d)/;
169 $defOpts{Strategy} = Z_FILTERED() if $mode =~ /f/i;
170 $defOpts{Strategy} = Z_HUFFMAN_ONLY() if $mode =~ /h/i;
171
172 my $infDef = $writing ? 'deflate' : 'inflate';
173 my @params = () ;
174
175 croak "gzopen: file parameter is not a filehandle or filename"
176 unless isaFilehandle $file || isaFilename $file ;
177
178 return undef unless $mode =~ /[rwa]/i ;
179
180 _set_gzerr(0) ;
181
182 if ($writing) {
183 $gz = new IO::Compress::Gzip($file, Minimal => 1, AutoClose => 1, %defOpts)
184 or $Compress::Zlib::gzerrno = $IO::Compress::Gzip::GzipError;
f4c6fd49
RGS
185 }
186 else {
642e522c
RGS
187 $gz = new IO::Uncompress::Gunzip($file, Append => 0, AutoClose => 1, Strict => 0)
188 or $Compress::Zlib::gzerrno = $IO::Uncompress::Gunzip::GunzipError;
f4c6fd49 189 }
642e522c
RGS
190
191 return undef
192 if ! defined $gz ;
193
194 bless [$gz, $infDef], 'Compress::Zlib::gzFile';
195}
196
197sub Compress::Zlib::gzFile::gzread
198{
199 my $self = shift ;
200
201 return _set_gzerr(Z_STREAM_ERROR())
202 if $self->[1] ne 'inflate';
203
204 return 0 if $self->gzeof();
205
206 my $gz = $self->[0] ;
207 my $status = $gz->read($_[0], defined $_[1] ? $_[1] : 4096) ;
208 $_[0] = "" if ! defined $_[0] ;
209 _save_gzerr($gz, 1);
210 return $status ;
f4c6fd49
RGS
211}
212
642e522c 213sub Compress::Zlib::gzFile::gzreadline
f4c6fd49 214{
642e522c 215 my $self = shift ;
f4c6fd49 216
642e522c
RGS
217 my $gz = $self->[0] ;
218 $_[0] = $gz->getline() ;
219 _save_gzerr($gz, 1);
220 return defined $_[0] ? length $_[0] : 0 ;
221}
f4c6fd49 222
642e522c
RGS
223sub Compress::Zlib::gzFile::gzwrite
224{
225 my $self = shift ;
226 my $gz = $self->[0] ;
f4c6fd49 227
642e522c
RGS
228 return _set_gzerr(Z_STREAM_ERROR())
229 if $self->[1] ne 'deflate';
f4c6fd49 230
642e522c
RGS
231 my $status = $gz->write($_[0]) ;
232 _save_gzerr($gz);
233 return $status ;
234}
f4c6fd49 235
642e522c
RGS
236sub Compress::Zlib::gzFile::gztell
237{
238 my $self = shift ;
239 my $gz = $self->[0] ;
240 my $status = $gz->tell() ;
241 _save_gzerr($gz);
242 return $status ;
243}
244
245sub Compress::Zlib::gzFile::gzseek
246{
247 my $self = shift ;
248 my $offset = shift ;
249 my $whence = shift ;
250
251 my $gz = $self->[0] ;
252 my $status ;
253 eval { $status = $gz->seek($offset, $whence) ; };
254 if ($@)
255 {
256 my $error = $@;
257 $error =~ s/^.*: /gzseek: /;
258 $error =~ s/ at .* line \d+\s*$//;
259 croak $error;
f4c6fd49 260 }
642e522c
RGS
261 _save_gzerr($gz);
262 return $status ;
263}
264
265sub Compress::Zlib::gzFile::gzflush
266{
267 my $self = shift ;
268 my $f = shift ;
f4c6fd49 269
642e522c
RGS
270 my $gz = $self->[0] ;
271 my $status = $gz->flush($f) ;
272 _save_gzerr($gz);
273 return $status ;
f4c6fd49
RGS
274}
275
642e522c
RGS
276sub Compress::Zlib::gzFile::gzclose
277{
278 my $self = shift ;
279 my $gz = $self->[0] ;
f4c6fd49 280
642e522c
RGS
281 my $status = $gz->close() ;
282 _save_gzerr($gz);
283 return ! $status ;
284}
f4c6fd49 285
642e522c
RGS
286sub Compress::Zlib::gzFile::gzeof
287{
288 my $self = shift ;
289 my $gz = $self->[0] ;
290
291 return 0
292 if $self->[1] ne 'inflate';
293
294 my $status = $gz->eof() ;
295 _save_gzerr($gz);
296 return $status ;
297}
298
299sub Compress::Zlib::gzFile::gzsetparams
300{
301 my $self = shift ;
302 croak "Usage: Compress::Zlib::gzFile::gzsetparams(file, level, strategy)"
303 unless @_ eq 2 ;
304
305 my $gz = $self->[0] ;
306 my $level = shift ;
307 my $strategy = shift;
308
309 return _set_gzerr(Z_STREAM_ERROR())
310 if $self->[1] ne 'deflate';
311
312 my $status = *$gz->{Deflate}->deflateParams(-Level => $level,
313 -Strategy => $strategy);
314 _save_gzerr($gz);
315 return $status ;
316}
317
318sub Compress::Zlib::gzFile::gzerror
f4c6fd49 319{
642e522c
RGS
320 my $self = shift ;
321 my $gz = $self->[0] ;
322
323 return $Compress::Zlib::gzerrno ;
f4c6fd49
RGS
324}
325
642e522c
RGS
326sub Compress::Zlib::Deflate::new
327{
328 my $pkg = shift ;
329 my ($got) = ParseParameters(0,
330 {
331 'AppendOutput' => [Parse_boolean, 0],
332 'CRC32' => [Parse_boolean, 0],
333 'ADLER32' => [Parse_boolean, 0],
334 'Bufsize' => [Parse_unsigned, 4096],
335
336 'Level' => [Parse_signed, Z_DEFAULT_COMPRESSION()],
337 'Method' => [Parse_unsigned, Z_DEFLATED()],
338 'WindowBits' => [Parse_signed, MAX_WBITS()],
339 'MemLevel' => [Parse_unsigned, MAX_MEM_LEVEL()],
340 'Strategy' => [Parse_unsigned, Z_DEFAULT_STRATEGY()],
341 'Dictionary' => [Parse_any, ""],
342 }, @_) ;
343
344
345 croak "Compress::Zlib::Deflate::new: Bufsize must be >= 1, you specified " .
346 $got->value('Bufsize')
347 unless $got->value('Bufsize') >= 1;
348
349 my $flags = 0 ;
350 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
351 $flags |= FLAG_CRC if $got->value('CRC32') ;
352 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
353
354 _deflateInit($flags,
355 $got->value('Level'),
356 $got->value('Method'),
357 $got->value('WindowBits'),
358 $got->value('MemLevel'),
359 $got->value('Strategy'),
360 $got->value('Bufsize'),
361 $got->value('Dictionary')) ;
362
363}
364
365sub Compress::Zlib::Inflate::new
366{
367 my $pkg = shift ;
368 my ($got) = ParseParameters(0,
369 {
370 'AppendOutput' => [Parse_boolean, 0],
371 'CRC32' => [Parse_boolean, 0],
372 'ADLER32' => [Parse_boolean, 0],
373 'ConsumeInput' => [Parse_boolean, 1],
374 'Bufsize' => [Parse_unsigned, 4096],
375
376 'WindowBits' => [Parse_signed, MAX_WBITS()],
377 'Dictionary' => [Parse_any, ""],
378 }, @_) ;
379
380
381 croak "Compress::Zlib::Inflate::new: Bufsize must be >= 1, you specified " .
382 $got->value('Bufsize')
383 unless $got->value('Bufsize') >= 1;
384
385 my $flags = 0 ;
386 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
387 $flags |= FLAG_CRC if $got->value('CRC32') ;
388 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
389 $flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
390
391 _inflateInit($flags, $got->value('WindowBits'), $got->value('Bufsize'),
392 $got->value('Dictionary')) ;
393}
394
395sub Compress::Zlib::InflateScan::new
396{
397 my $pkg = shift ;
398 my ($got) = ParseParameters(0,
399 {
400 'CRC32' => [Parse_boolean, 0],
401 'ADLER32' => [Parse_boolean, 0],
402 'Bufsize' => [Parse_unsigned, 4096],
403
404 'WindowBits' => [Parse_signed, -MAX_WBITS()],
405 'Dictionary' => [Parse_any, ""],
406 }, @_) ;
407
408
409 croak "Compress::Zlib::InflateScan::new: Bufsize must be >= 1, you specified " .
410 $got->value('Bufsize')
411 unless $got->value('Bufsize') >= 1;
412
413 my $flags = 0 ;
414 #$flags |= FLAG_APPEND if $got->value('AppendOutput') ;
415 $flags |= FLAG_CRC if $got->value('CRC32') ;
416 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
417 #$flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
418
419 _inflateScanInit($flags, $got->value('WindowBits'), $got->value('Bufsize'),
420 '') ;
421}
422
423sub Compress::Zlib::inflateScanStream::createDeflateStream
f4c6fd49 424{
642e522c
RGS
425 my $pkg = shift ;
426 my ($got) = ParseParameters(0,
427 {
428 'AppendOutput' => [Parse_boolean, 0],
429 'CRC32' => [Parse_boolean, 0],
430 'ADLER32' => [Parse_boolean, 0],
431 'Bufsize' => [Parse_unsigned, 4096],
f4c6fd49 432
642e522c
RGS
433 'Level' => [Parse_signed, Z_DEFAULT_COMPRESSION()],
434 'Method' => [Parse_unsigned, Z_DEFLATED()],
435 'WindowBits' => [Parse_signed, - MAX_WBITS()],
436 'MemLevel' => [Parse_unsigned, MAX_MEM_LEVEL()],
437 'Strategy' => [Parse_unsigned, Z_DEFAULT_STRATEGY()],
438 }, @_) ;
439
440 croak "Compress::Zlib::InflateScan::createDeflateStream: Bufsize must be >= 1, you specified " .
441 $got->value('Bufsize')
442 unless $got->value('Bufsize') >= 1;
443
444 my $flags = 0 ;
445 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
446 $flags |= FLAG_CRC if $got->value('CRC32') ;
447 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
448
449 $pkg->_createDeflateStream($flags,
450 $got->value('Level'),
451 $got->value('Method'),
452 $got->value('WindowBits'),
453 $got->value('MemLevel'),
454 $got->value('Strategy'),
455 $got->value('Bufsize'),
456 ) ;
457
f4c6fd49
RGS
458}
459
642e522c 460
f4c6fd49
RGS
461sub Compress::Zlib::deflateStream::deflateParams
462{
463 my $self = shift ;
642e522c
RGS
464 my ($got) = ParseParameters(0, {
465 'Level' => [Parse_signed, undef],
466 'Strategy' => [Parse_unsigned, undef],
467 'Bufsize' => [Parse_unsigned, undef],
468 },
469 @_) ;
470
471 croak "Compress::Zlib::deflateParams needs Level and/or Strategy"
472 unless $got->parsed('Level') + $got->parsed('Strategy') +
473 $got->parsed('Bufsize');
474
475 croak "Compress::Zlib::Inflate::deflateParams: Bufsize must be >= 1, you specified " .
476 $got->value('Bufsize')
477 if $got->parsed('Bufsize') && $got->value('Bufsize') <= 1;
f4c6fd49
RGS
478
479 my $flags = 0;
642e522c
RGS
480 $flags |= 1 if $got->parsed('Level') ;
481 $flags |= 2 if $got->parsed('Strategy') ;
482 $flags |= 4 if $got->parsed('Bufsize') ;
483
484 $self->_deflateParams($flags, $got->value('Level'),
485 $got->value('Strategy'), $got->value('Bufsize'));
486
f4c6fd49
RGS
487}
488
489sub compress($;$)
490{
642e522c 491 my ($x, $output, $err, $in) =('', '', '', '') ;
f4c6fd49
RGS
492
493 if (ref $_[0] ) {
494 $in = $_[0] ;
642e522c 495 croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
f4c6fd49
RGS
496 }
497 else {
498 $in = \$_[0] ;
499 }
500
501 my $level = (@_ == 2 ? $_[1] : Z_DEFAULT_COMPRESSION() );
502
642e522c
RGS
503 $x = new Compress::Zlib::Deflate -AppendOutput => 1, -Level => $level
504 or return undef ;
f4c6fd49 505
642e522c
RGS
506 $err = $x->deflate($in, $output) ;
507 return undef unless $err == Z_OK() ;
f4c6fd49 508
642e522c
RGS
509 $err = $x->flush($output) ;
510 return undef unless $err == Z_OK() ;
f4c6fd49 511
642e522c 512 return $output ;
f4c6fd49 513
f4c6fd49
RGS
514}
515
f4c6fd49
RGS
516sub uncompress($)
517{
642e522c 518 my ($x, $output, $err, $in) =('', '', '', '') ;
f4c6fd49
RGS
519
520 if (ref $_[0] ) {
521 $in = $_[0] ;
642e522c 522 croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
f4c6fd49
RGS
523 }
524 else {
525 $in = \$_[0] ;
526 }
527
642e522c 528 $x = new Compress::Zlib::Inflate -ConsumeInput => 0 or return undef ;
f4c6fd49 529
642e522c
RGS
530 $err = $x->inflate($in, $output) ;
531 return undef unless $err == Z_STREAM_END() ;
f4c6fd49 532
642e522c
RGS
533 return $output ;
534}
535
536
537### This stuff is for backward compat. with Compress::Zlib 1.x
538
f4c6fd49 539
642e522c
RGS
540sub deflateInit(@)
541{
542 my ($got) = ParseParameters(0,
543 {
544 'Bufsize' => [Parse_unsigned, 4096],
545 'Level' => [Parse_signed, Z_DEFAULT_COMPRESSION()],
546 'Method' => [Parse_unsigned, Z_DEFLATED()],
547 'WindowBits' => [Parse_signed, MAX_WBITS()],
548 'MemLevel' => [Parse_unsigned, MAX_MEM_LEVEL()],
549 'Strategy' => [Parse_unsigned, Z_DEFAULT_STRATEGY()],
550 'Dictionary' => [Parse_any, ""],
551 }, @_ ) ;
552
553 croak "Compress::Zlib::deflateInit: Bufsize must be >= 1, you specified " .
554 $got->value('Bufsize')
555 unless $got->value('Bufsize') >= 1;
556
557 my (%obj) = () ;
558
559 my $status = 0 ;
560 ($obj{def}, $status) =
561 _deflateInit(0,
562 $got->value('Level'),
563 $got->value('Method'),
564 $got->value('WindowBits'),
565 $got->value('MemLevel'),
566 $got->value('Strategy'),
567 $got->value('Bufsize'),
568 $got->value('Dictionary')) ;
569
570 my $x = ($status == Z_OK() ? bless \%obj, "Zlib::OldDeflate" : undef) ;
571 return wantarray ? ($x, $status) : $x ;
f4c6fd49 572}
642e522c
RGS
573
574sub inflateInit(@)
575{
576 my ($got) = ParseParameters(0,
577 {
578 'Bufsize' => [Parse_unsigned, 4096],
579 'WindowBits' => [Parse_signed, MAX_WBITS()],
580 'Dictionary' => [Parse_any, ""],
581 }, @_) ;
f4c6fd49
RGS
582
583
642e522c
RGS
584 croak "Compress::Zlib::inflateInit: Bufsize must be >= 1, you specified " .
585 $got->value('Bufsize')
586 unless $got->value('Bufsize') >= 1;
f4c6fd49 587
642e522c
RGS
588 my $status = 0 ;
589 my (%obj) = () ;
590 ($obj{def}, $status) = _inflateInit(FLAG_CONSUME_INPUT,
591 $got->value('WindowBits'),
592 $got->value('Bufsize'),
593 $got->value('Dictionary')) ;
594
595 my $x = ($status == Z_OK() ? bless \%obj, "Zlib::OldInflate" : undef) ;
596
597 wantarray ? ($x, $status) : $x ;
598}
599
600package Zlib::OldDeflate ;
601
602sub deflate
603{
604 my $self = shift ;
605 my $output ;
606 #my (@rest) = @_ ;
607
608 my $status = $self->{def}->deflate($_[0], $output) ;
609
610 wantarray ? ($output, $status) : $output ;
611}
612
613sub flush
614{
615 my $self = shift ;
616 my $output ;
617 my $flag = shift || Compress::Zlib::Z_FINISH();
618 my $status = $self->{def}->flush($output, $flag) ;
619
620 wantarray ? ($output, $status) : $output ;
621}
622
623sub deflateParams
624{
625 my $self = shift ;
626 $self->{def}->deflateParams(@_) ;
627}
628
629sub msg
630{
631 my $self = shift ;
632 $self->{def}->msg() ;
633}
634
635sub total_in
636{
637 my $self = shift ;
638 $self->{def}->total_in() ;
639}
640
641sub total_out
642{
643 my $self = shift ;
644 $self->{def}->total_out() ;
645}
646
647sub dict_adler
648{
649 my $self = shift ;
650 $self->{def}->dict_adler() ;
651}
652
653sub get_Level
654{
655 my $self = shift ;
656 $self->{def}->get_Level() ;
657}
658
659sub get_Strategy
660{
661 my $self = shift ;
662 $self->{def}->get_Strategy() ;
663}
664
665#sub DispStream
666#{
667# my $self = shift ;
668# $self->{def}->DispStream($_[0]) ;
669#}
670
671package Zlib::OldInflate ;
672
673sub inflate
674{
675 my $self = shift ;
676 my $output ;
677 my $status = $self->{def}->inflate($_[0], $output) ;
678 wantarray ? ($output, $status) : $output ;
679}
680
681sub inflateSync
682{
683 my $self = shift ;
684 $self->{def}->inflateSync($_[0]) ;
685}
686
687sub msg
688{
689 my $self = shift ;
690 $self->{def}->msg() ;
691}
692
693sub total_in
694{
695 my $self = shift ;
696 $self->{def}->total_in() ;
697}
698
699sub total_out
700{
701 my $self = shift ;
702 $self->{def}->total_out() ;
703}
704
705sub dict_adler
706{
707 my $self = shift ;
708 $self->{def}->dict_adler() ;
709}
710
711#sub DispStream
712#{
713# my $self = shift ;
714# $self->{def}->DispStream($_[0]) ;
715#}
716
717package Compress::Zlib ;
718
719use Compress::Gzip::Constants;
f4c6fd49 720
f4c6fd49
RGS
721sub memGzip($)
722{
642e522c
RGS
723 my $x = new Compress::Zlib::Deflate(
724 -AppendOutput => 1,
725 -CRC32 => 1,
726 -ADLER32 => 0,
f4c6fd49 727 -Level => Z_BEST_COMPRESSION(),
642e522c 728 -WindowBits => - MAX_WBITS(),
f4c6fd49
RGS
729 )
730 or return undef ;
731
732 # write a minimal gzip header
642e522c 733 my $output = GZIP_MINIMUM_HEADER ;
f4c6fd49
RGS
734
735 # if the deflation buffer isn't a reference, make it one
736 my $string = (ref $_[0] ? $_[0] : \$_[0]) ;
737
642e522c 738 my $status = $x->deflate($string, \$output) ;
f4c6fd49
RGS
739 $status == Z_OK()
740 or return undef ;
741
642e522c 742 $status = $x->flush(\$output) ;
f4c6fd49
RGS
743 $status == Z_OK()
744 or return undef ;
745
642e522c 746 return $output . pack("V V", $x->crc32(), $x->total_in()) ;
f4c6fd49 747
f4c6fd49
RGS
748}
749
642e522c 750
f4c6fd49
RGS
751sub _removeGzipHeader($)
752{
753 my $string = shift ;
754
755 return Z_DATA_ERROR()
642e522c 756 if length($$string) < GZIP_MIN_HEADER_SIZE ;
f4c6fd49
RGS
757
758 my ($magic1, $magic2, $method, $flags, $time, $xflags, $oscode) =
759 unpack ('CCCCVCC', $$string);
760
761 return Z_DATA_ERROR()
642e522c
RGS
762 unless $magic1 == GZIP_ID1 and $magic2 == GZIP_ID2 and
763 $method == Z_DEFLATED() and !($flags & GZIP_FLG_RESERVED) ;
764 substr($$string, 0, GZIP_MIN_HEADER_SIZE) = '' ;
f4c6fd49
RGS
765
766 # skip extra field
642e522c 767 if ($flags & GZIP_FLG_FEXTRA)
f4c6fd49
RGS
768 {
769 return Z_DATA_ERROR()
642e522c 770 if length($$string) < GZIP_FEXTRA_HEADER_SIZE ;
f4c6fd49
RGS
771
772 my ($extra_len) = unpack ('v', $$string);
642e522c 773 $extra_len += GZIP_FEXTRA_HEADER_SIZE;
f4c6fd49
RGS
774 return Z_DATA_ERROR()
775 if length($$string) < $extra_len ;
776
777 substr($$string, 0, $extra_len) = '';
778 }
779
780 # skip orig name
642e522c 781 if ($flags & GZIP_FLG_FNAME)
f4c6fd49 782 {
642e522c 783 my $name_end = index ($$string, GZIP_NULL_BYTE);
f4c6fd49
RGS
784 return Z_DATA_ERROR()
785 if $name_end == -1 ;
786 substr($$string, 0, $name_end + 1) = '';
787 }
788
789 # skip comment
642e522c 790 if ($flags & GZIP_FLG_FCOMMENT)
f4c6fd49 791 {
642e522c 792 my $comment_end = index ($$string, GZIP_NULL_BYTE);
f4c6fd49
RGS
793 return Z_DATA_ERROR()
794 if $comment_end == -1 ;
795 substr($$string, 0, $comment_end + 1) = '';
796 }
797
798 # skip header crc
642e522c 799 if ($flags & GZIP_FLG_FHCRC)
f4c6fd49
RGS
800 {
801 return Z_DATA_ERROR()
642e522c
RGS
802 if length ($$string) < GZIP_FHCRC_SIZE ;
803 substr($$string, 0, GZIP_FHCRC_SIZE) = '';
f4c6fd49
RGS
804 }
805
806 return Z_OK();
807}
808
809
810sub memGunzip($)
811{
812 # if the buffer isn't a reference, make it one
813 my $string = (ref $_[0] ? $_[0] : \$_[0]);
814
815 _removeGzipHeader($string) == Z_OK()
816 or return undef;
817
818 my $bufsize = length $$string > 4096 ? length $$string : 4096 ;
642e522c
RGS
819 my $x = new Compress::Zlib::Inflate({-WindowBits => - MAX_WBITS(),
820 -Bufsize => $bufsize})
821
f4c6fd49 822 or return undef;
642e522c
RGS
823
824 my $output = "" ;
825 my $status = $x->inflate($string, $output);
f4c6fd49
RGS
826 return undef
827 unless $status == Z_STREAM_END();
828
829 if (length $$string >= 8)
830 {
831 my ($crc, $len) = unpack ("VV", substr($$string, 0, 8));
832 substr($$string, 0, 8) = '';
833 return undef
834 unless $len == length($output) and
835 $crc == crc32($output);
836 }
837 else
838 {
839 $$string = '';
840 }
f4c6fd49
RGS
841 return $output;
842}
843
844# Autoload methods go after __END__, and are processed by the autosplit program.
845
8461;
847__END__
848
f4c6fd49
RGS
849
850=head1 NAME
851
852Compress::Zlib - Interface to zlib compression library
853
854=head1 SYNOPSIS
855
642e522c 856 use Compress::Zlib 2 ;
f4c6fd49 857
642e522c
RGS
858 ($d, $status) = new Compress::Zlib::Deflate( [OPT] ) ;
859 $status = $d->deflate($input, $output) ;
860 $status = $d->flush($output [, $flush_type]) ;
861 $d->deflateParams(OPTS) ;
862 $d->deflateTune(OPTS) ;
f4c6fd49 863 $d->dict_adler() ;
642e522c
RGS
864 $d->crc32() ;
865 $d->adler32() ;
f4c6fd49
RGS
866 $d->total_in() ;
867 $d->total_out() ;
868 $d->msg() ;
642e522c
RGS
869 $d->get_Strategy();
870 $d->get_Level();
871 $d->get_BufSize();
f4c6fd49 872
642e522c
RGS
873 ($i, $status) = new Compress::Zlib::Inflate( [OPT] ) ;
874 $status = $i->inflate($input, $output) ;
875 $status = $i->inflateSync($input) ;
f4c6fd49 876 $i->dict_adler() ;
642e522c
RGS
877 $d->crc32() ;
878 $d->adler32() ;
f4c6fd49
RGS
879 $i->total_in() ;
880 $i->total_out() ;
881 $i->msg() ;
642e522c 882 $d->get_BufSize();
f4c6fd49 883
642e522c 884 $dest = compress($source) ;
f4c6fd49
RGS
885 $dest = uncompress($source) ;
886
887 $gz = gzopen($filename or filehandle, $mode) ;
888 $bytesread = $gz->gzread($buffer [,$size]) ;
889 $bytesread = $gz->gzreadline($line) ;
890 $byteswritten = $gz->gzwrite($buffer) ;
891 $status = $gz->gzflush($flush) ;
642e522c
RGS
892 $offset = $gz->gztell() ;
893 $status = $gz->gzseek($offset, $whence) ;
f4c6fd49
RGS
894 $status = $gz->gzclose() ;
895 $status = $gz->gzeof() ;
896 $status = $gz->gzsetparams($level, $strategy) ;
897 $errstring = $gz->gzerror() ;
898 $gzerrno
899
900 $dest = Compress::Zlib::memGzip($buffer) ;
901 $dest = Compress::Zlib::memGunzip($buffer) ;
902
903 $crc = adler32($buffer [,$crc]) ;
904 $crc = crc32($buffer [,$crc]) ;
905
642e522c
RGS
906 $crc = adler32_combine($crc1, $crc2, $len2)l
907 $crc = crc32_combine($adler1, $adler2, $len2)
908
f4c6fd49 909 ZLIB_VERSION
642e522c
RGS
910 ZLIB_VERNUM
911
912 # Compress::Zlib 1.x legacy interface
913
914 ($d, $status) = deflateInit( [OPT] ) ;
915 ($out, $status) = $d->deflate($buffer) ;
916 $status = $d->deflateParams([OPT]) ;
917 ($out, $status) = $d->flush() ;
918 $d->dict_adler() ;
919 $d->total_in() ;
920 $d->total_out() ;
921 $d->msg() ;
922
923 ($i, $status) = inflateInit( [OPT] ) ;
924 ($out, $status) = $i->inflate($buffer) ;
925 $status = $i->inflateSync($buffer) ;
926 $i->dict_adler() ;
927 $i->total_in() ;
928 $i->total_out() ;
929 $i->msg() ;
930
f4c6fd49
RGS
931
932=head1 DESCRIPTION
933
934The I<Compress::Zlib> module provides a Perl interface to the I<zlib>
935compression library (see L</AUTHOR> for details about where to get
642e522c
RGS
936I<zlib>).
937The I<zlib> library allows reading and writing of
938compressed data streams that conform to RFC1950, RFC1951 and RFC1952
939(aka gzip).
940Most of the I<zlib> functionality is available in I<Compress::Zlib>.
f4c6fd49 941
642e522c
RGS
942Unless you are working with legacy code, or you need to work directly
943with the low-level zlib interface, it is recommended that applications
944use one of the newer C<IO::*> interfaces provided with this module.
f4c6fd49 945
642e522c
RGS
946The C<Compress::Zlib> module can be split into two general areas of
947functionality, namely a low-level in-memory compression/decompression
948interface and a simple read/write interface to I<gzip> files.
f4c6fd49 949
642e522c 950Each of these areas will be discussed separately below.
f4c6fd49 951
f4c6fd49 952
642e522c 953=head1 GZIP INTERFACE
f4c6fd49 954
642e522c
RGS
955A number of functions are supplied in I<zlib> for reading and writing
956I<gzip> files that conform to RFC1952. This module provides an interface
957to most of them.
f4c6fd49 958
642e522c
RGS
959If you are upgrading from C<Compress::Zlib> 1.x, the following enhancements
960have been made to the C<gzopen> interface:
f4c6fd49 961
642e522c 962=over 5
f4c6fd49 963
642e522c 964=item 1
f4c6fd49 965
642e522c
RGS
966If you want to to open either STDIN or STDOUT with C<gzopen>, you can
967optionally use the special filename "C<->" as a synonym for C<\*STDIN> and
968C<\*STDOUT>.
f4c6fd49 969
642e522c 970=item 2
f4c6fd49 971
642e522c
RGS
972In C<Compress::Zlib> version 1.x, C<gzopen> used the zlib library to open the
973underlying file. This made things especially tricky when a Perl filehandle was
974passed to C<gzopen>. Behind the scenes the numeric C file descriptor had to be
975extracted from the Perl filehandle and this passed to the zlib library.
f4c6fd49 976
642e522c
RGS
977Apart from being non-portable to some operating systems, this made it difficult
978to use C<gzopen> in situations where you wanted to extract/create a gzip data
979stream that is embedded in a larger file, without having to resort to opening
980and closing the file multiple times.
f4c6fd49 981
642e522c
RGS
982In C<Compress::Zlib> version 2.x, the C<gzopen> interface has been completely
983rewritten to use the L<IO::Compress::Gzip|IO::Compress::Gzip> for writing gzip files and
984L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for reading gzip files.
f4c6fd49 985
642e522c 986=item 3
f4c6fd49 987
642e522c 988Addition of C<gzseek> to provide a restricted C<seek> interface.
f4c6fd49 989
642e522c 990=item 4.
f4c6fd49 991
642e522c 992Added C<gztell>.
f4c6fd49 993
642e522c 994=back
f4c6fd49 995
642e522c
RGS
996A more complete and flexible interface for reading/writing gzip files/buffers
997is included with this module. See L<IO::Compress::Gzip|IO::Compress::Gzip> and
998L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for more details.
f4c6fd49 999
642e522c 1000=over 5
f4c6fd49 1001
642e522c 1002=item B<$gz = gzopen($filename, $mode)>
f4c6fd49 1003
642e522c 1004=item B<$gz = gzopen($filehandle, $mode)>
f4c6fd49 1005
642e522c
RGS
1006This function opens either the I<gzip> file C<$filename> for reading or writing
1007or attaches to the opened filehandle, C<$filehandle>. It returns an object on
1008success and C<undef> on failure.
f4c6fd49 1009
642e522c
RGS
1010When writing a gzip file this interface will always create the smallest
1011possible gzip header (exactly 10 bytes). If you want control over the
1012information stored in the gzip header (like the original filename or a comment)
1013use L<IO::Compress::Gzip|IO::Compress::Gzip> instead.
f4c6fd49 1014
642e522c
RGS
1015The second parameter, C<$mode>, is used to specify whether the file is
1016opened for reading or writing and to optionally specify a compression
1017level and compression strategy when writing. The format of the C<$mode>
1018parameter is similar to the mode parameter to the 'C' function C<fopen>,
1019so "rb" is used to open for reading and "wb" for writing.
f4c6fd49 1020
642e522c
RGS
1021To specify a compression level when writing, append a digit between 0
1022and 9 to the mode string -- 0 means no compression and 9 means maximum
1023compression.
1024If no compression level is specified Z_DEFAULT_COMPRESSION is used.
f4c6fd49 1025
642e522c
RGS
1026To specify the compression strategy when writing, append 'f' for filtered
1027data, 'h' for Huffman only compression, or 'R' for run-length encoding.
1028If no strategy is specified Z_DEFAULT_STRATEGY is used.
f4c6fd49 1029
642e522c
RGS
1030So, for example, "wb9" means open for writing with the maximum compression
1031using the default strategy and "wb4R" means open for writing with compression
1032level 4 and run-length encoding.
f4c6fd49 1033
642e522c
RGS
1034Refer to the I<zlib> documentation for the exact format of the C<$mode>
1035parameter.
f4c6fd49 1036
f4c6fd49 1037
642e522c
RGS
1038=item B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>
1039
1040Reads C<$size> bytes from the compressed file into C<$buffer>. If
1041C<$size> is not specified, it will default to 4096. If the scalar
1042C<$buffer> is not large enough, it will be extended automatically.
1043
1044Returns the number of bytes actually read. On EOF it returns 0 and in
1045the case of an error, -1.
1046
1047=item B<$bytesread = $gz-E<gt>gzreadline($line) ;>
1048
1049Reads the next line from the compressed file into C<$line>.
1050
1051Returns the number of bytes actually read. On EOF it returns 0 and in
1052the case of an error, -1.
1053
1054It is legal to intermix calls to C<gzread> and C<gzreadline>.
1055
1056In addition, C<gzreadline> fully supports the use of of the variable C<$/>
1057(C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
1058determine what constitutes an end of line. Both paragraph mode and file
1059slurp mode are supported.
1060
1061
1062=item B<$byteswritten = $gz-E<gt>gzwrite($buffer) ;>
1063
1064Writes the contents of C<$buffer> to the compressed file. Returns the
1065number of bytes actually written, or 0 on error.
1066
1067=item B<$status = $gz-E<gt>gzflush($flush_type) ;>
1068
1069Flushes all pending output into the compressed file.
1070
1071This method takes an optional parameter, C<$flush_type>, that controls
1072how the flushing will be carried out. By default the C<$flush_type>
1073used is C<Z_FINISH>. Other valid values for C<$flush_type> are
1074C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
1075strongly recommended that you only set the C<flush_type> parameter if
1076you fully understand the implications of what it does - overuse of C<flush>
1077can seriously degrade the level of compression achieved. See the C<zlib>
1078documentation for details.
1079
1080Returns 1 on success, 0 on failure.
1081
1082
1083=item B<$offset = $gz-E<gt>gztell() ;>
1084
1085Returns the uncompressed file offset.
1086
1087=item B<$status = $gz-E<gt>gzseek($offset, $whence) ;>
1088
1089Sets the file position of the
1090
1091Provides a sub-set of the C<seek> functionality, with the restriction
1092that it is only legal to seek forward in the compressed file.
1093It is a fatal error to attempt to seek backward.
1094
1095When opened for writing, empty parts of the file will have NULL (0x00)
1096bytes written to them.
1097
1098The C<$whence> parameter should be one of SEEK_SET, SEEK_CUR or SEEK_END.
1099
1100Returns 1 on success, 0 on failure.
1101
1102=item B<$gz-E<gt>gzclose>
1103
1104Closes the compressed file. Any pending data is flushed to the file
1105before it is closed.
1106
1107Returns 1 on success, 0 on failure.
1108
1109=item B<$gz-E<gt>gzsetparams($level, $strategy>
1110
1111Change settings for the deflate stream C<$gz>.
1112
1113The list of the valid options is shown below. Options not specified
1114will remain unchanged.
1115
1116Note: This method is only available if you are running zlib 1.0.6 or better.
1117
1118=over 5
1119
1120=item B<$level>
1121
1122Defines the compression level. Valid values are 0 through 9,
1123C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1124C<Z_DEFAULT_COMPRESSION>.
1125
1126=item B<$strategy>
1127
1128Defines the strategy used to tune the compression. The valid values are
1129C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1130
1131=back
1132
1133=item B<$gz-E<gt>gzerror>
1134
1135Returns the I<zlib> error message or number for the last operation
1136associated with C<$gz>. The return value will be the I<zlib> error
1137number when used in a numeric context and the I<zlib> error message
1138when used in a string context. The I<zlib> error number constants,
1139shown below, are available for use.
1140
1141 Z_OK
1142 Z_STREAM_END
1143 Z_ERRNO
1144 Z_STREAM_ERROR
1145 Z_DATA_ERROR
1146 Z_MEM_ERROR
1147 Z_BUF_ERROR
1148
1149=item B<$gzerrno>
1150
1151The C<$gzerrno> scalar holds the error code associated with the most
1152recent I<gzip> routine. Note that unlike C<gzerror()>, the error is
1153I<not> associated with a particular file.
1154
1155As with C<gzerror()> it returns an error number in numeric context and
1156an error message in string context. Unlike C<gzerror()> though, the
1157error message will correspond to the I<zlib> message when the error is
1158associated with I<zlib> itself, or the UNIX error message when it is
1159not (i.e. I<zlib> returned C<Z_ERRORNO>).
1160
1161As there is an overlap between the error numbers used by I<zlib> and
1162UNIX, C<$gzerrno> should only be used to check for the presence of
1163I<an> error in numeric context. Use C<gzerror()> to check for specific
1164I<zlib> errors. The I<gzcat> example below shows how the variable can
1165be used safely.
1166
1167=back
1168
1169
1170=head2 Examples
1171
1172Here is an example script which uses the interface. It implements a
1173I<gzcat> function.
1174
1175 use strict ;
1176 use warnings ;
1177
1178 use Compress::Zlib ;
1179
1180 # use stdin if no files supplied
1181 @ARGV = '-' unless @ARGV ;
1182
1183 foreach my $file (@ARGV) {
1184 my $buffer ;
1185
1186 my $gz = gzopen($file, "rb")
1187 or die "Cannot open $file: $gzerrno\n" ;
1188
1189 print $buffer while $gz->gzread($buffer) > 0 ;
1190
1191 die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n"
1192 if $gzerrno != Z_STREAM_END ;
1193
1194 $gz->gzclose() ;
1195 }
1196
1197Below is a script which makes use of C<gzreadline>. It implements a
1198very simple I<grep> like script.
1199
1200 use strict ;
1201 use warnings ;
1202
1203 use Compress::Zlib ;
1204
1205 die "Usage: gzgrep pattern [file...]\n"
1206 unless @ARGV >= 1;
1207
1208 my $pattern = shift ;
1209
1210 # use stdin if no files supplied
1211 @ARGV = '-' unless @ARGV ;
1212
1213 foreach my $file (@ARGV) {
1214 my $gz = gzopen($file, "rb")
1215 or die "Cannot open $file: $gzerrno\n" ;
1216
1217 while ($gz->gzreadline($_) > 0) {
1218 print if /$pattern/ ;
1219 }
1220
1221 die "Error reading from $file: $gzerrno\n"
1222 if $gzerrno != Z_STREAM_END ;
1223
1224 $gz->gzclose() ;
1225 }
1226
1227This script, I<gzstream>, does the opposite of the I<gzcat> script
1228above. It reads from standard input and writes a gzip data stream to
1229standard output.
1230
1231 use strict ;
1232 use warnings ;
1233
1234 use Compress::Zlib ;
1235
1236 binmode STDOUT; # gzopen only sets it on the fd
1237
1238 my $gz = gzopen(\*STDOUT, "wb")
1239 or die "Cannot open stdout: $gzerrno\n" ;
1240
1241 while (<>) {
1242 $gz->gzwrite($_)
1243 or die "error writing: $gzerrno\n" ;
1244 }
1245
1246 $gz->gzclose ;
1247
1248=head2 Compress::Zlib::memGzip
1249
1250This function is used to create an in-memory gzip file with the minimum
1251possible gzip header (exactly 10 bytes).
1252
1253 $dest = Compress::Zlib::memGzip($buffer) ;
1254
1255If successful, it returns the in-memory gzip file, otherwise it returns
1256undef.
1257
1258The C<$buffer> parameter can either be a scalar or a scalar reference.
1259
1260See L<IO::Compress::Gzip|IO::Compress::Gzip> for an alternative way to carry out in-memory gzip
1261compression.
1262
1263=head2 Compress::Zlib::memGunzip
1264
1265This function is used to uncompress an in-memory gzip file.
1266
1267 $dest = Compress::Zlib::memGunzip($buffer) ;
1268
1269If successful, it returns the uncompressed gzip file, otherwise it
1270returns undef.
1271
1272The C<$buffer> parameter can either be a scalar or a scalar reference. The
1273contents of the C<$buffer> parameter are destroyed after calling this function.
1274
1275See L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip> for an alternative way to carry out in-memory gzip
1276uncompression.
1277
1278=head1 COMPRESS/UNCOMPRESS
1279
1280Two functions are provided to perform in-memory compression/uncompression of
1281RFC 1950 data streams. They are called C<compress> and C<uncompress>.
1282
1283=over 5
1284
1285=item B<$dest = compress($source [, $level] ) ;>
1286
1287Compresses C<$source>. If successful it returns the compressed
1288data. Otherwise it returns I<undef>.
1289
1290The source buffer, C<$source>, can either be a scalar or a scalar
1291reference.
1292
1293The C<$level> parameter defines the compression level. Valid values are
12940 through 9, C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>,
1295C<Z_BEST_COMPRESSION>, and C<Z_DEFAULT_COMPRESSION>.
1296If C<$level> is not specified C<Z_DEFAULT_COMPRESSION> will be used.
1297
1298
1299=item B<$dest = uncompress($source) ;>
1300
1301Uncompresses C<$source>. If successful it returns the uncompressed
1302data. Otherwise it returns I<undef>.
1303
1304The source buffer can either be a scalar or a scalar reference.
1305
1306=back
1307
1308Please note: the two functions defined above are I<not> compatible with
1309the Unix commands of the same name.
1310
1311See L<IO::Compress::Deflate|IO::Compress::Deflate> and L<IO::Uncompress::Inflate|IO::Uncompress::Inflate> included with
1312this distribution for an alternative interface for reading/writing RFC 1950
1313files/buffers.
1314
1315=head1 CHECKSUM FUNCTIONS
1316
1317Two functions are provided by I<zlib> to calculate checksums. For the
1318Perl interface, the order of the two parameters in both functions has
1319been reversed. This allows both running checksums and one off
1320calculations to be done.
1321
1322 $crc = adler32($buffer [,$crc]) ;
1323 $crc = crc32($buffer [,$crc]) ;
1324
1325The buffer parameters can either be a scalar or a scalar reference.
1326
1327If the $crc parameters is C<undef>, the crc value will be reset.
1328
1329If you have built this module with zlib 1.2.3 or better, two more
1330CRC-related functions are available.
1331
1332 $crc = adler32_combine($crc1, $crc2, $len2)l
1333 $crc = crc32_combine($adler1, $adler2, $len2)
1334
1335These functions allow checksums to be merged.
1336
1337=head1 Compress::Zlib::Deflate
1338
1339This section defines an interface that allows in-memory compression using
1340the I<deflate> interface provided by zlib.
1341
1342Note: The interface defined in this section is different from version
13431.x of this module. The original deflate interface is still available
1344for backward compatibility and is documented in the section
1345L<Compress::Zlib 1.x Deflate Interface>.
1346
1347Here is a definition of the interface available:
1348
1349
1350=head2 B<($d, $status) = new Compress::Zlib::Deflate( [OPT] ) >
1351
1352Initialises a deflation object.
1353
1354If you are familiar with the I<zlib> library, it combines the
1355features of the I<zlib> functions C<deflateInit>, C<deflateInit2>
1356and C<deflateSetDictionary>.
1357
1358If successful, it will return the initialised deflation object, C<$d>
1359and a C<$status> of C<Z_OK> in a list context. In scalar context it
1360returns the deflation object, C<$d>, only.
1361
1362If not successful, the returned deflation object, C<$d>, will be
1363I<undef> and C<$status> will hold the a I<zlib> error code.
1364
1365The function optionally takes a number of named options specified as
1366C<-Name =E<gt> value> pairs. This allows individual options to be
1367tailored without having to specify them all in the parameter list.
1368
1369For backward compatibility, it is also possible to pass the parameters
1370as a reference to a hash containing the name=>value pairs.
1371
1372Below is a list of the valid options:
1373
1374=over 5
1375
1376=item B<-Level>
1377
1378Defines the compression level. Valid values are 0 through 9,
1379C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1380C<Z_DEFAULT_COMPRESSION>.
1381
1382The default is C<-Level =E<gt> Z_DEFAULT_COMPRESSION>.
1383
1384=item B<-Method>
1385
1386Defines the compression method. The only valid value at present (and
1387the default) is C<-Method =E<gt> Z_DEFLATED>.
1388
1389=item B<-WindowBits>
1390
1391For a definition of the meaning and valid values for C<WindowBits>
1392refer to the I<zlib> documentation for I<deflateInit2>.
1393
1394Defaults to C<-WindowBits =E<gt> MAX_WBITS>.
1395
1396=item B<-MemLevel>
1397
1398For a definition of the meaning and valid values for C<MemLevel>
1399refer to the I<zlib> documentation for I<deflateInit2>.
1400
1401Defaults to C<-MemLevel =E<gt> MAX_MEM_LEVEL>.
1402
1403=item B<-Strategy>
1404
1405Defines the strategy used to tune the compression. The valid values are
1406C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED>, C<Z_RLE>, C<Z_FIXED> and
1407C<Z_HUFFMAN_ONLY>.
1408
1409The default is C<-Strategy =E<gt>Z_DEFAULT_STRATEGY>.
1410
1411=item B<-Dictionary>
1412
1413When a dictionary is specified I<Compress::Zlib> will automatically
1414call C<deflateSetDictionary> directly after calling C<deflateInit>. The
1415Adler32 value for the dictionary can be obtained by calling the method
1416C<$d-E<gt>dict_adler()>.
f4c6fd49
RGS
1417
1418The default is no dictionary.
1419
1420=item B<-Bufsize>
1421
642e522c
RGS
1422Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
1423and C<$d-E<gt>flush> methods. If the buffer has to be
f4c6fd49 1424reallocated to increase the size, it will grow in increments of
642e522c
RGS
1425C<Bufsize>.
1426
1427The default buffer size is 4096.
1428
1429=item B<-AppendOutput>
1430
1431This option controls how data is written to the output buffer by the
1432C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
1433
1434If the C<AppendOutput> option is set to false, the output buffers in the
1435C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods will be truncated before
1436uncompressed data is written to them.
1437
1438If the option is set to true, uncompressed data will be appended to the
1439output buffer in the C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
1440
1441This option defaults to false.
1442
1443=item B<-CRC32>
1444
1445If set to true, a crc32 checksum of the uncompressed data will be
1446calculated. Use the C<$d-E<gt>crc32> method to retrieve this value.
1447
1448This option defaults to false.
1449
1450
1451=item B<-ADLER32>
1452
1453If set to true, an adler32 checksum of the uncompressed data will be
1454calculated. Use the C<$d-E<gt>adler32> method to retrieve this value.
1455
1456This option defaults to false.
f4c6fd49 1457
f4c6fd49
RGS
1458
1459=back
1460
642e522c
RGS
1461Here is an example of using the C<Compress::Zlib::Deflate> optional
1462parameter list to override the default buffer size and compression
1463level. All other options will take their default values.
f4c6fd49 1464
642e522c
RGS
1465 my $d = new Compress::Zlib::Deflate ( -Bufsize => 300,
1466 -Level => Z_BEST_SPEED ) ;
f4c6fd49
RGS
1467
1468
642e522c 1469=head2 B<$status = $d-E<gt>deflate($input, $output)>
f4c6fd49 1470
642e522c
RGS
1471Deflates the contents of C<$input> and writes the compressed data to
1472C<$output>.
f4c6fd49 1473
642e522c
RGS
1474The C<$input> and C<$output> parameters can be either scalars or scalar
1475references.
f4c6fd49 1476
642e522c
RGS
1477When finished, C<$input> will be completely processed (assuming there
1478were no errors). If the deflation was successful it writes the deflated
1479data to C<$output> and returns a status value of C<Z_OK>.
f4c6fd49 1480
642e522c 1481On error, it returns a I<zlib> error code.
f4c6fd49 1482
642e522c
RGS
1483If the C<AppendOutput> option is set to true in the constructor for
1484the C<$d> object, the compressed data will be appended to C<$output>. If
1485it is false, C<$output> will be truncated before any compressed data is
1486written to it.
f4c6fd49 1487
642e522c
RGS
1488B<Note>: This method will not necessarily write compressed data to
1489C<$output> every time it is called. So do not assume that there has been
1490an error if the contents of C<$output> is empty on returning from
1491this method. As long as the return code from the method is C<Z_OK>,
1492the deflate has succeeded.
f4c6fd49 1493
642e522c 1494=head2 B<$status = $d-E<gt>flush($output [, $flush_type]) >
f4c6fd49
RGS
1495
1496Typically used to finish the deflation. Any pending output will be
642e522c 1497written to C<$output>.
f4c6fd49 1498
642e522c 1499Returns C<Z_OK> if successful.
f4c6fd49
RGS
1500
1501Note that flushing can seriously degrade the compression ratio, so it
1502should only be used to terminate a decompression (using C<Z_FINISH>) or
1503when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
1504
1505By default the C<flush_type> used is C<Z_FINISH>. Other valid values
1506for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
1507and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
1508C<flush_type> parameter if you fully understand the implications of
1509what it does. See the C<zlib> documentation for details.
1510
642e522c
RGS
1511If the C<AppendOutput> option is set to true in the constructor for
1512the C<$d> object, the compressed data will be appended to C<$output>. If
1513it is false, C<$output> will be truncated before any compressed data is
1514written to it.
1515
f4c6fd49
RGS
1516=head2 B<$status = $d-E<gt>deflateParams([OPT])>
1517
642e522c 1518Change settings for the deflate object C<$d>.
f4c6fd49
RGS
1519
1520The list of the valid options is shown below. Options not specified
1521will remain unchanged.
1522
642e522c 1523
f4c6fd49
RGS
1524=over 5
1525
1526=item B<-Level>
1527
1528Defines the compression level. Valid values are 0 through 9,
1529C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1530C<Z_DEFAULT_COMPRESSION>.
1531
1532=item B<-Strategy>
1533
1534Defines the strategy used to tune the compression. The valid values are
1535C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1536
642e522c
RGS
1537=item B<-BufSize>
1538
1539Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
1540and C<$d-E<gt>flush> methods. If the buffer has to be
1541reallocated to increase the size, it will grow in increments of
1542C<Bufsize>.
1543
1544
f4c6fd49
RGS
1545=back
1546
642e522c
RGS
1547=head2 B<$status = $d-E<gt>deflateTune($good_length, $max_lazy, $nice_length, $max_chain)>
1548
1549Tune the internal settings for the deflate object C<$d>. This option is
1550only available if you are running zlib 1.2.2.3 or better.
1551
1552Refer to the documentation in zlib.h for instructions on how to fly
1553C<deflateTune>.
1554
f4c6fd49
RGS
1555=head2 B<$d-E<gt>dict_adler()>
1556
1557Returns the adler32 value for the dictionary.
1558
642e522c
RGS
1559=head2 B<$d-E<gt>crc32()>
1560
1561Returns the crc32 value for the uncompressed data to date.
1562
1563If the C<CRC32> option is not enabled in the constructor for this object,
1564this method will always return 0;
1565
1566=head2 B<$d-E<gt>adler32()>
1567
1568Returns the adler32 value for the uncompressed data to date.
1569
f4c6fd49
RGS
1570=head2 B<$d-E<gt>msg()>
1571
1572Returns the last error message generated by zlib.
1573
1574=head2 B<$d-E<gt>total_in()>
1575
1576Returns the total number of bytes uncompressed bytes input to deflate.
1577
1578=head2 B<$d-E<gt>total_out()>
1579
1580Returns the total number of compressed bytes output from deflate.
1581
642e522c
RGS
1582=head2 B<$d-E<gt>get_Strategy()>
1583
1584Returns the deflation strategy currently used. Valid values are
1585C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
1586
1587
1588=head2 B<$d-E<gt>get_Level()>
1589
1590Returns the compression level being used.
1591
1592=head2 B<$d-E<gt>get_BufSize()>
1593
1594Returns the buffer size used to carry out the compression.
1595
f4c6fd49
RGS
1596=head2 Example
1597
1598
642e522c 1599Here is a trivial example of using C<deflate>. It simply reads standard
f4c6fd49
RGS
1600input, deflates it and writes it to standard output.
1601
1602 use strict ;
1603 use warnings ;
1604
642e522c 1605 use Compress::Zlib 2 ;
f4c6fd49
RGS
1606
1607 binmode STDIN;
1608 binmode STDOUT;
642e522c 1609 my $x = new Compress::Zlib::Deflate
f4c6fd49
RGS
1610 or die "Cannot create a deflation stream\n" ;
1611
1612 my ($output, $status) ;
1613 while (<>)
1614 {
642e522c 1615 $status = $x->deflate($_, $output) ;
f4c6fd49
RGS
1616
1617 $status == Z_OK
1618 or die "deflation failed\n" ;
1619
1620 print $output ;
1621 }
1622
642e522c 1623 $status = $x->flush($output) ;
f4c6fd49
RGS
1624
1625 $status == Z_OK
1626 or die "deflation failed\n" ;
1627
1628 print $output ;
1629
642e522c
RGS
1630=head1 Compress::Zlib::Inflate
1631
1632This section defines an interface that allows in-memory uncompression using
1633the I<inflate> interface provided by zlib.
1634
1635Note: The interface defined in this section is different from version
16361.x of this module. The original inflate interface is still available
1637for backward compatibility and is documented in the section
1638L<Compress::Zlib 1.x Inflate Interface>.
f4c6fd49
RGS
1639
1640Here is a definition of the interface:
1641
1642
642e522c 1643=head2 B< ($i, $status) = new Compress::Zlib::Inflate( [OPT] ) >
f4c6fd49 1644
642e522c 1645Initialises an inflation object.
f4c6fd49 1646
642e522c
RGS
1647In a list context it returns the inflation object, C<$i>, and the
1648I<zlib> status code (C<$status>). In a scalar context it returns the
1649inflation object only.
f4c6fd49 1650
642e522c 1651If successful, C<$i> will hold the inflation object and C<$status> will
f4c6fd49
RGS
1652be C<Z_OK>.
1653
642e522c 1654If not successful, C<$i> will be I<undef> and C<$status> will hold the
f4c6fd49
RGS
1655I<zlib> error code.
1656
1657The function optionally takes a number of named options specified as
642e522c 1658C<-Name =E<gt> value> pairs. This allows individual options to be
f4c6fd49 1659tailored without having to specify them all in the parameter list.
642e522c 1660
f4c6fd49 1661For backward compatibility, it is also possible to pass the parameters
642e522c
RGS
1662as a reference to a hash containing the name=E<gt>value pairs.
1663
f4c6fd49
RGS
1664Here is a list of the valid options:
1665
1666=over 5
1667
1668=item B<-WindowBits>
1669
642e522c 1670For a definition of the meaning and valid values for C<WindowBits>
f4c6fd49
RGS
1671refer to the I<zlib> documentation for I<inflateInit2>.
1672
1673Defaults to C<-WindowBits =E<gt>MAX_WBITS>.
1674
1675=item B<-Bufsize>
1676
642e522c
RGS
1677Sets the initial size for the output buffer used by the C<$i-E<gt>inflate>
1678method. If the output buffer in this method has to be reallocated to
1679increase the size, it will grow in increments of C<Bufsize>.
f4c6fd49
RGS
1680
1681Default is 4096.
1682
1683=item B<-Dictionary>
1684
1685The default is no dictionary.
1686
642e522c
RGS
1687=item B<-AppendOutput>
1688
1689This option controls how data is written to the output buffer by the
1690C<$i-E<gt>inflate> method.
1691
1692If the option is set to false, the output buffer in the C<$i-E<gt>inflate>
1693method will be truncated before uncompressed data is written to it.
1694
1695If the option is set to true, uncompressed data will be appended to the
1696output buffer by the C<$i-E<gt>inflate> method.
1697
1698This option defaults to false.
1699
1700
1701=item B<-CRC32>
1702
1703If set to true, a crc32 checksum of the uncompressed data will be
1704calculated. Use the C<$i-E<gt>crc32> method to retrieve this value.
1705
1706This option defaults to false.
1707
1708=item B<-ADLER32>
1709
1710If set to true, an adler32 checksum of the uncompressed data will be
1711calculated. Use the C<$i-E<gt>adler32> method to retrieve this value.
1712
1713This option defaults to false.
1714
1715=item B<-ConsumeInput>
1716
1717If set to true, this option will remove compressed data from the input
1718buffer of the the C< $i-E<gt>inflate > method as the inflate progresses.
1719
1720This option can be useful when you are processing compressed data that is
1721embedded in another file/buffer. In this case the data that immediately
1722follows the compressed stream will be left in the input buffer.
1723
1724This option defaults to true.
1725
f4c6fd49
RGS
1726=back
1727
642e522c
RGS
1728Here is an example of using an optional parameter to override the default
1729buffer size.
f4c6fd49 1730
642e522c 1731 my ($i, $status) = new Compress::Zlib::Inflate( -Bufsize => 300 ) ;
f4c6fd49 1732
642e522c 1733=head2 B< $status = $i-E<gt>inflate($input, $output) >
f4c6fd49 1734
642e522c
RGS
1735Inflates the complete contents of C<$input> and writes the uncompressed
1736data to C<$output>. The C<$input> and C<$output> parameters can either be
1737scalars or scalar references.
f4c6fd49
RGS
1738
1739Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
1740compressed data has been successfully reached.
f4c6fd49 1741
642e522c
RGS
1742If not successful C<$status> will hold the I<zlib> error code.
1743
1744If the C<ConsumeInput> option has been set to true when the
1745C<Compress::Zlib::Inflate> object is created, the C<$input> parameter
1746is modified by C<inflate>. On completion it will contain what remains
1747of the input buffer after inflation. In practice, this means that when
1748the return status is C<Z_OK> the C<$input> parameter will contain an
1749empty string, and when the return status is C<Z_STREAM_END> the C<$input>
1750parameter will contains what (if anything) was stored in the input buffer
1751after the deflated data stream.
f4c6fd49
RGS
1752
1753This feature is useful when processing a file format that encapsulates
642e522c
RGS
1754a compressed data stream (e.g. gzip, zip) and there is useful data
1755immediately after the deflation stream.
f4c6fd49 1756
642e522c
RGS
1757If the C<AppendOutput> option is set to true in the constructor for
1758this object, the uncompressed data will be appended to C<$output>. If
1759it is false, C<$output> will be truncated before any uncompressed data
1760is written to it.
f4c6fd49 1761
642e522c
RGS
1762=head2 B<$status = $i-E<gt>inflateSync($input)>
1763
1764This method can be used to attempt to recover good data from a compressed
1765data stream that is partially corrupt.
1766It scans C<$input> until it reaches either a I<full flush point> or the
f4c6fd49
RGS
1767end of the buffer.
1768
642e522c
RGS
1769If a I<full flush point> is found, C<Z_OK> is returned and C<$input>
1770will be have all data up to the flush point removed. This data can then be
1771passed to the C<$i-E<gt>inflate> method to be uncompressed.
f4c6fd49
RGS
1772
1773Any other return code means that a flush point was not found. If more
1774data is available, C<inflateSync> can be called repeatedly with more
1775compressed data until the flush point is found.
1776
642e522c
RGS
1777Note I<full flush points> are not present by default in compressed
1778data streams. They must have been added explicitly when the data stream
1779was created by calling C<Compress::Deflate::flush> with C<Z_FULL_FLUSH>.
1780
f4c6fd49
RGS
1781
1782=head2 B<$i-E<gt>dict_adler()>
1783
1784Returns the adler32 value for the dictionary.
1785
642e522c
RGS
1786=head2 B<$i-E<gt>crc32()>
1787
1788Returns the crc32 value for the uncompressed data to date.
1789
1790If the C<CRC32> option is not enabled in the constructor for this object,
1791this method will always return 0;
1792
1793=head2 B<$i-E<gt>adler32()>
1794
1795Returns the adler32 value for the uncompressed data to date.
1796
1797If the C<ADLER32> option is not enabled in the constructor for this object,
1798this method will always return 0;
1799
f4c6fd49
RGS
1800=head2 B<$i-E<gt>msg()>
1801
1802Returns the last error message generated by zlib.
1803
1804=head2 B<$i-E<gt>total_in()>
1805
1806Returns the total number of bytes compressed bytes input to inflate.
1807
1808=head2 B<$i-E<gt>total_out()>
1809
1810Returns the total number of uncompressed bytes output from inflate.
1811
642e522c
RGS
1812=head2 B<$d-E<gt>get_BufSize()>
1813
1814Returns the buffer size used to carry out the decompression.
1815
f4c6fd49
RGS
1816=head2 Example
1817
642e522c 1818Here is an example of using C<inflate>.
f4c6fd49
RGS
1819
1820 use strict ;
1821 use warnings ;
1822
642e522c 1823 use Compress::Zlib 2 ;
f4c6fd49 1824
642e522c 1825 my $x = new Compress::Zlib::Inflate()
f4c6fd49
RGS
1826 or die "Cannot create a inflation stream\n" ;
1827
1828 my $input = '' ;
1829 binmode STDIN;
1830 binmode STDOUT;
1831
1832 my ($output, $status) ;
1833 while (read(STDIN, $input, 4096))
1834 {
642e522c 1835 $status = $x->inflate(\$input, $output) ;
f4c6fd49
RGS
1836
1837 print $output
1838 if $status == Z_OK or $status == Z_STREAM_END ;
1839
1840 last if $status != Z_OK ;
1841 }
1842
1843 die "inflation failed\n"
1844 unless $status == Z_STREAM_END ;
1845
642e522c
RGS
1846=head1 Compress::Zlib 1.x Deflate Interface
1847
1848This section defines the interface available in C<Compress::Zlib> version
18491.x that allows in-memory compression using the I<deflate> interface
1850provided by zlib.
1851
1852Here is a definition of the interface available:
1853
1854
1855=head2 B<($d, $status) = deflateInit( [OPT] )>
f4c6fd49 1856
642e522c
RGS
1857Initialises a deflation stream.
1858
1859It combines the features of the I<zlib> functions C<deflateInit>,
1860C<deflateInit2> and C<deflateSetDictionary>.
1861
1862If successful, it will return the initialised deflation stream, C<$d>
1863and C<$status> of C<Z_OK> in a list context. In scalar context it
1864returns the deflation stream, C<$d>, only.
1865
1866If not successful, the returned deflation stream (C<$d>) will be
1867I<undef> and C<$status> will hold the exact I<zlib> error code.
bdd93743 1868
642e522c
RGS
1869The function optionally takes a number of named options specified as
1870C<-Name=E<gt>value> pairs. This allows individual options to be
1871tailored without having to specify them all in the parameter list.
1872
1873For backward compatibility, it is also possible to pass the parameters
1874as a reference to a hash containing the name=>value pairs.
1875
1876The function takes one optional parameter, a reference to a hash. The
1877contents of the hash allow the deflation interface to be tailored.
1878
1879Here is a list of the valid options:
f4c6fd49
RGS
1880
1881=over 5
1882
642e522c 1883=item B<-Level>
f4c6fd49 1884
642e522c
RGS
1885Defines the compression level. Valid values are 0 through 9,
1886C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1887C<Z_DEFAULT_COMPRESSION>.
f4c6fd49 1888
642e522c 1889The default is C<-Level =E<gt>Z_DEFAULT_COMPRESSION>.
f4c6fd49 1890
642e522c 1891=item B<-Method>
f4c6fd49 1892
642e522c
RGS
1893Defines the compression method. The only valid value at present (and
1894the default) is C<-Method =E<gt>Z_DEFLATED>.
f4c6fd49 1895
642e522c 1896=item B<-WindowBits>
f4c6fd49 1897
642e522c
RGS
1898For a definition of the meaning and valid values for C<WindowBits>
1899refer to the I<zlib> documentation for I<deflateInit2>.
f4c6fd49 1900
642e522c 1901Defaults to C<-WindowBits =E<gt>MAX_WBITS>.
f4c6fd49 1902
642e522c 1903=item B<-MemLevel>
f4c6fd49 1904
642e522c
RGS
1905For a definition of the meaning and valid values for C<MemLevel>
1906refer to the I<zlib> documentation for I<deflateInit2>.
bdd93743 1907
642e522c 1908Defaults to C<-MemLevel =E<gt>MAX_MEM_LEVEL>.
f4c6fd49 1909
642e522c 1910=item B<-Strategy>
f4c6fd49 1911
642e522c
RGS
1912Defines the strategy used to tune the compression. The valid values are
1913C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
f4c6fd49 1914
642e522c 1915The default is C<-Strategy =E<gt>Z_DEFAULT_STRATEGY>.
f4c6fd49 1916
642e522c
RGS
1917=item B<-Dictionary>
1918
1919When a dictionary is specified I<Compress::Zlib> will automatically
1920call C<deflateSetDictionary> directly after calling C<deflateInit>. The
1921Adler32 value for the dictionary can be obtained by calling the method
1922C<$d->dict_adler()>.
f4c6fd49 1923
642e522c 1924The default is no dictionary.
f4c6fd49 1925
642e522c 1926=item B<-Bufsize>
f4c6fd49 1927
642e522c
RGS
1928Sets the initial size for the deflation buffer. If the buffer has to be
1929reallocated to increase the size, it will grow in increments of
1930C<Bufsize>.
f4c6fd49 1931
642e522c 1932The default is 4096.
f4c6fd49 1933
642e522c 1934=back
f4c6fd49 1935
642e522c
RGS
1936Here is an example of using the C<deflateInit> optional parameter list
1937to override the default buffer size and compression level. All other
1938options will take their default values.
f4c6fd49 1939
642e522c
RGS
1940 deflateInit( -Bufsize => 300,
1941 -Level => Z_BEST_SPEED ) ;
f4c6fd49 1942
f4c6fd49 1943
642e522c 1944=head2 B<($out, $status) = $d-E<gt>deflate($buffer)>
f4c6fd49 1945
f4c6fd49 1946
642e522c
RGS
1947Deflates the contents of C<$buffer>. The buffer can either be a scalar
1948or a scalar reference. When finished, C<$buffer> will be
1949completely processed (assuming there were no errors). If the deflation
1950was successful it returns the deflated output, C<$out>, and a status
1951value, C<$status>, of C<Z_OK>.
f4c6fd49 1952
642e522c
RGS
1953On error, C<$out> will be I<undef> and C<$status> will contain the
1954I<zlib> error code.
f4c6fd49 1955
642e522c 1956In a scalar context C<deflate> will return C<$out> only.
f4c6fd49 1957
642e522c
RGS
1958As with the I<deflate> function in I<zlib>, it is not necessarily the
1959case that any output will be produced by this method. So don't rely on
1960the fact that C<$out> is empty for an error test.
f4c6fd49 1961
f4c6fd49 1962
642e522c 1963=head2 B<($out, $status) = $d-E<gt>flush([flush_type])>
f4c6fd49 1964
642e522c
RGS
1965Typically used to finish the deflation. Any pending output will be
1966returned via C<$out>.
1967C<$status> will have a value C<Z_OK> if successful.
f4c6fd49 1968
642e522c 1969In a scalar context C<flush> will return C<$out> only.
f4c6fd49 1970
642e522c
RGS
1971Note that flushing can seriously degrade the compression ratio, so it
1972should only be used to terminate a decompression (using C<Z_FINISH>) or
1973when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
f4c6fd49 1974
642e522c
RGS
1975By default the C<flush_type> used is C<Z_FINISH>. Other valid values
1976for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
1977and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
1978C<flush_type> parameter if you fully understand the implications of
1979what it does. See the C<zlib> documentation for details.
f4c6fd49 1980
642e522c 1981=head2 B<$status = $d-E<gt>deflateParams([OPT])>
f4c6fd49 1982
642e522c 1983Change settings for the deflate stream C<$d>.
f4c6fd49
RGS
1984
1985The list of the valid options is shown below. Options not specified
1986will remain unchanged.
1987
f4c6fd49
RGS
1988=over 5
1989
642e522c 1990=item B<-Level>
f4c6fd49
RGS
1991
1992Defines the compression level. Valid values are 0 through 9,
1993C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
1994C<Z_DEFAULT_COMPRESSION>.
1995
642e522c 1996=item B<-Strategy>
f4c6fd49
RGS
1997
1998Defines the strategy used to tune the compression. The valid values are
1999C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
2000
2001=back
2002
642e522c 2003=head2 B<$d-E<gt>dict_adler()>
f4c6fd49 2004
642e522c 2005Returns the adler32 value for the dictionary.
f4c6fd49 2006
642e522c 2007=head2 B<$d-E<gt>msg()>
f4c6fd49 2008
642e522c 2009Returns the last error message generated by zlib.
f4c6fd49 2010
642e522c 2011=head2 B<$d-E<gt>total_in()>
f4c6fd49 2012
642e522c 2013Returns the total number of bytes uncompressed bytes input to deflate.
f4c6fd49 2014
642e522c 2015=head2 B<$d-E<gt>total_out()>
f4c6fd49 2016
642e522c 2017Returns the total number of compressed bytes output from deflate.
f4c6fd49 2018
642e522c 2019=head2 Example
f4c6fd49 2020
f4c6fd49 2021
642e522c
RGS
2022Here is a trivial example of using C<deflate>. It simply reads standard
2023input, deflates it and writes it to standard output.
f4c6fd49
RGS
2024
2025 use strict ;
2026 use warnings ;
642e522c 2027
f4c6fd49 2028 use Compress::Zlib ;
f4c6fd49 2029
642e522c
RGS
2030 binmode STDIN;
2031 binmode STDOUT;
2032 my $x = deflateInit()
2033 or die "Cannot create a deflation stream\n" ;
f4c6fd49 2034
642e522c
RGS
2035 my ($output, $status) ;
2036 while (<>)
2037 {
2038 ($output, $status) = $x->deflate($_) ;
f4c6fd49 2039
642e522c
RGS
2040 $status == Z_OK
2041 or die "deflation failed\n" ;
f4c6fd49 2042
642e522c 2043 print $output ;
f4c6fd49 2044 }
f4c6fd49 2045
642e522c 2046 ($output, $status) = $x->flush() ;
f4c6fd49 2047
642e522c
RGS
2048 $status == Z_OK
2049 or die "deflation failed\n" ;
f4c6fd49 2050
642e522c 2051 print $output ;
f4c6fd49 2052
642e522c 2053=head1 Compress::Zlib 1.x Inflate Interface
f4c6fd49 2054
642e522c
RGS
2055This section defines the interface available in C<Compress::Zlib> version
20561.x that allows in-memory uncompression using the I<deflate> interface
2057provided by zlib.
f4c6fd49 2058
642e522c 2059Here is a definition of the interface:
f4c6fd49 2060
f4c6fd49 2061
642e522c 2062=head2 B<($i, $status) = inflateInit()>
f4c6fd49 2063
642e522c 2064Initialises an inflation stream.
f4c6fd49 2065
642e522c
RGS
2066In a list context it returns the inflation stream, C<$i>, and the
2067I<zlib> status code (C<$status>). In a scalar context it returns the
2068inflation stream only.
f4c6fd49 2069
642e522c
RGS
2070If successful, C<$i> will hold the inflation stream and C<$status> will
2071be C<Z_OK>.
f4c6fd49 2072
642e522c
RGS
2073If not successful, C<$i> will be I<undef> and C<$status> will hold the
2074I<zlib> error code.
f4c6fd49 2075
642e522c
RGS
2076The function optionally takes a number of named options specified as
2077C<-Name=E<gt>value> pairs. This allows individual options to be
2078tailored without having to specify them all in the parameter list.
2079
2080For backward compatibility, it is also possible to pass the parameters
2081as a reference to a hash containing the name=>value pairs.
2082
2083The function takes one optional parameter, a reference to a hash. The
2084contents of the hash allow the deflation interface to be tailored.
2085
2086Here is a list of the valid options:
f4c6fd49 2087
642e522c 2088=over 5
f4c6fd49 2089
642e522c 2090=item B<-WindowBits>
f4c6fd49 2091
642e522c
RGS
2092For a definition of the meaning and valid values for C<WindowBits>
2093refer to the I<zlib> documentation for I<inflateInit2>.
f4c6fd49 2094
642e522c 2095Defaults to C<-WindowBits =E<gt>MAX_WBITS>.
f4c6fd49 2096
642e522c 2097=item B<-Bufsize>
f4c6fd49 2098
642e522c
RGS
2099Sets the initial size for the inflation buffer. If the buffer has to be
2100reallocated to increase the size, it will grow in increments of
2101C<Bufsize>.
f4c6fd49 2102
642e522c 2103Default is 4096.
5993747c 2104
642e522c 2105=item B<-Dictionary>
5993747c 2106
642e522c 2107The default is no dictionary.
5993747c 2108
642e522c 2109=back
5993747c 2110
642e522c
RGS
2111Here is an example of using the C<inflateInit> optional parameter to
2112override the default buffer size.
5993747c 2113
642e522c 2114 inflateInit( -Bufsize => 300 ) ;
5993747c 2115
642e522c 2116=head2 B<($out, $status) = $i-E<gt>inflate($buffer)>
5993747c 2117
642e522c
RGS
2118Inflates the complete contents of C<$buffer>. The buffer can either be
2119a scalar or a scalar reference.
5993747c 2120
642e522c
RGS
2121Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
2122compressed data has been successfully reached.
2123If not successful, C<$out> will be I<undef> and C<$status> will hold
2124the I<zlib> error code.
5993747c 2125
642e522c
RGS
2126The C<$buffer> parameter is modified by C<inflate>. On completion it
2127will contain what remains of the input buffer after inflation. This
2128means that C<$buffer> will be an empty string when the return status is
2129C<Z_OK>. When the return status is C<Z_STREAM_END> the C<$buffer>
2130parameter will contains what (if anything) was stored in the input
2131buffer after the deflated data stream.
5993747c 2132
642e522c
RGS
2133This feature is useful when processing a file format that encapsulates
2134a compressed data stream (e.g. gzip, zip).
5993747c 2135
642e522c 2136=head2 B<$status = $i-E<gt>inflateSync($buffer)>
5993747c 2137
642e522c
RGS
2138Scans C<$buffer> until it reaches either a I<full flush point> or the
2139end of the buffer.
5993747c 2140
642e522c
RGS
2141If a I<full flush point> is found, C<Z_OK> is returned and C<$buffer>
2142will be have all data up to the flush point removed. This can then be
2143passed to the C<deflate> method.
5993747c 2144
642e522c
RGS
2145Any other return code means that a flush point was not found. If more
2146data is available, C<inflateSync> can be called repeatedly with more
2147compressed data until the flush point is found.
5993747c 2148
5993747c 2149
642e522c 2150=head2 B<$i-E<gt>dict_adler()>
5993747c 2151
642e522c 2152Returns the adler32 value for the dictionary.
5993747c 2153
642e522c 2154=head2 B<$i-E<gt>msg()>
5993747c 2155
642e522c 2156Returns the last error message generated by zlib.
5993747c 2157
642e522c 2158=head2 B<$i-E<gt>total_in()>
5993747c 2159
642e522c 2160Returns the total number of bytes compressed bytes input to inflate.
f4c6fd49 2161
642e522c 2162=head2 B<$i-E<gt>total_out()>
f4c6fd49 2163
642e522c 2164Returns the total number of uncompressed bytes output from inflate.
f4c6fd49 2165
642e522c 2166=head2 Example
f4c6fd49 2167
642e522c 2168Here is an example of using C<inflate>.
f4c6fd49 2169
642e522c
RGS
2170 use strict ;
2171 use warnings ;
2172
2173 use Compress::Zlib ;
2174
2175 my $x = inflateInit()
2176 or die "Cannot create a inflation stream\n" ;
2177
2178 my $input = '' ;
2179 binmode STDIN;
2180 binmode STDOUT;
2181
2182 my ($output, $status) ;
2183 while (read(STDIN, $input, 4096))
2184 {
2185 ($output, $status) = $x->inflate(\$input) ;
2186
2187 print $output
2188 if $status == Z_OK or $status == Z_STREAM_END ;
2189
2190 last if $status != Z_OK ;
2191 }
2192
2193 die "inflation failed\n"
2194 unless $status == Z_STREAM_END ;
f4c6fd49 2195
642e522c 2196=head1 ACCESSING ZIP FILES
f4c6fd49 2197
642e522c
RGS
2198Although it is possible (with some effort on your part) to use this
2199module to access .zip files, there is a module on CPAN that will do all
2200the hard work for you. Check out the C<Archive::Zip> module on CPAN at
f4c6fd49 2201
642e522c 2202 http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
f4c6fd49 2203
f4c6fd49
RGS
2204
2205=head1 CONSTANTS
2206
2207All the I<zlib> constants are automatically imported when you make use
2208of I<Compress::Zlib>.
2209
642e522c
RGS
2210
2211=head1 SEE ALSO
2212
2213L<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::Uncompress::AnyInflate>
2214
2215L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
2216
2217L<File::GlobMapper|File::GlobMapper>, L<Archive::Tar|Archive::Zip>,
2218L<IO::Zlib|IO::Zlib>
2219
2220For RFC 1950, 1951 and 1952 see
2221F<http://www.faqs.org/rfcs/rfc1950.html>,
2222F<http://www.faqs.org/rfcs/rfc1951.html> and
2223F<http://www.faqs.org/rfcs/rfc1952.html>
2224
2225The primary site for the gzip program is F<http://www.gzip.org>.
2226
f4c6fd49
RGS
2227=head1 AUTHOR
2228
2229The I<Compress::Zlib> module was written by Paul Marquess,
2230F<pmqs@cpan.org>. The latest copy of the module can be
2231found on CPAN in F<modules/by-module/Compress/Compress-Zlib-x.x.tar.gz>.
2232
642e522c
RGS
2233The I<zlib> compression library was written by Jean-loup Gailly
2234F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
2235
f4c6fd49
RGS
2236The primary site for the I<zlib> compression library is
2237F<http://www.zlib.org>.
2238
2239=head1 MODIFICATION HISTORY
2240
2241See the Changes file.
642e522c
RGS
2242
2243=head1 COPYRIGHT AND LICENSE
2244
2245
2246Copyright (c) 1995-2005 Paul Marquess. All rights reserved.
2247This program is free software; you can redistribute it and/or
2248modify it under the same terms as Perl itself.
2249
2250
2251
2252
2253