IO::Unc...:UnZstd(3)

📦

version 2.217 · 4 versions

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

💖 IO::Uncompress::UnZstd 💖

okay bestie, welcome to the IO::Uncompress::UnZstd(3) page — yeah it's one of those long User Contributed Perl Documentation ones, and the title up top got chopped to IO::Unc...:UnZstd(3) but you and me both know the real name. she's giving compression, but make it un. let's go 🫶

✨ NAME ✨

IO::Uncompress::UnZstd — read zstd files/buffers. that's it, that's the whole job. she reads zstd, she does not write it, no cap 💅

🌸 SYNOPSIS 🌸

    use IO::Uncompress::UnZstd qw(unzstd $UnZstdError) ;

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

    my $z = IO::Uncompress::UnZstd->new( $input [OPTS] )
        or die "unzstd failed: $UnZstdError\n";

    $status = $z->read($buffer)
    $status = $z->read($buffer, $length)
    $status = $z->read($buffer, $length, $offset)
    $line = $z->getline()
    $char = $z->getc()
    $char = $z->ungetc()
    $char = $z->opened()

    $data = $z->trailingData()
    $status = $z->nextStream()
    $data = $z->getHeaderInfo()
    $z->tell()
    $z->seek($position, $whence)
    $z->binmode()
    $z->fileno()
    $z->eof()
    $z->close()

    $UnZstdError ;

    # IO::File mode

    <$z>
    read($z, $buffer);
    read($z, $buffer, $length);
    read($z, $buffer, $length, $offset);
    tell($z)
    seek($z, $position, $whence)
    binmode($z)
    fileno($z)
    eof($z)
    close($z)

look at all those methods. she's versatile. 💖

🦋 DESCRIPTION 🦋

this module hands you a Perl interface so you can read zstd files and buffers. reading only. she's not writing anything, she's just here to unzip and unbothered ✨

want to go the other way and actually write zstd files/buffers? that's her companion module's whole thing: IO::Compress::Zstd.

🌈 Functional Interface 🌈

there's a top-level function called unzstd that does the "one-shot" thing — straight-up uncompression between buffers and/or files, no fuss, no ceremony. but if you want finer control over the uncompression process (main character energy, doing it yourself), go read the "OO Interface" section instead.

    use IO::Uncompress::UnZstd qw(unzstd $UnZstdError) ;

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

heads up: the functional interface needs Perl5.005 or better. yes really. she's been around.

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

unzstd wants at least two parameters — $input_filename_or_reference and $output_filename_or_reference — plus zero or more optional ones (peep "Optional Parameters" for those).

💜 The `$input_filename_or_reference` parameter

this one decides where the compressed data comes from. she's flexible, she accepts:

A filename — if $input_filename_or_reference is a simple scalar, it gets treated as a filename. the file gets opened for reading and the input data gets read out of it.
A filehandle — if $input_filename_or_reference is a filehandle, the input data gets read from it. and the string '-' works as an alias for standard input. iconic.
A scalar reference — if $input_filename_or_reference is a scalar reference, the input data gets read from $$input_filename_or_reference.
An array reference — if $input_filename_or_reference is an array reference, every element in the array has to be a filename. the input data gets read from each file in turn. and the complete array gets walked first to make sure it only contains valid filenames before any data is uncompressed. she checks her receipts 💅
An Input FileGlob string — if $input_filename_or_reference is a string wrapped in the characters "<" and ">", unzstd assumes it's an input fileglob string. the input is the list of files matching that fileglob. (see File::GlobMapper for the details.)

if $input_filename_or_reference is literally any other type, undef gets returned. that's the vibe check failing, sorry bestie.

💙 The `$output_filename_or_reference` parameter

this one controls where the uncompressed data goes. options are:

A filename — if $output_filename_or_reference is a simple scalar, it's treated as a filename. it gets opened for writing and the uncompressed data gets written into it.
A filehandle — if $output_filename_or_reference is a filehandle, the uncompressed data gets written to it. the string '-' works as an alias for standard output.
A scalar reference — if $output_filename_or_reference is a scalar reference, the uncompressed data gets stored in $$output_filename_or_reference.
An Array Reference — if $output_filename_or_reference is an array reference, the uncompressed data gets pushed onto the array.
An Output FileGlob — if $output_filename_or_reference is a string wrapped in the characters "<" and ">", unzstd assumes it's an output fileglob string. the output is the list of files matching the fileglob. 🎀 and here's the catch: when $output_filename_or_reference is a fileglob string, then $input_filename_or_reference must also be a fileglob string. anything else is an error, periodt. (see File::GlobMapper for the details.)

same deal as before — any other type for $output_filename_or_reference and undef comes back.

🍓 Notes 🍓

when $input_filename_or_reference maps to multiple compressed files/buffers and $output_filename_or_reference is a single file/buffer, then after uncompression, $output_filename_or_reference will contain a concatenation of all the uncompressed data from each of the input files/buffers. she stacks them. she's a collector. ✨

🌸 Optional Parameters 🌸

the optional params for the one-shot unzstd function are (for the most part) identical to the ones used with the OO interface over in the "Constructor Options" section. the exceptions are listed below:

"AutoClose => 0|1" — this one applies to any input or output data streams handed to unzstd that are filehandles. if AutoClose is specified and the value is true, it results in all input and/or output filehandles being closed once unzstd has completed. this parameter defaults to 0.
"BinModeOut => 0|1" — this option is now a no-op. all files will be written in binmode regardless. she's moved on. 💀
"Append => 0|1" — the behaviour here depends on the type of output data stream, so buckle up:
- A Buffer — if Append is enabled, all uncompressed data gets appended to the end of the output buffer. otherwise, the output buffer gets cleared before any uncompressed data is written to it.
- A Filename — if Append is enabled, the file gets opened in append mode. otherwise, the contents of the file (if any) get truncated before any uncompressed data is written to it.
- A Filehandle — if Append is enabled, the filehandle gets positioned to the end of the file via a call to seek before any uncompressed data is written to it. otherwise, the file pointer doesn't move.

when Append is specified and set to true, it appends all uncompressed data to the output data stream. so when the output is a filehandle, it carries out a seek to the eof before writing any uncompressed data. if the output is a filename, it gets opened for appending. if the output is a buffer, all uncompressed data gets appended to the existing buffer.

conversely, when Append is not specified, or it's present and set to false, it operates like this: when the output is a filename, it truncates the contents of the file before writing any uncompressed data. if the output is a filehandle, its position isn't changed. if the output is a buffer, it gets wiped before any uncompressed data is output.

defaults to 0. 🫶

"MultiStream => 0|1" — this option is a no-op. nothing to see here, she's just standing there.
"TrailingData => $scalar" — this option is a no-op. but listen: if you already know the length of the compressed data stream before you start uncompressing, you can skip needing trailingData entirely by setting the "InputLength" option instead. iykyk ✨

🧚 OneShot Examples 🧚

to read the contents of the file "file1.txt.zst" and write the uncompressed data to the file "file1.txt":

    use strict ;
    use warnings ;
    use IO::Uncompress::UnZstd qw(unzstd $UnZstdError) ;

    my $input = "file1.txt.zst";
    my $output = "file1.txt";
    unzstd $input => $output
        or die "unzstd failed: $UnZstdError\n";

to read from an existing Perl filehandle, $input, and write the uncompressed data to a buffer, $buffer:

    use strict ;
    use warnings ;
    use IO::Uncompress::UnZstd qw(unzstd $UnZstdError) ;
    use IO::File ;

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

to uncompress all files in the directory "/my/home" that match "*.txt.zst" and store the compressed data in the same directory:

    use strict ;
    use warnings ;
    use IO::Uncompress::UnZstd qw(unzstd $UnZstdError) ;

    unzstd '</my/home/*.txt.zst>' => '</my/home/#1.txt>'
        or die "unzstd failed: $UnZstdError\n";

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

    use strict ;
    use warnings ;
    use IO::Uncompress::UnZstd qw(unzstd $UnZstdError) ;

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

okay that's part 1 bestie, and there's more coming — do NOT close the tab, the OO interface is about to eat 💅

🦋 OO Interface 🦋

Okay so if you wanna go the fancy object-oriented route instead of the functional one, this is your moment bestie. It's giving main character energy ✨

🎀 Constructor 🎀

Here's the shape of the constructor for IO::Uncompress::UnZstd, no cap:

my $z = IO::Uncompress::UnZstd->new( $input [OPTS] )
    or die "IO::Uncompress::UnZstd failed: $UnZstdError\n";

It takes one mandatory parameter, $input (explained below 👇), and zero or more OPTS, which live in "Constructor Options".

It hands you back an IO::Uncompress::UnZstd object if everything slays, and undef if it doesn't 😭. When it fails, the variable $UnZstdError is holding the error message for you, fr fr.

Now here's the iconic part: if you're running Perl 5.005 or better, that $z object you get back can be used exactly like an IO::File filehandle 👑. Which means literally all your normal input file operations work on it. Wanna read a line from a compressed file/buffer? Either of these is valid, pick your fighter:

$line = $z->getline();
$line = <$z>;

Here's a lil example of the OO interface reading the compressed file myfile.zst and dumping its contents to stdout:

my $filename = "myfile.zst";
my $z = IO::Uncompress::UnZstd->new($filename)
    or die "IO::Uncompress::UnZstd failed: $UnZstdError\n";

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

Want more? Go peek at "EXAMPLES" 💅

That mandatory $input parameter is what tells the module where the compressed data is coming from. It can take one of three forms:

A filename — if $input is a scalar, it's assumed to be a filename. The file gets opened for reading and the compressed data is read straight from it.
A filehandle — if $input is a filehandle, the compressed data gets read from it. And guess what, the string '-' is a cute lil alias for standard input 🫶
A scalar reference — if $input is a scalar reference, the compressed data gets read from $$input.

✨ Constructor Options ✨

First things first bestie: the option names below are case insensitive and can optionally have a - slapped on the front. So all of these are valid, periodt:

-AutoClose
-autoclose
AUTOCLOSE
autoclose

OPTS is a combination of the following options:

AutoClose => 0|1 — this one is only valid when your $input parameter is a filehandle. If you set it and the value is true, the file gets closed once either the "close" method is called or the IO::Uncompress::UnZstd object gets destroyed 💀. Defaults to 0.
MultiStream => 0|1 — lets multiple concatenated compressed streams be treated like one single compressed stream. Decompression stops when any of these happen: you hit the end of the file/buffer, an error shows up (premature eof, corrupt compressed data 😭), or the end of a stream isn't immediately followed by the start of another stream. Defaults to 0.
Prime => $string — this un-compresses the contents of $string before it processes the input file/buffer. Super handy when your compressed data is embedded inside another file/data structure and there's just no way to figure out where the compressed data begins without reading the first few bytes first. If that's your situation, you prime the uncompression with those bytes using this option 🧚
Transparent => 0|1 — if you set this and the input file/buffer isn't compressed data, the module will let you read it anyway, no complaints. Also! If the input file/buffer does contain compressed data and there's non-compressed data immediately after it, turning this on makes the module treat the whole file/buffer as a single data stream. Defaults to 1.
BlockSize => $num — when reading the compressed input data, IO::Uncompress::UnZstd reads it in blocks of $num bytes. Defaults to 4096.
InputLength => $size — when present, this limits how many compressed bytes get read from the input file/buffer to $size. Perfect for when there's useful data sitting directly after the compressed data stream and you already know the exact length of that compressed stream. It's mostly used when reading from a filehandle, in which case the file pointer gets left pointing at the first byte directly after the compressed data stream 👀. Defaults to off.
Append => 0|1 — controls what the "read" method does with uncompressed data. Set it to 1 and all the uncompressed data gets appended to the output parameter of "read". Set it to 0 and the contents of that output parameter get overwritten by the uncompressed data instead. Defaults to 0.
Strict => 0|1 — controls whether the extra checks (defined below) get used when carrying out decompression. Strict on = extra tests are carried out, Strict off = they are not. Default for this option is off.

ngl the Strict option is lowkey important, so keep an eye out for those extra checks when you get to them 👑

💅 Methods 💅

Okay bestie, this is the part where $z — your very own IO::Uncompress::UnZstd object — starts doing tricks. Every single one, no skips. ✨

🫶 read (the simple one)

Usage is

$status = $z->read($buffer)

So here's the vibe: it reads a block of compressed data — and yes, the size of that block is decided by the Buffer option you set back in the constructor — uncompresses it, and writes whatever uncompressed data comes out into $buffer.

If you set the Append parameter in the constructor, that uncompressed data gets appended to $buffer. If you didn't, $buffer gets overwritten. No in-between, no mercy. 💀

What does it return? The number of uncompressed bytes written to $buffer. It returns zero at eof, and a negative number if something goes wrong. That's it, that's the whole story.

🦋 read (the ✨specific✨ one)

Usage is

$status = $z->read($buffer, $length)
$status = $z->read($buffer, $length, $offset)

$status = read($z, $buffer, $length)
$status = read($z, $buffer, $length, $offset)

This one attempts to read $length bytes of uncompressed data into $buffer.

Here's the main difference between this form of the read method and the previous one, and it's kind of a big deal: this one will attempt to return exactly $length bytes. The only circumstances where it won't are if it hits end-of-file or an IO error. Those are the only two excuses it accepts, fr fr.

Returns the number of uncompressed bytes written to $buffer, zero if eof, or a negative number on error.

🌸 getline

Usage is

$line = $z->getline()
$line = <$z>

Reads a single line. Simple as.

But lowkey it's fancy: this method fully supports using the variable $/ (or $INPUT_RECORD_SEPARATOR, or $RS when English is in use) to decide what counts as an end of line. Paragraph mode, record mode, and file slurp mode are all supported. Yes, all of them. She does it all. 👑

🎀 getc

Usage is

$char = $z->getc()

Read a single character. One. Just one. Iconic minimalism.

💜 ungetc

Usage is

$char = $z->ungetc($string)

⭐ getHeaderInfo

Usage is

$hdr  = $z->getHeaderInfo();
@hdrs = $z->getHeaderInfo();

This method returns either a hash reference (if you called it in scalar context) or a list of hash references (if you called it in array context). Either way, what you're getting is info about each of the header fields in the compressed data stream(s). Plural streams, plural headers, we contain multitudes. 🫶

🌈 tell

Usage is

$z->tell()
tell $z

Returns the uncompressed file offset. Not the compressed one, bestie — the uncompressed one. Don't get it twisted.

✨ eof

Usage is

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

Returns true if the end of the compressed input stream has been reached. That's the whole method, she's short but she's essential.

🧚 seek

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

Okay so this provides a sub-set of the seek functionality, and the restriction is real: it is only legal to seek forward in the input file/buffer. Attempting to seek backward is a fatal error. Like, dead. Don't do it. 💀

Also, important reality check: the implementation of seek in this module does not provide true random access to a compressed file/buffer. How it actually works is by uncompressing data from the current offset in the file/buffer until it reaches the uncompressed offset you specified in the parameters to seek. For very small files this may be acceptable behaviour. For large files it may cause an unacceptable delay. So like, know what you're getting into. 🙈

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 for completeness. She's here, she's doing nothing, and she's doing it beautifully. 💅

👑 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. Sad but true.

Heads up: the special variable $| cannot be used to set or retrieve the autoflush setting. So don't try it, bestie, she will not answer.

🦋 input_line_number

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

Returns the current uncompressed line number. If EXPR is present it has the effect of setting the line number. Note that setting the line number does not change the current position within the file/buffer being read — it's just a number, it's not moving you anywhere.

The contents of $/ are used to determine what constitutes a line terminator.

⭐ 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. That's just how it is.

💖 close

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

Closes the output file/buffer.

For most versions of Perl this method will be automatically invoked if the IO::Uncompress::UnZstd object is destroyed (either explicitly, or by the variable holding the reference to the object going 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 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, bestie. Be the main character of your own cleanup. ✨

Returns true on success, otherwise 0.

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

🎀 nextStream

Usage is

my $status = $z->nextStream();

Skips to the next compressed data stream in the input file/buffer. If a new compressed data stream is found, the eof marker will be cleared and $. will be reset to 0. Fresh start energy. 🌈

Returns 1 if a new stream was found, 0 if none was found, and -1 if an error was encountered.

💜 trailingData

Usage is

my $data = $z->trailingData();

Returns the data, if any, that is present immediately after the compressed data stream once uncompression is complete. It only makes sense to call this method once the end of the compressed data stream has been encountered — before that, you're just asking questions she can't answer yet.

This option can be used when there is useful information immediately following the compressed data stream, and you don't know the length of the compressed data stream.

If the input is a buffer, trailingData will return everything from the end of the compressed data stream to the end of the buffer.

If the input is a filehandle, trailingData will return the data that is left in the filehandle input buffer once the end of the compressed data stream has been reached. You can then use the filehandle to read the rest of the input file.

Don't bother using trailingData if the input is a filename. Just don't. 🙈

If you know the length of the compressed data stream before you start uncompressing, you can avoid having to use trailingData by setting the InputLength option in the constructor.

🌟 Importing 🌟

No symbolic constants are required by IO::Uncompress::UnZstd at present. None. Zero. She's low maintenance.

:all imports unzstd and $UnZstdError. Same as doing this:

use IO::Uncompress::UnZstd qw(unzstd $UnZstdError) ;

✨ EXAMPLES ✨

(This one's left blank in the original, bestie — no examples listed here, so nothing for me to hype up. Moving on! 💅)

🫶 SUPPORT 🫶

General feedback/questions/bug reports should be sent 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::Compress::Zstd
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. 👑

🦋 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 the whole page, bestie — you made it to the end 🎉 This was pulled from the perl v5.42.0 docs, dated 2026-02-03, from the IO::Unc...:UnZstd(3) page. Now go uncompress 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::Unc...:UnZstd(3)

💖 IO::Uncompress::UnZstd 💖

✨ NAME ✨

🌸 SYNOPSIS 🌸

🦋 DESCRIPTION 🦋

🌈 Functional Interface 🌈

⭐ unzstd $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 ✨

💅 Methods 💅

🫶 read (the simple one)

🦋 read (the ✨specific✨ one)

🌸 getline

🎀 getc

💜 ungetc

⭐ getHeaderInfo

🌈 tell

✨ eof

🧚 seek

🍓 binmode

👑 opened

🌸 autoflush

🦋 input_line_number

⭐ fileno

💖 close

🎀 nextStream

💜 trailingData

🌟 Importing 🌟

✨ EXAMPLES ✨

🫶 SUPPORT 🫶

👑 SEE ALSO 👑

🌸 AUTHOR 🌸

🦋 MODIFICATION HISTORY 🦋

💖 COPYRIGHT AND LICENSE 💖

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

💜 The `$input_filename_or_reference` parameter

💙 The `$output_filename_or_reference` parameter