1Compress::Raw::Lzma(3)User Contributed Perl DocumentationCompress::Raw::Lzma(3)
2
6 Compress::Raw::Lzma - Low-Level Interface to lzma compression library
7
9 use Compress::Raw::Lzma ;
10 # Encoders
12 my ($lz, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS]
13 or die "Cannot create lzma object: $status\n";
14 my ($lz, $status) = new Compress::Raw::Lzma::AloneEncoder [OPTS]
16 or die "Cannot create lzma object: $status\n";
17 my ($lz, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS]
19 or die "Cannot create lzma object: $status\n";
20 my ($lz, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS]
22 or die "Cannot create lzma object: $status\n";
23 $status = $lz->code($input, $output);
25 $status = $lz->flush($output);
26 # Decoders
28 my ($lz, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS]
29 or die "Cannot create bunzip2 object: $status\n";
30 my ($lz, $status) = new Compress::Raw::Lzma::AutoDecoder [OPTS]
32 or die "Cannot create bunzip2 object: $status\n";
33 my ($lz, $status) = new Compress::Raw::Lzma::StreamDecoder [OPTS]
35 or die "Cannot create bunzip2 object: $status\n";
36 my ($lz, $status) = new Compress::Raw::Lzma::RawDecoder [OPTS]
38 or die "Cannot create bunzip2 object: $status\n";
39 $status = $lz->code($input, $output);
41 my $version = Compress::Raw::Lzma::lzma_version_number();
43 my $version = Compress::Raw::Lzma::lzma_version_string();
44
46 "Compress::Raw::Lzma" provides an interface to the in-memory
47 compression/uncompression functions from the lzma compression library.
48 Although the primary purpose for the existence of "Compress::Raw::Lzma"
50 is for use by the "IO::Compress::Lzma", "IO::Uncompress::UnLzma",
51 "IO::Compress::Xz" and "IO::Uncompress::UnXz" modules, it can be used
52 on its own for simple compression/uncompression tasks.
53 There are two functions, called "code" and "flush", used in all the
55 compression and uncompression interfaces defined in this module. By
56 default both of these functions overwrites any data stored in its
57 output buffer parameter. If you want to compress/uncompress to a single
58 buffer, and have "code" and "flush" append to that buffer, enable the
59 "AppendOutput" option when you create the compression/decompression
60 object.
61
63 There are four compression interfaces available in this module.
64 Compress::Raw::Lzma::EasyEncoder =item
66 Compress::Raw::Lzma::AloneEncoder =item
67 Compress::Raw::Lzma::StreamEncoder =item
68 Compress::Raw::Lzma::RawEncoder
69 ($z, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS];
71 Creates a new xz compression object.
72 If successful, it will return the initialised compression object, $z
74 and a $status of "LZMA_OK" in a list context. In scalar context it
75 returns the deflation object, $z, only.
76 If not successful, the returned compression object, $z, will be undef
78 and $status will hold the an lzma error code.
79 Below is a list of the valid options:
81 Preset => $preset
83 Used to choose the compression preset.
84 Valid values are 0-9 and "LZMA_PRESET_DEFAULT".
86 0 is the fastest compression with the lowest memory usage and the
88 lowest compression.
89 9 is the slowest compression with the highest memory usage but
91 with the best compression.
92 Defaults to "LZMA_PRESET_DEFAULT".
94 Extreme => 0|1
96 Makes the compression a lot slower, but a small compression gain.
97 Defaults to 0.
99 Check => $check
101 Used to specify the integrity check used in the xz data stream.
102 Valid values are "LZMA_CHECK_NONE", "LZMA_CHECK_CRC32",
103 "LZMA_CHECK_CRC64", "LZMA_CHECK_SHA256".
104 Defaults to "LZMA_CHECK_CRC32".
106 AppendOutput => 0|1
108 Controls whether the compressed data is appended to the output
109 buffer in the "code" and "flush" methods.
110 Defaults to 0. (Note in versions of this module prior to 2.072
112 the default value was incorrectly documented as 1).
113 BufSize => $number
115 Sets the initial size for the output buffer used by the "$d->code"
116 method. If the buffer has to be reallocated to increase the size,
117 it will grow in increments of "Bufsize".
118 Defaults to 16k.
120 ($z, $status) = new Compress::Raw::Lzma::AloneEncoder [OPTS];
122 Creates a legacy lzma compression object. This format is also know as
123 lzma_alone.
124 If successful, it will return the initialised compression object, $z
126 and a $status of "LZMA_OK" in a list context. In scalar context it
127 returns the deflation object, $z, only.
128 If not successful, the returned compression object, $z, will be undef
130 and $status will hold the an lzma error code.
131 Below is a list of the valid options:
133 Filter => $filter
135 The $filter option must be an object of type
136 "Lzma::Filter::Lzma1". See "Lzma::Filter::Lzma" in
137 Compress::Raw::Lzma for a definition of "Lzma::Filter::Lzma1".
138 If this option is not present an "Lzma::Filter::Lzma1" object with
140 default values will be used.
141 AppendOutput => 0|1
143 Controls whether the compressed data is appended to the output
144 buffer in the "code" and "flush" methods.
145 Defaults to 0. (Note in versions of this module prior to 2.072
147 the default value was incorrectly documented as 1).
148 BufSize => $number
150 Sets the initial size for the output buffer used by the "$d->code"
151 method. If the buffer has to be reallocated to increase the size,
152 it will grow in increments of "Bufsize".
153 Defaults to 16k.
155 ($z, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS];
157 Creates a xz compression object.
158 If successful, it will return the initialised compression object, $z
160 and a $status of "LZMA_OK" in a list context. In scalar context it
161 returns the deflation object, $z, only.
162 If not successful, the returned compression object, $z, will be undef
164 and $status will hold the an lzma error code.
165 Below is a list of the valid options:
167 Filter => $filter =item Filter => [$filter1, $filter2,...]
169 This option is used to change the bahaviour of the StreamEncoder
170 by applying between one and "LZMA_FILTERS_MAX" filters to the data
171 stream during compression. See "Filters" for more details on the
172 available filters.
173 If this option is present it must either contain a single
175 "Lzma::Filter::Lzma" filter object or an array reference
176 containing between one and "LZMA_FILTERS_MAX" filter objects.
177 If this option is not present an "Lzma::Filter::Lzma2" object with
179 default values will be used.
180 Check => $check
182 Used to specify the integrity check used in the xz data stream.
183 Valid values are "LZMA_CHECK_NONE", "LZMA_CHECK_CRC32",
184 "LZMA_CHECK_CRC64", "LZMA_CHECK_SHA256".
185 Defaults to "LZMA_CHECK_CRC32".
187 AppendOutput => 0|1
189 Controls whether the compressed data is appended to the output
190 buffer in the "code" and "flush" methods.
191 Defaults to 0. (Note in versions of this module prior to 2.072
193 the default value was incorrectly documented as 1).
194 BufSize => $number
196 Sets the initial size for the output buffer used by the "$d->code"
197 method. If the buffer has to be reallocated to increase the size,
198 it will grow in increments of "Bufsize".
199 Defaults to 16k.
201 ($z, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS];
203 Low level access to lzma.
204 If successful, it will return the initialised compression object, $z
206 and a $status of "LZMA_OK" in a list context. In scalar context it
207 returns the deflation object, $z, only.
208 If not successful, the returned compression object, $z, will be undef
210 and $status will hold the an lzma error code.
211 Below is a list of the valid options:
213 Filter => $filter =item Filter => [$filter1, $filter2,...]
215 This option is used to change the bahaviour of the RawEncoder by
216 applying between one and "LZMA_FILTERS_MAX" filters to the data
217 stream during compression. See "Filters" for more details on the
218 available filters.
219 If this option is present it must either contain a single
221 "Lzma::Filter::Lzma" filter object or an array reference
222 containing between one and "LZMA_FILTERS_MAX" filter objects.
223 If this option is not present an "Lzma::Filter::Lzma2" object with
225 default values will be used.
226 AppendOutput => 0|1
228 Controls whether the compressed data is appended to the output
229 buffer in the "code" and "flush" methods.
230 Defaults to 0. (Note in versions of this module prior to 2.072
232 the default value was incorrectly documented as 1).
233 BufSize => $number
235 Sets the initial size for the output buffer used by the "$d->code"
236 method. If the buffer has to be reallocated to increase the size,
237 it will grow in increments of "Bufsize".
238 Defaults to 16k.
240 ForZip => 1/0
242 This boolean option is used to enable prefixing the compressed
243 data stream with an encoded copy of the filter properties.
244 Defaults to 0.
246 $status = $lz->code($input, $output);
248 Reads the contents of $input, compresses it and writes the compressed
249 data to $output.
250 Returns "LZMA_OK" on success and an "lzma" error code on failure.
252 If "appendOutput" is enabled in the constructor for the lzma object,
254 the compressed data will be appended to $output. If not enabled,
255 $output will be truncated before the compressed data is written to it.
256 $status = $lz->flush($output, LZMA_FINISH);
258 Flushes any pending compressed data to $output. By default it
259 terminates the compressed data stream.
260 Returns "LZMA_OK" on success and an "lzma" error code on failure.
262 Example
264 TODO
265
267 There are four uncompression interfaces available in this module.
268 Compress::Raw::Lzma::AutoDecoder =item
270 Compress::Raw::Lzma::AloneDecoder =item
271 Compress::Raw::Lzma::StreamDecoder =item
272 Compress::Raw::Lzma::RawDecoder
273 ($z, $status) = new Compress::Raw::Lzma::AutoDecoder [OPTS] ;
275 Create an object that can uncompress any of the compressed data streams
276 that can be created by this module.
277 If successful, it will return the initialised uncompression object, $z
279 and a $status of "LZMA_OK" in a list context. In scalar context it
280 returns the deflation object, $z, only.
281 If not successful, the returned uncompression object, $z, will be undef
283 and $status will hold the an lzma error code.
284 Below is a list of the valid options:
286 -MemLimit
288 The number of bytes to use when uncompressing.
289 Default is unlimited.
291 -Bufsize
293 Sets the initial size for the output buffer used by the "$i->code"
294 method. If the output buffer in this method has to be reallocated
295 to increase the size, it will grow in increments of "Bufsize".
296 Default is 16k.
298 -AppendOutput
300 This option controls how data is written to the output buffer by
301 the "$i->code" method.
302 If the option is set to false, the output buffer in the "$i->code"
304 method will be truncated before uncompressed data is written to
305 it.
306 If the option is set to true, uncompressed data will be appended
308 to the output buffer by the "$i->code" method.
309 This option defaults to false.
311 -ConsumeInput
313 If set to true, this option will remove compressed data from the
314 input buffer of the "$i->code" method as the uncompression
315 progresses.
316 This option can be useful when you are processing compressed data
318 that is embedded in another file/buffer. In this case the data
319 that immediately follows the compressed stream will be left in the
320 input buffer.
321 This option defaults to true.
323 -LimitOutput
325 The "LimitOutput" option changes the behavior of the "$i->code"
326 method so that the amount of memory used by the output buffer can
327 be limited.
328 When "LimitOutput" is used the size of the output buffer used will
330 either be the value of the "Bufsize" option or the amount of
331 memory already allocated to $output, whichever is larger.
332 Predicting the output size available is tricky, so don't rely on
333 getting an exact output buffer size.
334 When "LimitOutout" is not specified "$i->code" will use as much
336 memory as it takes to write all the uncompressed data it creates
337 by uncompressing the input buffer.
338 If "LimitOutput" is enabled, the "ConsumeInput" option will also
340 be enabled.
341 This option defaults to false.
343 See "The LimitOutput option" for a discussion on why "LimitOutput"
345 is needed and how to use it.
346 ($z, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS] ;
348 Create an object that can uncompress an lzma_alone data stream.
349 If successful, it will return the initialised uncompression object, $z
351 and a $status of "LZMA_OK" in a list context. In scalar context it
352 returns the deflation object, $z, only.
353 If not successful, the returned uncompression object, $z, will be undef
355 and $status will hold the an lzma error code.
356 Below is a list of the valid options:
358 -MemLimit
360 The number of bytes to use when uncompressing.
361 Default is unlimited.
363 -Bufsize
365 Sets the initial size for the output buffer used by the "$i->code"
366 method. If the output buffer in this method has to be reallocated
367 to increase the size, it will grow in increments of "Bufsize".
368 Default is 16k.
370 -AppendOutput
372 This option controls how data is written to the output buffer by
373 the "$i->code" method.
374 If the option is set to false, the output buffer in the "$i->code"
376 method will be truncated before uncompressed data is written to
377 it.
378 If the option is set to true, uncompressed data will be appended
380 to the output buffer by the "$i->code" method.
381 This option defaults to false.
383 -ConsumeInput
385 If set to true, this option will remove compressed data from the
386 input buffer of the "$i->code" method as the uncompression
387 progresses.
388 This option can be useful when you are processing compressed data
390 that is embedded in another file/buffer. In this case the data
391 that immediately follows the compressed stream will be left in the
392 input buffer.
393 This option defaults to true.
395 -LimitOutput
397 The "LimitOutput" option changes the behavior of the "$i->code"
398 method so that the amount of memory used by the output buffer can
399 be limited.
400 When "LimitOutput" is used the size of the output buffer used will
402 either be the value of the "Bufsize" option or the amount of
403 memory already allocated to $output, whichever is larger.
404 Predicting the output size available is tricky, so don't rely on
405 getting an exact output buffer size.
406 When "LimitOutout" is not specified "$i->code" will use as much
408 memory as it takes to write all the uncompressed data it creates
409 by uncompressing the input buffer.
410 If "LimitOutput" is enabled, the "ConsumeInput" option will also
412 be enabled.
413 This option defaults to false.
415 See "The LimitOutput option" for a discussion on why "LimitOutput"
417 is needed and how to use it.
418 $status = $z->code($input, $output);
420 Uncompresses $input and writes the uncompressed data to $output.
421 Returns "LZMA_OK" if the uncompression was successful, but the end of
423 the compressed data stream has not been reached. Returns
424 "LZMA_STREAM_END" on successful uncompression and the end of the
425 compression stream has been reached.
426 If "consumeInput" is enabled in the constructor for the lzma object,
428 $input will have all compressed data removed from it after
429 uncompression. On "LZMA_OK" return this will mean that $input will be
430 an empty string; when "LZMA_STREAM_END" $input will either be an empty
431 string or will contain whatever data immediately followed the
432 compressed data stream.
433 If "appendOutput" is enabled in the constructor for the lzma object,
435 the uncompressed data will be appended to $output. If not enabled,
436 $output will be truncated before the uncompressed data is written to
437 it.
438
440 TODO - more here
441 A number of the Lzma compression interfaces (namely
443 "Compress::Raw::Lzma::StreamEncoder" &
444 "Compress::Raw::Lzma::AloneEncoder") and the raw lzma uncompression
445 interface make use of filters. These filters are used to change the
446 behaviour of compression (and raw uncompression).
447 All Lzma Filters are sub-classed from the "Lzma::Filter" base-class.
449 Lzma::Filter::Lzma
451 The "Lzma::Filter::Lzma" class is used to... TODO - more here
452 There are two subclasses of "Lzma::Filter::Lzma", namely
454 "Lzma::Filter::Lzma1" and "Lzma::Filter::Lzma2".
455 The former is typically used with "Compress::Raw::Lzma::AloneEncoder".
457 The latter with "Compress::Raw::Lzma::StreamEncoder".
458 When using Lzma filters an "Lzma::Filter::Lzma" must be included and it
460 must be the last filter in the chain. There can only be one
461 "Lzma::Filter::Lzma" filter in any filter chain.
462 The "Lzma::Filter::Lzma" construction takes the following options.
464 DictSize => $value
466 Dictionary size in bytes. This controls how many bytes of the
467 recently processed uncompressed data is kept in memory. The size
468 of the dictionary must be at least "LZMA_DICT_SIZE_MIN".
469 Defaults to "LZMA_DICT_SIZE_DEFAULT".
471 PresetDict => $dict
473 Provide an initial dictionary. This value is used to initialize
474 the LZ77 history window.
475 This feature only works correctly with raw encoding and decoding.
477 You may not be able to decode other formats that have been encoded
478 with a preset dictionary.
479 $dict should contain typical strings that occur in the files being
481 compressed, with the most probably strings near the end fo the
482 preset dictionary.
483 If $dict is larger than "DictSize", only the last "DictSize" bytes
485 are processed.
486 Lc => $value
488 Number of literal context bits.
489 How many of the highest bits of the previous uncompressed eight-
491 bit byte (also known as `literal') are taken into account when
492 predicting the bits of the next literal.
493 $value must be a number between "LZMA_LCLP_MIN" and
495 "LZMA_LCLP_MAX".
496 Note the sum of the "Lc" and "Lp" options cannot exceed 4.
498 Defaults to "LZMA_LC_DEFAULT".
500 Lp => $value
502 Number of literal position bits.
503 How many of the lowest bits of the current position (number of
505 bytes from the beginning of the uncompressed data) in the
506 uncompressed data is taken into account when predicting the bits
507 of the next literal (a single eight-bit byte).
508 Defaults to "LZMA_LP_DEFAULT".
510 Pb => $value
512 Number of position bits
513 How many of the lowest bits of the current position in the
515 uncompressed data is taken into account when estimating
516 probabilities of matches. A match is a sequence of bytes for which
517 a matching sequence is found from the dictionary and thus can be
518 stored as distance-length pair.
519 $value must be a number between "LZMA_PB_MIN" and "LZMA_PB_MAX".
521 Defaults to "LZMA_PB_DEFAULT".
523 Mode => $value
525 The Compression Mode. Valid values are "LZMA_MODE_FAST" and
526 "LZMA_MODE_NORMAL".
527 Defaults to "LZMA_MODE_NORMAL".
529 Nice => $value
531 Nice length of a match
532 Defaults to 64.
534 Mf => $value
536 Defines which Match Finder to use. Valid values are "LZMA_MF_HC3"
537 "LZMA_MF_HC4", "LZMA_MF_BT2" "LZMA_MF_BT3" and "LZMA_MF_BT4".
538 Defaults to "LZMA_MF_BT4".
540 Depth => $value
542 Maximum search depth in the match finder.
543 Defaults to 0.
545 Lzma::Filter::BCJ
547 The sub-classes of "Lzma::Filter::BCJ" are the Branch/Call/Jump
548 conversion filters. These filters are used to rewrite executable binary
549 code for a number of processor architectures. None of these classes
550 take any options.
551 Lzma::Filter::X86
553 Filter for x86 binaries.
554 Lzma::Filter::PowerPC
556 Filter for Big endian PowerPC binaries.
557 Lzma::Filter::IA64
559 Filter for IA64 (Itanium) binaries.
560 Lzma::Filter::ARM
562 Filter for ARM binaries.
563 Lzma::Filter::ARMThumb
565 Filter for ARMThumb binaries.
566 Lzma::Filter::Sparc
568 Filter for Sparc binaries.
569 Lzma::Filter::Delta
571 Usage is
572 Lzma::Filter::Delta [OPTS]
574 Type => $type
576 Defines the type of Delta calculation. The only available type
577 (and therefore the default) is "LZMA_DELTA_TYPE_BYTE",
578 Distance => $value
580 Defines the Delta Distance. $value must be a number between
581 "LZMA_DELTA_DIST_MIN" and "LZMA_DELTA_DIST_MAX".
582 Default is "LZMA_DELTA_DIST_MIN".
584
586 my $version = Compress::Raw::Lzma::lzma_version_number();
587 Returns the version of the underlying lzma library this module is using
588 at run-time as a number.
589 my $version = Compress::Raw::Lzma::lzma_version_string();
591 Returns the version of the underlying lzma library this module is using
592 at run-time as a string.
593 my $version = Compress::Raw::Lzma::LZMA_VERSION();
595 Returns the version of the underlying lzma library this module was
596 using at compile-time as a number.
597 my $version = Compress::Raw::Lzma::LZMA_VERSION_STRING();
599 Returns the version of the underlying lzma library this module was
600 using at compile-time as a string.
601
603 The following lzma constants are exported by this module
604 TODO - more here
606
608 General feedback/questions/bug reports should be sent to
609 <https://github.com/pmqs/Compress-Raw-Lzma/issues> (preferred) or
610 <https://rt.cpan.org/Public/Dist/Display.html?Name=Compress-Raw-Lzma>.
611
613 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip,
614 IO::Compress::Deflate, IO::Uncompress::Inflate,
615 IO::Compress::RawDeflate, IO::Uncompress::RawInflate,
616 IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma,
617 IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz,
618 IO::Compress::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop,
619 IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf,
620 IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate,
621 IO::Uncompress::AnyUncompress
622 IO::Compress::FAQ
624 File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
626
628 This module was written by Paul Marquess, "pmqs@cpan.org".
629
631 See the Changes file.
632
634 Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
635 This program is free software; you can redistribute it and/or modify it
637 under the same terms as Perl itself.
638perl v5.36.0 2023-02-09 Compress::Raw::Lzma(3)