diff options
Diffstat (limited to '')
| -rw-r--r-- | src/liblzma/api/lzma/index.h | 97 |
1 files changed, 83 insertions, 14 deletions
diff --git a/src/liblzma/api/lzma/index.h b/src/liblzma/api/lzma/index.h index d6072614..9d6b7550 100644 --- a/src/liblzma/api/lzma/index.h +++ b/src/liblzma/api/lzma/index.h @@ -1,6 +1,6 @@ /** * \file lzma/index.h - * \brief Handling of Index lists + * \brief Handling of .xz Index lists * * \author Copyright (C) 1999-2006 Igor Pavlov * \author Copyright (C) 2007 Lasse Collin @@ -69,6 +69,25 @@ typedef struct { /** + * \brief Calculate memory usage for Index with given number of Records + * + * On disk, the size of the Index field depends on both the number of Records + * stored and how big values the Records store (due to variable-length integer + * encoding). When the Index is kept in lzma_index structure, the memory usage + * depends only on the number of Records stored in the Index. The size in RAM + * is almost always a lot bigger than in encoded form on disk. + * + * This function calculates an approximate amount of memory needed hold the + * given number of Records in lzma_index structure. This value may vary + * between liblzma versions if the internal implementation is modified. + * + * If you want to know how much memory an existing lzma_index structure is + * using, use lzma_index_memusage(lzma_index_count(i)). + */ +extern uint64_t lzma_index_memusage(lzma_vli record_count); + + +/** * \brief Allocate and initialize a new lzma_index structure * * If i is NULL, a new lzma_index structure is allocated, initialized, @@ -76,7 +95,7 @@ typedef struct { * * If i is non-NULL, it is reinitialized and the same pointer returned. * In this case, return value cannot be NULL or a different pointer than - * the i given as argument. + * the i that was given as an argument. */ extern lzma_index *lzma_index_init(lzma_index *i, lzma_allocator *allocator) lzma_attr_warn_unused_result; @@ -84,6 +103,8 @@ extern lzma_index *lzma_index_init(lzma_index *i, lzma_allocator *allocator) /** * \brief Deallocate the Index + * + * If i is NULL, this does nothing. */ extern void lzma_index_end(lzma_index *i, lzma_allocator *allocator); @@ -91,14 +112,20 @@ extern void lzma_index_end(lzma_index *i, lzma_allocator *allocator); /** * \brief Add a new Record to an Index * - * \param index Pointer to a lzma_index structure - * \param unpadded_size Unpadded Size of a Block - * \param uncompressed_size Uncompressed Size of a Block, or - * LZMA_VLI_UNKNOWN to indicate padding. + * \param i Pointer to a lzma_index structure + * \param allocator Pointer to lzma_allocator, or NULL to + * use malloc() + * \param unpadded_size Unpadded Size of a Block. This can be + * calculated with lzma_block_unpadded_size() + * after encoding or decoding the Block. + * \param uncompressed_size Uncompressed Size of a Block. This can be + * taken directly from lzma_block structure + * after encoding or decoding the Block. * * Appending a new Record does not affect the read position. * * \return - LZMA_OK + * - LZMA_MEM_ERROR * - LZMA_DATA_ERROR: Compressed or uncompressed size of the * Stream or size of the Index field would grow too big. * - LZMA_PROG_ERROR @@ -117,7 +144,7 @@ extern lzma_vli lzma_index_count(const lzma_index *i) lzma_attr_pure; /** * \brief Get the size of the Index field as bytes * - * This is needed to verify the Index Size field from the Stream Footer. + * This is needed to verify the Backward Size field in the Stream Footer. */ extern lzma_vli lzma_index_size(const lzma_index *i) lzma_attr_pure; @@ -145,7 +172,8 @@ extern lzma_vli lzma_index_stream_size(const lzma_index *i) lzma_attr_pure; * * When no Indexes have been combined with lzma_index_cat(), this function is * identical to lzma_index_stream_size(). If multiple Indexes have been - * combined, this includes also the possible Stream Padding fields. + * combined, this includes also the headers of each separate Stream and the + * possible Stream Padding fields. */ extern lzma_vli lzma_index_file_size(const lzma_index *i) lzma_attr_pure; @@ -181,7 +209,8 @@ extern void lzma_index_rewind(lzma_index *i); * * \param i Pointer to lzma_index structure * \param record Pointer to a structure to hold the search results - * \param target Uncompressed target offset + * \param target Uncompressed target offset which the caller would + * like to locate from the Stream * * If the target is smaller than the uncompressed size of the Stream (can be * checked with lzma_index_uncompressed_size()): @@ -204,13 +233,15 @@ extern lzma_bool lzma_index_locate( * * * - * \param dest Destination Index after which src is appended Source - * \param src Index. The memory allocated for this is either moved - * to be part of *dest or freed iff the function call - * succeeds, and src will be an invalid pointer. + * \param dest Destination Index after which src is appended + * \param src Source Index. The memory allocated for this is + * either moved to be part of *dest or freed if and + * only if the function call succeeds, and src will + * be an invalid pointer. * \param allocator Custom memory allocator; can be NULL to use * malloc() and free(). * \param padding Size of the Stream Padding field between Streams. + * This must be a multiple of four. * * \return - LZMA_OK: Indexes concatenated successfully. * - LZMA_DATA_ERROR: *dest would grow too big. @@ -226,6 +257,8 @@ extern lzma_ret lzma_index_cat(lzma_index *lzma_restrict dest, /** * \brief Duplicates an Index list * + * Makes an identical copy of the Index. Also the read position is copied. + * * \return A copy of the Index, or NULL if memory allocation failed. */ extern lzma_index *lzma_index_dup( @@ -235,6 +268,8 @@ extern lzma_index *lzma_index_dup( /** * \brief Compares if two Index lists are identical + * + * \return True if *a and *b are equal, false otherwise. */ extern lzma_bool lzma_index_equal(const lzma_index *a, const lzma_index *b) lzma_attr_pure; @@ -242,6 +277,17 @@ extern lzma_bool lzma_index_equal(const lzma_index *a, const lzma_index *b) /** * \brief Initializes Index encoder + * + * \param strm Pointer to properly prepared lzma_stream + * \param i Pointer to lzma_index which should be encoded. + * The read position will be at the end of the Index + * after lzma_code() has returned LZMA_STREAM_END. + * + * The only valid action value for lzma_code() is LZMA_RUN. + * + * \return - LZMA_OK: Initialization succeeded, continue with lzma_code(). + * - LZMA_MEM_ERROR + * - LZMA_PROG_ERROR */ extern lzma_ret lzma_index_encoder(lzma_stream *strm, lzma_index *i) lzma_attr_warn_unused_result; @@ -249,6 +295,29 @@ extern lzma_ret lzma_index_encoder(lzma_stream *strm, lzma_index *i) /** * \brief Initializes Index decoder + * + * \param strm Pointer to properly prepared lzma_stream + * \param i Pointer to a pointer that will be made to point + * to the final decoded Index once lzma_code() has + * returned LZMA_STREAM_END. That is, + * lzma_index_decoder() takes care of allocating + * a new lzma_index structure. + * \param memlimit How much memory the resulting Index is allowed + * to require. + * + * The only valid action value for lzma_code() is LZMA_RUN. + * + * \return - LZMA_OK: Initialization succeeded, continue with lzma_code(). + * - LZMA_MEM_ERROR + * - LZMA_MEMLIMIT_ERROR + * - LZMA_PROG_ERROR + * + * \note The memory usage limit is checked early in the decoding + * (within the first dozen input bytes or so). The actual memory + * is allocated later in smaller pieces. If the memory usage + * limit is modified after decoding a part of the Index already, + * the new limit may be ignored. */ -extern lzma_ret lzma_index_decoder(lzma_stream *strm, lzma_index **i) +extern lzma_ret lzma_index_decoder( + lzma_stream *strm, lzma_index **i, uint64_t memlimit) lzma_attr_warn_unused_result; |