Bunch of liblzma API cleanups and fixes.

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;