man > Compress::Raw::Zlib

man perldoc info pydoc3 ri search

📖 NAME

Compress::Raw::Zlib - Low-Level Interface to zlib compression library

🚀 Quick Reference

Use Case	Command	Description
📦 Compress data in memory	Compress::Raw::Zlib::Deflate->new(OPT)	Create deflation object with optional compression level, window bits, etc.
📤 Write compressed data	$d->deflate($input, $output)	Compress $input and write to $output; returns Z_OK on success.
🏁 Finalize compression	$d->flush($output [, $flush_type])	Finish deflation, write pending output; default Z_FINISH.
📥 Uncompress data in memory	Compress::Raw::Zlib::Inflate->new(OPT)	Create inflation object with optional window bits, buffer size, etc.
📖 Read uncompressed data	$i->inflate($input, $output [, $eof])	Uncompress $input, write to $output; returns Z_OK or Z_STREAM_END.
🔄 Reset deflation stream	$d->deflateReset()	Reset deflation object for reuse on a new stream.
🔄 Reset inflation stream	$i->inflateReset()	Reset inflation object for reuse.
🔍 Compute checksum	crc32($buffer [, $crc])	Calculate CRC32 checksum; can be incremental.
🔍 Compute checksum	adler32($buffer [, $crc])	Calculate Adler32 checksum; can be incremental.
ℹ️ Get zlib version	Compress::Raw::Zlib::zlib_version()	Returns the version of the zlib library.

📋 SYNOPSIS

use Compress::Raw::Zlib ;

($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) ;
$status = $d->deflate($input, $output) ;
$status = $d->flush($output [, $flush_type]) ;
$d->deflateReset() ;
$d->deflateParams(OPTS) ;
$d->deflateTune(OPTS) ;
$d->dict_adler() ;
$d->crc32() ;
$d->adler32() ;
$d->total_in() ;
$d->total_out() ;
$d->msg() ;
$d->get_Strategy();
$d->get_Level();
$d->get_BufSize();

($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) ;
$status = $i->inflate($input, $output [, $eof]) ;
$status = $i->inflateSync($input) ;
$i->inflateReset() ;
$i->dict_adler() ;
$d->crc32() ;
$d->adler32() ;
$i->total_in() ;
$i->total_out() ;
$i->msg() ;
$d->get_BufSize();

$crc = adler32($buffer [,$crc]) ;
$crc = crc32($buffer [,$crc]) ;

$crc = crc32_combine($crc1, $crc2, $len2);
$adler = adler32_combine($adler1, $adler2, $len2);

my $version = Compress::Raw::Zlib::zlib_version();
my $flags = Compress::Raw::Zlib::zlibCompileFlags();

📝 DESCRIPTION

The Compress::Raw::Zlib module provides a Perl interface to the zlib compression library (see "AUTHOR" for details about where to get zlib).

🔧 Compress::Raw::Zlib::Deflate

This section defines an interface that allows in-memory compression using the deflate interface provided by zlib.

🔹 ($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] )

Initialises a deflation object. If you are familiar with the zlib library, it combines the features of the zlib functions deflateInit, deflateInit2 and deflateSetDictionary.

If successful, it will return the initialised deflation object, $d and a $status of Z_OK in a list context. In scalar context it returns the deflation object, $d, only.

If not successful, the returned deflation object, $d, will be undef and $status will hold a zlib error code.

The function optionally takes a number of named options specified as "Name => value" pairs. For backward compatibility, it is also possible to pass the parameters as a reference to a hash containing the name=>value pairs.

🔹 Valid Options

• -Level — Defines the compression level. Valid values: 0-9, Z_NO_COMPRESSION, Z_BEST_SPEED, Z_BEST_COMPRESSION, Z_DEFAULT_COMPRESSION. Default: Z_DEFAULT_COMPRESSION.
• -Method — Defines the compression method. Only valid value: Z_DEFLATED (default).
• -WindowBits — To compress RFC 1950 data stream, set positive between 8-15. For RFC 1951 (raw deflate), set to -MAX_WBITS. For gzip (RFC 1952), set to WANT_GZIP. Default: MAX_WBITS.
• -MemLevel — Refer to zlib documentation for deflateInit2. Default: MAX_MEM_LEVEL.
• -Strategy — Compression strategy: Z_DEFAULT_STRATEGY, Z_FILTERED, Z_RLE, Z_FIXED, Z_HUFFMAN_ONLY. Default: Z_DEFAULT_STRATEGY.
• -Dictionary — Specifies a dictionary; automatically calls deflateSetDictionary. Adler32 value obtained via $d->dict_adler(). Default: no dictionary.
• -Bufsize — Initial size for output buffer. Default: 4096.
• -AppendOutput — If false, output buffer truncated before writing; if true, appended. Default: false.
• -CRC32 — If true, calculate crc32 checksum of uncompressed data. Retrieve via $d->crc32(). Default: false.
• -ADLER32 — If true, calculate adler32 checksum of uncompressed data. Retrieve via $d->adler32(). Default: false.

Example:

my $d = new Compress::Raw::Zlib::Deflate ( -Bufsize => 300,
                                            -Level   => Z_BEST_SPEED ) ;

🔹 $status = $d->deflate($input, $output)

Deflates contents of $input and writes compressed data to $output. $input and $output can be scalars or scalar references. Returns Z_OK on success. Note: Not every call produces output; check return code.

🔹 $status = $d->flush($output [, $flush_type])

Finishes deflation; writes pending output. Default flush_type is Z_FINISH. Other valid: Z_NO_FLUSH, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, Z_FULL_FLUSH. Use with care.

🔹 $status = $d->deflateReset()

Resets deflation object for reuse on multiple data streams after successful flush.

🔹 $status = $d->deflateParams([OPT])

Change settings: -Level, -Strategy, -BufSize. Options not specified remain unchanged.

🔹 $status = $d->deflateTune($good_length, $max_lazy, $nice_length, $max_chain)

Tune internal settings (zlib 1.2.2.3+). See zlib.h documentation.

🔹 Other Methods

• $d->dict_adler() — Returns adler32 of dictionary.
• $d->crc32() — Returns crc32 of uncompressed data (if CRC32 option enabled).
• $d->adler32() — Returns adler32 of uncompressed data.
• $d->msg() — Last error message from zlib.
• $d->total_in() — Total bytes input to deflate.
• $d->total_out() — Total bytes output from deflate.
• $d->get_Strategy() — Current deflation strategy.
• $d->get_Level() — Current compression level.
• $d->get_BufSize() — Buffer size used for compression.

🔹 Example

use strict ;
use warnings ;

use Compress::Raw::Zlib ;

binmode STDIN;
binmode STDOUT;
my $x = new Compress::Raw::Zlib::Deflate
   or die "Cannot create a deflation stream\n" ;

my ($output, $status) ;
while (<>)
{
    $status = $x->deflate($_, $output) ;

    $status == Z_OK
        or die "deflation failed\n" ;

    print $output ;
}

$status = $x->flush($output) ;

$status == Z_OK
    or die "deflation failed\n" ;

print $output ;

🔨 Compress::Raw::Zlib::Inflate

This section defines an interface that allows in-memory uncompression using the inflate interface provided by zlib.

🔹 ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] )

Initialises an inflation object. Returns ($i, $status) in list context; $i only in scalar. $status is Z_OK on success.

🔹 Valid Options

• -WindowBits — Similar to deflate: positive for RFC 1950, -MAX_WBITS for raw inflate, WANT_GZIP for gzip, WANT_GZIP_OR_ZLIB for auto-detect. Default: MAX_WBITS.
• -Bufsize — Initial output buffer size. Default: 4096.
• -Dictionary — Default: no dictionary.
• -AppendOutput — If false, truncate output buffer; if true, append. Default: false.
• -CRC32 — Calculate crc32 checksum if true. Retrieve via $i->crc32(). Default: false.
• -ADLER32 — Calculate adler32 checksum if true. Retrieve via $i->adler32(). Default: false.
• -ConsumeInput — If true, remove compressed data from input buffer as inflate progresses. Useful for embedded streams. Default: true.
• -LimitOutput — Limits memory usage of output buffer. Enables ConsumeInput automatically. Default: false.

Example:

my ($i, $status) = new Compress::Raw::Zlib::Inflate( -Bufsize => 300 ) ;

🔹 $status = $i->inflate($input, $output [, $eof])

Inflates $input and writes uncompressed data to $output. Returns Z_OK or Z_STREAM_END. $eof parameter needed for raw deflate streams (RFC 1951) with no trailing data when using zlib < 1.2.0. Ignored for newer zlib.

🔹 $status = $i->inflateSync($input)

Scans for a full flush point in $input. Returns Z_OK if found, removing data up to flush point. Used for recovery from partially corrupt data.

🔹 $status = $i->inflateReset()

Resets inflation object for reuse on multiple streams.

🔹 Other Methods

• $i->dict_adler() — Returns adler32 of dictionary.
• $i->crc32() — Returns crc32 of uncompressed data (if CRC32 option enabled).
• $i->adler32() — Returns adler32 of uncompressed data (if ADLER32 option enabled).
• $i->msg() — Last error message from zlib.
• $i->total_in() — Total bytes compressed input to inflate.
• $i->total_out() — Total bytes uncompressed output from inflate.
• $d->get_BufSize() — Buffer size used for decompression.

🔹 Examples

Basic inflate:

use strict ;
use warnings ;

use Compress::Raw::Zlib;

my $x = new Compress::Raw::Zlib::Inflate()
   or die "Cannot create a inflation stream\n" ;

my $input = '' ;
binmode STDIN;
binmode STDOUT;

my ($output, $status) ;
while (read(STDIN, $input, 4096))
{
    $status = $x->inflate($input, $output) ;

    print $output ;

    last if $status != Z_OK ;
}

die "inflation failed\n"
    unless $status == Z_STREAM_END ;

With LimitOutput:

use strict ;
use warnings ;

use Compress::Raw::Zlib;

my $x = new Compress::Raw::Zlib::Inflate(LimitOutput => 1)
   or die "Cannot create a inflation stream\n" ;

my $input = '' ;
binmode STDIN;
binmode STDOUT;

my ($output, $status) ;

OUTER:
while (read(STDIN, $input, 4096))
{
    do
    {
        $status = $x->inflate($input, $output) ;

        print $output ;

        last OUTER
            unless $status == Z_OK || $status == Z_BUF_ERROR ;
    }
    while ($status == Z_OK && length $input);
}

die "inflation failed\n"
    unless $status == Z_STREAM_END ;

📊 CHECKSUM FUNCTIONS

Two functions are provided by zlib to calculate checksums. The order of parameters is reversed for Perl interface.

$crc = adler32($buffer [,$crc]) ;
$crc = crc32($buffer [,$crc]) ;

If $crc is undef, the crc value is reset. With zlib 1.2.3+, two combine functions are available:

$crc = crc32_combine($crc1, $crc2, $len2);
$adler = adler32_combine($adler1, $adler2, $len2);

🧩 Misc

🔹 my $version = Compress::Raw::Zlib::zlib_version();

Returns the version of the zlib library.

🔹 my $flags = Compress::Raw::Zlib::zlibCompileFlags();

Returns flags indicating compile-time options. See zlib documentation. For zlib <= 1.2.0, returns 0.

⚙️ The LimitOutput option

By default $i->inflate($input, $output) will uncompress all data in $input and write all uncompressed data to $output. This can cause unbounded memory growth. The LimitOutput option limits memory usage by returning Z_BUF_ERROR when output buffer is full. See example above for usage.

📁 ACCESSING ZIP FILES

Use modules like Archive::Zip, Archive::Zip::SimpleZip, IO::Compress::Zip and IO::Uncompress::Unzip for easier .zip handling.

❓ FAQ

🔹 Compatibility with Unix compress/uncompress

This module is not compatible with Unix compress. Use uncompress or gunzip to read compressed files, or compress to write.

🔹 Accessing .tar.Z files

Use uncompress or gunzip with Archive::Tar. Example:

open F, "uncompress -c $filename |";
my $tar = Archive::Tar->new(*F);
...

🔹 Zlib Library Version Support

Requires zlib 1.0.5 or better. Use zlib 1.2.1+ for -Merge option with IO::Compress::Gzip, etc. By default, builds with private copy of zlib 1.2.5.

🔢 CONSTANTS

All zlib constants are automatically imported when using Compress::Raw::Zlib.

🆘 SUPPORT

Send feedback/questions/bug reports to https://github.com/pmqs/Compress-Raw-Zlib/issues (preferred) or https://rt.cpan.org/Public/Dist/Display.html?Name=Compress-Raw-Zlib.

👀 SEE ALSO

Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, IO::Compress::Deflate, IO::Uncompress::Inflate, IO::Compress::RawDeflate, IO::Uncompress::RawInflate, IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress

IO::Compress::FAQ

File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib

For RFC 1950, 1951 and 1952 see http://www.faqs.org/rfcs/rfc1950.html, http://www.faqs.org/rfcs/rfc1951.html and http://www.faqs.org/rfcs/rfc1952.html

The zlib compression library was written by Jean-loup Gailly gzip AT prep.edu and Mark Adler madler AT alumni.edu. Primary site: http://www.zlib.org. gzip: http://www.gzip.org.

✍️ AUTHOR

Paul Marquess, pmqs AT cpan.org.

📜 MODIFICATION HISTORY

See the Changes file.

©️ COPYRIGHT AND LICENSE

Copyright (c) 2005-2021 Paul Marquess. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

📖 NAME 🚀 Quick Reference 📋 SYNOPSIS 📝 DESCRIPTION 📊 CHECKSUM FUNCTIONS 🧩 Misc ⚙️ The LimitOutput option 📁 ACCESSING ZIP FILES ❓ FAQ 🔢 CONSTANTS 🆘 SUPPORT 👀 SEE ALSO ✍️ AUTHOR 📜 MODIFICATION HISTORY ©️ COPYRIGHT AND LICENSE