1Compress::Raw::Lzma(3)User Contributed Perl DocumentationCompress::Raw::Lzma(3)
2
3
4

NAME

6       Compress::Raw::Lzma - Low-Level Interface to lzma compression library
7

SYNOPSIS

9           use Compress::Raw::Lzma ;
10
11           # Encoders
12           my ($lz, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS]
13               or die "Cannot create lzma object: $status\n";
14
15           my ($lz, $status) = new Compress::Raw::Lzma::AloneEncoder [OPTS]
16               or die "Cannot create lzma object: $status\n";
17
18           my ($lz, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS]
19               or die "Cannot create lzma object: $status\n";
20
21           my ($lz, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS]
22               or die "Cannot create lzma object: $status\n";
23
24           $status = $lz->code($input, $output);
25           $status = $lz->flush($output);
26
27           # Decoders
28           my ($lz, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS]
29               or die "Cannot create bunzip2 object: $status\n";
30
31           my ($lz, $status) = new Compress::Raw::Lzma::AutoDecoder [OPTS]
32               or die "Cannot create bunzip2 object: $status\n";
33
34           my ($lz, $status) = new Compress::Raw::Lzma::StreamDecoder [OPTS]
35               or die "Cannot create bunzip2 object: $status\n";
36
37           my ($lz, $status) = new Compress::Raw::Lzma::RawDecoder [OPTS]
38               or die "Cannot create bunzip2 object: $status\n";
39
40           $status = $lz->code($input, $output);
41
42           my $version = Compress::Raw::Lzma::lzma_version_number();
43           my $version = Compress::Raw::Lzma::lzma_version_string();
44

DESCRIPTION

46       "Compress::Raw::Lzma" provides an interface to the in-memory
47       compression/uncompression functions from the lzma compression library.
48
49       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
54       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

Compression

63       There are four compression interfaces available in this module.
64
65       Compress::Raw::Lzma::EasyEncoder =item
66       Compress::Raw::Lzma::AloneEncoder =item
67       Compress::Raw::Lzma::StreamEncoder =item
68       Compress::Raw::Lzma::RawEncoder
69
70   ($z, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS];
71       Creates a new xz compression object.
72
73       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
77       If not successful, the returned compression object, $z, will be undef
78       and $status will hold the an lzma error code.
79
80       Below is a list of the valid options:
81
82       Preset => $preset
83            Used to choose the compression preset.
84
85            Valid values are 0-9 and "LZMA_PRESET_DEFAULT".
86
87            0 is the fastest compression with the lowest memory usage and the
88            lowest compression.
89
90            9 is the slowest compression with the highest memory usage but
91            with the best compression.
92
93            Defaults to "LZMA_PRESET_DEFAULT".
94
95       Extreme => 0|1
96            Makes the compression a lot slower, but a small compression gain.
97
98            Defaults to 0.
99
100       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
105            Defaults to "LZMA_CHECK_CRC32".
106
107       AppendOutput => 0|1
108            Controls whether the compressed data is appended to the output
109            buffer in the "code" and "flush" methods.
110
111            Defaults to 0.  (Note in versions of this module prior to 2.072
112            the default value was incorrectly documented as 1).
113
114       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
119            Defaults to 16k.
120
121   ($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
125       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
129       If not successful, the returned compression object, $z, will be undef
130       and $status will hold the an lzma error code.
131
132       Below is a list of the valid options:
133
134       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
139            If this option is not present an "Lzma::Filter::Lzma1" object with
140            default values will be used.
141
142       AppendOutput => 0|1
143            Controls whether the compressed data is appended to the output
144            buffer in the "code" and "flush" methods.
145
146            Defaults to 0.  (Note in versions of this module prior to 2.072
147            the default value was incorrectly documented as 1).
148
149       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
154            Defaults to 16k.
155
156   ($z, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS];
157       Creates a xz compression object.
158
159       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
163       If not successful, the returned compression object, $z, will be undef
164       and $status will hold the an lzma error code.
165
166       Below is a list of the valid options:
167
168       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
174            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
178            If this option is not present an "Lzma::Filter::Lzma2" object with
179            default values will be used.
180
181       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
186            Defaults to "LZMA_CHECK_CRC32".
187
188       AppendOutput => 0|1
189            Controls whether the compressed data is appended to the output
190            buffer in the "code" and "flush" methods.
191
192            Defaults to 0.  (Note in versions of this module prior to 2.072
193            the default value was incorrectly documented as 1).
194
195       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
200            Defaults to 16k.
201
202   ($z, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS];
203       Low level access to lzma.
204
205       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
209       If not successful, the returned compression object, $z, will be undef
210       and $status will hold the an lzma error code.
211
212       Below is a list of the valid options:
213
214       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
220            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
224            If this option is not present an "Lzma::Filter::Lzma2" object with
225            default values will be used.
226
227       AppendOutput => 0|1
228            Controls whether the compressed data is appended to the output
229            buffer in the "code" and "flush" methods.
230
231            Defaults to 0.  (Note in versions of this module prior to 2.072
232            the default value was incorrectly documented as 1).
233
234       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
239            Defaults to 16k.
240
241       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
245            Defaults to 0.
246
247   $status = $lz->code($input, $output);
248       Reads the contents of $input, compresses it and writes the compressed
249       data to $output.
250
251       Returns "LZMA_OK" on success and an "lzma" error code on failure.
252
253       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
257   $status = $lz->flush($output, LZMA_FINISH);
258       Flushes any pending compressed data to $output. By default it
259       terminates the compressed data stream.
260
261       Returns "LZMA_OK" on success and an "lzma" error code on failure.
262
263   Example
264       TODO
265

Uncompression

267       There are four uncompression interfaces available in this module.
268
269       Compress::Raw::Lzma::AutoDecoder =item
270       Compress::Raw::Lzma::AloneDecoder =item
271       Compress::Raw::Lzma::StreamDecoder =item
272       Compress::Raw::Lzma::RawDecoder
273
274   ($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
278       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
282       If not successful, the returned uncompression object, $z, will be undef
283       and $status will hold the an lzma error code.
284
285       Below is a list of the valid options:
286
287       -MemLimit
288            The number of bytes to use when uncompressing.
289
290            Default is unlimited.
291
292       -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
297            Default is 16k.
298
299       -AppendOutput
300            This option controls how data is written to the output buffer by
301            the "$i->code" method.
302
303            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
307            If the option is set to true, uncompressed data will be appended
308            to the output buffer by the "$i->code" method.
309
310            This option defaults to false.
311
312       -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
317            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
322            This option defaults to true.
323
324       -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
329            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
335            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
339            If "LimitOutput" is enabled, the "ConsumeInput" option will also
340            be enabled.
341
342            This option defaults to false.
343
344            See "The LimitOutput option" for a discussion on why "LimitOutput"
345            is needed and how to use it.
346
347   ($z, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS] ;
348       Create an object that can uncompress an lzma_alone data stream.
349
350       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
354       If not successful, the returned uncompression object, $z, will be undef
355       and $status will hold the an lzma error code.
356
357       Below is a list of the valid options:
358
359       -MemLimit
360            The number of bytes to use when uncompressing.
361
362            Default is unlimited.
363
364       -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
369            Default is 16k.
370
371       -AppendOutput
372            This option controls how data is written to the output buffer by
373            the "$i->code" method.
374
375            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
379            If the option is set to true, uncompressed data will be appended
380            to the output buffer by the "$i->code" method.
381
382            This option defaults to false.
383
384       -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
389            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
394            This option defaults to true.
395
396       -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
401            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
407            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
411            If "LimitOutput" is enabled, the "ConsumeInput" option will also
412            be enabled.
413
414            This option defaults to false.
415
416            See "The LimitOutput option" for a discussion on why "LimitOutput"
417            is needed and how to use it.
418
419   $status = $z->code($input, $output);
420       Uncompresses $input and writes the uncompressed data to $output.
421
422       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
427       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
434       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

Filters

440       TODO - more here
441
442       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
448       All Lzma Filters are sub-classed from the "Lzma::Filter" base-class.
449
450   Lzma::Filter::Lzma
451       The "Lzma::Filter::Lzma" class is used to... TODO - more here
452
453       There are two subclasses of "Lzma::Filter::Lzma", namely
454       "Lzma::Filter::Lzma1" and "Lzma::Filter::Lzma2".
455
456       The former is typically used with "Compress::Raw::Lzma::AloneEncoder".
457       The latter with "Compress::Raw::Lzma::StreamEncoder".
458
459       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
463       The "Lzma::Filter::Lzma" construction takes the following options.
464
465       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
470            Defaults to "LZMA_DICT_SIZE_DEFAULT".
471
472       PresetDict => $dict
473            Provide an initial dictionary. This value is used to initialize
474            the LZ77 history window.
475
476            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
480            $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
484            If $dict is larger than "DictSize", only the last "DictSize" bytes
485            are processed.
486
487       Lc => $value
488            Number of literal context bits.
489
490            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
494            $value must be a number between "LZMA_LCLP_MIN" and
495            "LZMA_LCLP_MAX".
496
497            Note the sum of the "Lc" and "Lp" options cannot exceed 4.
498
499            Defaults to "LZMA_LC_DEFAULT".
500
501       Lp => $value
502            Number of literal position bits.
503
504            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
509            Defaults to "LZMA_LP_DEFAULT".
510
511       Pb => $value
512            Number of position bits
513
514            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
520            $value must be a number between "LZMA_PB_MIN" and "LZMA_PB_MAX".
521
522            Defaults to "LZMA_PB_DEFAULT".
523
524       Mode => $value
525            The Compression Mode. Valid values are "LZMA_MODE_FAST" and
526            "LZMA_MODE_NORMAL".
527
528            Defaults to "LZMA_MODE_NORMAL".
529
530       Nice => $value
531            Nice length of a match
532
533            Defaults to 64.
534
535       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
539            Defaults to "LZMA_MF_BT4".
540
541       Depth => $value
542            Maximum search depth in the match finder.
543
544            Defaults to 0.
545
546   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
552       Lzma::Filter::X86
553            Filter for x86 binaries.
554
555       Lzma::Filter::PowerPC
556            Filter for Big endian PowerPC binaries.
557
558       Lzma::Filter::IA64
559            Filter for IA64 (Itanium) binaries.
560
561       Lzma::Filter::ARM
562            Filter for ARM binaries.
563
564       Lzma::Filter::ARMThumb
565            Filter for ARMThumb binaries.
566
567       Lzma::Filter::Sparc
568            Filter for Sparc binaries.
569
570   Lzma::Filter::Delta
571       Usage is
572
573           Lzma::Filter::Delta [OPTS]
574
575       Type => $type
576            Defines the type of Delta calculation. The only available type
577            (and therefore the default) is "LZMA_DELTA_TYPE_BYTE",
578
579       Distance => $value
580            Defines the Delta Distance. $value must be a number between
581            "LZMA_DELTA_DIST_MIN" and "LZMA_DELTA_DIST_MAX".
582
583            Default is "LZMA_DELTA_DIST_MIN".
584

Misc

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
590   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
594   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
598   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

Constants

603       The following lzma constants are exported by this module
604
605       TODO - more here
606

SUPPORT

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

SEE ALSO

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
623       IO::Compress::FAQ
624
625       File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib
626

AUTHOR

628       This module was written by Paul Marquess, "pmqs@cpan.org".
629

MODIFICATION HISTORY

631       See the Changes file.
632
634       Copyright (c) 2005-2022 Paul Marquess. All rights reserved.
635
636       This program is free software; you can redistribute it and/or modify it
637       under the same terms as Perl itself.
638
639
640
641perl v5.36.0                      2023-01-23            Compress::Raw::Lzma(3)
Impressum