1IO::Compress::Lzma(3) User Contributed Perl DocumentationIO::Compress::Lzma(3)
2
3
4
6 IO::Compress::Lzma - Write lzma files/buffers
7
9 use IO::Compress::Lzma qw(lzma $LzmaError) ;
10
11 my $status = lzma $input => $output [,OPTS]
12 or die "lzma failed: $LzmaError\n";
13
14 my $z = IO::Compress::Lzma->new( $output [,OPTS] )
15 or die "lzma failed: $LzmaError\n";
16
17 $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
32 $z->close() ;
33
34 $LzmaError ;
35
36 # IO::File mode
37
38 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
51 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
59 use IO::Compress::Lzma qw(lzma $LzmaError) ;
60
61 lzma $input_filename_or_reference => $output_filename_or_reference [,OPTS]
62 or die "lzma failed: $LzmaError\n";
63
64 The functional interface needs Perl5.005 or better.
65
66 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
71 The $input_filename_or_reference parameter
72
73 The parameter, $input_filename_or_reference, is used to define the
74 source of the uncompressed data.
75
76 It can take one of the following forms:
77
78 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
83 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
88 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
92 An array reference
93 If $input_filename_or_reference is an array reference, each
94 element in the array must be a filename.
95
96 The input data will be read from each file in turn.
97
98 The complete array will be walked to ensure that it only contains
99 valid filenames before any data is compressed.
100
101 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
107 See File::GlobMapper for more details.
108
109 If the $input_filename_or_reference parameter is any other type,
110 "undef" will be returned.
111
112 The $output_filename_or_reference parameter
113
114 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
118 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
123 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
128 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
132 An Array Reference
133 If $output_filename_or_reference is an array reference, the
134 compressed data will be pushed onto the array.
135
136 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
142 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
146 See File::GlobMapper for more details.
147
148 If the $output_filename_or_reference parameter is any other type,
149 "undef" will be returned.
150
151 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
157 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
162 "AutoClose => 0|1"
163 This option applies to any input or output data streams to "lzma"
164 that are filehandles.
165
166 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
170 This parameter defaults to 0.
171
172 "BinModeIn => 0|1"
173 This option is now a no-op. All files will be read in binmode.
174
175 "Append => 0|1"
176 The behaviour of this option is dependent on the type of output
177 data stream.
178
179 • A Buffer
180
181 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
185 • A Filename
186
187 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
191 • A Filehandle
192
193 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
198 When "Append" is specified, and set to true, it will append all
199 compressed data to the output data stream.
200
201 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
207 Conversely when "Append" is not specified, or it is present and is
208 set to false, it will operate as follows.
209
210 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
215 Defaults to 0.
216
217 Oneshot Examples
218 Here are a few example that show the capabilities of the module.
219
220 Streaming
221
222 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
226 $ echo hello world | perl -MIO::Compress::Lzma=lzma -e 'lzma \*STDIN => \*STDOUT' >output.lzma
227
228 The special filename "-" can be used as a standin for both "\*STDIN"
229 and "\*STDOUT", so the above can be rewritten as
230
231 $ echo hello world | perl -MIO::Compress::Lzma=lzma -e 'lzma "-" => "-"' >output.lzma
232
233 Compressing a file from the filesystem
234
235 To read the contents of the file "file1.txt" and write the compressed
236 data to the file "file1.txt.lzma".
237
238 use strict ;
239 use warnings ;
240 use IO::Compress::Lzma qw(lzma $LzmaError) ;
241
242 my $input = "file1.txt";
243 lzma $input => "$input.lzma"
244 or die "lzma failed: $LzmaError\n";
245
246 Reading from a Filehandle and writing to an in-memory buffer
247
248 To read from an existing Perl filehandle, $input, and write the
249 compressed data to a buffer, $buffer.
250
251 use strict ;
252 use warnings ;
253 use IO::Compress::Lzma qw(lzma $LzmaError) ;
254 use IO::File ;
255
256 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
262 Compressing multiple files
263
264 To compress all files in the directory "/my/home" that match "*.txt"
265 and store the compressed data in the same directory
266
267 use strict ;
268 use warnings ;
269 use IO::Compress::Lzma qw(lzma $LzmaError) ;
270
271 lzma '</my/home/*.txt>' => '<*.lzma>'
272 or die "lzma failed: $LzmaError\n";
273
274 and if you want to compress each file one at a time, this will do the
275 trick
276
277 use strict ;
278 use warnings ;
279 use IO::Compress::Lzma qw(lzma $LzmaError) ;
280
281 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
292 my $z = IO::Compress::Lzma->new( $output [,OPTS] )
293 or die "IO::Compress::Lzma failed: $LzmaError\n";
294
295 The constructor takes one mandatory parameter, $output, defined below
296 and zero or more "OPTS", defined in "Constructor Options".
297
298 It returns an "IO::Compress::Lzma" object on success and "undef" on
299 failure. The variable $LzmaError will contain an error message on
300 failure.
301
302 If you are running Perl 5.005 or better the object, $z, returned from
303 IO::Compress::Lzma can be used exactly like an IO::File filehandle.
304 This means that all normal output file operations can be carried out
305 with $z. For example, to write to a compressed file/buffer you can use
306 either of these forms
307
308 $z->print("hello world\n");
309 print $z "hello world\n";
310
311 Below is a simple exaple of using the OO interface to create an output
312 file "myfile.lzma" and write some data to it.
313
314 my $filename = "myfile.lzma";
315 my $z = IO::Compress::Lzma->new($filename)
316 or die "IO::Compress::Lzma failed: $LzmaError\n";
317
318 $z->print("abcde");
319 $z->close();
320
321 See the "Examples" for more.
322
323 The mandatory parameter $output is used to control the destination of
324 the compressed data. This parameter can take one of these forms.
325
326 A filename
327 If the $output parameter is a simple scalar, it is assumed to be a
328 filename. This file will be opened for writing and the compressed
329 data will be written to it.
330
331 A filehandle
332 If the $output parameter is a filehandle, the compressed data will
333 be written to it. The string '-' can be used as an alias for
334 standard output.
335
336 A scalar reference
337 If $output is a scalar reference, the compressed data will be
338 stored in $$output.
339
340 If the $output parameter is any other type, "IO::Compress::Lzma"::new
341 will return undef.
342
343 Constructor Options
344 "OPTS" is any combination of zero or more the following options:
345
346 "AutoClose => 0|1"
347 This option is only valid when the $output parameter is a
348 filehandle. If specified, and the value is true, it will result in
349 the $output being closed once either the "close" method is called
350 or the "IO::Compress::Lzma" object is destroyed.
351
352 This parameter defaults to 0.
353
354 "Append => 0|1"
355 Opens $output in append mode.
356
357 The behaviour of this option is dependent on the type of $output.
358
359 • A Buffer
360
361 If $output is a buffer and "Append" is enabled, all
362 compressed data will be append to the end of $output.
363 Otherwise $output will be cleared before any data is written
364 to it.
365
366 • A Filename
367
368 If $output is a filename and "Append" is enabled, the file
369 will be opened in append mode. Otherwise the contents of the
370 file, if any, will be truncated before any compressed data is
371 written to it.
372
373 • A Filehandle
374
375 If $output is a filehandle, the file pointer will be
376 positioned to the end of the file via a call to "seek" before
377 any compressed data is written to it. Otherwise the file
378 pointer will not be moved.
379
380 This parameter defaults to 0.
381
382 "Filter => $filter"
383 When present $filter option must be an object of type
384 "Lzma::Filter::Lzma1". See "Lzma::Filter::Lzma" for a definition
385 of "Lzma::Filter::Lzma1".
386
387 If this option is not present an "Lzma::Filter::Lzma1" object with
388 default values will be used.
389
390 "Strict => 0|1"
391 This is a placeholder option.
392
393 Examples
394 Streaming
395
396 This very simple command line example demonstrates the streaming
397 capabilities of the module. The code reads data from STDIN or all the
398 files given on the commandline, compresses it, and writes the
399 compressed data to STDOUT.
400
401 use strict ;
402 use warnings ;
403 use IO::Compress::Lzma qw(lzma $LzmaError) ;
404
405 my $z = IO::Compress::Lzma->new("-", Stream => 1)
406 or die "IO::Compress::Lzma failed: $LzmaError\n";
407
408 while (<>) {
409 $z->print("abcde");
410 }
411 $z->close();
412
413 Note the use of "-" to means "STDOUT". Alternatively you can use
414 "\*STDOUT".
415
416 Compressing a file from the filesystem
417
418 To read the contents of the file "file1.txt" and write the compressed
419 data to the file "file1.txt.lzma" there are a few options
420
421 Start by creating the compression object and opening the input file
422
423 use strict ;
424 use warnings ;
425 use IO::Compress::Lzma qw(lzma $LzmaError) ;
426
427 my $input = "file1.txt";
428 my $z = IO::Compress::Lzma->new("file1.txt.lzma")
429 or die "IO::Compress::Lzma failed: $LzmaError\n";
430
431 # open the input file
432 open my $fh, "<", "file1.txt"
433 or die "Cannot open file1.txt: $!\n";
434
435 # loop through the input file & write to the compressed file
436 while (<$fh>) {
437 $z->print($_);
438 }
439
440 # not forgetting to close the compressed file
441 $z->close();
442
444 print
445 Usage is
446
447 $z->print($data)
448 print $z $data
449
450 Compresses and outputs the contents of the $data parameter. This has
451 the same behaviour as the "print" built-in.
452
453 Returns true if successful.
454
455 printf
456 Usage is
457
458 $z->printf($format, $data)
459 printf $z $format, $data
460
461 Compresses and outputs the contents of the $data parameter.
462
463 Returns true if successful.
464
465 syswrite
466 Usage is
467
468 $z->syswrite $data
469 $z->syswrite $data, $length
470 $z->syswrite $data, $length, $offset
471
472 Compresses and outputs the contents of the $data parameter.
473
474 Returns the number of uncompressed bytes written, or "undef" if
475 unsuccessful.
476
477 write
478 Usage is
479
480 $z->write $data
481 $z->write $data, $length
482 $z->write $data, $length, $offset
483
484 Compresses and outputs the contents of the $data parameter.
485
486 Returns the number of uncompressed bytes written, or "undef" if
487 unsuccessful.
488
489 flush
490 Usage is
491
492 $z->flush;
493
494 Flushes any pending compressed data to the output file/buffer.
495
496 Returns true on success.
497
498 tell
499 Usage is
500
501 $z->tell()
502 tell $z
503
504 Returns the uncompressed file offset.
505
506 eof
507 Usage is
508
509 $z->eof();
510 eof($z);
511
512 Returns true if the "close" method has been called.
513
514 seek
515 $z->seek($position, $whence);
516 seek($z, $position, $whence);
517
518 Provides a sub-set of the "seek" functionality, with the restriction
519 that it is only legal to seek forward in the output file/buffer. It is
520 a fatal error to attempt to seek backward.
521
522 Empty parts of the file/buffer will have NULL (0x00) bytes written to
523 them.
524
525 The $whence parameter takes one the usual values, namely SEEK_SET,
526 SEEK_CUR or SEEK_END.
527
528 Returns 1 on success, 0 on failure.
529
530 binmode
531 Usage is
532
533 $z->binmode
534 binmode $z ;
535
536 This is a noop provided for completeness.
537
538 opened
539 $z->opened()
540
541 Returns true if the object currently refers to a opened file/buffer.
542
543 autoflush
544 my $prev = $z->autoflush()
545 my $prev = $z->autoflush(EXPR)
546
547 If the $z object is associated with a file or a filehandle, this method
548 returns the current autoflush setting for the underlying filehandle. If
549 "EXPR" is present, and is non-zero, it will enable flushing after every
550 write/print operation.
551
552 If $z is associated with a buffer, this method has no effect and always
553 returns "undef".
554
555 Note that the special variable $| cannot be used to set or retrieve the
556 autoflush setting.
557
558 input_line_number
559 $z->input_line_number()
560 $z->input_line_number(EXPR)
561
562 This method always returns "undef" when compressing.
563
564 fileno
565 $z->fileno()
566 fileno($z)
567
568 If the $z object is associated with a file or a filehandle, "fileno"
569 will return the underlying file descriptor. Once the "close" method is
570 called "fileno" will return "undef".
571
572 If the $z object is associated with a buffer, this method will return
573 "undef".
574
575 close
576 $z->close() ;
577 close $z ;
578
579 Flushes any pending compressed data and then closes the output
580 file/buffer.
581
582 For most versions of Perl this method will be automatically invoked if
583 the IO::Compress::Lzma object is destroyed (either explicitly or by the
584 variable with the reference to the object going out of scope). The
585 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
586 cases, the "close" method will be called automatically, but not until
587 global destruction of all live objects when the program is terminating.
588
589 Therefore, if you want your scripts to be able to run on all versions
590 of Perl, you should call "close" explicitly and not rely on automatic
591 closing.
592
593 Returns true on success, otherwise 0.
594
595 If the "AutoClose" option has been enabled when the IO::Compress::Lzma
596 object was created, and the object is associated with a file, the
597 underlying file will also be closed.
598
599 newStream([OPTS])
600 Usage is
601
602 $z->newStream( [OPTS] )
603
604 Closes the current compressed data stream and starts a new one.
605
606 OPTS consists of any of the options that are available when creating
607 the $z object.
608
609 See the "Constructor Options" section for more details.
610
612 No symbolic constants are required by IO::Compress::Lzma at present.
613
614 :all Imports "lzma" and $LzmaError. Same as doing this
615
616 use IO::Compress::Lzma qw(lzma $LzmaError) ;
617
620 General feedback/questions/bug reports should be sent to
621 <https://github.com/pmqs/IO-Compress-Lzma/issues> (preferred) or
622 <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress-Lzma>.
623
625 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
626 IO::Compress::Deflate, IO::Uncompress::Inflate,
627 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
628 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Uncompress::UnLzma,
629 IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzip,
630 IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop,
631 IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd,
632 IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate,
633 IO::Uncompress::AnyUncompress
634
635 IO::Compress::FAQ
636
637 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
638
640 This module was written by Paul Marquess, "pmqs@cpan.org".
641
643 See the Changes file.
644
646 Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
647
648 This program is free software; you can redistribute it and/or modify it
649 under the same terms as Perl itself.
650
651
652
653perl v5.38.0 2023-07-26 IO::Compress::Lzma(3)