1IO::Uncompress::UnLzip(U3s)er Contributed Perl DocumentatIiOo:n:Uncompress::UnLzip(3)
2
3
4
6 IO::Uncompress::UnLzip - Read lzip files/buffers
7
9 use IO::Uncompress::UnLzip qw(unlzip $UnLzipError) ;
10
11 my $status = unlzip $input => $output [,OPTS]
12 or die "unlzip failed: $UnLzipError\n";
13
14 my $z = new IO::Uncompress::UnLzip $input [OPTS]
15 or die "unlzip failed: $UnLzipError\n";
16
17 $status = $z->read($buffer)
18 $status = $z->read($buffer, $length)
19 $status = $z->read($buffer, $length, $offset)
20 $line = $z->getline()
21 $char = $z->getc()
22 $char = $z->ungetc()
23 $char = $z->opened()
24
25 $data = $z->trailingData()
26 $status = $z->nextStream()
27 $data = $z->getHeaderInfo()
28 $z->tell()
29 $z->seek($position, $whence)
30 $z->binmode()
31 $z->fileno()
32 $z->eof()
33 $z->close()
34
35 $UnLzipError ;
36
37 # IO::File mode
38
39 <$z>
40 read($z, $buffer);
41 read($z, $buffer, $length);
42 read($z, $buffer, $length, $offset);
43 tell($z)
44 seek($z, $position, $whence)
45 binmode($z)
46 fileno($z)
47 eof($z)
48 close($z)
49
51 This module provides a Perl interface that allows the reading of lzma
52 files/buffers.
53
54 For writing lzip files/buffers, see the companion module
55 IO::Compress::Lzip.
56
58 A top-level function, "unlzip", is provided to carry out "one-shot"
59 uncompression between buffers and/or files. For finer control over the
60 uncompression process, see the "OO Interface" section.
61
62 use IO::Uncompress::UnLzip qw(unlzip $UnLzipError) ;
63
64 unlzip $input_filename_or_reference => $output_filename_or_reference [,OPTS]
65 or die "unlzip failed: $UnLzipError\n";
66
67 The functional interface needs Perl5.005 or better.
68
69 unlzip $input_filename_or_reference => $output_filename_or_reference [,
70 OPTS]
71 "unlzip" expects at least two parameters, $input_filename_or_reference
72 and $output_filename_or_reference.
73
74 The $input_filename_or_reference parameter
75
76 The parameter, $input_filename_or_reference, is used to define the
77 source of the compressed data.
78
79 It can take one of the following forms:
80
81 A filename
82 If the <$input_filename_or_reference> parameter is a simple
83 scalar, it is assumed to be a filename. This file will be opened
84 for reading and the input data will be read from it.
85
86 A filehandle
87 If the $input_filename_or_reference parameter is a filehandle, the
88 input data will be read from it. The string '-' can be used as an
89 alias for standard input.
90
91 A scalar reference
92 If $input_filename_or_reference is a scalar reference, the input
93 data will be read from $$input_filename_or_reference.
94
95 An array reference
96 If $input_filename_or_reference is an array reference, each
97 element in the array must be a filename.
98
99 The input data will be read from each file in turn.
100
101 The complete array will be walked to ensure that it only contains
102 valid filenames before any data is uncompressed.
103
104 An Input FileGlob string
105 If $input_filename_or_reference is a string that is delimited by
106 the characters "<" and ">" "unlzip" will assume that it is an
107 input fileglob string. The input is the list of files that match
108 the fileglob.
109
110 See File::GlobMapper for more details.
111
112 If the $input_filename_or_reference parameter is any other type,
113 "undef" will be returned.
114
115 The $output_filename_or_reference parameter
116
117 The parameter $output_filename_or_reference is used to control the
118 destination of the uncompressed data. This parameter can take one of
119 these forms.
120
121 A filename
122 If the $output_filename_or_reference parameter is a simple scalar,
123 it is assumed to be a filename. This file will be opened for
124 writing and the uncompressed data will be written to it.
125
126 A filehandle
127 If the $output_filename_or_reference parameter is a filehandle,
128 the uncompressed data will be written to it. The string '-' can
129 be used as an alias for standard output.
130
131 A scalar reference
132 If $output_filename_or_reference is a scalar reference, the
133 uncompressed data will be stored in
134 $$output_filename_or_reference.
135
136 An Array Reference
137 If $output_filename_or_reference is an array reference, the
138 uncompressed data will be pushed onto the array.
139
140 An Output FileGlob
141 If $output_filename_or_reference is a string that is delimited by
142 the characters "<" and ">" "unlzip" will assume that it is an
143 output fileglob string. The output is the list of files that match
144 the fileglob.
145
146 When $output_filename_or_reference is an fileglob string,
147 $input_filename_or_reference must also be a fileglob string.
148 Anything else is an error.
149
150 See File::GlobMapper for more details.
151
152 If the $output_filename_or_reference parameter is any other type,
153 "undef" will be returned.
154
155 Notes
156 When $input_filename_or_reference maps to multiple compressed
157 files/buffers and $output_filename_or_reference is a single
158 file/buffer, after uncompression $output_filename_or_reference will
159 contain a concatenation of all the uncompressed data from each of the
160 input files/buffers.
161
162 Optional Parameters
163 Unless specified below, the optional parameters for "unlzip", "OPTS",
164 are the same as those used with the OO interface defined in the
165 "Constructor Options" section below.
166
167 "AutoClose => 0|1"
168 This option applies to any input or output data streams to
169 "unlzip" that are filehandles.
170
171 If "AutoClose" is specified, and the value is true, it will result
172 in all input and/or output filehandles being closed once "unlzip"
173 has completed.
174
175 This parameter defaults to 0.
176
177 "BinModeOut => 0|1"
178 This option is now a no-op. All files will be written in binmode.
179
180 "Append => 0|1"
181 The behaviour of this option is dependent on the type of output
182 data stream.
183
184 · A Buffer
185
186 If "Append" is enabled, all uncompressed data will be append
187 to the end of the output buffer. Otherwise the output buffer
188 will be cleared before any uncompressed data is written to
189 it.
190
191 · A Filename
192
193 If "Append" is enabled, the file will be opened in append
194 mode. Otherwise the contents of the file, if any, will be
195 truncated before any uncompressed data is written to it.
196
197 · A Filehandle
198
199 If "Append" is enabled, the filehandle will be positioned to
200 the end of the file via a call to "seek" before any
201 uncompressed data is written to it. Otherwise the file
202 pointer will not be moved.
203
204 When "Append" is specified, and set to true, it will append all
205 uncompressed data to the output data stream.
206
207 So when the output is a filehandle it will carry out a seek to the
208 eof before writing any uncompressed data. If the output is a
209 filename, it will be opened for appending. If the output is a
210 buffer, all uncompressed data will be appended to the existing
211 buffer.
212
213 Conversely when "Append" is not specified, or it is present and is
214 set to false, it will operate as follows.
215
216 When the output is a filename, it will truncate the contents of
217 the file before writing any uncompressed data. If the output is a
218 filehandle its position will not be changed. If the output is a
219 buffer, it will be wiped before any uncompressed data is output.
220
221 Defaults to 0.
222
223 "MultiStream => 0|1"
224 If the input file/buffer contains multiple compressed data
225 streams, this option will uncompress the whole lot as a single
226 data stream.
227
228 Defaults to 0.
229
230 "TrailingData => $scalar"
231 Returns the data, if any, that is present immediately after the
232 compressed data stream once uncompression is complete.
233
234 This option can be used when there is useful information
235 immediately following the compressed data stream, and you don't
236 know the length of the compressed data stream.
237
238 If the input is a buffer, "trailingData" will return everything
239 from the end of the compressed data stream to the end of the
240 buffer.
241
242 If the input is a filehandle, "trailingData" will return the data
243 that is left in the filehandle input buffer once the end of the
244 compressed data stream has been reached. You can then use the
245 filehandle to read the rest of the input file.
246
247 Don't bother using "trailingData" if the input is a filename.
248
249 If you know the length of the compressed data stream before you
250 start uncompressing, you can avoid having to use "trailingData" by
251 setting the "InputLength" option.
252
253 Examples
254 To read the contents of the file "file1.txt.xz" and write the
255 uncompressed data to the file "file1.txt".
256
257 use strict ;
258 use warnings ;
259 use IO::Uncompress::UnLzip qw(unlzip $UnLzipError) ;
260
261 my $input = "file1.txt.xz";
262 my $output = "file1.txt";
263 unlzip $input => $output
264 or die "unlzip failed: $UnLzipError\n";
265
266 To read from an existing Perl filehandle, $input, and write the
267 uncompressed data to a buffer, $buffer.
268
269 use strict ;
270 use warnings ;
271 use IO::Uncompress::UnLzip qw(unlzip $UnLzipError) ;
272 use IO::File ;
273
274 my $input = new IO::File "<file1.txt.xz"
275 or die "Cannot open 'file1.txt.xz': $!\n" ;
276 my $buffer ;
277 unlzip $input => \$buffer
278 or die "unlzip failed: $UnLzipError\n";
279
280 To uncompress all files in the directory "/my/home" that match
281 "*.txt.xz" and store the compressed data in the same directory
282
283 use strict ;
284 use warnings ;
285 use IO::Uncompress::UnLzip qw(unlzip $UnLzipError) ;
286
287 unlzip '</my/home/*.txt.xz>' => '</my/home/#1.txt>'
288 or die "unlzip failed: $UnLzipError\n";
289
290 and if you want to compress each file one at a time, this will do the
291 trick
292
293 use strict ;
294 use warnings ;
295 use IO::Uncompress::UnLzip qw(unlzip $UnLzipError) ;
296
297 for my $input ( glob "/my/home/*.txt.xz" )
298 {
299 my $output = $input;
300 $output =~ s/.xz// ;
301 unlzip $input => $output
302 or die "Error compressing '$input': $UnLzipError\n";
303 }
304
306 Constructor
307 The format of the constructor for IO::Uncompress::UnLzip is shown below
308
309 my $z = new IO::Uncompress::UnLzip $input [OPTS]
310 or die "IO::Uncompress::UnLzip failed: $UnLzipError\n";
311
312 Returns an "IO::Uncompress::UnLzip" object on success and undef on
313 failure. The variable $UnLzipError will contain an error message on
314 failure.
315
316 If you are running Perl 5.005 or better the object, $z, returned from
317 IO::Uncompress::UnLzip can be used exactly like an IO::File filehandle.
318 This means that all normal input file operations can be carried out
319 with $z. For example, to read a line from a compressed file/buffer you
320 can use either of these forms
321
322 $line = $z->getline();
323 $line = <$z>;
324
325 The mandatory parameter $input is used to determine the source of the
326 compressed data. This parameter can take one of three forms.
327
328 A filename
329 If the $input parameter is a scalar, it is assumed to be a
330 filename. This file will be opened for reading and the compressed
331 data will be read from it.
332
333 A filehandle
334 If the $input parameter is a filehandle, the compressed data will
335 be read from it. The string '-' can be used as an alias for
336 standard input.
337
338 A scalar reference
339 If $input is a scalar reference, the compressed data will be read
340 from $$input.
341
342 Constructor Options
343 The option names defined below are case insensitive and can be
344 optionally prefixed by a '-'. So all of the following are valid
345
346 -AutoClose
347 -autoclose
348 AUTOCLOSE
349 autoclose
350
351 OPTS is a combination of the following options:
352
353 "AutoClose => 0|1"
354 This option is only valid when the $input parameter is a
355 filehandle. If specified, and the value is true, it will result in
356 the file being closed once either the "close" method is called or
357 the IO::Uncompress::UnLzip object is destroyed.
358
359 This parameter defaults to 0.
360
361 "MultiStream => 0|1"
362 Allows multiple concatenated compressed streams to be treated as a
363 single compressed stream. Decompression will stop once either the
364 end of the file/buffer is reached, an error is encountered
365 (premature eof, corrupt compressed data) or the end of a stream is
366 not immediately followed by the start of another stream.
367
368 This parameter defaults to 0.
369
370 "Prime => $string"
371 This option will uncompress the contents of $string before
372 processing the input file/buffer.
373
374 This option can be useful when the compressed data is embedded in
375 another file/data structure and it is not possible to work out
376 where the compressed data begins without having to read the first
377 few bytes. If this is the case, the uncompression can be primed
378 with these bytes using this option.
379
380 "Transparent => 0|1"
381 If this option is set and the input file/buffer is not compressed
382 data, the module will allow reading of it anyway.
383
384 In addition, if the input file/buffer does contain compressed data
385 and there is non-compressed data immediately following it, setting
386 this option will make this module treat the whole file/buffer as a
387 single data stream.
388
389 This option defaults to 1.
390
391 "BlockSize => $num"
392 When reading the compressed input data, IO::Uncompress::UnLzip
393 will read it in blocks of $num bytes.
394
395 This option defaults to 4096.
396
397 "InputLength => $size"
398 When present this option will limit the number of compressed bytes
399 read from the input file/buffer to $size. This option can be used
400 in the situation where there is useful data directly after the
401 compressed data stream and you know beforehand the exact length of
402 the compressed data stream.
403
404 This option is mostly used when reading from a filehandle, in
405 which case the file pointer will be left pointing to the first
406 byte directly after the compressed data stream.
407
408 This option defaults to off.
409
410 "Append => 0|1"
411 This option controls what the "read" method does with uncompressed
412 data.
413
414 If set to 1, all uncompressed data will be appended to the output
415 parameter of the "read" method.
416
417 If set to 0, the contents of the output parameter of the "read"
418 method will be overwritten by the uncompressed data.
419
420 Defaults to 0.
421
422 "Strict => 0|1"
423 This option controls whether the extra checks defined below are
424 used when carrying out the decompression. When Strict is on, the
425 extra tests are carried out, when Strict is off they are not.
426
427 The default for this option is off.
428
429 Examples
430 TODO
431
433 read
434 Usage is
435
436 $status = $z->read($buffer)
437
438 Reads a block of compressed data (the size of the compressed block is
439 determined by the "Buffer" option in the constructor), uncompresses it
440 and writes any uncompressed data into $buffer. If the "Append"
441 parameter is set in the constructor, the uncompressed data will be
442 appended to the $buffer parameter. Otherwise $buffer will be
443 overwritten.
444
445 Returns the number of uncompressed bytes written to $buffer, zero if
446 eof or a negative number on error.
447
448 read
449 Usage is
450
451 $status = $z->read($buffer, $length)
452 $status = $z->read($buffer, $length, $offset)
453
454 $status = read($z, $buffer, $length)
455 $status = read($z, $buffer, $length, $offset)
456
457 Attempt to read $length bytes of uncompressed data into $buffer.
458
459 The main difference between this form of the "read" method and the
460 previous one, is that this one will attempt to return exactly $length
461 bytes. The only circumstances that this function will not is if end-of-
462 file or an IO error is encountered.
463
464 Returns the number of uncompressed bytes written to $buffer, zero if
465 eof or a negative number on error.
466
467 getline
468 Usage is
469
470 $line = $z->getline()
471 $line = <$z>
472
473 Reads a single line.
474
475 This method fully supports the use of the variable $/ (or
476 $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
477 what constitutes an end of line. Paragraph mode, record mode and file
478 slurp mode are all supported.
479
480 getc
481 Usage is
482
483 $char = $z->getc()
484
485 Read a single character.
486
487 ungetc
488 Usage is
489
490 $char = $z->ungetc($string)
491
492 getHeaderInfo
493 Usage is
494
495 $hdr = $z->getHeaderInfo();
496 @hdrs = $z->getHeaderInfo();
497
498 This method returns either a hash reference (in scalar context) or a
499 list or hash references (in array context) that contains information
500 about each of the header fields in the compressed data stream(s).
501
502 tell
503 Usage is
504
505 $z->tell()
506 tell $z
507
508 Returns the uncompressed file offset.
509
510 eof
511 Usage is
512
513 $z->eof();
514 eof($z);
515
516 Returns true if the end of the compressed input stream has been
517 reached.
518
519 seek
520 $z->seek($position, $whence);
521 seek($z, $position, $whence);
522
523 Provides a sub-set of the "seek" functionality, with the restriction
524 that it is only legal to seek forward in the input file/buffer. It is
525 a fatal error to attempt to seek backward.
526
527 Note that the implementation of "seek" in this module does not provide
528 true random access to a compressed file/buffer. It works by
529 uncompressing data from the current offset in the file/buffer until it
530 reaches the uncompressed offset specified in the parameters to "seek".
531 For very small files this may be acceptable behaviour. For large files
532 it may cause an unacceptable delay.
533
534 The $whence parameter takes one the usual values, namely SEEK_SET,
535 SEEK_CUR or SEEK_END.
536
537 Returns 1 on success, 0 on failure.
538
539 binmode
540 Usage is
541
542 $z->binmode
543 binmode $z ;
544
545 This is a noop provided for completeness.
546
547 opened
548 $z->opened()
549
550 Returns true if the object currently refers to a opened file/buffer.
551
552 autoflush
553 my $prev = $z->autoflush()
554 my $prev = $z->autoflush(EXPR)
555
556 If the $z object is associated with a file or a filehandle, this method
557 returns the current autoflush setting for the underlying filehandle. If
558 "EXPR" is present, and is non-zero, it will enable flushing after every
559 write/print operation.
560
561 If $z is associated with a buffer, this method has no effect and always
562 returns "undef".
563
564 Note that the special variable $| cannot be used to set or retrieve the
565 autoflush setting.
566
567 input_line_number
568 $z->input_line_number()
569 $z->input_line_number(EXPR)
570
571 Returns the current uncompressed line number. If "EXPR" is present it
572 has the effect of setting the line number. Note that setting the line
573 number does not change the current position within the file/buffer
574 being read.
575
576 The contents of $/ are used to determine what constitutes a line
577 terminator.
578
579 fileno
580 $z->fileno()
581 fileno($z)
582
583 If the $z object is associated with a file or a filehandle, "fileno"
584 will return the underlying file descriptor. Once the "close" method is
585 called "fileno" will return "undef".
586
587 If the $z object is associated with a buffer, this method will return
588 "undef".
589
590 close
591 $z->close() ;
592 close $z ;
593
594 Closes the output file/buffer.
595
596 For most versions of Perl this method will be automatically invoked if
597 the IO::Uncompress::UnLzip object is destroyed (either explicitly or by
598 the variable with the reference to the object going out of scope). The
599 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
600 cases, the "close" method will be called automatically, but not until
601 global destruction of all live objects when the program is terminating.
602
603 Therefore, if you want your scripts to be able to run on all versions
604 of Perl, you should call "close" explicitly and not rely on automatic
605 closing.
606
607 Returns true on success, otherwise 0.
608
609 If the "AutoClose" option has been enabled when the
610 IO::Uncompress::UnLzip object was created, and the object is associated
611 with a file, the underlying file will also be closed.
612
613 nextStream
614 Usage is
615
616 my $status = $z->nextStream();
617
618 Skips to the next compressed data stream in the input file/buffer. If a
619 new compressed data stream is found, the eof marker will be cleared and
620 $. will be reset to 0.
621
622 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
623 error was encountered.
624
625 trailingData
626 Usage is
627
628 my $data = $z->trailingData();
629
630 Returns the data, if any, that is present immediately after the
631 compressed data stream once uncompression is complete. It only makes
632 sense to call this method once the end of the compressed data stream
633 has been encountered.
634
635 This option can be used when there is useful information immediately
636 following the compressed data stream, and you don't know the length of
637 the compressed data stream.
638
639 If the input is a buffer, "trailingData" will return everything from
640 the end of the compressed data stream to the end of the buffer.
641
642 If the input is a filehandle, "trailingData" will return the data that
643 is left in the filehandle input buffer once the end of the compressed
644 data stream has been reached. You can then use the filehandle to read
645 the rest of the input file.
646
647 Don't bother using "trailingData" if the input is a filename.
648
649 If you know the length of the compressed data stream before you start
650 uncompressing, you can avoid having to use "trailingData" by setting
651 the "InputLength" option in the constructor.
652
654 No symbolic constants are required by this IO::Uncompress::UnLzip at
655 present.
656
657 :all Imports "unlzip" and $UnLzipError. Same as doing this
658
659 use IO::Uncompress::UnLzip qw(unlzip $UnLzipError) ;
660
663 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
664 IO::Compress::Deflate, IO::Uncompress::Inflate,
665 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
666 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma,
667 IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz,
668 IO::Compress::Lzip, IO::Compress::Lzop, IO::Uncompress::UnLzop,
669 IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd,
670 IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate,
671 IO::Uncompress::AnyUncompress
672
673 IO::Compress::FAQ
674
675 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
676
678 This module was written by Paul Marquess, "pmqs@cpan.org".
679
681 See the Changes file.
682
684 Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
685
686 This program is free software; you can redistribute it and/or modify it
687 under the same terms as Perl itself.
688
689
690
691perl v5.30.0 2019-08-12 IO::Uncompress::UnLzip(3)