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