wimlib
Macros | Functions
Compression and decompression functions

Functions for XPRESS, LZX, and LZMS compression and decompression. More...

Macros

#define WIMLIB_COMPRESSOR_FLAG_DESTRUCTIVE   0x80000000
 

Functions

int wimlib_set_default_compression_level (int ctype, unsigned int compression_level)
 Set the default compression level for the specified compression type. More...
 
uint64_t wimlib_get_compressor_needed_memory (enum wimlib_compression_type ctype, size_t max_block_size, unsigned int compression_level)
 Return the approximate number of bytes needed to allocate a compressor with wimlib_create_compressor() for the specified compression type, maximum block size, and compression level. More...
 
int wimlib_create_compressor (enum wimlib_compression_type ctype, size_t max_block_size, unsigned int compression_level, struct wimlib_compressor **compressor_ret)
 Allocate a compressor for the specified compression type using the specified parameters. More...
 
size_t wimlib_compress (const void *uncompressed_data, size_t uncompressed_size, void *compressed_data, size_t compressed_size_avail, struct wimlib_compressor *compressor)
 Compress a buffer of data. More...
 
void wimlib_free_compressor (struct wimlib_compressor *compressor)
 Free a compressor previously allocated with wimlib_create_compressor(). More...
 
int wimlib_create_decompressor (enum wimlib_compression_type ctype, size_t max_block_size, struct wimlib_decompressor **decompressor_ret)
 Allocate a decompressor for the specified compression type. More...
 
int wimlib_decompress (const void *compressed_data, size_t compressed_size, void *uncompressed_data, size_t uncompressed_size, struct wimlib_decompressor *decompressor)
 Decompress a buffer of data. More...
 
void wimlib_free_decompressor (struct wimlib_decompressor *decompressor)
 Free a decompressor previously allocated with wimlib_create_decompressor(). More...
 

Detailed Description

Functions for XPRESS, LZX, and LZMS compression and decompression.

These functions are already used by wimlib internally when appropriate for reading and writing WIM archives. But they are exported and documented so that they can be used in other applications or libraries for general-purpose lossless data compression. They are implemented in highly optimized C code, using state-of-the-art compression techniques. The main limitation is the lack of sliding window support; this has, however, allowed the algorithms to be optimized for block-based compression.

Macro Definition Documentation

◆ WIMLIB_COMPRESSOR_FLAG_DESTRUCTIVE

#define WIMLIB_COMPRESSOR_FLAG_DESTRUCTIVE   0x80000000

Function Documentation

◆ wimlib_set_default_compression_level()

int wimlib_set_default_compression_level ( int  ctype,
unsigned int  compression_level 
)

Set the default compression level for the specified compression type.

This is the compression level that wimlib_create_compressor() assumes if it is called with compression_level specified as 0.

wimlib's WIM writing code (e.g. wimlib_write()) will pass 0 to wimlib_create_compressor() internally. Therefore, calling this function will affect the compression level of any data later written to WIM files using the specified compression type.

The initial state, before this function is called, is that all compression types have a default compression level of 50.

Parameters
ctypeCompression type for which to set the default compression level, as one of the wimlib_compression_type constants. Or, if this is the special value -1, the default compression levels for all compression types will be set.
compression_levelThe default compression level to set. If 0, the "default default" level of 50 is restored. Otherwise, a higher value indicates higher compression, whereas a lower value indicates lower compression. See wimlib_create_compressor() for more information.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_INVALID_COMPRESSION_TYPEctype was neither a supported compression type nor -1.

◆ wimlib_get_compressor_needed_memory()

uint64_t wimlib_get_compressor_needed_memory ( enum wimlib_compression_type  ctype,
size_t  max_block_size,
unsigned int  compression_level 
)

Return the approximate number of bytes needed to allocate a compressor with wimlib_create_compressor() for the specified compression type, maximum block size, and compression level.

compression_level may be 0, in which case the current default compression level for ctype is used. Returns 0 if the compression type is invalid, or the max_block_size for that compression type is invalid.

◆ wimlib_create_compressor()

int wimlib_create_compressor ( enum wimlib_compression_type  ctype,
size_t  max_block_size,
unsigned int  compression_level,
struct wimlib_compressor **  compressor_ret 
)

Allocate a compressor for the specified compression type using the specified parameters.

This function is part of wimlib's compression API; it is not necessary to call this to process a WIM file.

Parameters
ctypeCompression type for which to create the compressor, as one of the wimlib_compression_type constants.
max_block_sizeThe maximum compression block size to support. This specifies the maximum allowed value for the uncompressed_size parameter of wimlib_compress() when called using this compressor.
Usually, the amount of memory used by the compressor will scale in proportion to the max_block_size parameter. wimlib_get_compressor_needed_memory() can be used to query the specific amount of memory that will be required.
This parameter must be at least 1 and must be less than or equal to a compression-type-specific limit.
In general, the same value of max_block_size must be passed to wimlib_create_decompressor() when the data is later decompressed. However, some compression types have looser requirements regarding this.
compression_levelThe compression level to use. If 0, the default compression level (50, or another value as set through wimlib_set_default_compression_level()) is used. Otherwise, a higher value indicates higher compression. The values are scaled so that 10 is low compression, 50 is medium compression, and 100 is high compression. This is not a percentage; values above 100 are also valid.
Using a higher-than-default compression level can result in a better compression ratio, but can significantly reduce performance. Similarly, using a lower-than-default compression level can result in better performance, but can significantly worsen the compression ratio. The exact results will depend heavily on the compression type and what algorithms are implemented for it. If you are considering using a non-default compression level, you should run benchmarks to see if it is worthwhile for your application.
The compression level does not affect the format of the compressed data. Therefore, it is a compressor-only parameter and does not need to be passed to the decompressor.
Since wimlib v1.8.0, this parameter can be OR-ed with the flag WIMLIB_COMPRESSOR_FLAG_DESTRUCTIVE. This creates the compressor in a mode where it is allowed to modify the input buffer. Specifically, in this mode, if compression succeeds, the input buffer may have been modified, whereas if compression does not succeed the input buffer still may have been written to but will have been restored exactly to its original state. This mode is designed to save some memory when using large buffer sizes.
compressor_retA location into which to return the pointer to the allocated compressor. The allocated compressor can be used for any number of calls to wimlib_compress() before being freed with wimlib_free_compressor().
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_INVALID_COMPRESSION_TYPEctype was not a supported compression type.
WIMLIB_ERR_INVALID_PARAMmax_block_size was invalid for the compression type, or compressor_ret was NULL.
WIMLIB_ERR_NOMEMInsufficient memory to allocate the compressor.

◆ wimlib_compress()

size_t wimlib_compress ( const void *  uncompressed_data,
size_t  uncompressed_size,
void *  compressed_data,
size_t  compressed_size_avail,
struct wimlib_compressor *  compressor 
)

Compress a buffer of data.

Parameters
uncompressed_dataBuffer containing the data to compress.
uncompressed_sizeSize, in bytes, of the data to compress. This cannot be greater than the max_block_size with which wimlib_create_compressor() was called. (If it is, the data will not be compressed and 0 will be returned.)
compressed_dataBuffer into which to write the compressed data.
compressed_size_availNumber of bytes available in compressed_data.
compressorA compressor previously allocated with wimlib_create_compressor().
Returns
The size of the compressed data, in bytes, or 0 if the data could not be compressed to compressed_size_avail or fewer bytes.

◆ wimlib_free_compressor()

void wimlib_free_compressor ( struct wimlib_compressor *  compressor)

Free a compressor previously allocated with wimlib_create_compressor().

Parameters
compressorThe compressor to free. If NULL, no action is taken.

◆ wimlib_create_decompressor()

int wimlib_create_decompressor ( enum wimlib_compression_type  ctype,
size_t  max_block_size,
struct wimlib_decompressor **  decompressor_ret 
)

Allocate a decompressor for the specified compression type.

This function is part of wimlib's compression API; it is not necessary to call this to process a WIM file.

Parameters
ctypeCompression type for which to create the decompressor, as one of the wimlib_compression_type constants.
max_block_sizeThe maximum compression block size to support. This specifies the maximum allowed value for the uncompressed_size parameter of wimlib_decompress().
In general, this parameter must be the same as the max_block_size that was passed to wimlib_create_compressor() when the data was compressed. However, some compression types have looser requirements regarding this.
decompressor_retA location into which to return the pointer to the allocated decompressor. The allocated decompressor can be used for any number of calls to wimlib_decompress() before being freed with wimlib_free_decompressor().
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_INVALID_COMPRESSION_TYPEctype was not a supported compression type.
WIMLIB_ERR_INVALID_PARAMmax_block_size was invalid for the compression type, or decompressor_ret was NULL.
WIMLIB_ERR_NOMEMInsufficient memory to allocate the decompressor.

◆ wimlib_decompress()

int wimlib_decompress ( const void *  compressed_data,
size_t  compressed_size,
void *  uncompressed_data,
size_t  uncompressed_size,
struct wimlib_decompressor *  decompressor 
)

Decompress a buffer of data.

Parameters
compressed_dataBuffer containing the data to decompress.
compressed_sizeSize, in bytes, of the data to decompress.
uncompressed_dataBuffer into which to write the uncompressed data.
uncompressed_sizeSize, in bytes, of the data when uncompressed. This cannot exceed the max_block_size with which wimlib_create_decompressor() was called. (If it does, the data will not be decompressed and a nonzero value will be returned.)
decompressorA decompressor previously allocated with wimlib_create_decompressor().
Returns
0 on success; nonzero on failure.

No specific error codes are defined; any nonzero value indicates that the decompression failed. This can only occur if the data is truly invalid; there will never be transient errors like "out of memory", for example.

This function requires that the exact uncompressed size of the data be passed as the uncompressed_size parameter. If this is not done correctly, decompression may fail or the data may be decompressed incorrectly.

◆ wimlib_free_decompressor()

void wimlib_free_decompressor ( struct wimlib_decompressor *  decompressor)

Free a decompressor previously allocated with wimlib_create_decompressor().

Parameters
decompressorThe decompressor to free. If NULL, no action is taken.