Updates to liblzma API headers.

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.

1 files changed, 26 insertions, 22 deletions

diff --git a/src/liblzma/api/lzma/base.h b/src/liblzma/api/lzma/base.h
index e51de131..01555068 100644
--- a/src/liblzma/api/lzma/base.h
+++ b/src/liblzma/api/lzma/base.h
@@ -144,7 +144,7 @@ typedef enum {
 		 * Decoder would need more memory than allowed by the
 		 * specified memory usage limit. To continue decoding,
 		 * the memory usage limit has to be increased with
-		 * lzma_memlimit().
+		 * lzma_memlimit_set().
 		 */
 
 	LZMA_FORMAT_ERROR       = 7,
@@ -181,8 +181,7 @@ typedef enum {
 		 * format would be exceeded. These limits are huge, thus
 		 * getting this error from an encoder is mostly theoretical.
 		 * For example, the maximum compressed and uncompressed
-		 * size of a .xz Stream created with lzma_stream_encoder is
-		 * 2^63 - 1 bytes (one byte less than 8 EiB).
+		 * size of a .xz Stream is roughly 8 EiB (2^63 bytes).
 		 *
 		 * Decoders return this error if the input data is corrupt.
 		 * This can mean, for example, invalid CRC32 in headers
@@ -208,7 +207,8 @@ typedef enum {
 		 * LZMA_BUF_ERROR. This is intentional.
 		 *
 		 * 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
 		 * to properly written applications unless the input file
 		 * 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
  * as a separate function argument. The library will use the functions
  * 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
  * 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
 	 *              of liblzma return LZMA_MEM_ERROR.
 	 *
-	 * For performance reasons, the allocator should not waste time
-	 * zeroing the allocated buffers. This is not only about speed, but
-	 * also memory usage, since the operating system kernel doesn't
-	 * necessarily allocate the requested memory in physical memory until
-	 * it is actually used. With small input files liblzma may actually
-	 * need only a fraction of the memory that it requested for allocation.
+	 * The allocator should not waste time zeroing the allocated buffers.
+	 * This is not only about speed, but also memory usage, since the
+	 * operating system kernel doesn't necessarily allocate the requested
+	 * memory in physical memory until it is actually used. With small
+	 * input files, liblzma may actually need only a fraction of the
+	 * memory that it requested for allocation.
 	 *
 	 * \note        LZMA_MEM_ERROR is also used when the size of the
 	 *              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
  *
  * The lzma_stream structure is used for
- *   - passing pointers to input and output buffers to liblzma;
- *   - defining custom memory hander functions; and
- *   - holding a pointer to coder-specific internal data structures.
+ *  - passing pointers to input and output buffers to liblzma;
+ *  - defining custom memory hander functions; and
+ *  - holding a pointer to coder-specific internal data structures.
  *
  * Typical usage:
  *
@@ -459,7 +460,9 @@ typedef struct {
 	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().
 	 */
 	lzma_allocator *allocator;
@@ -516,11 +519,10 @@ typedef struct {
  * to and get output from liblzma.
  *
  * See the description of the coder-specific initialization function to find
- * out what `action' values are supported by the coder. See documentation of
- * lzma_ret for the possible return values.
+ * out what `action' values are supported by the coder.
  */
 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
  *              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
  *              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
  *              (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.
  */
 extern LZMA_API(lzma_ret) lzma_memlimit_set(
-		lzma_stream *strm, uint64_t memlimit);
+		lzma_stream *strm, uint64_t memlimit) lzma_nothrow;