1IO::Compress::Lzma(3) User Contributed Perl DocumentationIO::Compress::Lzma(3)
2
6 IO::Compress::Lzma - Write lzma files/buffers
7
9 use IO::Compress::Lzma qw(lzma $LzmaError) ;
10 my $status = lzma $input => $output [,OPTS]
12 or die "lzma failed: $LzmaError\n";
13 my $z = IO::Compress::Lzma->new( $output [,OPTS] )
15 or die "lzma failed: $LzmaError\n";
16 $z->print($string);
18 $z->printf($format, $string);
19 $z->write($string);
20 $z->syswrite($string [, $length, $offset]);
21 $z->flush();
22 $z->tell();
23 $z->eof();
24 $z->seek($position, $whence);
25 $z->binmode();
26 $z->fileno();
27 $z->opened();
28 $z->autoflush();
29 $z->input_line_number();
30 $z->newStream( [OPTS] );
31 $z->close() ;
33 $LzmaError ;
35 # IO::File mode
37 print $z $string;
39 printf $z $format, $string;
40 tell $z
41 eof $z
42 seek $z, $position, $whence
43 binmode $z
44 fileno $z
45 close $z ;
46
48 This module provides a Perl interface that allows writing lzma
49 compressed data to files or buffer.
50 For reading lzma files/buffers, see the companion module
52 IO::Uncompress::UnLzma.
53
55 A top-level function, "lzma", is provided to carry out "one-shot"
56 compression between buffers and/or files. For finer control over the
57 compression process, see the "OO Interface" section.
58 use IO::Compress::Lzma qw(lzma $LzmaError) ;
60 lzma $input_filename_or_reference => $output_filename_or_reference [,OPTS]
62 or die "lzma failed: $LzmaError\n";
63 The functional interface needs Perl5.005 or better.
65 lzma $input_filename_or_reference => $output_filename_or_reference [, OPTS]
67 "lzma" expects at least two parameters, $input_filename_or_reference
68 and $output_filename_or_reference and zero or more optional parameters
69 (see "Optional Parameters")
70 The $input_filename_or_reference parameter
72 The parameter, $input_filename_or_reference, is used to define the
74 source of the uncompressed data.
75 It can take one of the following forms:
77 A filename
79 If the $input_filename_or_reference parameter is a simple scalar,
80 it is assumed to be a filename. This file will be opened for
81 reading and the input data will be read from it.
82 A filehandle
84 If the $input_filename_or_reference parameter is a filehandle, the
85 input data will be read from it. The string '-' can be used as an
86 alias for standard input.
87 A scalar reference
89 If $input_filename_or_reference is a scalar reference, the input
90 data will be read from $$input_filename_or_reference.
91 An array reference
93 If $input_filename_or_reference is an array reference, each
94 element in the array must be a filename.
95 The input data will be read from each file in turn.
97 The complete array will be walked to ensure that it only contains
99 valid filenames before any data is compressed.
100 An Input FileGlob string
102 If $input_filename_or_reference is a string that is delimited by
103 the characters "<" and ">" "lzma" will assume that it is an input
104 fileglob string. The input is the list of files that match the
105 fileglob.
106 See File::GlobMapper for more details.
108 If the $input_filename_or_reference parameter is any other type,
110 "undef" will be returned.
111 The $output_filename_or_reference parameter
113 The parameter $output_filename_or_reference is used to control the
115 destination of the compressed data. This parameter can take one of
116 these forms.
117 A filename
119 If the $output_filename_or_reference parameter is a simple scalar,
120 it is assumed to be a filename. This file will be opened for
121 writing and the compressed data will be written to it.
122 A filehandle
124 If the $output_filename_or_reference parameter is a filehandle,
125 the compressed data will be written to it. The string '-' can be
126 used as an alias for standard output.
127 A scalar reference
129 If $output_filename_or_reference is a scalar reference, the
130 compressed data will be stored in $$output_filename_or_reference.
131 An Array Reference
133 If $output_filename_or_reference is an array reference, the
134 compressed data will be pushed onto the array.
135 An Output FileGlob
137 If $output_filename_or_reference is a string that is delimited by
138 the characters "<" and ">" "lzma" will assume that it is an output
139 fileglob string. The output is the list of files that match the
140 fileglob.
141 When $output_filename_or_reference is an fileglob string,
143 $input_filename_or_reference must also be a fileglob string.
144 Anything else is an error.
145 See File::GlobMapper for more details.
147 If the $output_filename_or_reference parameter is any other type,
149 "undef" will be returned.
150 Notes
152 When $input_filename_or_reference maps to multiple files/buffers and
153 $output_filename_or_reference is a single file/buffer the input
154 files/buffers will be stored in $output_filename_or_reference as a
155 concatenated series of compressed data streams.
156 Optional Parameters
158 The optional parameters for the one-shot function "lzma" are (for the
159 most part) identical to those used with the OO interface defined in the
160 "Constructor Options" section. The exceptions are listed below
161 "AutoClose => 0|1"
163 This option applies to any input or output data streams to "lzma"
164 that are filehandles.
165 If "AutoClose" is specified, and the value is true, it will result
167 in all input and/or output filehandles being closed once "lzma"
168 has completed.
169 This parameter defaults to 0.
171 "BinModeIn => 0|1"
173 This option is now a no-op. All files will be read in binmode.
174 "Append => 0|1"
176 The behaviour of this option is dependent on the type of output
177 data stream.
178 • A Buffer
180 If "Append" is enabled, all compressed data will be append to
182 the end of the output buffer. Otherwise the output buffer
183 will be cleared before any compressed data is written to it.
184 • A Filename
186 If "Append" is enabled, the file will be opened in append
188 mode. Otherwise the contents of the file, if any, will be
189 truncated before any compressed data is written to it.
190 • A Filehandle
192 If "Append" is enabled, the filehandle will be positioned to
194 the end of the file via a call to "seek" before any
195 compressed data is written to it. Otherwise the file pointer
196 will not be moved.
197 When "Append" is specified, and set to true, it will append all
199 compressed data to the output data stream.
200 So when the output is a filehandle it will carry out a seek to the
202 eof before writing any compressed data. If the output is a
203 filename, it will be opened for appending. If the output is a
204 buffer, all compressed data will be appended to the existing
205 buffer.
206 Conversely when "Append" is not specified, or it is present and is
208 set to false, it will operate as follows.
209 When the output is a filename, it will truncate the contents of
211 the file before writing any compressed data. If the output is a
212 filehandle its position will not be changed. If the output is a
213 buffer, it will be wiped before any compressed data is output.
214 Defaults to 0.
216 Examples
218 Here are a few example that show the capabilities of the module.
219 Streaming
221 This very simple command line example demonstrates the streaming
223 capabilities of the module. The code reads data from STDIN, compresses
224 it, and writes the compressed data to STDOUT.
225 $ echo hello world | perl -MIO::Compress::Lzma=lzma -e 'lzma \*STDIN => \*STDOUT' >output.lzma
227 The special filename "-" can be used as a standin for both "\*STDIN"
229 and "\*STDOUT", so the above can be rewritten as
230 $ echo hello world | perl -MIO::Compress::Lzma=lzma -e 'lzma "-" => "-"' >output.lzma
232 Compressing a file from the filesystem
234 To read the contents of the file "file1.txt" and write the compressed
236 data to the file "file1.txt.lzma".
237 use strict ;
239 use warnings ;
240 use IO::Compress::Lzma qw(lzma $LzmaError) ;
241 my $input = "file1.txt";
243 lzma $input => "$input.lzma"
244 or die "lzma failed: $LzmaError\n";
245 Reading from a Filehandle and writing to an in-memory buffer
247 To read from an existing Perl filehandle, $input, and write the
249 compressed data to a buffer, $buffer.
250 use strict ;
252 use warnings ;
253 use IO::Compress::Lzma qw(lzma $LzmaError) ;
254 use IO::File ;
255 my $input = IO::File->new( "<file1.txt" )
257 or die "Cannot open 'file1.txt': $!\n" ;
258 my $buffer ;
259 lzma $input => \$buffer
260 or die "lzma failed: $LzmaError\n";
261 Compressing multiple files
263 To compress all files in the directory "/my/home" that match "*.txt"
265 and store the compressed data in the same directory
266 use strict ;
268 use warnings ;
269 use IO::Compress::Lzma qw(lzma $LzmaError) ;
270 lzma '</my/home/*.txt>' => '<*.lzma>'
272 or die "lzma failed: $LzmaError\n";
273 and if you want to compress each file one at a time, this will do the
275 trick
276 use strict ;
278 use warnings ;
279 use IO::Compress::Lzma qw(lzma $LzmaError) ;
280 for my $input ( glob "/my/home/*.txt" )
282 {
283 my $output = "$input.lzma" ;
284 lzma $input => $output
285 or die "Error compressing '$input': $LzmaError\n";
286 }
287
289 Constructor
290 The format of the constructor for "IO::Compress::Lzma" is shown below
291 my $z = IO::Compress::Lzma->new( $output [,OPTS] )
293 or die "IO::Compress::Lzma failed: $LzmaError\n";
294 It returns an "IO::Compress::Lzma" object on success and undef on
296 failure. The variable $LzmaError will contain an error message on
297 failure.
298 If you are running Perl 5.005 or better the object, $z, returned from
300 IO::Compress::Lzma can be used exactly like an IO::File filehandle.
301 This means that all normal output file operations can be carried out
302 with $z. For example, to write to a compressed file/buffer you can use
303 either of these forms
304 $z->print("hello world\n");
306 print $z "hello world\n";
307 The mandatory parameter $output is used to control the destination of
309 the compressed data. This parameter can take one of these forms.
310 A filename
312 If the $output parameter is a simple scalar, it is assumed to be a
313 filename. This file will be opened for writing and the compressed
314 data will be written to it.
315 A filehandle
317 If the $output parameter is a filehandle, the compressed data will
318 be written to it. The string '-' can be used as an alias for
319 standard output.
320 A scalar reference
322 If $output is a scalar reference, the compressed data will be
323 stored in $$output.
324 If the $output parameter is any other type, "IO::Compress::Lzma"::new
326 will return undef.
327 Constructor Options
329 "OPTS" is any combination of zero or more the following options:
330 "AutoClose => 0|1"
332 This option is only valid when the $output parameter is a
333 filehandle. If specified, and the value is true, it will result in
334 the $output being closed once either the "close" method is called
335 or the "IO::Compress::Lzma" object is destroyed.
336 This parameter defaults to 0.
338 "Append => 0|1"
340 Opens $output in append mode.
341 The behaviour of this option is dependent on the type of $output.
343 • A Buffer
345 If $output is a buffer and "Append" is enabled, all
347 compressed data will be append to the end of $output.
348 Otherwise $output will be cleared before any data is written
349 to it.
350 • A Filename
352 If $output is a filename and "Append" is enabled, the file
354 will be opened in append mode. Otherwise the contents of the
355 file, if any, will be truncated before any compressed data is
356 written to it.
357 • A Filehandle
359 If $output is a filehandle, the file pointer will be
361 positioned to the end of the file via a call to "seek" before
362 any compressed data is written to it. Otherwise the file
363 pointer will not be moved.
364 This parameter defaults to 0.
366 "Filter => $filter"
368 When present $filter option must be an object of type
369 "Lzma::Filter::Lzma1". See "Lzma::Filter::Lzma" for a definition
370 of "Lzma::Filter::Lzma1".
371 If this option is not present an "Lzma::Filter::Lzma1" object with
373 default values will be used.
374 "Strict => 0|1"
376 This is a placeholder option.
377 Examples
379 TODO
380
382 print
383 Usage is
384 $z->print($data)
386 print $z $data
387 Compresses and outputs the contents of the $data parameter. This has
389 the same behaviour as the "print" built-in.
390 Returns true if successful.
392 printf
394 Usage is
395 $z->printf($format, $data)
397 printf $z $format, $data
398 Compresses and outputs the contents of the $data parameter.
400 Returns true if successful.
402 syswrite
404 Usage is
405 $z->syswrite $data
407 $z->syswrite $data, $length
408 $z->syswrite $data, $length, $offset
409 Compresses and outputs the contents of the $data parameter.
411 Returns the number of uncompressed bytes written, or "undef" if
413 unsuccessful.
414 write
416 Usage is
417 $z->write $data
419 $z->write $data, $length
420 $z->write $data, $length, $offset
421 Compresses and outputs the contents of the $data parameter.
423 Returns the number of uncompressed bytes written, or "undef" if
425 unsuccessful.
426 flush
428 Usage is
429 $z->flush;
431 Flushes any pending compressed data to the output file/buffer.
433 Returns true on success.
435 tell
437 Usage is
438 $z->tell()
440 tell $z
441 Returns the uncompressed file offset.
443 eof
445 Usage is
446 $z->eof();
448 eof($z);
449 Returns true if the "close" method has been called.
451 seek
453 $z->seek($position, $whence);
454 seek($z, $position, $whence);
455 Provides a sub-set of the "seek" functionality, with the restriction
457 that it is only legal to seek forward in the output file/buffer. It is
458 a fatal error to attempt to seek backward.
459 Empty parts of the file/buffer will have NULL (0x00) bytes written to
461 them.
462 The $whence parameter takes one the usual values, namely SEEK_SET,
464 SEEK_CUR or SEEK_END.
465 Returns 1 on success, 0 on failure.
467 binmode
469 Usage is
470 $z->binmode
472 binmode $z ;
473 This is a noop provided for completeness.
475 opened
477 $z->opened()
478 Returns true if the object currently refers to a opened file/buffer.
480 autoflush
482 my $prev = $z->autoflush()
483 my $prev = $z->autoflush(EXPR)
484 If the $z object is associated with a file or a filehandle, this method
486 returns the current autoflush setting for the underlying filehandle. If
487 "EXPR" is present, and is non-zero, it will enable flushing after every
488 write/print operation.
489 If $z is associated with a buffer, this method has no effect and always
491 returns "undef".
492 Note that the special variable $| cannot be used to set or retrieve the
494 autoflush setting.
495 input_line_number
497 $z->input_line_number()
498 $z->input_line_number(EXPR)
499 This method always returns "undef" when compressing.
501 fileno
503 $z->fileno()
504 fileno($z)
505 If the $z object is associated with a file or a filehandle, "fileno"
507 will return the underlying file descriptor. Once the "close" method is
508 called "fileno" will return "undef".
509 If the $z object is associated with a buffer, this method will return
511 "undef".
512 close
514 $z->close() ;
515 close $z ;
516 Flushes any pending compressed data and then closes the output
518 file/buffer.
519 For most versions of Perl this method will be automatically invoked if
521 the IO::Compress::Lzma object is destroyed (either explicitly or by the
522 variable with the reference to the object going out of scope). The
523 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
524 cases, the "close" method will be called automatically, but not until
525 global destruction of all live objects when the program is terminating.
526 Therefore, if you want your scripts to be able to run on all versions
528 of Perl, you should call "close" explicitly and not rely on automatic
529 closing.
530 Returns true on success, otherwise 0.
532 If the "AutoClose" option has been enabled when the IO::Compress::Lzma
534 object was created, and the object is associated with a file, the
535 underlying file will also be closed.
536 newStream([OPTS])
538 Usage is
539 $z->newStream( [OPTS] )
541 Closes the current compressed data stream and starts a new one.
543 OPTS consists of any of the options that are available when creating
545 the $z object.
546 See the "Constructor Options" section for more details.
548
550 No symbolic constants are required by IO::Compress::Lzma at present.
551 :all Imports "lzma" and $LzmaError. Same as doing this
553 use IO::Compress::Lzma qw(lzma $LzmaError) ;
555
558 General feedback/questions/bug reports should be sent to
559 <https://github.com/pmqs/IO-Compress-Lzma/issues> (preferred) or
560 <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress-Lzma>.
561
563 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
564 IO::Compress::Deflate, IO::Uncompress::Inflate,
565 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
566 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Uncompress::UnLzma,
567 IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzip,
568 IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop,
569 IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd,
570 IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate,
571 IO::Uncompress::AnyUncompress
572 IO::Compress::FAQ
574 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
576
578 This module was written by Paul Marquess, "pmqs@cpan.org".
579
581 See the Changes file.
582
584 Copyright (c) 2005-2021 Paul Marquess. All rights reserved.
585 This program is free software; you can redistribute it and/or modify it
587 under the same terms as Perl itself.
588perl v5.34.0 2021-07-22 IO::Compress::Lzma(3)