info > IO::Compress::Deflate

man perldoc info pydoc3 ri search

📝 NAME

IO::Compress::Deflate - Write RFC 1950 files/buffers

🚀 Quick Reference

Use Case	Command	Description
📁 Compress a file	deflate $input => $output	Compress a single file to a new file
📥 Compress from STDIN	deflate \*STDIN => \*STDOUT	Streaming compression from stdin to stdout
💾 Compress to buffer	deflate $input => \$buffer	Compress data into an in‑memory scalar
📂 Compress multiple files	deflate '</my/home/*.txt>' => '<*.1950>'	Glob‑based batch compression
🔄 OO streaming	my $z = IO::Compress::Deflate->new($output, OPTS)	Create an object for incremental compression
🔗 Append to existing stream	Merge => 1	Merge new data into an existing RFC 1950 stream

📖 SYNOPSIS

use IO::Compress::Deflate qw(deflate $DeflateError) ;

my $status = deflate $input => $output [,OPTS]
    or die "deflate failed: $DeflateError\n";

my $z = IO::Compress::Deflate->new( $output [,OPTS] )
    or die "deflate failed: $DeflateError\n";

$z->print($string);
$z->printf($format, $string);
$z->write($string);
$z->syswrite($string [, $length, $offset]);
$z->flush();
$z->tell();
$z->eof();
$z->seek($position, $whence);
$z->binmode();
$z->fileno();
$z->opened();
$z->autoflush();
$z->input_line_number();
$z->newStream( [OPTS] );

$z->deflateParams();

$z->close() ;

$DeflateError ;

# IO::File mode

print $z $string;
printf $z $format, $string;
tell $z
eof $z
seek $z, $position, $whence
binmode $z
fileno $z
close $z ;

📘 DESCRIPTION

This module provides a Perl interface that allows writing compressed data to files or buffer as defined in RFC 1950.

For reading RFC 1950 files/buffers, see the companion module IO::Uncompress::Inflate.

🔧 Functional Interface

A top-level function, deflate, is provided to carry out "one-shot" compression between buffers and/or files. For finer control over the compression process, see the OO Interface section.

use IO::Compress::Deflate qw(deflate $DeflateError) ;

deflate $input_filename_or_reference => $output_filename_or_reference [,OPTS]
    or die "deflate failed: $DeflateError\n";

The functional interface needs Perl5.005 or better.

🔧 deflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]

deflate expects at least two parameters, $input_filename_or_reference and $output_filename_or_reference and zero or more optional parameters (see Optional Parameters)

📥 The $input_filename_or_reference parameter

It can take one of the following forms:

• 📄 A filename – simple scalar assumed to be a filename, opened for reading.
• 📂 A filehandle – input data read from it; '-' alias for STDIN.
• 📦 A scalar reference – input data read from $$input_filename_or_reference.
• 📚 An array reference – each element must be a filename; read from each file in turn.
• 🔍 An Input FileGlob string – string delimited by < and >; input is the list of files matching the fileglob. See File::GlobMapper.

If any other type, undef is returned.

📤 The $output_filename_or_reference parameter

It can take one of these forms:

• 📄 A filename – simple scalar assumed to be a filename, opened for writing.
• 📂 A filehandle – compressed data written to it; '-' alias for STDOUT.
• 📦 A scalar reference – compressed data stored in $$output_filename_or_reference.
• 📚 An Array Reference – compressed data pushed onto the array.
• 🔍 An Output FileGlob – string delimited by < and >; output is the list of files matching the fileglob. $input_filename_or_reference must also be a fileglob string. See File::GlobMapper.

If any other type, undef is returned.

📝 Notes

When $input_filename_or_reference maps to multiple files/buffers and $output_filename_or_reference is a single file/buffer, the input files/buffers will be stored in $output_filename_or_reference as a concatenated series of compressed data streams.

⚙️ Optional Parameters

The optional parameters for the one-shot function deflate are (for the most part) identical to those used with the OO interface defined in the Constructor Options section. The exceptions are listed below:

• AutoClose => 0|1 – Closes input/output filehandles after completion (default 0).
• BinModeIn => 0|1 – Now a no-op; all files read in binmode.
• Append => 0|1 – Controls behaviour for buffers, filenames, and filehandles (default 0). See detailed explanation below.

Append behaviour:

• 🔹 Buffer: If enabled, compressed data appended to end of buffer; otherwise buffer cleared.
• 🔹 Filename: If enabled, file opened in append mode; otherwise truncated.
• 🔹 Filehandle: If enabled, file pointer seeks to end; otherwise not moved.

Defaults to 0.

💡 Examples

Streaming (STDIN to STDOUT):

$ echo hello world | perl -MIO::Compress::Deflate=deflate -e 'deflate \*STDIN => \*STDOUT' >output.1950

Using the special filename '-':

$ echo hello world | perl -MIO::Compress::Deflate=deflate -e 'deflate "-" => "-"' >output.1950

Compressing a file from the filesystem:

use strict ;
use warnings ;
use IO::Compress::Deflate qw(deflate $DeflateError) ;

my $input = "file1.txt";
deflate $input => "$input.1950"
    or die "deflate failed: $DeflateError\n";

Reading from a filehandle and writing to an in-memory buffer:

use strict ;
use warnings ;
use IO::Compress::Deflate qw(deflate $DeflateError) ;
use IO::File ;

my $input = IO::File->new( "<file1.txt" )
    or die "Cannot open 'file1.txt': $!\n" ;
my $buffer ;
deflate $input => \$buffer
    or die "deflate failed: $DeflateError\n";

Compressing multiple files with glob:

use strict ;
use warnings ;
use IO::Compress::Deflate qw(deflate $DeflateError) ;

deflate '</my/home/*.txt>' => '<*.1950>'
    or die "deflate failed: $DeflateError\n";

One at a time:

use strict ;
use warnings ;
use IO::Compress::Deflate qw(deflate $DeflateError) ;

for my $input ( glob "/my/home/*.txt" )
{
    my $output = "$input.1950" ;
    deflate $input => $output
        or die "Error compressing '$input': $DeflateError\n";
}

🛠️ OO Interface

🏗️ Constructor

my $z = IO::Compress::Deflate->new( $output [,OPTS] )
    or die "IO::Compress::Deflate failed: $DeflateError\n";

Returns an IO::Compress::Deflate object on success and undef on failure. The variable $DeflateError will contain an error message on failure.

If you are running Perl 5.005 or better, the object $z can be used exactly like an IO::File filehandle. For example:

$z->print("hello world\n");
print $z "hello world\n";

The mandatory parameter $output controls the destination of the compressed data and can take one of these forms:

• 📄 A filename – opened for writing.
• 📂 A filehandle – compressed data written to it; '-' alias for STDOUT.
• 📦 A scalar reference – compressed data stored in $$output.

If any other type, undef is returned.

⚙️ Constructor Options

OPTS is any combination of zero or more of the following options:

• AutoClose => 0|1 – Closes $output when close is called or object is destroyed (default 0).
• Append => 0|1 – Opens $output in append mode (default 0). Behaviour depends on $output type:
  • 🔹 Buffer: appended to end; otherwise cleared.
  • 🔹 Filename: opened in append mode; otherwise truncated.
  • 🔹 Filehandle: file pointer seeks to end; otherwise not moved.
• Merge => 0|1 – Compress input data and append to an existing RFC 1950 data stream in $output. Requires zlib 1.2.1+ and seekable output (default 0).
• -Level – Compression level (0-9) or symbolic constant: Z_NO_COMPRESSION, Z_BEST_SPEED, Z_BEST_COMPRESSION, Z_DEFAULT_COMPRESSION (default). Not imported by default; use :level or :all.
• -Strategy – Tuning strategy constant: Z_FILTERED, Z_HUFFMAN_ONLY, Z_RLE, Z_FIXED, Z_DEFAULT_STRATEGY (default). Not imported by default; use :strategy or :all.
• Strict => 0|1 – Placeholder option.

Example importing constants:

use IO::Compress::Deflate qw(:strategy);
use IO::Compress::Deflate qw(:constants);
use IO::Compress::Deflate qw(:all);

📋 Methods

print

$z->print($data)
print $z $data

Compresses and outputs the contents of $data. Returns true if successful.

printf

$z->printf($format, $data)
printf $z $format, $data

Compresses and outputs formatted data. Returns true if successful.

syswrite

$z->syswrite $data
$z->syswrite $data, $length
$z->syswrite $data, $length, $offset

Compresses and outputs data. Returns the number of uncompressed bytes written, or undef if unsuccessful.

write

$z->write $data
$z->write $data, $length
$z->write $data, $length, $offset

Compresses and outputs data. Returns the number of uncompressed bytes written, or undef if unsuccessful.

flush

$z->flush;
$z->flush($flush_type);

Flushes pending compressed data. Optional $flush_type (default Z_FINISH). Valid values: Z_NO_FLUSH, Z_SYNC_FLUSH, Z_FULL_FLUSH, Z_BLOCK. Overuse degrades compression. Returns true on success.

tell

$z->tell()
tell $z

Returns the uncompressed file offset.

eof

$z->eof();
eof($z);

Returns true if the close method has been called.

seek

$z->seek($position, $whence);
seek($z, $position, $whence);

Provides a subset of seek – only forward seeking allowed. Empty parts filled with NULL bytes. $whence can be SEEK_SET, SEEK_CUR, or SEEK_END. Returns 1 on success, 0 on failure.

binmode

$z->binmode
binmode $z ;

No-op for completeness.

opened

$z->opened()

Returns true if the object currently refers to an opened file/buffer.

autoflush

my $prev = $z->autoflush()
my $prev = $z->autoflush(EXPR)

Gets or sets autoflush for the underlying filehandle. If $z is associated with a buffer, returns undef.

input_line_number

$z->input_line_number()
$z->input_line_number(EXPR)

Always returns undef when compressing.

fileno

$z->fileno()
fileno($z)

Returns the underlying file descriptor if associated with a file/filehandle; undef for buffer or after close.

close

$z->close() ;
close $z ;

Flushes pending data and closes the output file/buffer. Returns true on success, otherwise 0. If AutoClose was enabled, the underlying file is also closed.

newStream([OPTS])

$z->newStream( [OPTS] )

Closes the current compressed data stream and starts a new one. OPTS can be any constructor options.

deflateParams

$z->deflateParams

TODO

📦 Importing

A number of symbolic constants are required by some methods. None are imported by default.

• :all – Imports deflate, $DeflateError and all symbolic constants (same as :constants).
• :constants – Imports all symbolic constants (same as :flush :level :strategy).
• :flush – Z_NO_FLUSH, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, Z_FULL_FLUSH, Z_FINISH, Z_BLOCK.
• :level – Z_NO_COMPRESSION, Z_BEST_SPEED, Z_BEST_COMPRESSION, Z_DEFAULT_COMPRESSION.
• :strategy – Z_FILTERED, Z_HUFFMAN_ONLY, Z_RLE, Z_FIXED, Z_DEFAULT_STRATEGY.

📚 EXAMPLES

🌐 Apache::GZip Revisited

See IO::Compress::FAQ

🌐 Working with Net::FTP

See IO::Compress::FAQ

🆘 SUPPORT

General feedback/questions/bug reports should be sent to https://github.com/pmqs/IO-Compress/issues (preferred) or https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress.

📎 SEE ALSO

Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, 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.

The primary site for the zlib compression library is http://www.zlib.org.

The primary site for gzip is http://www.gzip.org.

👤 AUTHOR

This module was written by 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.

perl v5.34.0 2026-06-23 IO::Compress::Deflate(3perl)

📝 NAME 🚀 Quick Reference 📖 SYNOPSIS 📘 DESCRIPTION 📚 EXAMPLES 🆘 SUPPORT 📎 SEE ALSO 👤 AUTHOR 📜 MODIFICATION HISTORY ©️ COPYRIGHT AND LICENSE