Sort of garbage collection commit. :-| Many things are still

broken. API has changed a lot and it will still change a
little more here and there. The command line tool doesn't
have all the required changes to reflect the API changes, so
it's easy to get "internal error" or trigger assertions.

21 files changed, 655 insertions, 628 deletions

diff --git a/src/liblzma/api/lzma/alignment.h b/src/liblzma/api/lzma/alignment.h
index 6672656c..008af690 100644
--- a/src/liblzma/api/lzma/alignment.h
+++ b/src/liblzma/api/lzma/alignment.h
@@ -27,7 +27,7 @@
  * FIXME desc
  */
 extern uint32_t lzma_alignment_input(
-		const lzma_options_filter *filters, uint32_t guess);
+		const lzma_filter *filters, uint32_t guess);
 
 
 /**
@@ -36,7 +36,7 @@ extern uint32_t lzma_alignment_input(
  * Knowing the alignment of the output data is useful e.g. in the Block
  * encoder which tries to align the Compressed Data field optimally.
  *
- * \param       filters   Pointer to lzma_options_filter array, whose last
+ * \param       filters   Pointer to lzma_filter array, whose last
  *                        member must have .id = LZMA_VLI_VALUE_UNKNOWN.
  * \param       guess     The value to return if the alignment of the output
  *                        is the same as the alignment of the input data.
@@ -57,4 +57,4 @@ extern uint32_t lzma_alignment_input(
  *              options), UINT32_MAX is returned.
  */
 extern uint32_t lzma_alignment_output(
-		const lzma_options_filter *filters, uint32_t guess);
+		const lzma_filter *filters, uint32_t guess);
diff --git a/src/liblzma/api/lzma/alone.h b/src/liblzma/api/lzma/alone.h
deleted file mode 100644
index 72299773..00000000
--- a/src/liblzma/api/lzma/alone.h
+++ /dev/null
@@ -1,52 +0,0 @@
-/**
- * \file        lzma/alone.h
- * \brief       Handling of the legacy LZMA_Alone format
- *
- * \author      Copyright (C) 1999-2006 Igor Pavlov
- * \author      Copyright (C) 2007 Lasse Collin
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public
- * License as published by the Free Software Foundation; either
- * version 2.1 of the License, or (at your option) any later version.
- *
- * This library is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- */
-
-#ifndef LZMA_H_INTERNAL
-#	error Never include this file directly. Use <lzma.h> instead.
-#endif
-
-
-/**
- * \brief       Initializes LZMA_Alone encoder
- *
- * LZMA_Alone files have the suffix .lzma like the .lzma Stream files.
- * LZMA_Alone format supports only one filter, the LZMA filter. There is
- * no support for integrity checks like CRC32.
- *
- * Use this format if and only if you need to create files readable by
- * legacy LZMA tools.
- *
- * LZMA_Alone encoder doesn't support LZMA_SYNC_FLUSH or LZMA_FULL_FLUSH.
- *
- * \return      - LZMA_OK
- *              - LZMA_MEM_ERROR
- *              - LZMA_PROG_ERROR
- */
-extern lzma_ret lzma_alone_encoder(
-		lzma_stream *strm, const lzma_options_lzma *options);
-
-
-/**
- * \brief       Initializes decoder for LZMA_Alone file
- *
- * The LZMA_Alone decoder supports LZMA_SYNC_FLUSH.
- *
- * \return      - LZMA_OK
- *              - LZMA_MEM_ERROR
- */
-extern lzma_ret lzma_alone_decoder(lzma_stream *strm);
diff --git a/src/liblzma/api/lzma/auto.h b/src/liblzma/api/lzma/auto.h
deleted file mode 100644
index fd5bf7d2..00000000
--- a/src/liblzma/api/lzma/auto.h
+++ /dev/null
@@ -1,36 +0,0 @@
-/**
- * \file        lzma/auto.h
- * \brief       Decoder with automatic file format detection
- *
- * \author      Copyright (C) 1999-2006 Igor Pavlov
- * \author      Copyright (C) 2007 Lasse Collin
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public
- * License as published by the Free Software Foundation; either
- * version 2.1 of the License, or (at your option) any later version.
- *
- * This library is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- */
-
-#ifndef LZMA_H_INTERNAL
-#	error Never include this file directly. Use <lzma.h> instead.
-#endif
-
-
-/**
- * \brief       Decode .lzma Streams and LZMA_Alone files with autodetection
- *
- * Autodetects between the .lzma Stream and LZMA_Alone formats, and
- * calls lzma_stream_decoder_init() or lzma_alone_decoder_init() once
- * the type of the file has been detected.
- *
- * \param       strm        Pointer to propertily prepared lzma_stream
- *
- * \return      - LZMA_OK: Initialization was successful.
- *              - LZMA_MEM_ERROR: Cannot allocate memory.
- */
-extern lzma_ret lzma_auto_decoder(lzma_stream *strm);
diff --git a/src/liblzma/api/lzma/base.h b/src/liblzma/api/lzma/base.h
index b0dfed95..cb614176 100644
--- a/src/liblzma/api/lzma/base.h
+++ b/src/liblzma/api/lzma/base.h
@@ -134,7 +134,7 @@ typedef enum {
 		 * \brief       Unknown file format
 		 */
 
-	LZMA_MEMLIMIT_ERROR     = -9
+	LZMA_MEMLIMIT_ERROR     = -9,
 		/**
 		 * \brief       Memory usage limit was reached
 		 *
@@ -143,6 +143,9 @@ typedef enum {
 		 * the memory usage limit has to be increased. See functions
 		 * lzma_memlimit_get() and lzma_memlimit_set().
 		 */
+
+	LZMA_NO_CHECK = -10,
+	LZMA_SEE_CHECK = -11
 } lzma_ret;
 
 
@@ -229,11 +232,6 @@ typedef struct {
 	/**
 	 * \brief       Pointer to custom memory allocation function
 	 *
-	 * Set this to point to your custom memory allocation function.
-	 * It can be useful for example if you want to limit how much
-	 * memory liblzma is allowed to use: for this, you may use
-	 * a pointer to lzma_memory_alloc().
-	 *
 	 * If you don't want a custom allocator, but still want
 	 * custom free(), set this to NULL and liblzma will use
 	 * the standard malloc().
@@ -250,16 +248,19 @@ typedef struct {
 	 *              size nmemb * size, or NULL if allocation fails
 	 *              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 until it is actually
+	 * used. With small input files liblzma may actually need only a
+	 * fraction of the memory that it requested for allocation.
 	 */
 	void *(*alloc)(void *opaque, size_t nmemb, size_t size);
 
 	/**
 	 * \brief       Pointer to custom memory freeing function
 	 *
-	 * Set this to point to your custom memory freeing function.
-	 * If lzma_memory_alloc() is used as allocator, this should
-	 * be set to lzma_memory_free().
-	 *
 	 * If you don't want a custom freeing function, but still
 	 * want a custom allocator, set this to NULL and liblzma
 	 * will use the standard free().
@@ -279,10 +280,6 @@ typedef struct {
 	 * and lzma_allocator.free(). This intended to ease implementing
 	 * custom memory allocation functions for use with liblzma.
 	 *
-	 * When using lzma_memory_alloc() and lzma_memory_free(), opaque
-	 * must point to lzma_memory_limiter structure allocated and
-	 * initialized with lzma_memory_limiter_create().
-	 *
 	 * If you don't need this, you should set it to NULL.
 	 */
 	void *opaque;
@@ -347,6 +344,17 @@ typedef struct {
 	/** Internal state is not visible to outsiders. */
 	lzma_internal *internal;
 
+	/**
+	 * Reserved space to allow possible future extensions without
+	 * breaking the ABI. Excluding the initialization of this structure,
+	 * you should not touch these, because the names of these variables
+	 * may change.
+	 */
+	void *reserved_ptr1;
+	void *reserved_ptr2;
+	uint64_t reserved_int1;
+	uint64_t reserved_int2;
+
 } lzma_stream;
 
 
@@ -358,22 +366,18 @@ typedef struct {
  * has been allocated yet:
  *
  *     lzma_stream strm = LZMA_STREAM_INIT;
- */
-#define LZMA_STREAM_INIT { NULL, 0, 0, NULL, 0, 0, NULL, NULL }
-
-
-/**
- * \brief       Initialization for lzma_stream
  *
- * This is like LZMA_STREAM_INIT, but this can be used when the lzma_stream
- * has already been allocated:
+ * If you need to initialize a dynamically allocatedlzma_stream, you can use
+ * memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this
+ * violates the C standard since NULL may have different internal
+ * representation than zero, but it should be portable enough in practice.
+ * Anyway, for maximum portability, you could use this:
  *
- *     lzma_stream *strm = malloc(sizeof(lzma_stream));
- *     if (strm == NULL)
- *         return LZMA_MEM_ERROR;
- *     *strm = LZMA_STREAM_INIT_VAR;
+ *     lzma_stream tmp = LZMA_STREAM_INIT;
+ *     *strm = tmp;
  */
-extern const lzma_stream LZMA_STREAM_INIT_VAR;
+#define LZMA_STREAM_INIT \
+	{ NULL, 0, 0, NULL, 0, 0, NULL, NULL, NULL, NULL, 0, 0 }
 
 
 /**
@@ -409,7 +413,8 @@ extern const lzma_stream LZMA_STREAM_INIT_VAR;
  *              - LZMA_PROG_ERROR: Invalid arguments or the internal state
  *                of the coder is corrupt.
  */
-extern lzma_ret lzma_code(lzma_stream *strm, lzma_action action);
+extern lzma_ret lzma_code(lzma_stream *strm, lzma_action action)
+		lzma_attr_warn_unused_result;
 
 
 /**
diff --git a/src/liblzma/api/lzma/block.h b/src/liblzma/api/lzma/block.h
index a8941165..45045815 100644
--- a/src/liblzma/api/lzma/block.h
+++ b/src/liblzma/api/lzma/block.h
@@ -36,12 +36,13 @@ typedef struct {
 	 * \brief       Size of the Block Header
 	 *
 	 * Read by:
+	 *  - lzma_block_header_encode()
+	 *  - lzma_block_header_decode()
 	 *  - lzma_block_encoder()
 	 *  - lzma_block_decoder()
 	 *
 	 * Written by:
 	 *  - lzma_block_header_size()
-	 *  - lzma_block_header_decode()
 	 */
 	uint32_t header_size;
 #	define LZMA_BLOCK_HEADER_SIZE_MIN 8
@@ -54,10 +55,12 @@ typedef struct {
 	 * Header, thus its value must be provided also when decoding.
 	 *
 	 * Read by:
+	 *  - lzma_block_header_encode()
+	 *  - lzma_block_header_decode()
 	 *  - lzma_block_encoder()
 	 *  - lzma_block_decoder()
 	 */
-	lzma_check_type check;
+	lzma_check check;
 
 	/**
 	 * \brief       Size of the Compressed Data in bytes
@@ -134,17 +137,17 @@ typedef struct {
 	 *              have LZMA_BLOCK_FILTERS_MAX + 1 members or the Block
 	 *              Header decoder will overflow the buffer.
 	 */
-	lzma_options_filter *filters;
+	lzma_filter *filters;
 #	define LZMA_BLOCK_FILTERS_MAX 4
 
-} lzma_options_block;
+} lzma_block;
 
 
 /**
  * \brief       Decodes the Block Header Size field
  *
  * To decode Block Header using lzma_block_header_decode(), the size of the
- * Block Header has to be known and stored into lzma_options_block.header_size.
+ * Block Header has to be known and stored into lzma_block.header_size.
  * The size can be calculated from the first byte of a Block using this macro.
  * Note that if the first byte is 0x00, it indicates beginning of Index; use
  * this macro only when the byte is not 0x00.
@@ -164,7 +167,8 @@ typedef struct {
  *              may return LZMA_OK even if lzma_block_header_encode() or
  *              lzma_block_encoder() would fail.
  */
-extern lzma_ret lzma_block_header_size(lzma_options_block *options);
+extern lzma_ret lzma_block_header_size(lzma_block *options)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -183,7 +187,8 @@ extern lzma_ret lzma_block_header_size(lzma_options_block *options);
  *              - LZMA_PROG_ERROR
  */
 extern lzma_ret lzma_block_header_encode(
-		const lzma_options_block *options, uint8_t *out);
+		const lzma_block *options, uint8_t *out)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -203,8 +208,9 @@ extern lzma_ret lzma_block_header_encode(
  *              - LZMA_HEADER_ERROR: Invalid or unsupported options.
  *              - LZMA_PROG_ERROR
  */
-extern lzma_ret lzma_block_header_decode(lzma_options_block *options,
-		lzma_allocator *allocator, const uint8_t *in);
+extern lzma_ret lzma_block_header_decode(lzma_block *options,
+		lzma_allocator *allocator, const uint8_t *in)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -227,7 +233,8 @@ extern lzma_ret lzma_block_header_decode(lzma_options_block *options,
  *                options->header_size between 8 and 1024 inclusive.
  */
 extern lzma_ret lzma_block_total_size_set(
-		lzma_options_block *options, lzma_vli total_size);
+		lzma_block *options, lzma_vli total_size)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -238,7 +245,8 @@ extern lzma_ret lzma_block_total_size_set(
  *
  * \return      Total Size on success, or zero on error.
  */
-extern lzma_vli lzma_block_total_size_get(const lzma_options_block *options);
+extern lzma_vli lzma_block_total_size_get(const lzma_block *options)
+		lzma_attr_pure;
 
 
 /**
@@ -259,8 +267,8 @@ extern lzma_vli lzma_block_total_size_get(const lzma_options_block *options);
  *
  * lzma_code() can return FIXME
  */
-extern lzma_ret lzma_block_encoder(
-		lzma_stream *strm, lzma_options_block *options);
+extern lzma_ret lzma_block_encoder(lzma_stream *strm, lzma_block *options)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -273,5 +281,5 @@ extern lzma_ret lzma_block_encoder(
  *              - LZMA_PROG_ERROR
  *              - LZMA_MEM_ERROR
  */
-extern lzma_ret lzma_block_decoder(
-		lzma_stream *strm, lzma_options_block *options);
+extern lzma_ret lzma_block_decoder(lzma_stream *strm, lzma_block *options)
+		lzma_attr_warn_unused_result;
diff --git a/src/liblzma/api/lzma/check.h b/src/liblzma/api/lzma/check.h
index dcba8269..18394a86 100644
--- a/src/liblzma/api/lzma/check.h
+++ b/src/liblzma/api/lzma/check.h
@@ -56,7 +56,7 @@ typedef enum {
 		 *
 		 * Size of the Check field: 32 bytes
 		 */
-} lzma_check_type;
+} lzma_check;
 
 
 /**
@@ -74,31 +74,34 @@ typedef enum {
 
 
 /**
- * \brief       Check IDs supported by this liblzma build
- *
- * If lzma_available_checks[n] is true, the Check ID n is supported by this
- * liblzma build. You can assume that LZMA_CHECK_NONE and LZMA_CHECK_CRC32
- * are always available.
+ * \brief       Maximum size of a Check field
  */
-extern const lzma_bool lzma_available_checks[LZMA_CHECK_ID_MAX + 1];
+#define LZMA_CHECK_SIZE_MAX 64
 
 
 /**
- * \brief       Size of the Check field with different Check IDs
+ * \brief       Test if the given Check ID is supported
  *
- * Although not all Check IDs have a check algorithm associated, the size of
- * every Check is already frozen. This array contains the size (in bytes) of
- * the Check field with specified Check ID. The values are taken from the
- * section 2.1.1.2 of the .lzma file format specification:
- * { 0, 4, 4, 4, 8, 8, 8, 16, 16, 16, 32, 32, 32, 64, 64, 64 }
+ * Returns true if the given Check ID is supported by this liblzma build.
+ * Otherwise false is returned. It is safe to call this with a value that
+ * is not in the range [0, 15]; in that case the return value is always false.
  */
-extern const uint32_t lzma_check_sizes[LZMA_CHECK_ID_MAX + 1];
+extern lzma_bool lzma_check_is_supported(lzma_check check)
+		lzma_attr_const;
 
 
 /**
- * \brief       Maximum size of a Check field
+ * \brief       Get the size of the Check field with given Check ID
+ *
+ * Although not all Check IDs have a check algorithm associated, the size of
+ * every Check is already frozen. This function returns the size (in bytes) of
+ * the Check field with the specified Check ID. The values are taken from the
+ * section 2.1.1.2 of the .lzma file format specification:
+ * { 0, 4, 4, 4, 8, 8, 8, 16, 16, 16, 32, 32, 32, 64, 64, 64 }
+ *
+ * If the argument is not in the range [0, 15], UINT32_MAX is returned.
  */
-#define LZMA_CHECK_SIZE_MAX 64
+extern uint32_t lzma_check_size(lzma_check check) lzma_attr_const;
 
 
 /**
@@ -115,7 +118,8 @@ extern const uint32_t lzma_check_sizes[LZMA_CHECK_ID_MAX + 1];
  * \return      Updated CRC value, which can be passed to this function
  *              again to continue CRC calculation.
  */
-extern uint32_t lzma_crc32(const uint8_t *buf, size_t size, uint32_t crc);
+extern uint32_t lzma_crc32(const uint8_t *buf, size_t size, uint32_t crc)
+		lzma_attr_pure;
 
 
 /**
@@ -125,7 +129,8 @@ extern uint32_t lzma_crc32(const uint8_t *buf, size_t size, uint32_t crc);
  *
  * This function is used similarly to lzma_crc32(). See its documentation.
  */
-extern uint64_t lzma_crc64(const uint8_t *buf, size_t size, uint64_t crc);
+extern uint64_t lzma_crc64(const uint8_t *buf, size_t size, uint64_t crc)
+		lzma_attr_pure;
 
 
 /*
diff --git a/src/liblzma/api/lzma/container.h b/src/liblzma/api/lzma/container.h
new file mode 100644
index 00000000..27014856
--- /dev/null
+++ b/src/liblzma/api/lzma/container.h
@@ -0,0 +1,252 @@
+/**
+ * \file        lzma/FIXME.h
+ * \brief       File formats
+ *
+ * \author      Copyright (C) 1999-2008 Igor Pavlov
+ * \author      Copyright (C) 2007-2008 Lasse Collin
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ */
+
+#ifndef LZMA_H_INTERNAL
+#	error Never include this file directly. Use <lzma.h> instead.
+#endif
+
+
+/************
+ * Encoding *
+ ************/
+
+/**
+ * \brief       Compression level names for lzma_easy_* functions
+ *
+ * At the moment, all the compression levels support LZMA_SYNC_FLUSH.
+ * In future there may be levels that don't support LZMA_SYNC_FLUSH.
+ * However, the LZMA_SYNC_FLUSH support won't be removed from the
+ * existing compression levels.
+ *
+ * \note        If liblzma is built without encoder support, or with some
+ *              filters disabled, some of the compression levels may be
+ *              unsupported. In that case, the initialization functions
+ *              will return LZMA_HEADER_ERROR.
+ */
+typedef enum {
+	LZMA_EASY_COPY      = 0,
+		/**<
+		 * No compression; the data is just wrapped into .lzma
+		 * container.
+		 */
+
+	LZMA_EASY_LZMA2_1   = 1,
+		/**<
+		 * LZMA2 filter with fast compression (fast in terms of LZMA2).
+		 * If you are interested in the exact options used, see
+		 * lzma_preset_lzma[0]. Note that the exact options may
+		 * change between liblzma versions.
+		 *
+		 * At the moment, the command line tool uses these settings
+		 * when `lzma -1' is used. In future, the command line tool
+		 * may default to some more complex way to determine the
+		 * settings used e.g. the type of files being compressed.
+		 *
+		 * LZMA_EASY_LZMA_2 is equivalent to lzma_preset_lzma[1]
+		 * and so on.
+		 */
+
+	LZMA_EASY_LZMA_2    = 2,
+	LZMA_EASY_LZMA_3    = 3,
+	LZMA_EASY_LZMA_4    = 4,
+	LZMA_EASY_LZMA_5    = 5,
+	LZMA_EASY_LZMA_6    = 6,
+	LZMA_EASY_LZMA_7    = 7,
+	LZMA_EASY_LZMA_8    = 8,
+	LZMA_EASY_LZMA_9    = 9,
+} lzma_easy_level;
+
+
+/**
+ * \brief       Default compression level
+ *
+ * Data Blocks contain the actual compressed data. It's not straightforward
+ * to recommend a default level, because in some cases keeping the resource
+ * usage relatively low is more important that getting the maximum
+ * compression ratio.
+ */
+#define LZMA_EASY_DEFAULT LZMA_EASY_LZMA2_7
+
+
+/**
+ * \brief       Calculates rough memory requirements of a compression level
+ *
+ * This function is a wrapper for lzma_memory_usage(), which is declared
+ * in filter.h.
+ *
+ * \return      Approximate memory usage of the encoder with the given
+ *              compression level in mebibytes (value * 1024 * 1024 bytes).
+ *              On error (e.g. compression level is not supported),
+ *              UINT32_MAX is returned.
+ */
+extern uint32_t lzma_easy_memory_usage(lzma_easy_level level)
+		lzma_attr_pure;
+
+
+/**
+ * \brief       Initializes .lzma Stream encoder
+ *
+ * This function is intended for those who just want to use the basic features
+ * if liblzma (that is, most developers out there). Lots of assumptions are
+ * made, which are correct or at least good enough for most situations.
+ *
+ * \param       strm    Pointer to lzma_stream that is at least initialized
+ *                      with LZMA_STREAM_INIT.
+ * \param       level   Compression level to use. This selects a set of
+ *                      compression settings from a list of compression
+ *                      presets.
+ *
+ * \return      - LZMA_OK: Initialization succeeded. Use lzma_code() to
+ *                encode your data.
+ *              - LZMA_MEM_ERROR: Memory allocation failed. All memory
+ *                previously allocated for *strm is now freed.
+ *              - LZMA_HEADER_ERROR: The given compression level is not
+ *                supported by this build of liblzma.
+ *
+ * If initialization succeeds, use lzma_code() to do the actual encoding.
+ * Valid values for `action' (the second argument of lzma_code()) are
+ * LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future,
+ * there may be compression levels that don't support LZMA_SYNC_FLUSH.
+ */
+extern lzma_ret lzma_easy_encoder(lzma_stream *strm, lzma_easy_level level)
+		lzma_attr_warn_unused_result;
+
+
+/**
+ * \brief       Initializes .lzma Stream encoder
+ *
+ * \param       strm    Pointer to properly prepared lzma_stream
+ * \param       filters Array of filters. This must be terminated with
+ *                      filters[n].id = LZMA_VLI_VALUE_UNKNOWN. There must
+ *                      be 1-4 filters, but there are restrictions on how
+ *                      multiple filters can be combined. FIXME Tell where
+ *                      to find more information.
+ * \param       check   Type of the integrity check to calculate from
+ *                      uncompressed data.
+ *
+ * \return      - LZMA_OK: Initialization was successful.
+ *              - LZMA_MEM_ERROR
+ *              - LZMA_HEADER_ERROR
+ *              - LZMA_PROG_ERROR
+ */
+extern lzma_ret lzma_stream_encoder(lzma_stream *strm,
+		const lzma_filter *filters, lzma_check check)
+		lzma_attr_warn_unused_result;
+
+
+/**
+ * \brief       Initializes LZMA_Alone (deprecated file format) encoder
+ *
+ * LZMA_Alone files have the suffix .lzma like the .lzma Stream files.
+ * LZMA_Alone format supports only one filter, the LZMA filter. There is
+ * no support for integrity checks like CRC32.
+ *
+ * Use this format if and only if you need to create files readable by
+ * legacy LZMA tools such as LZMA Utils 4.32.x.
+ *
+ * LZMA_Alone encoder doesn't support LZMA_SYNC_FLUSH or LZMA_FULL_FLUSH.
+ *
+ * \return      - LZMA_OK
+ *              - LZMA_MEM_ERROR
+ *              - LZMA_PROG_ERROR
+ */
+extern lzma_ret lzma_alone_encoder(
+		lzma_stream *strm, const lzma_options_lzma *options)
+		lzma_attr_warn_unused_result;
+
+
+/************
+ * Decoding *
+ ************/
+
+/**
+ * This flag makes lzma_code() return LZMA_NO_CHECK if the input stream
+ * being decoded has no integrity check. Note that when used with
+ * lzma_auto_decoder(), all LZMA_Alone files will cause trigger LZMA_NO_CHECK
+ * if LZMA_WARN_NO_CHECK is used.
+ */
+#define LZMA_WARN_NO_CHECK              UINT32_C(0x01)
+
+
+/**
+ * This flag makes lzma_code() return LZMA_UNSUPPORTED_CHECK if the input
+ * stream has an integrity check, but the type of the integrity check is not
+ * supported by this liblzma version or build. Such files can still be
+ * decoded, but the integrity check cannot be verified.
+ */
+#define LZMA_WARN_UNSUPPORTED_CHECK     UINT32_C(0x02)
+
+
+/**
+ * This flag makes lzma_code() return LZMA_READ_CHECK as soon as the type
+ * of the integrity check is known. The type can then be read with
+ * lzma_check_get().
+ */
+#define LZMA_TELL_CHECK                 UINT32_C(0x04)
+
+
+/**
+ * This flag makes lzma_code() decode concatenated .lzma files.
+ * FIXME Explain the changed API.
+ */
+#define LZMA_CONCATENATED               UINT32_C(0x08)
+
+
+/**
+ * \brief       Initializes decoder for .lzma Stream
+ *
+ * \param       strm        Pointer to propertily prepared lzma_stream
+ * \param       memlimit    Rough memory usage limit as bytes
+ *
+ * \return      - LZMA_OK: Initialization was successful.
+ *              - LZMA_MEM_ERROR: Cannot allocate memory.
+ */
+extern lzma_ret lzma_stream_decoder(
+		lzma_stream *strm, uint64_t memlimit, uint32_t flags)
+		lzma_attr_warn_unused_result;
+
+
+/**
+ * \brief       Decode .lzma Streams and LZMA_Alone files with autodetection
+ *
+ * Autodetects between the .lzma Stream and LZMA_Alone formats, and
+ * calls lzma_stream_decoder_init() or lzma_alone_decoder_init() once
+ * the type of the file has been detected.
+ *
+ * \param       strm        Pointer to propertily prepared lzma_stream
+ * \param       memlimit    Rough memory usage limit as bytes
+ * \param       flags       Bitwise-or of flags, or zero for no flags.
+ *
+ * \return      - LZMA_OK: Initialization was successful.
+ *              - LZMA_MEM_ERROR: Cannot allocate memory.
+ */
+extern lzma_ret lzma_auto_decoder(
+		lzma_stream *strm, uint64_t memlimit, uint32_t flags)
+		lzma_attr_warn_unused_result;
+
+
+/**
+ * \brief       Initializes decoder for LZMA_Alone file
+ *
+ * The LZMA_Alone decoder supports LZMA_SYNC_FLUSH. FIXME
+ *
+ * \return      - LZMA_OK
+ *              - LZMA_MEM_ERROR
+ */
+extern lzma_ret lzma_alone_decoder(lzma_stream *strm, uint64_t memlimit)
+		lzma_attr_warn_unused_result;
diff --git a/src/liblzma/api/lzma/delta.h b/src/liblzma/api/lzma/delta.h
index 58afec18..740de97c 100644
--- a/src/liblzma/api/lzma/delta.h
+++ b/src/liblzma/api/lzma/delta.h
@@ -24,9 +24,21 @@
 /**
  * \brief       Filter ID
  *
- * Filter ID of the Delta filter. This is used as lzma_options_filter.id.
+ * Filter ID of the Delta filter. This is used as lzma_filter.id.
  */
-#define LZMA_FILTER_DELTA       LZMA_VLI_C(0x20)
+#define LZMA_FILTER_DELTA       LZMA_VLI_C(0x03)
+
+
+/**
+ * \brief       Type of the delta calculation
+ *
+ * Currently only byte-wise delta is supported. Other possible types could
+ * be, for example, delta of 16/32/64-bit little/big endian integers, but
+ * these are not currently planned since byte-wise delta is almost as good.
+ */
+typedef enum {
+	LZMA_DELTA_TYPE_BYTE
+} lzma_delta_type;
 
 
 /**
@@ -35,8 +47,14 @@
  * These options are needed by both encoder and decoder.
  */
 typedef struct {
+	/** For now, this must always be LZMA_DELTA_TYPE_BYTE. */
+	lzma_delta_type type;
+
 	/**
-	 * \brief       Delta distance as bytes
+	 * \brief       Delta distance
+	 *
+	 * With the only currently supported type, LZMA_DELTA_TYPE_BYTE,
+	 * the distance is as bytes.
 	 *
 	 * Examples:
 	 *  - 16-bit stereo audio: distance = 4 bytes
@@ -46,4 +64,16 @@ typedef struct {
 #	define LZMA_DELTA_DISTANCE_MIN 1
 #	define LZMA_DELTA_DISTANCE_MAX 256
 
+	/**
+	 * \brief       Reserved space for possible future extensions
+	 *
+	 * You should not touch these, because the names of these variables
+	 * may change. These are and will never be used when type is
+	 * LZMA_DELTA_TYPE_BYTE, so it is safe to leave these uninitialized.
+	 */
+	uint32_t reserved_int1;
+	uint32_t reserved_int2;
+	void *reserved_ptr1;
+	void *reserved_ptr2;
+
 } lzma_options_delta;
diff --git a/src/liblzma/api/lzma/easy.h b/src/liblzma/api/lzma/easy.h
deleted file mode 100644
index d83a79a2..00000000
--- a/src/liblzma/api/lzma/easy.h
+++ /dev/null
@@ -1,121 +0,0 @@
-/**
- * \file        lzma/easy.h
- * \brief       Easy to use encoder initialization
- *
- * \author      Copyright (C) 1999-2006 Igor Pavlov
- * \author      Copyright (C) 2008 Lasse Collin
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public
- * License as published by the Free Software Foundation; either
- * version 2.1 of the License, or (at your option) any later version.
- *
- * This library is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- */
-
-#ifndef LZMA_H_INTERNAL
-#	error Never include this file directly. Use <lzma.h> instead.
-#endif
-
-
-/**
- * \brief       Compression level names for lzma_easy_* functions
- *
- * At the moment, all the compression levels support LZMA_SYNC_FLUSH.
- * In future there may be levels that don't support LZMA_SYNC_FLUSH.
- * However, the LZMA_SYNC_FLUSH support won't be removed from the
- * existing compression levels.
- *
- * \note        If liblzma is built without encoder support, or with some
- *              filters disabled, some of the compression levels may be
- *              unsupported. In that case, the initialization functions
- *              will return LZMA_HEADER_ERROR.
- */
-typedef enum {
-	LZMA_EASY_COPY,
-		/**<
-		 * No compression; the data is just wrapped into .lzma
-		 * container.
-		 */
-
-	LZMA_EASY_LZMA_1,
-		/**<
-		 * LZMA filter with fast compression (fast in terms of LZMA).
-		 * If you are interested in the exact options used, see
-		 * lzma_preset_lzma[0]. Note that the exact options may
-		 * change between liblzma versions.
-		 *
-		 * At the moment, the command line tool uses these settings
-		 * when `lzma -1' is used. In future, the command line tool
-		 * may default to some more complex way to determine the
-		 * settings used e.g. the type of files being compressed.
-		 *
-		 * LZMA_EASY_LZMA_2 is equivalent to lzma_preset_lzma[1]
-		 * and so on.
-		 */
-
-	LZMA_EASY_LZMA_2,
-	LZMA_EASY_LZMA_3,
-	LZMA_EASY_LZMA_4,
-	LZMA_EASY_LZMA_5,
-	LZMA_EASY_LZMA_6,
-	LZMA_EASY_LZMA_7,
-	LZMA_EASY_LZMA_8,
-	LZMA_EASY_LZMA_9,
-} lzma_easy_level;
-
-
-/**
- * \brief       Default compression level
- *
- * Data Blocks contain the actual compressed data. It's not straightforward
- * to recommend a default level, because in some cases keeping the resource
- * usage relatively low is more important that getting the maximum
- * compression ratio.
- */
-#define LZMA_EASY_DEFAULT LZMA_EASY_LZMA_7
-
-
-/**
- * \brief       Calculates rough memory requirements of a compression level
- *
- * This function is a wrapper for lzma_memory_usage(), which is declared
- * in lzma/filter.h.
- *
- * \return      Approximate memory usage of the encoder with the given
- *              compression level in mebibytes (value * 1024 * 1024 bytes).
- *              On error (e.g. compression level is not supported),
- *              UINT32_MAX is returned.
- */
-extern uint32_t lzma_easy_memory_usage(lzma_easy_level level);
-
-
-/**
- * \brief       Initializes .lzma Stream encoder
- *
- * This function is intended for those who just want to use the basic LZMA
- * features (that is, most developers out there). Lots of assumptions are
- * made, which are correct or at least good enough for most situations.
- *
- * \param       strm    Pointer to lzma_stream that is at least initialized
- *                      with LZMA_STREAM_INIT.
- * \param       level   Compression level to use. This selects a set of
- *                      compression settings from a list of compression
- *                      presets.
- *
- * \return      - LZMA_OK: Initialization succeeded. Use lzma_code() to
- *                encode your data.
- *              - LZMA_MEM_ERROR: Memory allocation failed. All memory
- *                previously allocated for *strm is now freed.
- *              - LZMA_HEADER_ERROR: The given compression level is not
- *                supported by this build of liblzma.
- *
- * If initialization succeeds, use lzma_code() to do the actual encoding.
- * Valid values for `action' (the second argument of lzma_code()) are
- * LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future,
- * there may be compression levels that don't support LZMA_SYNC_FLUSH.
- */
-extern lzma_ret lzma_easy_encoder(lzma_stream *strm, lzma_easy_level level);
diff --git a/src/liblzma/api/lzma/filter.h b/src/liblzma/api/lzma/filter.h
index 412c30e5..d5903f89 100644
--- a/src/liblzma/api/lzma/filter.h
+++ b/src/liblzma/api/lzma/filter.h
@@ -51,7 +51,7 @@ typedef struct {
 	 */
 	void *options;
 
-} lzma_options_filter;
+} lzma_filter;
 
 
 /**
@@ -65,7 +65,7 @@ typedef struct {
  * encoding-specific functions are probably missing from the library
  * API/ABI completely.
  */
-extern const lzma_vli *const lzma_available_filter_encoders;
+extern const lzma_vli *const lzma_filter_encoders;
 
 
 /**
@@ -79,7 +79,7 @@ extern const lzma_vli *const lzma_available_filter_encoders;
  * decoding-specific functions are probably missing from the library
  * API/ABI completely.
  */
-extern const lzma_vli *const lzma_available_filter_decoders;
+extern const lzma_vli *const lzma_filter_decoders;
 
 
 /**
@@ -87,8 +87,6 @@ extern const lzma_vli *const lzma_available_filter_decoders;
  *
  * \param       filters     Array of filters terminated with
  *                          .id == LZMA_VLI_VALUE_UNKNOWN.
- * \param       is_encoder  Set to true when calculating memory requirements
- *                          of an encoder; false for decoder.
  *
  * \return      Number of mebibytes (MiB i.e. 2^20) required for the given
  *              encoder or decoder filter chain.
@@ -98,8 +96,55 @@ extern const lzma_vli *const lzma_available_filter_decoders;
  *              if calculating memory requirements of decoder, lzma_init() or
  *              lzma_init_decoder() must have been called earlier.
  */
-extern uint32_t lzma_memory_usage(
-		const lzma_options_filter *filters, lzma_bool is_encoder);
+// extern uint32_t lzma_memory_usage(
+// 		const lzma_filter *filters, lzma_bool is_encoder);
+
+extern uint64_t lzma_memusage_encoder(const lzma_filter *filters)
+		lzma_attr_pure;
+
+extern uint64_t lzma_memusage_decoder(const lzma_filter *filters)
+		lzma_attr_pure;
+
+
+/**
+ * \brief       Initializes raw encoder
+ *
+ * This function may be useful when implementing custom file formats.
+ *
+ * \param       strm    Pointer to properly prepared lzma_stream
+ * \param       options Array of lzma_filter structures.
+ *                      The end of the array must be marked with
+ *                      .id = LZMA_VLI_VALUE_UNKNOWN. The minimum
+ *                      number of filters is one and the maximum is four.
+ *
+ * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the
+ * filter chain supports it), or LZMA_FINISH.
+ *
+ * \return      - LZMA_OK
+ *              - LZMA_MEM_ERROR
+ *              - LZMA_HEADER_ERROR
+ *              - LZMA_PROG_ERROR
+ */
+extern lzma_ret lzma_raw_encoder(
+		lzma_stream *strm, const lzma_filter *options)
+		lzma_attr_warn_unused_result;
+
+
+/**
+ * \brief       Initializes raw decoder
+ *
+ * The initialization of raw decoder goes similarly to raw encoder.
+ *
+ * The `action' with lzma_code() can be LZMA_RUN or LZMA_SYNC_FLUSH.
+ *
+ * \return      - LZMA_OK
+ *              - LZMA_MEM_ERROR
+ *              - LZMA_HEADER_ERROR
+ *              - LZMA_PROG_ERROR
+ */
+extern lzma_ret lzma_raw_decoder(
+		lzma_stream *strm, const lzma_filter *options)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -119,10 +164,11 @@ extern uint32_t lzma_memory_usage(
  *              - LZMA_PROG_ERROR: Invalid options
  *
  * \note        If you need to calculate size of List of Filter Flags,
- *              you need to loop over every lzma_options_filter entry.
+ *              you need to loop over every lzma_filter entry.
  */
 extern lzma_ret lzma_filter_flags_size(
-		uint32_t *size, const lzma_options_filter *options);
+		uint32_t *size, const lzma_filter *options)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -143,8 +189,9 @@ extern lzma_ret lzma_filter_flags_size(
  *                buffer space (you should have checked it with
  *                lzma_filter_flags_size()).
  */
-extern lzma_ret lzma_filter_flags_encode(uint8_t *out, size_t *out_pos,
-		size_t out_size, const lzma_options_filter *options);
+extern lzma_ret lzma_filter_flags_encode(const lzma_filter *options,
+		uint8_t *out, size_t *out_pos, size_t out_size)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -163,5 +210,6 @@ extern lzma_ret lzma_filter_flags_encode(uint8_t *out, size_t *out_pos,
  *              - LZMA_PROG_ERROR
  */
 extern lzma_ret lzma_filter_flags_decode(
-		lzma_options_filter *options, lzma_allocator *allocator,
-		const uint8_t *in, size_t *in_pos, size_t in_size);
+		lzma_filter *options, lzma_allocator *allocator,
+		const uint8_t *in, size_t *in_pos, size_t in_size)
+		lzma_attr_warn_unused_result;
diff --git a/src/liblzma/api/lzma/index.h b/src/liblzma/api/lzma/index.h
index 13cddf47..44be10b1 100644
--- a/src/liblzma/api/lzma/index.h
+++ b/src/liblzma/api/lzma/index.h
@@ -66,7 +66,8 @@ typedef struct {
  * In this case, return value cannot be NULL or a different pointer than
  * the i given as argument.
  */
-extern lzma_index *lzma_index_init(lzma_index *i, lzma_allocator *allocator);
+extern lzma_index *lzma_index_init(lzma_index *i, lzma_allocator *allocator)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -91,13 +92,14 @@ extern void lzma_index_end(lzma_index *i, lzma_allocator *allocator);
  *              - LZMA_PROG_ERROR
  */
 extern lzma_ret lzma_index_append(lzma_index *i, lzma_allocator *allocator,
-		lzma_vli total_size, lzma_vli uncompressed_size);
+		lzma_vli total_size, lzma_vli uncompressed_size)
+		lzma_attr_warn_unused_result;
 
 
 /**
  * \brief       Get the number of Records
  */
-extern lzma_vli lzma_index_count(const lzma_index *i);
+extern lzma_vli lzma_index_count(const lzma_index *i) lzma_attr_pure;
 
 
 /**
@@ -105,7 +107,7 @@ extern lzma_vli lzma_index_count(const lzma_index *i);
  *
  * This is needed to verify the Index Size field from the Stream Footer.
  */
-extern lzma_vli lzma_index_size(const lzma_index *i);
+extern lzma_vli lzma_index_size(const lzma_index *i) lzma_attr_pure;
 
 
 /**
@@ -114,7 +116,7 @@ extern lzma_vli lzma_index_size(const lzma_index *i);
  * This doesn't include the Stream Header, Stream Footer, Stream Padding,
  * or Index fields.
  */
-extern lzma_vli lzma_index_total_size(const lzma_index *i);
+extern lzma_vli lzma_index_total_size(const lzma_index *i) lzma_attr_pure;
 
 
 /**
@@ -123,7 +125,7 @@ extern lzma_vli lzma_index_total_size(const lzma_index *i);
  * If multiple Indexes have been combined, this works as if the Blocks
  * were in a single Stream.
  */
-extern lzma_vli lzma_index_stream_size(const lzma_index *i);
+extern lzma_vli lzma_index_stream_size(const lzma_index *i) lzma_attr_pure;
 
 
 /**
@@ -133,19 +135,21 @@ extern lzma_vli lzma_index_stream_size(const lzma_index *i);
  * identical to lzma_index_stream_size(). If multiple Indexes have been
  * combined, this includes also the possible Stream Padding fields.
  */
-extern lzma_vli lzma_index_file_size(const lzma_index *i);
+extern lzma_vli lzma_index_file_size(const lzma_index *i) lzma_attr_pure;
 
 
 /**
  * \brief       Get the uncompressed size of the Stream
  */
-extern lzma_vli lzma_index_uncompressed_size(const lzma_index *i);
+extern lzma_vli lzma_index_uncompressed_size(const lzma_index *i)
+		lzma_attr_pure;
 
 
 /**
  * \brief       Get the next Record from the Index
  */
-extern lzma_bool lzma_index_read(lzma_index *i, lzma_index_record *record);
+extern lzma_bool lzma_index_read(lzma_index *i, lzma_index_record *record)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -179,7 +183,8 @@ extern void lzma_index_rewind(lzma_index *i);
  * and the read position are not modified, and this function returns true.
  */
 extern lzma_bool lzma_index_locate(
-		lzma_index *i, lzma_index_record *record, lzma_vli target);
+		lzma_index *i, lzma_index_record *record, lzma_vli target)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -202,7 +207,8 @@ extern lzma_bool lzma_index_locate(
  */
 extern lzma_ret lzma_index_cat(lzma_index *lzma_restrict dest,
 		lzma_index *lzma_restrict src,
-		lzma_allocator *allocator, lzma_vli padding);
+		lzma_allocator *allocator, lzma_vli padding)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -211,22 +217,26 @@ extern lzma_ret lzma_index_cat(lzma_index *lzma_restrict dest,
  * \return      A copy of the Index, or NULL if memory allocation failed.
  */
 extern lzma_index *lzma_index_dup(
-		const lzma_index *i, lzma_allocator *allocator);
+		const lzma_index *i, lzma_allocator *allocator)
+		lzma_attr_warn_unused_result;
 
 
 /**
  * \brief       Compares if two Index lists are identical
  */
-extern lzma_bool lzma_index_equal(const lzma_index *a, const lzma_index *b);
+extern lzma_bool lzma_index_equal(const lzma_index *a, const lzma_index *b)
+		lzma_attr_pure;
 
 
 /**
  * \brief       Initializes Index encoder
  */
-extern lzma_ret lzma_index_encoder(lzma_stream *strm, lzma_index *i);
+extern lzma_ret lzma_index_encoder(lzma_stream *strm, lzma_index *i)
+		lzma_attr_warn_unused_result;
 
 
 /**
  * \brief       Initializes Index decoder
  */
-extern lzma_ret lzma_index_decoder(lzma_stream *strm, lzma_index **i);
+extern lzma_ret lzma_index_decoder(lzma_stream *strm, lzma_index **i)
+		lzma_attr_warn_unused_result;
diff --git a/src/liblzma/api/lzma/index_hash.h b/src/liblzma/api/lzma/index_hash.h
index 1edbbeaa..58fc8061 100644
--- a/src/liblzma/api/lzma/index_hash.h
+++ b/src/liblzma/api/lzma/index_hash.h
@@ -42,7 +42,8 @@ typedef struct lzma_index_hash_s lzma_index_hash;
  * pointer than the index_hash given as argument.
  */
 extern lzma_index_hash *lzma_index_hash_init(
-		lzma_index_hash *index_hash, lzma_allocator *allocator);
+		lzma_index_hash *index_hash, lzma_allocator *allocator)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -66,7 +67,8 @@ extern void lzma_index_hash_end(
  *                used when lzma_index_hash_decode() has already been used.
  */
 extern lzma_ret lzma_index_hash_append(lzma_index_hash *index_hash,
-		lzma_vli total_size, lzma_vli uncompressed_size);
+		lzma_vli total_size, lzma_vli uncompressed_size)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -83,7 +85,8 @@ extern lzma_ret lzma_index_hash_append(lzma_index_hash *index_hash,
  *              Records can be added using lzma_index_hash_append().
  */
 extern lzma_ret lzma_index_hash_decode(lzma_index_hash *index_hash,
-		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_attr_warn_unused_result;
 
 
 /**
@@ -91,4 +94,5 @@ extern lzma_ret lzma_index_hash_decode(lzma_index_hash *index_hash,
  *
  * This is needed to verify the Index Size field from the Stream Footer.
  */
-extern lzma_vli lzma_index_hash_size(const lzma_index_hash *index_hash);
+extern lzma_vli lzma_index_hash_size(const lzma_index_hash *index_hash)
+		lzma_attr_pure;
diff --git a/src/liblzma/api/lzma/lzma.h b/src/liblzma/api/lzma/lzma.h
index 9473f448..5a1cd912 100644
--- a/src/liblzma/api/lzma/lzma.h
+++ b/src/liblzma/api/lzma/lzma.h
@@ -24,43 +24,11 @@
 /**
  * \brief       Filter ID
  *
- * Filter ID of the LZMA filter. This is used as lzma_options_filter.id.
+ * Filter ID of the LZMA filter. This is used as lzma_filter.id.
  */
 #define LZMA_FILTER_LZMA        LZMA_VLI_C(0x40)
 
-
-/**
- * \brief       LZMA compression modes
- *
- * Currently there are only two modes. Earlier LZMA SDKs had also third
- * mode between fast and best.
- */
-typedef enum {
-	LZMA_MODE_INVALID = -1,
-		/**<
-		 * \brief       Invalid mode
-		 *
-		 * Used as array terminator in lzma_available_modes.
-		 */
-
-
-	LZMA_MODE_FAST = 0,
-		/**<
-		 * \brief       Fast compression
-		 *
-		 * Fast mode is usually at its best when combined with
-		 * a hash chain match finder.
-		 */
-
-	LZMA_MODE_BEST = 2
-		/**<
-		 * \brief       Best compression ratio
-		 *
-		 * This is usually notably slower than fast mode. Use this
-		 * together with binary tree match finders to expose the
-		 * full potential of the LZMA encoder.
-		 */
-} lzma_mode;
+#define LZMA_FILTER_LZMA2       LZMA_VLI_C(0x21)
 
 
 /**
@@ -129,6 +97,72 @@ typedef enum {
 
 
 /**
+ * \brief       Test if given match finder is supported
+ *
+ * Returns true if the given match finder is supported by this liblzma build.
+ * Otherwise false is returned. It is safe to call this with a value that
+ * isn't listed in lzma_match_finder enumeration; the return value will be
+ * false.
+ *
+ * There is no way to list which match finders are available in this
+ * particular liblzma version and build. It would be useless, because
+ * a new match finder, which the application developer wasn't aware,
+ * could require giving additional options to the encoder that the older
+ * match finders don't need.
+ */
+extern lzma_bool lzma_mf_is_supported(lzma_match_finder match_finder)
+		lzma_attr_const;
+
+
+/**
+ * \brief       LZMA compression modes
+ *
+ * This selects the function used to analyze the data produced by the match
+ * finder.
+ */
+typedef enum {
+	LZMA_MODE_INVALID = -1,
+		/**<
+		 * \brief       Invalid mode
+		 *
+		 * Used as array terminator in lzma_available_modes.
+		 */
+
+	LZMA_MODE_FAST = 0,
+		/**<
+		 * \brief       Fast compression
+		 *
+		 * Fast mode is usually at its best when combined with
+		 * a hash chain match finder.
+		 */
+
+	LZMA_MODE_NORMAL = 1
+		/**<
+		 * \brief       Normal compression
+		 *
+		 * This is usually notably slower than fast mode. Use this
+		 * together with binary tree match finders to expose the
+		 * full potential of the LZMA encoder.
+		 */
+} lzma_mode;
+
+
+/**
+ * \brief       Test if given compression mode is supported
+ *
+ * Returns true if the given compression mode is supported by this liblzma
+ * build. Otherwise false is returned. It is safe to call this with a value
+ * that isn't listed in lzma_mode enumeration; the return value will be false.
+ *
+ * There is no way to list which modes are available in this particular
+ * liblzma version and build. It would be useless, because a new compression
+ * mode, which the application developer wasn't aware, could require giving
+ * additional options to the encoder that the older modes don't need.
+ */
+extern lzma_bool lzma_mode_is_available(lzma_mode mode) lzma_attr_const;
+
+
+/**
  * \brief       Options specific to the LZMA method handler
  */
 typedef struct {
@@ -157,6 +191,44 @@ typedef struct {
 #	define LZMA_DICTIONARY_SIZE_DEFAULT        (UINT32_C(1) << 23)
 
 	/**
+	 * \brief       Pointer to an initial dictionary
+	 *
+	 * It is possible to initialize the LZ77 history window using
+	 * a preset dictionary. Here is a good quote from zlib's
+	 * documentation; this applies to LZMA as is:
+	 *
+	 * "The dictionary should consist of strings (byte sequences) that
+	 * are likely to be encountered later in the data to be compressed,
+	 * with the most commonly used strings preferably put towards the
+	 * end of the dictionary. Using a dictionary is most useful when
+	 * the data to be compressed is short and can be predicted with
+	 * good accuracy; the data can then be compressed better than
+	 * with the default empty dictionary."
+	 * (From deflateSetDictionary() in zlib.h of zlib version 1.2.3)
+	 *
+	 * This feature should be used only in special situations.
+	 * It works correctly only with raw encoding and decoding.
+	 * Currently none of the container formats supported by
+	 * liblzma allow preset dictionary when decoding, thus if
+	 * you create a .lzma file with preset dictionary, it cannot
+	 * be decoded with the regular .lzma decoder functions.
+	 *
+	 * \todo        This feature is not implemented yet.
+	 */
+	const uint8_t *preset_dictionary;
+
+	/**
+	 * \brief       Size of the preset dictionary
+	 *
+	 * Specifies the size of the preset dictionary. If the size is
+	 * bigger than dictionary_size, only the last dictionary_size
+	 * bytes are processed.
+	 *
+	 * This variable is read only when preset_dictionary is not NULL.
+	 */
+	uint32_t preset_dictionary_size;
+
+	/**
 	 * \brief       Number of literal context bits
 	 *
 	 * How many of the highest bits of the previous uncompressed
@@ -203,47 +275,22 @@ typedef struct {
 #	define LZMA_POS_BITS_MAX                   4
 #	define LZMA_POS_BITS_DEFAULT               2
 
-	/**
-	 * \brief       Pointer to an initial dictionary
-	 *
-	 * It is possible to initialize the LZ77 history window using
-	 * a preset dictionary. Here is a good quote from zlib's
-	 * documentation; this applies to LZMA as is:
-	 *
-	 * "The dictionary should consist of strings (byte sequences) that
-	 * are likely to be encountered later in the data to be compressed,
-	 * with the most commonly used strings preferably put towards the
-	 * end of the dictionary. Using a dictionary is most useful when
-	 * the data to be compressed is short and can be predicted with
-	 * good accuracy; the data can then be compressed better than
-	 * with the default empty dictionary."
-	 * (From deflateSetDictionary() in zlib.h of zlib version 1.2.3)
-	 *
-	 * This feature should be used only in special situations.
-	 * It works correctly only with raw encoding and decoding.
-	 * Currently none of the container formats supported by
-	 * liblzma allow preset dictionary when decoding, thus if
-	 * you create a .lzma file with preset dictionary, it cannot
-	 * be decoded with the regular .lzma decoder functions.
-	 *
-	 * \todo        This feature is not implemented yet.
-	 */
-	const uint8_t *preset_dictionary;
+	/******************************************
+	 * LZMA options needed only when encoding *
+	 ******************************************/
 
 	/**
-	 * \brief       Size of the preset dictionary
+	 * \brief       Indicate if the options structure is persistent
 	 *
-	 * Specifies the size of the preset dictionary. If the size is
-	 * bigger than dictionary_size, only the last dictionary_size
-	 * bytes are processed.
+	 * If this is true, the application must keep this options structure
+	 * available after the LZMA2 encoder has been initialized. With
+	 * persistent structure it is possible to change some encoder options
+	 * in the middle of the encoding process without resetting the encoder.
 	 *
-	 * This variable is read only when preset_dictionary is not NULL.
+	 * This option is used only by LZMA2. LZMA1 ignores this and it is
+	 * safeto not initialize this when encoding with LZMA1.
 	 */
-	uint32_t preset_dictionary_size;
-
-	/******************************************
-	 * LZMA options needed only when encoding *
-	 ******************************************/
+	lzma_bool persistent;
 
 	/** LZMA compression mode */
 	lzma_mode mode;
@@ -275,6 +322,20 @@ typedef struct {
 	 */
 	uint32_t match_finder_cycles;
 
+	/**
+	 * \brief       Reserved space for possible future extensions
+	 *
+	 * You should not touch these, because the names of these variables
+	 * may change. These are and will never be used with the currently
+	 * supported options, so it is safe to leave these uninitialized.
+	 */
+	uint32_t reserved_int1;
+	uint32_t reserved_int2;
+	uint32_t reserved_int3;
+	uint32_t reserved_int4;
+	void *reserved_ptr1;
+	void *reserved_ptr2;
+
 } lzma_options_lzma;
 
 
@@ -287,27 +348,6 @@ typedef struct {
 
 
 /**
- * \brief       Available LZMA encoding modes
- *
- * Pointer to an array containing the list of available encoding modes.
- *
- * This variable is available only if LZMA encoder has been enabled.
- */
-extern const lzma_mode *const lzma_available_modes;
-
-
-/**
- * \brief       Available match finders
- *
- * Pointer to an array containing the list of available match finders.
- * The last element is LZMA_MF_INVALID.
- *
- * This variable is available only if LZMA encoder has been enabled.
- */
-extern const lzma_match_finder *const lzma_available_match_finders;
-
-
-/**
  * \brief       Table of presets for the LZMA filter
  *
  * lzma_preset_lzma[0] is the fastest and lzma_preset_lzma[8] is the slowest.
diff --git a/src/liblzma/api/lzma/memlimit.h b/src/liblzma/api/lzma/memlimit.h
index 7a856a27..836b0854 100644
--- a/src/liblzma/api/lzma/memlimit.h
+++ b/src/liblzma/api/lzma/memlimit.h
@@ -58,7 +58,8 @@ typedef struct lzma_memlimit_s lzma_memlimit;
  *              lzma_memlimit_ can be used even if lzma_init() hasn't been
  *              called.
  */
-extern lzma_memlimit *lzma_memlimit_create(size_t limit);
+extern lzma_memlimit *lzma_memlimit_create(size_t limit)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -79,7 +80,8 @@ extern void lzma_memlimit_set(lzma_memlimit *mem, size_t limit);
 /**
  * \brief       Gets the current memory usage limit
  */
-extern size_t lzma_memlimit_get(const lzma_memlimit *mem);
+extern size_t lzma_memlimit_get(const lzma_memlimit *mem)
+		lzma_attr_pure;
 
 
 /**
@@ -89,7 +91,8 @@ extern size_t lzma_memlimit_get(const lzma_memlimit *mem);
  *              thus it will always be larger than the total number of
  *              bytes allocated via lzma_memlimit_alloc().
  */
-extern size_t lzma_memlimit_used(const lzma_memlimit *mem);
+extern size_t lzma_memlimit_used(const lzma_memlimit *mem)
+		lzma_attr_pure;
 
 
 /**
@@ -134,7 +137,8 @@ extern lzma_bool lzma_memlimit_reached(lzma_memlimit *mem, lzma_bool clear);
  * been allocated with lzma_memlimit_alloc() or all memory allocated
  * has been freed or detached, this will return zero.
  */
-extern size_t lzma_memlimit_count(const lzma_memlimit *mem);
+extern size_t lzma_memlimit_count(const lzma_memlimit *mem)
+		lzma_attr_pure;
 
 
 /**
@@ -157,7 +161,8 @@ extern size_t lzma_memlimit_count(const lzma_memlimit *mem);
  *              invalid amount of memory being allocated.
  */
 extern void *lzma_memlimit_alloc(
-		lzma_memlimit *mem, size_t nmemb, size_t size);
+		lzma_memlimit *mem, size_t nmemb, size_t size)
+		lzma_attr_warn_unused_result;
 
 
 /**
diff --git a/src/liblzma/api/lzma/raw.h b/src/liblzma/api/lzma/raw.h
deleted file mode 100644
index db8cba15..00000000
--- a/src/liblzma/api/lzma/raw.h
+++ /dev/null
@@ -1,60 +0,0 @@
-/**
- * \file        lzma/raw.h
- * \brief       Raw encoder and decoder
- *
- * \author      Copyright (C) 1999-2006 Igor Pavlov
- * \author      Copyright (C) 2007 Lasse Collin
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public
- * License as published by the Free Software Foundation; either
- * version 2.1 of the License, or (at your option) any later version.
- *
- * This library is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- */
-
-#ifndef LZMA_H_INTERNAL
-#	error Never include this file directly. Use <lzma.h> instead.
-#endif
-
-
-/**
- * \brief       Initializes raw encoder
- *
- * This function may be useful when implementing custom file formats.
- *
- * \param       strm    Pointer to properly prepared lzma_stream
- * \param       options Array of lzma_options_filter structures.
- *                      The end of the array must be marked with
- *                      .id = LZMA_VLI_VALUE_UNKNOWN. The minimum
- *                      number of filters is one and the maximum is four.
- *
- * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the
- * filter chain supports it), or LZMA_FINISH.
- *
- * \return      - LZMA_OK
- *              - LZMA_MEM_ERROR
- *              - LZMA_HEADER_ERROR
- *              - LZMA_PROG_ERROR
- */
-extern lzma_ret lzma_raw_encoder(
-		lzma_stream *strm, const lzma_options_filter *options);
-
-
-/**
- * \brief       Initializes raw decoder
- *
- * The initialization of raw decoder goes similarly to raw encoder.
- *
- * The `action' with lzma_code() can be LZMA_RUN or LZMA_SYNC_FLUSH.
- *
- * \return      - LZMA_OK
- *              - LZMA_MEM_ERROR
- *              - LZMA_HEADER_ERROR
- *              - LZMA_PROG_ERROR
- */
-extern lzma_ret lzma_raw_decoder(
-		lzma_stream *strm, const lzma_options_filter *options);
diff --git a/src/liblzma/api/lzma/simple.h b/src/liblzma/api/lzma/simple.h
index 807a4c46..13417480 100644
--- a/src/liblzma/api/lzma/simple.h
+++ b/src/liblzma/api/lzma/simple.h
@@ -21,7 +21,7 @@
 #endif
 
 
-/* Filter IDs for lzma_options_filter.id */
+/* Filter IDs for lzma_filter.id */
 
 #define LZMA_FILTER_X86         LZMA_VLI_C(0x04)
 	/**<
diff --git a/src/liblzma/api/lzma/stream.h b/src/liblzma/api/lzma/stream.h
deleted file mode 100644
index 4bb17e7d..00000000
--- a/src/liblzma/api/lzma/stream.h
+++ /dev/null
@@ -1,53 +0,0 @@
-/**
- * \file        lzma/stream.h
- * \brief       .lzma Stream handling
- *
- * \author      Copyright (C) 1999-2006 Igor Pavlov
- * \author      Copyright (C) 2007 Lasse Collin
- *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public
- * License as published by the Free Software Foundation; either
- * version 2.1 of the License, or (at your option) any later version.
- *
- * This library is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- */
-
-#ifndef LZMA_H_INTERNAL
-#	error Never include this file directly. Use <lzma.h> instead.
-#endif
-
-
-/**
- * \brief       Initializes .lzma Stream encoder
- *
- * \param       strm    Pointer to properly prepared lzma_stream
- * \param       filters Array of filters. This must be terminated with
- *                      filters[n].id = LZMA_VLI_VALUE_UNKNOWN. There must
- *                      be 1-4 filters, but there are restrictions on how
- *                      multiple filters can be combined. FIXME Tell where
- *                      to find more information.
- * \param       check   Type of the integrity check to calculate from
- *                      uncompressed data.
- *
- * \return      - LZMA_OK: Initialization was successful.
- *              - LZMA_MEM_ERROR
- *              - LZMA_HEADER_ERROR
- *              - LZMA_PROG_ERROR
- */
-extern lzma_ret lzma_stream_encoder(lzma_stream *strm,
-		const lzma_options_filter *filters, lzma_check_type check);
-
-
-/**
- * \brief       Initializes decoder for .lzma Stream
- *
- * \param       strm        Pointer to propertily prepared lzma_stream
- *
- * \return      - LZMA_OK: Initialization was successful.
- *              - LZMA_MEM_ERROR: Cannot allocate memory.
- */
-extern lzma_ret lzma_stream_decoder(lzma_stream *strm);
diff --git a/src/liblzma/api/lzma/stream_flags.h b/src/liblzma/api/lzma/stream_flags.h
index f4c5c335..80c5f00f 100644
--- a/src/liblzma/api/lzma/stream_flags.h
+++ b/src/liblzma/api/lzma/stream_flags.h
@@ -46,7 +46,7 @@ typedef struct {
 	/**
 	 * Type of the Check calculated from uncompressed data
 	 */
-	lzma_check_type check;
+	lzma_check check;
 
 } lzma_stream_flags;
 
@@ -64,7 +64,8 @@ typedef struct {
  *              - LZMA_PROG_ERROR: Invalid options.
  */
 extern lzma_ret lzma_stream_header_encode(
-		const lzma_stream_flags *options, uint8_t *out);
+		const lzma_stream_flags *options, uint8_t *out)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -78,7 +79,8 @@ extern lzma_ret lzma_stream_header_encode(
  *              - LZMA_PROG_ERROR: Invalid options.
  */
 extern lzma_ret lzma_stream_footer_encode(
-		const lzma_stream_flags *options, uint8_t *out);
+		const lzma_stream_flags *options, uint8_t *out)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -101,7 +103,8 @@ extern lzma_ret lzma_stream_footer_encode(
  *                in the header.
  */
 extern lzma_ret lzma_stream_header_decode(
-		lzma_stream_flags *options, const uint8_t *in);
+		lzma_stream_flags *options, const uint8_t *in)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -120,7 +123,8 @@ extern lzma_ret lzma_stream_header_decode(
  *                in the footer.
  */
 extern lzma_ret lzma_stream_footer_decode(
-		lzma_stream_flags *options, const uint8_t *in);
+		lzma_stream_flags *options, const uint8_t *in)
+		lzma_attr_warn_unused_result;
 
 
 /**
@@ -131,4 +135,5 @@ extern lzma_ret lzma_stream_footer_decode(
  * \return      true if both structures are considered equal; false otherwise.
  */
 extern lzma_bool lzma_stream_flags_equal(
-		const lzma_stream_flags *a, lzma_stream_flags *b);
+		const lzma_stream_flags *a, const lzma_stream_flags *b)
+		lzma_attr_pure;
diff --git a/src/liblzma/api/lzma/subblock.h b/src/liblzma/api/lzma/subblock.h
index 1db35b13..b9a3025b 100644
--- a/src/liblzma/api/lzma/subblock.h
+++ b/src/liblzma/api/lzma/subblock.h
@@ -24,7 +24,7 @@
 /**
  * \brief       Filter ID
  *
- * Filter ID of the Subblock filter. This is used as lzma_options_filter.id.
+ * Filter ID of the Subblock filter. This is used as lzma_filter.id.
  */
 #define LZMA_FILTER_SUBBLOCK    LZMA_VLI_C(0x01)
 
@@ -199,6 +199,6 @@ typedef struct {
 	 *
 	 * \note        This variable is ignored if allow_subfilters is false.
 	 */
-	lzma_options_filter subfilter_options;
+	lzma_filter subfilter_options;
 
 } lzma_options_subblock;
diff --git a/src/liblzma/api/lzma/version.h b/src/liblzma/api/lzma/version.h
index 252458a3..811f93e0 100644
--- a/src/liblzma/api/lzma/version.h
+++ b/src/liblzma/api/lzma/version.h
@@ -41,17 +41,17 @@
 /**
  * \brief       liblzma version number as an integer
  *
- * This is the value of LZMA_VERSION macro at the compile time of liblzma.
+ * Returns the value of LZMA_VERSION macro at the compile time of liblzma.
  * This allows the application to compare if it was built against the same,
  * older, or newer version of liblzma that is currently running.
  */
-extern const uint32_t lzma_version_number;
+extern uint32_t lzma_version_number(void) lzma_attr_const;
 
 
 /**
- * \brief       Returns versions number of liblzma as a string
+ * \brief       Version number of liblzma as a string
  *
  * This function may be useful if you want to display which version of
- * libilzma your application is currently using.
+ * liblzma your application is currently using.
  */
-extern const char *const lzma_version_string;
+extern const char *lzma_version_string(void) lzma_attr_const;
diff --git a/src/liblzma/api/lzma/vli.h b/src/liblzma/api/lzma/vli.h
index 15a9d0bf..294e5cdd 100644
--- a/src/liblzma/api/lzma/vli.h
+++ b/src/liblzma/api/lzma/vli.h
@@ -72,90 +72,24 @@ typedef uint64_t lzma_vli;
 
 
 /**
- * \brief       Sets VLI to given value with error checking
- *
- * \param       dest    Target variable which must have type of lzma_vli.
- * \param       src     New value to be stored to dest.
- * \param       limit   Maximum allowed value for src.
- *
- * \return      False on success, true on error. If an error occurred,
- *              dest is left in undefined state (i.e. it's possible that
- *              it will be different in newer liblzma versions).
- */
-#define lzma_vli_set_lim(dest, src, limit) \
-	((src) > (limit) || ((dest) = (src)) > (limit))
-
-/**
- * \brief
- */
-#define lzma_vli_add_lim(dest, src, limit) \
-	((src) > (limit) || ((dest) += (src)) > (limit))
-
-#define lzma_vli_add2_lim(dest, src1, src2, limit) \
-	(lzma_vli_add_lim(dest, src1, limit) \
-		|| lzma_vli_add_lim(dest, src2, limit))
-
-#define lzma_vli_add3_lim(dest, src1, src2, src3, limit) \
-	(lzma_vli_add_lim(dest, src1, limit) \
-		|| lzma_vli_add_lim(dest, src2, limit) \
-		|| lzma_vli_add_lim(dest, src3, limit))
-
-#define lzma_vli_add4_lim(dest, src1, src2, src3, src4, limit) \
-	(lzma_vli_add_lim(dest, src1, limit) \
-		|| lzma_vli_add_lim(dest, src2, limit) \
-		|| lzma_vli_add_lim(dest, src3, limit) \
-		|| lzma_vli_add_lim(dest, src4, limit))
-
-#define lzma_vli_sum_lim(dest, src1, src2, limit) \
-	(lzma_vli_set_lim(dest, src1, limit) \
-		|| lzma_vli_add_lim(dest, src2, limit))
-
-#define lzma_vli_sum3_lim(dest, src1, src2, src3, limit) \
-	(lzma_vli_set_lim(dest, src1, limit) \
-		|| lzma_vli_add_lim(dest, src2, limit) \
-		|| lzma_vli_add_lim(dest, src3, limit))
-
-#define lzma_vli_sum4_lim(dest, src1, src2, src3, src4, limit) \
-	(lzma_vli_set_lim(dest, src1, limit) \
-		|| lzma_vli_add_lim(dest, src2, limit) \
-		|| lzma_vli_add_lim(dest, src3, limit) \
-		|| lzma_vli_add_lim(dest, src4, limit))
-
-#define lzma_vli_set(dest, src) lzma_vli_set_lim(dest, src, LZMA_VLI_VALUE_MAX)
-
-#define lzma_vli_add(dest, src) lzma_vli_add_lim(dest, src, LZMA_VLI_VALUE_MAX)
-
-#define lzma_vli_add2(dest, src1, src2) \
-	lzma_vli_add2_lim(dest, src1, src2, LZMA_VLI_VALUE_MAX)
-
-#define lzma_vli_add3(dest, src1, src2, src3) \
-	lzma_vli_add3_lim(dest, src1, src2, src3, LZMA_VLI_VALUE_MAX)
-
-#define lzma_vli_add4(dest, src1, src2, src3, src4) \
-	lzma_vli_add4_lim(dest, src1, src2, src3, src4, LZMA_VLI_VALUE_MAX)
-
-#define lzma_vli_sum(dest, src1, src2) \
-	lzma_vli_sum_lim(dest, src1, src2, LZMA_VLI_VALUE_MAX)
-
-#define lzma_vli_sum3(dest, src1, src2, src3) \
-	lzma_vli_sum3_lim(dest, src1, src2, src3, LZMA_VLI_VALUE_MAX)
-
-#define lzma_vli_sum4(dest, src1, src2, src3, src4) \
-	lzma_vli_sum4_lim(dest, src1, src2, src3, src4, LZMA_VLI_VALUE_MAX)
-
-
-/**
  * \brief       Encodes variable-length integer
  *
- * In the new .lzma format, most integers are encoded in variable-length
+ * In the .lzma format, most integers are encoded in variable-length
  * representation. This saves space when smaller values are more likely
  * than bigger values.
  *
  * The encoding scheme encodes seven bits to every byte, using minimum
- * number of bytes required to represent the given value. In other words,
- * it puts 7-63 bits into 1-9 bytes. This implementation limits the number
- * of bits used to 63, thus num must be at maximum of UINT64_MAX / 2. You
- * may use LZMA_VLI_VALUE_MAX for clarity.
+ * number of bytes required to represent the given value. Encodings that use
+ * non-minimum number of bytes are invalid, thus every integer has exactly
+ * one encoded representation. The maximum number of bits in a VLI is 63,
+ * thus the vli argument must be at maximum of UINT64_MAX / 2. You should
+ * use LZMA_VLI_VALUE_MAX for clarity.
+ *
+ * This function has two modes: single-call and multi-call. Single-call mode
+ * encodes the whole integer at once; it is an error if the output buffer is
+ * too small. Multi-call mode saves the position in *vli_pos, and thus it is
+ * possible to continue encoding if the buffer becomes full before the whole
+ * integer has been encoded.
  *
  * \param       vli       Integer to be encoded
  * \param       vli_pos   How many VLI-encoded bytes have already been written
@@ -170,19 +104,19 @@ typedef uint64_t lzma_vli;
  * \return      Slightly different return values are used in multi-call and
  *              single-call modes.
  *
+ *              Single-call (vli_pos == NULL):
+ *              - LZMA_OK: Integer successfully encoded.
+ *              - LZMA_PROG_ERROR: Arguments are not sane. This can be due
+ *                to too little output space; single-call mode doesn't use
+ *                LZMA_BUF_ERROR, since the application should have checked
+ *                the encoded size with lzma_vli_size().
+ *
  *              Multi-call (vli_pos != NULL):
  *              - LZMA_OK: So far all OK, but the integer is not
  *                completely written out yet.
  *              - LZMA_STREAM_END: Integer successfully encoded.
- *              - LZMA_PROG_ERROR: Arguments are not sane. This can be due
- *                to no *out_pos == out_size; this function doesn't use
- *                LZMA_BUF_ERROR.
- *
- *              Single-call (vli_pos == NULL):
- *              - LZMA_OK: Integer successfully encoded.
- *              - LZMA_PROG_ERROR: Arguments are not sane. This can be due
- *                to too little output space; this function doesn't use
- *                LZMA_BUF_ERROR.
+ *              - LZMA_BUF_ERROR: No output space was provided.
+ *              - LZMA_PROG_ERROR: Arguments are not sane.
  */
 extern lzma_ret lzma_vli_encode(
 		lzma_vli vli, size_t *lzma_restrict vli_pos,
@@ -193,6 +127,8 @@ extern lzma_ret lzma_vli_encode(
 /**
  * \brief       Decodes variable-length integer
  *
+ * Like lzma_vli_encode(), this function has single-call and multi-call modes.
+ *
  * \param       vli       Pointer to decoded integer. The decoder will
  *                        initialize it to zero when *vli_pos == 0, so
  *                        application isn't required to initialize *vli.
@@ -208,20 +144,20 @@ extern lzma_ret lzma_vli_encode(
  * \return      Slightly different return values are used in multi-call and
  *              single-call modes.
  *
+ *              Single-call (vli_pos == NULL):
+ *              - LZMA_OK: Integer successfully decoded.
+ *              - LZMA_DATA_ERROR: Integer is corrupt. This includes hitting
+ *                the end of the input buffer before the whole integer was
+ *                decoded; providing no input at all will use LZMA_DATA_ERROR.
+ *              - LZMA_PROG_ERROR: Arguments are not sane.
+ *
  *              Multi-call (vli_pos != NULL):
  *              - LZMA_OK: So far all OK, but the integer is not
  *                completely decoded yet.
  *              - LZMA_STREAM_END: Integer successfully decoded.
  *              - LZMA_DATA_ERROR: Integer is corrupt.
- *              - LZMA_PROG_ERROR: Arguments are not sane. This can be
- *                due to *in_pos == in_size; this function doesn't use
- *                LZMA_BUF_ERROR.
- *
- *              Single-call (vli_pos == NULL):
- *              - LZMA_OK: Integer successfully decoded.
- *              - LZMA_DATA_ERROR: Integer is corrupt.
- *              - LZMA_PROG_ERROR: Arguments are not sane. This can be due to
- *                too little input; this function doesn't use LZMA_BUF_ERROR.
+ *              - LZMA_BUF_ERROR: No input was provided.
+ *              - LZMA_PROG_ERROR: Arguments are not sane.
  */
 extern lzma_ret lzma_vli_decode(lzma_vli *lzma_restrict vli,
 		size_t *lzma_restrict vli_pos, const uint8_t *lzma_restrict in,
@@ -234,4 +170,5 @@ extern lzma_ret lzma_vli_decode(lzma_vli *lzma_restrict vli,
  * \return      Number of bytes on success (1-9). If vli isn't valid,
  *              zero is returned.
  */
-extern uint32_t lzma_vli_size(lzma_vli vli);
+extern uint32_t lzma_vli_size(lzma_vli vli)
+		lzma_attr_pure;