LZ4 API Guide  1.00.01.00
Data Structures | Macros | Typedefs | Enumerations | Functions
LZ4

The following is a reference of all LZ4 compression and decompression API's available for the application to use. More...

Data Structures

struct  LZ4_compressParams
 Compression parameters for a LZ4 frame. More...
 
struct  LZ4_compressBlockParams
 Compression parameters for a single LZ4 block. More...
 
struct  LZ4_decompressParams
 Decompression parameters for a LZ4 frame. More...
 
struct  LZ4_decompressBlockParams
 Decompression parameters for a single LZ4 block. More...
 
struct  LZ4_streamDecompressBlockState
 Decompression state for a streaming LZ4 block. More...
 
struct  LZ4_streamDecompressBlockParams
 Decompression parameters for a streaming LZ4 block. More...
 

Macros

#define LZ4_COMPRESS_MAX_SIZE(n)   ((size_t)((n * 101) / 100) + 27)
 Maximum size of a compressed file, one percent plus 27 bytes larger than uncompressed data. More...
 
#define LZ4_MAGIC_NUMBER   0x184d2204
 
#define LZ4_MAX_BLOCK_SIZE   0x00100000
 
#define LZ4_FLG_VERSION   0x40
 
#define LZ4_FLG_BLOCK_INDEP   0x20
 
#define LZ4_FLG_BLOCK_CHECKSUM   0x10
 
#define LZ4_FLG_CONTENT_SIZE   0x08
 
#define LZ4_FLG_CONTENT_CHECKSUM   0x04
 
#define LZ4_BD_BYTE   0x70
 
#define LZ4_MIN_MATCH   4
 
#define LZ4_LAST_MATCH_DIST   12
 
#define LZ4_LAST_LITERAL_LENGTH   5
 
#define LZ4_TOKEN_LITERAL_MASK   0xf0
 
#define LZ4_TOKEN_MATCH_MASK   0x0f
 
#define LZ4_HASH_VALUE   0x9E3779B1
 

Typedefs

typedef struct LZ4_compressParams LZ4_compressParams
 Compression parameters for a LZ4 frame. More...
 
typedef struct LZ4_compressBlockParams LZ4_compressBlockParams
 Compression parameters for a single LZ4 block. More...
 
typedef struct LZ4_decompressParams LZ4_decompressParams
 Decompression parameters for a LZ4 frame. More...
 
typedef struct LZ4_decompressBlockParams LZ4_decompressBlockParams
 Decompression parameters for a single LZ4 block. More...
 
typedef struct LZ4_streamDecompressBlockState LZ4_streamDecompressBlockState
 Decompression state for a streaming LZ4 block. More...
 
typedef struct LZ4_streamDecompressBlockParams LZ4_streamDecompressBlockParams
 Decompression parameters for a streaming LZ4 block. More...
 

Enumerations

enum  LZ4_status {
  LZ4_SUCCESS, LZ4_PARTIAL_SUCCESS, LZ4_NO_CONTENT_SIZE, LZ4_FRAMING_ERROR,
  LZ4_BLOCK_CHECKSUM_ERROR, LZ4_CONTENT_CHECKSUM_ERROR
}
 LZ4 status return types. More...
 
enum  LZ4_streamState {
  LZ4_BLOCK_SIZE, LZ4_TOKEN, LZ4_LITERAL_LENGTH, LZ4_LITERAL,
  LZ4_MATCH_LENGTH, LZ4_MATCH_OFFSET_LOW, LZ4_MATCH_OFFSET_HIGH
}
 LZ4 streaming API state. More...
 

Functions

uint32_t LZ4_compress (const LZ4_compressParams *params, LZ4_status *status)
 Compress a block of data to a LZ4 frame. More...
 
uint32_t LZ4_compressBlock (const LZ4_compressBlockParams *params, LZ4_status *status)
 Compress a block of data to a single LZ4 block without framing. More...
 
uint32_t LZ4_decompress (const LZ4_decompressParams *params, LZ4_status *status)
 Decompress a LZ4 frame to a block of data. More...
 
uint32_t LZ4_decompressBlock (const LZ4_decompressBlockParams *params, LZ4_status *status)
 Decompress a single LZ4 block without framing to a block of data. More...
 
uint32_t LZ4_getContentSize (const uint8_t *src, LZ4_status *status)
 Get the content size of a compressed LZ4 frame. More...
 
void LZ4_streamDecompressBlockInit (const LZ4_streamDecompressBlockParams *params, LZ4_streamDecompressBlockState *state, LZ4_status *status)
 Initialize LZ4 stream decompression. More...
 
uint32_t LZ4_streamDecompressBlock (LZ4_streamDecompressBlockState *state, const void *data, uint16_t length, LZ4_status *status)
 Decompress a single LZ4 block as a stream of data. More...
 

Detailed Description

The following is a reference of all LZ4 compression and decompression API's available for the application to use.

The LZ4 API set includes both compression and decompression APIs that can be called directly from the main application.

Macro Definition Documentation

§ LZ4_COMPRESS_MAX_SIZE

#define LZ4_COMPRESS_MAX_SIZE (   n)    ((size_t)((n * 101) / 100) + 27)

Maximum size of a compressed file, one percent plus 27 bytes larger than uncompressed data.

§ LZ4_MAGIC_NUMBER

#define LZ4_MAGIC_NUMBER   0x184d2204

§ LZ4_MAX_BLOCK_SIZE

#define LZ4_MAX_BLOCK_SIZE   0x00100000

§ LZ4_FLG_VERSION

#define LZ4_FLG_VERSION   0x40

§ LZ4_FLG_BLOCK_INDEP

#define LZ4_FLG_BLOCK_INDEP   0x20

§ LZ4_FLG_BLOCK_CHECKSUM

#define LZ4_FLG_BLOCK_CHECKSUM   0x10

§ LZ4_FLG_CONTENT_SIZE

#define LZ4_FLG_CONTENT_SIZE   0x08

§ LZ4_FLG_CONTENT_CHECKSUM

#define LZ4_FLG_CONTENT_CHECKSUM   0x04

§ LZ4_BD_BYTE

#define LZ4_BD_BYTE   0x70

§ LZ4_MIN_MATCH

#define LZ4_MIN_MATCH   4

§ LZ4_LAST_MATCH_DIST

#define LZ4_LAST_MATCH_DIST   12

Referenced by LZ4_compressBlock().

§ LZ4_LAST_LITERAL_LENGTH

#define LZ4_LAST_LITERAL_LENGTH   5

§ LZ4_TOKEN_LITERAL_MASK

#define LZ4_TOKEN_LITERAL_MASK   0xf0

§ LZ4_TOKEN_MATCH_MASK

#define LZ4_TOKEN_MATCH_MASK   0x0f

§ LZ4_HASH_VALUE

#define LZ4_HASH_VALUE   0x9E3779B1

Typedef Documentation

§ LZ4_compressParams

Compression parameters for a LZ4 frame.

§ LZ4_compressBlockParams

Compression parameters for a single LZ4 block.

§ LZ4_decompressParams

Decompression parameters for a LZ4 frame.

§ LZ4_decompressBlockParams

Decompression parameters for a single LZ4 block.

§ LZ4_streamDecompressBlockState

Decompression state for a streaming LZ4 block.

§ LZ4_streamDecompressBlockParams

Decompression parameters for a streaming LZ4 block.

Enumeration Type Documentation

§ LZ4_status

enum LZ4_status

LZ4 status return types.

Enumerator
LZ4_SUCCESS 

Successful operation.

LZ4_PARTIAL_SUCCESS 

Data was partially decompressed due to insufficient space.

LZ4_NO_CONTENT_SIZE 

Content size is not present in LZ4 frame header.

LZ4_FRAMING_ERROR 

Error in frame header.

LZ4_BLOCK_CHECKSUM_ERROR 

Incorrect block checksum.

LZ4_CONTENT_CHECKSUM_ERROR 

Incorrect content checksum.

§ LZ4_streamState

LZ4 streaming API state.

Enumerator
LZ4_BLOCK_SIZE 

Next byte is the token.

LZ4_TOKEN 

Next byte is the token.

LZ4_LITERAL_LENGTH 

Next byte is the literal length.

LZ4_LITERAL 

Next byte is a literal character.

LZ4_MATCH_LENGTH 

Next byte is the match length.

LZ4_MATCH_OFFSET_LOW 

Next byte is the low match address offset.

LZ4_MATCH_OFFSET_HIGH 

Next byte is the high match address offset.

Function Documentation

§ LZ4_compress()

uint32_t LZ4_compress ( const LZ4_compressParams params,
LZ4_status status 
)

Compress a block of data to a LZ4 frame.

Compress a block of data using LZ4 compression and add LZ4 framing. This API will compress data to a valid LZ4 file and contains several parameters to enable or disable features of the LZ4 framing specification such as content and block checksum using the xxHash algorithm or block size. See the LZ4_compressParams structure documentation for more details about the available parameters.

A block compressed with this method can be saved as a binary .lz4 file and extracted using the LZ4 command line utility.

Parameters
paramsPointer to the LZ4 compression parameter structure.
statusPointer to a LZ4 status that will contain the result status.
Returns
The total compressed frame size.

References LZ4_compressParams::dst, and LZ4_compressParams::src.

§ LZ4_compressBlock()

uint32_t LZ4_compressBlock ( const LZ4_compressBlockParams params,
LZ4_status status 
)

Compress a block of data to a single LZ4 block without framing.

Compress a block of data using only LZ4 compression and block format. This API can be used to compress data and create a custom framing scheme using an alternative checksum method. The LZ4 block format has a single parameter for enabling block checksum computation with the xxHash algorithm. The block checksum is computed on the compressed data block. See the LZ4_compressBlockParams structure documentation for more details about the available parameters.

Parameters
paramsPointer to the LZ4 compression block parameter structure.
statusPointer to a LZ4 status that will contain the result status.
Returns
The total compressed block size.

References LZ4_compressBlockParams::dst, LZ4_compressBlockParams::hashLog2Size, LZ4_compressBlockParams::hashTable, LZ4_compressBlockParams::length, LZ4_LAST_MATCH_DIST, and LZ4_compressBlockParams::src.

§ LZ4_decompress()

uint32_t LZ4_decompress ( const LZ4_decompressParams params,
LZ4_status status 
)

Decompress a LZ4 frame to a block of data.

Decompress a LZ4 frame to an uncompressed data block. This API contains parameters to enable checking of content and block checksum. When enabled the xxHash algorithm is used to verify the checksum. While not required it is the application programmers responsibility to determine if validating the checksum is necessary. See the LZ4_decompressParams structure documentation for more details about the available parameters.

A .lz4 file compressed with the LZ4 command line utility can be decompressed using this API.

Parameters
paramsPointer to the LZ4 decompression parameter structure.
statusPointer to a LZ4 status that will contain the result status.
Returns
The total decompressed data block size.

References LZ4_decompressParams::dst, LZ4_decompressParams::dstLength, and LZ4_decompressParams::src.

§ LZ4_decompressBlock()

uint32_t LZ4_decompressBlock ( const LZ4_decompressBlockParams params,
LZ4_status status 
)

Decompress a single LZ4 block without framing to a block of data.

Decompress a LZ4 block to an uncompressed data block. This API contains a single parameter to enable checking of the block checksum. When enabled the xxHash algorithm is used to verify the checksum. While not required it is the application programmers responsibility to determine if validating the checksum is necessary. See the LZ4_decompressBlockParams structure documentation for more details about the available parameters.

Parameters
paramsPointer to the LZ4 decompression block parameter structure.
statusPointer to a LZ4 status that will contain the result status.
Returns
The total decompressed data block size.

References LZ4_decompressBlockParams::dst, LZ4_decompressBlockParams::dstLength, and LZ4_decompressBlockParams::src.

§ LZ4_getContentSize()

uint32_t LZ4_getContentSize ( const uint8_t *  src,
LZ4_status status 
)

Get the content size of a compressed LZ4 frame.

Get the size of the original uncompressed data block if it is present. The content size is an optional parameter when compressing but it is recommended to enable it and verify the uncompressed data block fits in the allocated buffer before decompressing.

Parameters
srcPointer to the LZ4 frame.
statusPointer to a LZ4 status that will contain the result status.
Returns
The total decompressed content size. The content size is stored as 64-bit but will be truncated to 32-bit.

§ LZ4_streamDecompressBlockInit()

void LZ4_streamDecompressBlockInit ( const LZ4_streamDecompressBlockParams params,
LZ4_streamDecompressBlockState state,
LZ4_status status 
)

Initialize LZ4 stream decompression.

Initialize LZ4 decompression using a stream of data blocks. The streaming API's can be used when data is sent in chunks such as over-the-air or wired serial communication and removes the need to buffer then entire compressed data before running decompression, reducing total system memory used.

This function must be first called to initialize the state before calling LZ4_streamDecompressBlock() to decompress data.

Parameters
paramsPointer to the LZ4 decompression strean parameter structure.
statePointer to the LZ4 decompression stream state.
statusPointer to a LZ4 status that will contain the result status.
Returns
none

References LZ4_streamDecompressBlockParams::containsBlockSize, LZ4_streamDecompressBlockParams::dst, LZ4_streamDecompressBlockState::dstLength, LZ4_streamDecompressBlockParams::dstLength, LZ4_streamDecompressBlockState::dstOrigin, LZ4_streamDecompressBlockState::dstPtr, LZ4_streamDecompressBlockState::literalLength, LZ4_BLOCK_SIZE, LZ4_SUCCESS, LZ4_TOKEN, LZ4_streamDecompressBlockState::matchLength, LZ4_streamDecompressBlockState::matchOffset, and LZ4_streamDecompressBlockState::state.

§ LZ4_streamDecompressBlock()

uint32_t LZ4_streamDecompressBlock ( LZ4_streamDecompressBlockState state,
const void *  data,
uint16_t  length,
LZ4_status status 
)

Decompress a single LZ4 block as a stream of data.

Continue decompression using a stream of data blocks. The streaming API's can be used when data is sent in chunks such as over-the-air or wired serial communication and removes the need to buffer then entire compressed data before running decompression, reducing total system memory used.

The LZ4_streamDecompressBlockInit() function must first be called to initialize the state before decompressing data.

Parameters
statePointer to the LZ4 decompression stream state.
dataPointer to a block of data to continue decompression with.
lengthLength of data block in bytes.
statusPointer to a LZ4 status that will contain the result status.
Returns
The current length of decompressed data.

References LZ4_streamDecompressBlockState::dstLength, LZ4_streamDecompressBlockState::dstOrigin, LZ4_streamDecompressBlockState::dstPtr, LZ4_streamDecompressBlockState::literalLength, LZ4_BLOCK_SIZE, LZ4_LITERAL, LZ4_LITERAL_LENGTH, LZ4_MATCH_LENGTH, LZ4_MATCH_OFFSET_HIGH, LZ4_MATCH_OFFSET_LOW, LZ4_MIN_MATCH, LZ4_PARTIAL_SUCCESS, LZ4_SUCCESS, LZ4_TOKEN, LZ4_TOKEN_LITERAL_MASK, LZ4_TOKEN_MATCH_MASK, LZ4_streamDecompressBlockState::matchLength, LZ4_streamDecompressBlockState::matchOffset, and LZ4_streamDecompressBlockState::state.

© Copyright 1995-2018, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale