Google

Edit File: base.h

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