.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Compress::Raw::Lzma 3"
.TH Compress::Raw::Lzma 3 "2021-02-20" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Compress::Raw::Lzma \- Low\-Level Interface to lzma compression library
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Compress::Raw::Lzma ;
\&
\&    # Encoders
\&    my ($lz, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS]
\&        or die "Cannot create lzma object: $status\en";
\&
\&    my ($lz, $status) = new Compress::Raw::Lzma::AloneEncoder [OPTS]
\&        or die "Cannot create lzma object: $status\en";
\&
\&    my ($lz, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS]
\&        or die "Cannot create lzma object: $status\en";
\&
\&    my ($lz, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS]
\&        or die "Cannot create lzma object: $status\en";
\&
\&    $status = $lz\->code($input, $output);
\&    $status = $lz\->flush($output);
\&
\&    # Decoders
\&    my ($lz, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS]
\&        or die "Cannot create bunzip2 object: $status\en";
\&
\&    my ($lz, $status) = new Compress::Raw::Lzma::AutoDecoder [OPTS]
\&        or die "Cannot create bunzip2 object: $status\en";
\&
\&    my ($lz, $status) = new Compress::Raw::Lzma::StreamDecoder [OPTS]
\&        or die "Cannot create bunzip2 object: $status\en";
\&
\&    my ($lz, $status) = new Compress::Raw::Lzma::RawDecoder [OPTS]
\&        or die "Cannot create bunzip2 object: $status\en";
\&
\&    $status = $lz\->code($input, $output);
\&
\&    my $version = Compress::Raw::Lzma::lzma_version_number();
\&    my $version = Compress::Raw::Lzma::lzma_version_string();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Compress::Raw::Lzma\*(C'\fR provides an interface to the in-memory
compression/uncompression functions from the lzma compression library.
.PP
Although the primary purpose for the existence of \f(CW\*(C`Compress::Raw::Lzma\*(C'\fR is
for use by the  \f(CW\*(C`IO::Compress::Lzma\*(C'\fR, \f(CW\*(C`IO::Uncompress::UnLzma\*(C'\fR,
\&\f(CW\*(C`IO::Compress::Xz\*(C'\fR and \f(CW\*(C`IO::Uncompress::UnXz\*(C'\fR modules, it can be used on
its own for simple compression/uncompression tasks.
.PP
There are two functions, called \f(CW\*(C`code\*(C'\fR and \f(CW\*(C`flush\*(C'\fR, used in all the
compression and uncompression interfaces defined in this module. By default
both of these functions overwrites any data stored in its output buffer
parameter. If you want to compress/uncompress to a single buffer, and have
\&\f(CW\*(C`code\*(C'\fR and \f(CW\*(C`flush\*(C'\fR append to that buffer, enable the \f(CW\*(C`AppendOutput\*(C'\fR
option when you create the compression/decompression object.
.SH "Compression"
.IX Header "Compression"
There are four compression interfaces available in this module.
.IP "Compress::Raw::Lzma::EasyEncoder =item Compress::Raw::Lzma::AloneEncoder =item Compress::Raw::Lzma::StreamEncoder =item Compress::Raw::Lzma::RawEncoder" 5
.IX Item "Compress::Raw::Lzma::EasyEncoder =item Compress::Raw::Lzma::AloneEncoder =item Compress::Raw::Lzma::StreamEncoder =item Compress::Raw::Lzma::RawEncoder"
.ie n .SS "($z, $status) = new Compress::Raw::Lzma::EasyEncoder [\s-1OPTS\s0];"
.el .SS "($z, \f(CW$status\fP) = new Compress::Raw::Lzma::EasyEncoder [\s-1OPTS\s0];"
.IX Subsection "($z, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS];"
Creates a new \fIxz\fR compression object.
.PP
If successful, it will return the initialised compression object, \f(CW$z\fR
and a \f(CW$status\fR of \f(CW\*(C`LZMA_OK\*(C'\fR in a list context. In scalar context it
returns the deflation object, \f(CW$z\fR, only.
.PP
If not successful, the returned compression object, \f(CW$z\fR, will be
\&\fIundef\fR and \f(CW$status\fR will hold the an \fIlzma\fR error code.
.PP
Below is a list of the valid options:
.IP "\fBPreset => \f(CB$preset\fB\fR" 5
.IX Item "Preset => $preset"
Used to choose the compression preset.
.Sp
Valid values are 0\-9 and \f(CW\*(C`LZMA_PRESET_DEFAULT\*(C'\fR.
.Sp
0 is the fastest compression with the lowest memory usage and the lowest
compression.
.Sp
9 is the slowest compression with the highest memory usage but with the best
compression.
.Sp
Defaults to \f(CW\*(C`LZMA_PRESET_DEFAULT\*(C'\fR.
.IP "\fBExtreme => 0|1\fR" 5
.IX Item "Extreme => 0|1"
Makes the compression a lot slower, but a small compression gain.
.Sp
Defaults to 0.
.IP "\fBCheck => \f(CB$check\fB\fR" 5
.IX Item "Check => $check"
Used to specify the integrity check used in the xz data stream.
Valid values are \f(CW\*(C`LZMA_CHECK_NONE\*(C'\fR, \f(CW\*(C`LZMA_CHECK_CRC32\*(C'\fR,
\&\f(CW\*(C`LZMA_CHECK_CRC64\*(C'\fR, \f(CW\*(C`LZMA_CHECK_SHA256\*(C'\fR.
.Sp
Defaults to \f(CW\*(C`LZMA_CHECK_CRC32\*(C'\fR.
.IP "\fBAppendOutput => 0|1\fR" 5
.IX Item "AppendOutput => 0|1"
Controls whether the compressed data is appended to the output buffer in
the \f(CW\*(C`code\*(C'\fR and \f(CW\*(C`flush\*(C'\fR methods.
.Sp
Defaults to 0.
(Note in versions of this module prior to 2.072 the default value was
incorrectly documented as 1).
.IP "\fBBufSize => \f(CB$number\fB\fR" 5
.IX Item "BufSize => $number"
Sets the initial size for the output buffer used by the \f(CW\*(C`$d\->code\*(C'\fR
method. If the buffer has to be reallocated to increase the size, it will
grow in increments of \f(CW\*(C`Bufsize\*(C'\fR.
.Sp
Defaults to 16k.
.ie n .SS "($z, $status) = new Compress::Raw::Lzma::AloneEncoder [\s-1OPTS\s0];"
.el .SS "($z, \f(CW$status\fP) = new Compress::Raw::Lzma::AloneEncoder [\s-1OPTS\s0];"
.IX Subsection "($z, $status) = new Compress::Raw::Lzma::AloneEncoder [OPTS];"
Creates a legacy \fIlzma\fR compression object. This format is also know as
lzma_alone.
.PP
If successful, it will return the initialised compression object, \f(CW$z\fR
and a \f(CW$status\fR of \f(CW\*(C`LZMA_OK\*(C'\fR in a list context. In scalar context it
returns the deflation object, \f(CW$z\fR, only.
.PP
If not successful, the returned compression object, \f(CW$z\fR, will be
\&\fIundef\fR and \f(CW$status\fR will hold the an \fIlzma\fR error code.
.PP
Below is a list of the valid options:
.IP "\fBFilter => \f(CB$filter\fB\fR" 5
.IX Item "Filter => $filter"
The \f(CW $filter \fR option must be an object of type \f(CW\*(C`Lzma::Filter::Lzma1\*(C'\fR.
See \*(L"Lzma::Filter::Lzma\*(R" in Compress::Raw::Lzma for a definition
of \f(CW\*(C`Lzma::Filter::Lzma1\*(C'\fR.
.Sp
If this option is not present an \f(CW\*(C`Lzma::Filter::Lzma1\*(C'\fR object with default
values will be used.
.IP "\fBAppendOutput => 0|1\fR" 5
.IX Item "AppendOutput => 0|1"
Controls whether the compressed data is appended to the output buffer in
the \f(CW\*(C`code\*(C'\fR and \f(CW\*(C`flush\*(C'\fR methods.
.Sp
Defaults to 0.
(Note in versions of this module prior to 2.072 the default value was
incorrectly documented as 1).
.IP "\fBBufSize => \f(CB$number\fB\fR" 5
.IX Item "BufSize => $number"
Sets the initial size for the output buffer used by the \f(CW\*(C`$d\->code\*(C'\fR
method. If the buffer has to be reallocated to increase the size, it will
grow in increments of \f(CW\*(C`Bufsize\*(C'\fR.
.Sp
Defaults to 16k.
.ie n .SS "($z, $status) = new Compress::Raw::Lzma::StreamEncoder [\s-1OPTS\s0];"
.el .SS "($z, \f(CW$status\fP) = new Compress::Raw::Lzma::StreamEncoder [\s-1OPTS\s0];"
.IX Subsection "($z, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS];"
Creates a \fIxz\fR compression object.
.PP
If successful, it will return the initialised compression object, \f(CW$z\fR
and a \f(CW$status\fR of \f(CW\*(C`LZMA_OK\*(C'\fR in a list context. In scalar context it
returns the deflation object, \f(CW$z\fR, only.
.PP
If not successful, the returned compression object, \f(CW$z\fR, will be
\&\fIundef\fR and \f(CW$status\fR will hold the an \fIlzma\fR error code.
.PP
Below is a list of the valid options:
.IP "\fBFilter => \f(CB$filter\fB\fR =item \fBFilter => [$filter1, \f(CB$filter2\fB,...]\fR" 5
.IX Item "Filter => $filter =item Filter => [$filter1, $filter2,...]"
This option is used to change the bahaviour of the StreamEncoder by
applying between one and \f(CW\*(C`LZMA_FILTERS_MAX\*(C'\fR filters to the data stream
during compression. See \*(L"Filters\*(R" for more details on the available
filters.
.Sp
If this option is present it must either contain a single
\&\f(CW\*(C`Lzma::Filter::Lzma\*(C'\fR filter object or an array reference containing between
one and \f(CW\*(C`LZMA_FILTERS_MAX\*(C'\fR filter objects.
.Sp
If this option is not present an \f(CW\*(C`Lzma::Filter::Lzma2\*(C'\fR object with default
values will be used.
.IP "\fBCheck => \f(CB$check\fB\fR" 5
.IX Item "Check => $check"
Used to specify the integrity check used in the xz data stream.
Valid values are \f(CW\*(C`LZMA_CHECK_NONE\*(C'\fR, \f(CW\*(C`LZMA_CHECK_CRC32\*(C'\fR,
\&\f(CW\*(C`LZMA_CHECK_CRC64\*(C'\fR, \f(CW\*(C`LZMA_CHECK_SHA256\*(C'\fR.
.Sp
Defaults to \f(CW\*(C`LZMA_CHECK_CRC32\*(C'\fR.
.IP "\fBAppendOutput => 0|1\fR" 5
.IX Item "AppendOutput => 0|1"
Controls whether the compressed data is appended to the output buffer in
the \f(CW\*(C`code\*(C'\fR and \f(CW\*(C`flush\*(C'\fR methods.
.Sp
Defaults to 0.
(Note in versions of this module prior to 2.072 the default value was
incorrectly documented as 1).
.IP "\fBBufSize => \f(CB$number\fB\fR" 5
.IX Item "BufSize => $number"
Sets the initial size for the output buffer used by the \f(CW\*(C`$d\->code\*(C'\fR
method. If the buffer has to be reallocated to increase the size, it will
grow in increments of \f(CW\*(C`Bufsize\*(C'\fR.
.Sp
Defaults to 16k.
.ie n .SS "($z, $status) = new Compress::Raw::Lzma::RawEncoder [\s-1OPTS\s0];"
.el .SS "($z, \f(CW$status\fP) = new Compress::Raw::Lzma::RawEncoder [\s-1OPTS\s0];"
.IX Subsection "($z, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS];"
Low level access to lzma.
.PP
If successful, it will return the initialised compression object, \f(CW$z\fR
and a \f(CW$status\fR of \f(CW\*(C`LZMA_OK\*(C'\fR in a list context. In scalar context it
returns the deflation object, \f(CW$z\fR, only.
.PP
If not successful, the returned compression object, \f(CW$z\fR, will be
\&\fIundef\fR and \f(CW$status\fR will hold the an \fIlzma\fR error code.
.PP
Below is a list of the valid options:
.IP "\fBFilter => \f(CB$filter\fB\fR =item \fBFilter => [$filter1, \f(CB$filter2\fB,...]\fR" 5
.IX Item "Filter => $filter =item Filter => [$filter1, $filter2,...]"
This option is used to change the bahaviour of the RawEncoder by
applying between one and \f(CW\*(C`LZMA_FILTERS_MAX\*(C'\fR filters to the data stream
during compression. See \*(L"Filters\*(R" for more details on the available
filters.
.Sp
If this option is present it must either contain a single
\&\f(CW\*(C`Lzma::Filter::Lzma\*(C'\fR filter object or an array reference containing between
one and \f(CW\*(C`LZMA_FILTERS_MAX\*(C'\fR filter objects.
.Sp
If this option is not present an \f(CW\*(C`Lzma::Filter::Lzma2\*(C'\fR object with default
values will be used.
.IP "\fBAppendOutput => 0|1\fR" 5
.IX Item "AppendOutput => 0|1"
Controls whether the compressed data is appended to the output buffer in
the \f(CW\*(C`code\*(C'\fR and \f(CW\*(C`flush\*(C'\fR methods.
.Sp
Defaults to 0.
(Note in versions of this module prior to 2.072 the default value was
incorrectly documented as 1).
.IP "\fBBufSize => \f(CB$number\fB\fR" 5
.IX Item "BufSize => $number"
Sets the initial size for the output buffer used by the \f(CW\*(C`$d\->code\*(C'\fR
method. If the buffer has to be reallocated to increase the size, it will
grow in increments of \f(CW\*(C`Bufsize\*(C'\fR.
.Sp
Defaults to 16k.
.IP "\fBForZip => 1/0\fR" 5
.IX Item "ForZip => 1/0"
This boolean option is used to enable prefixing the compressed data stream
with an encoded copy of the filter properties.
.Sp
Defaults to 0.
.ie n .SS "$status = $lz\->code($input, $output);"
.el .SS "\f(CW$status\fP = \f(CW$lz\fP\->code($input, \f(CW$output\fP);"
.IX Subsection "$status = $lz->code($input, $output);"
Reads the contents of \f(CW$input\fR, compresses it and writes the compressed
data to \f(CW$output\fR.
.PP
Returns \f(CW\*(C`LZMA_OK\*(C'\fR on success and an \f(CW\*(C`lzma\*(C'\fR error code on failure.
.PP
If \f(CW\*(C`appendOutput\*(C'\fR is enabled in the constructor for the lzma object, the
compressed data will be appended to \f(CW$output\fR. If not enabled, \f(CW$output\fR
will be truncated before the compressed data is written to it.
.ie n .SS "$status = $lz\->flush($output, \s-1LZMA_FINISH\s0);"
.el .SS "\f(CW$status\fP = \f(CW$lz\fP\->flush($output, \s-1LZMA_FINISH\s0);"
.IX Subsection "$status = $lz->flush($output, LZMA_FINISH);"
Flushes any pending compressed data to \f(CW$output\fR. By default it terminates
the compressed data stream.
.PP
Returns \f(CW\*(C`LZMA_OK\*(C'\fR on success and an \f(CW\*(C`lzma\*(C'\fR error code on failure.
.SS "Example"
.IX Subsection "Example"
\&\s-1TODO\s0
.SH "Uncompression"
.IX Header "Uncompression"
There are four uncompression interfaces available in this module.
.IP "Compress::Raw::Lzma::AutoDecoder =item Compress::Raw::Lzma::AloneDecoder =item Compress::Raw::Lzma::StreamDecoder =item Compress::Raw::Lzma::RawDecoder" 5
.IX Item "Compress::Raw::Lzma::AutoDecoder =item Compress::Raw::Lzma::AloneDecoder =item Compress::Raw::Lzma::StreamDecoder =item Compress::Raw::Lzma::RawDecoder"
.ie n .SS "($z, $status) = new Compress::Raw::Lzma::AutoDecoder [\s-1OPTS\s0] ;"
.el .SS "($z, \f(CW$status\fP) = new Compress::Raw::Lzma::AutoDecoder [\s-1OPTS\s0] ;"
.IX Subsection "($z, $status) = new Compress::Raw::Lzma::AutoDecoder [OPTS] ;"
Create an object that can uncompress any of the compressed data streams
that can be created by this module.
.PP
If successful, it will return the initialised uncompression object, \f(CW$z\fR
and a \f(CW$status\fR of \f(CW\*(C`LZMA_OK\*(C'\fR in a list context. In scalar context it
returns the deflation object, \f(CW$z\fR, only.
.PP
If not successful, the returned uncompression object, \f(CW$z\fR, will be
\&\fIundef\fR and \f(CW$status\fR will hold the an \fIlzma\fR error code.
.PP
Below is a list of the valid options:
.IP "\fB\-MemLimit\fR" 5
.IX Item "-MemLimit"
The number of bytes to use when uncompressing.
.Sp
Default is unlimited.
.IP "\fB\-Bufsize\fR" 5
.IX Item "-Bufsize"
Sets the initial size for the output buffer used by the \f(CW\*(C`$i\->code\*(C'\fR
method. If the output buffer in this method has to be reallocated to
increase the size, it will grow in increments of \f(CW\*(C`Bufsize\*(C'\fR.
.Sp
Default is 16k.
.IP "\fB\-AppendOutput\fR" 5
.IX Item "-AppendOutput"
This option controls how data is written to the output buffer by the
\&\f(CW\*(C`$i\->code\*(C'\fR method.
.Sp
If the option is set to false, the output buffer in the \f(CW\*(C`$i\->code\*(C'\fR
method will be truncated before uncompressed data is written to it.
.Sp
If the option is set to true, uncompressed data will be appended to the
output buffer by the \f(CW\*(C`$i\->code\*(C'\fR method.
.Sp
This option defaults to false.
.IP "\fB\-ConsumeInput\fR" 5
.IX Item "-ConsumeInput"
If set to true, this option will remove compressed data from the input
buffer of the \f(CW\*(C`$i\->code\*(C'\fR method as the uncompression progresses.
.Sp
This option can be useful when you are processing compressed data that is
embedded in another file/buffer. In this case the data that immediately
follows the compressed stream will be left in the input buffer.
.Sp
This option defaults to true.
.IP "\fB\-LimitOutput\fR" 5
.IX Item "-LimitOutput"
The \f(CW\*(C`LimitOutput\*(C'\fR option changes the behavior of the \f(CW\*(C`$i\->code\*(C'\fR
method so that the amount of memory used by the output buffer can be
limited.
.Sp
When \f(CW\*(C`LimitOutput\*(C'\fR is used the size of the output buffer used will either
be the value of the \f(CW\*(C`Bufsize\*(C'\fR option or the amount of memory already
allocated to \f(CW$output\fR, whichever is larger. Predicting the output size
available is tricky, so don't rely on getting an exact output buffer size.
.Sp
When \f(CW\*(C`LimitOutout\*(C'\fR is not specified \f(CW\*(C`$i\->code\*(C'\fR will use as much
memory as it takes to write all the uncompressed data it creates by
uncompressing the input buffer.
.Sp
If \f(CW\*(C`LimitOutput\*(C'\fR is enabled, the \f(CW\*(C`ConsumeInput\*(C'\fR option will also be
enabled.
.Sp
This option defaults to false.
.Sp
See \*(L"The LimitOutput option\*(R" for a discussion on why \f(CW\*(C`LimitOutput\*(C'\fR is
needed and how to use it.
.ie n .SS "($z, $status) = new Compress::Raw::Lzma::AloneDecoder [\s-1OPTS\s0] ;"
.el .SS "($z, \f(CW$status\fP) = new Compress::Raw::Lzma::AloneDecoder [\s-1OPTS\s0] ;"
.IX Subsection "($z, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS] ;"
Create an object that can uncompress an lzma_alone data stream.
.PP
If successful, it will return the initialised uncompression object, \f(CW$z\fR
and a \f(CW$status\fR of \f(CW\*(C`LZMA_OK\*(C'\fR in a list context. In scalar context it
returns the deflation object, \f(CW$z\fR, only.
.PP
If not successful, the returned uncompression object, \f(CW$z\fR, will be
\&\fIundef\fR and \f(CW$status\fR will hold the an \fIlzma\fR error code.
.PP
Below is a list of the valid options:
.IP "\fB\-MemLimit\fR" 5
.IX Item "-MemLimit"
The number of bytes to use when uncompressing.
.Sp
Default is unlimited.
.IP "\fB\-Bufsize\fR" 5
.IX Item "-Bufsize"
Sets the initial size for the output buffer used by the \f(CW\*(C`$i\->code\*(C'\fR
method. If the output buffer in this method has to be reallocated to
increase the size, it will grow in increments of \f(CW\*(C`Bufsize\*(C'\fR.
.Sp
Default is 16k.
.IP "\fB\-AppendOutput\fR" 5
.IX Item "-AppendOutput"
This option controls how data is written to the output buffer by the
\&\f(CW\*(C`$i\->code\*(C'\fR method.
.Sp
If the option is set to false, the output buffer in the \f(CW\*(C`$i\->code\*(C'\fR
method will be truncated before uncompressed data is written to it.
.Sp
If the option is set to true, uncompressed data will be appended to the
output buffer by the \f(CW\*(C`$i\->code\*(C'\fR method.
.Sp
This option defaults to false.
.IP "\fB\-ConsumeInput\fR" 5
.IX Item "-ConsumeInput"
If set to true, this option will remove compressed data from the input
buffer of the \f(CW\*(C`$i\->code\*(C'\fR method as the uncompression progresses.
.Sp
This option can be useful when you are processing compressed data that is
embedded in another file/buffer. In this case the data that immediately
follows the compressed stream will be left in the input buffer.
.Sp
This option defaults to true.
.IP "\fB\-LimitOutput\fR" 5
.IX Item "-LimitOutput"
The \f(CW\*(C`LimitOutput\*(C'\fR option changes the behavior of the \f(CW\*(C`$i\->code\*(C'\fR
method so that the amount of memory used by the output buffer can be
limited.
.Sp
When \f(CW\*(C`LimitOutput\*(C'\fR is used the size of the output buffer used will either
be the value of the \f(CW\*(C`Bufsize\*(C'\fR option or the amount of memory already
allocated to \f(CW$output\fR, whichever is larger. Predicting the output size
available is tricky, so don't rely on getting an exact output buffer size.
.Sp
When \f(CW\*(C`LimitOutout\*(C'\fR is not specified \f(CW\*(C`$i\->code\*(C'\fR will use as much
memory as it takes to write all the uncompressed data it creates by
uncompressing the input buffer.
.Sp
If \f(CW\*(C`LimitOutput\*(C'\fR is enabled, the \f(CW\*(C`ConsumeInput\*(C'\fR option will also be
enabled.
.Sp
This option defaults to false.
.Sp
See \*(L"The LimitOutput option\*(R" for a discussion on why \f(CW\*(C`LimitOutput\*(C'\fR is
needed and how to use it.
.ie n .SS "$status = $z\->code($input, $output);"
.el .SS "\f(CW$status\fP = \f(CW$z\fP\->code($input, \f(CW$output\fP);"
.IX Subsection "$status = $z->code($input, $output);"
Uncompresses \f(CW$input\fR and writes the uncompressed data to \f(CW$output\fR.
.PP
Returns \f(CW\*(C`LZMA_OK\*(C'\fR if the uncompression was successful, but the end of the
compressed data stream has not been reached. Returns \f(CW\*(C`LZMA_STREAM_END\*(C'\fR on
successful uncompression and the end of the compression stream has been
reached.
.PP
If \f(CW\*(C`consumeInput\*(C'\fR is enabled in the constructor for the lzma object,
\&\f(CW$input\fR will have all compressed data removed from it after
uncompression. On \f(CW\*(C`LZMA_OK\*(C'\fR return this will mean that \f(CW$input\fR will be an
empty string; when \f(CW\*(C`LZMA_STREAM_END\*(C'\fR \f(CW$input\fR will either be an empty
string or will contain whatever data immediately followed the compressed
data stream.
.PP
If \f(CW\*(C`appendOutput\*(C'\fR is enabled in the constructor for the lzma object,
the uncompressed data will be appended to \f(CW$output\fR. If not enabled,
\&\f(CW$output\fR will be truncated before the uncompressed data is written to it.
.SH "Filters"
.IX Header "Filters"
\&\s-1TODO\s0 \- more here
.PP
A number of the Lzma compression interfaces (namely
\&\f(CW\*(C`Compress::Raw::Lzma::StreamEncoder\*(C'\fR &
\&\f(CW\*(C`Compress::Raw::Lzma::AloneEncoder\*(C'\fR) and the raw lzma uncompression interface
make use of filters. These filters are used to change the behaviour of
compression (and raw uncompression).
.PP
All Lzma Filters are sub-classed from the \f(CW\*(C`Lzma::Filter\*(C'\fR base-class.
.SS "Lzma::Filter::Lzma"
.IX Subsection "Lzma::Filter::Lzma"
The \f(CW\*(C`Lzma::Filter::Lzma\*(C'\fR class is used to... \s-1TODO\s0 \- more here
.PP
There are two subclasses of \f(CW\*(C`Lzma::Filter::Lzma\*(C'\fR, namely
\&\f(CW\*(C`Lzma::Filter::Lzma1\*(C'\fR and \f(CW\*(C`Lzma::Filter::Lzma2\*(C'\fR.
.PP
The former is typically used with \f(CW\*(C`Compress::Raw::Lzma::AloneEncoder\*(C'\fR.
The latter with \f(CW\*(C`Compress::Raw::Lzma::StreamEncoder\*(C'\fR.
.PP
When using Lzma filters an \f(CW\*(C`Lzma::Filter::Lzma\*(C'\fR \fImust\fR be included and it
\&\fImust\fR be the last filter in the chain. There can only be one
\&\f(CW\*(C`Lzma::Filter::Lzma\*(C'\fR filter in any filter chain.
.PP
The \f(CW\*(C`Lzma::Filter::Lzma\*(C'\fR construction takes the following options.
.ie n .IP "DictSize => $value" 5
.el .IP "DictSize => \f(CW$value\fR" 5
.IX Item "DictSize => $value"
Dictionary size in bytes. This controls
how many bytes of the recently processed
uncompressed data is kept in memory. The size of the dictionary must be at
least \f(CW\*(C`LZMA_DICT_SIZE_MIN\*(C'\fR.
.Sp
Defaults to \f(CW\*(C`LZMA_DICT_SIZE_DEFAULT\*(C'\fR.
.ie n .IP "PresetDict => $dict" 5
.el .IP "PresetDict => \f(CW$dict\fR" 5
.IX Item "PresetDict => $dict"
Provide an initial dictionary. This value is used to initialize the \s-1LZ77\s0 history window.
.Sp
This feature only works correctly with raw encoding and decoding.
You may not be able to decode other formats that have been encoded with a preset dictionary.
.Sp
\&\f(CW$dict\fR should contain typical strings that occur in the files being compressed,
with the most probably strings near the end fo the preset dictionary.
.Sp
If \f(CW$dict\fR is larger than \f(CW\*(C`DictSize\*(C'\fR, only the last \f(CW\*(C`DictSize\*(C'\fR bytes are processed.
.ie n .IP "Lc => $value" 5
.el .IP "Lc => \f(CW$value\fR" 5
.IX Item "Lc => $value"
Number of literal context bits.
.Sp
How many of the highest bits of the previous uncompressed
eight-bit byte (also known as `literal') are taken into
account when predicting the bits of the next literal.
.Sp
\&\f(CW$value\fR must be a number between \f(CW\*(C`LZMA_LCLP_MIN\*(C'\fR and
\&\f(CW\*(C`LZMA_LCLP_MAX\*(C'\fR.
.Sp
Note the sum of the \f(CW\*(C`Lc\*(C'\fR and \f(CW\*(C`Lp\*(C'\fR options cannot exceed 4.
.Sp
Defaults to \f(CW\*(C`LZMA_LC_DEFAULT\*(C'\fR.
.ie n .IP "Lp => $value" 5
.el .IP "Lp => \f(CW$value\fR" 5
.IX Item "Lp => $value"
Number of literal position bits.
.Sp
How many of the lowest bits of the current position (number
of bytes from the beginning of the uncompressed data) in the
uncompressed data is taken into account when predicting the
bits of the next literal (a single eight-bit byte).
.Sp
Defaults to \f(CW\*(C`LZMA_LP_DEFAULT\*(C'\fR.
.ie n .IP "Pb => $value" 5
.el .IP "Pb => \f(CW$value\fR" 5
.IX Item "Pb => $value"
Number of position bits
.Sp
How many of the lowest bits of the current position in the
uncompressed data is taken into account when estimating
probabilities of matches. A match is a sequence of bytes for
which a matching sequence is found from the dictionary and
thus can be stored as distance-length pair.
.Sp
\&\f(CW$value\fR must be a number between \f(CW\*(C`LZMA_PB_MIN\*(C'\fR and
\&\f(CW\*(C`LZMA_PB_MAX\*(C'\fR.
.Sp
Defaults to \f(CW\*(C`LZMA_PB_DEFAULT\*(C'\fR.
.ie n .IP "Mode => $value" 5
.el .IP "Mode => \f(CW$value\fR" 5
.IX Item "Mode => $value"
The Compression Mode. Valid values are \f(CW\*(C`LZMA_MODE_FAST\*(C'\fR and
\&\f(CW\*(C`LZMA_MODE_NORMAL\*(C'\fR.
.Sp
Defaults to \f(CW\*(C`LZMA_MODE_NORMAL\*(C'\fR.
.ie n .IP "Nice => $value" 5
.el .IP "Nice => \f(CW$value\fR" 5
.IX Item "Nice => $value"
Nice length of a match
.Sp
Defaults to 64.
.ie n .IP "Mf => $value" 5
.el .IP "Mf => \f(CW$value\fR" 5
.IX Item "Mf => $value"
Defines which Match Finder to use. Valid values are \f(CW\*(C`LZMA_MF_HC3\*(C'\fR
\&\f(CW\*(C`LZMA_MF_HC4\*(C'\fR, \f(CW\*(C`LZMA_MF_BT2\*(C'\fR \f(CW\*(C`LZMA_MF_BT3\*(C'\fR and \f(CW\*(C`LZMA_MF_BT4\*(C'\fR.
.Sp
Defaults to \f(CW\*(C`LZMA_MF_BT4\*(C'\fR.
.ie n .IP "Depth => $value" 5
.el .IP "Depth => \f(CW$value\fR" 5
.IX Item "Depth => $value"
Maximum search depth in the match finder.
.Sp
Defaults to 0.
.SS "Lzma::Filter::BCJ"
.IX Subsection "Lzma::Filter::BCJ"
The sub-classes of \f(CW\*(C`Lzma::Filter::BCJ\*(C'\fR are the
Branch/Call/Jump conversion filters. These filters are used to rewrite
executable binary code for a number of processor architectures.
None of these classes take any options.
.IP "Lzma::Filter::X86" 5
.IX Item "Lzma::Filter::X86"
Filter for x86 binaries.
.IP "Lzma::Filter::PowerPC" 5
.IX Item "Lzma::Filter::PowerPC"
Filter for Big endian PowerPC binaries.
.IP "Lzma::Filter::IA64" 5
.IX Item "Lzma::Filter::IA64"
Filter for \s-1IA64\s0 (Itanium) binaries.
.IP "Lzma::Filter::ARM" 5
.IX Item "Lzma::Filter::ARM"
Filter for \s-1ARM\s0 binaries.
.IP "Lzma::Filter::ARMThumb" 5
.IX Item "Lzma::Filter::ARMThumb"
Filter for ARMThumb binaries.
.IP "Lzma::Filter::Sparc" 5
.IX Item "Lzma::Filter::Sparc"
Filter for Sparc binaries.
.SS "Lzma::Filter::Delta"
.IX Subsection "Lzma::Filter::Delta"
Usage is
.PP
.Vb 1
\&    Lzma::Filter::Delta [OPTS]
.Ve
.ie n .IP "Type => $type" 5
.el .IP "Type => \f(CW$type\fR" 5
.IX Item "Type => $type"
Defines the type of Delta calculation. The only available type (and
therefore the default) is
\&\f(CW\*(C`LZMA_DELTA_TYPE_BYTE\*(C'\fR,
.ie n .IP "Distance => $value" 5
.el .IP "Distance => \f(CW$value\fR" 5
.IX Item "Distance => $value"
Defines the Delta Distance. \f(CW$value\fR must be a number between
\&\f(CW\*(C`LZMA_DELTA_DIST_MIN\*(C'\fR and \f(CW\*(C`LZMA_DELTA_DIST_MAX\*(C'\fR.
.Sp
Default is \f(CW\*(C`LZMA_DELTA_DIST_MIN\*(C'\fR.
.SH "Misc"
.IX Header "Misc"
.ie n .SS "my $version = \fBCompress::Raw::Lzma::lzma_version_number()\fP;"
.el .SS "my \f(CW$version\fP = \fBCompress::Raw::Lzma::lzma_version_number()\fP;"
.IX Subsection "my $version = Compress::Raw::Lzma::lzma_version_number();"
Returns the version of the underlying lzma library this module is using at
run-time as a number.
.ie n .SS "my $version = \fBCompress::Raw::Lzma::lzma_version_string()\fP;"
.el .SS "my \f(CW$version\fP = \fBCompress::Raw::Lzma::lzma_version_string()\fP;"
.IX Subsection "my $version = Compress::Raw::Lzma::lzma_version_string();"
Returns the version of the underlying lzma library this module is using at
run-time as a string.
.ie n .SS "my $version = \fBCompress::Raw::Lzma::LZMA_VERSION()\fP;"
.el .SS "my \f(CW$version\fP = \fBCompress::Raw::Lzma::LZMA_VERSION()\fP;"
.IX Subsection "my $version = Compress::Raw::Lzma::LZMA_VERSION();"
Returns the version of the underlying lzma library this module was using at
compile-time as a number.
.ie n .SS "my $version = \fBCompress::Raw::Lzma::LZMA_VERSION_STRING()\fP;"
.el .SS "my \f(CW$version\fP = \fBCompress::Raw::Lzma::LZMA_VERSION_STRING()\fP;"
.IX Subsection "my $version = Compress::Raw::Lzma::LZMA_VERSION_STRING();"
Returns the version of the underlying lzma library this module was using at
compile-time as a string.
.SH "Constants"
.IX Header "Constants"
The following lzma constants are exported by this module
.PP
\&\s-1TODO\s0 \- more here
.SH "SUPPORT"
.IX Header "SUPPORT"
General feedback/questions/bug reports should be sent to
<https://github.com/pmqs/Compress\-Raw\-Lzma/issues> (preferred) or
<https://rt.cpan.org/Public/Dist/Display.html?Name=Compress\-Raw\-Lzma>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, IO::Compress::Deflate, IO::Uncompress::Inflate, IO::Compress::RawDeflate, IO::Uncompress::RawInflate, IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
.PP
IO::Compress::FAQ
.PP
File::GlobMapper, Archive::Zip,
Archive::Tar,
IO::Zlib
.SH "AUTHOR"
.IX Header "AUTHOR"
This module was written by Paul Marquess, \f(CW\*(C`pmqs@cpan.org\*(C'\fR.
.SH "MODIFICATION HISTORY"
.IX Header "MODIFICATION HISTORY"
See the Changes file.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2005\-2021 Paul Marquess. All rights reserved.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.