jpayne@69: /* SPDX-License-Identifier: 0BSD */ jpayne@69: jpayne@69: /** jpayne@69: * \file lzma/base.h jpayne@69: * \brief Data types and functions used in many places in liblzma API jpayne@69: * \note Never include this file directly. Use instead. 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 Boolean jpayne@69: * jpayne@69: * This is here because C89 doesn't have stdbool.h. To set a value for jpayne@69: * variables having type lzma_bool, you can use jpayne@69: * - C99's 'true' and 'false' from stdbool.h; jpayne@69: * - C++'s internal 'true' and 'false'; or jpayne@69: * - integers one (true) and zero (false). jpayne@69: */ jpayne@69: typedef unsigned char lzma_bool; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Type of reserved enumeration variable in structures jpayne@69: * jpayne@69: * To avoid breaking library ABI when new features are added, several jpayne@69: * structures contain extra variables that may be used in future. Since jpayne@69: * sizeof(enum) can be different than sizeof(int), and sizeof(enum) may jpayne@69: * even vary depending on the range of enumeration constants, we specify jpayne@69: * a separate type to be used for reserved enumeration variables. All jpayne@69: * enumeration constants in liblzma API will be non-negative and less jpayne@69: * than 128, which should guarantee that the ABI won't break even when jpayne@69: * new constants are added to existing enumerations. jpayne@69: */ jpayne@69: typedef enum { jpayne@69: LZMA_RESERVED_ENUM = 0 jpayne@69: } lzma_reserved_enum; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Return values used by several functions in liblzma jpayne@69: * jpayne@69: * Check the descriptions of specific functions to find out which return jpayne@69: * values they can return. With some functions the return values may have jpayne@69: * more specific meanings than described here; those differences are jpayne@69: * described per-function basis. jpayne@69: */ jpayne@69: typedef enum { jpayne@69: LZMA_OK = 0, jpayne@69: /**< jpayne@69: * \brief Operation completed successfully jpayne@69: */ jpayne@69: jpayne@69: LZMA_STREAM_END = 1, jpayne@69: /**< jpayne@69: * \brief End of stream was reached jpayne@69: * jpayne@69: * In encoder, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or jpayne@69: * LZMA_FINISH was finished. In decoder, this indicates jpayne@69: * that all the data was successfully decoded. jpayne@69: * jpayne@69: * In all cases, when LZMA_STREAM_END is returned, the last jpayne@69: * output bytes should be picked from strm->next_out. jpayne@69: */ jpayne@69: jpayne@69: LZMA_NO_CHECK = 2, jpayne@69: /**< jpayne@69: * \brief Input stream has no integrity check jpayne@69: * jpayne@69: * This return value can be returned only if the jpayne@69: * LZMA_TELL_NO_CHECK flag was used when initializing jpayne@69: * the decoder. LZMA_NO_CHECK is just a warning, and jpayne@69: * the decoding can be continued normally. jpayne@69: * jpayne@69: * It is possible to call lzma_get_check() immediately after jpayne@69: * lzma_code has returned LZMA_NO_CHECK. The result will jpayne@69: * naturally be LZMA_CHECK_NONE, but the possibility to call jpayne@69: * lzma_get_check() may be convenient in some applications. jpayne@69: */ jpayne@69: jpayne@69: LZMA_UNSUPPORTED_CHECK = 3, jpayne@69: /**< jpayne@69: * \brief Cannot calculate the integrity check jpayne@69: * jpayne@69: * The usage of this return value is different in encoders jpayne@69: * and decoders. jpayne@69: * jpayne@69: * Encoders can return this value only from the initialization jpayne@69: * function. If initialization fails with this value, the jpayne@69: * encoding cannot be done, because there's no way to produce jpayne@69: * output with the correct integrity check. jpayne@69: * jpayne@69: * Decoders can return this value only from lzma_code() and jpayne@69: * only if the LZMA_TELL_UNSUPPORTED_CHECK flag was used when jpayne@69: * initializing the decoder. The decoding can still be jpayne@69: * continued normally even if the check type is unsupported, jpayne@69: * but naturally the check will not be validated, and possible jpayne@69: * errors may go undetected. jpayne@69: * jpayne@69: * With decoder, it is possible to call lzma_get_check() jpayne@69: * immediately after lzma_code() has returned jpayne@69: * LZMA_UNSUPPORTED_CHECK. This way it is possible to find jpayne@69: * out what the unsupported Check ID was. jpayne@69: */ jpayne@69: jpayne@69: LZMA_GET_CHECK = 4, jpayne@69: /**< jpayne@69: * \brief Integrity check type is now available jpayne@69: * jpayne@69: * This value can be returned only by the lzma_code() function jpayne@69: * and only if the decoder was initialized with the jpayne@69: * LZMA_TELL_ANY_CHECK flag. LZMA_GET_CHECK tells the jpayne@69: * application that it may now call lzma_get_check() to find jpayne@69: * out the Check ID. This can be used, for example, to jpayne@69: * implement a decoder that accepts only files that have jpayne@69: * strong enough integrity check. jpayne@69: */ jpayne@69: jpayne@69: LZMA_MEM_ERROR = 5, jpayne@69: /**< jpayne@69: * \brief Cannot allocate memory jpayne@69: * jpayne@69: * Memory allocation failed, or the size of the allocation jpayne@69: * would be greater than SIZE_MAX. jpayne@69: * jpayne@69: * Due to internal implementation reasons, the coding cannot jpayne@69: * be continued even if more memory were made available after jpayne@69: * LZMA_MEM_ERROR. jpayne@69: */ jpayne@69: jpayne@69: LZMA_MEMLIMIT_ERROR = 6, jpayne@69: /**< jpayne@69: * \brief Memory usage limit was reached jpayne@69: * jpayne@69: * Decoder would need more memory than allowed by the jpayne@69: * specified memory usage limit. To continue decoding, jpayne@69: * the memory usage limit has to be increased with jpayne@69: * lzma_memlimit_set(). jpayne@69: * jpayne@69: * liblzma 5.2.6 and earlier had a bug in single-threaded .xz jpayne@69: * decoder (lzma_stream_decoder()) which made it impossible jpayne@69: * to continue decoding after LZMA_MEMLIMIT_ERROR even if jpayne@69: * the limit was increased using lzma_memlimit_set(). jpayne@69: * Other decoders worked correctly. jpayne@69: */ jpayne@69: jpayne@69: LZMA_FORMAT_ERROR = 7, jpayne@69: /**< jpayne@69: * \brief File format not recognized jpayne@69: * jpayne@69: * The decoder did not recognize the input as supported file jpayne@69: * format. This error can occur, for example, when trying to jpayne@69: * decode .lzma format file with lzma_stream_decoder, jpayne@69: * because lzma_stream_decoder accepts only the .xz format. jpayne@69: */ jpayne@69: jpayne@69: LZMA_OPTIONS_ERROR = 8, jpayne@69: /**< jpayne@69: * \brief Invalid or unsupported options jpayne@69: * jpayne@69: * Invalid or unsupported options, for example jpayne@69: * - unsupported filter(s) or filter options; or jpayne@69: * - reserved bits set in headers (decoder only). jpayne@69: * jpayne@69: * Rebuilding liblzma with more features enabled, or jpayne@69: * upgrading to a newer version of liblzma may help. jpayne@69: */ jpayne@69: jpayne@69: LZMA_DATA_ERROR = 9, jpayne@69: /**< jpayne@69: * \brief Data is corrupt jpayne@69: * jpayne@69: * The usage of this return value is different in encoders jpayne@69: * and decoders. In both encoder and decoder, the coding jpayne@69: * cannot continue after this error. jpayne@69: * jpayne@69: * Encoders return this if size limits of the target file jpayne@69: * format would be exceeded. These limits are huge, thus jpayne@69: * getting this error from an encoder is mostly theoretical. jpayne@69: * For example, the maximum compressed and uncompressed jpayne@69: * size of a .xz Stream is roughly 8 EiB (2^63 bytes). jpayne@69: * jpayne@69: * Decoders return this error if the input data is corrupt. jpayne@69: * This can mean, for example, invalid CRC32 in headers jpayne@69: * or invalid check of uncompressed data. jpayne@69: */ jpayne@69: jpayne@69: LZMA_BUF_ERROR = 10, jpayne@69: /**< jpayne@69: * \brief No progress is possible jpayne@69: * jpayne@69: * This error code is returned when the coder cannot consume jpayne@69: * any new input and produce any new output. The most common jpayne@69: * reason for this error is that the input stream being jpayne@69: * decoded is truncated or corrupt. jpayne@69: * jpayne@69: * This error is not fatal. Coding can be continued normally jpayne@69: * by providing more input and/or more output space, if jpayne@69: * possible. jpayne@69: * jpayne@69: * Typically the first call to lzma_code() that can do no jpayne@69: * progress returns LZMA_OK instead of LZMA_BUF_ERROR. Only jpayne@69: * the second consecutive call doing no progress will return jpayne@69: * LZMA_BUF_ERROR. This is intentional. jpayne@69: * jpayne@69: * With zlib, Z_BUF_ERROR may be returned even if the jpayne@69: * application is doing nothing wrong, so apps will need jpayne@69: * to handle Z_BUF_ERROR specially. The above hack jpayne@69: * guarantees that liblzma never returns LZMA_BUF_ERROR jpayne@69: * to properly written applications unless the input file jpayne@69: * is truncated or corrupt. This should simplify the jpayne@69: * applications a little. jpayne@69: */ jpayne@69: jpayne@69: LZMA_PROG_ERROR = 11, jpayne@69: /**< jpayne@69: * \brief Programming error jpayne@69: * jpayne@69: * This indicates that the arguments given to the function are jpayne@69: * invalid or the internal state of the decoder is corrupt. jpayne@69: * - Function arguments are invalid or the structures jpayne@69: * pointed by the argument pointers are invalid jpayne@69: * e.g. if strm->next_out has been set to NULL and jpayne@69: * strm->avail_out > 0 when calling lzma_code(). jpayne@69: * - lzma_* functions have been called in wrong order jpayne@69: * e.g. lzma_code() was called right after lzma_end(). jpayne@69: * - If errors occur randomly, the reason might be flaky jpayne@69: * hardware. jpayne@69: * jpayne@69: * If you think that your code is correct, this error code jpayne@69: * can be a sign of a bug in liblzma. See the documentation jpayne@69: * how to report bugs. jpayne@69: */ jpayne@69: jpayne@69: LZMA_SEEK_NEEDED = 12, jpayne@69: /**< jpayne@69: * \brief Request to change the input file position jpayne@69: * jpayne@69: * Some coders can do random access in the input file. The jpayne@69: * initialization functions of these coders take the file size jpayne@69: * as an argument. No other coders can return LZMA_SEEK_NEEDED. jpayne@69: * jpayne@69: * When this value is returned, the application must seek to jpayne@69: * the file position given in lzma_stream.seek_pos. This value jpayne@69: * is guaranteed to never exceed the file size that was jpayne@69: * specified at the coder initialization. jpayne@69: * jpayne@69: * After seeking the application should read new input and jpayne@69: * pass it normally via lzma_stream.next_in and .avail_in. jpayne@69: */ jpayne@69: jpayne@69: /* jpayne@69: * These enumerations may be used internally by liblzma jpayne@69: * but they will never be returned to applications. jpayne@69: */ jpayne@69: LZMA_RET_INTERNAL1 = 101, jpayne@69: LZMA_RET_INTERNAL2 = 102, jpayne@69: LZMA_RET_INTERNAL3 = 103, jpayne@69: LZMA_RET_INTERNAL4 = 104, jpayne@69: LZMA_RET_INTERNAL5 = 105, jpayne@69: LZMA_RET_INTERNAL6 = 106, jpayne@69: LZMA_RET_INTERNAL7 = 107, jpayne@69: LZMA_RET_INTERNAL8 = 108 jpayne@69: } lzma_ret; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief The 'action' argument for lzma_code() jpayne@69: * jpayne@69: * After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, LZMA_FULL_BARRIER, jpayne@69: * or LZMA_FINISH, the same 'action' must be used until lzma_code() returns jpayne@69: * LZMA_STREAM_END. Also, the amount of input (that is, strm->avail_in) must jpayne@69: * not be modified by the application until lzma_code() returns jpayne@69: * LZMA_STREAM_END. Changing the 'action' or modifying the amount of input jpayne@69: * will make lzma_code() return LZMA_PROG_ERROR. jpayne@69: */ jpayne@69: typedef enum { jpayne@69: LZMA_RUN = 0, jpayne@69: /**< jpayne@69: * \brief Continue coding jpayne@69: * jpayne@69: * Encoder: Encode as much input as possible. Some internal jpayne@69: * buffering will probably be done (depends on the filter jpayne@69: * chain in use), which causes latency: the input used won't jpayne@69: * usually be decodeable from the output of the same jpayne@69: * lzma_code() call. jpayne@69: * jpayne@69: * Decoder: Decode as much input as possible and produce as jpayne@69: * much output as possible. jpayne@69: */ jpayne@69: jpayne@69: LZMA_SYNC_FLUSH = 1, jpayne@69: /**< jpayne@69: * \brief Make all the input available at output jpayne@69: * jpayne@69: * Normally the encoder introduces some latency. jpayne@69: * LZMA_SYNC_FLUSH forces all the buffered data to be jpayne@69: * available at output without resetting the internal jpayne@69: * state of the encoder. This way it is possible to use jpayne@69: * compressed stream for example for communication over jpayne@69: * network. jpayne@69: * jpayne@69: * Only some filters support LZMA_SYNC_FLUSH. Trying to use jpayne@69: * LZMA_SYNC_FLUSH with filters that don't support it will jpayne@69: * make lzma_code() return LZMA_OPTIONS_ERROR. For example, jpayne@69: * LZMA1 doesn't support LZMA_SYNC_FLUSH but LZMA2 does. jpayne@69: * jpayne@69: * Using LZMA_SYNC_FLUSH very often can dramatically reduce jpayne@69: * the compression ratio. With some filters (for example, jpayne@69: * LZMA2), fine-tuning the compression options may help jpayne@69: * mitigate this problem significantly (for example, jpayne@69: * match finder with LZMA2). jpayne@69: * jpayne@69: * Decoders don't support LZMA_SYNC_FLUSH. jpayne@69: */ jpayne@69: jpayne@69: LZMA_FULL_FLUSH = 2, jpayne@69: /**< jpayne@69: * \brief Finish encoding of the current Block jpayne@69: * jpayne@69: * All the input data going to the current Block must have jpayne@69: * been given to the encoder (the last bytes can still be jpayne@69: * pending in *next_in). Call lzma_code() with LZMA_FULL_FLUSH jpayne@69: * until it returns LZMA_STREAM_END. Then continue normally jpayne@69: * with LZMA_RUN or finish the Stream with LZMA_FINISH. jpayne@69: * jpayne@69: * This action is currently supported only by Stream encoder jpayne@69: * and easy encoder (which uses Stream encoder). If there is jpayne@69: * no unfinished Block, no empty Block is created. jpayne@69: */ jpayne@69: jpayne@69: LZMA_FULL_BARRIER = 4, jpayne@69: /**< jpayne@69: * \brief Finish encoding of the current Block jpayne@69: * jpayne@69: * This is like LZMA_FULL_FLUSH except that this doesn't jpayne@69: * necessarily wait until all the input has been made jpayne@69: * available via the output buffer. That is, lzma_code() jpayne@69: * might return LZMA_STREAM_END as soon as all the input jpayne@69: * has been consumed (avail_in == 0). jpayne@69: * jpayne@69: * LZMA_FULL_BARRIER is useful with a threaded encoder if jpayne@69: * one wants to split the .xz Stream into Blocks at specific jpayne@69: * offsets but doesn't care if the output isn't flushed jpayne@69: * immediately. Using LZMA_FULL_BARRIER allows keeping jpayne@69: * the threads busy while LZMA_FULL_FLUSH would make jpayne@69: * lzma_code() wait until all the threads have finished jpayne@69: * until more data could be passed to the encoder. jpayne@69: * jpayne@69: * With a lzma_stream initialized with the single-threaded jpayne@69: * lzma_stream_encoder() or lzma_easy_encoder(), jpayne@69: * LZMA_FULL_BARRIER is an alias for LZMA_FULL_FLUSH. jpayne@69: */ jpayne@69: jpayne@69: LZMA_FINISH = 3 jpayne@69: /**< jpayne@69: * \brief Finish the coding operation jpayne@69: * jpayne@69: * All the input data must have been given to the encoder jpayne@69: * (the last bytes can still be pending in next_in). jpayne@69: * Call lzma_code() with LZMA_FINISH until it returns jpayne@69: * LZMA_STREAM_END. Once LZMA_FINISH has been used, jpayne@69: * the amount of input must no longer be changed by jpayne@69: * the application. jpayne@69: * jpayne@69: * When decoding, using LZMA_FINISH is optional unless the jpayne@69: * LZMA_CONCATENATED flag was used when the decoder was jpayne@69: * initialized. When LZMA_CONCATENATED was not used, the only jpayne@69: * effect of LZMA_FINISH is that the amount of input must not jpayne@69: * be changed just like in the encoder. jpayne@69: */ jpayne@69: } lzma_action; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Custom functions for memory handling jpayne@69: * jpayne@69: * A pointer to lzma_allocator may be passed via lzma_stream structure jpayne@69: * to liblzma, and some advanced functions take a pointer to lzma_allocator jpayne@69: * as a separate function argument. The library will use the functions jpayne@69: * specified in lzma_allocator for memory handling instead of the default jpayne@69: * malloc() and free(). C++ users should note that the custom memory jpayne@69: * handling functions must not throw exceptions. jpayne@69: * jpayne@69: * Single-threaded mode only: liblzma doesn't make an internal copy of jpayne@69: * lzma_allocator. Thus, it is OK to change these function pointers in jpayne@69: * the middle of the coding process, but obviously it must be done jpayne@69: * carefully to make sure that the replacement 'free' can deallocate jpayne@69: * memory allocated by the earlier 'alloc' function(s). jpayne@69: * jpayne@69: * Multithreaded mode: liblzma might internally store pointers to the jpayne@69: * lzma_allocator given via the lzma_stream structure. The application jpayne@69: * must not change the allocator pointer in lzma_stream or the contents jpayne@69: * of the pointed lzma_allocator structure until lzma_end() has been used jpayne@69: * to free the memory associated with that lzma_stream. The allocation jpayne@69: * functions might be called simultaneously from multiple threads, and jpayne@69: * thus they must be thread safe. jpayne@69: */ jpayne@69: typedef struct { jpayne@69: /** jpayne@69: * \brief Pointer to a custom memory allocation function jpayne@69: * jpayne@69: * If you don't want a custom allocator, but still want jpayne@69: * custom free(), set this to NULL and liblzma will use jpayne@69: * the standard malloc(). jpayne@69: * jpayne@69: * \param opaque lzma_allocator.opaque (see below) jpayne@69: * \param nmemb Number of elements like in calloc(). liblzma jpayne@69: * will always set nmemb to 1, so it is safe to jpayne@69: * ignore nmemb in a custom allocator if you like. jpayne@69: * The nmemb argument exists only for jpayne@69: * compatibility with zlib and libbzip2. jpayne@69: * \param size Size of an element in bytes. jpayne@69: * liblzma never sets this to zero. jpayne@69: * jpayne@69: * \return Pointer to the beginning of a memory block of jpayne@69: * 'size' bytes, or NULL if allocation fails jpayne@69: * for some reason. When allocation fails, functions jpayne@69: * of liblzma return LZMA_MEM_ERROR. jpayne@69: * jpayne@69: * The allocator should not waste time zeroing the allocated buffers. jpayne@69: * This is not only about speed, but also memory usage, since the jpayne@69: * operating system kernel doesn't necessarily allocate the requested jpayne@69: * memory in physical memory until it is actually used. With small jpayne@69: * input files, liblzma may actually need only a fraction of the jpayne@69: * memory that it requested for allocation. jpayne@69: * jpayne@69: * \note LZMA_MEM_ERROR is also used when the size of the jpayne@69: * allocation would be greater than SIZE_MAX. Thus, jpayne@69: * don't assume that the custom allocator must have jpayne@69: * returned NULL if some function from liblzma jpayne@69: * returns LZMA_MEM_ERROR. jpayne@69: */ jpayne@69: void *(LZMA_API_CALL *alloc)(void *opaque, size_t nmemb, size_t size); jpayne@69: jpayne@69: /** jpayne@69: * \brief Pointer to a custom memory freeing function jpayne@69: * jpayne@69: * If you don't want a custom freeing function, but still jpayne@69: * want a custom allocator, set this to NULL and liblzma jpayne@69: * will use the standard free(). jpayne@69: * jpayne@69: * \param opaque lzma_allocator.opaque (see below) jpayne@69: * \param ptr Pointer returned by lzma_allocator.alloc(), jpayne@69: * or when it is set to NULL, a pointer returned jpayne@69: * by the standard malloc(). jpayne@69: */ jpayne@69: void (LZMA_API_CALL *free)(void *opaque, void *ptr); jpayne@69: jpayne@69: /** jpayne@69: * \brief Pointer passed to .alloc() and .free() jpayne@69: * jpayne@69: * opaque is passed as the first argument to lzma_allocator.alloc() jpayne@69: * and lzma_allocator.free(). This intended to ease implementing jpayne@69: * custom memory allocation functions for use with liblzma. jpayne@69: * jpayne@69: * If you don't need this, you should set this to NULL. jpayne@69: */ jpayne@69: void *opaque; jpayne@69: jpayne@69: } lzma_allocator; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Internal data structure jpayne@69: * jpayne@69: * The contents of this structure is not visible outside the library. jpayne@69: */ jpayne@69: typedef struct lzma_internal_s lzma_internal; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Passing data to and from liblzma jpayne@69: * jpayne@69: * The lzma_stream structure is used for jpayne@69: * - passing pointers to input and output buffers to liblzma; jpayne@69: * - defining custom memory handler functions; and jpayne@69: * - holding a pointer to coder-specific internal data structures. jpayne@69: * jpayne@69: * Typical usage: jpayne@69: * jpayne@69: * - After allocating lzma_stream (on stack or with malloc()), it must be jpayne@69: * initialized to LZMA_STREAM_INIT (see LZMA_STREAM_INIT for details). jpayne@69: * jpayne@69: * - Initialize a coder to the lzma_stream, for example by using jpayne@69: * lzma_easy_encoder() or lzma_auto_decoder(). Some notes: jpayne@69: * - In contrast to zlib, strm->next_in and strm->next_out are jpayne@69: * ignored by all initialization functions, thus it is safe jpayne@69: * to not initialize them yet. jpayne@69: * - The initialization functions always set strm->total_in and jpayne@69: * strm->total_out to zero. jpayne@69: * - If the initialization function fails, no memory is left allocated jpayne@69: * that would require freeing with lzma_end() even if some memory was jpayne@69: * associated with the lzma_stream structure when the initialization jpayne@69: * function was called. jpayne@69: * jpayne@69: * - Use lzma_code() to do the actual work. jpayne@69: * jpayne@69: * - Once the coding has been finished, the existing lzma_stream can be jpayne@69: * reused. It is OK to reuse lzma_stream with different initialization jpayne@69: * function without calling lzma_end() first. Old allocations are jpayne@69: * automatically freed. jpayne@69: * jpayne@69: * - Finally, use lzma_end() to free the allocated memory. lzma_end() never jpayne@69: * frees the lzma_stream structure itself. jpayne@69: * jpayne@69: * Application may modify the values of total_in and total_out as it wants. jpayne@69: * They are updated by liblzma to match the amount of data read and jpayne@69: * written but aren't used for anything else except as a possible return jpayne@69: * values from lzma_get_progress(). jpayne@69: */ jpayne@69: typedef struct { jpayne@69: const uint8_t *next_in; /**< Pointer to the next input byte. */ jpayne@69: size_t avail_in; /**< Number of available input bytes in next_in. */ jpayne@69: uint64_t total_in; /**< Total number of bytes read by liblzma. */ jpayne@69: jpayne@69: uint8_t *next_out; /**< Pointer to the next output position. */ jpayne@69: size_t avail_out; /**< Amount of free space in next_out. */ jpayne@69: uint64_t total_out; /**< Total number of bytes written by liblzma. */ jpayne@69: jpayne@69: /** jpayne@69: * \brief Custom memory allocation functions jpayne@69: * jpayne@69: * In most cases this is NULL which makes liblzma use jpayne@69: * the standard malloc() and free(). jpayne@69: * jpayne@69: * \note In 5.0.x this is not a const pointer. jpayne@69: */ jpayne@69: const lzma_allocator *allocator; jpayne@69: jpayne@69: /** Internal state is not visible to applications. */ jpayne@69: lzma_internal *internal; jpayne@69: jpayne@69: /* jpayne@69: * Reserved space to allow possible future extensions without jpayne@69: * breaking the ABI. Excluding the initialization of this structure, jpayne@69: * you should not touch these, because the names of these variables jpayne@69: * may change. jpayne@69: */ jpayne@69: jpayne@69: /** \private Reserved member. */ jpayne@69: void *reserved_ptr1; jpayne@69: jpayne@69: /** \private Reserved member. */ jpayne@69: void *reserved_ptr2; jpayne@69: jpayne@69: /** \private Reserved member. */ jpayne@69: void *reserved_ptr3; jpayne@69: jpayne@69: /** \private Reserved member. */ jpayne@69: void *reserved_ptr4; jpayne@69: jpayne@69: /** jpayne@69: * \brief New seek input position for LZMA_SEEK_NEEDED jpayne@69: * jpayne@69: * When lzma_code() returns LZMA_SEEK_NEEDED, the new input position jpayne@69: * needed by liblzma will be available seek_pos. The value is jpayne@69: * guaranteed to not exceed the file size that was specified when jpayne@69: * this lzma_stream was initialized. jpayne@69: * jpayne@69: * In all other situations the value of this variable is undefined. jpayne@69: */ jpayne@69: uint64_t seek_pos; jpayne@69: jpayne@69: /** \private Reserved member. */ jpayne@69: uint64_t reserved_int2; jpayne@69: jpayne@69: /** \private Reserved member. */ jpayne@69: size_t reserved_int3; jpayne@69: jpayne@69: /** \private Reserved member. */ jpayne@69: size_t reserved_int4; jpayne@69: jpayne@69: /** \private Reserved member. */ jpayne@69: lzma_reserved_enum reserved_enum1; jpayne@69: jpayne@69: /** \private Reserved member. */ jpayne@69: lzma_reserved_enum reserved_enum2; jpayne@69: jpayne@69: } lzma_stream; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Initialization for lzma_stream jpayne@69: * jpayne@69: * When you declare an instance of lzma_stream, you can immediately jpayne@69: * initialize it so that initialization functions know that no memory jpayne@69: * has been allocated yet: jpayne@69: * jpayne@69: * lzma_stream strm = LZMA_STREAM_INIT; jpayne@69: * jpayne@69: * If you need to initialize a dynamically allocated lzma_stream, you can use jpayne@69: * memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this jpayne@69: * violates the C standard since NULL may have different internal jpayne@69: * representation than zero, but it should be portable enough in practice. jpayne@69: * Anyway, for maximum portability, you can use something like this: jpayne@69: * jpayne@69: * lzma_stream tmp = LZMA_STREAM_INIT; jpayne@69: * *strm = tmp; jpayne@69: */ jpayne@69: #define LZMA_STREAM_INIT \ jpayne@69: { NULL, 0, 0, NULL, 0, 0, NULL, NULL, \ jpayne@69: NULL, NULL, NULL, NULL, 0, 0, 0, 0, \ jpayne@69: LZMA_RESERVED_ENUM, LZMA_RESERVED_ENUM } jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Encode or decode data jpayne@69: * jpayne@69: * Once the lzma_stream has been successfully initialized (e.g. with jpayne@69: * lzma_stream_encoder()), the actual encoding or decoding is done jpayne@69: * using this function. The application has to update strm->next_in, jpayne@69: * strm->avail_in, strm->next_out, and strm->avail_out to pass input jpayne@69: * to and get output from liblzma. jpayne@69: * jpayne@69: * See the description of the coder-specific initialization function to find jpayne@69: * out what 'action' values are supported by the coder. jpayne@69: * jpayne@69: * \param strm Pointer to lzma_stream that is at least initialized jpayne@69: * with LZMA_STREAM_INIT. jpayne@69: * \param action Action for this function to take. Must be a valid jpayne@69: * lzma_action enum value. jpayne@69: * jpayne@69: * \return Any valid lzma_ret. See the lzma_ret enum description for more jpayne@69: * information. jpayne@69: */ jpayne@69: extern LZMA_API(lzma_ret) lzma_code(lzma_stream *strm, lzma_action action) jpayne@69: lzma_nothrow lzma_attr_warn_unused_result; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Free memory allocated for the coder data structures jpayne@69: * jpayne@69: * After lzma_end(strm), strm->internal is guaranteed to be NULL. No other jpayne@69: * members of the lzma_stream structure are touched. jpayne@69: * jpayne@69: * \note zlib indicates an error if application end()s unfinished jpayne@69: * stream structure. liblzma doesn't do this, and assumes that jpayne@69: * application knows what it is doing. jpayne@69: * jpayne@69: * \param strm Pointer to lzma_stream that is at least initialized jpayne@69: * with LZMA_STREAM_INIT. jpayne@69: */ jpayne@69: extern LZMA_API(void) lzma_end(lzma_stream *strm) lzma_nothrow; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Get progress information jpayne@69: * jpayne@69: * In single-threaded mode, applications can get progress information from jpayne@69: * strm->total_in and strm->total_out. In multi-threaded mode this is less jpayne@69: * useful because a significant amount of both input and output data gets jpayne@69: * buffered internally by liblzma. This makes total_in and total_out give jpayne@69: * misleading information and also makes the progress indicator updates jpayne@69: * non-smooth. jpayne@69: * jpayne@69: * This function gives realistic progress information also in multi-threaded jpayne@69: * mode by taking into account the progress made by each thread. In jpayne@69: * single-threaded mode *progress_in and *progress_out are set to jpayne@69: * strm->total_in and strm->total_out, respectively. jpayne@69: * jpayne@69: * \param strm Pointer to lzma_stream that is at least jpayne@69: * initialized with LZMA_STREAM_INIT. jpayne@69: * \param[out] progress_in Pointer to the number of input bytes processed. jpayne@69: * \param[out] progress_out Pointer to the number of output bytes processed. jpayne@69: */ jpayne@69: extern LZMA_API(void) lzma_get_progress(lzma_stream *strm, jpayne@69: uint64_t *progress_in, uint64_t *progress_out) lzma_nothrow; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Get the memory usage of decoder filter chain jpayne@69: * jpayne@69: * This function is currently supported only when *strm has been initialized jpayne@69: * with a function that takes a memlimit argument. With other functions, you jpayne@69: * should use e.g. lzma_raw_encoder_memusage() or lzma_raw_decoder_memusage() jpayne@69: * to estimate the memory requirements. jpayne@69: * jpayne@69: * This function is useful e.g. after LZMA_MEMLIMIT_ERROR to find out how big jpayne@69: * the memory usage limit should have been to decode the input. Note that jpayne@69: * this may give misleading information if decoding .xz Streams that have jpayne@69: * multiple Blocks, because each Block can have different memory requirements. jpayne@69: * jpayne@69: * \param strm Pointer to lzma_stream that is at least initialized jpayne@69: * with LZMA_STREAM_INIT. jpayne@69: * jpayne@69: * \return How much memory is currently allocated for the filter jpayne@69: * decoders. If no filter chain is currently allocated, jpayne@69: * some non-zero value is still returned, which is less than jpayne@69: * or equal to what any filter chain would indicate as its jpayne@69: * memory requirement. jpayne@69: * jpayne@69: * If this function isn't supported by *strm or some other error jpayne@69: * occurs, zero is returned. jpayne@69: */ jpayne@69: extern LZMA_API(uint64_t) lzma_memusage(const lzma_stream *strm) jpayne@69: lzma_nothrow lzma_attr_pure; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Get the current memory usage limit jpayne@69: * jpayne@69: * This function is supported only when *strm has been initialized with jpayne@69: * a function that takes a memlimit argument. jpayne@69: * jpayne@69: * \param strm Pointer to lzma_stream that is at least initialized jpayne@69: * with LZMA_STREAM_INIT. jpayne@69: * jpayne@69: * \return On success, the current memory usage limit is returned jpayne@69: * (always non-zero). On error, zero is returned. jpayne@69: */ jpayne@69: extern LZMA_API(uint64_t) lzma_memlimit_get(const lzma_stream *strm) jpayne@69: lzma_nothrow lzma_attr_pure; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * \brief Set the memory usage limit jpayne@69: * jpayne@69: * This function is supported only when *strm has been initialized with jpayne@69: * a function that takes a memlimit argument. jpayne@69: * jpayne@69: * liblzma 5.2.3 and earlier has a bug where memlimit value of 0 causes jpayne@69: * this function to do nothing (leaving the limit unchanged) and still jpayne@69: * return LZMA_OK. Later versions treat 0 as if 1 had been specified (so jpayne@69: * lzma_memlimit_get() will return 1 even if you specify 0 here). jpayne@69: * jpayne@69: * liblzma 5.2.6 and earlier had a bug in single-threaded .xz decoder jpayne@69: * (lzma_stream_decoder()) which made it impossible to continue decoding jpayne@69: * after LZMA_MEMLIMIT_ERROR even if the limit was increased using jpayne@69: * lzma_memlimit_set(). Other decoders worked correctly. jpayne@69: * jpayne@69: * \return Possible lzma_ret values: jpayne@69: * - LZMA_OK: New memory usage limit successfully set. jpayne@69: * - LZMA_MEMLIMIT_ERROR: The new limit is too small. jpayne@69: * The limit was not changed. jpayne@69: * - LZMA_PROG_ERROR: Invalid arguments, e.g. *strm doesn't jpayne@69: * support memory usage limit. jpayne@69: */ jpayne@69: extern LZMA_API(lzma_ret) lzma_memlimit_set( jpayne@69: lzma_stream *strm, uint64_t memlimit) lzma_nothrow;