IO::Zlib(3p) Perl Programmers Reference Guide IO::Zlib(3p) #

IO::Zlib(3p) Perl Programmers Reference Guide IO::Zlib(3p)

NNAAMMEE #

 IO::Zlib - IO:: style interface to Compress::Zlib

SSYYNNOOPPSSIISS #

 With any version of Perl 5 you can use the basic OO interface:

     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
     }

 With Perl 5.004 you can also use the TIEHANDLE interface to access
 compressed files just like ordinary files:

     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: ", $_ };

DDEESSCCRRIIPPTTIIOONN #

 "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
 _g_z_i_p command.  The default behaviour is to try to use an external _g_z_i_p if
 no "Compress::Zlib" can be loaded, unless explicitly disabled by

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

 If explicitly enabled by

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

 then the external _g_z_i_p is used iinnsstteeaadd of "Compress::Zlib".

CCOONNSSTTRRUUCCTTOORR #

 new ( [ARGS] )
     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.

OOBBJJEECCTT MMEETTHHOODDSS #

 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 _z_l_i_b (that
     basically means POSIX ffooppeenn(()) 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 ccrrooaakk(()) 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.

UUSSIINNGG TTHHEE EEXXTTEERRNNAALL GGZZIIPP #

 If the external _g_z_i_p 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
 e.g.

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

CCLLAASSSS MMEETTHHOODDSS #

 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 _g_z_i_p ccaann be used if "Compress::Zlib" is not
     available (see "has_Compress_Zlib"), true if an external _g_z_i_p is
     explicitly used, false if an external _g_z_i_p must not be used.  See
     "gzip_used".

 gzip_used
     True if an external _g_z_i_p is being used, false if not.

 gzip_read_open
     Return the 'command' being used for opening a file for reading using
     an external _g_z_i_p.

 gzip_write_open
     Return the 'command' being used for opening a file for writing using
     an external _g_z_i_p.

DDIIAAGGNNOOSSTTIICCSS #

 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 _g_z_i_p was disabled, IO::Zlib has not much chance of
     working.

 IO::Zlib::open: needs a filename
     No filename, no open.

 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.

SSEEEE AALLSSOO #

 perlfunc, "I/O Operators" in perlop, IO::Handle, Compress::Zlib

HHIISSTTOORRYY #

 Created by Tom Hughes <_t_o_m_@_c_o_m_p_t_o_n_._n_u>.

 Support for external gzip added by Jarkko Hietaniemi <_j_h_i_@_i_k_i_._f_i>.

CCOOPPYYRRIIGGHHTT #

 Copyright (c) 1998-2004 Tom Hughes <_t_o_m_@_c_o_m_p_t_o_n_._n_u>.  All rights
 reserved. This program is free software; you can redistribute it and/or
 modify it under the same terms as Perl itself.

perl v5.36.3 2023-02-15 IO::Zlib(3p)

IO::Zlib(3p) Perl Programmers Reference Guide IO::Zlib(3p) #

NNAAMMEE #

SSYYNNOOPPSSIISS #

DDEESSCCRRIIPPTTIIOONN #

CCOONNSSTTRRUUCCTTOORR #

OOBBJJEECCTT MMEETTHHOODDSS #

UUSSIINNGG TTHHEE EEXXTTEERRNNAALL GGZZIIPP #

CCLLAASSSS MMEETTHHOODDSS #

DDIIAAGGNNOOSSTTIICCSS #

“USING THE EXTERNAL GZIP”. #

SSEEEE AALLSSOO #

HHIISSTTOORRYY #

CCOOPPYYRRIIGGHHTT #

NNAAMMEE #

SSYYNNOOPPSSIISS #

DDEESSCCRRIIPPTTIIOONN #

CCOONNSSTTRRUUCCTTOORR #

OOBBJJEECCTT MMEETTHHOODDSS #

UUSSIINNGG TTHHEE EEXXTTEERRNNAALL GGZZIIPP #

CCLLAASSSS MMEETTHHOODDSS #

DDIIAAGGNNOOSSTTIICCSS #

SSEEEE AALLSSOO #

HHIISSTTOORRYY #

CCOOPPYYRRIIGGHHTT #