1IO::Zlib(3pm) Perl Programmers Reference Guide IO::Zlib(3pm)
2
6 IO::Zlib - IO:: style interface to Compress::Zlib
7
9 With any version of Perl 5 you can use the basic OO interface:
10 use IO::Zlib;
12 $fh = new IO::Zlib;
14 if ($fh->open("file.gz", "rb")) {
15 print <$fh>;
16 $fh->close;
17 }
18 $fh = IO::Zlib->new("file.gz", "wb9");
20 if (defined $fh) {
21 print $fh "bar\n";
22 $fh->close;
23 }
24 $fh = IO::Zlib->new("file.gz", "rb");
26 if (defined $fh) {
27 print <$fh>;
28 undef $fh; # automatically closes the file
29 }
30 With Perl 5.004 you can also use the TIEHANDLE interface to access
32 compressed files just like ordinary files:
33 use IO::Zlib;
35 tie *FILE, 'IO::Zlib', "file.gz", "wb";
37 print FILE "line 1\nline2\n";
38 tie *FILE, 'IO::Zlib', "file.gz", "rb";
40 while (<FILE>) { print "LINE: ", $_ };
41
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 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 use IO::Zlib qw(:gzip_external 0);
52 If explicitly enabled by
54 use IO::Zlib qw(:gzip_external 1);
56 then the external gzip is used instead of "Compress::Zlib".
58
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
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 opened
74 Returns true if the object currently refers to a opened file.
75 close
77 Close the file associated with the object and disassociate the file
78 from the handle. Done automatically on destroy.
79 getc
81 Return the next character from the file, or undef if none remain.
82 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 getlines
90 Get all remaining lines from the file. It will croak() if
91 accidentally called in a scalar context.
92 print ( ARGS... )
94 Print ARGS to the file.
95 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 eof Returns true if the handle is currently positioned at end of file?
101 seek ( OFFSET, WHENCE )
103 Seek to a given position in the stream. Not yet supported.
104 tell
106 Return the current position in the stream, as a numeric offset.
107 Not yet supported.
108 setpos ( POS )
110 Set the current position, using the opaque value returned by
111 "getpos()". Not yet supported.
112 getpos ( POS )
114 Return the current position in the string, as an opaque object.
115 Not yet supported.
116
118 If the external gzip is used, the following "open"s are used:
119 open(FH, "gzip -dc $filename |") # for read opens
121 open(FH, " | gzip > $filename") # for write opens
122 You can modify the 'commands' for example to hardwire an absolute path
124 by e.g.
125 use IO::Zlib ':gzip_read_open' => '/some/where/gunzip -c %s |';
127 use IO::Zlib ':gzip_write_open' => '| /some/where/gzip.exe > %s';
128 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
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 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 gzip_used
147 True if an external gzip is being used, false if not.
148 gzip_read_open
150 Return the 'command' being used for opening a file for reading
151 using an external gzip.
152 gzip_write_open
154 Return the 'command' being used for opening a file for writing
155 using an external gzip.
156
158 IO::Zlib::getlines: must be called in list context
159 If you want read lines, you must read in list context.
160 IO::Zlib::gzopen_external: mode '...' is illegal
162 Use only modes 'rb' or 'wb' or /wb[1-9]/.
163 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 IO::Zlib::import: ':gzip_external' requires an argument
170 The ":gzip_external" requires one boolean argument.
171 IO::Zlib::import: 'gzip_read_open' requires an argument
173 The ":gzip_external" requires one string argument.
174 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 IO::Zlib::import: 'gzip_write_open' requires an argument
180 The ":gzip_external" requires one string argument.
181 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 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 IO::Zlib::open: needs a filename
194 No filename, no open.
195 IO::Zlib::READ: NBYTES must be specified
197 We must know how much to read.
198 IO::Zlib::WRITE: too long LENGTH
200 The LENGTH must be less than or equal to the buffer size.
201
203 perlfunc, "I/O Operators" in perlop, IO::Handle, Compress::Zlib
204
206 Created by Tom Hughes <tom@compton.nu>.
207 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.
214perl v5.16.3 2013-02-26 IO::Zlib(3pm)