1IO::Uncompress::UnXz(3)User Contributed Perl DocumentatioInO::Uncompress::UnXz(3)
2
6 IO::Uncompress::UnXz - Read xz files/buffers
7
9 use IO::Uncompress::UnXz qw(unxz $UnXzError) ;
10 my $status = unxz $input => $output [,OPTS]
12 or die "unxz failed: $UnXzError\n";
13 my $z = new IO::Uncompress::UnXz $input [OPTS]
15 or die "unxz failed: $UnXzError\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 $UnXzError ;
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 xz files/buffers, see the companion module
65 IO::Compress::Xz.
66
68 A top-level function, "unxz", 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::UnXz qw(unxz $UnXzError) ;
73 unxz $input_filename_or_reference => $output_filename_or_reference [,OPTS]
75 or die "unxz failed: $UnXzError\n";
76 The functional interface needs Perl5.005 or better.
78 unxz $input_filename_or_reference => $output_filename_or_reference [, OPTS]
80 "unxz" expects at least two parameters, $input_filename_or_reference
81 and $output_filename_or_reference.
82 The $input_filename_or_reference parameter
84 The parameter, $input_filename_or_reference, is used to define the
86 source of the compressed data.
87 It can take one of the following forms:
89 A filename
91 If the <$input_filename_or_reference> parameter is a simple
92 scalar, it is assumed to be a filename. This file will be opened
93 for reading and the input data will be read from it.
94 A filehandle
96 If the $input_filename_or_reference parameter is a filehandle, the
97 input data will be read from it. The string '-' can be used as an
98 alias for standard input.
99 A scalar reference
101 If $input_filename_or_reference is a scalar reference, the input
102 data will be read from $$input_filename_or_reference.
103 An array reference
105 If $input_filename_or_reference is an array reference, each
106 element in the array must be a filename.
107 The input data will be read from each file in turn.
109 The complete array will be walked to ensure that it only contains
111 valid filenames before any data is uncompressed.
112 An Input FileGlob string
114 If $input_filename_or_reference is a string that is delimited by
115 the characters "<" and ">" "unxz" will assume that it is an input
116 fileglob string. The input is the list of files that match the
117 fileglob.
118 See File::GlobMapper for more details.
120 If the $input_filename_or_reference parameter is any other type,
122 "undef" will be returned.
123 The $output_filename_or_reference parameter
125 The parameter $output_filename_or_reference is used to control the
127 destination of the uncompressed data. This parameter can take one of
128 these forms.
129 A filename
131 If the $output_filename_or_reference parameter is a simple scalar,
132 it is assumed to be a filename. This file will be opened for
133 writing and the uncompressed data will be written to it.
134 A filehandle
136 If the $output_filename_or_reference parameter is a filehandle,
137 the uncompressed data will be written to it. The string '-' can
138 be used as an alias for standard output.
139 A scalar reference
141 If $output_filename_or_reference is a scalar reference, the
142 uncompressed data will be stored in
143 $$output_filename_or_reference.
144 An Array Reference
146 If $output_filename_or_reference is an array reference, the
147 uncompressed data will be pushed onto the array.
148 An Output FileGlob
150 If $output_filename_or_reference is a string that is delimited by
151 the characters "<" and ">" "unxz" will assume that it is an output
152 fileglob string. The output is the list of files that match the
153 fileglob.
154 When $output_filename_or_reference is an fileglob string,
156 $input_filename_or_reference must also be a fileglob string.
157 Anything else is an error.
158 See File::GlobMapper for more details.
160 If the $output_filename_or_reference parameter is any other type,
162 "undef" will be returned.
163 Notes
165 When $input_filename_or_reference maps to multiple compressed
166 files/buffers and $output_filename_or_reference is a single
167 file/buffer, after uncompression $output_filename_or_reference will
168 contain a concatenation of all the uncompressed data from each of the
169 input files/buffers.
170 Optional Parameters
172 Unless specified below, the optional parameters for "unxz", "OPTS", are
173 the same as those used with the OO interface defined in the
174 "Constructor Options" section below.
175 "AutoClose => 0|1"
177 This option applies to any input or output data streams to "unxz"
178 that are filehandles.
179 If "AutoClose" is specified, and the value is true, it will result
181 in all input and/or output filehandles being closed once "unxz"
182 has completed.
183 This parameter defaults to 0.
185 "BinModeOut => 0|1"
187 When writing to a file or filehandle, set "binmode" before writing
188 to the file.
189 Defaults to 0.
191 "Append => 0|1"
193 The behaviour of this option is dependent on the type of output
194 data stream.
195 · A Buffer
197 If "Append" is enabled, all uncompressed data will be append
199 to the end of the output buffer. Otherwise the output buffer
200 will be cleared before any uncompressed data is written to
201 it.
202 · A Filename
204 If "Append" is enabled, the file will be opened in append
206 mode. Otherwise the contents of the file, if any, will be
207 truncated before any uncompressed data is written to it.
208 · A Filehandle
210 If "Append" is enabled, the filehandle will be positioned to
212 the end of the file via a call to "seek" before any
213 uncompressed data is written to it. Otherwise the file
214 pointer will not be moved.
215 When "Append" is specified, and set to true, it will append all
217 uncompressed data to the output data stream.
218 So when the output is a filehandle it will carry out a seek to the
220 eof before writing any uncompressed data. If the output is a
221 filename, it will be opened for appending. If the output is a
222 buffer, all uncompressed data will be appended to the existing
223 buffer.
224 Conversely when "Append" is not specified, or it is present and is
226 set to false, it will operate as follows.
227 When the output is a filename, it will truncate the contents of
229 the file before writing any uncompressed data. If the output is a
230 filehandle its position will not be changed. If the output is a
231 buffer, it will be wiped before any uncompressed data is output.
232 Defaults to 0.
234 "MultiStream => 0|1"
236 If the input file/buffer contains multiple compressed data
237 streams, this option will uncompress the whole lot as a single
238 data stream.
239 Defaults to 0.
241 "TrailingData => $scalar"
243 Returns the data, if any, that is present immediately after the
244 compressed data stream once uncompression is complete.
245 This option can be used when there is useful information
247 immediately following the compressed data stream, and you don't
248 know the length of the compressed data stream.
249 If the input is a buffer, "trailingData" will return everything
251 from the end of the compressed data stream to the end of the
252 buffer.
253 If the input is a filehandle, "trailingData" will return the data
255 that is left in the filehandle input buffer once the end of the
256 compressed data stream has been reached. You can then use the
257 filehandle to read the rest of the input file.
258 Don't bother using "trailingData" if the input is a filename.
260 If you know the length of the compressed data stream before you
262 start uncompressing, you can avoid having to use "trailingData" by
263 setting the "InputLength" option.
264 Examples
266 To read the contents of the file "file1.txt.xz" and write the
267 uncompressed data to the file "file1.txt".
268 use strict ;
270 use warnings ;
271 use IO::Uncompress::UnXz qw(unxz $UnXzError) ;
272 my $input = "file1.txt.xz";
274 my $output = "file1.txt";
275 unxz $input => $output
276 or die "unxz failed: $UnXzError\n";
277 To read from an existing Perl filehandle, $input, and write the
279 uncompressed data to a buffer, $buffer.
280 use strict ;
282 use warnings ;
283 use IO::Uncompress::UnXz qw(unxz $UnXzError) ;
284 use IO::File ;
285 my $input = new IO::File "<file1.txt.xz"
287 or die "Cannot open 'file1.txt.xz': $!\n" ;
288 my $buffer ;
289 unxz $input => \$buffer
290 or die "unxz failed: $UnXzError\n";
291 To uncompress all files in the directory "/my/home" that match
293 "*.txt.xz" and store the compressed data in the same directory
294 use strict ;
296 use warnings ;
297 use IO::Uncompress::UnXz qw(unxz $UnXzError) ;
298 unxz '</my/home/*.txt.xz>' => '</my/home/#1.txt>'
300 or die "unxz failed: $UnXzError\n";
301 and if you want to compress each file one at a time, this will do the
303 trick
304 use strict ;
306 use warnings ;
307 use IO::Uncompress::UnXz qw(unxz $UnXzError) ;
308 for my $input ( glob "/my/home/*.txt.xz" )
310 {
311 my $output = $input;
312 $output =~ s/.xz// ;
313 unxz $input => $output
314 or die "Error compressing '$input': $UnXzError\n";
315 }
316
318 Constructor
319 The format of the constructor for IO::Uncompress::UnXz is shown below
320 my $z = new IO::Uncompress::UnXz $input [OPTS]
322 or die "IO::Uncompress::UnXz failed: $UnXzError\n";
323 Returns an "IO::Uncompress::UnXz" object on success and undef on
325 failure. The variable $UnXzError will contain an error message on
326 failure.
327 If you are running Perl 5.005 or better the object, $z, returned from
329 IO::Uncompress::UnXz can be used exactly like an IO::File filehandle.
330 This means that all normal input file operations can be carried out
331 with $z. For example, to read a line from a compressed file/buffer you
332 can use either of these forms
333 $line = $z->getline();
335 $line = <$z>;
336 The mandatory parameter $input is used to determine the source of the
338 compressed data. This parameter can take one of three forms.
339 A filename
341 If the $input parameter is a scalar, it is assumed to be a
342 filename. This file will be opened for reading and the compressed
343 data will be read from it.
344 A filehandle
346 If the $input parameter is a filehandle, the compressed data will
347 be read from it. The string '-' can be used as an alias for
348 standard input.
349 A scalar reference
351 If $input is a scalar reference, the compressed data will be read
352 from $$input.
353 Constructor Options
355 The option names defined below are case insensitive and can be
356 optionally prefixed by a '-'. So all of the following are valid
357 -AutoClose
359 -autoclose
360 AUTOCLOSE
361 autoclose
362 OPTS is a combination of the following options:
364 "AutoClose => 0|1"
366 This option is only valid when the $input parameter is a
367 filehandle. If specified, and the value is true, it will result in
368 the file being closed once either the "close" method is called or
369 the IO::Uncompress::UnXz object is destroyed.
370 This parameter defaults to 0.
372 "MultiStream => 0|1"
374 Allows multiple concatenated compressed streams to be treated as a
375 single compressed stream. Decompression will stop once either the
376 end of the file/buffer is reached, an error is encountered
377 (premature eof, corrupt compressed data) or the end of a stream is
378 not immediately followed by the start of another stream.
379 This parameter defaults to 0.
381 "Prime => $string"
383 This option will uncompress the contents of $string before
384 processing the input file/buffer.
385 This option can be useful when the compressed data is embedded in
387 another file/data structure and it is not possible to work out
388 where the compressed data begins without having to read the first
389 few bytes. If this is the case, the uncompression can be primed
390 with these bytes using this option.
391 "Transparent => 0|1"
393 If this option is set and the input file/buffer is not compressed
394 data, the module will allow reading of it anyway.
395 In addition, if the input file/buffer does contain compressed data
397 and there is non-compressed data immediately following it, setting
398 this option will make this module treat the whole file/buffer as a
399 single data stream.
400 This option defaults to 1.
402 "BlockSize => $num"
404 When reading the compressed input data, IO::Uncompress::UnXz will
405 read it in blocks of $num bytes.
406 This option defaults to 4096.
408 "InputLength => $size"
410 When present this option will limit the number of compressed bytes
411 read from the input file/buffer to $size. This option can be used
412 in the situation where there is useful data directly after the
413 compressed data stream and you know beforehand the exact length of
414 the compressed data stream.
415 This option is mostly used when reading from a filehandle, in
417 which case the file pointer will be left pointing to the first
418 byte directly after the compressed data stream.
419 This option defaults to off.
421 "Append => 0|1"
423 This option controls what the "read" method does with uncompressed
424 data.
425 If set to 1, all uncompressed data will be appended to the output
427 parameter of the "read" method.
428 If set to 0, the contents of the output parameter of the "read"
430 method will be overwritten by the uncompressed data.
431 Defaults to 0.
433 "Strict => 0|1"
435 This option controls whether the extra checks defined below are
436 used when carrying out the decompression. When Strict is on, the
437 extra tests are carried out, when Strict is off they are not.
438 The default for this option is off.
440 "MemLimit => $number"
442 Default is 128Meg.
443 "Flags => $flags"
445 Default is 0.
446 Examples
448 TODO
449
451 read
452 Usage is
453 $status = $z->read($buffer)
455 Reads a block of compressed data (the size of the compressed block is
457 determined by the "Buffer" option in the constructor), uncompresses it
458 and writes any uncompressed data into $buffer. If the "Append"
459 parameter is set in the constructor, the uncompressed data will be
460 appended to the $buffer parameter. Otherwise $buffer will be
461 overwritten.
462 Returns the number of uncompressed bytes written to $buffer, zero if
464 eof or a negative number on error.
465 read
467 Usage is
468 $status = $z->read($buffer, $length)
470 $status = $z->read($buffer, $length, $offset)
471 $status = read($z, $buffer, $length)
473 $status = read($z, $buffer, $length, $offset)
474 Attempt to read $length bytes of uncompressed data into $buffer.
476 The main difference between this form of the "read" method and the
478 previous one, is that this one will attempt to return exactly $length
479 bytes. The only circumstances that this function will not is if end-of-
480 file or an IO error is encountered.
481 Returns the number of uncompressed bytes written to $buffer, zero if
483 eof or a negative number on error.
484 getline
486 Usage is
487 $line = $z->getline()
489 $line = <$z>
490 Reads a single line.
492 This method fully supports the use of the variable $/ (or
494 $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
495 what constitutes an end of line. Paragraph mode, record mode and file
496 slurp mode are all supported.
497 getc
499 Usage is
500 $char = $z->getc()
502 Read a single character.
504 ungetc
506 Usage is
507 $char = $z->ungetc($string)
509 getHeaderInfo
511 Usage is
512 $hdr = $z->getHeaderInfo();
514 @hdrs = $z->getHeaderInfo();
515 This method returns either a hash reference (in scalar context) or a
517 list or hash references (in array context) that contains information
518 about each of the header fields in the compressed data stream(s).
519 tell
521 Usage is
522 $z->tell()
524 tell $z
525 Returns the uncompressed file offset.
527 eof
529 Usage is
530 $z->eof();
532 eof($z);
533 Returns true if the end of the compressed input stream has been
535 reached.
536 seek
538 $z->seek($position, $whence);
539 seek($z, $position, $whence);
540 Provides a sub-set of the "seek" functionality, with the restriction
542 that it is only legal to seek forward in the input file/buffer. It is
543 a fatal error to attempt to seek backward.
544 Note that the implementation of "seek" in this module does not provide
546 true random access to a compressed file/buffer. It works by
547 uncompressing data from the current offset in the file/buffer until it
548 reaches the uncompressed offset specified in the parameters to "seek".
549 For very small files this may be acceptable behaviour. For large files
550 it may cause an unacceptable delay.
551 The $whence parameter takes one the usual values, namely SEEK_SET,
553 SEEK_CUR or SEEK_END.
554 Returns 1 on success, 0 on failure.
556 binmode
558 Usage is
559 $z->binmode
561 binmode $z ;
562 This is a noop provided for completeness.
564 opened
566 $z->opened()
567 Returns true if the object currently refers to a opened file/buffer.
569 autoflush
571 my $prev = $z->autoflush()
572 my $prev = $z->autoflush(EXPR)
573 If the $z object is associated with a file or a filehandle, this method
575 returns the current autoflush setting for the underlying filehandle. If
576 "EXPR" is present, and is non-zero, it will enable flushing after every
577 write/print operation.
578 If $z is associated with a buffer, this method has no effect and always
580 returns "undef".
581 Note that the special variable $| cannot be used to set or retrieve the
583 autoflush setting.
584 input_line_number
586 $z->input_line_number()
587 $z->input_line_number(EXPR)
588 Returns the current uncompressed line number. If "EXPR" is present it
590 has the effect of setting the line number. Note that setting the line
591 number does not change the current position within the file/buffer
592 being read.
593 The contents of $/ are used to determine what constitutes a line
595 terminator.
596 fileno
598 $z->fileno()
599 fileno($z)
600 If the $z object is associated with a file or a filehandle, "fileno"
602 will return the underlying file descriptor. Once the "close" method is
603 called "fileno" will return "undef".
604 If the $z object is associated with a buffer, this method will return
606 "undef".
607 close
609 $z->close() ;
610 close $z ;
611 Closes the output file/buffer.
613 For most versions of Perl this method will be automatically invoked if
615 the IO::Uncompress::UnXz object is destroyed (either explicitly or by
616 the variable with the reference to the object going out of scope). The
617 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
618 cases, the "close" method will be called automatically, but not until
619 global destruction of all live objects when the program is terminating.
620 Therefore, if you want your scripts to be able to run on all versions
622 of Perl, you should call "close" explicitly and not rely on automatic
623 closing.
624 Returns true on success, otherwise 0.
626 If the "AutoClose" option has been enabled when the
628 IO::Uncompress::UnXz object was created, and the object is associated
629 with a file, the underlying file will also be closed.
630 nextStream
632 Usage is
633 my $status = $z->nextStream();
635 Skips to the next compressed data stream in the input file/buffer. If a
637 new compressed data stream is found, the eof marker will be cleared and
638 $. will be reset to 0.
639 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
641 error was encountered.
642 trailingData
644 Usage is
645 my $data = $z->trailingData();
647 Returns the data, if any, that is present immediately after the
649 compressed data stream once uncompression is complete. It only makes
650 sense to call this method once the end of the compressed data stream
651 has been encountered.
652 This option can be used when there is useful information immediately
654 following the compressed data stream, and you don't know the length of
655 the compressed data stream.
656 If the input is a buffer, "trailingData" will return everything from
658 the end of the compressed data stream to the end of the buffer.
659 If the input is a filehandle, "trailingData" will return the data that
661 is left in the filehandle input buffer once the end of the compressed
662 data stream has been reached. You can then use the filehandle to read
663 the rest of the input file.
664 Don't bother using "trailingData" if the input is a filename.
666 If you know the length of the compressed data stream before you start
668 uncompressing, you can avoid having to use "trailingData" by setting
669 the "InputLength" option in the constructor.
670
672 No symbolic constants are required by this IO::Uncompress::UnXz at
673 present.
674 :all Imports "unxz" and $UnXzError. Same as doing this
676 use IO::Uncompress::UnXz qw(unxz $UnXzError) ;
678
681 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
682 IO::Compress::Deflate, IO::Uncompress::Inflate,
683 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
684 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma,
685 IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Compress::Lzop,
686 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
687 IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
688 IO::Compress::FAQ
690 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
692
694 This module was written by Paul Marquess, "pmqs@cpan.org".
695
697 See the Changes file.
698
700 Copyright (c) 2005-2018 Paul Marquess. All rights reserved.
701 This program is free software; you can redistribute it and/or modify it
703 under the same terms as Perl itself.
704perl v5.28.0 2018-04-04 IO::Uncompress::UnXz(3)