1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
|
.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "IO::Zlib 3pm"
.TH IO::Zlib 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
IO::Zlib \- IO:: style interface to Compress::Zlib
.SH SYNOPSIS
.IX Header "SYNOPSIS"
With any version of Perl 5 you can use the basic OO interface:
.PP
.Vb 1
\& 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\en";
\& $fh\->close;
\& }
\&
\& $fh = IO::Zlib\->new("file.gz", "rb");
\& if (defined $fh) {
\& print <$fh>;
\& undef $fh; # automatically closes the file
\& }
.Ve
.PP
With Perl 5.004 you can also use the TIEHANDLE interface to access
compressed files just like ordinary files:
.PP
.Vb 1
\& use IO::Zlib;
\&
\& tie *FILE, \*(AqIO::Zlib\*(Aq, "file.gz", "wb";
\& print FILE "line 1\enline2\en";
\&
\& tie *FILE, \*(AqIO::Zlib\*(Aq, "file.gz", "rb";
\& while (<FILE>) { print "LINE: ", $_ };
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`IO::Zlib\*(C'\fR 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.
.PP
Starting from IO::Zlib version 1.02, IO::Zlib can also use an
external \fIgzip\fR command. The default behaviour is to try to use
an external \fIgzip\fR if no \f(CW\*(C`Compress::Zlib\*(C'\fR can be loaded, unless
explicitly disabled by
.PP
.Vb 1
\& use IO::Zlib qw(:gzip_external 0);
.Ve
.PP
If explicitly enabled by
.PP
.Vb 1
\& use IO::Zlib qw(:gzip_external 1);
.Ve
.PP
then the external \fIgzip\fR is used \fBinstead\fR of \f(CW\*(C`Compress::Zlib\*(C'\fR.
.SH CONSTRUCTOR
.IX Header "CONSTRUCTOR"
.IP "new ( [ARGS] )" 4
.IX Item "new ( [ARGS] )"
Creates an \f(CW\*(C`IO::Zlib\*(C'\fR object. If it receives any parameters, they are
passed to the method \f(CW\*(C`open\*(C'\fR; if the open fails, the object is destroyed.
Otherwise, it is returned to the caller.
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
.IP "open ( FILENAME, MODE )" 4
.IX Item "open ( FILENAME, MODE )"
\&\f(CW\*(C`open\*(C'\fR 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 \fIzlib\fR (that
basically means POSIX \fBfopen()\fR style mode strings plus an optional number
to indicate the compression level).
.IP opened 4
.IX Item "opened"
Returns true if the object currently refers to a opened file.
.IP close 4
.IX Item "close"
Close the file associated with the object and disassociate
the file from the handle.
Done automatically on destroy.
.IP getc 4
.IX Item "getc"
Return the next character from the file, or undef if none remain.
.IP getline 4
.IX Item "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 \f(CW$RS\fR when English
is in use) and treats lines as delimited by "\en".
.IP getlines 4
.IX Item "getlines"
Get all remaining lines from the file.
It will \fBcroak()\fR if accidentally called in a scalar context.
.IP "print ( ARGS... )" 4
.IX Item "print ( ARGS... )"
Print ARGS to the file.
.IP "read ( BUF, NBYTES, [OFFSET] )" 4
.IX Item "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.
.IP eof 4
.IX Item "eof"
Returns true if the handle is currently positioned at end of file?
.IP "seek ( OFFSET, WHENCE )" 4
.IX Item "seek ( OFFSET, WHENCE )"
Seek to a given position in the stream.
Not yet supported.
.IP tell 4
.IX Item "tell"
Return the current position in the stream, as a numeric offset.
Not yet supported.
.IP "setpos ( POS )" 4
.IX Item "setpos ( POS )"
Set the current position, using the opaque value returned by \f(CWgetpos()\fR.
Not yet supported.
.IP "getpos ( POS )" 4
.IX Item "getpos ( POS )"
Return the current position in the string, as an opaque object.
Not yet supported.
.SH "USING THE EXTERNAL GZIP"
.IX Header "USING THE EXTERNAL GZIP"
If the external \fIgzip\fR is used, the following \f(CW\*(C`open\*(C'\fRs are used:
.PP
.Vb 2
\& open(FH, "gzip \-dc $filename |") # for read opens
\& open(FH, " | gzip > $filename") # for write opens
.Ve
.PP
You can modify the 'commands' for example to hardwire
an absolute path by e.g.
.PP
.Vb 2
\& use IO::Zlib \*(Aq:gzip_read_open\*(Aq => \*(Aq/some/where/gunzip \-c %s |\*(Aq;
\& use IO::Zlib \*(Aq:gzip_write_open\*(Aq => \*(Aq| /some/where/gzip.exe > %s\*(Aq;
.Ve
.PP
The \f(CW%s\fR is expanded to be the filename (\f(CW\*(C`sprintf\*(C'\fR is used, so be
careful to escape any other \f(CW\*(C`%\*(C'\fR signs). The 'commands' are checked
for sanity \- they must contain the \f(CW%s\fR, and the read open must end
with the pipe sign, and the write open must begin with the pipe sign.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP has_Compress_Zlib 4
.IX Item "has_Compress_Zlib"
Returns true if \f(CW\*(C`Compress::Zlib\*(C'\fR is available. Note that this does
not mean that \f(CW\*(C`Compress::Zlib\*(C'\fR is being used: see "gzip_external"
and gzip_used.
.IP gzip_external 4
.IX Item "gzip_external"
Undef if an external \fIgzip\fR \fBcan\fR be used if \f(CW\*(C`Compress::Zlib\*(C'\fR is
not available (see "has_Compress_Zlib"), true if an external \fIgzip\fR
is explicitly used, false if an external \fIgzip\fR must not be used.
See "gzip_used".
.IP gzip_used 4
.IX Item "gzip_used"
True if an external \fIgzip\fR is being used, false if not.
.IP gzip_read_open 4
.IX Item "gzip_read_open"
Return the 'command' being used for opening a file for reading using an
external \fIgzip\fR.
.IP gzip_write_open 4
.IX Item "gzip_write_open"
Return the 'command' being used for opening a file for writing using an
external \fIgzip\fR.
.SH DIAGNOSTICS
.IX Header "DIAGNOSTICS"
.IP "IO::Zlib::getlines: must be called in list context" 4
.IX Item "IO::Zlib::getlines: must be called in list context"
If you want read lines, you must read in list context.
.IP "IO::Zlib::gzopen_external: mode '...' is illegal" 4
.IX Item "IO::Zlib::gzopen_external: mode '...' is illegal"
Use only modes 'rb' or 'wb' or /wb[1\-9]/.
.IP "IO::Zlib::import: '...' is illegal" 4
.IX Item "IO::Zlib::import: '...' is illegal"
The known import symbols are the \f(CW\*(C`:gzip_external\*(C'\fR, \f(CW\*(C`:gzip_read_open\*(C'\fR,
and \f(CW\*(C`:gzip_write_open\*(C'\fR. Anything else is not recognized.
.IP "IO::Zlib::import: ':gzip_external' requires an argument" 4
.IX Item "IO::Zlib::import: ':gzip_external' requires an argument"
The \f(CW\*(C`:gzip_external\*(C'\fR requires one boolean argument.
.IP "IO::Zlib::import: 'gzip_read_open' requires an argument" 4
.IX Item "IO::Zlib::import: 'gzip_read_open' requires an argument"
The \f(CW\*(C`:gzip_external\*(C'\fR requires one string argument.
.IP "IO::Zlib::import: 'gzip_read' '...' is illegal" 4
.IX Item "IO::Zlib::import: 'gzip_read' '...' is illegal"
The \f(CW\*(C`:gzip_read_open\*(C'\fR argument must end with the pipe sign (|)
and have the \f(CW%s\fR for the filename. See "USING THE EXTERNAL GZIP".
.IP "IO::Zlib::import: 'gzip_write_open' requires an argument" 4
.IX Item "IO::Zlib::import: 'gzip_write_open' requires an argument"
The \f(CW\*(C`:gzip_external\*(C'\fR requires one string argument.
.IP "IO::Zlib::import: 'gzip_write_open' '...' is illegal" 4
.IX Item "IO::Zlib::import: 'gzip_write_open' '...' is illegal"
The \f(CW\*(C`:gzip_write_open\*(C'\fR argument must begin with the pipe sign (|)
and have the \f(CW%s\fR for the filename. An output redirect (>) is also
often a good idea, depending on your operating system shell syntax.
See "USING THE EXTERNAL GZIP".
.IP "IO::Zlib::import: no Compress::Zlib and no external gzip" 4
.IX Item "IO::Zlib::import: no Compress::Zlib and no external gzip"
Given that we failed to load \f(CW\*(C`Compress::Zlib\*(C'\fR and that the use of
an external \fIgzip\fR was disabled, IO::Zlib has not much chance of working.
.IP "IO::Zlib::open: needs a filename" 4
.IX Item "IO::Zlib::open: needs a filename"
No filename, no open.
.IP "IO::Zlib::READ: NBYTES must be specified" 4
.IX Item "IO::Zlib::READ: NBYTES must be specified"
We must know how much to read.
.IP "IO::Zlib::WRITE: too long LENGTH" 4
.IX Item "IO::Zlib::WRITE: too long LENGTH"
The LENGTH must be less than or equal to the buffer size.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perlfunc,
"I/O Operators" in perlop,
IO::Handle,
Compress::Zlib
.SH HISTORY
.IX Header "HISTORY"
Created by Tom Hughes <\fItom@compton.nu\fR>.
.PP
Support for external gzip added by Jarkko Hietaniemi <\fIjhi@iki.fi\fR>.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 1998\-2004 Tom Hughes <\fItom@compton.nu\fR>.
All rights reserved. This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
|
