12940b44dSPeter Avalos /** 22940b44dSPeter Avalos * \file lzma/base.h 32940b44dSPeter Avalos * \brief Data types and functions used in many places in liblzma API 42940b44dSPeter Avalos */ 52940b44dSPeter Avalos 62940b44dSPeter Avalos /* 72940b44dSPeter Avalos * Author: Lasse Collin 82940b44dSPeter Avalos * 92940b44dSPeter Avalos * This file has been put into the public domain. 102940b44dSPeter Avalos * You can do whatever you want with this file. 112940b44dSPeter Avalos * 122940b44dSPeter Avalos * See ../lzma.h for information about liblzma as a whole. 132940b44dSPeter Avalos */ 142940b44dSPeter Avalos 152940b44dSPeter Avalos #ifndef LZMA_H_INTERNAL 162940b44dSPeter Avalos # error Never include this file directly. Use <lzma.h> instead. 172940b44dSPeter Avalos #endif 182940b44dSPeter Avalos 192940b44dSPeter Avalos 202940b44dSPeter Avalos /** 212940b44dSPeter Avalos * \brief Boolean 222940b44dSPeter Avalos * 232940b44dSPeter Avalos * This is here because C89 doesn't have stdbool.h. To set a value for 242940b44dSPeter Avalos * variables having type lzma_bool, you can use 252940b44dSPeter Avalos * - C99's `true' and `false' from stdbool.h; 262940b44dSPeter Avalos * - C++'s internal `true' and `false'; or 272940b44dSPeter Avalos * - integers one (true) and zero (false). 282940b44dSPeter Avalos */ 292940b44dSPeter Avalos typedef unsigned char lzma_bool; 302940b44dSPeter Avalos 312940b44dSPeter Avalos 322940b44dSPeter Avalos /** 332940b44dSPeter Avalos * \brief Type of reserved enumeration variable in structures 342940b44dSPeter Avalos * 352940b44dSPeter Avalos * To avoid breaking library ABI when new features are added, several 362940b44dSPeter Avalos * structures contain extra variables that may be used in future. Since 372940b44dSPeter Avalos * sizeof(enum) can be different than sizeof(int), and sizeof(enum) may 382940b44dSPeter Avalos * even vary depending on the range of enumeration constants, we specify 392940b44dSPeter Avalos * a separate type to be used for reserved enumeration variables. All 402940b44dSPeter Avalos * enumeration constants in liblzma API will be non-negative and less 412940b44dSPeter Avalos * than 128, which should guarantee that the ABI won't break even when 422940b44dSPeter Avalos * new constants are added to existing enumerations. 432940b44dSPeter Avalos */ 442940b44dSPeter Avalos typedef enum { 452940b44dSPeter Avalos LZMA_RESERVED_ENUM = 0 462940b44dSPeter Avalos } lzma_reserved_enum; 472940b44dSPeter Avalos 482940b44dSPeter Avalos 492940b44dSPeter Avalos /** 502940b44dSPeter Avalos * \brief Return values used by several functions in liblzma 512940b44dSPeter Avalos * 522940b44dSPeter Avalos * Check the descriptions of specific functions to find out which return 532940b44dSPeter Avalos * values they can return. With some functions the return values may have 542940b44dSPeter Avalos * more specific meanings than described here; those differences are 552940b44dSPeter Avalos * described per-function basis. 562940b44dSPeter Avalos */ 572940b44dSPeter Avalos typedef enum { 582940b44dSPeter Avalos LZMA_OK = 0, 592940b44dSPeter Avalos /**< 602940b44dSPeter Avalos * \brief Operation completed successfully 612940b44dSPeter Avalos */ 622940b44dSPeter Avalos 632940b44dSPeter Avalos LZMA_STREAM_END = 1, 642940b44dSPeter Avalos /**< 652940b44dSPeter Avalos * \brief End of stream was reached 662940b44dSPeter Avalos * 672940b44dSPeter Avalos * In encoder, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or 682940b44dSPeter Avalos * LZMA_FINISH was finished. In decoder, this indicates 692940b44dSPeter Avalos * that all the data was successfully decoded. 702940b44dSPeter Avalos * 712940b44dSPeter Avalos * In all cases, when LZMA_STREAM_END is returned, the last 722940b44dSPeter Avalos * output bytes should be picked from strm->next_out. 732940b44dSPeter Avalos */ 742940b44dSPeter Avalos 752940b44dSPeter Avalos LZMA_NO_CHECK = 2, 762940b44dSPeter Avalos /**< 772940b44dSPeter Avalos * \brief Input stream has no integrity check 782940b44dSPeter Avalos * 792940b44dSPeter Avalos * This return value can be returned only if the 802940b44dSPeter Avalos * LZMA_TELL_NO_CHECK flag was used when initializing 812940b44dSPeter Avalos * the decoder. LZMA_NO_CHECK is just a warning, and 822940b44dSPeter Avalos * the decoding can be continued normally. 832940b44dSPeter Avalos * 842940b44dSPeter Avalos * It is possible to call lzma_get_check() immediately after 852940b44dSPeter Avalos * lzma_code has returned LZMA_NO_CHECK. The result will 862940b44dSPeter Avalos * naturally be LZMA_CHECK_NONE, but the possibility to call 872940b44dSPeter Avalos * lzma_get_check() may be convenient in some applications. 882940b44dSPeter Avalos */ 892940b44dSPeter Avalos 902940b44dSPeter Avalos LZMA_UNSUPPORTED_CHECK = 3, 912940b44dSPeter Avalos /**< 922940b44dSPeter Avalos * \brief Cannot calculate the integrity check 932940b44dSPeter Avalos * 942940b44dSPeter Avalos * The usage of this return value is different in encoders 952940b44dSPeter Avalos * and decoders. 962940b44dSPeter Avalos * 972940b44dSPeter Avalos * Encoders can return this value only from the initialization 982940b44dSPeter Avalos * function. If initialization fails with this value, the 992940b44dSPeter Avalos * encoding cannot be done, because there's no way to produce 1002940b44dSPeter Avalos * output with the correct integrity check. 1012940b44dSPeter Avalos * 1022940b44dSPeter Avalos * Decoders can return this value only from lzma_code() and 1032940b44dSPeter Avalos * only if the LZMA_TELL_UNSUPPORTED_CHECK flag was used when 1042940b44dSPeter Avalos * initializing the decoder. The decoding can still be 1052940b44dSPeter Avalos * continued normally even if the check type is unsupported, 1062940b44dSPeter Avalos * but naturally the check will not be validated, and possible 1072940b44dSPeter Avalos * errors may go undetected. 1082940b44dSPeter Avalos * 1092940b44dSPeter Avalos * With decoder, it is possible to call lzma_get_check() 1102940b44dSPeter Avalos * immediately after lzma_code() has returned 1112940b44dSPeter Avalos * LZMA_UNSUPPORTED_CHECK. This way it is possible to find 1122940b44dSPeter Avalos * out what the unsupported Check ID was. 1132940b44dSPeter Avalos */ 1142940b44dSPeter Avalos 1152940b44dSPeter Avalos LZMA_GET_CHECK = 4, 1162940b44dSPeter Avalos /**< 1172940b44dSPeter Avalos * \brief Integrity check type is now available 1182940b44dSPeter Avalos * 1192940b44dSPeter Avalos * This value can be returned only by the lzma_code() function 1202940b44dSPeter Avalos * and only if the decoder was initialized with the 1212940b44dSPeter Avalos * LZMA_TELL_ANY_CHECK flag. LZMA_GET_CHECK tells the 1222940b44dSPeter Avalos * application that it may now call lzma_get_check() to find 1232940b44dSPeter Avalos * out the Check ID. This can be used, for example, to 1242940b44dSPeter Avalos * implement a decoder that accepts only files that have 1252940b44dSPeter Avalos * strong enough integrity check. 1262940b44dSPeter Avalos */ 1272940b44dSPeter Avalos 1282940b44dSPeter Avalos LZMA_MEM_ERROR = 5, 1292940b44dSPeter Avalos /**< 1302940b44dSPeter Avalos * \brief Cannot allocate memory 1312940b44dSPeter Avalos * 1322940b44dSPeter Avalos * Memory allocation failed, or the size of the allocation 1332940b44dSPeter Avalos * would be greater than SIZE_MAX. 1342940b44dSPeter Avalos * 1352940b44dSPeter Avalos * Due to internal implementation reasons, the coding cannot 1362940b44dSPeter Avalos * be continued even if more memory were made available after 1372940b44dSPeter Avalos * LZMA_MEM_ERROR. 1382940b44dSPeter Avalos */ 1392940b44dSPeter Avalos 1402940b44dSPeter Avalos LZMA_MEMLIMIT_ERROR = 6, 1412940b44dSPeter Avalos /** 1422940b44dSPeter Avalos * \brief Memory usage limit was reached 1432940b44dSPeter Avalos * 1442940b44dSPeter Avalos * Decoder would need more memory than allowed by the 1452940b44dSPeter Avalos * specified memory usage limit. To continue decoding, 1462940b44dSPeter Avalos * the memory usage limit has to be increased with 1472940b44dSPeter Avalos * lzma_memlimit_set(). 1482940b44dSPeter Avalos */ 1492940b44dSPeter Avalos 1502940b44dSPeter Avalos LZMA_FORMAT_ERROR = 7, 1512940b44dSPeter Avalos /**< 1522940b44dSPeter Avalos * \brief File format not recognized 1532940b44dSPeter Avalos * 1542940b44dSPeter Avalos * The decoder did not recognize the input as supported file 1552940b44dSPeter Avalos * format. This error can occur, for example, when trying to 1562940b44dSPeter Avalos * decode .lzma format file with lzma_stream_decoder, 1572940b44dSPeter Avalos * because lzma_stream_decoder accepts only the .xz format. 1582940b44dSPeter Avalos */ 1592940b44dSPeter Avalos 1602940b44dSPeter Avalos LZMA_OPTIONS_ERROR = 8, 1612940b44dSPeter Avalos /**< 1622940b44dSPeter Avalos * \brief Invalid or unsupported options 1632940b44dSPeter Avalos * 1642940b44dSPeter Avalos * Invalid or unsupported options, for example 1652940b44dSPeter Avalos * - unsupported filter(s) or filter options; or 1662940b44dSPeter Avalos * - reserved bits set in headers (decoder only). 1672940b44dSPeter Avalos * 1682940b44dSPeter Avalos * Rebuilding liblzma with more features enabled, or 1692940b44dSPeter Avalos * upgrading to a newer version of liblzma may help. 1702940b44dSPeter Avalos */ 1712940b44dSPeter Avalos 1722940b44dSPeter Avalos LZMA_DATA_ERROR = 9, 1732940b44dSPeter Avalos /**< 1742940b44dSPeter Avalos * \brief Data is corrupt 1752940b44dSPeter Avalos * 1762940b44dSPeter Avalos * The usage of this return value is different in encoders 1772940b44dSPeter Avalos * and decoders. In both encoder and decoder, the coding 1782940b44dSPeter Avalos * cannot continue after this error. 1792940b44dSPeter Avalos * 1802940b44dSPeter Avalos * Encoders return this if size limits of the target file 1812940b44dSPeter Avalos * format would be exceeded. These limits are huge, thus 1822940b44dSPeter Avalos * getting this error from an encoder is mostly theoretical. 1832940b44dSPeter Avalos * For example, the maximum compressed and uncompressed 1842940b44dSPeter Avalos * size of a .xz Stream is roughly 8 EiB (2^63 bytes). 1852940b44dSPeter Avalos * 1862940b44dSPeter Avalos * Decoders return this error if the input data is corrupt. 1872940b44dSPeter Avalos * This can mean, for example, invalid CRC32 in headers 1882940b44dSPeter Avalos * or invalid check of uncompressed data. 1892940b44dSPeter Avalos */ 1902940b44dSPeter Avalos 1912940b44dSPeter Avalos LZMA_BUF_ERROR = 10, 1922940b44dSPeter Avalos /**< 1932940b44dSPeter Avalos * \brief No progress is possible 1942940b44dSPeter Avalos * 1952940b44dSPeter Avalos * This error code is returned when the coder cannot consume 1962940b44dSPeter Avalos * any new input and produce any new output. The most common 1972940b44dSPeter Avalos * reason for this error is that the input stream being 1982940b44dSPeter Avalos * decoded is truncated or corrupt. 1992940b44dSPeter Avalos * 2002940b44dSPeter Avalos * This error is not fatal. Coding can be continued normally 2012940b44dSPeter Avalos * by providing more input and/or more output space, if 2022940b44dSPeter Avalos * possible. 2032940b44dSPeter Avalos * 2042940b44dSPeter Avalos * Typically the first call to lzma_code() that can do no 2052940b44dSPeter Avalos * progress returns LZMA_OK instead of LZMA_BUF_ERROR. Only 2062940b44dSPeter Avalos * the second consecutive call doing no progress will return 2072940b44dSPeter Avalos * LZMA_BUF_ERROR. This is intentional. 2082940b44dSPeter Avalos * 2092940b44dSPeter Avalos * With zlib, Z_BUF_ERROR may be returned even if the 2102940b44dSPeter Avalos * application is doing nothing wrong, so apps will need 2112940b44dSPeter Avalos * to handle Z_BUF_ERROR specially. The above hack 2122940b44dSPeter Avalos * guarantees that liblzma never returns LZMA_BUF_ERROR 2132940b44dSPeter Avalos * to properly written applications unless the input file 2142940b44dSPeter Avalos * is truncated or corrupt. This should simplify the 2152940b44dSPeter Avalos * applications a little. 2162940b44dSPeter Avalos */ 2172940b44dSPeter Avalos 2182940b44dSPeter Avalos LZMA_PROG_ERROR = 11, 2192940b44dSPeter Avalos /**< 2202940b44dSPeter Avalos * \brief Programming error 2212940b44dSPeter Avalos * 2222940b44dSPeter Avalos * This indicates that the arguments given to the function are 2232940b44dSPeter Avalos * invalid or the internal state of the decoder is corrupt. 2242940b44dSPeter Avalos * - Function arguments are invalid or the structures 2252940b44dSPeter Avalos * pointed by the argument pointers are invalid 2262940b44dSPeter Avalos * e.g. if strm->next_out has been set to NULL and 2272940b44dSPeter Avalos * strm->avail_out > 0 when calling lzma_code(). 2282940b44dSPeter Avalos * - lzma_* functions have been called in wrong order 2292940b44dSPeter Avalos * e.g. lzma_code() was called right after lzma_end(). 2302940b44dSPeter Avalos * - If errors occur randomly, the reason might be flaky 2312940b44dSPeter Avalos * hardware. 2322940b44dSPeter Avalos * 2332940b44dSPeter Avalos * If you think that your code is correct, this error code 2342940b44dSPeter Avalos * can be a sign of a bug in liblzma. See the documentation 2352940b44dSPeter Avalos * how to report bugs. 2362940b44dSPeter Avalos */ 2372940b44dSPeter Avalos } lzma_ret; 2382940b44dSPeter Avalos 2392940b44dSPeter Avalos 2402940b44dSPeter Avalos /** 2412940b44dSPeter Avalos * \brief The `action' argument for lzma_code() 2422940b44dSPeter Avalos * 24315ab8c86SJohn Marino * After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, LZMA_FULL_BARRIER, 24415ab8c86SJohn Marino * or LZMA_FINISH, the same `action' must is used until lzma_code() returns 24515ab8c86SJohn Marino * LZMA_STREAM_END. Also, the amount of input (that is, strm->avail_in) must 24615ab8c86SJohn Marino * not be modified by the application until lzma_code() returns 24715ab8c86SJohn Marino * LZMA_STREAM_END. Changing the `action' or modifying the amount of input 24815ab8c86SJohn Marino * will make lzma_code() return LZMA_PROG_ERROR. 2492940b44dSPeter Avalos */ 2502940b44dSPeter Avalos typedef enum { 2512940b44dSPeter Avalos LZMA_RUN = 0, 2522940b44dSPeter Avalos /**< 2532940b44dSPeter Avalos * \brief Continue coding 2542940b44dSPeter Avalos * 2552940b44dSPeter Avalos * Encoder: Encode as much input as possible. Some internal 2562940b44dSPeter Avalos * buffering will probably be done (depends on the filter 2572940b44dSPeter Avalos * chain in use), which causes latency: the input used won't 2582940b44dSPeter Avalos * usually be decodeable from the output of the same 2592940b44dSPeter Avalos * lzma_code() call. 2602940b44dSPeter Avalos * 2612940b44dSPeter Avalos * Decoder: Decode as much input as possible and produce as 2622940b44dSPeter Avalos * much output as possible. 2632940b44dSPeter Avalos */ 2642940b44dSPeter Avalos 2652940b44dSPeter Avalos LZMA_SYNC_FLUSH = 1, 2662940b44dSPeter Avalos /**< 2672940b44dSPeter Avalos * \brief Make all the input available at output 2682940b44dSPeter Avalos * 2692940b44dSPeter Avalos * Normally the encoder introduces some latency. 2702940b44dSPeter Avalos * LZMA_SYNC_FLUSH forces all the buffered data to be 2712940b44dSPeter Avalos * available at output without resetting the internal 2722940b44dSPeter Avalos * state of the encoder. This way it is possible to use 2732940b44dSPeter Avalos * compressed stream for example for communication over 2742940b44dSPeter Avalos * network. 2752940b44dSPeter Avalos * 2762940b44dSPeter Avalos * Only some filters support LZMA_SYNC_FLUSH. Trying to use 2772940b44dSPeter Avalos * LZMA_SYNC_FLUSH with filters that don't support it will 2782940b44dSPeter Avalos * make lzma_code() return LZMA_OPTIONS_ERROR. For example, 2792940b44dSPeter Avalos * LZMA1 doesn't support LZMA_SYNC_FLUSH but LZMA2 does. 2802940b44dSPeter Avalos * 2812940b44dSPeter Avalos * Using LZMA_SYNC_FLUSH very often can dramatically reduce 2822940b44dSPeter Avalos * the compression ratio. With some filters (for example, 2832940b44dSPeter Avalos * LZMA2), fine-tuning the compression options may help 2842940b44dSPeter Avalos * mitigate this problem significantly (for example, 2852940b44dSPeter Avalos * match finder with LZMA2). 2862940b44dSPeter Avalos * 2872940b44dSPeter Avalos * Decoders don't support LZMA_SYNC_FLUSH. 2882940b44dSPeter Avalos */ 2892940b44dSPeter Avalos 2902940b44dSPeter Avalos LZMA_FULL_FLUSH = 2, 2912940b44dSPeter Avalos /**< 2922940b44dSPeter Avalos * \brief Finish encoding of the current Block 2932940b44dSPeter Avalos * 2942940b44dSPeter Avalos * All the input data going to the current Block must have 2952940b44dSPeter Avalos * been given to the encoder (the last bytes can still be 2962940b44dSPeter Avalos * pending in *next_in). Call lzma_code() with LZMA_FULL_FLUSH 2972940b44dSPeter Avalos * until it returns LZMA_STREAM_END. Then continue normally 2982940b44dSPeter Avalos * with LZMA_RUN or finish the Stream with LZMA_FINISH. 2992940b44dSPeter Avalos * 3002940b44dSPeter Avalos * This action is currently supported only by Stream encoder 3012940b44dSPeter Avalos * and easy encoder (which uses Stream encoder). If there is 3022940b44dSPeter Avalos * no unfinished Block, no empty Block is created. 3032940b44dSPeter Avalos */ 3042940b44dSPeter Avalos 30515ab8c86SJohn Marino LZMA_FULL_BARRIER = 4, 30615ab8c86SJohn Marino /**< 30715ab8c86SJohn Marino * \brief Finish encoding of the current Block 30815ab8c86SJohn Marino * 30915ab8c86SJohn Marino * This is like LZMA_FULL_FLUSH except that this doesn't 31015ab8c86SJohn Marino * necessarily wait until all the input has been made 31115ab8c86SJohn Marino * available via the output buffer. That is, lzma_code() 31215ab8c86SJohn Marino * might return LZMA_STREAM_END as soon as all the input 31315ab8c86SJohn Marino * has been consumed (avail_in == 0). 31415ab8c86SJohn Marino * 31515ab8c86SJohn Marino * LZMA_FULL_BARRIER is useful with a threaded encoder if 31615ab8c86SJohn Marino * one wants to split the .xz Stream into Blocks at specific 31715ab8c86SJohn Marino * offsets but doesn't care if the output isn't flushed 31815ab8c86SJohn Marino * immediately. Using LZMA_FULL_BARRIER allows keeping 31915ab8c86SJohn Marino * the threads busy while LZMA_FULL_FLUSH would make 32015ab8c86SJohn Marino * lzma_code() wait until all the threads have finished 32115ab8c86SJohn Marino * until more data could be passed to the encoder. 32215ab8c86SJohn Marino * 32315ab8c86SJohn Marino * With a lzma_stream initialized with the single-threaded 32415ab8c86SJohn Marino * lzma_stream_encoder() or lzma_easy_encoder(), 32515ab8c86SJohn Marino * LZMA_FULL_BARRIER is an alias for LZMA_FULL_FLUSH. 32615ab8c86SJohn Marino */ 32715ab8c86SJohn Marino 3282940b44dSPeter Avalos LZMA_FINISH = 3 3292940b44dSPeter Avalos /**< 3302940b44dSPeter Avalos * \brief Finish the coding operation 3312940b44dSPeter Avalos * 3322940b44dSPeter Avalos * All the input data must have been given to the encoder 3332940b44dSPeter Avalos * (the last bytes can still be pending in next_in). 3342940b44dSPeter Avalos * Call lzma_code() with LZMA_FINISH until it returns 3352940b44dSPeter Avalos * LZMA_STREAM_END. Once LZMA_FINISH has been used, 3362940b44dSPeter Avalos * the amount of input must no longer be changed by 3372940b44dSPeter Avalos * the application. 3382940b44dSPeter Avalos * 3392940b44dSPeter Avalos * When decoding, using LZMA_FINISH is optional unless the 3402940b44dSPeter Avalos * LZMA_CONCATENATED flag was used when the decoder was 3412940b44dSPeter Avalos * initialized. When LZMA_CONCATENATED was not used, the only 3422940b44dSPeter Avalos * effect of LZMA_FINISH is that the amount of input must not 3432940b44dSPeter Avalos * be changed just like in the encoder. 3442940b44dSPeter Avalos */ 3452940b44dSPeter Avalos } lzma_action; 3462940b44dSPeter Avalos 3472940b44dSPeter Avalos 3482940b44dSPeter Avalos /** 3492940b44dSPeter Avalos * \brief Custom functions for memory handling 3502940b44dSPeter Avalos * 3512940b44dSPeter Avalos * A pointer to lzma_allocator may be passed via lzma_stream structure 3522940b44dSPeter Avalos * to liblzma, and some advanced functions take a pointer to lzma_allocator 3532940b44dSPeter Avalos * as a separate function argument. The library will use the functions 3542940b44dSPeter Avalos * specified in lzma_allocator for memory handling instead of the default 3552940b44dSPeter Avalos * malloc() and free(). C++ users should note that the custom memory 3562940b44dSPeter Avalos * handling functions must not throw exceptions. 3572940b44dSPeter Avalos * 35815ab8c86SJohn Marino * Single-threaded mode only: liblzma doesn't make an internal copy of 35915ab8c86SJohn Marino * lzma_allocator. Thus, it is OK to change these function pointers in 36015ab8c86SJohn Marino * the middle of the coding process, but obviously it must be done 36115ab8c86SJohn Marino * carefully to make sure that the replacement `free' can deallocate 36215ab8c86SJohn Marino * memory allocated by the earlier `alloc' function(s). 36315ab8c86SJohn Marino * 36415ab8c86SJohn Marino * Multithreaded mode: liblzma might internally store pointers to the 36515ab8c86SJohn Marino * lzma_allocator given via the lzma_stream structure. The application 36615ab8c86SJohn Marino * must not change the allocator pointer in lzma_stream or the contents 36715ab8c86SJohn Marino * of the pointed lzma_allocator structure until lzma_end() has been used 36815ab8c86SJohn Marino * to free the memory associated with that lzma_stream. The allocation 36915ab8c86SJohn Marino * functions might be called simultaneously from multiple threads, and 37015ab8c86SJohn Marino * thus they must be thread safe. 3712940b44dSPeter Avalos */ 3722940b44dSPeter Avalos typedef struct { 3732940b44dSPeter Avalos /** 3742940b44dSPeter Avalos * \brief Pointer to a custom memory allocation function 3752940b44dSPeter Avalos * 3762940b44dSPeter Avalos * If you don't want a custom allocator, but still want 3772940b44dSPeter Avalos * custom free(), set this to NULL and liblzma will use 3782940b44dSPeter Avalos * the standard malloc(). 3792940b44dSPeter Avalos * 3802940b44dSPeter Avalos * \param opaque lzma_allocator.opaque (see below) 3812940b44dSPeter Avalos * \param nmemb Number of elements like in calloc(). liblzma 3822940b44dSPeter Avalos * will always set nmemb to 1, so it is safe to 3832940b44dSPeter Avalos * ignore nmemb in a custom allocator if you like. 3842940b44dSPeter Avalos * The nmemb argument exists only for 3852940b44dSPeter Avalos * compatibility with zlib and libbzip2. 3862940b44dSPeter Avalos * \param size Size of an element in bytes. 3872940b44dSPeter Avalos * liblzma never sets this to zero. 3882940b44dSPeter Avalos * 3892940b44dSPeter Avalos * \return Pointer to the beginning of a memory block of 3902940b44dSPeter Avalos * `size' bytes, or NULL if allocation fails 3912940b44dSPeter Avalos * for some reason. When allocation fails, functions 3922940b44dSPeter Avalos * of liblzma return LZMA_MEM_ERROR. 3932940b44dSPeter Avalos * 3942940b44dSPeter Avalos * The allocator should not waste time zeroing the allocated buffers. 3952940b44dSPeter Avalos * This is not only about speed, but also memory usage, since the 3962940b44dSPeter Avalos * operating system kernel doesn't necessarily allocate the requested 3972940b44dSPeter Avalos * memory in physical memory until it is actually used. With small 3982940b44dSPeter Avalos * input files, liblzma may actually need only a fraction of the 3992940b44dSPeter Avalos * memory that it requested for allocation. 4002940b44dSPeter Avalos * 4012940b44dSPeter Avalos * \note LZMA_MEM_ERROR is also used when the size of the 4022940b44dSPeter Avalos * allocation would be greater than SIZE_MAX. Thus, 4032940b44dSPeter Avalos * don't assume that the custom allocator must have 4042940b44dSPeter Avalos * returned NULL if some function from liblzma 4052940b44dSPeter Avalos * returns LZMA_MEM_ERROR. 4062940b44dSPeter Avalos */ 4072940b44dSPeter Avalos void *(LZMA_API_CALL *alloc)(void *opaque, size_t nmemb, size_t size); 4082940b44dSPeter Avalos 4092940b44dSPeter Avalos /** 4102940b44dSPeter Avalos * \brief Pointer to a custom memory freeing function 4112940b44dSPeter Avalos * 4122940b44dSPeter Avalos * If you don't want a custom freeing function, but still 4132940b44dSPeter Avalos * want a custom allocator, set this to NULL and liblzma 4142940b44dSPeter Avalos * will use the standard free(). 4152940b44dSPeter Avalos * 4162940b44dSPeter Avalos * \param opaque lzma_allocator.opaque (see below) 4172940b44dSPeter Avalos * \param ptr Pointer returned by lzma_allocator.alloc(), 4182940b44dSPeter Avalos * or when it is set to NULL, a pointer returned 4192940b44dSPeter Avalos * by the standard malloc(). 4202940b44dSPeter Avalos */ 4212940b44dSPeter Avalos void (LZMA_API_CALL *free)(void *opaque, void *ptr); 4222940b44dSPeter Avalos 4232940b44dSPeter Avalos /** 4242940b44dSPeter Avalos * \brief Pointer passed to .alloc() and .free() 4252940b44dSPeter Avalos * 4262940b44dSPeter Avalos * opaque is passed as the first argument to lzma_allocator.alloc() 4272940b44dSPeter Avalos * and lzma_allocator.free(). This intended to ease implementing 4282940b44dSPeter Avalos * custom memory allocation functions for use with liblzma. 4292940b44dSPeter Avalos * 4302940b44dSPeter Avalos * If you don't need this, you should set this to NULL. 4312940b44dSPeter Avalos */ 4322940b44dSPeter Avalos void *opaque; 4332940b44dSPeter Avalos 4342940b44dSPeter Avalos } lzma_allocator; 4352940b44dSPeter Avalos 4362940b44dSPeter Avalos 4372940b44dSPeter Avalos /** 4382940b44dSPeter Avalos * \brief Internal data structure 4392940b44dSPeter Avalos * 4402940b44dSPeter Avalos * The contents of this structure is not visible outside the library. 4412940b44dSPeter Avalos */ 4422940b44dSPeter Avalos typedef struct lzma_internal_s lzma_internal; 4432940b44dSPeter Avalos 4442940b44dSPeter Avalos 4452940b44dSPeter Avalos /** 4462940b44dSPeter Avalos * \brief Passing data to and from liblzma 4472940b44dSPeter Avalos * 4482940b44dSPeter Avalos * The lzma_stream structure is used for 4492940b44dSPeter Avalos * - passing pointers to input and output buffers to liblzma; 4502940b44dSPeter Avalos * - defining custom memory hander functions; and 4512940b44dSPeter Avalos * - holding a pointer to coder-specific internal data structures. 4522940b44dSPeter Avalos * 4532940b44dSPeter Avalos * Typical usage: 4542940b44dSPeter Avalos * 4552940b44dSPeter Avalos * - After allocating lzma_stream (on stack or with malloc()), it must be 4562940b44dSPeter Avalos * initialized to LZMA_STREAM_INIT (see LZMA_STREAM_INIT for details). 4572940b44dSPeter Avalos * 4582940b44dSPeter Avalos * - Initialize a coder to the lzma_stream, for example by using 4592940b44dSPeter Avalos * lzma_easy_encoder() or lzma_auto_decoder(). Some notes: 4602940b44dSPeter Avalos * - In contrast to zlib, strm->next_in and strm->next_out are 4612940b44dSPeter Avalos * ignored by all initialization functions, thus it is safe 4622940b44dSPeter Avalos * to not initialize them yet. 4632940b44dSPeter Avalos * - The initialization functions always set strm->total_in and 4642940b44dSPeter Avalos * strm->total_out to zero. 4652940b44dSPeter Avalos * - If the initialization function fails, no memory is left allocated 4662940b44dSPeter Avalos * that would require freeing with lzma_end() even if some memory was 4672940b44dSPeter Avalos * associated with the lzma_stream structure when the initialization 4682940b44dSPeter Avalos * function was called. 4692940b44dSPeter Avalos * 4702940b44dSPeter Avalos * - Use lzma_code() to do the actual work. 4712940b44dSPeter Avalos * 4722940b44dSPeter Avalos * - Once the coding has been finished, the existing lzma_stream can be 4732940b44dSPeter Avalos * reused. It is OK to reuse lzma_stream with different initialization 4742940b44dSPeter Avalos * function without calling lzma_end() first. Old allocations are 4752940b44dSPeter Avalos * automatically freed. 4762940b44dSPeter Avalos * 4772940b44dSPeter Avalos * - Finally, use lzma_end() to free the allocated memory. lzma_end() never 4782940b44dSPeter Avalos * frees the lzma_stream structure itself. 4792940b44dSPeter Avalos * 4802940b44dSPeter Avalos * Application may modify the values of total_in and total_out as it wants. 4812940b44dSPeter Avalos * They are updated by liblzma to match the amount of data read and 48215ab8c86SJohn Marino * written but aren't used for anything else except as a possible return 48315ab8c86SJohn Marino * values from lzma_get_progress(). 4842940b44dSPeter Avalos */ 4852940b44dSPeter Avalos typedef struct { 4862940b44dSPeter Avalos const uint8_t *next_in; /**< Pointer to the next input byte. */ 4872940b44dSPeter Avalos size_t avail_in; /**< Number of available input bytes in next_in. */ 4882940b44dSPeter Avalos uint64_t total_in; /**< Total number of bytes read by liblzma. */ 4892940b44dSPeter Avalos 4902940b44dSPeter Avalos uint8_t *next_out; /**< Pointer to the next output position. */ 4912940b44dSPeter Avalos size_t avail_out; /**< Amount of free space in next_out. */ 4922940b44dSPeter Avalos uint64_t total_out; /**< Total number of bytes written by liblzma. */ 4932940b44dSPeter Avalos 4942940b44dSPeter Avalos /** 4952940b44dSPeter Avalos * \brief Custom memory allocation functions 4962940b44dSPeter Avalos * 4972940b44dSPeter Avalos * In most cases this is NULL which makes liblzma use 4982940b44dSPeter Avalos * the standard malloc() and free(). 49915ab8c86SJohn Marino * 50015ab8c86SJohn Marino * \note In 5.0.x this is not a const pointer. 5012940b44dSPeter Avalos */ 50215ab8c86SJohn Marino const lzma_allocator *allocator; 5032940b44dSPeter Avalos 5042940b44dSPeter Avalos /** Internal state is not visible to applications. */ 5052940b44dSPeter Avalos lzma_internal *internal; 5062940b44dSPeter Avalos 5072940b44dSPeter Avalos /* 5082940b44dSPeter Avalos * Reserved space to allow possible future extensions without 5092940b44dSPeter Avalos * breaking the ABI. Excluding the initialization of this structure, 5102940b44dSPeter Avalos * you should not touch these, because the names of these variables 5112940b44dSPeter Avalos * may change. 5122940b44dSPeter Avalos */ 5132940b44dSPeter Avalos void *reserved_ptr1; 5142940b44dSPeter Avalos void *reserved_ptr2; 5152940b44dSPeter Avalos void *reserved_ptr3; 5162940b44dSPeter Avalos void *reserved_ptr4; 5172940b44dSPeter Avalos uint64_t reserved_int1; 5182940b44dSPeter Avalos uint64_t reserved_int2; 5192940b44dSPeter Avalos size_t reserved_int3; 5202940b44dSPeter Avalos size_t reserved_int4; 5212940b44dSPeter Avalos lzma_reserved_enum reserved_enum1; 5222940b44dSPeter Avalos lzma_reserved_enum reserved_enum2; 5232940b44dSPeter Avalos 5242940b44dSPeter Avalos } lzma_stream; 5252940b44dSPeter Avalos 5262940b44dSPeter Avalos 5272940b44dSPeter Avalos /** 5282940b44dSPeter Avalos * \brief Initialization for lzma_stream 5292940b44dSPeter Avalos * 5302940b44dSPeter Avalos * When you declare an instance of lzma_stream, you can immediately 5312940b44dSPeter Avalos * initialize it so that initialization functions know that no memory 5322940b44dSPeter Avalos * has been allocated yet: 5332940b44dSPeter Avalos * 5342940b44dSPeter Avalos * lzma_stream strm = LZMA_STREAM_INIT; 5352940b44dSPeter Avalos * 5362940b44dSPeter Avalos * If you need to initialize a dynamically allocated lzma_stream, you can use 5372940b44dSPeter Avalos * memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this 5382940b44dSPeter Avalos * violates the C standard since NULL may have different internal 5392940b44dSPeter Avalos * representation than zero, but it should be portable enough in practice. 5402940b44dSPeter Avalos * Anyway, for maximum portability, you can use something like this: 5412940b44dSPeter Avalos * 5422940b44dSPeter Avalos * lzma_stream tmp = LZMA_STREAM_INIT; 5432940b44dSPeter Avalos * *strm = tmp; 5442940b44dSPeter Avalos */ 5452940b44dSPeter Avalos #define LZMA_STREAM_INIT \ 5462940b44dSPeter Avalos { NULL, 0, 0, NULL, 0, 0, NULL, NULL, \ 5472940b44dSPeter Avalos NULL, NULL, NULL, NULL, 0, 0, 0, 0, \ 5482940b44dSPeter Avalos LZMA_RESERVED_ENUM, LZMA_RESERVED_ENUM } 5492940b44dSPeter Avalos 5502940b44dSPeter Avalos 5512940b44dSPeter Avalos /** 5522940b44dSPeter Avalos * \brief Encode or decode data 5532940b44dSPeter Avalos * 5542940b44dSPeter Avalos * Once the lzma_stream has been successfully initialized (e.g. with 5552940b44dSPeter Avalos * lzma_stream_encoder()), the actual encoding or decoding is done 5562940b44dSPeter Avalos * using this function. The application has to update strm->next_in, 5572940b44dSPeter Avalos * strm->avail_in, strm->next_out, and strm->avail_out to pass input 5582940b44dSPeter Avalos * to and get output from liblzma. 5592940b44dSPeter Avalos * 5602940b44dSPeter Avalos * See the description of the coder-specific initialization function to find 5612940b44dSPeter Avalos * out what `action' values are supported by the coder. 5622940b44dSPeter Avalos */ 5632940b44dSPeter Avalos extern LZMA_API(lzma_ret) lzma_code(lzma_stream *strm, lzma_action action) 5642940b44dSPeter Avalos lzma_nothrow lzma_attr_warn_unused_result; 5652940b44dSPeter Avalos 5662940b44dSPeter Avalos 5672940b44dSPeter Avalos /** 5682940b44dSPeter Avalos * \brief Free memory allocated for the coder data structures 5692940b44dSPeter Avalos * 5702940b44dSPeter Avalos * \param strm Pointer to lzma_stream that is at least initialized 5712940b44dSPeter Avalos * with LZMA_STREAM_INIT. 5722940b44dSPeter Avalos * 5732940b44dSPeter Avalos * After lzma_end(strm), strm->internal is guaranteed to be NULL. No other 5742940b44dSPeter Avalos * members of the lzma_stream structure are touched. 5752940b44dSPeter Avalos * 5762940b44dSPeter Avalos * \note zlib indicates an error if application end()s unfinished 5772940b44dSPeter Avalos * stream structure. liblzma doesn't do this, and assumes that 5782940b44dSPeter Avalos * application knows what it is doing. 5792940b44dSPeter Avalos */ 5802940b44dSPeter Avalos extern LZMA_API(void) lzma_end(lzma_stream *strm) lzma_nothrow; 5812940b44dSPeter Avalos 5822940b44dSPeter Avalos 5832940b44dSPeter Avalos /** 58415ab8c86SJohn Marino * \brief Get progress information 58515ab8c86SJohn Marino * 58615ab8c86SJohn Marino * In single-threaded mode, applications can get progress information from 58715ab8c86SJohn Marino * strm->total_in and strm->total_out. In multi-threaded mode this is less 58815ab8c86SJohn Marino * useful because a significant amount of both input and output data gets 58915ab8c86SJohn Marino * buffered internally by liblzma. This makes total_in and total_out give 59015ab8c86SJohn Marino * misleading information and also makes the progress indicator updates 59115ab8c86SJohn Marino * non-smooth. 59215ab8c86SJohn Marino * 59315ab8c86SJohn Marino * This function gives realistic progress information also in multi-threaded 59415ab8c86SJohn Marino * mode by taking into account the progress made by each thread. In 59515ab8c86SJohn Marino * single-threaded mode *progress_in and *progress_out are set to 59615ab8c86SJohn Marino * strm->total_in and strm->total_out, respectively. 59715ab8c86SJohn Marino */ 59815ab8c86SJohn Marino extern LZMA_API(void) lzma_get_progress(lzma_stream *strm, 59915ab8c86SJohn Marino uint64_t *progress_in, uint64_t *progress_out) lzma_nothrow; 60015ab8c86SJohn Marino 60115ab8c86SJohn Marino 60215ab8c86SJohn Marino /** 6032940b44dSPeter Avalos * \brief Get the memory usage of decoder filter chain 6042940b44dSPeter Avalos * 6052940b44dSPeter Avalos * This function is currently supported only when *strm has been initialized 6062940b44dSPeter Avalos * with a function that takes a memlimit argument. With other functions, you 6072940b44dSPeter Avalos * should use e.g. lzma_raw_encoder_memusage() or lzma_raw_decoder_memusage() 6082940b44dSPeter Avalos * to estimate the memory requirements. 6092940b44dSPeter Avalos * 6102940b44dSPeter Avalos * This function is useful e.g. after LZMA_MEMLIMIT_ERROR to find out how big 6112940b44dSPeter Avalos * the memory usage limit should have been to decode the input. Note that 6122940b44dSPeter Avalos * this may give misleading information if decoding .xz Streams that have 6132940b44dSPeter Avalos * multiple Blocks, because each Block can have different memory requirements. 6142940b44dSPeter Avalos * 6152940b44dSPeter Avalos * \return How much memory is currently allocated for the filter 6162940b44dSPeter Avalos * decoders. If no filter chain is currently allocated, 6172940b44dSPeter Avalos * some non-zero value is still returned, which is less than 6182940b44dSPeter Avalos * or equal to what any filter chain would indicate as its 6192940b44dSPeter Avalos * memory requirement. 6202940b44dSPeter Avalos * 6212940b44dSPeter Avalos * If this function isn't supported by *strm or some other error 6222940b44dSPeter Avalos * occurs, zero is returned. 6232940b44dSPeter Avalos */ 6242940b44dSPeter Avalos extern LZMA_API(uint64_t) lzma_memusage(const lzma_stream *strm) 6252940b44dSPeter Avalos lzma_nothrow lzma_attr_pure; 6262940b44dSPeter Avalos 6272940b44dSPeter Avalos 6282940b44dSPeter Avalos /** 6292940b44dSPeter Avalos * \brief Get the current memory usage limit 6302940b44dSPeter Avalos * 6312940b44dSPeter Avalos * This function is supported only when *strm has been initialized with 6322940b44dSPeter Avalos * a function that takes a memlimit argument. 6332940b44dSPeter Avalos * 6342940b44dSPeter Avalos * \return On success, the current memory usage limit is returned 6352940b44dSPeter Avalos * (always non-zero). On error, zero is returned. 6362940b44dSPeter Avalos */ 6372940b44dSPeter Avalos extern LZMA_API(uint64_t) lzma_memlimit_get(const lzma_stream *strm) 6382940b44dSPeter Avalos lzma_nothrow lzma_attr_pure; 6392940b44dSPeter Avalos 6402940b44dSPeter Avalos 6412940b44dSPeter Avalos /** 6422940b44dSPeter Avalos * \brief Set the memory usage limit 6432940b44dSPeter Avalos * 6442940b44dSPeter Avalos * This function is supported only when *strm has been initialized with 6452940b44dSPeter Avalos * a function that takes a memlimit argument. 6462940b44dSPeter Avalos * 647*46a2189dSzrj * liblzma 5.2.3 and earlier has a bug where memlimit value of 0 causes 648*46a2189dSzrj * this function to do nothing (leaving the limit unchanged) and still 649*46a2189dSzrj * return LZMA_OK. Later versions treat 0 as if 1 had been specified (so 650*46a2189dSzrj * lzma_memlimit_get() will return 1 even if you specify 0 here). 651*46a2189dSzrj * 6522940b44dSPeter Avalos * \return - LZMA_OK: New memory usage limit successfully set. 6532940b44dSPeter Avalos * - LZMA_MEMLIMIT_ERROR: The new limit is too small. 6542940b44dSPeter Avalos * The limit was not changed. 6552940b44dSPeter Avalos * - LZMA_PROG_ERROR: Invalid arguments, e.g. *strm doesn't 656*46a2189dSzrj * support memory usage limit. 6572940b44dSPeter Avalos */ 6582940b44dSPeter Avalos extern LZMA_API(lzma_ret) lzma_memlimit_set( 6592940b44dSPeter Avalos lzma_stream *strm, uint64_t memlimit) lzma_nothrow; 660