IO::Co...eflate(3perl)

📦

version 5.44.0 · 14 versions

✨ IO::Compress::RawDeflate ✨

Perl Programmers Reference Guide · the page header yells IO::Co...eflate(3perl) at you and honestly bestie it's just vibes from there.

👑 NAME 👑

IO::Compress::RawDeflate — write RFC 1951 files/buffers 💅

🎀 SYNOPSIS 🎀

use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;

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

my $z = IO::Compress::RawDeflate->new( $output [,OPTS] )
    or die "rawdeflate failed: $RawDeflateError\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() ;

$RawDeflateError ;

# 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 🌸

Okay so this module hands you a Perl interface that lets you write compressed data to files or buffers, exactly as defined in RFC 1951. ✨

⚠️ Real talk though — RFC 1951 data is not a good choice of compression format to use in isolation, especially if you want to auto-detect it. Like, it's giving "great ingredient, terrible standalone meal". 😭

For reading RFC 1951 files/buffers, go check out its companion module IO::Uncompress::RawInflate. 🦋

💜 Functional Interface

There's a top-level function, rawdeflate, that does "one-shot" compression between buffers and/or files. It's the quick-and-easy path 🫶 — but if you want finer control over the compression process, you want the "OO Interface" section instead.

use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;

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

The functional interface needs Perl5.005 or better. 🧚

⭐ `rawdeflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]`

"rawdeflate" expects at least two parameters — $input_filename_or_reference and $output_filename_or_reference — plus zero or more optional parameters (peep "Optional Parameters" 💕).

🌈 The `$input_filename_or_reference` parameter

This parameter is what defines the source of the uncompressed data. It can take one of these forms:

A filename — if $input_filename_or_reference is a simple scalar, it's assumed to be a filename. That file gets opened for reading and the input data is read from it. 📂
A filehandle — if $input_filename_or_reference is a filehandle, the input data is read from it. The string '-' can be used as an alias for standard input. 🌀
A scalar reference — if $input_filename_or_reference is a scalar reference, the input data is read from $$input_filename_or_reference.
An array reference — if $input_filename_or_reference is an array reference, every element in the array must be a filename. The input data is read from each file in turn. The complete array will be walked to make sure it only contains valid filenames before any data is compressed. 👀
An Input FileGlob string — if $input_filename_or_reference is a string delimited by the characters "<" and ">", "rawdeflate" will assume it's an input fileglob string. The input is the list of files that match the fileglob. See File::GlobMapper for more details. 🦋

If $input_filename_or_reference is any other type, "undef" will be returned. 💀

🌟 The `$output_filename_or_reference` parameter

This parameter controls where the compressed data goes. It can take one of these forms:

A filename — if $output_filename_or_reference is a simple scalar, it's assumed to be a filename. That file gets opened for writing and the compressed data is written to it. 📝
A filehandle — if $output_filename_or_reference is a filehandle, the compressed data is written to it. The string '-' can be used as an alias for standard output. 🌀
A scalar reference — if $output_filename_or_reference is a scalar reference, the compressed data will be stored in $$output_filename_or_reference.
An Array Reference — if $output_filename_or_reference is an array reference, the compressed data will be pushed onto the array. 🧺
An Output FileGlob — if $output_filename_or_reference is a string delimited by the characters "<" and ">", "rawdeflate" will assume it's an output fileglob string. The output is the list of files that match the fileglob. When $output_filename_or_reference is a fileglob string, $input_filename_or_reference must also be a fileglob string. Anything else is an error. See File::GlobMapper for more details.

If $output_filename_or_reference is any other type, "undef" will be 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. Stack 'em up bestie 💅

💖 Optional Parameters

The optional parameters for the one-shot function "rawdeflate" 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" — this option applies to any input or output data streams to "rawdeflate" that are filehandles. If "AutoClose" is specified and the value is true, it will result in all input and/or output filehandles being closed once "rawdeflate" has completed. This parameter defaults to 0. 🔒
"BinModeIn => 0|1" — this option is now a no-op. All files will be read in binmode. 🙈
"Append => 0|1" — the behaviour of this option depends on the type of output data stream. Check it:
- A Buffer — if "Append" is enabled, all compressed data will be appended to the end of the output buffer. Otherwise the output buffer will be cleared before any compressed data is written to it.
- A Filename — if "Append" is enabled, the file will be opened in append mode. Otherwise the contents of the file, if any, will be truncated before any compressed data is written to it.
- A Filehandle — if "Append" is enabled, the filehandle will be positioned to the end of the file via a call to "seek" before any compressed data is written to it. Otherwise the file pointer will not be moved.

When "Append" is specified and set to true, it will append all compressed data to the output data stream. So when the output is a filehandle it will carry out a seek to the eof before writing any compressed data. If the output is a filename, it will be opened for appending. If the output is a buffer, all compressed data will be appended to the existing buffer. ✨

Conversely, when "Append" is not specified, or it is present and set to false, it operates like this: when the output is a filename, it will truncate the contents of the file before writing any compressed data. If the output is a filehandle its position will not be changed. If the output is a buffer, it will be wiped before any compressed data is output. Defaults to 0. 🧼

🎀 Oneshot Examples

Here are a few examples showing off what the module can do 💅

🌊 Streaming

This very simple command line example demonstrates the streaming capabilities of the module. The code reads data from STDIN, compresses it, and writes the compressed data to STDOUT.

$ echo hello world | perl -MIO::Compress::RawDeflate=rawdeflate -e 'rawdeflate \*STDIN => \*STDOUT' >output.1951

The special filename "-" can be used as a standin for both "\*STDIN" and "\*STDOUT", so the above can be rewritten as

$ echo hello world | perl -MIO::Compress::RawDeflate=rawdeflate -e 'rawdeflate "-" => "-"' >output.1951

📂 Compressing a file from the filesystem

To read the contents of the file "file1.txt" and write the compressed data to the file "file1.txt.1951".

use strict ;
use warnings ;
use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;

my $input = "file1.txt";
rawdeflate $input => "$input.1951"
    or die "rawdeflate failed: $RawDeflateError\n";

🫶 Reading from a Filehandle and writing to an in-memory buffer

To read from an existing Perl filehandle, $input, and write the compressed data to a buffer, $buffer.

use strict ;
use warnings ;
use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
use IO::File ;

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

🦋 Compressing multiple files

To compress all files in the directory "/my/home" that match "*.txt" and store the compressed data in the same directory

use strict ;
use warnings ;
use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;

rawdeflate '</my/home/*.txt>' => '<*.1951>'
    or die "rawdeflate failed: $RawDeflateError\n";

and if you want to compress each file one at a time, this will do the trick 😌

use strict ;
use warnings ;
use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;

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

…and that's where part 1 leaves us bestie, more incoming 💖

💅 OO INTERFACE 💅

okay bestie, this is the glow-up version of the interface — objects, methods, the whole ~main character~ situation. let's go 🫶

✨ Constructor ✨

here's the format of the constructor for IO::Compress::RawDeflate, in all its glory:

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

so the constructor takes one mandatory parameter, $output (we'll define it below, don't worry), plus zero or more OPTS — and those live in "Constructor Options" 👑

it returns an IO::Compress::RawDeflate object on success, and undef on failure. and if it fails? the variable $RawDeflateError will be holding the error message, like a little note passed in class 😭

here's the cute part: if you're running Perl 5.005 or better, the object $z that you get back from IO::Compress::RawDeflate can be used exactly like an IO::File filehandle. literally every normal output file operation works with $z. so if you wanna write to a compressed file/buffer you can do either of these:

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

below is a simple example of using the OO interface to create an output file myfile.1951 and write some data to it 💖

my $filename = "myfile.1951";
my $z = IO::Compress::RawDeflate->new($filename)
    or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";

$z->print("abcde");
$z->close();

see the "Examples" section for more ✨

so the mandatory parameter $output — that's the thing that controls where your compressed data ends up. and it can take one of these forms:

A filename — if $output is a simple scalar, it's assumed to be a filename. that file gets opened for writing, and the compressed data gets written to it. simple as 🎀
A filehandle — if $output is a filehandle, the compressed data goes to it. and the string '-' can be used as an alias for standard output 👑
A scalar reference — if $output is a scalar reference, the compressed data gets stored in $$output ✨

if $output is any other type, IO::Compress::RawDeflate::new will return undef. so like. don't do that 💀

🎀 Constructor Options 🎀

OPTS is any combination of zero or more of these options, bestie:

AutoClose => 0|1 — this one's only valid when the $output parameter is a filehandle. if you specify it and the value is true, then $output gets closed once either the close method is called or the IO::Compress::RawDeflate object gets destroyed 💅 defaults to 0.
Append => 0|1 — opens $output in append mode. but the behaviour depends on what type $output actually is:
- A Buffer — if $output is a buffer and Append is enabled, all the compressed data gets appended to the end of $output. otherwise $output is cleared before any data is written to it.
- A Filename — if $output is a filename and Append is enabled, the file gets opened in append mode. otherwise the contents of the file (if there were any) get truncated before any compressed data is written to it.
- A Filehandle — if $output is a filehandle, the file pointer gets positioned to the end of the file via a call to seek before any compressed data is written to it. otherwise the file pointer isn't moved.

defaults to 0.

Merge => 0|1 — this option is used to compress input data and append it onto an existing compressed data stream in $output. the end result is a single compressed data stream stored in $output 🦋

it is a fatal error to attempt to use this option when $output isn't an RFC 1951 data stream. like, it will not go well 😭

and there are a number of other limitations with the Merge option too:

this module needs to have been built with zlib 1.2.1 or better for it to work. a fatal error gets thrown if Merge is used with an older version of zlib.
if $output is a file or a filehandle, it must be seekable.

defaults to 0.

-Level — defines the compression level that zlib uses. the value should either be a number between 0 and 9 (0 means no compression, and 9 is maximum compression, no cap), or one of the symbolic constants defined below:

Z_NO_COMPRESSION
Z_BEST_SPEED
Z_BEST_COMPRESSION
Z_DEFAULT_COMPRESSION

the default is Z_DEFAULT_COMPRESSION ✨

📌 note: these constants are not imported by IO::Compress::RawDeflate by default. so if you want them, you go get them: use IO::Compress::RawDeflate qw(:strategy); use IO::Compress::RawDeflate qw(:constants); use IO::Compress::RawDeflate qw(:all);

-Strategy — defines the strategy used to tune the compression. use one of the symbolic constants defined below:

Z_FILTERED
Z_HUFFMAN_ONLY
Z_RLE
Z_FIXED
Z_DEFAULT_STRATEGY

the default is Z_DEFAULT_STRATEGY.

Strict => 0|1 — this is a placeholder option. that's it. that's the whole vibe. it's giving "reserved for future drama" 🤡

🌸 Examples 🌸

🦋 Streaming

this very simple command line example demonstrates the streaming capabilities of the module. the code reads data from STDIN (or from all the files given on the commandline), compresses it, and writes the compressed data to STDOUT 💖

use strict ;
use warnings ;
use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;

my $z = IO::Compress::RawDeflate->new("-", Stream => 1)
    or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";

while (<>) {
    $z->print("abcde");
}
$z->close();

💡 note the use of "-" to mean "STDOUT". or alternatively you can use "\*STDOUT" — either one works, bestie 🫶

🎀 Compressing a file from the filesystem

to read the contents of the file file1.txt and write the compressed data to the file file1.txt.1951, there are a few options 👑

start by creating the compression object and opening the input file:

use strict ;
use warnings ;
use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;

my $input = "file1.txt";
my $z = IO::Compress::RawDeflate->new("file1.txt.1951")
    or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";

# open the input file
open my $fh, "<", "file1.txt"
    or die "Cannot open file1.txt: $!\n";

# loop through the input file & write to the compressed file
while (<$fh>) {
    $z->print($_);
}

# not forgetting to close the compressed file
$z->close();

and that's the whole flow — open, loop, print, close. iconic, no notes ✨

✨ Methods ✨

okay bestie, this is the part where the object actually does things. all the verbs. let's go 💅

💌 print

Usage is:

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

Compresses and outputs the contents of the $data parameter. This has the same behaviour as the "print" built-in.

Returns true if successful. slay ✨

💌 printf

Usage is:

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

Compresses and outputs the contents of the $data parameter.

Returns true if successful.

💌 syswrite

Usage is:

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

Compresses and outputs the contents of the $data parameter.

Returns the number of uncompressed bytes written, or "undef" if unsuccessful. not the vibe, but okay 😭

💌 write

Usage is:

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

Compresses and outputs the contents of the $data parameter.

Returns the number of uncompressed bytes written, or "undef" if unsuccessful.

🌊 flush

Usage is:

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

Flushes any pending compressed data to the output file/buffer. get it out of there 🫶

This method takes an optional parameter, $flush_type, that controls how the flushing will be carried out. By default the $flush_type used is "Z_FINISH". Other valid values for $flush_type are "Z_NO_FLUSH", "Z_SYNC_FLUSH", "Z_FULL_FLUSH" and "Z_BLOCK". It is strongly recommended that you only set the "flush_type" parameter if you fully understand the implications of what it does — overuse of "flush" can seriously degrade the level of compression achieved. See the "zlib" documentation for details.

Returns true on success.

📍 tell

Usage is:

$z->tell()
tell $z

Returns the uncompressed file offset.

🏁 eof

Usage is:

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

Returns true if the "close" method has been called.

🕹️ seek

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

Provides a sub-set of the "seek" functionality, with the restriction that it is only legal to seek forward in the output file/buffer. It is a fatal error to attempt to seek backward. no take-backsies, bestie 💀

Empty parts of the file/buffer will have NULL (0x00) bytes written to them.

The $whence parameter takes one the usual values, namely SEEK_SET, SEEK_CUR or SEEK_END.

Returns 1 on success, 0 on failure.

🫧 binmode

Usage is:

$z->binmode
binmode $z ;

This is a noop provided for completeness. it literally does nothing and that's its whole job ✨

👀 opened

$z->opened()

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

🚿 autoflush

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

If the $z object is associated with a file or a filehandle, this method returns the current autoflush setting for the underlying filehandle. If "EXPR" is present, and is non-zero, it will enable flushing after every write/print operation.

If $z is associated with a buffer, this method has no effect and always returns "undef".

⚠️ heads up: the special variable $| cannot be used to set or retrieve the autoflush setting. iykyk.

🔢 input_line_number

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

This method always returns "undef" when compressing. it's giving nothing and it knows it 😭

🎟️ fileno

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

If the $z object is associated with a file or a filehandle, "fileno" will return the underlying file descriptor. Once the "close" method is called "fileno" will return "undef".

If the $z object is associated with a buffer, this method will return "undef".

🔒 close

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

Flushes any pending compressed data and then closes the output file/buffer.

For most versions of Perl this method will be automatically invoked if the IO::Compress::RawDeflate object is destroyed (either explicitly or by the variable with the reference to the object going out of scope). The exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these cases, the "close" method will be called automatically, but not until global destruction of all live objects when the program is terminating.

Therefore, if you want your scripts to be able to run on all versions of Perl, you should call "close" explicitly and not rely on automatic closing. do it yourself, main character energy 👑

Returns true on success, otherwise 0.

If the "AutoClose" option has been enabled when the IO::Compress::RawDeflate object was created, and the object is associated with a file, the underlying file will also be closed.

🌀 newStream([OPTS])

Usage is:

$z->newStream( [OPTS] )

Closes the current compressed data stream and starts a new one.

OPTS consists of any of the options that are available when creating the $z object.

See the "Constructor Options" section for more details.

🛠️ deflateParams

Usage is:

$z->deflateParams

TODO 😭 (yes that's really all it says, i'm not making it up)

🧚 Importing 🧚

A number of symbolic constants are required by some methods in "IO::Compress::RawDeflate". None are imported by default. so you gotta ask, bestie 🎀

:all — Imports "rawdeflate", $RawDeflateError and all symbolic constants that can be used by "IO::Compress::RawDeflate". Same as doing this:

use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;

:constants — Import all symbolic constants. Same as doing this:

use IO::Compress::RawDeflate qw(:flush :level :strategy) ;

:flush — These symbolic constants are used by the "flush" method.

Z_NO_FLUSH
Z_PARTIAL_FLUSH
Z_SYNC_FLUSH
Z_FULL_FLUSH
Z_FINISH
Z_BLOCK

:level — These symbolic constants are used by the "Level" option in the constructor.

Z_NO_COMPRESSION
Z_BEST_SPEED
Z_BEST_COMPRESSION
Z_DEFAULT_COMPRESSION

:strategy — These symbolic constants are used by the "Strategy" option in the constructor.

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>. they wanna hear from you fr fr 💖

👑 SEE ALSO 👑

the whole squad, no cap:

Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
IO::Compress::Deflate, IO::Uncompress::Inflate,
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 <https://datatracker.ietf.org/doc/html/rfc1950>, <https://datatracker.ietf.org/doc/html/rfc1951> and <https://datatracker.ietf.org/doc/html/rfc1952>

The zlib compression library was written by Jean-loup Gailly "gzip@prep.ai.mit.edu" and Mark Adler "madler@alumni.caltech.edu". absolute legends 🫡

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

The primary site for the zlib-ng compression library is <https://github.com/zlib-ng/zlib-ng>.

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

✍️ AUTHOR ✍️

This module was written by Paul Marquess, "pmqs@cpan.org".

📜 MODIFICATION HISTORY 📜

See the Changes file.

💜 COPYRIGHT AND LICENSE 💜

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

aaaand that's the whole page bestie, we made it to the end 🎉🦋 this one came from perl v5.44.0, dated 2026-10-17, and it's the IO::Co...eflate(3perl) page. go compress something iconic 💖✨

📦 where this page comes from

arch rolling: perl 5.44.0-1 · Artistic-1.0-Perl AND GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

IO::Co...eflate(3perl)

✨ IO::Compress::RawDeflate ✨

👑 NAME 👑

🎀 SYNOPSIS 🎀

🌸 DESCRIPTION 🌸

💜 Functional Interface

⭐ rawdeflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]

🌈 The $input_filename_or_reference parameter

🌟 The $output_filename_or_reference parameter

🍓 Notes

💖 Optional Parameters

🎀 Oneshot Examples

🌊 Streaming

📂 Compressing a file from the filesystem

🫶 Reading from a Filehandle and writing to an in-memory buffer

🦋 Compressing multiple files

💅 OO INTERFACE 💅

✨ Constructor ✨

🎀 Constructor Options 🎀

🌸 Examples 🌸

🦋 Streaming

🎀 Compressing a file from the filesystem

✨ Methods ✨

💌 print

💌 printf

💌 syswrite

💌 write

🌊 flush

📍 tell

🏁 eof

🕹️ seek

🫧 binmode

👀 opened

🚿 autoflush

🔢 input_line_number

🎟️ fileno

🔒 close

🌀 newStream([OPTS])

🛠️ deflateParams

🧚 Importing 🧚

🌈 EXAMPLES 🌈

🗜️ Apache::GZip Revisited

🌐 Working with Net::FTP

🫶 SUPPORT 🫶

👑 SEE ALSO 👑

✍️ AUTHOR ✍️

📜 MODIFICATION HISTORY 📜

💜 COPYRIGHT AND LICENSE 💜

⭐ `rawdeflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]`

🌈 The `$input_filename_or_reference` parameter

🌟 The `$output_filename_or_reference` parameter