IO::Compress::Zstd(3)

📦

version 2.217 · 4 versions

2.217 · fedora 44 (latest)
2.101 · epel 9
2.212 · epel 10
2.213 · fedora 43

💖 NAME 💖

okay bestie, welcome to IO::Compress::Zstd(3) — the User Contributed Perl Documentation page for IO::Compress::Zstd. This module is literally here to write zstd files/buffers. 💅✨

✨ SYNOPSIS ✨

use IO::Compress::Zstd qw(zstd $ZstdError) ;

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

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

$ZstdError ;

# 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 zstd compressed data to files or buffer. 🦋

For reading zstd files/buffers, see the companion module IO::Uncompress::UnZstd. 👑

Functional Interface

A top-level function, "zstd", 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::Zstd qw(zstd $ZstdError) ;

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

The functional interface needs Perl5.005 or better. ⭐

zstd $input_filename_or_reference => $output_filename_or_reference [, OPTS]

"zstd" 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

The parameter, $input_filename_or_reference, is used to define the source of the uncompressed data. It can take one of the following forms:

A filename — If the $input_filename_or_reference parameter is a simple scalar, it is assumed to be a filename. This file will be opened for reading and the input data will be read from it. 📂
A filehandle — If the $input_filename_or_reference parameter is a filehandle, the input data will be 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 will be read from $$input_filename_or_reference. ✨
An array reference — If $input_filename_or_reference is an array reference, each element in the array must be a filename. The input data will be read from each file in turn. The complete array will be walked to ensure that it only contains valid filenames before any data is compressed. 🌈
An Input FileGlob string — If $input_filename_or_reference is a string that is delimited by the characters "<" and ">" "zstd" will assume that it is an input fileglob string. The input is the list of files that match the fileglob. See File::GlobMapper for more details. 🧚

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

The `$output_filename_or_reference` parameter

The parameter $output_filename_or_reference is used to control the destination of the compressed data. This parameter can take one of these forms.

A filename — If the $output_filename_or_reference parameter is a simple scalar, it is assumed to be a filename. This file will be opened for writing and the compressed data will be written to it. 📝
A filehandle — If the $output_filename_or_reference parameter is a filehandle, the compressed data will be 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 that is delimited by the characters "<" and ">" "zstd" will assume that it is an output fileglob string. The output is the list of files that match the fileglob. When $output_filename_or_reference is an fileglob string, $input_filename_or_reference must also be a fileglob string. Anything else is an error. See File::GlobMapper for more details. 👑

If the $output_filename_or_reference parameter 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. 🔥

Optional Parameters

The optional parameters for the one-shot function "zstd" 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 "zstd" 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 "zstd" 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 is dependent on the type of output data stream. 📎
- A Buffer — If "Append" is enabled, all compressed data will be append 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 is set to false, it will operate as follows. 🔄

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 that show the capabilities of the module. 🎬

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::Zstd=zstd -e 'zstd \*STDIN => \*STDOUT' >output.zst

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::Zstd=zstd -e 'zstd "-" => "-"' >output.zst

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.zst". 📁

use strict ;
use warnings ;
use IO::Compress::Zstd qw(zstd $ZstdError) ;

my $input = "file1.txt";
zstd $input => "$input.zst"
    or die "zstd failed: $ZstdError\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::Zstd qw(zstd $ZstdError) ;
use IO::File ;

my $input = IO::File->new( "<file1.txt" )
    or die "Cannot open 'file1.txt': $!\n" ;
my $buffer ;
zstd $input => \$buffer
    or die "zstd failed: $ZstdError\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::Zstd qw(zstd $ZstdError) ;

zstd '</my/home/*.txt>' => '<*.zst>'
    or die "zstd failed: $ZstdError\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::Zstd qw(zstd $ZstdError) ;

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

💖 OO Interface 💖

Okay bestie, this is the ✨fancy✨ way to do it — object-oriented, all up in your code, very main character energy.

🎀 Constructor 🎀

Here's the vibe of the constructor for IO::Compress::Zstd:

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

It takes one mandatory parameter, $output (deets below 👇) and zero or more OPTS, which are described over in "Constructor Options".

It hands you back an IO::Compress::Zstd object if it works, and undef if it does NOT. On failure, the variable $ZstdError is gonna be holding an error message for you, so like, read it, it's there to help 🫶

If you're on Perl 5.005 or better, the object $z you get back from IO::Compress::Zstd can be used exactly like an IO::File filehandle. Which means literally all your normal output file operations just work with $z. So to write to a compressed file/buffer you can do either of these:

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

Here's a lil example of the OO interface making an output file myfile.zst and writing some data into it:

my $filename = "myfile.zst";
my $z = IO::Compress::Zstd->new($filename)
    or die "IO::Compress::Zstd failed: $ZstdError\n";

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

Peep the "Examples" section for more, bestie.

The mandatory parameter $output is what controls where the compressed data goes. It can take one of these forms:

A filename — if $output is a simple scalar, it's treated as a filename. That file gets opened for writing and the compressed data goes into it. 🗂️
A filehandle — if $output is a filehandle, the compressed data gets written to it. The string '-' works 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 literally anything else, IO::Compress::Zstd::new will return undef. No cap. 💀

✨ Constructor Options ✨

OPTS is any combination of zero or more of these bad boys:

AutoClose => 0|1 — only valid when $output is a filehandle, iykyk. If you set it and the value is true, $output gets closed once either the close method is called or the IO::Compress::Zstd object gets destroyed. Defaults to 0. 🚪
Append => 0|1 — opens $output in append mode.

How this behaves depends on what kind of $output you got:

A Buffer — if $output is a buffer and Append is on, all the compressed data gets appended to the end of $output. Otherwise $output gets cleared before anything is written to it. 🧹
A Filename — if $output is a filename and Append is on, the file is opened in append mode. Otherwise the contents of the file (if it has any) get truncated before any compressed data is written. ✂️
A Filehandle — if $output is a filehandle, the file pointer gets moved to the end of the file via a call to seek before any compressed data is written. Otherwise the file pointer does NOT move. 📍

Defaults to 0.

Level => number — sets the compression level used. This gets passed to the ZSTD function ZSTD_initCStream. Default is 3. 🎚️
Strict => 0|1 — this is a placeholder option. That's it. That's the whole thing. 🙈

🌸 Examples 🌸

Streaming

This super simple command line example shows off the module's streaming capabilities. The code reads data from STDIN or all the files given on the commandline, compresses it, and writes the compressed data to STDOUT. 🌊

use strict ;
use warnings ;
use IO::Compress::Zstd qw(zstd $ZstdError) ;

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

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

Note the use of "-" meaning "STDOUT". Alternatively you can use "\*STDOUT". 👑

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.zst, you got a few options. 🗃️

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

use strict ;
use warnings ;
use IO::Compress::Zstd qw(zstd $ZstdError) ;

my $input = "file1.txt";
my $z = IO::Compress::Zstd->new("file1.txt.zst")
    or die "IO::Compress::Zstd failed: $ZstdError\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();

👑 Methods 👑

`print`

Usage is:

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

Compresses and outputs the contents of the $data parameter. Behaves exactly like the print built-in. Returns true if it worked. 💖

`printf`

Usage is:

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

Compresses and outputs the contents of the $data parameter. Returns true if it worked. ✨

`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 it didn't work out. 😭

`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 it didn't work out. 😭

`flush`

Usage is:

$z->flush;

Flushes any pending compressed data out to the output file/buffer. 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);

Gives you a sub-set of the seek functionality, with the restriction that it's only legal to seek forward in the output file/buffer. Trying to seek backward is a fatal error, periodt. 🚫

Empty parts of the file/buffer get NULL (0x00) bytes written into them.

The $whence parameter takes one of 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 purely for completeness. It does nothing and it's thriving. 💅

`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)

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 non-zero, it enables flushing after every write/print operation. 🚽

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

Heads up bestie: the special variable $| can NOT be used to set or retrieve the autoflush setting. 🚨

`input_line_number`

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

This method always returns undef when compressing. Always. No exceptions. 🙃

`fileno`

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

If the $z object is associated with a file or a filehandle, fileno returns the underlying file descriptor. Once the close method gets called, fileno returns undef. 🫥

If the $z object is associated with a buffer, this method returns 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 gets automatically invoked if the IO::Compress::Zstd object is destroyed (either explicitly, or because the variable holding the reference to the object went out of scope). The exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In those cases the close method WILL be called automatically, but not until global destruction of all live objects, when the program is terminating. 😵

So if you want your scripts to run on ALL versions of Perl, call close explicitly and don't rely on automatic closing. Fr fr. 🙏

Returns true on success, otherwise 0.

If the AutoClose option was enabled when the IO::Compress::Zstd object was created, and the object is associated with a file, the underlying file also gets closed. 🚪

`newStream([OPTS])`

Usage is:

$z->newStream( [OPTS] )

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

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

Check the "Constructor Options" section for more details.

🌈 Importing 🌈

No symbolic constants are required by IO::Compress::Zstd at present.

:all — imports zstd and $ZstdError. Same as doing this:

use IO::Compress::Zstd qw(zstd $ZstdError) ;

🦋 EXAMPLES 🦋

(Yeah bestie, this heading is just vibing here on its own, the examples live up in the OO Interface section. 💀)

🫶 SUPPORT 🫶

General feedback, questions and bug reports should go to <https://github.com/pmqs/IO-Compress-Zstd/issues> (preferred 💖) or <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress-Zstd>.

⭐ 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::Uncompress::UnZstd, IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress

IO::Compress::FAQ

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

💜 AUTHOR 💜

This module was written by Paul Marquess, pmqs@cpan.org. King behaviour, honestly. 👑

🎀 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.

And that's a wrap, bestie!! 🎉💖✨ This whole thing was perl v5.42.0, dated 2026-02-03, and it's the manual page for IO::Compress::Zstd(3). Go compress something iconic. 🦋👑💅

📦 where this page comes from

fedora 44: perl-IO-Compress-Zstd 2.217-1.fc44 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

IO::Compress::Zstd(3)

💖 NAME 💖

✨ SYNOPSIS ✨

🌸 DESCRIPTION 🌸

Functional Interface

zstd $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

💖 OO Interface 💖

🎀 Constructor 🎀

✨ Constructor Options ✨

🌸 Examples 🌸

👑 Methods 👑

print

printf

syswrite

write

flush

tell

eof

seek

binmode

opened

autoflush

input_line_number

fileno

close

newStream([OPTS])

🌈 Importing 🌈

🦋 EXAMPLES 🦋

🫶 SUPPORT 🫶

⭐ SEE ALSO ⭐

💜 AUTHOR 💜

🎀 MODIFICATION HISTORY 🎀

🌸 COPYRIGHT AND LICENSE 🌸

The `$input_filename_or_reference` parameter

The `$output_filename_or_reference` parameter

`print`

`printf`

`syswrite`

`write`

`flush`

`tell`

`eof`

`seek`

`binmode`

`opened`

`autoflush`

`input_line_number`

`fileno`

`close`

`newStream([OPTS])`