Debian Codegraph @

upstream/debian-unstable/man3/IO::Zlib.3perl

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