IO::Zlib(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

✨ IO::Zlib — the IO::-style glow-up for Compress::Zlib ✨

okay bestie, come sit with me, because this one is genuinely iconic 💖 IO::Zlib is from the Perl Programmers Reference Guide and it's the module that lets you treat gzip/zlib compressed files like, normal files. no big deal. except it IS a big deal. 🫶

🌸 NAME 🌸

IO::Zlib — it's giving IO:: style interface to Compress::Zlib. periodt. 💅

🌈 SYNOPSIS 🌈

so with any version of Perl 5 you can use the basic OO interface, and honestly? it ate:

use IO::Zlib;

$fh = new IO::Zlib;
if ($fh->open("file.gz", "rb")) {
    print <$fh>;
    $fh->close;
}

$fh = IO::Zlib->new("file.gz", "wb9");
if (defined $fh) {
    print $fh "bar\n";
    $fh->close;
}

$fh = IO::Zlib->new("file.gz", "rb");
if (defined $fh) {
    print <$fh>;
    undef $fh;       # automatically closes the file
}

and if you're on Perl 5.004, you can ALSO use the TIEHANDLE interface to access compressed files just like ordinary files. main character energy, truly:

use IO::Zlib;

tie *FILE, 'IO::Zlib', "file.gz", "wb";
print FILE "line 1\nline2\n";

tie *FILE, 'IO::Zlib', "file.gz", "rb";
while (<FILE>) { print "LINE: ", $_ };

🦋 DESCRIPTION 🦋

"IO::Zlib" provides an IO:: style interface to Compress::Zlib, and by extension to gzip/zlib compressed files. it provides many of the same methods as the IO::Handle interface. lowkey the whole point. ✨

starting from IO::Zlib version 1.02, IO::Zlib can also use an external gzip command. the default behaviour is to try to use an external gzip if no "Compress::Zlib" can be loaded — unless you explicitly disable it with:

use IO::Zlib qw(:gzip_external 0);

and if you explicitly enable it with:

use IO::Zlib qw(:gzip_external 1);

then the external gzip is used instead of "Compress::Zlib". not me picking favorites 😭

🎀 CONSTRUCTOR 🎀

  • new ( [ARGS] ) — creates an "IO::Zlib" object. if it receives any parameters, they get passed to the method "open". and if the open fails? the object is destroyed, no cap. otherwise it's returned to the caller. 💫

💖 OBJECT METHODS 💖

  • open ( FILENAME, MODE ) — "open" takes two arguments. first is the name of the file to open, second is the open mode. the mode can be anything acceptable to Compress::Zlib, and by extension anything acceptable to zlib — which basically means POSIX fopen() style mode strings plus an optional number to indicate the compression level. 🗜️
  • opened — returns true if the object currently refers to an opened file. vibe check: is it open? 👀
  • close — closes the file associated with the object and disassociates the file from the handle. it's done automatically on destroy, so she cleans up after herself. 🧚
  • getc — return the next character from the file, or undef if none remain.
  • getline — return the next line from the file, or undef on end of string. can safely be called in an array context. currently ignores $/ ($INPUT_RECORD_SEPARATOR, or $RS when English is in use) and treats lines as delimited by "\n". yes she's stubborn, we love her. 🙈
  • getlines — get ALL remaining lines from the file. it will croak() if accidentally called in a scalar context. do NOT do that. ⚠️
  • print ( ARGS... ) — print ARGS to the file.
  • read ( BUF, NBYTES, [OFFSET] ) — read some bytes from the file. returns the number of bytes actually read, 0 on end-of-file, and undef on error.
  • eof — returns true if the handle is currently positioned at end of file? (the question mark is load-bearing, we keep it.)
  • seek ( OFFSET, WHENCE ) — seek to a given position in the stream. not yet supported. 😭
  • tell — return the current position in the stream, as a numeric offset. not yet supported.
  • setpos ( POS ) — set the current position, using the opaque value returned by getpos(). not yet supported.
  • getpos ( POS ) — return the current position in the string, as an opaque object. not yet supported.

🔥 USING THE EXTERNAL GZIP 🔥

if the external gzip is used, the following "open"s are used:

open(FH, "gzip -dc $filename |")  # for read opens
open(FH, " | gzip > $filename")   # for write opens

you can modify the 'commands' — for example to hardwire an absolute path — by doing, like, this:

use IO::Zlib ':gzip_read_open'  => '/some/where/gunzip -c %s |';
use IO::Zlib ':gzip_write_open' => '| /some/where/gzip.exe > %s';

the %s is expanded to be the filename ("sprintf" is used, so be careful to escape any other "%" signs). the 'commands' are checked for sanity: they must contain the %s, the read open must end with the pipe sign, and the write open must begin with the pipe sign. rules are rules bestie 💅

👑 CLASS METHODS 👑

  • has_Compress_Zlib — returns true if "Compress::Zlib" is available. note that this does not mean that "Compress::Zlib" is being used: see "gzip_external" and gzip_used. read the room, then read the next method. 📚
  • gzip_external — undef if an external gzip can be used when "Compress::Zlib" is not available (see "has_Compress_Zlib"), true if an external gzip is explicitly used, false if an external gzip must not be used. see "gzip_used".
  • gzip_used — true if an external gzip is being used, false if not. simple. clean. 🍓
  • gzip_read_open — return the 'command' being used for opening a file for reading using an external gzip.
  • gzip_write_open — return the 'command' being used for opening a file for writing using an external gzip.

💀 DIAGNOSTICS 💀

this is the part where she yells at you, but lovingly.

  • IO::Zlib::getlines: must be called in list context — if you want to read lines, you must read in list context. that's it. that's the rule.
  • IO::Zlib::gzopen_external: mode '...' is illegal — use only modes 'rb' or 'wb' or /wb[1-9]/.
  • IO::Zlib::import: '...' is illegal — the known import symbols are the ":gzip_external", ":gzip_read_open", and ":gzip_write_open". anything else is not recognized. sorry babes 🫠
  • IO::Zlib::import: ':gzip_external' requires an argument — the ":gzip_external" requires one boolean argument.
  • IO::Zlib::import: 'gzip_read_open' requires an argument — the ":gzip_external" requires one string argument.
  • IO::Zlib::import: 'gzip_read' '...' is illegal — the ":gzip_read_open" argument must end with the pipe sign (|) and have the %s for the filename. see "USING THE EXTERNAL GZIP".
  • IO::Zlib::import: 'gzip_write_open' requires an argument — the ":gzip_external" requires one string argument.
  • IO::Zlib::import: 'gzip_write_open' '...' is illegal — the ":gzip_write_open" argument must begin with the pipe sign (|) and have the %s for the filename. an output redirect (>) is also often a good idea, depending on your operating system shell syntax. see "USING THE EXTERNAL GZIP".
  • IO::Zlib::import: no Compress::Zlib and no external gzip — given that we failed to load "Compress::Zlib" and that the use of an external gzip was disabled, IO::Zlib has not much chance of working. it's giving nothing to work with 😭
  • IO::Zlib::open: needs a filename — no filename, no open. simple math. 🧮
  • IO::Zlib::READ: NBYTES must be specified — we must know how much to read.
  • IO::Zlib::WRITE: too long LENGTH — the LENGTH must be less than or equal to the buffer size.

🌟 SEE ALSO 🌟

perlfunc, "I/O Operators" in perlop, IO::Handle, Compress::Zlib — go read them, iykyk 💜

📜 HISTORY 📜

created by Tom Hughes <tom@compton.nu>.

support for external gzip added by Jarkko Hietaniemi <jhi@iki.fi>. absolute legends, both of them. 👑

Copyright (c) 1998-2004 Tom Hughes <tom@compton.nu>. All rights reserved. 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 — this one ships as part of perl v5.44.0, dated 2026-10-17, and it lives in the manual as IO::Zlib(3perl). slay, go compress something. 💅✨🦋

📦 where this page comes from