jpayne@69: /* SPDX-License-Identifier: 0BSD */ jpayne@69: jpayne@69: /** jpayne@69: * \file lzma/vli.h jpayne@69: * \brief Variable-length integer handling jpayne@69: * \note Never include this file directly. Use instead. jpayne@69: * jpayne@69: * In the .xz format, most integers are encoded in a variable-length jpayne@69: * representation, which is sometimes called little endian base-128 encoding. jpayne@69: * This saves space when smaller values are more likely than bigger values. jpayne@69: * jpayne@69: * The encoding scheme encodes seven bits to every byte, using minimum jpayne@69: * number of bytes required to represent the given value. Encodings that use jpayne@69: * non-minimum number of bytes are invalid, thus every integer has exactly jpayne@69: * one encoded representation. The maximum number of bits in a VLI is 63, jpayne@69: * thus the vli argument must be less than or equal to UINT64_MAX / 2. You jpayne@69: * should use LZMA_VLI_MAX for clarity. jpayne@69: */ jpayne@69: jpayne@69: /* jpayne@69: * Author: Lasse Collin jpayne@69: */ jpayne@69: jpayne@69: #ifndef LZMA_H_INTERNAL jpayne@69: # error Never include this file directly. Use instead. jpayne@69: #endif jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Maximum supported value of a variable-length integer jpayne@69: */ jpayne@69: #define LZMA_VLI_MAX (UINT64_MAX / 2) jpayne@69: jpayne@69: /** jpayne@69: * \brief VLI value to denote that the value is unknown jpayne@69: */ jpayne@69: #define LZMA_VLI_UNKNOWN UINT64_MAX jpayne@69: jpayne@69: /** jpayne@69: * \brief Maximum supported encoded length of variable length integers jpayne@69: */ jpayne@69: #define LZMA_VLI_BYTES_MAX 9 jpayne@69: jpayne@69: /** jpayne@69: * \brief VLI constant suffix jpayne@69: */ jpayne@69: #define LZMA_VLI_C(n) UINT64_C(n) jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Variable-length integer type jpayne@69: * jpayne@69: * Valid VLI values are in the range [0, LZMA_VLI_MAX]. Unknown value is jpayne@69: * indicated with LZMA_VLI_UNKNOWN, which is the maximum value of the jpayne@69: * underlying integer type. jpayne@69: * jpayne@69: * lzma_vli will be uint64_t for the foreseeable future. If a bigger size jpayne@69: * is needed in the future, it is guaranteed that 2 * LZMA_VLI_MAX will jpayne@69: * not overflow lzma_vli. This simplifies integer overflow detection. jpayne@69: */ jpayne@69: typedef uint64_t lzma_vli; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Validate a variable-length integer jpayne@69: * jpayne@69: * This is useful to test that application has given acceptable values jpayne@69: * for example in the uncompressed_size and compressed_size variables. jpayne@69: * jpayne@69: * \return True if the integer is representable as a VLI or if it jpayne@69: * indicates an unknown value. False otherwise. jpayne@69: */ jpayne@69: #define lzma_vli_is_valid(vli) \ jpayne@69: ((vli) <= LZMA_VLI_MAX || (vli) == LZMA_VLI_UNKNOWN) jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Encode a variable-length integer jpayne@69: * jpayne@69: * This function has two modes: single-call and multi-call. Single-call mode jpayne@69: * encodes the whole integer at once; it is an error if the output buffer is jpayne@69: * too small. Multi-call mode saves the position in *vli_pos, and thus it is jpayne@69: * possible to continue encoding if the buffer becomes full before the whole jpayne@69: * integer has been encoded. jpayne@69: * jpayne@69: * \param vli Integer to be encoded jpayne@69: * \param[out] vli_pos How many VLI-encoded bytes have already been written jpayne@69: * out. When starting to encode a new integer in jpayne@69: * multi-call mode, *vli_pos must be set to zero. jpayne@69: * To use single-call encoding, set vli_pos to NULL. jpayne@69: * \param[out] out Beginning of the output buffer jpayne@69: * \param[out] out_pos The next byte will be written to out[*out_pos]. jpayne@69: * \param out_size Size of the out buffer; the first byte into jpayne@69: * which no data is written to is out[out_size]. jpayne@69: * jpayne@69: * \return Slightly different return values are used in multi-call and jpayne@69: * single-call modes. jpayne@69: * jpayne@69: * Single-call (vli_pos == NULL): jpayne@69: * - LZMA_OK: Integer successfully encoded. jpayne@69: * - LZMA_PROG_ERROR: Arguments are not sane. This can be due jpayne@69: * to too little output space; single-call mode doesn't use jpayne@69: * LZMA_BUF_ERROR, since the application should have checked jpayne@69: * the encoded size with lzma_vli_size(). jpayne@69: * jpayne@69: * Multi-call (vli_pos != NULL): jpayne@69: * - LZMA_OK: So far all OK, but the integer is not jpayne@69: * completely written out yet. jpayne@69: * - LZMA_STREAM_END: Integer successfully encoded. jpayne@69: * - LZMA_BUF_ERROR: No output space was provided. jpayne@69: * - LZMA_PROG_ERROR: Arguments are not sane. jpayne@69: */ jpayne@69: extern LZMA_API(lzma_ret) lzma_vli_encode(lzma_vli vli, size_t *vli_pos, jpayne@69: uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Decode a variable-length integer jpayne@69: * jpayne@69: * Like lzma_vli_encode(), this function has single-call and multi-call modes. jpayne@69: * jpayne@69: * \param[out] vli Pointer to decoded integer. The decoder will jpayne@69: * initialize it to zero when *vli_pos == 0, so jpayne@69: * application isn't required to initialize *vli. jpayne@69: * \param[out] vli_pos How many bytes have already been decoded. When jpayne@69: * starting to decode a new integer in multi-call jpayne@69: * mode, *vli_pos must be initialized to zero. To jpayne@69: * use single-call decoding, set vli_pos to NULL. jpayne@69: * \param in Beginning of the input buffer jpayne@69: * \param[out] in_pos The next byte will be read from in[*in_pos]. jpayne@69: * \param in_size Size of the input buffer; the first byte that jpayne@69: * won't be read is in[in_size]. jpayne@69: * jpayne@69: * \return Slightly different return values are used in multi-call and jpayne@69: * single-call modes. jpayne@69: * jpayne@69: * Single-call (vli_pos == NULL): jpayne@69: * - LZMA_OK: Integer successfully decoded. jpayne@69: * - LZMA_DATA_ERROR: Integer is corrupt. This includes hitting jpayne@69: * the end of the input buffer before the whole integer was jpayne@69: * decoded; providing no input at all will use LZMA_DATA_ERROR. jpayne@69: * - LZMA_PROG_ERROR: Arguments are not sane. jpayne@69: * jpayne@69: * Multi-call (vli_pos != NULL): jpayne@69: * - LZMA_OK: So far all OK, but the integer is not jpayne@69: * completely decoded yet. jpayne@69: * - LZMA_STREAM_END: Integer successfully decoded. jpayne@69: * - LZMA_DATA_ERROR: Integer is corrupt. jpayne@69: * - LZMA_BUF_ERROR: No input was provided. jpayne@69: * - LZMA_PROG_ERROR: Arguments are not sane. jpayne@69: */ jpayne@69: extern LZMA_API(lzma_ret) lzma_vli_decode(lzma_vli *vli, size_t *vli_pos, jpayne@69: const uint8_t *in, size_t *in_pos, size_t in_size) jpayne@69: lzma_nothrow; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Get the number of bytes required to encode a VLI jpayne@69: * jpayne@69: * \param vli Integer whose encoded size is to be determined jpayne@69: * jpayne@69: * \return Number of bytes on success (1-9). If vli isn't valid, jpayne@69: * zero is returned. jpayne@69: */ jpayne@69: extern LZMA_API(uint32_t) lzma_vli_size(lzma_vli vli) jpayne@69: lzma_nothrow lzma_attr_pure;