aboutsummaryrefslogtreecommitdiff
path: root/src/liblzma/api/lzma/index.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/liblzma/api/lzma/index.h97
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;