153200025SRui Paulo /** 253200025SRui Paulo * \file lzma/lzma12.h 353200025SRui Paulo * \brief LZMA1 and LZMA2 filters 4c917796cSXin LI * \note Never include this file directly. Use <lzma.h> instead. 553200025SRui Paulo */ 653200025SRui Paulo 753200025SRui Paulo /* 853200025SRui Paulo * Author: Lasse Collin 92f9cd13dSXin LI * 102f9cd13dSXin LI * This file has been put into the public domain. 112f9cd13dSXin LI * You can do whatever you want with this file. 1253200025SRui Paulo */ 1353200025SRui Paulo 1453200025SRui Paulo #ifndef LZMA_H_INTERNAL 1553200025SRui Paulo # error Never include this file directly. Use <lzma.h> instead. 1653200025SRui Paulo #endif 1753200025SRui Paulo 1853200025SRui Paulo 1953200025SRui Paulo /** 2073ed8e77SXin LI * \brief LZMA1 Filter ID (for raw encoder/decoder only, not in .xz) 2153200025SRui Paulo * 2253200025SRui Paulo * LZMA1 is the very same thing as what was called just LZMA in LZMA Utils, 2353200025SRui Paulo * 7-Zip, and LZMA SDK. It's called LZMA1 here to prevent developers from 2453200025SRui Paulo * accidentally using LZMA when they actually want LZMA2. 2553200025SRui Paulo */ 2653200025SRui Paulo #define LZMA_FILTER_LZMA1 LZMA_VLI_C(0x4000000000000001) 2753200025SRui Paulo 2853200025SRui Paulo /** 2973ed8e77SXin LI * \brief LZMA1 Filter ID with extended options (for raw encoder/decoder) 3073ed8e77SXin LI * 3173ed8e77SXin LI * This is like LZMA_FILTER_LZMA1 but with this ID a few extra options 3273ed8e77SXin LI * are supported in the lzma_options_lzma structure: 3373ed8e77SXin LI * 3473ed8e77SXin LI * - A flag to tell the encoder if the end of payload marker (EOPM) alias 3573ed8e77SXin LI * end of stream (EOS) marker must be written at the end of the stream. 3673ed8e77SXin LI * In contrast, LZMA_FILTER_LZMA1 always writes the end marker. 3773ed8e77SXin LI * 3873ed8e77SXin LI * - Decoder needs to be told the uncompressed size of the stream 3973ed8e77SXin LI * or that it is unknown (using the special value UINT64_MAX). 4073ed8e77SXin LI * If the size is known, a flag can be set to allow the presence of 4173ed8e77SXin LI * the end marker anyway. In contrast, LZMA_FILTER_LZMA1 always 4273ed8e77SXin LI * behaves as if the uncompressed size was unknown. 4373ed8e77SXin LI * 4473ed8e77SXin LI * This allows handling file formats where LZMA1 streams are used but where 4573ed8e77SXin LI * the end marker isn't allowed or where it might not (always) be present. 4673ed8e77SXin LI * This extended LZMA1 functionality is provided as a Filter ID for raw 4773ed8e77SXin LI * encoder and decoder instead of adding new encoder and decoder initialization 4873ed8e77SXin LI * functions because this way it is possible to also use extra filters, 4973ed8e77SXin LI * for example, LZMA_FILTER_X86 in a filter chain with LZMA_FILTER_LZMA1EXT, 5073ed8e77SXin LI * which might be needed to handle some file formats. 5173ed8e77SXin LI */ 5273ed8e77SXin LI #define LZMA_FILTER_LZMA1EXT LZMA_VLI_C(0x4000000000000002) 5373ed8e77SXin LI 5473ed8e77SXin LI /** 5553200025SRui Paulo * \brief LZMA2 Filter ID 5653200025SRui Paulo * 5753200025SRui Paulo * Usually you want this instead of LZMA1. Compared to LZMA1, LZMA2 adds 5853200025SRui Paulo * support for LZMA_SYNC_FLUSH, uncompressed chunks (smaller expansion 591f3ced26SXin LI * when trying to compress incompressible data), possibility to change 6053200025SRui Paulo * lc/lp/pb in the middle of encoding, and some other internal improvements. 6153200025SRui Paulo */ 6253200025SRui Paulo #define LZMA_FILTER_LZMA2 LZMA_VLI_C(0x21) 6353200025SRui Paulo 6453200025SRui Paulo 6553200025SRui Paulo /** 6653200025SRui Paulo * \brief Match finders 6753200025SRui Paulo * 6853200025SRui Paulo * Match finder has major effect on both speed and compression ratio. 6953200025SRui Paulo * Usually hash chains are faster than binary trees. 7053200025SRui Paulo * 7153200025SRui Paulo * If you will use LZMA_SYNC_FLUSH often, the hash chains may be a better 7253200025SRui Paulo * choice, because binary trees get much higher compression ratio penalty 7353200025SRui Paulo * with LZMA_SYNC_FLUSH. 7453200025SRui Paulo * 7553200025SRui Paulo * The memory usage formulas are only rough estimates, which are closest to 7653200025SRui Paulo * reality when dict_size is a power of two. The formulas are more complex 7753200025SRui Paulo * in reality, and can also change a little between liblzma versions. Use 7853200025SRui Paulo * lzma_raw_encoder_memusage() to get more accurate estimate of memory usage. 7953200025SRui Paulo */ 8053200025SRui Paulo typedef enum { 8153200025SRui Paulo LZMA_MF_HC3 = 0x03, 8253200025SRui Paulo /**< 8353200025SRui Paulo * \brief Hash Chain with 2- and 3-byte hashing 8453200025SRui Paulo * 8553200025SRui Paulo * Minimum nice_len: 3 8653200025SRui Paulo * 8753200025SRui Paulo * Memory usage: 8853200025SRui Paulo * - dict_size <= 16 MiB: dict_size * 7.5 8953200025SRui Paulo * - dict_size > 16 MiB: dict_size * 5.5 + 64 MiB 9053200025SRui Paulo */ 9153200025SRui Paulo 9253200025SRui Paulo LZMA_MF_HC4 = 0x04, 9353200025SRui Paulo /**< 9453200025SRui Paulo * \brief Hash Chain with 2-, 3-, and 4-byte hashing 9553200025SRui Paulo * 9653200025SRui Paulo * Minimum nice_len: 4 9753200025SRui Paulo * 9853200025SRui Paulo * Memory usage: 9953200025SRui Paulo * - dict_size <= 32 MiB: dict_size * 7.5 10053200025SRui Paulo * - dict_size > 32 MiB: dict_size * 6.5 10153200025SRui Paulo */ 10253200025SRui Paulo 10353200025SRui Paulo LZMA_MF_BT2 = 0x12, 10453200025SRui Paulo /**< 10553200025SRui Paulo * \brief Binary Tree with 2-byte hashing 10653200025SRui Paulo * 10753200025SRui Paulo * Minimum nice_len: 2 10853200025SRui Paulo * 10953200025SRui Paulo * Memory usage: dict_size * 9.5 11053200025SRui Paulo */ 11153200025SRui Paulo 11253200025SRui Paulo LZMA_MF_BT3 = 0x13, 11353200025SRui Paulo /**< 11453200025SRui Paulo * \brief Binary Tree with 2- and 3-byte hashing 11553200025SRui Paulo * 11653200025SRui Paulo * Minimum nice_len: 3 11753200025SRui Paulo * 11853200025SRui Paulo * Memory usage: 11953200025SRui Paulo * - dict_size <= 16 MiB: dict_size * 11.5 12053200025SRui Paulo * - dict_size > 16 MiB: dict_size * 9.5 + 64 MiB 12153200025SRui Paulo */ 12253200025SRui Paulo 12353200025SRui Paulo LZMA_MF_BT4 = 0x14 12453200025SRui Paulo /**< 12553200025SRui Paulo * \brief Binary Tree with 2-, 3-, and 4-byte hashing 12653200025SRui Paulo * 12753200025SRui Paulo * Minimum nice_len: 4 12853200025SRui Paulo * 12953200025SRui Paulo * Memory usage: 13053200025SRui Paulo * - dict_size <= 32 MiB: dict_size * 11.5 13153200025SRui Paulo * - dict_size > 32 MiB: dict_size * 10.5 13253200025SRui Paulo */ 13353200025SRui Paulo } lzma_match_finder; 13453200025SRui Paulo 13553200025SRui Paulo 13653200025SRui Paulo /** 13753200025SRui Paulo * \brief Test if given match finder is supported 13853200025SRui Paulo * 139c917796cSXin LI * It is safe to call this with a value that isn't listed in 140c917796cSXin LI * lzma_match_finder enumeration; the return value will be false. 14153200025SRui Paulo * 14253200025SRui Paulo * There is no way to list which match finders are available in this 14353200025SRui Paulo * particular liblzma version and build. It would be useless, because 14453200025SRui Paulo * a new match finder, which the application developer wasn't aware, 14553200025SRui Paulo * could require giving additional options to the encoder that the older 14653200025SRui Paulo * match finders don't need. 147c917796cSXin LI * 148c917796cSXin LI * \param match_finder Match finder ID 149c917796cSXin LI * 150c917796cSXin LI * \return lzma_bool: 151c917796cSXin LI * - true if the match finder is supported by this liblzma build. 152c917796cSXin LI * - false otherwise. 15353200025SRui Paulo */ 15453200025SRui Paulo extern LZMA_API(lzma_bool) lzma_mf_is_supported(lzma_match_finder match_finder) 15553200025SRui Paulo lzma_nothrow lzma_attr_const; 15653200025SRui Paulo 15753200025SRui Paulo 15853200025SRui Paulo /** 15953200025SRui Paulo * \brief Compression modes 16053200025SRui Paulo * 16153200025SRui Paulo * This selects the function used to analyze the data produced by the match 16253200025SRui Paulo * finder. 16353200025SRui Paulo */ 16453200025SRui Paulo typedef enum { 16553200025SRui Paulo LZMA_MODE_FAST = 1, 16653200025SRui Paulo /**< 16753200025SRui Paulo * \brief Fast compression 16853200025SRui Paulo * 16953200025SRui Paulo * Fast mode is usually at its best when combined with 17053200025SRui Paulo * a hash chain match finder. 17153200025SRui Paulo */ 17253200025SRui Paulo 17353200025SRui Paulo LZMA_MODE_NORMAL = 2 17453200025SRui Paulo /**< 17553200025SRui Paulo * \brief Normal compression 17653200025SRui Paulo * 17753200025SRui Paulo * This is usually notably slower than fast mode. Use this 17853200025SRui Paulo * together with binary tree match finders to expose the 17953200025SRui Paulo * full potential of the LZMA1 or LZMA2 encoder. 18053200025SRui Paulo */ 18153200025SRui Paulo } lzma_mode; 18253200025SRui Paulo 18353200025SRui Paulo 18453200025SRui Paulo /** 18553200025SRui Paulo * \brief Test if given compression mode is supported 18653200025SRui Paulo * 187c917796cSXin LI * It is safe to call this with a value that isn't listed in lzma_mode 188c917796cSXin LI * enumeration; the return value will be false. 18953200025SRui Paulo * 19053200025SRui Paulo * There is no way to list which modes are available in this particular 19153200025SRui Paulo * liblzma version and build. It would be useless, because a new compression 19253200025SRui Paulo * mode, which the application developer wasn't aware, could require giving 19353200025SRui Paulo * additional options to the encoder that the older modes don't need. 194c917796cSXin LI * 195c917796cSXin LI * \param mode Mode ID. 196c917796cSXin LI * 197c917796cSXin LI * \return lzma_bool: 198c917796cSXin LI * - true if the compression mode is supported by this liblzma 199c917796cSXin LI * build. 200c917796cSXin LI * - false otherwise. 20153200025SRui Paulo */ 20253200025SRui Paulo extern LZMA_API(lzma_bool) lzma_mode_is_supported(lzma_mode mode) 20353200025SRui Paulo lzma_nothrow lzma_attr_const; 20453200025SRui Paulo 20553200025SRui Paulo 20653200025SRui Paulo /** 20753200025SRui Paulo * \brief Options specific to the LZMA1 and LZMA2 filters 20853200025SRui Paulo * 20953200025SRui Paulo * Since LZMA1 and LZMA2 share most of the code, it's simplest to share 21053200025SRui Paulo * the options structure too. For encoding, all but the reserved variables 21153200025SRui Paulo * need to be initialized unless specifically mentioned otherwise. 21253200025SRui Paulo * lzma_lzma_preset() can be used to get a good starting point. 21353200025SRui Paulo * 21453200025SRui Paulo * For raw decoding, both LZMA1 and LZMA2 need dict_size, preset_dict, and 21553200025SRui Paulo * preset_dict_size (if preset_dict != NULL). LZMA1 needs also lc, lp, and pb. 21653200025SRui Paulo */ 21753200025SRui Paulo typedef struct { 21853200025SRui Paulo /** 21953200025SRui Paulo * \brief Dictionary size in bytes 22053200025SRui Paulo * 22153200025SRui Paulo * Dictionary size indicates how many bytes of the recently processed 22253200025SRui Paulo * uncompressed data is kept in memory. One method to reduce size of 22353200025SRui Paulo * the uncompressed data is to store distance-length pairs, which 22453200025SRui Paulo * indicate what data to repeat from the dictionary buffer. Thus, 22553200025SRui Paulo * the bigger the dictionary, the better the compression ratio 22653200025SRui Paulo * usually is. 22753200025SRui Paulo * 22853200025SRui Paulo * Maximum size of the dictionary depends on multiple things: 22953200025SRui Paulo * - Memory usage limit 23053200025SRui Paulo * - Available address space (not a problem on 64-bit systems) 23153200025SRui Paulo * - Selected match finder (encoder only) 23253200025SRui Paulo * 23353200025SRui Paulo * Currently the maximum dictionary size for encoding is 1.5 GiB 23453200025SRui Paulo * (i.e. (UINT32_C(1) << 30) + (UINT32_C(1) << 29)) even on 64-bit 23553200025SRui Paulo * systems for certain match finder implementation reasons. In the 23653200025SRui Paulo * future, there may be match finders that support bigger 23753200025SRui Paulo * dictionaries. 23853200025SRui Paulo * 23953200025SRui Paulo * Decoder already supports dictionaries up to 4 GiB - 1 B (i.e. 24053200025SRui Paulo * UINT32_MAX), so increasing the maximum dictionary size of the 24153200025SRui Paulo * encoder won't cause problems for old decoders. 24253200025SRui Paulo * 24353200025SRui Paulo * Because extremely small dictionaries sizes would have unneeded 24453200025SRui Paulo * overhead in the decoder, the minimum dictionary size is 4096 bytes. 24553200025SRui Paulo * 24653200025SRui Paulo * \note When decoding, too big dictionary does no other harm 24753200025SRui Paulo * than wasting memory. 24853200025SRui Paulo */ 24953200025SRui Paulo uint32_t dict_size; 25053200025SRui Paulo # define LZMA_DICT_SIZE_MIN UINT32_C(4096) 25153200025SRui Paulo # define LZMA_DICT_SIZE_DEFAULT (UINT32_C(1) << 23) 25253200025SRui Paulo 25353200025SRui Paulo /** 25453200025SRui Paulo * \brief Pointer to an initial dictionary 25553200025SRui Paulo * 25653200025SRui Paulo * It is possible to initialize the LZ77 history window using 25753200025SRui Paulo * a preset dictionary. It is useful when compressing many 25853200025SRui Paulo * similar, relatively small chunks of data independently from 25953200025SRui Paulo * each other. The preset dictionary should contain typical 26053200025SRui Paulo * strings that occur in the files being compressed. The most 26153200025SRui Paulo * probable strings should be near the end of the preset dictionary. 26253200025SRui Paulo * 26353200025SRui Paulo * This feature should be used only in special situations. For 26453200025SRui Paulo * now, it works correctly only with raw encoding and decoding. 26553200025SRui Paulo * Currently none of the container formats supported by 26653200025SRui Paulo * liblzma allow preset dictionary when decoding, thus if 26753200025SRui Paulo * you create a .xz or .lzma file with preset dictionary, it 26853200025SRui Paulo * cannot be decoded with the regular decoder functions. In the 26953200025SRui Paulo * future, the .xz format will likely get support for preset 27053200025SRui Paulo * dictionary though. 27153200025SRui Paulo */ 27253200025SRui Paulo const uint8_t *preset_dict; 27353200025SRui Paulo 27453200025SRui Paulo /** 27553200025SRui Paulo * \brief Size of the preset dictionary 27653200025SRui Paulo * 27753200025SRui Paulo * Specifies the size of the preset dictionary. If the size is 27853200025SRui Paulo * bigger than dict_size, only the last dict_size bytes are 27953200025SRui Paulo * processed. 28053200025SRui Paulo * 28153200025SRui Paulo * This variable is read only when preset_dict is not NULL. 28253200025SRui Paulo * If preset_dict is not NULL but preset_dict_size is zero, 28353200025SRui Paulo * no preset dictionary is used (identical to only setting 28453200025SRui Paulo * preset_dict to NULL). 28553200025SRui Paulo */ 28653200025SRui Paulo uint32_t preset_dict_size; 28753200025SRui Paulo 28853200025SRui Paulo /** 28953200025SRui Paulo * \brief Number of literal context bits 29053200025SRui Paulo * 29153200025SRui Paulo * How many of the highest bits of the previous uncompressed 2922f9cd13dSXin LI * eight-bit byte (also known as `literal') are taken into 29353200025SRui Paulo * account when predicting the bits of the next literal. 29453200025SRui Paulo * 29553200025SRui Paulo * E.g. in typical English text, an upper-case letter is 29653200025SRui Paulo * often followed by a lower-case letter, and a lower-case 29753200025SRui Paulo * letter is usually followed by another lower-case letter. 29853200025SRui Paulo * In the US-ASCII character set, the highest three bits are 010 29953200025SRui Paulo * for upper-case letters and 011 for lower-case letters. 30053200025SRui Paulo * When lc is at least 3, the literal coding can take advantage of 30153200025SRui Paulo * this property in the uncompressed data. 30253200025SRui Paulo * 30353200025SRui Paulo * There is a limit that applies to literal context bits and literal 30453200025SRui Paulo * position bits together: lc + lp <= 4. Without this limit the 30553200025SRui Paulo * decoding could become very slow, which could have security related 30653200025SRui Paulo * results in some cases like email servers doing virus scanning. 30753200025SRui Paulo * This limit also simplifies the internal implementation in liblzma. 30853200025SRui Paulo * 30953200025SRui Paulo * There may be LZMA1 streams that have lc + lp > 4 (maximum possible 31053200025SRui Paulo * lc would be 8). It is not possible to decode such streams with 31153200025SRui Paulo * liblzma. 31253200025SRui Paulo */ 31353200025SRui Paulo uint32_t lc; 31453200025SRui Paulo # define LZMA_LCLP_MIN 0 31553200025SRui Paulo # define LZMA_LCLP_MAX 4 31653200025SRui Paulo # define LZMA_LC_DEFAULT 3 31753200025SRui Paulo 31853200025SRui Paulo /** 31953200025SRui Paulo * \brief Number of literal position bits 32053200025SRui Paulo * 32153200025SRui Paulo * lp affects what kind of alignment in the uncompressed data is 32253200025SRui Paulo * assumed when encoding literals. A literal is a single 8-bit byte. 32353200025SRui Paulo * See pb below for more information about alignment. 32453200025SRui Paulo */ 32553200025SRui Paulo uint32_t lp; 32653200025SRui Paulo # define LZMA_LP_DEFAULT 0 32753200025SRui Paulo 32853200025SRui Paulo /** 32953200025SRui Paulo * \brief Number of position bits 33053200025SRui Paulo * 33153200025SRui Paulo * pb affects what kind of alignment in the uncompressed data is 33253200025SRui Paulo * assumed in general. The default means four-byte alignment 33353200025SRui Paulo * (2^ pb =2^2=4), which is often a good choice when there's 33453200025SRui Paulo * no better guess. 33553200025SRui Paulo * 336a8675d92SXin LI * When the alignment is known, setting pb accordingly may reduce 33753200025SRui Paulo * the file size a little. E.g. with text files having one-byte 33853200025SRui Paulo * alignment (US-ASCII, ISO-8859-*, UTF-8), setting pb=0 can 33953200025SRui Paulo * improve compression slightly. For UTF-16 text, pb=1 is a good 34053200025SRui Paulo * choice. If the alignment is an odd number like 3 bytes, pb=0 34153200025SRui Paulo * might be the best choice. 34253200025SRui Paulo * 34353200025SRui Paulo * Even though the assumed alignment can be adjusted with pb and 34453200025SRui Paulo * lp, LZMA1 and LZMA2 still slightly favor 16-byte alignment. 34553200025SRui Paulo * It might be worth taking into account when designing file formats 34653200025SRui Paulo * that are likely to be often compressed with LZMA1 or LZMA2. 34753200025SRui Paulo */ 34853200025SRui Paulo uint32_t pb; 34953200025SRui Paulo # define LZMA_PB_MIN 0 35053200025SRui Paulo # define LZMA_PB_MAX 4 35153200025SRui Paulo # define LZMA_PB_DEFAULT 2 35253200025SRui Paulo 35353200025SRui Paulo /** Compression mode */ 35453200025SRui Paulo lzma_mode mode; 35553200025SRui Paulo 35653200025SRui Paulo /** 35753200025SRui Paulo * \brief Nice length of a match 35853200025SRui Paulo * 35953200025SRui Paulo * This determines how many bytes the encoder compares from the match 36053200025SRui Paulo * candidates when looking for the best match. Once a match of at 36153200025SRui Paulo * least nice_len bytes long is found, the encoder stops looking for 36253200025SRui Paulo * better candidates and encodes the match. (Naturally, if the found 36353200025SRui Paulo * match is actually longer than nice_len, the actual length is 36453200025SRui Paulo * encoded; it's not truncated to nice_len.) 36553200025SRui Paulo * 36653200025SRui Paulo * Bigger values usually increase the compression ratio and 36753200025SRui Paulo * compression time. For most files, 32 to 128 is a good value, 36853200025SRui Paulo * which gives very good compression ratio at good speed. 36953200025SRui Paulo * 37053200025SRui Paulo * The exact minimum value depends on the match finder. The maximum 37153200025SRui Paulo * is 273, which is the maximum length of a match that LZMA1 and 37253200025SRui Paulo * LZMA2 can encode. 37353200025SRui Paulo */ 37453200025SRui Paulo uint32_t nice_len; 37553200025SRui Paulo 37653200025SRui Paulo /** Match finder ID */ 37753200025SRui Paulo lzma_match_finder mf; 37853200025SRui Paulo 37953200025SRui Paulo /** 38053200025SRui Paulo * \brief Maximum search depth in the match finder 38153200025SRui Paulo * 38253200025SRui Paulo * For every input byte, match finder searches through the hash chain 38353200025SRui Paulo * or binary tree in a loop, each iteration going one step deeper in 38453200025SRui Paulo * the chain or tree. The searching stops if 38553200025SRui Paulo * - a match of at least nice_len bytes long is found; 38653200025SRui Paulo * - all match candidates from the hash chain or binary tree have 38753200025SRui Paulo * been checked; or 38853200025SRui Paulo * - maximum search depth is reached. 38953200025SRui Paulo * 39053200025SRui Paulo * Maximum search depth is needed to prevent the match finder from 39153200025SRui Paulo * wasting too much time in case there are lots of short match 39253200025SRui Paulo * candidates. On the other hand, stopping the search before all 39353200025SRui Paulo * candidates have been checked can reduce compression ratio. 39453200025SRui Paulo * 39553200025SRui Paulo * Setting depth to zero tells liblzma to use an automatic default 39653200025SRui Paulo * value, that depends on the selected match finder and nice_len. 39753200025SRui Paulo * The default is in the range [4, 200] or so (it may vary between 39853200025SRui Paulo * liblzma versions). 39953200025SRui Paulo * 40053200025SRui Paulo * Using a bigger depth value than the default can increase 40153200025SRui Paulo * compression ratio in some cases. There is no strict maximum value, 40253200025SRui Paulo * but high values (thousands or millions) should be used with care: 40353200025SRui Paulo * the encoder could remain fast enough with typical input, but 40453200025SRui Paulo * malicious input could cause the match finder to slow down 40553200025SRui Paulo * dramatically, possibly creating a denial of service attack. 40653200025SRui Paulo */ 40753200025SRui Paulo uint32_t depth; 40853200025SRui Paulo 40973ed8e77SXin LI /** 41073ed8e77SXin LI * \brief For LZMA_FILTER_LZMA1EXT: Extended flags 41173ed8e77SXin LI * 41273ed8e77SXin LI * This is used only with LZMA_FILTER_LZMA1EXT. 41373ed8e77SXin LI * 41473ed8e77SXin LI * Currently only one flag is supported, LZMA_LZMA1EXT_ALLOW_EOPM: 41573ed8e77SXin LI * 41673ed8e77SXin LI * - Encoder: If the flag is set, then end marker is written just 41773ed8e77SXin LI * like it is with LZMA_FILTER_LZMA1. Without this flag the 41873ed8e77SXin LI * end marker isn't written and the application has to store 41973ed8e77SXin LI * the uncompressed size somewhere outside the compressed stream. 4201f3ced26SXin LI * To decompress streams without the end marker, the application 42173ed8e77SXin LI * has to set the correct uncompressed size in ext_size_low and 42273ed8e77SXin LI * ext_size_high. 42373ed8e77SXin LI * 42473ed8e77SXin LI * - Decoder: If the uncompressed size in ext_size_low and 42573ed8e77SXin LI * ext_size_high is set to the special value UINT64_MAX 42673ed8e77SXin LI * (indicating unknown uncompressed size) then this flag is 42773ed8e77SXin LI * ignored and the end marker must always be present, that is, 42873ed8e77SXin LI * the behavior is identical to LZMA_FILTER_LZMA1. 42973ed8e77SXin LI * 43073ed8e77SXin LI * Otherwise, if this flag isn't set, then the input stream 43173ed8e77SXin LI * must not have the end marker; if the end marker is detected 43273ed8e77SXin LI * then it will result in LZMA_DATA_ERROR. This is useful when 43373ed8e77SXin LI * it is known that the stream must not have the end marker and 43473ed8e77SXin LI * strict validation is wanted. 43573ed8e77SXin LI * 43673ed8e77SXin LI * If this flag is set, then it is autodetected if the end marker 43773ed8e77SXin LI * is present after the specified number of uncompressed bytes 43873ed8e77SXin LI * has been decompressed (ext_size_low and ext_size_high). The 43973ed8e77SXin LI * end marker isn't allowed in any other position. This behavior 44073ed8e77SXin LI * is useful when uncompressed size is known but the end marker 44173ed8e77SXin LI * may or may not be present. This is the case, for example, 44273ed8e77SXin LI * in .7z files (valid .7z files that have the end marker in 44373ed8e77SXin LI * LZMA1 streams are rare but they do exist). 44473ed8e77SXin LI */ 44573ed8e77SXin LI uint32_t ext_flags; 44673ed8e77SXin LI # define LZMA_LZMA1EXT_ALLOW_EOPM UINT32_C(0x01) 44773ed8e77SXin LI 44873ed8e77SXin LI /** 44973ed8e77SXin LI * \brief For LZMA_FILTER_LZMA1EXT: Uncompressed size (low bits) 45073ed8e77SXin LI * 45173ed8e77SXin LI * The 64-bit uncompressed size is needed for decompression with 45273ed8e77SXin LI * LZMA_FILTER_LZMA1EXT. The size is ignored by the encoder. 45373ed8e77SXin LI * 45473ed8e77SXin LI * The special value UINT64_MAX indicates that the uncompressed size 45573ed8e77SXin LI * is unknown and that the end of payload marker (also known as 45673ed8e77SXin LI * end of stream marker) must be present to indicate the end of 45773ed8e77SXin LI * the LZMA1 stream. Any other value indicates the expected 45873ed8e77SXin LI * uncompressed size of the LZMA1 stream. (If LZMA1 was used together 45973ed8e77SXin LI * with filters that change the size of the data then the uncompressed 46073ed8e77SXin LI * size of the LZMA1 stream could be different than the final 46173ed8e77SXin LI * uncompressed size of the filtered stream.) 46273ed8e77SXin LI * 46373ed8e77SXin LI * ext_size_low holds the least significant 32 bits of the 46473ed8e77SXin LI * uncompressed size. The most significant 32 bits must be set 46573ed8e77SXin LI * in ext_size_high. The macro lzma_ext_size_set(opt_lzma, u64size) 46673ed8e77SXin LI * can be used to set these members. 46773ed8e77SXin LI * 46873ed8e77SXin LI * The 64-bit uncompressed size is split into two uint32_t variables 46973ed8e77SXin LI * because there were no reserved uint64_t members and using the 47073ed8e77SXin LI * same options structure for LZMA_FILTER_LZMA1, LZMA_FILTER_LZMA1EXT, 47173ed8e77SXin LI * and LZMA_FILTER_LZMA2 was otherwise more convenient than having 47273ed8e77SXin LI * a new options structure for LZMA_FILTER_LZMA1EXT. (Replacing two 47373ed8e77SXin LI * uint32_t members with one uint64_t changes the ABI on some systems 47473ed8e77SXin LI * as the alignment of this struct can increase from 4 bytes to 8.) 47573ed8e77SXin LI */ 47673ed8e77SXin LI uint32_t ext_size_low; 47773ed8e77SXin LI 47873ed8e77SXin LI /** 47973ed8e77SXin LI * \brief For LZMA_FILTER_LZMA1EXT: Uncompressed size (high bits) 48073ed8e77SXin LI * 48173ed8e77SXin LI * This holds the most significant 32 bits of the uncompressed size. 48273ed8e77SXin LI */ 48373ed8e77SXin LI uint32_t ext_size_high; 48473ed8e77SXin LI 48553200025SRui Paulo /* 48653200025SRui Paulo * Reserved space to allow possible future extensions without 48753200025SRui Paulo * breaking the ABI. You should not touch these, because the names 48853200025SRui Paulo * of these variables may change. These are and will never be used 48953200025SRui Paulo * with the currently supported options, so it is safe to leave these 49053200025SRui Paulo * uninitialized. 49153200025SRui Paulo */ 492c917796cSXin LI 493c917796cSXin LI /** \private Reserved member. */ 49453200025SRui Paulo uint32_t reserved_int4; 495c917796cSXin LI 496c917796cSXin LI /** \private Reserved member. */ 49753200025SRui Paulo uint32_t reserved_int5; 498c917796cSXin LI 499c917796cSXin LI /** \private Reserved member. */ 50053200025SRui Paulo uint32_t reserved_int6; 501c917796cSXin LI 502c917796cSXin LI /** \private Reserved member. */ 50353200025SRui Paulo uint32_t reserved_int7; 504c917796cSXin LI 505c917796cSXin LI /** \private Reserved member. */ 50653200025SRui Paulo uint32_t reserved_int8; 507c917796cSXin LI 508c917796cSXin LI /** \private Reserved member. */ 50953200025SRui Paulo lzma_reserved_enum reserved_enum1; 510c917796cSXin LI 511c917796cSXin LI /** \private Reserved member. */ 51253200025SRui Paulo lzma_reserved_enum reserved_enum2; 513c917796cSXin LI 514c917796cSXin LI /** \private Reserved member. */ 51553200025SRui Paulo lzma_reserved_enum reserved_enum3; 516c917796cSXin LI 517c917796cSXin LI /** \private Reserved member. */ 51853200025SRui Paulo lzma_reserved_enum reserved_enum4; 519c917796cSXin LI 520c917796cSXin LI /** \private Reserved member. */ 52153200025SRui Paulo void *reserved_ptr1; 522c917796cSXin LI 523c917796cSXin LI /** \private Reserved member. */ 52453200025SRui Paulo void *reserved_ptr2; 52553200025SRui Paulo 52653200025SRui Paulo } lzma_options_lzma; 52753200025SRui Paulo 52853200025SRui Paulo 52953200025SRui Paulo /** 53073ed8e77SXin LI * \brief Macro to set the 64-bit uncompressed size in ext_size_* 53173ed8e77SXin LI * 53273ed8e77SXin LI * This might be convenient when decoding using LZMA_FILTER_LZMA1EXT. 53373ed8e77SXin LI * This isn't used with LZMA_FILTER_LZMA1 or LZMA_FILTER_LZMA2. 53473ed8e77SXin LI */ 53573ed8e77SXin LI #define lzma_set_ext_size(opt_lzma2, u64size) \ 53673ed8e77SXin LI do { \ 53773ed8e77SXin LI (opt_lzma2).ext_size_low = (uint32_t)(u64size); \ 53873ed8e77SXin LI (opt_lzma2).ext_size_high = (uint32_t)((uint64_t)(u64size) >> 32); \ 53973ed8e77SXin LI } while (0) 54073ed8e77SXin LI 54173ed8e77SXin LI 54273ed8e77SXin LI /** 54353200025SRui Paulo * \brief Set a compression preset to lzma_options_lzma structure 54453200025SRui Paulo * 54553200025SRui Paulo * 0 is the fastest and 9 is the slowest. These match the switches -0 .. -9 54653200025SRui Paulo * of the xz command line tool. In addition, it is possible to bitwise-or 54753200025SRui Paulo * flags to the preset. Currently only LZMA_PRESET_EXTREME is supported. 54853200025SRui Paulo * The flags are defined in container.h, because the flags are used also 54953200025SRui Paulo * with lzma_easy_encoder(). 55053200025SRui Paulo * 551c917796cSXin LI * The preset levels are subject to changes between liblzma versions. 55253200025SRui Paulo * 55353200025SRui Paulo * This function is available only if LZMA1 or LZMA2 encoder has been enabled 55453200025SRui Paulo * when building liblzma. 55553200025SRui Paulo * 556c917796cSXin LI * If features (like certain match finders) have been disabled at build time, 557c917796cSXin LI * then the function may return success (false) even though the resulting 558c917796cSXin LI * LZMA1/LZMA2 options may not be usable for encoder initialization 559c917796cSXin LI * (LZMA_OPTIONS_ERROR). 560c917796cSXin LI * 561c917796cSXin LI * \param[out] options Pointer to LZMA1 or LZMA2 options to be filled 562c917796cSXin LI * \param preset Preset level bitwse-ORed with preset flags 563c917796cSXin LI * 564c917796cSXin LI * \return lzma_bool: 565c917796cSXin LI * - true if the preset is not supported (failure). 566c917796cSXin LI * - false otherwise (success). 56753200025SRui Paulo */ 56853200025SRui Paulo extern LZMA_API(lzma_bool) lzma_lzma_preset( 56953200025SRui Paulo lzma_options_lzma *options, uint32_t preset) lzma_nothrow; 570