Debian Codegraph @

upstream/mageia-cauldron/man3pm/IO::Zlib.3pm

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