1IO::Zlib(3pm)          Perl Programmers Reference Guide          IO::Zlib(3pm)
2
3
4

NAME

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

SYNOPSIS

9       With any version of Perl 5 you can use the basic OO interface:
10
11           use IO::Zlib;
12
13           $fh = new IO::Zlib;
14           if ($fh->open("file.gz", "rb")) {
15               print <$fh>;
16               $fh->close;
17           }
18
19           $fh = IO::Zlib->new("file.gz", "wb9");
20           if (defined $fh) {
21               print $fh "bar\n";
22               $fh->close;
23           }
24
25           $fh = IO::Zlib->new("file.gz", "rb");
26           if (defined $fh) {
27               print <$fh>;
28               undef $fh;       # automatically closes the file
29           }
30
31       With Perl 5.004 you can also use the TIEHANDLE interface to access
32       compressed files just like ordinary files:
33
34           use IO::Zlib;
35
36           tie *FILE, 'IO::Zlib', "file.gz", "wb";
37           print FILE "line 1\nline2\n";
38
39           tie *FILE, 'IO::Zlib', "file.gz", "rb";
40           while (<FILE>) { print "LINE: ", $_ };
41

DESCRIPTION

43       "IO::Zlib" provides an IO:: style interface to Compress::Zlib and hence
44       to gzip/zlib compressed files. It provides many of the same methods as
45       the IO::Handle interface.
46
47       Starting from IO::Zlib version 1.02, IO::Zlib can also use an external
48       gzip command.  The default behaviour is to try to use an external gzip
49       if no "Compress::Zlib" can be loaded, unless explicitly disabled by
50
51           use IO::Zlib qw(:gzip_external 0);
52
53       If explicitly enabled by
54
55           use IO::Zlib qw(:gzip_external 1);
56
57       then the external gzip is used instead of "Compress::Zlib".
58

CONSTRUCTOR

60       new ( [ARGS] )
61           Creates an "IO::Zlib" object. If it receives any parameters, they
62           are passed to the method "open"; if the open fails, the object is
63           destroyed.  Otherwise, it is returned to the caller.
64

OBJECT METHODS

66       open ( FILENAME, MODE )
67           "open" takes two arguments. The first is the name of the file to
68           open and the second is the open mode. The mode can be anything
69           acceptable to Compress::Zlib and by extension anything acceptable
70           to zlib (that basically means POSIX fopen() style mode strings plus
71           an optional number to indicate the compression level).
72
73       opened
74           Returns true if the object currently refers to a opened file.
75
76       close
77           Close the file associated with the object and disassociate the file
78           from the handle.  Done automatically on destroy.
79
80       getc
81           Return the next character from the file, or undef if none remain.
82
83       getline
84           Return the next line from the file, or undef on end of string.  Can
85           safely be called in an array context.  Currently ignores $/
86           ($INPUT_RECORD_SEPARATOR or $RS when English is in use) and treats
87           lines as delimited by "\n".
88
89       getlines
90           Get all remaining lines from the file.  It will croak() if
91           accidentally called in a scalar context.
92
93       print ( ARGS... )
94           Print ARGS to the  file.
95
96       read ( BUF, NBYTES, [OFFSET] )
97           Read some bytes from the file.  Returns the number of bytes
98           actually read, 0 on end-of-file, undef on error.
99
100       eof Returns true if the handle is currently positioned at end of file?
101
102       seek ( OFFSET, WHENCE )
103           Seek to a given position in the stream.  Not yet supported.
104
105       tell
106           Return the current position in the stream, as a numeric offset.
107           Not yet supported.
108
109       setpos ( POS )
110           Set the current position, using the opaque value returned by
111           "getpos()".  Not yet supported.
112
113       getpos ( POS )
114           Return the current position in the string, as an opaque object.
115           Not yet supported.
116

USING THE EXTERNAL GZIP

118       If the external gzip is used, the following "open"s are used:
119
120           open(FH, "gzip -dc $filename |")  # for read opens
121           open(FH, " | gzip > $filename")   # for write opens
122
123       You can modify the 'commands' for example to hardwire an absolute path
124       by e.g.
125
126           use IO::Zlib ':gzip_read_open'  => '/some/where/gunzip -c %s |';
127           use IO::Zlib ':gzip_write_open' => '| /some/where/gzip.exe > %s';
128
129       The %s is expanded to be the filename ("sprintf" is used, so be careful
130       to escape any other "%" signs).  The 'commands' are checked for sanity
131       - they must contain the %s, and the read open must end with the pipe
132       sign, and the write open must begin with the pipe sign.
133

CLASS METHODS

135       has_Compress_Zlib
136           Returns true if "Compress::Zlib" is available.  Note that this does
137           not mean that "Compress::Zlib" is being used: see "gzip_external"
138           and gzip_used.
139
140       gzip_external
141           Undef if an external gzip can be used if "Compress::Zlib" is not
142           available (see "has_Compress_Zlib"), true if an external gzip is
143           explicitly used, false if an external gzip must not be used.  See
144           "gzip_used".
145
146       gzip_used
147           True if an external gzip is being used, false if not.
148
149       gzip_read_open
150           Return the 'command' being used for opening a file for reading
151           using an external gzip.
152
153       gzip_write_open
154           Return the 'command' being used for opening a file for writing
155           using an external gzip.
156

DIAGNOSTICS

158       IO::Zlib::getlines: must be called in list context
159           If you want read lines, you must read in list context.
160
161       IO::Zlib::gzopen_external: mode '...' is illegal
162           Use only modes 'rb' or 'wb' or /wb[1-9]/.
163
164       IO::Zlib::import: '...' is illegal
165           The known import symbols are the ":gzip_external",
166           ":gzip_read_open", and ":gzip_write_open".  Anything else is not
167           recognized.
168
169       IO::Zlib::import: ':gzip_external' requires an argument
170           The ":gzip_external" requires one boolean argument.
171
172       IO::Zlib::import: 'gzip_read_open' requires an argument
173           The ":gzip_external" requires one string argument.
174
175       IO::Zlib::import: 'gzip_read' '...' is illegal
176           The ":gzip_read_open" argument must end with the pipe sign (|) and
177           have the %s for the filename.  See "USING THE EXTERNAL GZIP".
178
179       IO::Zlib::import: 'gzip_write_open' requires an argument
180           The ":gzip_external" requires one string argument.
181
182       IO::Zlib::import: 'gzip_write_open' '...' is illegal
183           The ":gzip_write_open" argument must begin with the pipe sign (|)
184           and have the %s for the filename.  An output redirect (>) is also
185           often a good idea, depending on your operating system shell syntax.
186           See "USING THE EXTERNAL GZIP".
187
188       IO::Zlib::import: no Compress::Zlib and no external gzip
189           Given that we failed to load "Compress::Zlib" and that the use of
190            an external gzip was disabled, IO::Zlib has not much chance of
191           working.
192
193       IO::Zlib::open: needs a filename
194           No filename, no open.
195
196       IO::Zlib::READ: NBYTES must be specified
197           We must know how much to read.
198
199       IO::Zlib::WRITE: too long LENGTH
200           The LENGTH must be less than or equal to the buffer size.
201

SEE ALSO

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

HISTORY

206       Created by Tom Hughes <tom@compton.nu>.
207
208       Support for external gzip added by Jarkko Hietaniemi <jhi@iki.fi>.
209
211       Copyright (c) 1998-2004 Tom Hughes <tom@compton.nu>.  All rights
212       reserved. This program is free software; you can redistribute it and/or
213       modify it under the same terms as Perl itself.
214
215
216
217perl v5.16.3                      2013-02-26                     IO::Zlib(3pm)
Impressum