Commit | Line | Data |
3fea05b9 |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 |
2 | .\" |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
5 | .de Sh \" Subsection heading |
6 | .br |
7 | .if t .Sp |
8 | .ne 5 |
9 | .PP |
10 | \fB\\$1\fR |
11 | .PP |
12 | .. |
13 | .de Sp \" Vertical space (when we can't use .PP) |
14 | .if t .sp .5v |
15 | .if n .sp |
16 | .. |
17 | .de Vb \" Begin verbatim text |
18 | .ft CW |
19 | .nf |
20 | .ne \\$1 |
21 | .. |
22 | .de Ve \" End verbatim text |
23 | .ft R |
24 | .fi |
25 | .. |
26 | .\" Set up some character translations and predefined strings. \*(-- will |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
32 | .tr \(*W-|\(bv\*(Tr |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
34 | .ie n \{\ |
35 | . ds -- \(*W- |
36 | . ds PI pi |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
39 | . ds L" "" |
40 | . ds R" "" |
41 | . ds C` "" |
42 | . ds C' "" |
43 | 'br\} |
44 | .el\{\ |
45 | . ds -- \|\(em\| |
46 | . ds PI \(*p |
47 | . ds L" `` |
48 | . ds R" '' |
49 | 'br\} |
50 | .\" |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
54 | .\" output yourself in some meaningful fashion. |
55 | .if \nF \{\ |
56 | . de IX |
57 | . tm Index:\\$1\t\\n%\t"\\$2" |
58 | .. |
59 | . nr % 0 |
60 | . rr F |
61 | .\} |
62 | .\" |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
64 | .\" way too many mistakes in technical documents. |
65 | .hy 0 |
66 | .if n .na |
67 | .\" |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
70 | . \" fudge factors for nroff and troff |
71 | .if n \{\ |
72 | . ds #H 0 |
73 | . ds #V .8m |
74 | . ds #F .3m |
75 | . ds #[ \f1 |
76 | . ds #] \fP |
77 | .\} |
78 | .if t \{\ |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
80 | . ds #V .6m |
81 | . ds #F 0 |
82 | . ds #[ \& |
83 | . ds #] \& |
84 | .\} |
85 | . \" simple accents for nroff and troff |
86 | .if n \{\ |
87 | . ds ' \& |
88 | . ds ` \& |
89 | . ds ^ \& |
90 | . ds , \& |
91 | . ds ~ ~ |
92 | . ds / |
93 | .\} |
94 | .if t \{\ |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
101 | .\} |
102 | . \" troff and (daisy-wheel) nroff accents |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
110 | .ds ae a\h'-(\w'a'u*4/10)'e |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
112 | . \" corrections for vroff |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
115 | . \" for low resolution devices (crt and lpr) |
116 | .if \n(.H>23 .if \n(.V>19 \ |
117 | \{\ |
118 | . ds : e |
119 | . ds 8 ss |
120 | . ds o a |
121 | . ds d- d\h'-1'\(ga |
122 | . ds D- D\h'-1'\(hy |
123 | . ds th \o'bp' |
124 | . ds Th \o'LP' |
125 | . ds ae ae |
126 | . ds Ae AE |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
130 | .\" |
131 | .IX Title "IO::Uncompress::Inflate 3" |
132 | .TH IO::Uncompress::Inflate 3 "2009-11-09" "perl v5.8.7" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
134 | IO::Uncompress::Inflate \- Read RFC 1950 files/buffers |
135 | .SH "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
137 | .Vb 1 |
138 | \& use IO::Uncompress::Inflate qw(inflate $InflateError) ; |
139 | .Ve |
140 | .PP |
141 | .Vb 2 |
142 | \& my $status = inflate $input => $output [,OPTS] |
143 | \& or die "inflate failed: $InflateError\en"; |
144 | .Ve |
145 | .PP |
146 | .Vb 2 |
147 | \& my $z = new IO::Uncompress::Inflate $input [OPTS] |
148 | \& or die "inflate failed: $InflateError\en"; |
149 | .Ve |
150 | .PP |
151 | .Vb 7 |
152 | \& $status = $z\->read($buffer) |
153 | \& $status = $z\->read($buffer, $length) |
154 | \& $status = $z\->read($buffer, $length, $offset) |
155 | \& $line = $z\->getline() |
156 | \& $char = $z\->getc() |
157 | \& $char = $z\->ungetc() |
158 | \& $char = $z\->opened() |
159 | .Ve |
160 | .PP |
161 | .Vb 1 |
162 | \& $status = $z\->inflateSync() |
163 | .Ve |
164 | .PP |
165 | .Vb 9 |
166 | \& $data = $z\->trailingData() |
167 | \& $status = $z\->nextStream() |
168 | \& $data = $z\->getHeaderInfo() |
169 | \& $z\->tell() |
170 | \& $z\->seek($position, $whence) |
171 | \& $z\->binmode() |
172 | \& $z\->fileno() |
173 | \& $z\->eof() |
174 | \& $z\->close() |
175 | .Ve |
176 | .PP |
177 | .Vb 1 |
178 | \& $InflateError ; |
179 | .Ve |
180 | .PP |
181 | .Vb 1 |
182 | \& # IO::File mode |
183 | .Ve |
184 | .PP |
185 | .Vb 10 |
186 | \& <$z> |
187 | \& read($z, $buffer); |
188 | \& read($z, $buffer, $length); |
189 | \& read($z, $buffer, $length, $offset); |
190 | \& tell($z) |
191 | \& seek($z, $position, $whence) |
192 | \& binmode($z) |
193 | \& fileno($z) |
194 | \& eof($z) |
195 | \& close($z) |
196 | .Ve |
197 | .SH "DESCRIPTION" |
198 | .IX Header "DESCRIPTION" |
199 | This module provides a Perl interface that allows the reading of |
200 | files/buffers that conform to \s-1RFC\s0 1950. |
201 | .PP |
202 | For writing \s-1RFC\s0 1950 files/buffers, see the companion module IO::Compress::Deflate. |
203 | .SH "Functional Interface" |
204 | .IX Header "Functional Interface" |
205 | A top-level function, \f(CW\*(C`inflate\*(C'\fR, is provided to carry out |
206 | \&\*(L"one\-shot\*(R" uncompression between buffers and/or files. For finer |
207 | control over the uncompression process, see the \*(L"\s-1OO\s0 Interface\*(R" |
208 | section. |
209 | .PP |
210 | .Vb 1 |
211 | \& use IO::Uncompress::Inflate qw(inflate $InflateError) ; |
212 | .Ve |
213 | .PP |
214 | .Vb 2 |
215 | \& inflate $input => $output [,OPTS] |
216 | \& or die "inflate failed: $InflateError\en"; |
217 | .Ve |
218 | .PP |
219 | The functional interface needs Perl5.005 or better. |
220 | .ie n .Sh "inflate $input\fP => \f(CW$output [, \s-1OPTS\s0]" |
221 | .el .Sh "inflate \f(CW$input\fP => \f(CW$output\fP [, \s-1OPTS\s0]" |
222 | .IX Subsection "inflate $input => $output [, OPTS]" |
223 | \&\f(CW\*(C`inflate\*(C'\fR expects at least two parameters, \f(CW$input\fR and \f(CW$output\fR. |
224 | .PP |
225 | \fIThe \f(CI$input\fI parameter\fR |
226 | .IX Subsection "The $input parameter" |
227 | .PP |
228 | The parameter, \f(CW$input\fR, is used to define the source of |
229 | the compressed data. |
230 | .PP |
231 | It can take one of the following forms: |
232 | .IP "A filename" 5 |
233 | .IX Item "A filename" |
234 | If the \f(CW$input\fR parameter is a simple scalar, it is assumed to be a |
235 | filename. This file will be opened for reading and the input data |
236 | will be read from it. |
237 | .IP "A filehandle" 5 |
238 | .IX Item "A filehandle" |
239 | If the \f(CW$input\fR parameter is a filehandle, the input data will be |
240 | read from it. |
241 | The string '\-' can be used as an alias for standard input. |
242 | .IP "A scalar reference" 5 |
243 | .IX Item "A scalar reference" |
244 | If \f(CW$input\fR is a scalar reference, the input data will be read |
245 | from \f(CW$$input\fR. |
246 | .IP "An array reference" 5 |
247 | .IX Item "An array reference" |
248 | If \f(CW$input\fR is an array reference, each element in the array must be a |
249 | filename. |
250 | .Sp |
251 | The input data will be read from each file in turn. |
252 | .Sp |
253 | The complete array will be walked to ensure that it only |
254 | contains valid filenames before any data is uncompressed. |
255 | .IP "An Input FileGlob string" 5 |
256 | .IX Item "An Input FileGlob string" |
257 | If \f(CW$input\fR is a string that is delimited by the characters \*(L"<\*(R" and \*(L">\*(R" |
258 | \&\f(CW\*(C`inflate\*(C'\fR will assume that it is an \fIinput fileglob string\fR. The |
259 | input is the list of files that match the fileglob. |
260 | .Sp |
261 | If the fileglob does not match any files ... |
262 | .Sp |
263 | See File::GlobMapper for more details. |
264 | .PP |
265 | If the \f(CW$input\fR parameter is any other type, \f(CW\*(C`undef\*(C'\fR will be returned. |
266 | .PP |
267 | \fIThe \f(CI$output\fI parameter\fR |
268 | .IX Subsection "The $output parameter" |
269 | .PP |
270 | The parameter \f(CW$output\fR is used to control the destination of the |
271 | uncompressed data. This parameter can take one of these forms. |
272 | .IP "A filename" 5 |
273 | .IX Item "A filename" |
274 | If the \f(CW$output\fR parameter is a simple scalar, it is assumed to be a |
275 | filename. This file will be opened for writing and the uncompressed |
276 | data will be written to it. |
277 | .IP "A filehandle" 5 |
278 | .IX Item "A filehandle" |
279 | If the \f(CW$output\fR parameter is a filehandle, the uncompressed data |
280 | will be written to it. |
281 | The string '\-' can be used as an alias for standard output. |
282 | .IP "A scalar reference" 5 |
283 | .IX Item "A scalar reference" |
284 | If \f(CW$output\fR is a scalar reference, the uncompressed data will be |
285 | stored in \f(CW$$output\fR. |
286 | .IP "An Array Reference" 5 |
287 | .IX Item "An Array Reference" |
288 | If \f(CW$output\fR is an array reference, the uncompressed data will be |
289 | pushed onto the array. |
290 | .IP "An Output FileGlob" 5 |
291 | .IX Item "An Output FileGlob" |
292 | If \f(CW$output\fR is a string that is delimited by the characters \*(L"<\*(R" and \*(L">\*(R" |
293 | \&\f(CW\*(C`inflate\*(C'\fR will assume that it is an \fIoutput fileglob string\fR. The |
294 | output is the list of files that match the fileglob. |
295 | .Sp |
296 | When \f(CW$output\fR is an fileglob string, \f(CW$input\fR must also be a fileglob |
297 | string. Anything else is an error. |
298 | .PP |
299 | If the \f(CW$output\fR parameter is any other type, \f(CW\*(C`undef\*(C'\fR will be returned. |
300 | .Sh "Notes" |
301 | .IX Subsection "Notes" |
302 | When \f(CW$input\fR maps to multiple compressed files/buffers and \f(CW$output\fR is |
303 | a single file/buffer, after uncompression \f(CW$output\fR will contain a |
304 | concatenation of all the uncompressed data from each of the input |
305 | files/buffers. |
306 | .Sh "Optional Parameters" |
307 | .IX Subsection "Optional Parameters" |
308 | Unless specified below, the optional parameters for \f(CW\*(C`inflate\*(C'\fR, |
309 | \&\f(CW\*(C`OPTS\*(C'\fR, are the same as those used with the \s-1OO\s0 interface defined in the |
310 | \&\*(L"Constructor Options\*(R" section below. |
311 | .ie n .IP """AutoClose => 0|1""" 5 |
312 | .el .IP "\f(CWAutoClose => 0|1\fR" 5 |
313 | .IX Item "AutoClose => 0|1" |
314 | This option applies to any input or output data streams to |
315 | \&\f(CW\*(C`inflate\*(C'\fR that are filehandles. |
316 | .Sp |
317 | If \f(CW\*(C`AutoClose\*(C'\fR is specified, and the value is true, it will result in all |
318 | input and/or output filehandles being closed once \f(CW\*(C`inflate\*(C'\fR has |
319 | completed. |
320 | .Sp |
321 | This parameter defaults to 0. |
322 | .ie n .IP """BinModeOut => 0|1""" 5 |
323 | .el .IP "\f(CWBinModeOut => 0|1\fR" 5 |
324 | .IX Item "BinModeOut => 0|1" |
325 | When writing to a file or filehandle, set \f(CW\*(C`binmode\*(C'\fR before writing to the |
326 | file. |
327 | .Sp |
328 | Defaults to 0. |
329 | .ie n .IP """Append => 0|1""" 5 |
330 | .el .IP "\f(CWAppend => 0|1\fR" 5 |
331 | .IX Item "Append => 0|1" |
332 | The behaviour of this option is dependent on the type of output data |
333 | stream. |
334 | .RS 5 |
335 | .IP "* A Buffer" 5 |
336 | .IX Item "A Buffer" |
337 | If \f(CW\*(C`Append\*(C'\fR is enabled, all uncompressed data will be append to the end of |
338 | the output buffer. Otherwise the output buffer will be cleared before any |
339 | uncompressed data is written to it. |
340 | .IP "* A Filename" 5 |
341 | .IX Item "A Filename" |
342 | If \f(CW\*(C`Append\*(C'\fR is enabled, the file will be opened in append mode. Otherwise |
343 | the contents of the file, if any, will be truncated before any uncompressed |
344 | data is written to it. |
345 | .IP "* A Filehandle" 5 |
346 | .IX Item "A Filehandle" |
347 | If \f(CW\*(C`Append\*(C'\fR is enabled, the filehandle will be positioned to the end of |
348 | the file via a call to \f(CW\*(C`seek\*(C'\fR before any uncompressed data is |
349 | written to it. Otherwise the file pointer will not be moved. |
350 | .RE |
351 | .RS 5 |
352 | .Sp |
353 | When \f(CW\*(C`Append\*(C'\fR is specified, and set to true, it will \fIappend\fR all uncompressed |
354 | data to the output data stream. |
355 | .Sp |
356 | So when the output is a filehandle it will carry out a seek to the eof |
357 | before writing any uncompressed data. If the output is a filename, it will be opened for |
358 | appending. If the output is a buffer, all uncompressed data will be appened to |
359 | the existing buffer. |
360 | .Sp |
361 | Conversely when \f(CW\*(C`Append\*(C'\fR is not specified, or it is present and is set to |
362 | false, it will operate as follows. |
363 | .Sp |
364 | When the output is a filename, it will truncate the contents of the file |
365 | before writing any uncompressed data. If the output is a filehandle |
366 | its position will not be changed. If the output is a buffer, it will be |
367 | wiped before any uncompressed data is output. |
368 | .Sp |
369 | Defaults to 0. |
370 | .RE |
371 | .ie n .IP """MultiStream => 0|1""" 5 |
372 | .el .IP "\f(CWMultiStream => 0|1\fR" 5 |
373 | .IX Item "MultiStream => 0|1" |
374 | If the input file/buffer contains multiple compressed data streams, this |
375 | option will uncompress the whole lot as a single data stream. |
376 | .Sp |
377 | Defaults to 0. |
378 | .ie n .IP """TrailingData => $scalar""" 5 |
379 | .el .IP "\f(CWTrailingData => $scalar\fR" 5 |
380 | .IX Item "TrailingData => $scalar" |
381 | Returns the data, if any, that is present immediately after the compressed |
382 | data stream once uncompression is complete. |
383 | .Sp |
384 | This option can be used when there is useful information immediately |
385 | following the compressed data stream, and you don't know the length of the |
386 | compressed data stream. |
387 | .Sp |
388 | If the input is a buffer, \f(CW\*(C`trailingData\*(C'\fR will return everything from the |
389 | end of the compressed data stream to the end of the buffer. |
390 | .Sp |
391 | If the input is a filehandle, \f(CW\*(C`trailingData\*(C'\fR will return the data that is |
392 | left in the filehandle input buffer once the end of the compressed data |
393 | stream has been reached. You can then use the filehandle to read the rest |
394 | of the input file. |
395 | .Sp |
396 | Don't bother using \f(CW\*(C`trailingData\*(C'\fR if the input is a filename. |
397 | .Sp |
398 | If you know the length of the compressed data stream before you start |
399 | uncompressing, you can avoid having to use \f(CW\*(C`trailingData\*(C'\fR by setting the |
400 | \&\f(CW\*(C`InputLength\*(C'\fR option. |
401 | .Sh "Examples" |
402 | .IX Subsection "Examples" |
403 | To read the contents of the file \f(CW\*(C`file1.txt.1950\*(C'\fR and write the |
404 | uncompressed data to the file \f(CW\*(C`file1.txt\*(C'\fR. |
405 | .PP |
406 | .Vb 3 |
407 | \& use strict ; |
408 | \& use warnings ; |
409 | \& use IO::Uncompress::Inflate qw(inflate $InflateError) ; |
410 | .Ve |
411 | .PP |
412 | .Vb 4 |
413 | \& my $input = "file1.txt.1950"; |
414 | \& my $output = "file1.txt"; |
415 | \& inflate $input => $output |
416 | \& or die "inflate failed: $InflateError\en"; |
417 | .Ve |
418 | .PP |
419 | To read from an existing Perl filehandle, \f(CW$input\fR, and write the |
420 | uncompressed data to a buffer, \f(CW$buffer\fR. |
421 | .PP |
422 | .Vb 4 |
423 | \& use strict ; |
424 | \& use warnings ; |
425 | \& use IO::Uncompress::Inflate qw(inflate $InflateError) ; |
426 | \& use IO::File ; |
427 | .Ve |
428 | .PP |
429 | .Vb 5 |
430 | \& my $input = new IO::File "<file1.txt.1950" |
431 | \& or die "Cannot open 'file1.txt.1950': $!\en" ; |
432 | \& my $buffer ; |
433 | \& inflate $input => \e$buffer |
434 | \& or die "inflate failed: $InflateError\en"; |
435 | .Ve |
436 | .PP |
437 | To uncompress all files in the directory \*(L"/my/home\*(R" that match \*(L"*.txt.1950\*(R" and store the compressed data in the same directory |
438 | .PP |
439 | .Vb 3 |
440 | \& use strict ; |
441 | \& use warnings ; |
442 | \& use IO::Uncompress::Inflate qw(inflate $InflateError) ; |
443 | .Ve |
444 | .PP |
445 | .Vb 2 |
446 | \& inflate '</my/home/*.txt.1950>' => '</my/home/#1.txt>' |
447 | \& or die "inflate failed: $InflateError\en"; |
448 | .Ve |
449 | .PP |
450 | and if you want to compress each file one at a time, this will do the trick |
451 | .PP |
452 | .Vb 3 |
453 | \& use strict ; |
454 | \& use warnings ; |
455 | \& use IO::Uncompress::Inflate qw(inflate $InflateError) ; |
456 | .Ve |
457 | .PP |
458 | .Vb 7 |
459 | \& for my $input ( glob "/my/home/*.txt.1950" ) |
460 | \& { |
461 | \& my $output = $input; |
462 | \& $output =~ s/.1950// ; |
463 | \& inflate $input => $output |
464 | \& or die "Error compressing '$input': $InflateError\en"; |
465 | \& } |
466 | .Ve |
467 | .SH "OO Interface" |
468 | .IX Header "OO Interface" |
469 | .Sh "Constructor" |
470 | .IX Subsection "Constructor" |
471 | The format of the constructor for IO::Uncompress::Inflate is shown below |
472 | .PP |
473 | .Vb 2 |
474 | \& my $z = new IO::Uncompress::Inflate $input [OPTS] |
475 | \& or die "IO::Uncompress::Inflate failed: $InflateError\en"; |
476 | .Ve |
477 | .PP |
478 | Returns an \f(CW\*(C`IO::Uncompress::Inflate\*(C'\fR object on success and undef on failure. |
479 | The variable \f(CW$InflateError\fR will contain an error message on failure. |
480 | .PP |
481 | If you are running Perl 5.005 or better the object, \f(CW$z\fR, returned from |
482 | IO::Uncompress::Inflate can be used exactly like an IO::File filehandle. |
483 | This means that all normal input file operations can be carried out with |
484 | \&\f(CW$z\fR. For example, to read a line from a compressed file/buffer you can |
485 | use either of these forms |
486 | .PP |
487 | .Vb 2 |
488 | \& $line = $z\->getline(); |
489 | \& $line = <$z>; |
490 | .Ve |
491 | .PP |
492 | The mandatory parameter \f(CW$input\fR is used to determine the source of the |
493 | compressed data. This parameter can take one of three forms. |
494 | .IP "A filename" 5 |
495 | .IX Item "A filename" |
496 | If the \f(CW$input\fR parameter is a scalar, it is assumed to be a filename. This |
497 | file will be opened for reading and the compressed data will be read from it. |
498 | .IP "A filehandle" 5 |
499 | .IX Item "A filehandle" |
500 | If the \f(CW$input\fR parameter is a filehandle, the compressed data will be |
501 | read from it. |
502 | The string '\-' can be used as an alias for standard input. |
503 | .IP "A scalar reference" 5 |
504 | .IX Item "A scalar reference" |
505 | If \f(CW$input\fR is a scalar reference, the compressed data will be read from |
506 | \&\f(CW$$output\fR. |
507 | .Sh "Constructor Options" |
508 | .IX Subsection "Constructor Options" |
509 | The option names defined below are case insensitive and can be optionally |
510 | prefixed by a '\-'. So all of the following are valid |
511 | .PP |
512 | .Vb 4 |
513 | \& \-AutoClose |
514 | \& \-autoclose |
515 | \& AUTOCLOSE |
516 | \& autoclose |
517 | .Ve |
518 | .PP |
519 | \&\s-1OPTS\s0 is a combination of the following options: |
520 | .ie n .IP """AutoClose => 0|1""" 5 |
521 | .el .IP "\f(CWAutoClose => 0|1\fR" 5 |
522 | .IX Item "AutoClose => 0|1" |
523 | This option is only valid when the \f(CW$input\fR parameter is a filehandle. If |
524 | specified, and the value is true, it will result in the file being closed once |
525 | either the \f(CW\*(C`close\*(C'\fR method is called or the IO::Uncompress::Inflate object is |
526 | destroyed. |
527 | .Sp |
528 | This parameter defaults to 0. |
529 | .ie n .IP """MultiStream => 0|1""" 5 |
530 | .el .IP "\f(CWMultiStream => 0|1\fR" 5 |
531 | .IX Item "MultiStream => 0|1" |
532 | Allows multiple concatenated compressed streams to be treated as a single |
533 | compressed stream. Decompression will stop once either the end of the |
534 | file/buffer is reached, an error is encountered (premature eof, corrupt |
535 | compressed data) or the end of a stream is not immediately followed by the |
536 | start of another stream. |
537 | .Sp |
538 | This parameter defaults to 0. |
539 | .ie n .IP """Prime => $string""" 5 |
540 | .el .IP "\f(CWPrime => $string\fR" 5 |
541 | .IX Item "Prime => $string" |
542 | This option will uncompress the contents of \f(CW$string\fR before processing the |
543 | input file/buffer. |
544 | .Sp |
545 | This option can be useful when the compressed data is embedded in another |
546 | file/data structure and it is not possible to work out where the compressed |
547 | data begins without having to read the first few bytes. If this is the |
548 | case, the uncompression can be \fIprimed\fR with these bytes using this |
549 | option. |
550 | .ie n .IP """Transparent => 0|1""" 5 |
551 | .el .IP "\f(CWTransparent => 0|1\fR" 5 |
552 | .IX Item "Transparent => 0|1" |
553 | If this option is set and the input file/buffer is not compressed data, |
554 | the module will allow reading of it anyway. |
555 | .Sp |
556 | In addition, if the input file/buffer does contain compressed data and |
557 | there is non-compressed data immediately following it, setting this option |
558 | will make this module treat the whole file/bufffer as a single data stream. |
559 | .Sp |
560 | This option defaults to 1. |
561 | .ie n .IP """BlockSize => $num""" 5 |
562 | .el .IP "\f(CWBlockSize => $num\fR" 5 |
563 | .IX Item "BlockSize => $num" |
564 | When reading the compressed input data, IO::Uncompress::Inflate will read it in |
565 | blocks of \f(CW$num\fR bytes. |
566 | .Sp |
567 | This option defaults to 4096. |
568 | .ie n .IP """InputLength => $size""" 5 |
569 | .el .IP "\f(CWInputLength => $size\fR" 5 |
570 | .IX Item "InputLength => $size" |
571 | When present this option will limit the number of compressed bytes read |
572 | from the input file/buffer to \f(CW$size\fR. This option can be used in the |
573 | situation where there is useful data directly after the compressed data |
574 | stream and you know beforehand the exact length of the compressed data |
575 | stream. |
576 | .Sp |
577 | This option is mostly used when reading from a filehandle, in which case |
578 | the file pointer will be left pointing to the first byte directly after the |
579 | compressed data stream. |
580 | .Sp |
581 | This option defaults to off. |
582 | .ie n .IP """Append => 0|1""" 5 |
583 | .el .IP "\f(CWAppend => 0|1\fR" 5 |
584 | .IX Item "Append => 0|1" |
585 | This option controls what the \f(CW\*(C`read\*(C'\fR method does with uncompressed data. |
586 | .Sp |
587 | If set to 1, all uncompressed data will be appended to the output parameter |
588 | of the \f(CW\*(C`read\*(C'\fR method. |
589 | .Sp |
590 | If set to 0, the contents of the output parameter of the \f(CW\*(C`read\*(C'\fR method |
591 | will be overwritten by the uncompressed data. |
592 | .Sp |
593 | Defaults to 0. |
594 | .ie n .IP """Strict => 0|1""" 5 |
595 | .el .IP "\f(CWStrict => 0|1\fR" 5 |
596 | .IX Item "Strict => 0|1" |
597 | This option controls whether the extra checks defined below are used when |
598 | carrying out the decompression. When Strict is on, the extra tests are |
599 | carried out, when Strict is off they are not. |
600 | .Sp |
601 | The default for this option is off. |
602 | .RS 5 |
603 | .IP "1" 5 |
604 | .IX Item "1" |
605 | The \s-1ADLER32\s0 checksum field must be present. |
606 | .IP "2" 5 |
607 | .IX Item "2" |
608 | The value of the \s-1ADLER32\s0 field read must match the adler32 value of the |
609 | uncompressed data actually contained in the file. |
610 | .RE |
611 | .RS 5 |
612 | .RE |
613 | .Sh "Examples" |
614 | .IX Subsection "Examples" |
615 | \&\s-1TODO\s0 |
616 | .SH "Methods" |
617 | .IX Header "Methods" |
618 | .Sh "read" |
619 | .IX Subsection "read" |
620 | Usage is |
621 | .PP |
622 | .Vb 1 |
623 | \& $status = $z\->read($buffer) |
624 | .Ve |
625 | .PP |
626 | Reads a block of compressed data (the size the the compressed block is |
627 | determined by the \f(CW\*(C`Buffer\*(C'\fR option in the constructor), uncompresses it and |
628 | writes any uncompressed data into \f(CW$buffer\fR. If the \f(CW\*(C`Append\*(C'\fR parameter is |
629 | set in the constructor, the uncompressed data will be appended to the |
630 | \&\f(CW$buffer\fR parameter. Otherwise \f(CW$buffer\fR will be overwritten. |
631 | .PP |
632 | Returns the number of uncompressed bytes written to \f(CW$buffer\fR, zero if eof |
633 | or a negative number on error. |
634 | .Sh "read" |
635 | .IX Subsection "read" |
636 | Usage is |
637 | .PP |
638 | .Vb 2 |
639 | \& $status = $z\->read($buffer, $length) |
640 | \& $status = $z\->read($buffer, $length, $offset) |
641 | .Ve |
642 | .PP |
643 | .Vb 2 |
644 | \& $status = read($z, $buffer, $length) |
645 | \& $status = read($z, $buffer, $length, $offset) |
646 | .Ve |
647 | .PP |
648 | Attempt to read \f(CW$length\fR bytes of uncompressed data into \f(CW$buffer\fR. |
649 | .PP |
650 | The main difference between this form of the \f(CW\*(C`read\*(C'\fR method and the |
651 | previous one, is that this one will attempt to return \fIexactly\fR \f(CW$length\fR |
652 | bytes. The only circumstances that this function will not is if end-of-file |
653 | or an \s-1IO\s0 error is encountered. |
654 | .PP |
655 | Returns the number of uncompressed bytes written to \f(CW$buffer\fR, zero if eof |
656 | or a negative number on error. |
657 | .Sh "getline" |
658 | .IX Subsection "getline" |
659 | Usage is |
660 | .PP |
661 | .Vb 2 |
662 | \& $line = $z\->getline() |
663 | \& $line = <$z> |
664 | .Ve |
665 | .PP |
666 | Reads a single line. |
667 | .PP |
668 | This method fully supports the use of of the variable \f(CW$/\fR (or |
669 | \&\f(CW$INPUT_RECORD_SEPARATOR\fR or \f(CW$RS\fR when \f(CW\*(C`English\*(C'\fR is in use) to |
670 | determine what constitutes an end of line. Paragraph mode, record mode and |
671 | file slurp mode are all supported. |
672 | .Sh "getc" |
673 | .IX Subsection "getc" |
674 | Usage is |
675 | .PP |
676 | .Vb 1 |
677 | \& $char = $z\->getc() |
678 | .Ve |
679 | .PP |
680 | Read a single character. |
681 | .Sh "ungetc" |
682 | .IX Subsection "ungetc" |
683 | Usage is |
684 | .PP |
685 | .Vb 1 |
686 | \& $char = $z\->ungetc($string) |
687 | .Ve |
688 | .Sh "inflateSync" |
689 | .IX Subsection "inflateSync" |
690 | Usage is |
691 | .PP |
692 | .Vb 1 |
693 | \& $status = $z\->inflateSync() |
694 | .Ve |
695 | .PP |
696 | \&\s-1TODO\s0 |
697 | .Sh "getHeaderInfo" |
698 | .IX Subsection "getHeaderInfo" |
699 | Usage is |
700 | .PP |
701 | .Vb 2 |
702 | \& $hdr = $z\->getHeaderInfo(); |
703 | \& @hdrs = $z\->getHeaderInfo(); |
704 | .Ve |
705 | .PP |
706 | This method returns either a hash reference (in scalar context) or a list |
707 | or hash references (in array context) that contains information about each |
708 | of the header fields in the compressed data stream(s). |
709 | .Sh "tell" |
710 | .IX Subsection "tell" |
711 | Usage is |
712 | .PP |
713 | .Vb 2 |
714 | \& $z\->tell() |
715 | \& tell $z |
716 | .Ve |
717 | .PP |
718 | Returns the uncompressed file offset. |
719 | .Sh "eof" |
720 | .IX Subsection "eof" |
721 | Usage is |
722 | .PP |
723 | .Vb 2 |
724 | \& $z\->eof(); |
725 | \& eof($z); |
726 | .Ve |
727 | .PP |
728 | Returns true if the end of the compressed input stream has been reached. |
729 | .Sh "seek" |
730 | .IX Subsection "seek" |
731 | .Vb 2 |
732 | \& $z\->seek($position, $whence); |
733 | \& seek($z, $position, $whence); |
734 | .Ve |
735 | .PP |
736 | Provides a sub-set of the \f(CW\*(C`seek\*(C'\fR functionality, with the restriction |
737 | that it is only legal to seek forward in the input file/buffer. |
738 | It is a fatal error to attempt to seek backward. |
739 | .PP |
740 | The \f(CW$whence\fR parameter takes one the usual values, namely \s-1SEEK_SET\s0, |
741 | \&\s-1SEEK_CUR\s0 or \s-1SEEK_END\s0. |
742 | .PP |
743 | Returns 1 on success, 0 on failure. |
744 | .Sh "binmode" |
745 | .IX Subsection "binmode" |
746 | Usage is |
747 | .PP |
748 | .Vb 2 |
749 | \& $z\->binmode |
750 | \& binmode $z ; |
751 | .Ve |
752 | .PP |
753 | This is a noop provided for completeness. |
754 | .Sh "opened" |
755 | .IX Subsection "opened" |
756 | .Vb 1 |
757 | \& $z\->opened() |
758 | .Ve |
759 | .PP |
760 | Returns true if the object currently refers to a opened file/buffer. |
761 | .Sh "autoflush" |
762 | .IX Subsection "autoflush" |
763 | .Vb 2 |
764 | \& my $prev = $z\->autoflush() |
765 | \& my $prev = $z\->autoflush(EXPR) |
766 | .Ve |
767 | .PP |
768 | If the \f(CW$z\fR object is associated with a file or a filehandle, this method |
769 | returns the current autoflush setting for the underlying filehandle. If |
770 | \&\f(CW\*(C`EXPR\*(C'\fR is present, and is non\-zero, it will enable flushing after every |
771 | write/print operation. |
772 | .PP |
773 | If \f(CW$z\fR is associated with a buffer, this method has no effect and always |
774 | returns \f(CW\*(C`undef\*(C'\fR. |
775 | .PP |
776 | \&\fBNote\fR that the special variable \f(CW$|\fR \fBcannot\fR be used to set or |
777 | retrieve the autoflush setting. |
778 | .Sh "input_line_number" |
779 | .IX Subsection "input_line_number" |
780 | .Vb 2 |
781 | \& $z\->input_line_number() |
782 | \& $z\->input_line_number(EXPR) |
783 | .Ve |
784 | .PP |
785 | Returns the current uncompressed line number. If \f(CW\*(C`EXPR\*(C'\fR is present it has |
786 | the effect of setting the line number. Note that setting the line number |
787 | does not change the current position within the file/buffer being read. |
788 | .PP |
789 | The contents of \f(CW$/\fR are used to to determine what constitutes a line |
790 | terminator. |
791 | .Sh "fileno" |
792 | .IX Subsection "fileno" |
793 | .Vb 2 |
794 | \& $z\->fileno() |
795 | \& fileno($z) |
796 | .Ve |
797 | .PP |
798 | If the \f(CW$z\fR object is associated with a file or a filehandle, \f(CW\*(C`fileno\*(C'\fR |
799 | will return the underlying file descriptor. Once the \f(CW\*(C`close\*(C'\fR method is |
800 | called \f(CW\*(C`fileno\*(C'\fR will return \f(CW\*(C`undef\*(C'\fR. |
801 | .PP |
802 | If the \f(CW$z\fR object is is associated with a buffer, this method will return |
803 | \&\f(CW\*(C`undef\*(C'\fR. |
804 | .Sh "close" |
805 | .IX Subsection "close" |
806 | .Vb 2 |
807 | \& $z\->close() ; |
808 | \& close $z ; |
809 | .Ve |
810 | .PP |
811 | Closes the output file/buffer. |
812 | .PP |
813 | For most versions of Perl this method will be automatically invoked if |
814 | the IO::Uncompress::Inflate object is destroyed (either explicitly or by the |
815 | variable with the reference to the object going out of scope). The |
816 | exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In |
817 | these cases, the \f(CW\*(C`close\*(C'\fR method will be called automatically, but |
818 | not until global destruction of all live objects when the program is |
819 | terminating. |
820 | .PP |
821 | Therefore, if you want your scripts to be able to run on all versions |
822 | of Perl, you should call \f(CW\*(C`close\*(C'\fR explicitly and not rely on automatic |
823 | closing. |
824 | .PP |
825 | Returns true on success, otherwise 0. |
826 | .PP |
827 | If the \f(CW\*(C`AutoClose\*(C'\fR option has been enabled when the IO::Uncompress::Inflate |
828 | object was created, and the object is associated with a file, the |
829 | underlying file will also be closed. |
830 | .Sh "nextStream" |
831 | .IX Subsection "nextStream" |
832 | Usage is |
833 | .PP |
834 | .Vb 1 |
835 | \& my $status = $z\->nextStream(); |
836 | .Ve |
837 | .PP |
838 | Skips to the next compressed data stream in the input file/buffer. If a new |
839 | compressed data stream is found, the eof marker will be cleared and \f(CW$.\fR |
840 | will be reset to 0. |
841 | .PP |
842 | Returns 1 if a new stream was found, 0 if none was found, and \-1 if an |
843 | error was encountered. |
844 | .Sh "trailingData" |
845 | .IX Subsection "trailingData" |
846 | Usage is |
847 | .PP |
848 | .Vb 1 |
849 | \& my $data = $z\->trailingData(); |
850 | .Ve |
851 | .PP |
852 | Returns the data, if any, that is present immediately after the compressed |
853 | data stream once uncompression is complete. It only makes sense to call |
854 | this method once the end of the compressed data stream has been |
855 | encountered. |
856 | .PP |
857 | This option can be used when there is useful information immediately |
858 | following the compressed data stream, and you don't know the length of the |
859 | compressed data stream. |
860 | .PP |
861 | If the input is a buffer, \f(CW\*(C`trailingData\*(C'\fR will return everything from the |
862 | end of the compressed data stream to the end of the buffer. |
863 | .PP |
864 | If the input is a filehandle, \f(CW\*(C`trailingData\*(C'\fR will return the data that is |
865 | left in the filehandle input buffer once the end of the compressed data |
866 | stream has been reached. You can then use the filehandle to read the rest |
867 | of the input file. |
868 | .PP |
869 | Don't bother using \f(CW\*(C`trailingData\*(C'\fR if the input is a filename. |
870 | .PP |
871 | If you know the length of the compressed data stream before you start |
872 | uncompressing, you can avoid having to use \f(CW\*(C`trailingData\*(C'\fR by setting the |
873 | \&\f(CW\*(C`InputLength\*(C'\fR option in the constructor. |
874 | .SH "Importing" |
875 | .IX Header "Importing" |
876 | No symbolic constants are required by this IO::Uncompress::Inflate at present. |
877 | .IP ":all" 5 |
878 | .IX Item ":all" |
879 | Imports \f(CW\*(C`inflate\*(C'\fR and \f(CW$InflateError\fR. |
880 | Same as doing this |
881 | .Sp |
882 | .Vb 1 |
883 | \& use IO::Uncompress::Inflate qw(inflate $InflateError) ; |
884 | .Ve |
885 | .SH "EXAMPLES" |
886 | .IX Header "EXAMPLES" |
887 | .Sh "Working with Net::FTP" |
888 | .IX Subsection "Working with Net::FTP" |
889 | See IO::Uncompress::Inflate::FAQ |
890 | .SH "SEE ALSO" |
891 | .IX Header "SEE ALSO" |
892 | Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, IO::Compress::Deflate, IO::Compress::RawDeflate, IO::Uncompress::RawInflate, IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress |
893 | .PP |
894 | Compress::Zlib::FAQ |
895 | .PP |
896 | File::GlobMapper, Archive::Zip, |
897 | Archive::Tar, |
898 | IO::Zlib |
899 | .PP |
900 | For \s-1RFC\s0 1950, 1951 and 1952 see |
901 | \&\fIhttp://www.faqs.org/rfcs/rfc1950.html\fR, |
902 | \&\fIhttp://www.faqs.org/rfcs/rfc1951.html\fR and |
903 | \&\fIhttp://www.faqs.org/rfcs/rfc1952.html\fR |
904 | .PP |
905 | The \fIzlib\fR compression library was written by Jean-loup Gailly |
906 | \&\fIgzip@prep.ai.mit.edu\fR and Mark Adler \fImadler@alumni.caltech.edu\fR. |
907 | .PP |
908 | The primary site for the \fIzlib\fR compression library is |
909 | \&\fIhttp://www.zlib.org\fR. |
910 | .PP |
911 | The primary site for gzip is \fIhttp://www.gzip.org\fR. |
912 | .SH "AUTHOR" |
913 | .IX Header "AUTHOR" |
914 | This module was written by Paul Marquess, \fIpmqs@cpan.org\fR. |
915 | .SH "MODIFICATION HISTORY" |
916 | .IX Header "MODIFICATION HISTORY" |
917 | See the Changes file. |
918 | .SH "COPYRIGHT AND LICENSE" |
919 | .IX Header "COPYRIGHT AND LICENSE" |
920 | Copyright (c) 2005\-2009 Paul Marquess. All rights reserved. |
921 | .PP |
922 | This program is free software; you can redistribute it and/or |
923 | modify it under the same terms as Perl itself. |