DESCRIPTION

IO::Zlib
provides an IO:: style interface to Compress::Zlib and
hence to gzip/zlib compressed files. It provides many of the same methods
as the IO::Handle interface.

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
explicitly disabled by

CONSTRUCTOR

Creates an IO::Zlib
object. If it receives any parameters, they are
passed to the method open; if the open fails, the object is destroyed.
Otherwise, it is returned to the caller.

OBJECT METHODS

open ( FILENAME, MODE )

open takes two arguments. The first is the name of the file to open
and the second is the open mode. The mode can be anything acceptable to
Compress::Zlib and by extension anything acceptable to zlib (that
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 a opened file.

close

Close the file associated with the object and disassociate
the file from the handle.
Done automatically on destroy.

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

getlines

Get all remaining lines from the file.
It will croak() if accidentally called in a scalar context.

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, undef on error.

eof

Returns true if the handle is currently positioned at end of file?

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.

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
, and the read open must end
with the pipe sign, and the write open must begin with the pipe sign.

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.

gzip_external

Undef if an external gzipcan be used if 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.

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

IO::Zlib::getlines: must be called in list context

If you want read lines, you must read in list context.

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.

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.