root
/
xz
mirror of https://git.tukaani.org/xz.git
1
0
Fork 0
Code Issues Releases Wiki Activity

liblzma: Update the comments in the API headers. 

Adding support for LZMA_FINISH for Index encoding and
decoding needed tiny additions to the relevant .c files too.
This commit is contained in:
Lasse Collin 2010-10-21 23:06:31 +03:00
parent 33c1c0e102
commit d09c5753e3
14 changed files with 136 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/liblzma/api/lzma.h
View File

@ -60,8 +60,8 @@
* *
* Some could argue that liblzma API should provide all the required types, * Some could argue that liblzma API should provide all the required types,
* for example lzma_uint64, LZMA_UINT64_C(n), and LZMA_UINT64_MAX. This was * for example lzma_uint64, LZMA_UINT64_C(n), and LZMA_UINT64_MAX. This was
* seen unnecessary mess, since most systems already provide all the necessary * seen as an unnecessary mess, since most systems already provide all the
* types and macros in the standard headers. * necessary types and macros in the standard headers.
* *
* Note that liblzma API still has lzma_bool, because using stdbool.h would * Note that liblzma API still has lzma_bool, because using stdbool.h would
* break C89 and C++ programs on many systems. sizeof(bool) in C99 isn't * break C89 and C++ programs on many systems. sizeof(bool) in C99 isn't

38
src/liblzma/api/lzma/base.h
View File

@ -281,21 +281,21 @@ typedef enum {
* Using LZMA_SYNC_FLUSH very often can dramatically reduce * Using LZMA_SYNC_FLUSH very often can dramatically reduce
* the compression ratio. With some filters (for example, * the compression ratio. With some filters (for example,
* LZMA2), fine-tuning the compression options may help * LZMA2), fine-tuning the compression options may help
* mitigate this problem significantly. * mitigate this problem significantly (for example,
* match finder with LZMA2).
* *
* Decoders don't support LZMA_SYNC_FLUSH. * Decoders don't support LZMA_SYNC_FLUSH.
*/ */
LZMA_FULL_FLUSH = 2, LZMA_FULL_FLUSH = 2,
/**< /**<
* \brief Make all the input available at output * \brief Finish encoding of the current Block
* *
* Finish encoding of the current Block. All the input * All the input data going to the current Block must have
* data going to the current Block must have been given * been given to the encoder (the last bytes can still be
* to the encoder (the last bytes can still be pending in * pending in* next_in). Call lzma_code() with LZMA_FULL_FLUSH
* next_in). Call lzma_code() with LZMA_FULL_FLUSH until * until it returns LZMA_STREAM_END. Then continue normally
* it returns LZMA_STREAM_END. Then continue normally with * with LZMA_RUN or finish the Stream with LZMA_FINISH.
* LZMA_RUN or finish the Stream with LZMA_FINISH.
* *
* This action is currently supported only by Stream encoder * This action is currently supported only by Stream encoder
* and easy encoder (which uses Stream encoder). If there is * and easy encoder (which uses Stream encoder). If there is
@ -306,12 +306,12 @@ typedef enum {
/**< /**<
* \brief Finish the coding operation * \brief Finish the coding operation
* *
* Finishes the coding operation. All the input data must * All the input data must have been given to the encoder
* have been given to the encoder (the last bytes can still * (the last bytes can still be pending in next_in).
* be pending in next_in). Call lzma_code() with LZMA_FINISH * Call lzma_code() with LZMA_FINISH until it returns
* until it returns LZMA_STREAM_END. Once LZMA_FINISH has * LZMA_STREAM_END. Once LZMA_FINISH has been used,
* been used, the amount of input must no longer be changed * the amount of input must no longer be changed by
* by the application. * the application.
* *
* When decoding, using LZMA_FINISH is optional unless the * When decoding, using LZMA_FINISH is optional unless the
* LZMA_CONCATENATED flag was used when the decoder was * LZMA_CONCATENATED flag was used when the decoder was
@ -554,11 +554,11 @@ extern LZMA_API(void) lzma_end(lzma_stream *strm) lzma_nothrow;
* this may give misleading information if decoding .xz Streams that have * this may give misleading information if decoding .xz Streams that have
* multiple Blocks, because each Block can have different memory requirements. * multiple Blocks, because each Block can have different memory requirements.
* *
* \return Rough estimate of how much memory is currently allocated * \return How much memory is currently allocated for the filter
* for the filter decoders. If no filter chain is currently * decoders. If no filter chain is currently allocated,
* allocated, some non-zero value is still returned, which is * some non-zero value is still returned, which is less than
* less than or equal to what any filter chain would indicate * or equal to what any filter chain would indicate as its
* as its memory requirement. * memory requirement.
* *
* 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.

4
src/liblzma/api/lzma/bcj.h
View File

@ -31,7 +31,7 @@
#define LZMA_FILTER_IA64 LZMA_VLI_C(0x06) #define LZMA_FILTER_IA64 LZMA_VLI_C(0x06)
/**< /**<
* Filter for IA64 (Itanium) binaries. * Filter for IA-64 (Itanium) binaries.
*/ */
#define LZMA_FILTER_ARM LZMA_VLI_C(0x07) #define LZMA_FILTER_ARM LZMA_VLI_C(0x07)
@ -41,7 +41,7 @@
#define LZMA_FILTER_ARMTHUMB LZMA_VLI_C(0x08) #define LZMA_FILTER_ARMTHUMB LZMA_VLI_C(0x08)
/**< /**<
* Filter for ARMThumb binaries. * Filter for ARM-Thumb binaries.
*/ */
#define LZMA_FILTER_SPARC LZMA_VLI_C(0x09) #define LZMA_FILTER_SPARC LZMA_VLI_C(0x09)

4
src/liblzma/api/lzma/block.h
View File

@ -318,8 +318,8 @@ extern LZMA_API(lzma_ret) lzma_block_header_encode(
* The size of the Block Header must have already been decoded with * The size of the Block Header must have already been decoded with
* lzma_block_header_size_decode() macro and stored to block->header_size. * lzma_block_header_size_decode() macro and stored to block->header_size.
* *
* block->filters must have been allocated, but not necessarily initialized. * block->filters must have been allocated, but they don't need to be
* Possible existing filter options are _not_ freed. * initialized (possible existing filter options are not freed).
* *
* \param block Destination for Block options. * \param block Destination for Block options.
* \param allocator lzma_allocator for custom allocator functions. * \param allocator lzma_allocator for custom allocator functions.

26
src/liblzma/api/lzma/container.h
View File

@ -55,13 +55,13 @@
* *
* 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-2). * a little but only at the lowest preset levels (0-3).
*/ */
#define LZMA_PRESET_EXTREME (UINT32_C(1) << 31) #define LZMA_PRESET_EXTREME (UINT32_C(1) << 31)
/** /**
* \brief Calculate rough memory usage of easy encoder * \brief Calculate approximate memory usage of easy encoder
* *
* This function is a wrapper for lzma_raw_encoder_memusage(). * This function is a wrapper for lzma_raw_encoder_memusage().
* *
@ -72,7 +72,7 @@ extern LZMA_API(uint64_t) lzma_easy_encoder_memusage(uint32_t preset)
/** /**
* \brief Calculate rough decoder memory usage of a preset * \brief Calculate approximate decoder memory usage of a preset
* *
* This function is a wrapper for lzma_raw_decoder_memusage(). * This function is a wrapper for lzma_raw_decoder_memusage().
* *
@ -93,16 +93,19 @@ extern LZMA_API(uint64_t) lzma_easy_decoder_memusage(uint32_t preset)
* \param preset Compression preset to use. A preset consist of level * \param preset Compression preset to use. A preset consist of level
* number and zero or more flags. Usually flags aren't * number and zero or more flags. Usually flags aren't
* used, so preset is simply a number [0, 9] which match * used, so preset is simply a number [0, 9] which match
* the options -0 .. -9 of the xz command line tool. * the options -0 ... -9 of the xz command line tool.
* Additional flags can be be set using bitwise-or with * Additional flags can be be set using bitwise-or with
* the preset level number, e.g. 6 | LZMA_PRESET_EXTREME. * the preset level number, e.g. 6 | LZMA_PRESET_EXTREME.
* \param check Integrity check type to use. See check.h for available * \param check Integrity check type to use. See check.h for available
* checks. If you are unsure, use LZMA_CHECK_CRC32. * checks. The xz command line tool defaults to
* LZMA_CHECK_CRC64, which is a good choice if you are
* unsure. LZMA_CHECK_CRC32 is good too as long as the
* uncompressed file is not many gigabytes.
* *
* \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. * - LZMA_MEM_ERROR: Memory allocation failed.
* - LZMA_OPTIONS_ERROR: The given compression level is not * - LZMA_OPTIONS_ERROR: The given compression preset 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
* supported by this liblzma build. * supported by this liblzma build.
@ -310,7 +313,8 @@ extern LZMA_API(lzma_ret) lzma_stream_buffer_encode(
* \brief Initialize .xz Stream decoder * \brief Initialize .xz Stream decoder
* *
* \param strm Pointer to properly prepared lzma_stream * \param strm Pointer to properly prepared lzma_stream
* \param memlimit Rough memory usage limit as bytes * \param memlimit Memory usage limit as bytes. Use UINT64_MAX
* to effectively disable the limiter.
* \param flags Bitwise-or of zero or more of the decoder flags: * \param flags Bitwise-or of zero or more of the decoder flags:
* LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, * LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK,
* LZMA_TELL_ANY_CHECK, LZMA_CONCATENATED * LZMA_TELL_ANY_CHECK, LZMA_CONCATENATED
@ -318,6 +322,7 @@ extern LZMA_API(lzma_ret) lzma_stream_buffer_encode(
* \return - LZMA_OK: Initialization was successful. * \return - LZMA_OK: Initialization was successful.
* - LZMA_MEM_ERROR: Cannot allocate memory. * - LZMA_MEM_ERROR: Cannot allocate memory.
* - LZMA_OPTIONS_ERROR: Unsupported flags * - LZMA_OPTIONS_ERROR: Unsupported flags
* - LZMA_PROG_ERROR
*/ */
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)
@ -332,12 +337,14 @@ extern LZMA_API(lzma_ret) lzma_stream_decoder(
* of the input file has been detected. * of the input file has been detected.
* *
* \param strm Pointer to properly prepared lzma_stream * \param strm Pointer to properly prepared lzma_stream
* \param memlimit Rough memory usage limit as bytes * \param memlimit Memory usage limit as bytes. Use UINT64_MAX
* to effectively disable the limiter.
* \param flags Bitwise-or of flags, or zero for no flags. * \param flags Bitwise-or of flags, or zero for no flags.
* *
* \return - LZMA_OK: Initialization was successful. * \return - LZMA_OK: Initialization was successful.
* - LZMA_MEM_ERROR: Cannot allocate memory. * - LZMA_MEM_ERROR: Cannot allocate memory.
* - LZMA_OPTIONS_ERROR: Unsupported flags * - LZMA_OPTIONS_ERROR: Unsupported flags
* - LZMA_PROG_ERROR
*/ */
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)
@ -353,6 +360,7 @@ extern LZMA_API(lzma_ret) lzma_auto_decoder(
* *
* \return - LZMA_OK * \return - LZMA_OK
* - LZMA_MEM_ERROR * - LZMA_MEM_ERROR
* - LZMA_PROG_ERROR
*/ */
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)
@ -379,7 +387,7 @@ extern LZMA_API(lzma_ret) lzma_alone_decoder(
* won't be read is in[in_size]. * won't be read is in[in_size].
* \param out Beginning of the output buffer * \param out Beginning of the output buffer
* \param out_pos The next byte will be written to out[*out_pos]. * \param out_pos The next byte will be written to out[*out_pos].
* *out_pos is updated only if encoding succeeds. * *out_pos is updated only if decoding succeeds.
* \param out_size Size of the out buffer; the first byte into * \param out_size Size of the out buffer; the first byte into
* which no data is written to is out[out_size]. * which no data is written to is out[out_size].
* *

51
src/liblzma/api/lzma/filter.h
View File

@ -1,6 +1,6 @@
/** /**
* \file lzma/filter.h * \file lzma/filter.h
* \brief Common filter related types * \brief Common filter related types and functions
*/ */
/* /*
@ -59,11 +59,6 @@ typedef struct {
* If the filter doesn't need options, set this to NULL. If id is * If the filter doesn't need options, set this to NULL. If id is
* set to LZMA_VLI_UNKNOWN, options is ignored, and thus * set to LZMA_VLI_UNKNOWN, options is ignored, and thus
* doesn't need be initialized. * doesn't need be initialized.
*
* Some filters support changing the options in the middle of
* the encoding process. These filters store the pointer of the
* options structure and communicate with the application via
* modifications of the options structure.
*/ */
void *options; void *options;
@ -126,15 +121,16 @@ extern LZMA_API(lzma_ret) lzma_filters_copy(const lzma_filter *src,
/** /**
* \brief Calculate rough memory requirements for raw encoder * \brief Calculate approximate memory requirements for raw encoder
* *
* Because the calculation is rough, this function can be used to calculate * This function can be used to calculate the memory requirements for
* the memory requirements for Block and Stream encoders too. * Block and Stream encoders too because Block and Stream encoders don't
* need significantly more memory than raw encoder.
* *
* \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 of memory required for the given * \return Number of bytes of memory required for the given
* filter chain 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)
@ -142,15 +138,16 @@ extern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters)
/** /**
* \brief Calculate rough memory requirements for raw decoder * \brief Calculate approximate memory requirements for raw decoder
* *
* Because the calculation is rough, this function can be used to calculate * This function can be used to calculate the memory requirements for
* the memory requirements for Block and Stream decoders too. * Block and Stream decoders too because Block and Stream decoders don't
* need significantly more memory than raw decoder.
* *
* \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 of memory required for the given * \return Number of bytes of memory required for the given
* filter chain 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)
@ -251,7 +248,8 @@ extern LZMA_API(lzma_ret) lzma_filters_update(
* *
* \note There is no function to calculate how big output buffer * \note There is no function to calculate how big output buffer
* would surely be big enough. (lzma_stream_buffer_bound() * would surely be big enough. (lzma_stream_buffer_bound()
* works only for lzma_stream_buffer_encode().) * works only for lzma_stream_buffer_encode(); raw encoder
* won't necessarily meet that bound.)
*/ */
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,
@ -323,9 +321,10 @@ extern LZMA_API(lzma_ret) lzma_properties_size(
* succeeds but using the same options to initialize the encoder * succeeds but using the same options to initialize the encoder
* will fail. * will fail.
* *
* \note It is OK to skip calling this function if * \note If lzma_properties_size() indicated that the size
* lzma_properties_size() indicated that the size * of the Filter Properties field is zero, calling
* of the Filter Properties field is zero. * lzma_properties_encode() is not required, but it
* won't do any harm either.
*/ */
extern LZMA_API(lzma_ret) lzma_properties_encode( extern LZMA_API(lzma_ret) lzma_properties_encode(
const lzma_filter *filter, uint8_t *props) lzma_nothrow; const lzma_filter *filter, uint8_t *props) lzma_nothrow;
@ -364,11 +363,11 @@ extern LZMA_API(lzma_ret) lzma_properties_decode(
* memory to hold the encoded Filter Flags. * memory to hold the encoded Filter Flags.
* *
* \param size Pointer to integer to hold the calculated size * \param size Pointer to integer to hold the calculated size
* \param filters Filter ID and associated options whose encoded * \param filter Filter ID and associated options whose encoded
* size is to be calculated * size is to be calculated
* *
* \return - LZMA_OK: *size set successfully. Note that this doesn't * \return - LZMA_OK: *size set successfully. Note that this doesn't
* guarantee that filters->options is valid, thus * guarantee that filter->options is valid, thus
* lzma_filter_flags_encode() may still fail. * lzma_filter_flags_encode() may still fail.
* - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options. * - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options.
* - LZMA_PROG_ERROR: Invalid options * - LZMA_PROG_ERROR: Invalid options
@ -377,7 +376,7 @@ extern LZMA_API(lzma_ret) lzma_properties_decode(
* you need to loop over every lzma_filter entry. * you need to loop over every lzma_filter entry.
*/ */
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 *filter)
lzma_nothrow lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
@ -387,7 +386,7 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_size(
* In contrast to some functions, this doesn't allocate the needed buffer. * In contrast to some functions, this doesn't allocate the needed buffer.
* This is due to how this function is used internally by liblzma. * This is due to how this function is used internally by liblzma.
* *
* \param filters Filter ID and options to be encoded * \param filter Filter ID and options to be encoded
* \param out Beginning of the output buffer * \param out Beginning of the output buffer
* \param out_pos out[*out_pos] is the next write position. This * \param out_pos out[*out_pos] is the next write position. This
* is updated by the encoder. * is updated by the encoder.
@ -399,7 +398,7 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_size(
* buffer space (you should have checked it with * buffer space (you should have checked it with
* lzma_filter_flags_size()). * 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 *filter,
uint8_t *out, size_t *out_pos, size_t out_size) uint8_t *out, size_t *out_pos, size_t out_size)
lzma_nothrow lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;
@ -407,8 +406,8 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters,
/** /**
* \brief Decode Filter Flags from given buffer * \brief Decode Filter Flags from given buffer
* *
* The decoded result is stored into *filters. filters->options is * The decoded result is stored into *filter. The old value of
* initialized but the old value is NOT free()d. * filter->options is not free()d.
* *
* \return - LZMA_OK * \return - LZMA_OK
* - LZMA_OPTIONS_ERROR * - LZMA_OPTIONS_ERROR
@ -416,6 +415,6 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters,
* - LZMA_PROG_ERROR * - LZMA_PROG_ERROR
*/ */
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 *filter, 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 lzma_attr_warn_unused_result; lzma_nothrow lzma_attr_warn_unused_result;

3
src/liblzma/api/lzma/hardware.h
View File

@ -39,8 +39,7 @@
* *
* This function may be useful when determining a reasonable memory * This function may be useful when determining a reasonable memory
* usage limit for decompressing or how much memory it is OK to use * usage limit for decompressing or how much memory it is OK to use
* for compressing. For example, the default limit used by the xz * for compressing.
* command line tool is 40 % of RAM.
* *
* \return On success, the total amount of physical memory in bytes * \return On success, the total amount of physical memory in bytes
* is returned. If the amount of RAM cannot be determined, * is returned. If the amount of RAM cannot be determined,

28
src/liblzma/api/lzma/index.h
View File

@ -136,6 +136,13 @@ typedef struct {
* *
* This offset is relative to the beginning of the lzma_index * This offset is relative to the beginning of the lzma_index
* (i.e. usually the beginning of the .xz file). * (i.e. usually the beginning of the .xz file).
*
* 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_file_offset or uncompressed_stream_offset,
* and possibly decode and throw away some amount of data
* before reaching the target offset.
*/ */
lzma_vli uncompressed_file_offset; lzma_vli uncompressed_file_offset;
@ -166,14 +173,8 @@ typedef struct {
* \brief Uncompressed size of this Block * \brief Uncompressed size of this Block
* *
* You should pass this to the Block decoder if you will * You should pass this to the Block decoder if you will
* decode this Block. * decode this Block. It will allow the Block decoder to
* * validate the uncompressed size.
* 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_file_offset or uncompressed_stream_offset,
* and possibly decode and throw away some amount of data
* before reaching the target offset.
*/ */
lzma_vli uncompressed_size; lzma_vli uncompressed_size;
@ -181,7 +182,8 @@ typedef struct {
* \brief Unpadded size of this Block * \brief Unpadded size of this Block
* *
* You should pass this to the Block decoder if you will * You should pass this to the Block decoder if you will
* decode this Block. * decode this Block. It will allow the Block decoder to
* validate the unpadded size.
*/ */
lzma_vli unpadded_size; lzma_vli unpadded_size;
@ -583,7 +585,9 @@ extern LZMA_API(lzma_index *) lzma_index_dup(
* \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.
* *
* The only valid action value for lzma_code() is LZMA_RUN. * The valid `action' values for lzma_code() are LZMA_RUN and LZMA_FINISH.
* It is enough to use only one of them (you can choose freely; use LZMA_RUN
* to support liblzma versions older than 5.0.0).
* *
* \return - LZMA_OK: Initialization succeeded, continue with lzma_code(). * \return - LZMA_OK: Initialization succeeded, continue with lzma_code().
* - LZMA_MEM_ERROR * - LZMA_MEM_ERROR
@ -608,7 +612,9 @@ extern LZMA_API(lzma_ret) lzma_index_encoder(
* \param memlimit How much memory the resulting lzma_index is * \param memlimit How much memory the resulting lzma_index is
* allowed to require. * allowed to require.
* *
* The only valid action value for lzma_code() is LZMA_RUN. * The valid `action' values for lzma_code() are LZMA_RUN and LZMA_FINISH.
* It is enough to use only one of them (you can choose freely; use LZMA_RUN
* to support liblzma versions older than 5.0.0).
* *
* \return - LZMA_OK: Initialization succeeded, continue with lzma_code(). * \return - LZMA_OK: Initialization succeeded, continue with lzma_code().
* - LZMA_MEM_ERROR * - LZMA_MEM_ERROR

2
src/liblzma/api/lzma/index_hash.h
View File

@ -1,6 +1,6 @@
/** /**
* \file lzma/index_hash.h * \file lzma/index_hash.h
* \brief Validates Index by using a hash function * \brief Validate Index by using a hash function
* *
* Hashing makes it possible to use constant amount of memory to validate * Hashing makes it possible to use constant amount of memory to validate
* Index of arbitrary size. * Index of arbitrary size.

46
src/liblzma/api/lzma/lzma.h
View File

@ -46,6 +46,10 @@
* Match finder has major effect on both speed and compression ratio. * Match finder has major effect on both speed and compression ratio.
* Usually hash chains are faster than binary trees. * Usually hash chains are faster than binary trees.
* *
* If you will use LZMA_SYNC_FLUSH often, the hash chains may be a better
* choice, because binary trees get much higher compression ratio penalty
* with LZMA_SYNC_FLUSH.
*
* The memory usage formulas are only rough estimates, which are closest to * The memory usage formulas are only rough estimates, which are closest to
* reality when dict_size is a power of two. The formulas are more complex * reality when dict_size is a power of two. The formulas are more complex
* in reality, and can also change a little between liblzma versions. Use * in reality, and can also change a little between liblzma versions. Use
@ -173,6 +177,7 @@ extern LZMA_API(lzma_bool) lzma_mode_is_supported(lzma_mode mode)
* Since LZMA1 and LZMA2 share most of the code, it's simplest to share * Since LZMA1 and LZMA2 share most of the code, it's simplest to share
* the options structure too. For encoding, all but the reserved variables * the options structure too. For encoding, all but the reserved variables
* need to be initialized unless specifically mentioned otherwise. * need to be initialized unless specifically mentioned otherwise.
* lzma_lzma_preset() can be used to get a good starting point.
* *
* For raw decoding, both LZMA1 and LZMA2 need dict_size, preset_dict, and * For raw decoding, both LZMA1 and LZMA2 need dict_size, preset_dict, and
* preset_dict_size (if preset_dict != NULL). LZMA1 needs also lc, lp, and pb. * preset_dict_size (if preset_dict != NULL). LZMA1 needs also lc, lp, and pb.
@ -255,7 +260,13 @@ typedef struct {
* eight-bit byte (also known as `literal') are taken into * eight-bit byte (also known as `literal') are taken into
* account when predicting the bits of the next literal. * account when predicting the bits of the next literal.
* *
* \todo Example * E.g. in typical English text, an upper-case letter is
* often followed by a lower-case letter, and a lower-case
* letter is usually followed by another lower-case letter.
* In the US-ASCII character set, the highest three bits are 010
* for upper-case letters and 011 for lower-case letters.
* When lc is at least 3, the literal coding can take advantage of
* this property in the uncompressed data.
* *
* There is a limit that applies to literal context bits and literal * There is a limit that applies to literal context bits and literal
* position bits together: lc + lp <= 4. Without this limit the * position bits together: lc + lp <= 4. Without this limit the
@ -275,12 +286,9 @@ typedef struct {
/** /**
* \brief Number of literal position bits * \brief Number of literal position bits
* *
* How many of the lowest bits of the current position (number * lp affects what kind of alignment in the uncompressed data is
* of bytes from the beginning of the uncompressed data) in the * assumed when encoding literals. A literal is a single 8-bit byte.
* uncompressed data is taken into account when predicting the * See pb below for more information about alignment.
* bits of the next literal (a single eight-bit byte).
*
* \todo Example
*/ */
uint32_t lp; uint32_t lp;
# define LZMA_LP_DEFAULT 0 # define LZMA_LP_DEFAULT 0
@ -288,14 +296,22 @@ typedef struct {
/** /**
* \brief Number of position bits * \brief Number of position bits
* *
* How many of the lowest bits of the current position in the * pb affects what kind of alignment in the uncompressed data is
* uncompressed data is taken into account when estimating * assumed in general. The default means four-byte alignment
* probabilities of matches. A match is a sequence of bytes for * (2^ pb =2^2=4), which is often a good choice when there's
* which a matching sequence is found from the dictionary and * no better guess.
* thus can be stored as distance-length pair.
* *
* Example: If most of the matches occur at byte positions of * When the aligment is known, setting pb accordingly may reduce
* 8 * n + 3, that is, 3, 11, 19, ... set pb to 3, because 2**3 == 8. * the file size a little. E.g. with text files having one-byte
* alignment (US-ASCII, ISO-8859-*, UTF-8), setting pb=0 can
* improve compression slightly. For UTF-16 text, pb=1 is a good
* choice. If the alignment is an odd number like 3 bytes, pb=0
* might be the best choice.
*
* Even though the assumed alignment can be adjusted with pb and
* lp, LZMA1 and LZMA2 still slightly favor 16-byte alignment.
* It might be worth taking into account when designing file formats
* that are likely to be often compressed with LZMA1 or LZMA2.
*/ */
uint32_t pb; uint32_t pb;
# define LZMA_PB_MIN 0 # define LZMA_PB_MIN 0
@ -346,7 +362,7 @@ typedef struct {
* *
* Setting depth to zero tells liblzma to use an automatic default * Setting depth to zero tells liblzma to use an automatic default
* value, that depends on the selected match finder and nice_len. * value, that depends on the selected match finder and nice_len.
* The default is in the range [10, 200] or so (it may vary between * The default is in the range [4, 200] or so (it may vary between
* liblzma versions). * liblzma versions).
* *
* Using a bigger depth value than the default can increase * Using a bigger depth value than the default can increase

4
src/liblzma/api/lzma/stream_flags.h
View File

@ -148,7 +148,7 @@ extern LZMA_API(lzma_ret) lzma_stream_footer_encode(
/** /**
* \brief Decode Stream Header * \brief Decode Stream Header
* *
* \param options Stream Header options to be encoded. * \param options Target for the decoded Stream Header options.
* \param in Beginning of the input buffer of * \param in Beginning of the input buffer of
* LZMA_STREAM_HEADER_SIZE bytes. * LZMA_STREAM_HEADER_SIZE bytes.
* *
@ -183,7 +183,7 @@ extern LZMA_API(lzma_ret) lzma_stream_header_decode(
/** /**
* \brief Decode Stream Footer * \brief Decode Stream Footer
* *
* \param options Stream Header options to be encoded. * \param options Target for the decoded Stream Header options.
* \param in Beginning of the input buffer of * \param in Beginning of the input buffer of
* LZMA_STREAM_HEADER_SIZE bytes. * LZMA_STREAM_HEADER_SIZE bytes.
* *

31
src/liblzma/api/lzma/vli.h
View File

@ -29,7 +29,7 @@
/** /**
* \brief Maximum supported value of variable-length integer * \brief Maximum supported value of a variable-length integer
*/ */
#define LZMA_VLI_MAX (UINT64_MAX / 2) #define LZMA_VLI_MAX (UINT64_MAX / 2)
@ -39,11 +39,10 @@
#define LZMA_VLI_UNKNOWN UINT64_MAX #define LZMA_VLI_UNKNOWN UINT64_MAX
/** /**
* \brief Maximum supported length of variable length integers * \brief Maximum supported encoded length of variable length integers
*/ */
#define LZMA_VLI_BYTES_MAX 9 #define LZMA_VLI_BYTES_MAX 9
/** /**
* \brief VLI constant suffix * \brief VLI constant suffix
*/ */
@ -53,19 +52,19 @@
/** /**
* \brief Variable-length integer type * \brief Variable-length integer type
* *
* This will always be unsigned integer. Valid VLI values are in the range * Valid VLI values are in the range [0, LZMA_VLI_MAX]. Unknown value is
* [0, LZMA_VLI_MAX]. Unknown value is indicated with LZMA_VLI_UNKNOWN, * indicated with LZMA_VLI_UNKNOWN, which is the maximum value of the
* which is the maximum value of the underlaying integer type. * underlaying integer type.
* *
* In future, even if lzma_vli is defined to be something other than uint64_t, * lzma_vli will be uint64_t for the foreseeable future. If a bigger size
* it is guaranteed that 2 * LZMA_VLI_MAX will not overflow lzma_vli. * is needed in the future, it is guaranteed that 2 * LZMA_VLI_MAX will
* This simplifies integer overflow detection. * not overflow lzma_vli. This simplifies integer overflow detection.
*/ */
typedef uint64_t lzma_vli; typedef uint64_t lzma_vli;
/** /**
* \brief Simple macro to validate variable-length integer * \brief Validate a variable-length integer
* *
* This is useful to test that application has given acceptable values * This is useful to test that application has given acceptable values
* for example in the uncompressed_size and compressed_size variables. * for example in the uncompressed_size and compressed_size variables.
@ -88,9 +87,9 @@ typedef uint64_t lzma_vli;
* *
* \param vli Integer to be encoded * \param vli Integer to be encoded
* \param vli_pos How many VLI-encoded bytes have already been written * \param vli_pos How many VLI-encoded bytes have already been written
* out. When starting to encode a new integer, *vli_pos * out. When starting to encode a new integer in
* must be set to zero. To use single-call encoding, * multi-call mode, *vli_pos must be set to zero.
* set vli_pos to NULL. * To use single-call encoding, set vli_pos to NULL.
* \param out Beginning of the output buffer * \param out Beginning of the output buffer
* \param out_pos The next byte will be written to out[*out_pos]. * \param out_pos The next byte will be written to out[*out_pos].
* \param out_size Size of the out buffer; the first byte into * \param out_size Size of the out buffer; the first byte into
@ -126,9 +125,9 @@ extern LZMA_API(lzma_ret) lzma_vli_encode(lzma_vli vli, size_t *vli_pos,
* initialize it to zero when *vli_pos == 0, so * initialize it to zero when *vli_pos == 0, so
* application isn't required to initialize *vli. * application isn't required to initialize *vli.
* \param vli_pos How many bytes have already been decoded. When * \param vli_pos How many bytes have already been decoded. When
* starting to decode a new integer, *vli_pos must * starting to decode a new integer in multi-call
* be initialized to zero. To use single-call decoding, * mode, *vli_pos must be initialized to zero. To
* set this to NULL. * use single-call decoding, set vli_pos to NULL.
* \param in Beginning of the input buffer * \param in Beginning of the input buffer
* \param in_pos The next byte will be read from in[*in_pos]. * \param in_pos The next byte will be read from in[*in_pos].
* \param in_size Size of the input buffer; the first byte that * \param in_size Size of the input buffer; the first byte that

1
src/liblzma/common/index_decoder.c
View File

@ -291,6 +291,7 @@ lzma_index_decoder(lzma_stream *strm, lzma_index **i, uint64_t memlimit)
lzma_next_strm_init(index_decoder_init, strm, i, memlimit); lzma_next_strm_init(index_decoder_init, strm, i, memlimit);
strm->internal->supported_actions[LZMA_RUN] = true; strm->internal->supported_actions[LZMA_RUN] = true;
strm->internal->supported_actions[LZMA_FINISH] = true;
return LZMA_OK; return LZMA_OK;
} }

1
src/liblzma/common/index_encoder.c
View File

@ -209,6 +209,7 @@ lzma_index_encoder(lzma_stream *strm, const lzma_index *i)
lzma_next_strm_init(lzma_index_encoder_init, strm, i); lzma_next_strm_init(lzma_index_encoder_init, strm, i);
strm->internal->supported_actions[LZMA_RUN] = true; strm->internal->supported_actions[LZMA_RUN] = true;
strm->internal->supported_actions[LZMA_FINISH] = true;
return LZMA_OK; return LZMA_OK;
} }