Compress::Raw::Lzma(3pm)

NAME
Compress::Raw::Lzma - Low-Level Perl Interface to lzma compression library

SYNOPSIS
    use Compress::Raw::Lzma ;

    # Encoders
    my ($lz, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS]
        or die "Cannot create lzma object: $status\n";

    my ($lz, $status) = new Compress::Raw::Lzma::AloneEncoder [OPTS]
        or die "Cannot create lzma object: $status\n";

    my ($lz, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS]
        or die "Cannot create lzma object: $status\n";

    my ($lz, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS]
        or die "Cannot create lzma object: $status\n";

    $status = $lz->code($input, $output);
    $status = $lz->flush($output);

    # Decoders
    my ($lz, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS]
        or die "Cannot create lzma object: $status\n";

    my ($lz, $status) = new Compress::Raw::Lzma::AutoDecoder [OPTS]
        or die "Cannot create lzma object: $status\n";

    my ($lz, $status) = new Compress::Raw::Lzma::StreamDecoder [OPTS]
        or die "Cannot create lzma object: $status\n";

    my ($lz, $status) = new Compress::Raw::Lzma::RawDecoder [OPTS]
        or die "Cannot create lzma object: $status\n";

    $status = $lz->code($input, $output);

    my $version = Compress::Raw::Lzma::lzma_version_number();
    my $version = Compress::Raw::Lzma::lzma_version_string();

DESCRIPTION
"Compress::Raw::Lzma" provides an interface to the in-memory compression/uncompression functions from the lzma compression library.

Although the primary purpose for the existence of "Compress::Raw::Lzma" is for use by the "IO::Compress::Lzma", "IO::Uncompress::UnLzma", "IO::Compress::Xz" and "IO::Uncompress::UnXz" modules, it can be used on its own for simple compression/uncompression tasks.

There are two functions, called "code" and "flush", 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 "code" and "flush" append to that buffer, enable the "AppendOutput" option when you create the compression/decompression object.

Compression
There are four compression interfaces available in this module.

Compress::Raw::Lzma::EasyEncoder
Compress::Raw::Lzma::AloneEncoder
Compress::Raw::Lzma::StreamEncoder
Compress::Raw::Lzma::RawEncoder

  ($z, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS];
Creates a new xz compression object.

If successful, it will return the initialised compression object, $z and a $status of "LZMA_OK" in a list context. In scalar context it returns the deflation object, $z, only.

If not successful, the returned compression object, $z, will be undef and $status will hold the an lzma error code.

Below is a list of the valid options:

Preset => $preset
    Used to choose the compression preset.

    Valid values are 0-9 and "LZMA_PRESET_DEFAULT".

    0 is the fastest compression with the lowest memory usage and the lowest compression.

    9 is the slowest compression with the highest memory usage but with the best compression.

    Defaults to "LZMA_PRESET_DEFAULT".

Extreme => 0|1
    Makes the compression a lot slower, but a small compression gain.

    Defaults to 0.

Check => $check
    Used to specify the integrity check used in the xz data stream. Valid values are "LZMA_CHECK_NONE", "LZMA_CHECK_CRC32", "LZMA_CHECK_CRC64", "LZMA_CHECK_SHA256".

    Defaults to "LZMA_CHECK_CRC32".

AppendOutput => 0|1
    Controls whether the compressed data is appended to the output buffer in the "code" and "flush" methods.

    Defaults to 0. (Note in versions of this module prior to 2.072 the default value was incorrectly documented as 1).

BufSize => $number
    Sets the initial size for the output buffer used by the "$d->code" method. If the buffer has to be reallocated to increase the size, it will grow in increments of "Bufsize".

    Defaults to 16k.

  ($z, $status) = new Compress::Raw::Lzma::AloneEncoder [OPTS];
Creates a legacy lzma compression object. This format is also know as lzma_alone.

If successful, it will return the initialised compression object, $z and a $status of "LZMA_OK" in a list context. In scalar context it returns the deflation object, $z, only.

If not successful, the returned compression object, $z, will be undef and $status will hold the an lzma error code.

Below is a list of the valid options:

Filter => $filter
    The $filter option must be an object of type "Lzma::Filter::Lzma1". See "Lzma::Filter::Lzma" in Compress::Raw::Lzma for a definition of "Lzma::Filter::Lzma1".

    If this option is not present an "Lzma::Filter::Lzma1" object with default values will be used.

AppendOutput => 0|1
    Controls whether the compressed data is appended to the output buffer in the "code" and "flush" methods.

    Defaults to 0. (Note in versions of this module prior to 2.072 the default value was incorrectly documented as 1).

BufSize => $number
    Sets the initial size for the output buffer used by the "$d->code" method. If the buffer has to be reallocated to increase the size, it will grow in increments of "Bufsize".

    Defaults to 16k.

  ($z, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS];
Creates a xz compression object.

If successful, it will return the initialised compression object, $z and a $status of "LZMA_OK" in a list context. In scalar context it returns the deflation object, $z, only.

If not successful, the returned compression object, $z, will be undef and $status will hold the an lzma error code.

Below is a list of the valid options:

Filter => $filter
Filter => [$filter1, $filter2,...]
    This option is used to change the bahaviour of the StreamEncoder by applying between one and "LZMA_FILTERS_MAX" filters to the data stream during compression. See "Filters" for more details on the available filters.

    If this option is present it must either contain a single "Lzma::Filter::Lzma" filter object or an array reference containing between one and "LZMA_FILTERS_MAX" filter objects.

    If this option is not present an "Lzma::Filter::Lzma2" object with default values will be used.

Check => $check
    Used to specify the integrity check used in the xz data stream. Valid values are "LZMA_CHECK_NONE", "LZMA_CHECK_CRC32", "LZMA_CHECK_CRC64", "LZMA_CHECK_SHA256".

    Defaults to "LZMA_CHECK_CRC32".

AppendOutput => 0|1
    Controls whether the compressed data is appended to the output buffer in the "code" and "flush" methods.

    Defaults to 0. (Note in versions of this module prior to 2.072 the default value was incorrectly documented as 1).

BufSize => $number
    Sets the initial size for the output buffer used by the "$d->code" method. If the buffer has to be reallocated to increase the size, it will grow in increments of "Bufsize".

    Defaults to 16k.

  ($z, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS];
Low level access to lzma.

If successful, it will return the initialised compression object, $z and a $status of "LZMA_OK" in a list context. In scalar context it returns the deflation object, $z, only.

If not successful, the returned compression object, $z, will be undef and $status will hold the an lzma error code.

Below is a list of the valid options:

Filter => $filter
Filter => [$filter1, $filter2,...]
    This option is used to change the bahaviour of the RawEncoder by applying between one and "LZMA_FILTERS_MAX" filters to the data stream during compression. See "Filters" for more details on the available filters.

    If this option is present it must either contain a single "Lzma::Filter::Lzma" filter object or an array reference containing between one and "LZMA_FILTERS_MAX" filter objects.

    If this option is not present an "Lzma::Filter::Lzma2" object with default values will be used.

AppendOutput => 0|1
    Controls whether the compressed data is appended to the output buffer in the "code" and "flush" methods.

    Defaults to 0. (Note in versions of this module prior to 2.072 the default value was incorrectly documented as 1).

BufSize => $number
    Sets the initial size for the output buffer used by the "$d->code" method. If the buffer has to be reallocated to increase the size, it will grow in increments of "Bufsize".

    Defaults to 16k.

ForZip => 1/0
    This boolean option is used to enable prefixing the compressed data stream with an encoded copy of the filter properties.

    Defaults to 0.

  $status = $lz->code($input, $output)
Reads the contents of $input, compresses it and writes the compressed data to $output.

Returns "LZMA_OK" on success and an "lzma" error code on failure.

If "appendOutput" is enabled in the constructor for the lzma object, the compressed data will be appended to $output. If not enabled, $output will be truncated before the compressed data is written to it.

  $status = $lz->flush($output, LZMA_FINISH);
Flushes any pending compressed data to $output. By default it terminates the compressed data stream.

Returns "LZMA_STREAM_END" on success and an "lzma" error code on failure.

Compression examples

  Simple compression with EasyEncoder
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    my ($lz, $status) = Compress::Raw::Lzma::EasyEncoder->new(
        Preset => 6,
        Extreme => 0,
    );
    die "Cannot create encoder: $status\n" unless $lz;

    my $input = "This is the data to compress " x 100;
    my $compressed = '';

    $status = $lz->code($input, $compressed);
    die "Compression failed: $status\n" unless $status == LZMA_OK;

    $status = $lz->flush($compressed);
    die "Flush failed: $status\n" unless $status == LZMA_STREAM_END;

    print "Original size: ", length($input), "\n";
    print "Compressed size: ", length($compressed), "\n";

  Streaming compression with AppendOutput
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    my ($lz, $status) = Compress::Raw::Lzma::EasyEncoder->new(
        AppendOutput => 1,
        Preset => LZMA_PRESET_DEFAULT,
    );
    die "Cannot create encoder: $status\n" unless $lz;

    my $compressed = '';

    # Compress data in chunks
    for my $chunk ("Hello ", "world", "!") {
        $status = $lz->code($chunk, $compressed);
        die "Compression failed\n" unless $status == LZMA_OK;
    }

    # Finish compression
    $status = $lz->flush($compressed);
    die "Flush failed\n" unless $status == LZMA_STREAM_END;

    print "Compressed: ", length($compressed), " bytes\n";

  Using custom filters with StreamEncoder
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    # Create a custom LZMA2 filter
    my $filter = Lzma::Filter::Lzma2(
        DictSize => 1024 * 1024 * 8,  # 8MB dictionary
        Lc => 3,
        Lp => 0,
        Pb => 2,
        Mode => LZMA_MODE_NORMAL,
        Nice => 128,
        Mf => LZMA_MF_BT4,
        Depth => 512,
    );

    my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
        Filter => $filter,
        Check => LZMA_CHECK_SHA256,
    );
    die "Cannot create encoder: $status\n" unless $lz;

    my $input = "Custom filter example data";
    my $compressed = '';

    $status = $lz->code($input, $compressed);
    $status = $lz->flush(compressed);

  Using multiple filters (BCJ + LZMA2)
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    # Combine BCJ filter for x86 binaries with LZMA2 compression
    my @filters = (
        Lzma::Filter::X86(),      # BCJ filter for x86 code
        Lzma::Filter::Lzma2(),    # LZMA2 compression
    );

    my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
        Filter => \@filters,
        Check => LZMA_CHECK_CRC64,
    );
    die "Cannot create encoder: $status\n" unless $lz;

    # ... compress binary data ...

Uncompression
There are four uncompression interfaces available in this module.

Compress::Raw::Lzma::AutoDecoder
Compress::Raw::Lzma::AloneDecoder
Compress::Raw::Lzma::StreamDecoder
Compress::Raw::Lzma::RawDecoder

  ($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.

If successful, it will return the initialised uncompression object, $z and a $status of "LZMA_OK" in a list context. In scalar context it returns the deflation object, $z, only.

If not successful, the returned uncompression object, $z, will be undef and $status will hold the an lzma error code.

Below is a list of the valid options:

-MemLimit
    The number of bytes to use when uncompressing.

    Default is unlimited.

-Bufsize
    Sets the initial size for the output buffer used by the "$i->code" method. If the output buffer in this method has to be reallocated to increase the size, it will grow in increments of "Bufsize".

    Default is 16k.

-AppendOutput
    This option controls how data is written to the output buffer by the "$i->code" method.

    If the option is set to false, the output buffer in the "$i->code" method will be truncated before uncompressed data is written to it.

    If the option is set to true, uncompressed data will be appended to the output buffer by the "$i->code" method.

    This option defaults to false.

-ConsumeInput
    If set to true, this option will remove compressed data from the input buffer of the "$i->code" method as the uncompression progresses.

    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.

    This option defaults to true.

-LimitOutput
    The "LimitOutput" option changes the behavior of the "$i->code" method so that the amount of memory used by the output buffer can be limited.

    When "LimitOutput" is used the size of the output buffer used will either be the value of the "Bufsize" option or the amount of memory already allocated to $output, whichever is larger. Predicting the output size available is tricky, so don't rely on getting an exact output buffer size.

    When "LimitOutout" is not specified "$i->code" will use as much memory as it takes to write all the uncompressed data it creates by uncompressing the input buffer.

    If "LimitOutput" is enabled, the "ConsumeInput" option will also be enabled.

    This option defaults to false.

  ($z, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS] ;
Create an object that can uncompress an lzma_alone data stream.

If successful, it will return the initialised uncompression object, $z and a $status of "LZMA_OK" in a list context. In scalar context it returns the deflation object, $z, only.

If not successful, the returned uncompression object, $z, will be undef and $status will hold the an lzma error code.

Below is a list of the valid options:

-MemLimit
    The number of bytes to use when uncompressing.

    Default is unlimited.

-Bufsize
    Sets the initial size for the output buffer used by the "$i->code" method. If the output buffer in this method has to be reallocated to increase the size, it will grow in increments of "Bufsize".

    Default is 16k.

-AppendOutput
    This option controls how data is written to the output buffer by the "$i->code" method.

    If the option is set to false, the output buffer in the "$i->code" method will be truncated before uncompressed data is written to it.

    If the option is set to true, uncompressed data will be appended to the output buffer by the "$i->code" method.

    This option defaults to false.

-ConsumeInput
    If set to true, this option will remove compressed data from the input buffer of the "$i->code" method as the uncompression progresses.

    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.

    This option defaults to true.

-LimitOutput
    The "LimitOutput" option changes the behavior of the "$i->code" method so that the amount of memory used by the output buffer can be limited.

    When "LimitOutput" is used the size of the output buffer used will either be the value of the "Bufsize" option or the amount of memory already allocated to $output, whichever is larger. Predicting the output size available is tricky, so don't rely on getting an exact output buffer size.

    When "LimitOutout" is not specified "$i->code" will use as much memory as it takes to write all the uncompressed data it creates by uncompressing the input buffer.

    If "LimitOutput" is enabled, the "ConsumeInput" option will also be enabled.

    This option defaults to false.

  $status = $z->code($input, $output);
Uncompresses $input and writes the uncompressed data to $output.

Returns "LZMA_OK" if the uncompression was successful, but the end of the compressed data stream has not been reached. Returns "LZMA_STREAM_END" on successful uncompression and the end of the compression stream has been reached.

If "consumeInput" is enabled in the constructor for the lzma object, $input will have all compressed data removed from it after uncompression. On "LZMA_OK" return this will mean that $input will be an empty string; when "LZMA_STREAM_END" $input will either be an empty string or will contain whatever data immediately followed the compressed data stream.

If "appendOutput" is enabled in the constructor for the lzma object, the uncompressed data will be appended to $output. If not enabled, $output will be truncated before the uncompressed data is written to it.

Uncompression examples

  Simple uncompression with AutoDecoder
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    # $compressed contains xz/lzma compressed data
    my $compressed = ...;

    my ($lz, $status) = Compress::Raw::Lzma::AutoDecoder->new(
        AppendOutput => 1,
        ConsumeInput => 1,
    );
    die "Cannot create decoder: $status\n" unless $lz;

    my $uncompressed = '';
    $status = $lz->code($compressed, $uncompressed);
    die "Decompression failed: $status\n"
        unless $status == LZMA_STREAM_END;

    print "Uncompressed size: ", length($uncompressed), "\n";

  Streaming uncompression with LimitOutput
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    my ($lz, $status) = Compress::Raw::Lzma::AutoDecoder->new(
        LimitOutput => 1,
        ConsumeInput => 1,
        Bufsize => 4096,
    );
    die "Cannot create decoder: $status\n" unless $lz;

    # Process compressed data in chunks
    my $compressed = ...;  # your compressed data
    my $uncompressed = '';

    while (length($compressed) > 0) {
        my $output = '';
        $status = $lz->code($compressed, $output);

        $uncompressed .= $output;

        last if $status == LZMA_STREAM_END;
        die "Decompression error: $status\n" unless $status == LZMA_OK;
    }

    print "Total uncompressed: ", length($uncompressed), " bytes\n";

  Uncompressing specific format with AloneDecoder
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    # For legacy .lzma format (lzma_alone)
    my ($lz, $status) = Compress::Raw::Lzma::AloneDecoder->new(
        MemLimit => 128 * 1024 * 1024,  # 128 MB limit
        AppendOutput => 0,
    );
    die "Cannot create decoder: $status\n" unless $lz;

    my $compressed = ...;  # .lzma format data
    my $output = '';

    $status = $lz->code($compressed, $output);
    die "Decompression failed: $status\n"
        unless $status == LZMA_STREAM_END;

Filters
A number of the Lzma compression interfaces (namely "Compress::Raw::Lzma::StreamEncoder" & "Compress::Raw::Lzma::AloneEncoder") and the raw lzma uncompression interface make use of filters. These filters are used to change the behaviour of compression (and raw uncompression).

All Lzma Filters are sub-classed from the "Lzma::Filter" base-class.

  Lzma::Filter::Lzma
The "Lzma::Filter::Lzma" class is the primary compression filter for LZMA algorithms. It provides fine-grained control over compression parameters.

There are two subclasses of "Lzma::Filter::Lzma", namely "Lzma::Filter::Lzma1" and "Lzma::Filter::Lzma2".

The former is typically used with "Compress::Raw::Lzma::AloneEncoder". The latter with "Compress::Raw::Lzma::StreamEncoder".

When using Lzma filters an "Lzma::Filter::Lzma" must be included and it must be the last filter in the chain. There can only be one "Lzma::Filter::Lzma" filter in any filter chain.

The "Lzma::Filter::Lzma" construction takes the following options.

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 "LZMA_DICT_SIZE_MIN".

    Defaults to "LZMA_DICT_SIZE_DEFAULT".

PresetDict => $dict
    Provide an initial dictionary. This value is used to initialize the LZ77 history window.

    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.

    $dict should contain typical strings that occur in the files being compressed, with the most probably strings near the end fo the preset dictionary.

    If $dict is larger than "DictSize", only the last "DictSize" bytes are processed.

Lc => $value
    Number of literal context bits.

    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.

    $value must be a number between "LZMA_LCLP_MIN" and "LZMA_LCLP_MAX".

    Note the sum of the "Lc" and "Lp" options cannot exceed 4.

    Defaults to "LZMA_LC_DEFAULT".

Lp => $value
    Number of literal position bits.

    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).

    Defaults to "LZMA_LP_DEFAULT".

Pb => $value
    Number of position bits

    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.

    $value must be a number between "LZMA_PB_MIN" and "LZMA_PB_MAX".

    Defaults to "LZMA_PB_DEFAULT".

Mode => $value
    The Compression Mode. Valid values are "LZMA_MODE_FAST" and "LZMA_MODE_NORMAL".

    Defaults to "LZMA_MODE_NORMAL".

Nice => $value
    Nice length of a match

    Defaults to 64.

Mf => $value
    Defines which Match Finder to use. Valid values are "LZMA_MF_HC3" "LZMA_MF_HC4", "LZMA_MF_BT2" "LZMA_MF_BT3" and "LZMA_MF_BT4".

    Defaults to "LZMA_MF_BT4".

Depth => $value
    Maximum search depth in the match finder.

    Defaults to 0.

  Lzma::Filter::BCJ
The sub-classes of "Lzma::Filter::BCJ" 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.

Lzma::Filter::X86
    Filter for x86 binaries.

Lzma::Filter::PowerPC
    Filter for Big endian PowerPC binaries.

Lzma::Filter::IA64
    Filter for IA64 (Itanium) binaries.

Lzma::Filter::ARM
    Filter for ARM binaries.

Lzma::Filter::ARMThumb
    Filter for ARMThumb binaries.

Lzma::Filter::Sparc
    Filter for Sparc binaries.

  Lzma::Filter::Delta
Usage is

    Lzma::Filter::Delta [OPTS]

Type => $type
    Defines the type of Delta calculation. The only available type (and therefore the default) is "LZMA_DELTA_TYPE_BYTE",

Distance => $value
    Defines the Delta Distance. $value must be a number between "LZMA_DELTA_DIST_MIN" and "LZMA_DELTA_DIST_MAX".

    Default is "LZMA_DELTA_DIST_MIN".

Filter examples

  Using LZMA2 filter with custom dictionary size
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    # Create LZMA2 filter with large dictionary for better compression
    my $filter = Lzma::Filter::Lzma2(
        DictSize => 16 * 1024 * 1024,  # 16 MB dictionary
        Lc => 3,
        Lp => 0,
        Pb => 2,
    );

    my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
        Filter => $filter,
        Check => LZMA_CHECK_CRC64,
    );
    die "Cannot create encoder: $status\n" unless $lz;

    my $input = "Data to compress...";
    my $output = '';

    $lz->code($input, $output);
    $lz->flush($output);

  Using LZMA1 filter for legacy .lzma format
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    # LZMA1 is used for the legacy .lzma format
    my $filter = Lzma::Filter::Lzma1(
        DictSize => 8 * 1024 * 1024,
        Mode => LZMA_MODE_NORMAL,
        Mf => LZMA_MF_BT4,
        Nice => 273,
    );

    my ($lz, $status) = Compress::Raw::Lzma::AloneEncoder->new(
        Filter => $filter,
    );
    die "Cannot create encoder: $status\n" unless $lz;

  Using preset-based LZMA2 filter
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    # Use preset instead of manually configuring parameters
    # Preset 9 = maximum compression
    my $filter = Lzma::Filter::Lzma2::Preset(9 | LZMA_PRESET_EXTREME);

    my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
        Filter => $filter,
    );
    die "Cannot create encoder: $status\n" unless $lz;

  Combining Delta filter with LZMA2
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    # Delta filter is useful for data with small changes between bytes
    # (e.g., uncompressed images, audio samples)
    my @filters = (
        Lzma::Filter::Delta(
            Type => LZMA_DELTA_TYPE_BYTE,
            Distance => 1,
        ),
        Lzma::Filter::Lzma2(
            DictSize => 8 * 1024 * 1024,
        ),
    );

    my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
        Filter => \@filters,
        Check => LZMA_CHECK_CRC32,
    );
    die "Cannot create encoder: $status\n" unless $lz;

    # Compress image or audio data
    my $raw_data = ...;
    my $compressed = '';

    $lz->code($raw_data, $compressed);
    $lz->flush($compressed);

  Using BCJ filter for x86 executable compression
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    # BCJ (Branch/Call/Jump) filter optimizes compression of x86 binaries
    my @filters = (
        Lzma::Filter::X86(Offset => 0),
        Lzma::Filter::Lzma2(),
    );

    my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
        Filter => \@filters,
        Check => LZMA_CHECK_SHA256,
    );
    die "Cannot create encoder: $status\n" unless $lz;

    # Read and compress x86 binary
    open my $fh, '<', 'program.exe' or die $!;
    binmode $fh;
    my $binary = do { local $/; <$fh> };
    close $fh;

    my $compressed = '';
    $lz->code($binary, $compressed);
    $lz->flush($compressed);

    print "Original: ", length($binary), " bytes\n";
    print "Compressed: ", length($compressed), " bytes\n";

  Using ARM filter for ARM binaries
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    # For ARM executables
    my @filters = (
        Lzma::Filter::ARM(),
        Lzma::Filter::Lzma2(
            DictSize => 4 * 1024 * 1024,
        ),
    );

    my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
        Filter => \@filters,
    );
    die "Cannot create encoder: $status\n" unless $lz;

  Maximum compression with multiple filters
    use strict;
    use warnings;

    use Compress::Raw::Lzma;

    # Combine filters for maximum compression
    my @filters = (
        Lzma::Filter::Delta(Distance => 1),
        Lzma::Filter::Lzma2(
            DictSize => 64 * 1024 * 1024,  # 64 MB
            Lc => 4,
            Lp => 0,
            Pb => 2,
            Mode => LZMA_MODE_NORMAL,
            Nice => 273,
            Mf => LZMA_MF_BT4,
            Depth => 1024,
        ),
    );

    my ($lz, $status) = Compress::Raw::Lzma::StreamEncoder->new(
        Filter => \@filters,
        Check => LZMA_CHECK_SHA256,
    );
    die "Cannot create encoder: $status\n" unless $lz;

Misc

  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.

  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.

  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.

  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.

Constants
The following lzma constants are exported by this module.

  Return/Status Codes

LZMA_OK
    Operation completed successfully.

LZMA_STREAM_END
    End of stream was reached. The complete compressed data has been decoded/encoded.

LZMA_NO_CHECK
    Input stream has no integrity check.

LZMA_UNSUPPORTED_CHECK
    Cannot calculate the integrity check (not supported by this build).

LZMA_GET_CHECK
    Integrity check type is now available.

LZMA_MEM_ERROR
    Cannot allocate memory.

LZMA_MEMLIMIT_ERROR
    Memory usage limit was reached.

LZMA_FORMAT_ERROR
    File format not recognized.

LZMA_OPTIONS_ERROR
    Invalid or unsupported options.

LZMA_DATA_ERROR
    Data is corrupt.

LZMA_BUF_ERROR
    No progress is possible (stream is truncated or corrupt).

LZMA_PROG_ERROR
    Programming error (should never happen in correct usage).

  Flush Modes

LZMA_RUN
    Continue coding. Used for normal operation.

LZMA_SYNC_FLUSH
    Make all the input available at output. Not commonly used with LZMA.

LZMA_FULL_FLUSH
    Finish encoding of the current Block. Not commonly used.

LZMA_FINISH
    Finish the coding operation. All input must have been given to the encoder.

  Integrity Check Types

LZMA_CHECK_NONE
    No Check is calculated.

LZMA_CHECK_CRC32
    CRC32 using the polynomial from IEEE-802.3.

LZMA_CHECK_CRC64
    CRC64 using the polynomial from ECMA-182.

LZMA_CHECK_SHA256
    SHA-256 checksum.

LZMA_CHECK_ID_MAX
    Maximum valid Check ID.

LZMA_CHECK_SIZE_MAX
    Maximum size of any Check algorithm.

  Preset and Compression Level

LZMA_PRESET_DEFAULT
    Default compression preset (currently 6).

LZMA_PRESET_LEVEL_MASK
    Mask for preset level (0-9).

LZMA_PRESET_EXTREME
    Extreme compression preset flag. Can be combined with preset level using bitwise OR (e.g., "6 | LZMA_PRESET_EXTREME").

  Stream Flags

LZMA_TELL_NO_CHECK
    Accept streams with no integrity check.

LZMA_TELL_UNSUPPORTED_CHECK
    Accept streams with unsupported integrity check.

LZMA_TELL_ANY_CHECK
    Accept any type of integrity check.

LZMA_CONCATENATED
    Enable support for concatenated streams.

  Match Finder Types

LZMA_MF_HC3
    Hash Chain with 3 byte hashing.

LZMA_MF_HC4
    Hash Chain with 4 byte hashing.

LZMA_MF_BT2
    Binary Tree with 2 byte hashing.

LZMA_MF_BT3
    Binary Tree with 3 byte hashing.

LZMA_MF_BT4
    Binary Tree with 4 byte hashing (default and recommended).

  Compression Mode

LZMA_MODE_FAST
    Fast compression mode.

LZMA_MODE_NORMAL
    Normal compression mode (default).

  Dictionary and Parameter Limits

LZMA_DICT_SIZE_MIN
    Minimum dictionary size (4 KiB).

LZMA_DICT_SIZE_DEFAULT
    Default dictionary size.

LZMA_LCLP_MIN
    Minimum for lc and lp (0).

LZMA_LCLP_MAX
    Maximum for lc and lp (4).

LZMA_LC_DEFAULT
    Default number of literal context bits (3).

LZMA_LP_DEFAULT
    Default number of literal position bits (0).

LZMA_PB_MIN
    Minimum number of position bits (0).

LZMA_PB_MAX
    Maximum number of position bits (4).

LZMA_PB_DEFAULT
    Default number of position bits (2).

  BCJ (Branch/Call/Jump) Filters
Architecture-specific filters for executable code:

LZMA_FILTER_X86
    Filter for x86 (32-bit and 64-bit) binaries.

LZMA_FILTER_POWERPC
    Filter for Big endian PowerPC binaries.

LZMA_FILTER_IA64
    Filter for IA-64 (Itanium) binaries.

LZMA_FILTER_ARM
    Filter for ARM binaries.

LZMA_FILTER_ARMTHUMB
    Filter for ARM-Thumb binaries.

LZMA_FILTER_SPARC
    Filter for SPARC binaries.

  Delta Filter

LZMA_FILTER_DELTA
    Delta filter ID.

LZMA_DELTA_TYPE_BYTE
    Byte-wise delta calculation.

LZMA_DELTA_DIST_MIN
    Minimum delta distance (1).

LZMA_DELTA_DIST_MAX
    Maximum delta distance (256).

  LZMA Filters

LZMA_FILTER_LZMA2
    LZMA2 filter (used in .xz format).

LZMA_FILTERS_MAX
    Maximum number of filters in a chain (4).

  Stream Header and Block

LZMA_STREAM_HEADER_SIZE
    Size of Stream Header (12 bytes).

LZMA_BLOCK_HEADER_SIZE_MIN
    Minimum size of Block Header.

LZMA_BLOCK_HEADER_SIZE_MAX
    Maximum size of Block Header.

LZMA_BACKWARD_SIZE_MIN
    Minimum Backward Size.

  Version Information

LZMA_VERSION
    Encoded version number of liblzma.

LZMA_VERSION_MAJOR
    Major version number.

LZMA_VERSION_MINOR
    Minor version number.

LZMA_VERSION_PATCH
    Patch version number.

LZMA_VERSION_STABILITY
    Stability indicator.

LZMA_VERSION_STABILITY_STRING
    Stability as string (e.g., "alpha", "beta", "stable").

LZMA_VERSION_STRING
    Full version string.

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>.

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

IO::Compress::FAQ

File::GlobMapper, Archive::Zip, Archive::Tar, IO::Zlib

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

MODIFICATION HISTORY
See the Changes file.

COPYRIGHT AND LICENSE
Copyright (c) 2005-2026 Paul Marquess. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.