ext/Compress/Zlib/Zlib.pm

   1 # File    : Zlib.pm
   2 # Author  : Paul Marquess
   3 # Created : 30 January 2005
   4 # Version : 1.35
   5 #
   6 #     Copyright (c) 1995-2005 Paul Marquess. All rights reserved.
   7 #     This program is free software; you can redistribute it and/or
   8 #     modify it under the same terms as Perl itself.
   9 #
  10
  11 package Compress::Zlib;
  12
  13 require 5.004 ;
  14 require Exporter;
  15 use AutoLoader;
  16 use Carp ;
  17 use IO::Handle ;
  18
  19 use strict ;
  20 use warnings ;
  21 our ($VERSION, @ISA, @EXPORT, $AUTOLOAD);
  22 our ($deflateDefault, $deflateParamsDefault, $inflateDefault);
  23
  24 $VERSION = "1.35" ;
  25
  26 @ISA = qw(Exporter);
  27 # Items to export into callers namespace by default. Note: do not export
  28 # names by default without a very good reason. Use EXPORT_OK instead.
  29 # Do not simply export all your public functions/methods/constants.
  30 @EXPORT = qw(
  31         deflateInit
  32         inflateInit
  33
  34         compress
  35         uncompress
  36
  37         gzip gunzip
  38
  39         gzopen
  40         $gzerrno
  41
  42         adler32
  43         crc32
  44
  45         ZLIB_VERSION
  46     ZLIB_VERNUM
  47
  48         DEF_WBITS
  49         OS_CODE
  50
  51         MAX_MEM_LEVEL
  52         MAX_WBITS
  53
  54         Z_ASCII
  55         Z_BEST_COMPRESSION
  56         Z_BEST_SPEED
  57         Z_BINARY
  58         Z_BUF_ERROR
  59         Z_DATA_ERROR
  60         Z_DEFAULT_COMPRESSION
  61         Z_DEFAULT_STRATEGY
  62         Z_DEFLATED
  63         Z_ERRNO
  64         Z_FILTERED
  65         Z_FINISH
  66         Z_FULL_FLUSH
  67         Z_HUFFMAN_ONLY
  68         Z_MEM_ERROR
  69         Z_NEED_DICT
  70         Z_NO_COMPRESSION
  71         Z_NO_FLUSH
  72         Z_NULL
  73         Z_OK
  74         Z_PARTIAL_FLUSH
  75         Z_STREAM_END
  76         Z_STREAM_ERROR
  77         Z_SYNC_FLUSH
  78         Z_UNKNOWN
  79         Z_VERSION_ERROR
  80 );
  81
  82
  83
  84 sub AUTOLOAD {
  85     my($constname);
  86     ($constname = $AUTOLOAD) =~ s/.*:://;
  87     my ($error, $val) = constant($constname);
  88     Carp::croak $error if $error;
  89     no strict 'refs';
  90     *{$AUTOLOAD} = sub { $val };
  91     goto &{$AUTOLOAD};
  92 }
  93
  94 eval {
  95     require XSLoader;
  96     XSLoader::load('Compress::Zlib', $VERSION);
  97 } or do {
  98     require DynaLoader;
  99     local @ISA = qw(DynaLoader);
 100     bootstrap Compress::Zlib $VERSION ;
 101 } ;
 102
 103 # Preloaded methods go here.
 104
 105 sub isaFilehandle($)
 106 {
 107     my $fh = shift ;
 108
 109     return ((UNIVERSAL::isa($fh,'GLOB') or UNIVERSAL::isa(\$fh,'GLOB'))
 110                 and defined fileno($fh)  )
 111
 112 }
 113
 114 sub isaFilename($)
 115 {
 116     my $name = shift ;
 117
 118     return (! ref $name and UNIVERSAL::isa(\$name, 'SCALAR')) ;
 119 }
 120
 121 sub gzopen($$)
 122 {
 123     my ($file, $mode) = @_ ;
 124
 125     if (isaFilehandle $file) {
 126         IO::Handle::flush($file) ;
 127         my $offset = tell($file) ;
 128         gzdopen_(fileno($file), $mode, $offset) ;
 129     }
 130     elsif (isaFilename $file) {
 131         gzopen_($file, $mode)
 132     }
 133     else {
 134         croak "gzopen: file parameter is not a filehandle or filename"
 135     }
 136 }
 137
 138 sub ParseParameters($@)
 139 {
 140     my ($default, @rest) = @_ ;
 141     my (%got) = %$default ;
 142     my (@Bad) ;
 143     my ($key, $value) ;
 144     my $sub = (caller(1))[3] ;
 145     my %options = () ;
 146
 147     # allow the options to be passed as a hash reference or
 148     # as the complete hash.
 149     if (@rest == 1) {
 150
 151         croak "$sub: parameter is not a reference to a hash"
 152             if ref $rest[0] ne "HASH" ;
 153
 154         %options = %{ $rest[0] } ;
 155     }
 156     elsif (@rest >= 2) {
 157         my $count = @rest;
 158         croak "$sub: Expected even number of parameters, got $count"
 159             if @rest % 2 != 0 ;
 160         %options = @rest ;
 161     }
 162
 163     while (($key, $value) = each %options)
 164     {
 165         $key =~ s/^-// ;
 166
 167         if (exists $default->{$key})
 168           { $got{$key} = $value }
 169         else
 170           { push (@Bad, $key) }
 171     }
 172
 173     if (@Bad) {
 174         my ($bad) = join(", ", @Bad) ;
 175         croak "unknown key value(s) @Bad" ;
 176     }
 177
 178     return \%got ;
 179 }
 180
 181 $deflateDefault = {
 182         'Level'      => Z_DEFAULT_COMPRESSION(),
 183         'Method'     => Z_DEFLATED(),
 184         'WindowBits' => MAX_WBITS(),
 185         'MemLevel'   => MAX_MEM_LEVEL(),
 186         'Strategy'   => Z_DEFAULT_STRATEGY(),
 187         'Bufsize'    => 4096,
 188         'Dictionary' => "",
 189         } ;
 190
 191 $deflateParamsDefault = {
 192         'Level'      => undef,
 193         'Strategy'   => undef,
 194         'Bufsize'    => undef,
 195         } ;
 196
 197 $inflateDefault = {
 198         'WindowBits' => MAX_WBITS(),
 199         'Bufsize'    => 4096,
 200         'Dictionary' => "",
 201         } ;
 202
 203
 204 sub deflateInit(@)
 205 {
 206     my ($got) = ParseParameters($deflateDefault, @_) ;
 207     no warnings;
 208     croak "deflateInit: Bufsize must be >= 1, you specified $got->{Bufsize}"
 209         unless $got->{Bufsize} >= 1;
 210     _deflateInit($got->{Level}, $got->{Method}, $got->{WindowBits},
 211                 $got->{MemLevel}, $got->{Strategy}, $got->{Bufsize},
 212                 $got->{Dictionary}) ;
 213
 214 }
 215
 216 sub inflateInit(@)
 217 {
 218     my ($got) = ParseParameters($inflateDefault, @_) ;
 219     no warnings;
 220     croak "inflateInit: Bufsize must be >= 1, you specified $got->{Bufsize}"
 221         unless $got->{Bufsize} >= 1;
 222     _inflateInit($got->{WindowBits}, $got->{Bufsize}, $got->{Dictionary});
 223
 224 }
 225
 226 sub Compress::Zlib::deflateStream::deflateParams
 227 {
 228     my $self = shift ;
 229     my ($got) = ParseParameters($deflateParamsDefault, @_) ;
 230     croak "deflateParams needs Level and/or Strategy"
 231         unless defined $got->{Level} || defined $got->{Strategy};
 232     no warnings;
 233     croak "deflateParams: Bufsize must be >= 1, you specified $got->{Bufsize}"
 234         unless  !defined $got->{Bufsize} || $got->{Bufsize} >= 1;
 235
 236     my $flags = 0;
 237     if (defined $got->{Level})
 238       { $flags |= 1 }
 239     else
 240       { $got->{Level} = 0 }
 241
 242     if (defined $got->{Strategy})
 243       { $flags |= 2 }
 244     else
 245       { $got->{Strategy} = 0 }
 246
 247     $got->{Bufsize} = 0
 248         if !defined $got->{Bufsize};
 249
 250     $self->_deflateParams($flags, $got->{Level}, $got->{Strategy},
 251                           $got->{Bufsize});
 252
 253 }
 254
 255 sub compress($;$)
 256 {
 257     my ($x, $output, $out, $err, $in) ;
 258
 259     if (ref $_[0] ) {
 260         $in = $_[0] ;
 261         croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
 262     }
 263     else {
 264         $in = \$_[0] ;
 265     }
 266
 267     my $level = (@_ == 2 ? $_[1] : Z_DEFAULT_COMPRESSION() );
 268
 269
 270     if ( (($x, $err) = deflateInit(Level => $level))[1] == Z_OK()) {
 271
 272         ($output, $err) = $x->deflate($in) ;
 273         return undef unless $err == Z_OK() ;
 274
 275         ($out, $err) = $x->flush() ;
 276         return undef unless $err == Z_OK() ;
 277
 278         return ($output . $out) ;
 279
 280     }
 281
 282     return undef ;
 283 }
 284
 285
 286 sub uncompress($)
 287 {
 288     my ($x, $output, $err, $in) ;
 289
 290     if (ref $_[0] ) {
 291         $in = $_[0] ;
 292         croak "not a scalar reference" unless ref $in eq 'SCALAR' ;
 293     }
 294     else {
 295         $in = \$_[0] ;
 296     }
 297
 298     if ( (($x, $err) = inflateInit())[1] == Z_OK())  {
 299
 300         ($output, $err) = $x->__unc_inflate($in) ;
 301         return undef unless $err == Z_STREAM_END() ;
 302
 303         return $output ;
 304     }
 305
 306     return undef ;
 307 }
 308
 309
 310 # Constants
 311 use constant MAGIC1     => 0x1f ;
 312 use constant MAGIC2     => 0x8b ;
 313 use constant OSCODE     => 3 ;
 314
 315 use constant FTEXT      => 1 ;
 316 use constant FHCRC      => 2 ;
 317 use constant FEXTRA     => 4 ;
 318 use constant FNAME      => 8 ;
 319 use constant FCOMMENT   => 16 ;
 320 use constant NULL       => pack("C", 0) ;
 321 use constant RESERVED   => 0xE0 ;
 322
 323 use constant MIN_HDR_SIZE => 10 ; # minimum gzip header size
 324
 325 sub memGzip($)
 326 {
 327   my $x = deflateInit(
 328                       -Level         => Z_BEST_COMPRESSION(),
 329                       -WindowBits     =>  - MAX_WBITS(),
 330                      )
 331       or return undef ;
 332
 333   # write a minimal gzip header
 334   my(@m);
 335   push @m, pack("C" . MIN_HDR_SIZE,
 336                 MAGIC1, MAGIC2, Z_DEFLATED(), 0,0,0,0,0,0, OSCODE) ;
 337
 338   # if the deflation buffer isn't a reference, make it one
 339   my $string = (ref $_[0] ? $_[0] : \$_[0]) ;
 340
 341   my ($output, $status) = $x->deflate($string) ;
 342   push @m, $output ;
 343   $status == Z_OK()
 344       or return undef ;
 345
 346   ($output, $status) = $x->flush() ;
 347   push @m, $output ;
 348   $status == Z_OK()
 349       or return undef ;
 350
 351   push @m, pack("V V", crc32($string), $x->total_in());
 352
 353   return join "", @m;
 354 }
 355
 356 sub _removeGzipHeader($)
 357 {
 358     my $string = shift ;
 359
 360     return Z_DATA_ERROR()
 361         if length($$string) < MIN_HDR_SIZE ;
 362
 363     my ($magic1, $magic2, $method, $flags, $time, $xflags, $oscode) =
 364         unpack ('CCCCVCC', $$string);
 365
 366     return Z_DATA_ERROR()
 367         unless $magic1 == MAGIC1 and $magic2 == MAGIC2 and
 368            $method == Z_DEFLATED() and !($flags & RESERVED()) ;
 369     substr($$string, 0, MIN_HDR_SIZE) = '' ;
 370
 371     # skip extra field
 372     if ($flags & FEXTRA)
 373     {
 374         return Z_DATA_ERROR()
 375             if length($$string) < 2 ;
 376
 377         my ($extra_len) = unpack ('v', $$string);
 378         $extra_len += 2;
 379         return Z_DATA_ERROR()
 380             if length($$string) < $extra_len ;
 381
 382         substr($$string, 0, $extra_len) = '';
 383     }
 384
 385     # skip orig name
 386     if ($flags & FNAME)
 387     {
 388         my $name_end = index ($$string, NULL);
 389         return Z_DATA_ERROR()
 390            if $name_end == -1 ;
 391         substr($$string, 0, $name_end + 1) =  '';
 392     }
 393
 394     # skip comment
 395     if ($flags & FCOMMENT)
 396     {
 397         my $comment_end = index ($$string, NULL);
 398         return Z_DATA_ERROR()
 399             if $comment_end == -1 ;
 400         substr($$string, 0, $comment_end + 1) = '';
 401     }
 402
 403     # skip header crc
 404     if ($flags & FHCRC)
 405     {
 406         return Z_DATA_ERROR()
 407             if length ($$string) < 2 ;
 408         substr($$string, 0, 2) = '';
 409     }
 410
 411     return Z_OK();
 412 }
 413
 414
 415 sub memGunzip($)
 416 {
 417     # if the buffer isn't a reference, make it one
 418     my $string = (ref $_[0] ? $_[0] : \$_[0]);
 419
 420     _removeGzipHeader($string) == Z_OK()
 421         or return undef;
 422
 423     my $bufsize = length $$string > 4096 ? length $$string : 4096 ;
 424     my $x = inflateInit( -WindowBits => - MAX_WBITS(),
 425                          -Bufsize => $bufsize)
 426               or return undef;
 427     my ($output, $status) = $x->inflate($string);
 428     return undef
 429         unless $status == Z_STREAM_END();
 430
 431     if (length $$string >= 8)
 432     {
 433         my ($crc, $len) = unpack ("VV", substr($$string, 0, 8));
 434         substr($$string, 0, 8) = '';
 435         return undef
 436             unless $len == length($output) and
 437                    $crc == crc32($output);
 438     }
 439     else
 440     {
 441         $$string = '';
 442     }
 443
 444     return $output;
 445 }
 446
 447 # Autoload methods go after __END__, and are processed by the autosplit program.
 448
 449 1;
 450 __END__
 451
 452 =cut
 453
 454 =head1 NAME
 455
 456 Compress::Zlib - Interface to zlib compression library
 457
 458 =head1 SYNOPSIS
 459
 460     use Compress::Zlib ;
 461
 462     ($d, $status) = deflateInit( [OPT] ) ;
 463     ($out, $status) = $d->deflate($buffer) ;
 464     $status = $d->deflateParams([OPT]) ;
 465     ($out, $status) = $d->flush() ;
 466     $d->dict_adler() ;
 467     $d->total_in() ;
 468     $d->total_out() ;
 469     $d->msg() ;
 470
 471     ($i, $status) = inflateInit( [OPT] ) ;
 472     ($out, $status) = $i->inflate($buffer) ;
 473     $status = $i->inflateSync($buffer) ;
 474     $i->dict_adler() ;
 475     $i->total_in() ;
 476     $i->total_out() ;
 477     $i->msg() ;
 478
 479     $dest = compress($source, [$level]) ;
 480     $dest = uncompress($source) ;
 481
 482     $gz = gzopen($filename or filehandle, $mode) ;
 483     $bytesread = $gz->gzread($buffer [,$size]) ;
 484     $bytesread = $gz->gzreadline($line) ;
 485     $byteswritten = $gz->gzwrite($buffer) ;
 486     $status = $gz->gzflush($flush) ;
 487     $status = $gz->gzclose() ;
 488     $status = $gz->gzeof() ;
 489     $status = $gz->gzsetparams($level, $strategy) ;
 490     $errstring = $gz->gzerror() ;
 491     $gzerrno
 492
 493     $dest = Compress::Zlib::memGzip($buffer) ;
 494     $dest = Compress::Zlib::memGunzip($buffer) ;
 495
 496     $crc = adler32($buffer [,$crc]) ;
 497     $crc = crc32($buffer [,$crc]) ;
 498
 499     ZLIB_VERSION
 500
 501 =head1 DESCRIPTION
 502
 503 The I<Compress::Zlib> module provides a Perl interface to the I<zlib>
 504 compression library (see L</AUTHOR> for details about where to get
 505 I<zlib>). Most of the functionality provided by I<zlib> is available
 506 in I<Compress::Zlib>.
 507
 508 The module can be split into two general areas of functionality, namely
 509 in-memory compression/decompression and read/write access to I<gzip>
 510 files. Each of these areas will be discussed separately below.
 511
 512 =head1 DEFLATE
 513
 514 The interface I<Compress::Zlib> provides to the in-memory I<deflate>
 515 (and I<inflate>) functions has been modified to fit into a Perl model.
 516
 517 The main difference is that for both inflation and deflation, the Perl
 518 interface will I<always> consume the complete input buffer before
 519 returning. Also the output buffer returned will be automatically grown
 520 to fit the amount of output available.
 521
 522 Here is a definition of the interface available:
 523
 524
 525 =head2 B<($d, $status) = deflateInit( [OPT] )>
 526
 527 Initialises a deflation stream.
 528
 529 It combines the features of the I<zlib> functions B<deflateInit>,
 530 B<deflateInit2> and B<deflateSetDictionary>.
 531
 532 If successful, it will return the initialised deflation stream, B<$d>
 533 and B<$status> of C<Z_OK> in a list context. In scalar context it
 534 returns the deflation stream, B<$d>, only.
 535
 536 If not successful, the returned deflation stream (B<$d>) will be
 537 I<undef> and B<$status> will hold the exact I<zlib> error code.
 538
 539 The function optionally takes a number of named options specified as
 540 C<-Name=E<gt>value> pairs. This allows individual options to be
 541 tailored without having to specify them all in the parameter list.
 542
 543 For backward compatibility, it is also possible to pass the parameters
 544 as a reference to a hash containing the name=>value pairs.
 545
 546 The function takes one optional parameter, a reference to a hash.  The
 547 contents of the hash allow the deflation interface to be tailored.
 548
 549 Here is a list of the valid options:
 550
 551 =over 5
 552
 553 =item B<-Level>
 554
 555 Defines the compression level. Valid values are 0 through 9,
 556 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
 557 C<Z_DEFAULT_COMPRESSION>.
 558
 559 The default is C<-Level =E<gt>Z_DEFAULT_COMPRESSION>.
 560
 561 =item B<-Method>
 562
 563 Defines the compression method. The only valid value at present (and
 564 the default) is C<-Method =E<gt>Z_DEFLATED>.
 565
 566 =item B<-WindowBits>
 567
 568 For a definition of the meaning and valid values for B<WindowBits>
 569 refer to the I<zlib> documentation for I<deflateInit2>.
 570
 571 Defaults to C<-WindowBits =E<gt>MAX_WBITS>.
 572
 573 =item B<-MemLevel>
 574
 575 For a definition of the meaning and valid values for B<MemLevel>
 576 refer to the I<zlib> documentation for I<deflateInit2>.
 577
 578 Defaults to C<-MemLevel =E<gt>MAX_MEM_LEVEL>.
 579
 580 =item B<-Strategy>
 581
 582 Defines the strategy used to tune the compression. The valid values are
 583 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
 584
 585 The default is C<-Strategy =E<gt>Z_DEFAULT_STRATEGY>.
 586
 587 =item B<-Dictionary>
 588
 589 When a dictionary is specified I<Compress::Zlib> will automatically
 590 call B<deflateSetDictionary> directly after calling B<deflateInit>. The
 591 Adler32 value for the dictionary can be obtained by calling the method
 592 C<$d->dict_adler()>.
 593
 594 The default is no dictionary.
 595
 596 =item B<-Bufsize>
 597
 598 Sets the initial size for the deflation buffer. If the buffer has to be
 599 reallocated to increase the size, it will grow in increments of
 600 B<Bufsize>.
 601
 602 The default is 4096.
 603
 604 =back
 605
 606 Here is an example of using the B<deflateInit> optional parameter list
 607 to override the default buffer size and compression level. All other
 608 options will take their default values.
 609
 610     deflateInit( -Bufsize => 300,
 611                  -Level => Z_BEST_SPEED  ) ;
 612
 613
 614 =head2 B<($out, $status) = $d-E<gt>deflate($buffer)>
 615
 616
 617 Deflates the contents of B<$buffer>. The buffer can either be a scalar
 618 or a scalar reference.  When finished, B<$buffer> will be
 619 completely processed (assuming there were no errors). If the deflation
 620 was successful it returns the deflated output, B<$out>, and a status
 621 value, B<$status>, of C<Z_OK>.
 622
 623 On error, B<$out> will be I<undef> and B<$status> will contain the
 624 I<zlib> error code.
 625
 626 In a scalar context B<deflate> will return B<$out> only.
 627
 628 As with the I<deflate> function in I<zlib>, it is not necessarily the
 629 case that any output will be produced by this method. So don't rely on
 630 the fact that B<$out> is empty for an error test.
 631
 632
 633 =head2 B<($out, $status) = $d-E<gt>flush([flush_type])>
 634
 635 Typically used to finish the deflation. Any pending output will be
 636 returned via B<$out>.
 637 B<$status> will have a value C<Z_OK> if successful.
 638
 639 In a scalar context B<flush> will return B<$out> only.
 640
 641 Note that flushing can seriously degrade the compression ratio, so it
 642 should only be used to terminate a decompression (using C<Z_FINISH>) or
 643 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
 644
 645 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
 646 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
 647 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
 648 C<flush_type> parameter if you fully understand the implications of
 649 what it does. See the C<zlib> documentation for details.
 650
 651 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
 652
 653 Change settings for the deflate stream C<$d>.
 654
 655 The list of the valid options is shown below. Options not specified
 656 will remain unchanged.
 657
 658 =over 5
 659
 660 =item B<-Level>
 661
 662 Defines the compression level. Valid values are 0 through 9,
 663 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
 664 C<Z_DEFAULT_COMPRESSION>.
 665
 666 =item B<-Strategy>
 667
 668 Defines the strategy used to tune the compression. The valid values are
 669 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
 670
 671 =back
 672
 673 =head2 B<$d-E<gt>dict_adler()>
 674
 675 Returns the adler32 value for the dictionary.
 676
 677 =head2 B<$d-E<gt>msg()>
 678
 679 Returns the last error message generated by zlib.
 680
 681 =head2 B<$d-E<gt>total_in()>
 682
 683 Returns the total number of bytes uncompressed bytes input to deflate.
 684
 685 =head2 B<$d-E<gt>total_out()>
 686
 687 Returns the total number of compressed bytes output from deflate.
 688
 689 =head2 Example
 690
 691
 692 Here is a trivial example of using B<deflate>. It simply reads standard
 693 input, deflates it and writes it to standard output.
 694
 695     use strict ;
 696     use warnings ;
 697
 698     use Compress::Zlib ;
 699
 700     binmode STDIN;
 701     binmode STDOUT;
 702     my $x = deflateInit()
 703        or die "Cannot create a deflation stream\n" ;
 704
 705     my ($output, $status) ;
 706     while (<>)
 707     {
 708         ($output, $status) = $x->deflate($_) ;
 709
 710         $status == Z_OK
 711             or die "deflation failed\n" ;
 712
 713         print $output ;
 714     }
 715
 716     ($output, $status) = $x->flush() ;
 717
 718     $status == Z_OK
 719         or die "deflation failed\n" ;
 720
 721     print $output ;
 722
 723 =head1 INFLATE
 724
 725 Here is a definition of the interface:
 726
 727
 728 =head2 B<($i, $status) = inflateInit()>
 729
 730 Initialises an inflation stream.
 731
 732 In a list context it returns the inflation stream, B<$i>, and the
 733 I<zlib> status code (B<$status>). In a scalar context it returns the
 734 inflation stream only.
 735
 736 If successful, B<$i> will hold the inflation stream and B<$status> will
 737 be C<Z_OK>.
 738
 739 If not successful, B<$i> will be I<undef> and B<$status> will hold the
 740 I<zlib> error code.
 741
 742 The function optionally takes a number of named options specified as
 743 C<-Name=E<gt>value> pairs. This allows individual options to be
 744 tailored without having to specify them all in the parameter list.
 745
 746 For backward compatibility, it is also possible to pass the parameters
 747 as a reference to a hash containing the name=>value pairs.
 748
 749 The function takes one optional parameter, a reference to a hash.  The
 750 contents of the hash allow the deflation interface to be tailored.
 751
 752 Here is a list of the valid options:
 753
 754 =over 5
 755
 756 =item B<-WindowBits>
 757
 758 For a definition of the meaning and valid values for B<WindowBits>
 759 refer to the I<zlib> documentation for I<inflateInit2>.
 760
 761 Defaults to C<-WindowBits =E<gt>MAX_WBITS>.
 762
 763 =item B<-Bufsize>
 764
 765 Sets the initial size for the inflation buffer. If the buffer has to be
 766 reallocated to increase the size, it will grow in increments of
 767 B<Bufsize>.
 768
 769 Default is 4096.
 770
 771 =item B<-Dictionary>
 772
 773 The default is no dictionary.
 774
 775 =back
 776
 777 Here is an example of using the B<inflateInit> optional parameter to
 778 override the default buffer size.
 779
 780     inflateInit( -Bufsize => 300 ) ;
 781
 782 =head2 B<($out, $status) = $i-E<gt>inflate($buffer)>
 783
 784 Inflates the complete contents of B<$buffer>. The buffer can either be
 785 a scalar or a scalar reference.
 786
 787 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
 788 compressed data has been successfully reached.
 789 If not successful, B<$out> will be I<undef> and B<$status> will hold
 790 the I<zlib> error code.
 791
 792 The C<$buffer> parameter is modified by C<inflate>. On completion it
 793 will contain what remains of the input buffer after inflation. This
 794 means that C<$buffer> will be an empty string when the return status is
 795 C<Z_OK>. When the return status is C<Z_STREAM_END> the C<$buffer>
 796 parameter will contains what (if anything) was stored in the input
 797 buffer after the deflated data stream.
 798
 799 This feature is useful when processing a file format that encapsulates
 800 a  compressed data stream (e.g. gzip, zip).
 801
 802 =head2 B<$status = $i-E<gt>inflateSync($buffer)>
 803
 804 Scans C<$buffer> until it reaches either a I<full flush point> or the
 805 end of the buffer.
 806
 807 If a I<full flush point> is found, C<Z_OK> is returned and C<$buffer>
 808 will be have all data up to the flush point removed. This can then be
 809 passed to the C<deflate> method.
 810
 811 Any other return code means that a flush point was not found. If more
 812 data is available, C<inflateSync> can be called repeatedly with more
 813 compressed data until the flush point is found.
 814
 815
 816 =head2 B<$i-E<gt>dict_adler()>
 817
 818 Returns the adler32 value for the dictionary.
 819
 820 =head2 B<$i-E<gt>msg()>
 821
 822 Returns the last error message generated by zlib.
 823
 824 =head2 B<$i-E<gt>total_in()>
 825
 826 Returns the total number of bytes compressed bytes input to inflate.
 827
 828 =head2 B<$i-E<gt>total_out()>
 829
 830 Returns the total number of uncompressed bytes output from inflate.
 831
 832 =head2 Example
 833
 834 Here is an example of using B<inflate>.
 835
 836     use strict ;
 837     use warnings ;
 838
 839     use Compress::Zlib ;
 840
 841     my $x = inflateInit()
 842        or die "Cannot create a inflation stream\n" ;
 843
 844     my $input = '' ;
 845     binmode STDIN;
 846     binmode STDOUT;
 847
 848     my ($output, $status) ;
 849     while (read(STDIN, $input, 4096))
 850     {
 851         ($output, $status) = $x->inflate(\$input) ;
 852
 853         print $output
 854             if $status == Z_OK or $status == Z_STREAM_END ;
 855
 856         last if $status != Z_OK ;
 857     }
 858
 859     die "inflation failed\n"
 860         unless $status == Z_STREAM_END ;
 861
 862 =head1 COMPRESS/UNCOMPRESS
 863
 864 Two high-level functions are provided by I<zlib> to perform in-memory
 865 compression/uncompression of RFC1950 data streams. They are called
 866 B<compress> and B<uncompress>.
 867
 868 The two Perl subs defined below provide the equivalent
 869 functionality.
 870
 871 =over 5
 872
 873 =item B<$dest = compress($source [, $level] ) ;>
 874
 875 Compresses B<$source>. If successful it returns the
 876 compressed data. Otherwise it returns I<undef>.
 877
 878 The source buffer can either be a scalar or a scalar reference.
 879
 880 The B<$level> paramter defines the compression level. Valid values are
 881 0 through 9, C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>,
 882 C<Z_BEST_COMPRESSION>, and C<Z_DEFAULT_COMPRESSION>.
 883 If B<$level> is not specified C<Z_DEFAULT_COMPRESSION> will be used.
 884
 885
 886 =item B<$dest = uncompress($source) ;>
 887
 888 Uncompresses B<$source>. If successful it returns the uncompressed
 889 data. Otherwise it returns I<undef>.
 890
 891 The source buffer can either be a scalar or a scalar reference.
 892
 893 =back
 894
 895 Please note: the two functions defined above are I<not> compatible with
 896 the Unix commands of the same name.
 897
 898 =head1 GZIP INTERFACE
 899
 900 A number of functions are supplied in I<zlib> for reading and writing
 901 I<gzip> files. This module provides an interface to most of them. In
 902 general the interface provided by this module operates identically to
 903 the functions provided by I<zlib>. Any differences are explained
 904 below.
 905
 906 =over 5
 907
 908 =item B<$gz = gzopen(filename or filehandle, mode)>
 909
 910 This function operates identically to the I<zlib> equivalent except
 911 that it returns an object which is used to access the other I<gzip>
 912 methods.
 913
 914 As with the I<zlib> equivalent, the B<mode> parameter is used to
 915 specify both whether the file is opened for reading or writing and to
 916 optionally specify a a compression level. Refer to the I<zlib>
 917 documentation for the exact format of the B<mode> parameter.
 918
 919 If a reference to an open filehandle is passed in place of the
 920 filename, gzdopen will be called behind the scenes. The third example
 921 at the end of this section, I<gzstream>, uses this feature.
 922
 923 =item B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>
 924
 925 Reads B<$size> bytes from the compressed file into B<$buffer>. If
 926 B<$size> is not specified, it will default to 4096. If the scalar
 927 B<$buffer> is not large enough, it will be extended automatically.
 928
 929 Returns the number of bytes actually read. On EOF it returns 0 and in
 930 the case of an error, -1.
 931
 932 =item B<$bytesread = $gz-E<gt>gzreadline($line) ;>
 933
 934 Reads the next line from the compressed file into B<$line>.
 935
 936 Returns the number of bytes actually read. On EOF it returns 0 and in
 937 the case of an error, -1.
 938
 939 It is legal to intermix calls to B<gzread> and B<gzreadline>.
 940
 941 At this time B<gzreadline> ignores the variable C<$/>
 942 (C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use). The
 943 end of a line is denoted by the C character C<'\n'>.
 944
 945 =item B<$byteswritten = $gz-E<gt>gzwrite($buffer) ;>
 946
 947 Writes the contents of B<$buffer> to the compressed file. Returns the
 948 number of bytes actually written, or 0 on error.
 949
 950 =item B<$status = $gz-E<gt>gzflush($flush) ;>
 951
 952 Flushes all pending output to the compressed file.
 953 Works identically to the I<zlib> function it interfaces to. Note that
 954 the use of B<gzflush> can degrade compression.
 955
 956 Returns C<Z_OK> if B<$flush> is C<Z_FINISH> and all output could be
 957 flushed. Otherwise the zlib error code is returned.
 958
 959 Refer to the I<zlib> documentation for the valid values of B<$flush>.
 960
 961 =item B<$status = $gz-E<gt>gzeof() ;>
 962
 963 Returns 1 if the end of file has been detected while reading the input
 964 file, otherwise returns 0.
 965
 966 =item B<$gz-E<gt>gzclose>
 967
 968 Closes the compressed file. Any pending data is flushed to the file
 969 before it is closed.
 970
 971 =item B<$gz-E<gt>gzsetparams($level, $strategy>
 972
 973 Change settings for the deflate stream C<$gz>.
 974
 975 The list of the valid options is shown below. Options not specified
 976 will remain unchanged.
 977
 978 Note: This method is only available if you are running zlib 1.0.6 or better.
 979
 980 =over 5
 981
 982 =item B<$level>
 983
 984 Defines the compression level. Valid values are 0 through 9,
 985 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
 986 C<Z_DEFAULT_COMPRESSION>.
 987
 988 =item B<$strategy>
 989
 990 Defines the strategy used to tune the compression. The valid values are
 991 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
 992
 993 =back
 994
 995 =item B<$gz-E<gt>gzerror>
 996
 997 Returns the I<zlib> error message or number for the last operation
 998 associated with B<$gz>. The return value will be the I<zlib> error
 999 number when used in a numeric context and the I<zlib> error message
1000 when used in a string context. The I<zlib> error number constants,
1001 shown below, are available for use.
1002
1003     Z_OK
1004     Z_STREAM_END
1005     Z_ERRNO
1006     Z_STREAM_ERROR
1007     Z_DATA_ERROR
1008     Z_MEM_ERROR
1009     Z_BUF_ERROR
1010
1011 =item B<$gzerrno>
1012
1013 The B<$gzerrno> scalar holds the error code associated with the most
1014 recent I<gzip> routine. Note that unlike B<gzerror()>, the error is
1015 I<not> associated with a particular file.
1016
1017 As with B<gzerror()> it returns an error number in numeric context and
1018 an error message in string context. Unlike B<gzerror()> though, the
1019 error message will correspond to the I<zlib> message when the error is
1020 associated with I<zlib> itself, or the UNIX error message when it is
1021 not (i.e. I<zlib> returned C<Z_ERRORNO>).
1022
1023 As there is an overlap between the error numbers used by I<zlib> and
1024 UNIX, B<$gzerrno> should only be used to check for the presence of
1025 I<an> error in numeric context. Use B<gzerror()> to check for specific
1026 I<zlib> errors. The I<gzcat> example below shows how the variable can
1027 be used safely.
1028
1029 =back
1030
1031
1032 =head2 Examples
1033
1034 Here is an example script which uses the interface. It implements a
1035 I<gzcat> function.
1036
1037     use strict ;
1038     use warnings ;
1039
1040     use Compress::Zlib ;
1041
1042     die "Usage: gzcat file...\n"
1043         unless @ARGV ;
1044
1045     my $file ;
1046
1047     foreach $file (@ARGV) {
1048         my $buffer ;
1049
1050         my $gz = gzopen($file, "rb")
1051              or die "Cannot open $file: $gzerrno\n" ;
1052
1053         print $buffer while $gz->gzread($buffer) > 0 ;
1054
1055         die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n"
1056             if $gzerrno != Z_STREAM_END ;
1057
1058         $gz->gzclose() ;
1059     }
1060
1061 Below is a script which makes use of B<gzreadline>. It implements a
1062 very simple I<grep> like script.
1063
1064     use strict ;
1065     use warnings ;
1066
1067     use Compress::Zlib ;
1068
1069     die "Usage: gzgrep pattern file...\n"
1070         unless @ARGV >= 2;
1071
1072     my $pattern = shift ;
1073
1074     my $file ;
1075
1076     foreach $file (@ARGV) {
1077         my $gz = gzopen($file, "rb")
1078              or die "Cannot open $file: $gzerrno\n" ;
1079
1080         while ($gz->gzreadline($_) > 0) {
1081             print if /$pattern/ ;
1082         }
1083
1084         die "Error reading from $file: $gzerrno\n"
1085             if $gzerrno != Z_STREAM_END ;
1086
1087         $gz->gzclose() ;
1088     }
1089
1090 This script, I<gzstream>, does the opposite of the I<gzcat> script
1091 above. It reads from standard input and writes a gzip file to standard
1092 output.
1093
1094     use strict ;
1095     use warnings ;
1096
1097     use Compress::Zlib ;
1098
1099     binmode STDOUT;     # gzopen only sets it on the fd
1100
1101     my $gz = gzopen(\*STDOUT, "wb")
1102           or die "Cannot open stdout: $gzerrno\n" ;
1103
1104     while (<>) {
1105         $gz->gzwrite($_)
1106         or die "error writing: $gzerrno\n" ;
1107     }
1108
1109     $gz->gzclose ;
1110
1111 =head2 Compress::Zlib::memGzip
1112
1113 This function is used to create an in-memory gzip file.
1114 It creates a minimal gzip header.
1115
1116     $dest = Compress::Zlib::memGzip($buffer) ;
1117
1118 If successful, it returns the in-memory gzip file, otherwise it returns
1119 undef.
1120
1121 The buffer parameter can either be a scalar or a scalar reference.
1122
1123 =head2 Compress::Zlib::memGunzip
1124
1125 This function is used to uncompress an in-memory gzip file.
1126
1127     $dest = Compress::Zlib::memGunzip($buffer) ;
1128
1129 If successful, it returns the uncompressed gzip file, otherwise it
1130 returns undef.
1131
1132 The buffer parameter can either be a scalar or a scalar reference. The
1133 contents of the buffer parameter are destroyed after calling this
1134 function.
1135
1136 =head1 CHECKSUM FUNCTIONS
1137
1138 Two functions are provided by I<zlib> to calculate a checksum. For the
1139 Perl interface, the order of the two parameters in both functions has
1140 been reversed. This allows both running checksums and one off
1141 calculations to be done.
1142
1143     $crc = adler32($buffer [,$crc]) ;
1144     $crc = crc32($buffer [,$crc]) ;
1145
1146 The buffer parameters can either be a scalar or a scalar reference.
1147
1148 If the $crc parameters is C<undef>, the crc value will be reset.
1149
1150 =head1 ACCESSING ZIP FILES
1151
1152 Although it is possible to use this module to access .zip files, there
1153 is a module on CPAN that will do all the hard work for you. Check out
1154
1155     http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
1156
1157 Assuming you don't want to use this module to access zip files there
1158 are a number of undocumented features in the zlib library you need to
1159 be aware of.
1160
1161 =over 5
1162
1163 =item 1.
1164
1165 When calling B<inflateInit> or B<deflateInit> the B<WindowBits> parameter
1166 must be set to C<-MAX_WBITS>. This disables the creation of the zlib
1167 header.
1168
1169 =item 2.
1170
1171 The zlib function B<inflate>, and so the B<inflate> method supplied in
1172 this module, assume that there is at least one trailing byte after the
1173 compressed data stream. Normally this isn't a problem because both
1174 the gzip and zip file formats will guarantee that there is data directly
1175 after the compressed data stream.
1176
1177 =back
1178
1179 =head1 CONSTANTS
1180
1181 All the I<zlib> constants are automatically imported when you make use
1182 of I<Compress::Zlib>.
1183
1184 =head1 AUTHOR
1185
1186 The I<Compress::Zlib> module was written by Paul Marquess,
1187 F<pmqs@cpan.org>. The latest copy of the module can be
1188 found on CPAN in F<modules/by-module/Compress/Compress-Zlib-x.x.tar.gz>.
1189
1190 The primary site for the I<zlib> compression library is
1191 F<http://www.zlib.org>.
1192
1193 =head1 MODIFICATION HISTORY
1194
1195 See the Changes file.