revi-archive/xz-archive
1
0
Fork 0
mirror of https://git.tukaani.org/xz.git synced 2024-04-04 12:36:23 +02:00
Code Activity

Updates to liblzma API headers.

Browse source 
Added lzma_nothrow for every function. It adds
throw() when the header is used in C++ code.

Some lzma_attrs were added or removed.

Lots of comments were improved.
This commit is contained in:
Lasse Collin 2009-08-27 10:13:46 +03:00
parent 8e8ebc17c5
commit 3e2ba8b585
12 changed files with 275 additions and 197 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
src/liblzma/api/lzma.h
View file

@ -198,6 +198,26 @@
#endif #endif
/***********
* nothrow *
***********/
/*
* None of the functions in liblzma may throw an exception. Even
* the functions that use callback functions won't throw exceptions,
* because liblzma would break if a callback function threw an exception.
*/
#ifndef lzma_nothrow
# if defined(__cplusplus)
# define lzma_nothrow throw()
# elif __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
# define lzma_nothrow __attribute__((__nothrow__))
# else
# define lzma_nothrow
# endif
#endif
/******************** /********************
* GNU C extensions * * GNU C extensions *
********************/ ********************/

48
src/liblzma/api/lzma/base.h
View file

@ -144,7 +144,7 @@ typedef enum {
* Decoder would need more memory than allowed by the * Decoder would need more memory than allowed by the
* specified memory usage limit. To continue decoding, * specified memory usage limit. To continue decoding,
* the memory usage limit has to be increased with * the memory usage limit has to be increased with
* lzma_memlimit(). * lzma_memlimit_set().
*/ */
LZMA_FORMAT_ERROR = 7, LZMA_FORMAT_ERROR = 7,
@ -181,8 +181,7 @@ typedef enum {
* format would be exceeded. These limits are huge, thus * format would be exceeded. These limits are huge, thus
* getting this error from an encoder is mostly theoretical. * getting this error from an encoder is mostly theoretical.
* For example, the maximum compressed and uncompressed * For example, the maximum compressed and uncompressed
* size of a .xz Stream created with lzma_stream_encoder is * size of a .xz Stream is roughly 8 EiB (2^63 bytes).
* 2^63 - 1 bytes (one byte less than 8 EiB).
* *
* Decoders return this error if the input data is corrupt. * Decoders return this error if the input data is corrupt.
* This can mean, for example, invalid CRC32 in headers * This can mean, for example, invalid CRC32 in headers
@ -208,7 +207,8 @@ typedef enum {
* LZMA_BUF_ERROR. This is intentional. * LZMA_BUF_ERROR. This is intentional.
* *
* With zlib, Z_BUF_ERROR may be returned even if the * With zlib, Z_BUF_ERROR may be returned even if the
* application is doing nothing wrong. The above hack * application is doing nothing wrong, so apps will need
* to handle Z_BUF_ERROR specially. The above hack
* guarantees that liblzma never returns LZMA_BUF_ERROR * guarantees that liblzma never returns LZMA_BUF_ERROR
* to properly written applications unless the input file * to properly written applications unless the input file
* is truncated or corrupt. This should simplify the * is truncated or corrupt. This should simplify the
@ -329,7 +329,8 @@ typedef enum {
* to liblzma, and some advanced functions take a pointer to lzma_allocator * to liblzma, and some advanced functions take a pointer to lzma_allocator
* as a separate function argument. The library will use the functions * as a separate function argument. The library will use the functions
* specified in lzma_allocator for memory handling instead of the default * specified in lzma_allocator for memory handling instead of the default
* malloc() and free(). * malloc() and free(). C++ users should note that the custom memory
* handling functions must not throw exceptions.
* *
* liblzma doesn't make an internal copy of lzma_allocator. Thus, it is * liblzma doesn't make an internal copy of lzma_allocator. Thus, it is
* OK to change these function pointers in the middle of the coding * OK to change these function pointers in the middle of the coding
@ -359,12 +360,12 @@ typedef struct {
* for some reason. When allocation fails, functions * for some reason. When allocation fails, functions
* of liblzma return LZMA_MEM_ERROR. * of liblzma return LZMA_MEM_ERROR.
* *
* For performance reasons, the allocator should not waste time * The allocator should not waste time zeroing the allocated buffers.
* zeroing the allocated buffers. This is not only about speed, but * This is not only about speed, but also memory usage, since the
* also memory usage, since the operating system kernel doesn't * operating system kernel doesn't necessarily allocate the requested
* necessarily allocate the requested memory in physical memory until * memory in physical memory until it is actually used. With small
* it is actually used. With small input files liblzma may actually * input files, liblzma may actually need only a fraction of the
* need only a fraction of the memory that it requested for allocation. * memory that it requested for allocation.
* *
* \note LZMA_MEM_ERROR is also used when the size of the * \note LZMA_MEM_ERROR is also used when the size of the
* allocation would be greater than SIZE_MAX. Thus, * allocation would be greater than SIZE_MAX. Thus,
@ -414,9 +415,9 @@ typedef struct lzma_internal_s lzma_internal;
* \brief Passing data to and from liblzma * \brief Passing data to and from liblzma
* *
* The lzma_stream structure is used for * The lzma_stream structure is used for
* - passing pointers to input and output buffers to liblzma; * - passing pointers to input and output buffers to liblzma;
* - defining custom memory hander functions; and * - defining custom memory hander functions; and
* - holding a pointer to coder-specific internal data structures. * - holding a pointer to coder-specific internal data structures.
* *
* Typical usage: * Typical usage:
* *
@ -459,7 +460,9 @@ typedef struct {
uint64_t total_out; /**< Total number of bytes written by liblzma. */ uint64_t total_out; /**< Total number of bytes written by liblzma. */
/** /**
* Custom memory allocation functions. Set to NULL to use * \brief Custom memory allocation functions
*
* In most cases this is NULL which makes liblzma use
* the standard malloc() and free(). * the standard malloc() and free().
*/ */
lzma_allocator *allocator; lzma_allocator *allocator;
@ -516,11 +519,10 @@ typedef struct {
* to and get output from liblzma. * to and get output from liblzma.
* *
* See the description of the coder-specific initialization function to find * See the description of the coder-specific initialization function to find
* out what `action' values are supported by the coder. See documentation of * out what `action' values are supported by the coder.
* lzma_ret for the possible return values.
*/ */
extern LZMA_API(lzma_ret) lzma_code(lzma_stream *strm, lzma_action action) extern LZMA_API(lzma_ret) lzma_code(lzma_stream *strm, lzma_action action)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -536,7 +538,7 @@ extern LZMA_API(lzma_ret) lzma_code(lzma_stream *strm, lzma_action action)
* stream structure. liblzma doesn't do this, and assumes that * stream structure. liblzma doesn't do this, and assumes that
* application knows what it is doing. * application knows what it is doing.
*/ */
extern LZMA_API(void) lzma_end(lzma_stream *strm); extern LZMA_API(void) lzma_end(lzma_stream *strm) lzma_nothrow;
/** /**
@ -561,7 +563,8 @@ extern LZMA_API(void) lzma_end(lzma_stream *strm);
* If this function isn't supported by *strm or some other error * If this function isn't supported by *strm or some other error
* occurs, zero is returned. * occurs, zero is returned.
*/ */
extern LZMA_API(uint64_t) lzma_memusage(const lzma_stream *strm); extern LZMA_API(uint64_t) lzma_memusage(const lzma_stream *strm)
lzma_nothrow lzma_attr_pure;
/** /**
@ -573,7 +576,8 @@ extern LZMA_API(uint64_t) lzma_memusage(const lzma_stream *strm);
* \return On success, the current memory usage limit is returned * \return On success, the current memory usage limit is returned
* (always non-zero). On error, zero is returned. * (always non-zero). On error, zero is returned.
*/ */
extern LZMA_API(uint64_t) lzma_memlimit_get(const lzma_stream *strm); extern LZMA_API(uint64_t) lzma_memlimit_get(const lzma_stream *strm)
lzma_nothrow lzma_attr_pure;
/** /**
@ -589,4 +593,4 @@ extern LZMA_API(uint64_t) lzma_memlimit_get(const lzma_stream *strm);
* support memory usage limit or memlimit was zero. * support memory usage limit or memlimit was zero.
*/ */
extern LZMA_API(lzma_ret) lzma_memlimit_set( extern LZMA_API(lzma_ret) lzma_memlimit_set(
lzma_stream *strm, uint64_t memlimit); lzma_stream *strm, uint64_t memlimit) lzma_nothrow;

38
src/liblzma/api/lzma/block.h
View file

@ -160,9 +160,9 @@ typedef struct {
* *
* This is handled very similarly to compressed_size above. * This is handled very similarly to compressed_size above.
* *
* Unlike compressed_size, uncompressed_size is needed by fewer * uncompressed_size is needed by fewer functions than
* functions. This is because uncompressed_size isn't needed to * compressed_size. This is because uncompressed_size isn't
* validate that Block stays within proper limits. * needed to validate that Block stays within proper limits.
* *
* Read by: * Read by:
* - lzma_block_header_size() * - lzma_block_header_size()
@ -222,7 +222,7 @@ typedef struct {
* - lzma_block_buffer_encode() * - lzma_block_buffer_encode()
* - lzma_block_buffer_decode() * - lzma_block_buffer_decode()
*/ */
uint8_t raw_check[64]; uint8_t raw_check[LZMA_CHECK_SIZE_MAX];
/* /*
* Reserved space to allow possible future extensions without * Reserved space to allow possible future extensions without
@ -294,14 +294,14 @@ typedef struct {
* a side-effect validates the filter chain. * a side-effect validates the filter chain.
*/ */
extern LZMA_API(lzma_ret) lzma_block_header_size(lzma_block *block) extern LZMA_API(lzma_ret) lzma_block_header_size(lzma_block *block)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
* \brief Encode Block Header * \brief Encode Block Header
* *
* The caller must have calculated the size of the Block Header already with * The caller must have calculated the size of the Block Header already with
* lzma_block_header_size(). If larger value than the one calculated by * lzma_block_header_size(). If a value larger than the one calculated by
* lzma_block_header_size() is used, the Block Header will be padded to the * lzma_block_header_size() is used, the Block Header will be padded to the
* specified size. * specified size.
* *
@ -317,7 +317,7 @@ extern LZMA_API(lzma_ret) lzma_block_header_size(lzma_block *block)
*/ */
extern LZMA_API(lzma_ret) lzma_block_header_encode( extern LZMA_API(lzma_ret) lzma_block_header_encode(
const lzma_block *block, uint8_t *out) const lzma_block *block, uint8_t *out)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -347,7 +347,7 @@ extern LZMA_API(lzma_ret) lzma_block_header_encode(
*/ */
extern LZMA_API(lzma_ret) lzma_block_header_decode(lzma_block *block, extern LZMA_API(lzma_ret) lzma_block_header_decode(lzma_block *block,
lzma_allocator *allocator, const uint8_t *in) lzma_allocator *allocator, const uint8_t *in)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -379,7 +379,7 @@ extern LZMA_API(lzma_ret) lzma_block_header_decode(lzma_block *block,
*/ */
extern LZMA_API(lzma_ret) lzma_block_compressed_size( extern LZMA_API(lzma_ret) lzma_block_compressed_size(
lzma_block *block, lzma_vli unpadded_size) lzma_block *block, lzma_vli unpadded_size)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -394,7 +394,7 @@ extern LZMA_API(lzma_ret) lzma_block_compressed_size(
* \return Unpadded Size on success, or zero on error. * \return Unpadded Size on success, or zero on error.
*/ */
extern LZMA_API(lzma_vli) lzma_block_unpadded_size(const lzma_block *block) extern LZMA_API(lzma_vli) lzma_block_unpadded_size(const lzma_block *block)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/** /**
@ -407,7 +407,7 @@ extern LZMA_API(lzma_vli) lzma_block_unpadded_size(const lzma_block *block)
* zero is returned. * zero is returned.
*/ */
extern LZMA_API(lzma_vli) lzma_block_total_size(const lzma_block *block) extern LZMA_API(lzma_vli) lzma_block_total_size(const lzma_block *block)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/** /**
@ -426,7 +426,7 @@ extern LZMA_API(lzma_vli) lzma_block_total_size(const lzma_block *block)
*/ */
extern LZMA_API(lzma_ret) lzma_block_encoder( extern LZMA_API(lzma_ret) lzma_block_encoder(
lzma_stream *strm, lzma_block *block) lzma_stream *strm, lzma_block *block)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -444,16 +444,17 @@ extern LZMA_API(lzma_ret) lzma_block_encoder(
*/ */
extern LZMA_API(lzma_ret) lzma_block_decoder( extern LZMA_API(lzma_ret) lzma_block_decoder(
lzma_stream *strm, lzma_block *block) lzma_stream *strm, lzma_block *block)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
* \brief Calculate maximum output buffer size for single-call encoding * \brief Calculate maximum output size for single-call Block encoding
* *
* This is equivalent to lzma_stream_buffer_bound() but for .xz Blocks. * This is equivalent to lzma_stream_buffer_bound() but for .xz Blocks.
* See the documentation of lzma_stream_buffer_bound(). * See the documentation of lzma_stream_buffer_bound().
*/ */
extern LZMA_API(size_t) lzma_block_buffer_bound(size_t uncompressed_size); extern LZMA_API(size_t) lzma_block_buffer_bound(size_t uncompressed_size)
lzma_nothrow;
/** /**
@ -474,7 +475,7 @@ extern LZMA_API(size_t) lzma_block_buffer_bound(size_t uncompressed_size);
* still works normally, because it doesn't read the filters array. * still works normally, because it doesn't read the filters array.
* *
* \param block Block options: block->version, block->check, * \param block Block options: block->version, block->check,
* and block->filters must be initialized. * and block->filters must have been initialized.
* \param allocator lzma_allocator for custom allocator functions. * \param allocator lzma_allocator for custom allocator functions.
* Set to NULL to use malloc() and free(). * Set to NULL to use malloc() and free().
* \param in Beginning of the input buffer * \param in Beginning of the input buffer
@ -496,7 +497,7 @@ extern LZMA_API(lzma_ret) lzma_block_buffer_encode(
lzma_block *block, lzma_allocator *allocator, lzma_block *block, lzma_allocator *allocator,
const uint8_t *in, size_t in_size, const uint8_t *in, size_t in_size,
uint8_t *out, size_t *out_pos, size_t out_size) uint8_t *out, size_t *out_pos, size_t out_size)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -529,4 +530,5 @@ extern LZMA_API(lzma_ret) lzma_block_buffer_encode(
extern LZMA_API(lzma_ret) lzma_block_buffer_decode( extern LZMA_API(lzma_ret) lzma_block_buffer_decode(
lzma_block *block, lzma_allocator *allocator, lzma_block *block, lzma_allocator *allocator,
const uint8_t *in, size_t *in_pos, size_t in_size, const uint8_t *in, size_t *in_pos, size_t in_size,
uint8_t *out, size_t *out_pos, size_t out_size); uint8_t *out, size_t *out_pos, size_t out_size)
lzma_nothrow;

22
src/liblzma/api/lzma/check.h
View file

@ -21,7 +21,7 @@
* \brief Type of the integrity check (Check ID) * \brief Type of the integrity check (Check ID)
* *
* The .xz format supports multiple types of checks that are calculated * The .xz format supports multiple types of checks that are calculated
* from the uncompressed data. They very in both speed and ability to * from the uncompressed data. They vary in both speed and ability to
* detect errors. * detect errors.
*/ */
typedef enum { typedef enum {
@ -71,7 +71,7 @@ typedef enum {
/** /**
* \brief Test if the given Check ID is supported * \brief Test if the given Check ID is supported
* *
* Returns true if the given Check ID is supported by this liblzma build. * Return true if the given Check ID is supported by this liblzma build.
* Otherwise false is returned. It is safe to call this with a value that * Otherwise false is returned. It is safe to call this with a value that
* is not in the range [0, 15]; in that case the return value is always false. * is not in the range [0, 15]; in that case the return value is always false.
* *
@ -79,7 +79,7 @@ typedef enum {
* supported (even if liblzma is built with limited features). * supported (even if liblzma is built with limited features).
*/ */
extern LZMA_API(lzma_bool) lzma_check_is_supported(lzma_check check) extern LZMA_API(lzma_bool) lzma_check_is_supported(lzma_check check)
lzma_attr_const; lzma_nothrow lzma_attr_const;
/** /**
@ -92,7 +92,8 @@ extern LZMA_API(lzma_bool) lzma_check_is_supported(lzma_check check)
* *
* If the argument is not in the range [0, 15], UINT32_MAX is returned. * If the argument is not in the range [0, 15], UINT32_MAX is returned.
*/ */
extern LZMA_API(uint32_t) lzma_check_size(lzma_check check) lzma_attr_const; extern LZMA_API(uint32_t) lzma_check_size(lzma_check check)
lzma_nothrow lzma_attr_const;
/** /**
@ -104,32 +105,32 @@ extern LZMA_API(uint32_t) lzma_check_size(lzma_check check) lzma_attr_const;
/** /**
* \brief Calculate CRC32 * \brief Calculate CRC32
* *
* Calculates CRC32 using the polynomial from the IEEE 802.3 standard. * Calculate CRC32 using the polynomial from the IEEE 802.3 standard.
* *
* \param buf Pointer to the input buffer * \param buf Pointer to the input buffer
* \param size Size of the input buffer * \param size Size of the input buffer
* \param crc Previously returned CRC value. This is used to * \param crc Previously returned CRC value. This is used to
* calculate the CRC of a big buffer in smaller chunks. * calculate the CRC of a big buffer in smaller chunks.
* Set to zero when there is no previous value. * Set to zero when starting a new calculation.
* *
* \return Updated CRC value, which can be passed to this function * \return Updated CRC value, which can be passed to this function
* again to continue CRC calculation. * again to continue CRC calculation.
*/ */
extern LZMA_API(uint32_t) lzma_crc32( extern LZMA_API(uint32_t) lzma_crc32(
const uint8_t *buf, size_t size, uint32_t crc) const uint8_t *buf, size_t size, uint32_t crc)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/** /**
* \brief Calculate CRC64 * \brief Calculate CRC64
* *
* Calculates CRC64 using the polynomial from the ECMA-182 standard. * Calculate CRC64 using the polynomial from the ECMA-182 standard.
* *
* This function is used similarly to lzma_crc32(). See its documentation. * This function is used similarly to lzma_crc32(). See its documentation.
*/ */
extern LZMA_API(uint64_t) lzma_crc64( extern LZMA_API(uint64_t) lzma_crc64(
const uint8_t *buf, size_t size, uint64_t crc) const uint8_t *buf, size_t size, uint64_t crc)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/* /*
@ -145,4 +146,5 @@ extern LZMA_API(uint64_t) lzma_crc64(
* returned LZMA_NO_CHECK, LZMA_UNSUPPORTED_CHECK, or LZMA_GET_CHECK. * returned LZMA_NO_CHECK, LZMA_UNSUPPORTED_CHECK, or LZMA_GET_CHECK.
* Calling this function in any other situation has undefined behavior. * Calling this function in any other situation has undefined behavior.
*/ */
extern LZMA_API(lzma_check) lzma_get_check(const lzma_stream *strm); extern LZMA_API(lzma_check) lzma_get_check(const lzma_stream *strm)
lzma_nothrow;

36
src/liblzma/api/lzma/container.h
View file

@ -55,7 +55,7 @@
* *
* This flag doesn't affect the memory usage requirements of the decoder (at * This flag doesn't affect the memory usage requirements of the decoder (at
* least not significantly). The memory usage of the encoder may be increased * least not significantly). The memory usage of the encoder may be increased
* a little but only at the lowest preset levels (0-4 or so). * a little but only at the lowest preset levels (0-2).
*/ */
#define LZMA_PRESET_EXTREME (UINT32_C(1) << 31) #define LZMA_PRESET_EXTREME (UINT32_C(1) << 31)
@ -68,7 +68,7 @@
* \param preset Compression preset (level and possible flags) * \param preset Compression preset (level and possible flags)
*/ */
extern LZMA_API(uint64_t) lzma_easy_encoder_memusage(uint32_t preset) extern LZMA_API(uint64_t) lzma_easy_encoder_memusage(uint32_t preset)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/** /**
@ -79,7 +79,7 @@ extern LZMA_API(uint64_t) lzma_easy_encoder_memusage(uint32_t preset)
* \param preset Compression preset (level and possible flags) * \param preset Compression preset (level and possible flags)
*/ */
extern LZMA_API(uint64_t) lzma_easy_decoder_memusage(uint32_t preset) extern LZMA_API(uint64_t) lzma_easy_decoder_memusage(uint32_t preset)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/** /**
@ -101,8 +101,7 @@ extern LZMA_API(uint64_t) lzma_easy_decoder_memusage(uint32_t preset)
* *
* \return - LZMA_OK: Initialization succeeded. Use lzma_code() to * \return - LZMA_OK: Initialization succeeded. Use lzma_code() to
* encode your data. * encode your data.
* - LZMA_MEM_ERROR: Memory allocation failed. All memory * - LZMA_MEM_ERROR: Memory allocation failed.
* previously allocated for *strm is now freed.
* - LZMA_OPTIONS_ERROR: The given compression level is not * - LZMA_OPTIONS_ERROR: The given compression level is not
* supported by this build of liblzma. * supported by this build of liblzma.
* - LZMA_UNSUPPORTED_CHECK: The given check type is not * - LZMA_UNSUPPORTED_CHECK: The given check type is not
@ -110,6 +109,10 @@ extern LZMA_API(uint64_t) lzma_easy_decoder_memusage(uint32_t preset)
* - LZMA_PROG_ERROR: One or more of the parameters have values * - LZMA_PROG_ERROR: One or more of the parameters have values
* that will never be valid. For example, strm == NULL. * that will never be valid. For example, strm == NULL.
* *
* If initialization fails (return value is not LZMA_OK), all the memory
* allocated for *strm by liblzma is always freed. Thus, there is no need
* to call lzma_end() after failed initialization.
*
* If initialization succeeds, use lzma_code() to do the actual encoding. * If initialization succeeds, use lzma_code() to do the actual encoding.
* Valid values for `action' (the second argument of lzma_code()) are * Valid values for `action' (the second argument of lzma_code()) are
* LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future, * LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future,
@ -117,7 +120,7 @@ extern LZMA_API(uint64_t) lzma_easy_decoder_memusage(uint32_t preset)
*/ */
extern LZMA_API(lzma_ret) lzma_easy_encoder( extern LZMA_API(lzma_ret) lzma_easy_encoder(
lzma_stream *strm, uint32_t preset, lzma_check check) lzma_stream *strm, uint32_t preset, lzma_check check)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -150,7 +153,7 @@ extern LZMA_API(lzma_ret) lzma_easy_encoder(
extern LZMA_API(lzma_ret) lzma_easy_buffer_encode( extern LZMA_API(lzma_ret) lzma_easy_buffer_encode(
uint32_t preset, lzma_check check, uint32_t preset, lzma_check check,
lzma_allocator *allocator, const uint8_t *in, size_t in_size, lzma_allocator *allocator, const uint8_t *in, size_t in_size,
uint8_t *out, size_t *out_pos, size_t out_size); uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow;
/** /**
@ -170,7 +173,7 @@ extern LZMA_API(lzma_ret) lzma_easy_buffer_encode(
*/ */
extern LZMA_API(lzma_ret) lzma_stream_encoder(lzma_stream *strm, extern LZMA_API(lzma_ret) lzma_stream_encoder(lzma_stream *strm,
const lzma_filter *filters, lzma_check check) const lzma_filter *filters, lzma_check check)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -195,7 +198,7 @@ extern LZMA_API(lzma_ret) lzma_stream_encoder(lzma_stream *strm,
*/ */
extern LZMA_API(lzma_ret) lzma_alone_encoder( extern LZMA_API(lzma_ret) lzma_alone_encoder(
lzma_stream *strm, const lzma_options_lzma *options) lzma_stream *strm, const lzma_options_lzma *options)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -220,11 +223,12 @@ extern LZMA_API(lzma_ret) lzma_alone_encoder(
* uncompressible data. Currently there is no function to * uncompressible data. Currently there is no function to
* calculate the maximum expansion of multi-call encoding. * calculate the maximum expansion of multi-call encoding.
*/ */
extern LZMA_API(size_t) lzma_stream_buffer_bound(size_t uncompressed_size); extern LZMA_API(size_t) lzma_stream_buffer_bound(size_t uncompressed_size)
lzma_nothrow;
/** /**
* \brief Single-call Stream encoder * \brief Single-call .xz Stream encoder
* *
* \param filters Array of filters. This must be terminated with * \param filters Array of filters. This must be terminated with
* filters[n].id = LZMA_VLI_UNKNOWN. See filter.h * filters[n].id = LZMA_VLI_UNKNOWN. See filter.h
@ -252,7 +256,7 @@ extern LZMA_API(lzma_ret) lzma_stream_buffer_encode(
lzma_filter *filters, lzma_check check, lzma_filter *filters, lzma_check check,
lzma_allocator *allocator, const uint8_t *in, size_t in_size, lzma_allocator *allocator, const uint8_t *in, size_t in_size,
uint8_t *out, size_t *out_pos, size_t out_size) uint8_t *out, size_t *out_pos, size_t out_size)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/************ /************
@ -317,7 +321,7 @@ extern LZMA_API(lzma_ret) lzma_stream_buffer_encode(
*/ */
extern LZMA_API(lzma_ret) lzma_stream_decoder( extern LZMA_API(lzma_ret) lzma_stream_decoder(
lzma_stream *strm, uint64_t memlimit, uint32_t flags) lzma_stream *strm, uint64_t memlimit, uint32_t flags)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -337,7 +341,7 @@ extern LZMA_API(lzma_ret) lzma_stream_decoder(
*/ */
extern LZMA_API(lzma_ret) lzma_auto_decoder( extern LZMA_API(lzma_ret) lzma_auto_decoder(
lzma_stream *strm, uint64_t memlimit, uint32_t flags) lzma_stream *strm, uint64_t memlimit, uint32_t flags)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -352,7 +356,7 @@ extern LZMA_API(lzma_ret) lzma_auto_decoder(
*/ */
extern LZMA_API(lzma_ret) lzma_alone_decoder( extern LZMA_API(lzma_ret) lzma_alone_decoder(
lzma_stream *strm, uint64_t memlimit) lzma_stream *strm, uint64_t memlimit)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -397,4 +401,4 @@ extern LZMA_API(lzma_ret) lzma_stream_buffer_decode(
uint64_t *memlimit, uint32_t flags, lzma_allocator *allocator, uint64_t *memlimit, uint32_t flags, lzma_allocator *allocator,
const uint8_t *in, size_t *in_pos, size_t in_size, const uint8_t *in, size_t *in_pos, size_t in_size,
uint8_t *out, size_t *out_pos, size_t out_size) uint8_t *out, size_t *out_pos, size_t out_size)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;

81
src/liblzma/api/lzma/filter.h
View file

@ -29,16 +29,16 @@
/** /**
* \brief Filter options * \brief Filter options
* *
* This structure is used to pass Filter ID and a pointer filter's options * This structure is used to pass Filter ID and a pointer filter's
* to liblzma. An array of lzma_filter structures is used to define a filter * options to liblzma. A few functions work with a single lzma_filter
* chain. * structure, while most functions expect a filter chain.
* *
* A filter chain is indicated with an array of lzma_filter structures. * A filter chain is indicated with an array of lzma_filter structures.
* The array is terminated with .id = LZMA_VLI_UNKNOWN. Thus, the filter array * The array is terminated with .id = LZMA_VLI_UNKNOWN. Thus, the filter
* must have LZMA_FILTERS_MAX + 1 elements (that is, five) to be able to hold * array must have LZMA_FILTERS_MAX + 1 elements (that is, five) to
* any arbitrary filter chain. This is important when using * be able to hold any arbitrary filter chain. This is important when
* lzma_block_header_decode() from block.h, because too small array would * using lzma_block_header_decode() from block.h, because too small
* make liblzma write past the end of the filters array. * array would make liblzma write past the end of the filters array.
*/ */
typedef struct { typedef struct {
/** /**
@ -47,6 +47,9 @@ typedef struct {
* Use constants whose name begin with `LZMA_FILTER_' to specify * Use constants whose name begin with `LZMA_FILTER_' to specify
* different filters. In an array of lzma_filter structures, use * different filters. In an array of lzma_filter structures, use
* LZMA_VLI_UNKNOWN to indicate end of filters. * LZMA_VLI_UNKNOWN to indicate end of filters.
*
* \note This is not an enum, because on some systems enums
* cannot be 64-bit.
*/ */
lzma_vli id; lzma_vli id;
@ -70,49 +73,57 @@ typedef struct {
/** /**
* \brief Test if the given Filter ID is supported for encoding * \brief Test if the given Filter ID is supported for encoding
* *
* Returns true if the give Filter ID is supported for encoding by this * Return true if the give Filter ID is supported for encoding by this
* liblzma build. Otherwise false is returned. * liblzma build. Otherwise false is returned.
* *
* There is no way to list which filters are available in this particular * There is no way to list which filters are available in this particular
* liblzma version and build. It would be useless, because the application * liblzma version and build. It would be useless, because the application
* couldn't know what kind of options the filter would need. * couldn't know what kind of options the filter would need.
*/ */
extern LZMA_API(lzma_bool) lzma_filter_encoder_is_supported(lzma_vli id); extern LZMA_API(lzma_bool) lzma_filter_encoder_is_supported(lzma_vli id)
lzma_nothrow lzma_attr_const;
/** /**
* \brief Test if the given Filter ID is supported for decoding * \brief Test if the given Filter ID is supported for decoding
* *
* Returns true if the give Filter ID is supported for decoding by this * Return true if the give Filter ID is supported for decoding by this
* liblzma build. Otherwise false is returned. * liblzma build. Otherwise false is returned.
*/ */
extern LZMA_API(lzma_bool) lzma_filter_decoder_is_supported(lzma_vli id); extern LZMA_API(lzma_bool) lzma_filter_decoder_is_supported(lzma_vli id)
lzma_nothrow lzma_attr_const;
/** /**
* \brief Calculate rough memory requirements for raw encoder * \brief Calculate rough memory requirements for raw encoder
* *
* Because the calculation is rough, this function can be used to calculate
* the memory requirements for Block and Stream encoders too.
*
* \param filters Array of filters terminated with * \param filters Array of filters terminated with
* .id == LZMA_VLI_UNKNOWN. * .id == LZMA_VLI_UNKNOWN.
* *
* \return Rough number of bytes required for the given filter chain * \return Rough number of bytes of memory required for the given
* when encoding. * filter chain when encoding.
*/ */
extern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters) extern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/** /**
* \brief Calculate rough memory requirements for raw decoder * \brief Calculate rough memory requirements for raw decoder
* *
* Because the calculation is rough, this function can be used to calculate
* the memory requirements for Block and Stream decoders too.
*
* \param filters Array of filters terminated with * \param filters Array of filters terminated with
* .id == LZMA_VLI_UNKNOWN. * .id == LZMA_VLI_UNKNOWN.
* *
* \return Rough number of bytes required for the given filter chain * \return Rough number of bytes of memory required for the given
* when decoding. * filter chain when decoding.
*/ */
extern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters) extern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/** /**
@ -121,10 +132,8 @@ extern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters)
* This function may be useful when implementing custom file formats. * This function may be useful when implementing custom file formats.
* *
* \param strm Pointer to properly prepared lzma_stream * \param strm Pointer to properly prepared lzma_stream
* \param filters Array of lzma_filter structures. * \param filters Array of lzma_filter structures. The end of the
* The end of the array must be marked with * array must be marked with .id = LZMA_VLI_UNKNOWN.
* .id = LZMA_VLI_UNKNOWN. The minimum
* number of filters is one and the maximum is four.
* *
* The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the
* filter chain supports it), or LZMA_FINISH. * filter chain supports it), or LZMA_FINISH.
@ -136,7 +145,7 @@ extern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters)
*/ */
extern LZMA_API(lzma_ret) lzma_raw_encoder( extern LZMA_API(lzma_ret) lzma_raw_encoder(
lzma_stream *strm, const lzma_filter *filters) lzma_stream *strm, const lzma_filter *filters)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -154,12 +163,14 @@ extern LZMA_API(lzma_ret) lzma_raw_encoder(
*/ */
extern LZMA_API(lzma_ret) lzma_raw_decoder( extern LZMA_API(lzma_ret) lzma_raw_decoder(
lzma_stream *strm, const lzma_filter *filters) lzma_stream *strm, const lzma_filter *filters)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
* \brief Single-call raw encoder * \brief Single-call raw encoder
* *
* \param filters Array of lzma_filter structures. The end of the
* array must be marked with .id = LZMA_VLI_UNKNOWN.
* \param allocator lzma_allocator for custom allocator functions. * \param allocator lzma_allocator for custom allocator functions.
* Set to NULL to use malloc() and free(). * Set to NULL to use malloc() and free().
* \param in Beginning of the input buffer * \param in Beginning of the input buffer
@ -176,16 +187,22 @@ extern LZMA_API(lzma_ret) lzma_raw_decoder(
* - LZMA_MEM_ERROR * - LZMA_MEM_ERROR
* - LZMA_DATA_ERROR * - LZMA_DATA_ERROR
* - LZMA_PROG_ERROR * - LZMA_PROG_ERROR
*
* \note There is no function to calculate how big output buffer
* would surely be big enough. (lzma_stream_buffer_bound()
* works only for lzma_stream_buffer_encode().)
*/ */
extern LZMA_API(lzma_ret) lzma_raw_buffer_encode( extern LZMA_API(lzma_ret) lzma_raw_buffer_encode(
const lzma_filter *filters, lzma_allocator *allocator, const lzma_filter *filters, lzma_allocator *allocator,
const uint8_t *in, size_t in_size, uint8_t *out, const uint8_t *in, size_t in_size, uint8_t *out,
size_t *out_pos, size_t out_size); size_t *out_pos, size_t out_size) lzma_nothrow;
/** /**
* \brief Single-call raw decoder * \brief Single-call raw decoder
* *
* \param filters Array of lzma_filter structures. The end of the
* array must be marked with .id = LZMA_VLI_UNKNOWN.
* \param allocator lzma_allocator for custom allocator functions. * \param allocator lzma_allocator for custom allocator functions.
* Set to NULL to use malloc() and free(). * Set to NULL to use malloc() and free().
* \param in Beginning of the input buffer * \param in Beginning of the input buffer
@ -202,7 +219,7 @@ extern LZMA_API(lzma_ret) lzma_raw_buffer_encode(
extern LZMA_API(lzma_ret) lzma_raw_buffer_decode( extern LZMA_API(lzma_ret) lzma_raw_buffer_decode(
const lzma_filter *filters, lzma_allocator *allocator, const lzma_filter *filters, lzma_allocator *allocator,
const uint8_t *in, size_t *in_pos, size_t in_size, const uint8_t *in, size_t *in_pos, size_t in_size,
uint8_t *out, size_t *out_pos, size_t out_size); uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow;
/** /**
@ -225,7 +242,7 @@ extern LZMA_API(lzma_ret) lzma_raw_buffer_decode(
* lzma_properties_encode() returns LZMA_OPTIONS_ERROR. * lzma_properties_encode() returns LZMA_OPTIONS_ERROR.
*/ */
extern LZMA_API(lzma_ret) lzma_properties_size( extern LZMA_API(lzma_ret) lzma_properties_size(
uint32_t *size, const lzma_filter *filter); uint32_t *size, const lzma_filter *filter) lzma_nothrow;
/** /**
@ -250,7 +267,7 @@ extern LZMA_API(lzma_ret) lzma_properties_size(
* of the Filter Properties field is zero. * of the Filter Properties field is zero.
*/ */
extern LZMA_API(lzma_ret) lzma_properties_encode( extern LZMA_API(lzma_ret) lzma_properties_encode(
const lzma_filter *filter, uint8_t *props); const lzma_filter *filter, uint8_t *props) lzma_nothrow;
/** /**
@ -276,7 +293,7 @@ extern LZMA_API(lzma_ret) lzma_properties_encode(
*/ */
extern LZMA_API(lzma_ret) lzma_properties_decode( extern LZMA_API(lzma_ret) lzma_properties_decode(
lzma_filter *filter, lzma_allocator *allocator, lzma_filter *filter, lzma_allocator *allocator,
const uint8_t *props, size_t props_size); const uint8_t *props, size_t props_size) lzma_nothrow;
/** /**
@ -300,7 +317,7 @@ extern LZMA_API(lzma_ret) lzma_properties_decode(
*/ */
extern LZMA_API(lzma_ret) lzma_filter_flags_size( extern LZMA_API(lzma_ret) lzma_filter_flags_size(
uint32_t *size, const lzma_filter *filters) uint32_t *size, const lzma_filter *filters)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -323,7 +340,7 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_size(
*/ */
extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters, extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters,
uint8_t *out, size_t *out_pos, size_t out_size) uint8_t *out, size_t *out_pos, size_t out_size)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -340,4 +357,4 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters,
extern LZMA_API(lzma_ret) lzma_filter_flags_decode( extern LZMA_API(lzma_ret) lzma_filter_flags_decode(
lzma_filter *filters, lzma_allocator *allocator, lzma_filter *filters, lzma_allocator *allocator,
const uint8_t *in, size_t *in_pos, size_t in_size) const uint8_t *in, size_t *in_pos, size_t in_size)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;

97
src/liblzma/api/lzma/index.h
View file

@ -50,14 +50,24 @@ typedef struct {
lzma_vli uncompressed_size; lzma_vli uncompressed_size;
/** /**
* Offset of the first byte of a Block relative to the beginning * \brief Compressed offset in the Stream(s)
* of the Stream, or if there are multiple Indexes combined, *
* relative to the beginning of the first Stream. * This is the offset of the first byte of the Block, that is,
* where you need to seek to decode the Block. The offset
* is relative to the beginning of the Stream, or if there are
* multiple Indexes combined, relative to the beginning of the
* first Stream.
*/ */
lzma_vli stream_offset; lzma_vli stream_offset;
/** /**
* Uncompressed offset * \brief Uncompressed offset
*
* When doing random-access reading, it is possible that the target
* offset is not exactly at Block boundary. One will need to compare
* the target offset against uncompressed_offset, and possibly decode
* and throw away some amount of data before reaching the target
* offset.
*/ */
lzma_vli uncompressed_offset; lzma_vli uncompressed_offset;
@ -80,7 +90,8 @@ typedef struct {
* If you want to know how much memory an existing lzma_index structure is * If you want to know how much memory an existing lzma_index structure is
* using, use lzma_index_memusage(lzma_index_count(i)). * using, use lzma_index_memusage(lzma_index_count(i)).
*/ */
extern LZMA_API(uint64_t) lzma_index_memusage(lzma_vli record_count); extern LZMA_API(uint64_t) lzma_index_memusage(lzma_vli record_count)
lzma_nothrow;
/** /**
@ -94,8 +105,7 @@ extern LZMA_API(uint64_t) lzma_index_memusage(lzma_vli record_count);
* the i that was given as an argument. * the i that was given as an argument.
*/ */
extern LZMA_API(lzma_index *) lzma_index_init( extern LZMA_API(lzma_index *) lzma_index_init(
lzma_index *i, lzma_allocator *allocator) lzma_index *i, lzma_allocator *allocator) lzma_nothrow;
lzma_attr_warn_unused_result;
/** /**
@ -103,7 +113,8 @@ extern LZMA_API(lzma_index *) lzma_index_init(
* *
* If i is NULL, this does nothing. * If i is NULL, this does nothing.
*/ */
extern LZMA_API(void) lzma_index_end(lzma_index *i, lzma_allocator *allocator); extern LZMA_API(void) lzma_index_end(lzma_index *i, lzma_allocator *allocator)
lzma_nothrow;
/** /**
@ -130,13 +141,14 @@ extern LZMA_API(void) lzma_index_end(lzma_index *i, lzma_allocator *allocator);
extern LZMA_API(lzma_ret) lzma_index_append( extern LZMA_API(lzma_ret) lzma_index_append(
lzma_index *i, lzma_allocator *allocator, lzma_index *i, lzma_allocator *allocator,
lzma_vli unpadded_size, lzma_vli uncompressed_size) lzma_vli unpadded_size, lzma_vli uncompressed_size)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
* \brief Get the number of Records * \brief Get the number of Records
*/ */
extern LZMA_API(lzma_vli) lzma_index_count(const lzma_index *i) lzma_attr_pure; extern LZMA_API(lzma_vli) lzma_index_count(const lzma_index *i)
lzma_nothrow lzma_attr_pure;
/** /**
@ -144,7 +156,8 @@ extern LZMA_API(lzma_vli) lzma_index_count(const lzma_index *i) lzma_attr_pure;
* *
* This is needed to verify the Backward Size field in the Stream Footer. * This is needed to verify the Backward Size field in the Stream Footer.
*/ */
extern LZMA_API(lzma_vli) lzma_index_size(const lzma_index *i) lzma_attr_pure; extern LZMA_API(lzma_vli) lzma_index_size(const lzma_index *i)
lzma_nothrow lzma_attr_pure;
/** /**
@ -154,7 +167,7 @@ extern LZMA_API(lzma_vli) lzma_index_size(const lzma_index *i) lzma_attr_pure;
* or Index fields. * or Index fields.
*/ */
extern LZMA_API(lzma_vli) lzma_index_total_size(const lzma_index *i) extern LZMA_API(lzma_vli) lzma_index_total_size(const lzma_index *i)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/** /**
@ -164,7 +177,7 @@ extern LZMA_API(lzma_vli) lzma_index_total_size(const lzma_index *i)
* were in a single Stream. * were in a single Stream.
*/ */
extern LZMA_API(lzma_vli) lzma_index_stream_size(const lzma_index *i) extern LZMA_API(lzma_vli) lzma_index_stream_size(const lzma_index *i)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/** /**
@ -176,14 +189,14 @@ extern LZMA_API(lzma_vli) lzma_index_stream_size(const lzma_index *i)
* possible Stream Padding fields. * possible Stream Padding fields.
*/ */
extern LZMA_API(lzma_vli) lzma_index_file_size(const lzma_index *i) extern LZMA_API(lzma_vli) lzma_index_file_size(const lzma_index *i)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/** /**
* \brief Get the uncompressed size of the Stream * \brief Get the uncompressed size of the Stream
*/ */
extern LZMA_API(lzma_vli) lzma_index_uncompressed_size(const lzma_index *i) extern LZMA_API(lzma_vli) lzma_index_uncompressed_size(const lzma_index *i)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/** /**
@ -191,7 +204,7 @@ extern LZMA_API(lzma_vli) lzma_index_uncompressed_size(const lzma_index *i)
*/ */
extern LZMA_API(lzma_bool) lzma_index_read( extern LZMA_API(lzma_bool) lzma_index_read(
lzma_index *i, lzma_index_record *record) lzma_index *i, lzma_index_record *record)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -200,7 +213,7 @@ extern LZMA_API(lzma_bool) lzma_index_read(
* Rewind the Index so that next call to lzma_index_read() will return the * Rewind the Index so that next call to lzma_index_read() will return the
* first Record. * first Record.
*/ */
extern LZMA_API(void) lzma_index_rewind(lzma_index *i); extern LZMA_API(void) lzma_index_rewind(lzma_index *i) lzma_nothrow;
/** /**
@ -227,25 +240,27 @@ extern LZMA_API(void) lzma_index_rewind(lzma_index *i);
*/ */
extern LZMA_API(lzma_bool) lzma_index_locate( extern LZMA_API(lzma_bool) lzma_index_locate(
lzma_index *i, lzma_index_record *record, lzma_vli target) lzma_index *i, lzma_index_record *record, lzma_vli target)
lzma_attr_warn_unused_result; lzma_nothrow;
/** /**
* \brief Concatenate Indexes of two Streams * \brief Concatenate Indexes of two Streams
* *
* * Concatenating Indexes is useful when doing random-access reading in
* multi-Stream .xz file, or when combining multiple Streams into single
* Stream.
* *
* \param dest Destination Index after which src is appended * \param dest Destination Index after which src is appended
* \param src Source Index. The memory allocated for this is * \param src Source Index. If this function succeeds, the
* either moved to be part of *dest or freed if and * memory allocated for src is freed or moved to
* only if the function call succeeds, and src will * be part of dest.
* be an invalid pointer.
* \param allocator Custom memory allocator; can be NULL to use * \param allocator Custom memory allocator; can be NULL to use
* malloc() and free(). * malloc() and free().
* \param padding Size of the Stream Padding field between Streams. * \param padding Size of the Stream Padding field between Streams.
* This must be a multiple of four. * This must be a multiple of four.
* *
* \return - LZMA_OK: Indexes concatenated successfully. * \return - LZMA_OK: Indexes concatenated successfully. src is now
* a dangling pointer.
* - LZMA_DATA_ERROR: *dest would grow too big. * - LZMA_DATA_ERROR: *dest would grow too big.
* - LZMA_MEM_ERROR * - LZMA_MEM_ERROR
* - LZMA_PROG_ERROR * - LZMA_PROG_ERROR
@ -253,7 +268,7 @@ extern LZMA_API(lzma_bool) lzma_index_locate(
extern LZMA_API(lzma_ret) lzma_index_cat(lzma_index *lzma_restrict dest, extern LZMA_API(lzma_ret) lzma_index_cat(lzma_index *lzma_restrict dest,
lzma_index *lzma_restrict src, lzma_index *lzma_restrict src,
lzma_allocator *allocator, lzma_vli padding) lzma_allocator *allocator, lzma_vli padding)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -265,21 +280,23 @@ extern LZMA_API(lzma_ret) lzma_index_cat(lzma_index *lzma_restrict dest,
*/ */
extern LZMA_API(lzma_index *) lzma_index_dup( extern LZMA_API(lzma_index *) lzma_index_dup(
const lzma_index *i, lzma_allocator *allocator) const lzma_index *i, lzma_allocator *allocator)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
* \brief Compare if two Index lists are identical * \brief Compare if two Index lists are identical
* *
* Read positions are not compared.
*
* \return True if *a and *b are equal, false otherwise. * \return True if *a and *b are equal, false otherwise.
*/ */
extern LZMA_API(lzma_bool) lzma_index_equal( extern LZMA_API(lzma_bool) lzma_index_equal(
const lzma_index *a, const lzma_index *b) const lzma_index *a, const lzma_index *b)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;
/** /**
* \brief Initialize Index encoder * \brief Initialize .xz Index encoder
* *
* \param strm Pointer to properly prepared lzma_stream * \param strm Pointer to properly prepared lzma_stream
* \param i Pointer to lzma_index which should be encoded. * \param i Pointer to lzma_index which should be encoded.
@ -293,11 +310,11 @@ extern LZMA_API(lzma_bool) lzma_index_equal(
* - LZMA_PROG_ERROR * - LZMA_PROG_ERROR
*/ */
extern LZMA_API(lzma_ret) lzma_index_encoder(lzma_stream *strm, lzma_index *i) extern LZMA_API(lzma_ret) lzma_index_encoder(lzma_stream *strm, lzma_index *i)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
* \brief Initialize Index decoder * \brief Initialize .xz Index decoder
* *
* \param strm Pointer to properly prepared lzma_stream * \param strm Pointer to properly prepared lzma_stream
* \param i Pointer to a pointer that will be made to point * \param i Pointer to a pointer that will be made to point
@ -319,16 +336,17 @@ extern LZMA_API(lzma_ret) lzma_index_encoder(lzma_stream *strm, lzma_index *i)
* \note The memory usage limit is checked early in the decoding * \note The memory usage limit is checked early in the decoding
* (within the first dozen input bytes or so). The actual memory * (within the first dozen input bytes or so). The actual memory
* is allocated later in smaller pieces. If the memory usage * is allocated later in smaller pieces. If the memory usage
* limit is modified after decoding a part of the Index already, * limit is modified with lzma_memlimit_set() after a part
* the new limit may be ignored. * of the Index has already been decoded, the new limit may
* get ignored.
*/ */
extern LZMA_API(lzma_ret) lzma_index_decoder( extern LZMA_API(lzma_ret) lzma_index_decoder(
lzma_stream *strm, lzma_index **i, uint64_t memlimit) lzma_stream *strm, lzma_index **i, uint64_t memlimit)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
* \brief Single-call Index encoder * \brief Single-call .xz Index encoder
* *
* \param i Index to be encoded. The read position will be at * \param i Index to be encoded. The read position will be at
* the end of the Index if encoding succeeds, or at * the end of the Index if encoding succeeds, or at
@ -349,11 +367,11 @@ extern LZMA_API(lzma_ret) lzma_index_decoder(
* the internal data is allocated on stack. * the internal data is allocated on stack.
*/ */
extern LZMA_API(lzma_ret) lzma_index_buffer_encode(lzma_index *i, extern LZMA_API(lzma_ret) lzma_index_buffer_encode(lzma_index *i,
uint8_t *out, size_t *out_pos, size_t out_size); uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow;
/** /**
* \brief Single-call Index decoder * \brief Single-call .xz Index decoder
* *
* \param i Pointer to a pointer that will be made to point * \param i Pointer to a pointer that will be made to point
* to the final decoded Index if decoding is * to the final decoded Index if decoding is
@ -379,6 +397,7 @@ extern LZMA_API(lzma_ret) lzma_index_buffer_encode(lzma_index *i,
* - LZMA_DATA_ERROR * - LZMA_DATA_ERROR
* - LZMA_PROG_ERROR * - LZMA_PROG_ERROR
*/ */
extern LZMA_API(lzma_ret) lzma_index_buffer_decode( extern LZMA_API(lzma_ret) lzma_index_buffer_decode(lzma_index **i,
lzma_index **i, uint64_t *memlimit, lzma_allocator *allocator, uint64_t *memlimit, lzma_allocator *allocator,
const uint8_t *in, size_t *in_pos, size_t in_size); const uint8_t *in, size_t *in_pos, size_t in_size)
lzma_nothrow;

14
src/liblzma/api/lzma/index_hash.h
View file

@ -1,6 +1,9 @@
/** /**
* \file lzma/index_hash.h * \file lzma/index_hash.h
* \brief Validates Index by using a hash function * \brief Validates Index by using a hash function
*
* Hashing makes it possible to use constant amount of memory to validate
* Index of arbitrary size.
*/ */
/* /*
@ -35,14 +38,15 @@ typedef struct lzma_index_hash_s lzma_index_hash;
*/ */
extern LZMA_API(lzma_index_hash *) lzma_index_hash_init( extern LZMA_API(lzma_index_hash *) lzma_index_hash_init(
lzma_index_hash *index_hash, lzma_allocator *allocator) lzma_index_hash *index_hash, lzma_allocator *allocator)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
* \brief Deallocate lzma_index_hash structure * \brief Deallocate lzma_index_hash structure
*/ */
extern LZMA_API(void) lzma_index_hash_end( extern LZMA_API(void) lzma_index_hash_end(
lzma_index_hash *index_hash, lzma_allocator *allocator); lzma_index_hash *index_hash, lzma_allocator *allocator)
lzma_nothrow;
/** /**
@ -60,7 +64,7 @@ extern LZMA_API(void) lzma_index_hash_end(
*/ */
extern LZMA_API(lzma_ret) lzma_index_hash_append(lzma_index_hash *index_hash, extern LZMA_API(lzma_ret) lzma_index_hash_append(lzma_index_hash *index_hash,
lzma_vli unpadded_size, lzma_vli uncompressed_size) lzma_vli unpadded_size, lzma_vli uncompressed_size)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -90,7 +94,7 @@ extern LZMA_API(lzma_ret) lzma_index_hash_append(lzma_index_hash *index_hash,
*/ */
extern LZMA_API(lzma_ret) lzma_index_hash_decode(lzma_index_hash *index_hash, extern LZMA_API(lzma_ret) lzma_index_hash_decode(lzma_index_hash *index_hash,
const uint8_t *in, size_t *in_pos, size_t in_size) const uint8_t *in, size_t *in_pos, size_t in_size)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -100,4 +104,4 @@ extern LZMA_API(lzma_ret) lzma_index_hash_decode(lzma_index_hash *index_hash,
*/ */
extern LZMA_API(lzma_vli) lzma_index_hash_size( extern LZMA_API(lzma_vli) lzma_index_hash_size(
const lzma_index_hash *index_hash) const lzma_index_hash *index_hash)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;

87
src/liblzma/api/lzma/lzma.h
View file

@ -20,9 +20,12 @@
/** /**
* \brief LZMA1 Filter ID * \brief LZMA1 Filter ID
* *
* LZMA1 is the very same thing as what was called just LZMA in earlier * LZMA1 is the very same thing as what was called just LZMA in LZMA Utils,
* LZMA Utils, 7-Zip, and LZMA SDK. It's called LZMA1 here to prevent * 7-Zip, and LZMA SDK. It's called LZMA1 here to prevent developers from
* developers from accidentally using LZMA when they actually want LZMA2. * accidentally using LZMA when they actually want LZMA2.
*
* LZMA1 shouldn't be used for new applications unless you _really_ know
* what you are doing. LZMA2 is almost always a better choice.
*/ */
#define LZMA_FILTER_LZMA1 LZMA_VLI_C(0x4000000000000001) #define LZMA_FILTER_LZMA1 LZMA_VLI_C(0x4000000000000001)
@ -30,9 +33,9 @@
* \brief LZMA2 Filter ID * \brief LZMA2 Filter ID
* *
* Usually you want this instead of LZMA1. Compared to LZMA1, LZMA2 adds * Usually you want this instead of LZMA1. Compared to LZMA1, LZMA2 adds
* support for LZMA_SYNC_FLUSH, uncompressed chunks (expands uncompressible * support for LZMA_SYNC_FLUSH, uncompressed chunks (smaller expansion
* data less), possibility to change lc/lp/pb in the middle of encoding, and * when trying to compress uncompressible data), possibility to change
* some other internal improvements. * lc/lp/pb in the middle of encoding, and some other internal improvements.
*/ */
#define LZMA_FILTER_LZMA2 LZMA_VLI_C(0x21) #define LZMA_FILTER_LZMA2 LZMA_VLI_C(0x21)
@ -103,7 +106,7 @@ typedef enum {
/** /**
* \brief Test if given match finder is supported * \brief Test if given match finder is supported
* *
* Returns true if the given match finder is supported by this liblzma build. * Return true if the given match finder is supported by this liblzma build.
* Otherwise false is returned. It is safe to call this with a value that * Otherwise false is returned. It is safe to call this with a value that
* isn't listed in lzma_match_finder enumeration; the return value will be * isn't listed in lzma_match_finder enumeration; the return value will be
* false. * false.
@ -115,11 +118,11 @@ typedef enum {
* match finders don't need. * match finders don't need.
*/ */
extern LZMA_API(lzma_bool) lzma_mf_is_supported(lzma_match_finder match_finder) extern LZMA_API(lzma_bool) lzma_mf_is_supported(lzma_match_finder match_finder)
lzma_attr_const; lzma_nothrow lzma_attr_const;
/** /**
* \brief LZMA compression modes * \brief Compression modes
* *
* This selects the function used to analyze the data produced by the match * This selects the function used to analyze the data produced by the match
* finder. * finder.
@ -139,7 +142,7 @@ typedef enum {
* *
* This is usually notably slower than fast mode. Use this * This is usually notably slower than fast mode. Use this
* together with binary tree match finders to expose the * together with binary tree match finders to expose the
* full potential of the LZMA encoder. * full potential of the LZMA1 or LZMA2 encoder.
*/ */
} lzma_mode; } lzma_mode;
@ -147,7 +150,7 @@ typedef enum {
/** /**
* \brief Test if given compression mode is supported * \brief Test if given compression mode is supported
* *
* Returns true if the given compression mode is supported by this liblzma * Return true if the given compression mode is supported by this liblzma
* build. Otherwise false is returned. It is safe to call this with a value * build. Otherwise false is returned. It is safe to call this with a value
* that isn't listed in lzma_mode enumeration; the return value will be false. * that isn't listed in lzma_mode enumeration; the return value will be false.
* *
@ -157,7 +160,7 @@ typedef enum {
* additional options to the encoder that the older modes don't need. * additional options to the encoder that the older modes don't need.
*/ */
extern LZMA_API(lzma_bool) lzma_mode_is_supported(lzma_mode mode) extern LZMA_API(lzma_bool) lzma_mode_is_supported(lzma_mode mode)
lzma_attr_const; lzma_nothrow lzma_attr_const;
/** /**
@ -178,7 +181,8 @@ typedef struct {
* uncompressed data is kept in memory. One method to reduce size of * uncompressed data is kept in memory. One method to reduce size of
* the uncompressed data is to store distance-length pairs, which * the uncompressed data is to store distance-length pairs, which
* indicate what data to repeat from the dictionary buffer. Thus, * indicate what data to repeat from the dictionary buffer. Thus,
* the bigger the dictionary, the better compression ratio usually is. * the bigger the dictionary, the better the compression ratio
* usually is.
* *
* Maximum size of the dictionary depends on multiple things: * Maximum size of the dictionary depends on multiple things:
* - Memory usage limit * - Memory usage limit
@ -187,9 +191,9 @@ typedef struct {
* *
* Currently the maximum dictionary size for encoding is 1.5 GiB * Currently the maximum dictionary size for encoding is 1.5 GiB
* (i.e. (UINT32_C(1) << 30) + (UINT32_C(1) << 29)) even on 64-bit * (i.e. (UINT32_C(1) << 30) + (UINT32_C(1) << 29)) even on 64-bit
* systems for certain match finder implementation reasons. In future, * systems for certain match finder implementation reasons. In the
* there may be match finders that support bigger dictionaries (3 GiB * future, there may be match finders that support bigger
* will probably be the maximum). * dictionaries.
* *
* Decoder already supports dictionaries up to 4 GiB - 1 B (i.e. * Decoder already supports dictionaries up to 4 GiB - 1 B (i.e.
* UINT32_MAX), so increasing the maximum dictionary size of the * UINT32_MAX), so increasing the maximum dictionary size of the
@ -209,26 +213,20 @@ typedef struct {
* \brief Pointer to an initial dictionary * \brief Pointer to an initial dictionary
* *
* It is possible to initialize the LZ77 history window using * It is possible to initialize the LZ77 history window using
* a preset dictionary. Here is a good quote from zlib's * a preset dictionary. It is useful when compressing many
* documentation; this applies to LZMA as is: * similar, relatively small chunks of data independently from
* each other. The preset dictionary should contain typical
* strings that occur in the files being compressed. The most
* probable strings should be near the end of the preset dictionary.
* *
* "The dictionary should consist of strings (byte sequences) that * This feature should be used only in special situations. For
* are likely to be encountered later in the data to be compressed, * now, it works correctly only with raw encoding and decoding.
* with the most commonly used strings preferably put towards the
* end of the dictionary. Using a dictionary is most useful when
* the data to be compressed is short and can be predicted with
* good accuracy; the data can then be compressed better than
* with the default empty dictionary."
* (From deflateSetDictionary() in zlib.h of zlib version 1.2.3)
*
* This feature should be used only in special situations.
* It works correctly only with raw encoding and decoding.
* Currently none of the container formats supported by * Currently none of the container formats supported by
* liblzma allow preset dictionary when decoding, thus if * liblzma allow preset dictionary when decoding, thus if
* you create a .lzma file with preset dictionary, it cannot * you create a .xz or .lzma file with preset dictionary, it
* be decoded with the regular .lzma decoder functions. * cannot be decoded with the regular decoder functions. In the
* * future, the .xz format will likely get support for preset
* \todo This feature is not implemented yet. * dictionary though.
*/ */
const uint8_t *preset_dict; const uint8_t *preset_dict;
@ -236,9 +234,13 @@ typedef struct {
* \brief Size of the preset dictionary * \brief Size of the preset dictionary
* *
* Specifies the size of the preset dictionary. If the size is * Specifies the size of the preset dictionary. If the size is
* bigger than dict_size, only the last dict_size bytes are processed. * bigger than dict_size, only the last dict_size bytes are
* processed.
* *
* This variable is read only when preset_dict is not NULL. * This variable is read only when preset_dict is not NULL.
* If preset_dict is not NULL but preset_dict_size is zero,
* no preset dictionary is used (identical to only setting
* preset_dict to NULL).
*/ */
uint32_t preset_dict_size; uint32_t preset_dict_size;
@ -257,9 +259,9 @@ typedef struct {
* results in some cases like email servers doing virus scanning. * results in some cases like email servers doing virus scanning.
* This limit also simplifies the internal implementation in liblzma. * This limit also simplifies the internal implementation in liblzma.
* *
* There may be LZMA streams that have lc + lp > 4 (maximum lc * There may be LZMA1 streams that have lc + lp > 4 (maximum possible
* possible would be 8). It is not possible to decode such streams * lc would be 8). It is not possible to decode such streams with
* with liblzma. * liblzma.
*/ */
uint32_t lc; uint32_t lc;
# define LZMA_LCLP_MIN 0 # define LZMA_LCLP_MIN 0
@ -309,7 +311,7 @@ typedef struct {
*/ */
lzma_bool persistent; lzma_bool persistent;
/** LZMA compression mode */ /** Compression mode */
lzma_mode mode; lzma_mode mode;
/** /**
@ -323,11 +325,12 @@ typedef struct {
* encoded; it's not truncated to nice_len.) * encoded; it's not truncated to nice_len.)
* *
* Bigger values usually increase the compression ratio and * Bigger values usually increase the compression ratio and
* compression time. For most files, 30 to 100 is a good value, * compression time. For most files, 32 to 128 is a good value,
* which gives very good compression ratio at good speed. * which gives very good compression ratio at good speed.
* *
* The exact minimum value depends on the match finder. The maximum is * The exact minimum value depends on the match finder. The maximum
* 273, which is the maximum length of a match that LZMA can encode. * is 273, which is the maximum length of a match that LZMA1 and
* LZMA2 can encode.
*/ */
uint32_t nice_len; uint32_t nice_len;
@ -404,4 +407,4 @@ typedef struct {
* when building liblzma. * when building liblzma.
*/ */
extern LZMA_API(lzma_bool) lzma_lzma_preset( extern LZMA_API(lzma_bool) lzma_lzma_preset(
lzma_options_lzma *options, uint32_t preset); lzma_options_lzma *options, uint32_t preset) lzma_nothrow;

12
src/liblzma/api/lzma/stream_flags.h
View file

@ -28,7 +28,7 @@
/** /**
* Options for encoding and decoding Stream Header and Stream Footer * \brief Options for encoding/decoding Stream Header and Stream Footer
*/ */
typedef struct { typedef struct {
/** /**
@ -125,7 +125,7 @@ typedef struct {
*/ */
extern LZMA_API(lzma_ret) lzma_stream_header_encode( extern LZMA_API(lzma_ret) lzma_stream_header_encode(
const lzma_stream_flags *options, uint8_t *out) const lzma_stream_flags *options, uint8_t *out)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -142,7 +142,7 @@ extern LZMA_API(lzma_ret) lzma_stream_header_encode(
*/ */
extern LZMA_API(lzma_ret) lzma_stream_footer_encode( extern LZMA_API(lzma_ret) lzma_stream_footer_encode(
const lzma_stream_flags *options, uint8_t *out) const lzma_stream_flags *options, uint8_t *out)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -177,7 +177,7 @@ extern LZMA_API(lzma_ret) lzma_stream_footer_encode(
*/ */
extern LZMA_API(lzma_ret) lzma_stream_header_decode( extern LZMA_API(lzma_ret) lzma_stream_header_decode(
lzma_stream_flags *options, const uint8_t *in) lzma_stream_flags *options, const uint8_t *in)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -204,7 +204,7 @@ extern LZMA_API(lzma_ret) lzma_stream_header_decode(
*/ */
extern LZMA_API(lzma_ret) lzma_stream_footer_decode( extern LZMA_API(lzma_ret) lzma_stream_footer_decode(
lzma_stream_flags *options, const uint8_t *in) lzma_stream_flags *options, const uint8_t *in)
lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
/** /**
@ -224,4 +224,4 @@ extern LZMA_API(lzma_ret) lzma_stream_footer_decode(
*/ */
extern LZMA_API(lzma_ret) lzma_stream_flags_compare( extern LZMA_API(lzma_ret) lzma_stream_flags_compare(
const lzma_stream_flags *a, const lzma_stream_flags *b) const lzma_stream_flags *a, const lzma_stream_flags *b)
lzma_attr_pure; lzma_nothrow lzma_attr_pure;

10
src/liblzma/api/lzma/version.h
View file

@ -95,17 +95,18 @@
LZMA_VERSION_COMMIT) LZMA_VERSION_COMMIT)
/* #ifndef is needed for use with MinGW's windres. */ /* #ifndef is needed for use with windres (MinGW or Cygwin). */
#ifndef LZMA_H_INTERNAL_RC #ifndef LZMA_H_INTERNAL_RC
/** /**
* \brief Run-time version number as an integer * \brief Run-time version number as an integer
* *
* Returns the value of LZMA_VERSION macro at the compile time of liblzma. * Return the value of LZMA_VERSION macro at the compile time of liblzma.
* This allows the application to compare if it was built against the same, * This allows the application to compare if it was built against the same,
* older, or newer version of liblzma that is currently running. * older, or newer version of liblzma that is currently running.
*/ */
extern LZMA_API(uint32_t) lzma_version_number(void) lzma_attr_const; extern LZMA_API(uint32_t) lzma_version_number(void)
lzma_nothrow lzma_attr_const;
/** /**
@ -114,6 +115,7 @@ extern LZMA_API(uint32_t) lzma_version_number(void) lzma_attr_const;
* This function may be useful if you want to display which version of * This function may be useful if you want to display which version of
* liblzma your application is currently using. * liblzma your application is currently using.
*/ */
extern LZMA_API(const char *) lzma_version_string(void) lzma_attr_const; extern LZMA_API(const char *) lzma_version_string(void)
lzma_nothrow lzma_attr_const;
#endif #endif

7
src/liblzma/api/lzma/vli.h
View file

@ -115,7 +115,7 @@ typedef uint64_t lzma_vli;
*/ */
extern LZMA_API(lzma_ret) lzma_vli_encode(lzma_vli vli, extern LZMA_API(lzma_ret) lzma_vli_encode(lzma_vli vli,
size_t *lzma_restrict vli_pos, uint8_t *lzma_restrict out, size_t *lzma_restrict vli_pos, uint8_t *lzma_restrict out,
size_t *lzma_restrict out_pos, size_t out_size); size_t *lzma_restrict out_pos, size_t out_size) lzma_nothrow;
/** /**
@ -155,7 +155,7 @@ extern LZMA_API(lzma_ret) lzma_vli_encode(lzma_vli vli,
*/ */
extern LZMA_API(lzma_ret) lzma_vli_decode(lzma_vli *lzma_restrict vli, extern LZMA_API(lzma_ret) lzma_vli_decode(lzma_vli *lzma_restrict vli,
size_t *lzma_restrict vli_pos, const uint8_t *lzma_restrict in, size_t *lzma_restrict vli_pos, const uint8_t *lzma_restrict in,
size_t *lzma_restrict in_pos, size_t in_size); size_t *lzma_restrict in_pos, size_t in_size) lzma_nothrow;
/** /**
@ -164,4 +164,5 @@ extern LZMA_API(lzma_ret) lzma_vli_decode(lzma_vli *lzma_restrict vli,
* \return Number of bytes on success (1-9). If vli isn't valid, * \return Number of bytes on success (1-9). If vli isn't valid,
* zero is returned. * zero is returned.
*/ */
extern LZMA_API(uint32_t) lzma_vli_size(lzma_vli vli) lzma_attr_pure; extern LZMA_API(uint32_t) lzma_vli_size(lzma_vli vli)
lzma_nothrow lzma_attr_pure;