fork/slippc
git clone https://git.julia.blue/fork/slippc
39f196d
0.6.0
1/** 2* \file lzma/block.h 3* \brief .xz Block handling 4*/ 5 6/* 7* Author: Lasse Collin 8* 9* This file has been put into the public domain. 10* You can do whatever you want with this file. 11* 12* See ../lzma.h for information about liblzma as a whole. 13*/ 14 15#ifndef LZMA_H_INTERNAL 16# error Never include this file directly. Use <lzma.h> instead. 17#endif 18 19 20/** 21* \brief Options for the Block and Block Header encoders and decoders 22* 23* Different Block handling functions use different parts of this structure. 24* Some read some members, other functions write, and some do both. Only the 25* members listed for reading need to be initialized when the specified 26* functions are called. The members marked for writing will be assigned 27* new values at some point either by calling the given function or by 28* later calls to lzma_code(). 29*/ 30typedef struct { 31/** 32* \brief Block format version 33* 34* To prevent API and ABI breakages when new features are needed, 35* a version number is used to indicate which fields in this 36* structure are in use: 37* - liblzma >= 5.0.0: version = 0 is supported. 38* - liblzma >= 5.1.4beta: Support for version = 1 was added, 39* which adds the ignore_check field. 40* 41* If version is greater than one, most Block related functions 42* will return LZMA_OPTIONS_ERROR (lzma_block_header_decode() works 43* with any version value). 44* 45* Read by: 46* - All functions that take pointer to lzma_block as argument, 47* including lzma_block_header_decode(). 48* 49* Written by: 50* - lzma_block_header_decode() 51*/ 52uint32_t version ; 53 54/** 55* \brief Size of the Block Header field 56* 57* This is always a multiple of four. 58* 59* Read by: 60* - lzma_block_header_encode() 61* - lzma_block_header_decode() 62* - lzma_block_compressed_size() 63* - lzma_block_unpadded_size() 64* - lzma_block_total_size() 65* - lzma_block_decoder() 66* - lzma_block_buffer_decode() 67* 68* Written by: 69* - lzma_block_header_size() 70* - lzma_block_buffer_encode() 71*/ 72uint32_t header_size ; 73# define LZMA_BLOCK_HEADER_SIZE_MIN 8 74# define LZMA_BLOCK_HEADER_SIZE_MAX 1024 75 76/** 77* \brief Type of integrity Check 78* 79* The Check ID is not stored into the Block Header, thus its value 80* must be provided also when decoding. 81* 82* Read by: 83* - lzma_block_header_encode() 84* - lzma_block_header_decode() 85* - lzma_block_compressed_size() 86* - lzma_block_unpadded_size() 87* - lzma_block_total_size() 88* - lzma_block_encoder() 89* - lzma_block_decoder() 90* - lzma_block_buffer_encode() 91* - lzma_block_buffer_decode() 92*/ 93lzma_check check ; 94 95/** 96* \brief Size of the Compressed Data in bytes 97* 98* Encoding: If this is not LZMA_VLI_UNKNOWN, Block Header encoder 99* will store this value to the Block Header. Block encoder doesn't 100* care about this value, but will set it once the encoding has been 101* finished. 102* 103* Decoding: If this is not LZMA_VLI_UNKNOWN, Block decoder will 104* verify that the size of the Compressed Data field matches 105* compressed_size. 106* 107* Usually you don't know this value when encoding in streamed mode, 108* and thus cannot write this field into the Block Header. 109* 110* In non-streamed mode you can reserve space for this field before 111* encoding the actual Block. After encoding the data, finish the 112* Block by encoding the Block Header. Steps in detail: 113* 114* - Set compressed_size to some big enough value. If you don't know 115* better, use LZMA_VLI_MAX, but remember that bigger values take 116* more space in Block Header. 117* 118* - Call lzma_block_header_size() to see how much space you need to 119* reserve for the Block Header. 120* 121* - Encode the Block using lzma_block_encoder() and lzma_code(). 122* It sets compressed_size to the correct value. 123* 124* - Use lzma_block_header_encode() to encode the Block Header. 125* Because space was reserved in the first step, you don't need 126* to call lzma_block_header_size() anymore, because due to 127* reserving, header_size has to be big enough. If it is "too big", 128* lzma_block_header_encode() will add enough Header Padding to 129* make Block Header to match the size specified by header_size. 130* 131* Read by: 132* - lzma_block_header_size() 133* - lzma_block_header_encode() 134* - lzma_block_compressed_size() 135* - lzma_block_unpadded_size() 136* - lzma_block_total_size() 137* - lzma_block_decoder() 138* - lzma_block_buffer_decode() 139* 140* Written by: 141* - lzma_block_header_decode() 142* - lzma_block_compressed_size() 143* - lzma_block_encoder() 144* - lzma_block_decoder() 145* - lzma_block_buffer_encode() 146* - lzma_block_buffer_decode() 147*/ 148lzma_vli compressed_size ; 149 150/** 151* \brief Uncompressed Size in bytes 152* 153* This is handled very similarly to compressed_size above. 154* 155* uncompressed_size is needed by fewer functions than 156* compressed_size. This is because uncompressed_size isn't 157* needed to validate that Block stays within proper limits. 158* 159* Read by: 160* - lzma_block_header_size() 161* - lzma_block_header_encode() 162* - lzma_block_decoder() 163* - lzma_block_buffer_decode() 164* 165* Written by: 166* - lzma_block_header_decode() 167* - lzma_block_encoder() 168* - lzma_block_decoder() 169* - lzma_block_buffer_encode() 170* - lzma_block_buffer_decode() 171*/ 172lzma_vli uncompressed_size ; 173 174/** 175* \brief Array of filters 176* 177* There can be 1-4 filters. The end of the array is marked with 178* .id = LZMA_VLI_UNKNOWN. 179* 180* Read by: 181* - lzma_block_header_size() 182* - lzma_block_header_encode() 183* - lzma_block_encoder() 184* - lzma_block_decoder() 185* - lzma_block_buffer_encode() 186* - lzma_block_buffer_decode() 187* 188* Written by: 189* - lzma_block_header_decode(): Note that this does NOT free() 190* the old filter options structures. All unused filters[] will 191* have .id == LZMA_VLI_UNKNOWN and .options == NULL. If 192* decoding fails, all filters[] are guaranteed to be 193* LZMA_VLI_UNKNOWN and NULL. 194* 195* \note Because of the array is terminated with 196* .id = LZMA_VLI_UNKNOWN, the actual array must 197* have LZMA_FILTERS_MAX + 1 members or the Block 198* Header decoder will overflow the buffer. 199*/ 200lzma_filter * filters ; 201 202/** 203* \brief Raw value stored in the Check field 204* 205* After successful coding, the first lzma_check_size(check) bytes 206* of this array contain the raw value stored in the Check field. 207* 208* Note that CRC32 and CRC64 are stored in little endian byte order. 209* Take it into account if you display the Check values to the user. 210* 211* Written by: 212* - lzma_block_encoder() 213* - lzma_block_decoder() 214* - lzma_block_buffer_encode() 215* - lzma_block_buffer_decode() 216*/ 217uint8_t raw_check [LZMA_CHECK_SIZE_MAX ]; 218 219/* 220* Reserved space to allow possible future extensions without 221* breaking the ABI. You should not touch these, because the names 222* of these variables may change. These are and will never be used 223* with the currently supported options, so it is safe to leave these 224* uninitialized. 225*/ 226void * reserved_ptr1 ; 227void * reserved_ptr2 ; 228void * reserved_ptr3 ; 229uint32_t reserved_int1 ; 230uint32_t reserved_int2 ; 231lzma_vli reserved_int3 ; 232lzma_vli reserved_int4 ; 233lzma_vli reserved_int5 ; 234lzma_vli reserved_int6 ; 235lzma_vli reserved_int7 ; 236lzma_vli reserved_int8 ; 237lzma_reserved_enum reserved_enum1 ; 238lzma_reserved_enum reserved_enum2 ; 239lzma_reserved_enum reserved_enum3 ; 240lzma_reserved_enum reserved_enum4 ; 241 242/** 243* \brief A flag to Block decoder to not verify the Check field 244* 245* This field is supported by liblzma >= 5.1.4beta if .version >= 1. 246* 247* If this is set to true, the integrity check won't be calculated 248* and verified. Unless you know what you are doing, you should 249* leave this to false. (A reason to set this to true is when the 250* file integrity is verified externally anyway and you want to 251* speed up the decompression, which matters mostly when using 252* SHA-256 as the integrity check.) 253* 254* If .version >= 1, read by: 255* - lzma_block_decoder() 256* - lzma_block_buffer_decode() 257* 258* Written by (.version is ignored): 259* - lzma_block_header_decode() always sets this to false 260*/ 261lzma_bool ignore_check ; 262 263lzma_bool reserved_bool2 ; 264lzma_bool reserved_bool3 ; 265lzma_bool reserved_bool4 ; 266lzma_bool reserved_bool5 ; 267lzma_bool reserved_bool6 ; 268lzma_bool reserved_bool7 ; 269lzma_bool reserved_bool8 ; 270 271}lzma_block ; 272 273 274/** 275* \brief Decode the Block Header Size field 276* 277* To decode Block Header using lzma_block_header_decode(), the size of the 278* Block Header has to be known and stored into lzma_block.header_size. 279* The size can be calculated from the first byte of a Block using this macro. 280* Note that if the first byte is 0x00, it indicates beginning of Index; use 281* this macro only when the byte is not 0x00. 282* 283* There is no encoding macro, because Block Header encoder is enough for that. 284*/ 285#define lzma_block_header_size_decode (b ) (((uint32_t)(b) + 1) * 4) 286 287 288/** 289* \brief Calculate Block Header Size 290* 291* Calculate the minimum size needed for the Block Header field using the 292* settings specified in the lzma_block structure. Note that it is OK to 293* increase the calculated header_size value as long as it is a multiple of 294* four and doesn't exceed LZMA_BLOCK_HEADER_SIZE_MAX. Increasing header_size 295* just means that lzma_block_header_encode() will add Header Padding. 296* 297* \return - LZMA_OK: Size calculated successfully and stored to 298* block->header_size. 299* - LZMA_OPTIONS_ERROR: Unsupported version, filters or 300* filter options. 301* - LZMA_PROG_ERROR: Invalid values like compressed_size == 0. 302* 303* \note This doesn't check that all the options are valid i.e. this 304* may return LZMA_OK even if lzma_block_header_encode() or 305* lzma_block_encoder() would fail. If you want to validate the 306* filter chain, consider using lzma_memlimit_encoder() which as 307* a side-effect validates the filter chain. 308*/ 309extern LZMA_API (lzma_ret )lzma_block_header_size (lzma_block * block ) 310lzma_nothrow lzma_attr_warn_unused_result ; 311 312 313/** 314* \brief Encode Block Header 315* 316* The caller must have calculated the size of the Block Header already with 317* lzma_block_header_size(). If a value larger than the one calculated by 318* lzma_block_header_size() is used, the Block Header will be padded to the 319* specified size. 320* 321* \param out Beginning of the output buffer. This must be 322* at least block->header_size bytes. 323* \param block Block options to be encoded. 324* 325* \return - LZMA_OK: Encoding was successful. block->header_size 326* bytes were written to output buffer. 327* - LZMA_OPTIONS_ERROR: Invalid or unsupported options. 328* - LZMA_PROG_ERROR: Invalid arguments, for example 329* block->header_size is invalid or block->filters is NULL. 330*/ 331extern LZMA_API (lzma_ret )lzma_block_header_encode ( 332const lzma_block * block ,uint8_t * out ) 333lzma_nothrow lzma_attr_warn_unused_result ; 334 335 336/** 337* \brief Decode Block Header 338* 339* block->version should (usually) be set to the highest value supported 340* by the application. If the application sets block->version to a value 341* higher than supported by the current liblzma version, this function will 342* downgrade block->version to the highest value supported by it. Thus one 343* should check the value of block->version after calling this function if 344* block->version was set to a non-zero value and the application doesn't 345* otherwise know that the liblzma version being used is new enough to 346* support the specified block->version. 347* 348* The size of the Block Header must have already been decoded with 349* lzma_block_header_size_decode() macro and stored to block->header_size. 350* 351* The integrity check type from Stream Header must have been stored 352* to block->check. 353* 354* block->filters must have been allocated, but they don't need to be 355* initialized (possible existing filter options are not freed). 356* 357* \param block Destination for Block options. 358* \param allocator lzma_allocator for custom allocator functions. 359* Set to NULL to use malloc() (and also free() 360* if an error occurs). 361* \param in Beginning of the input buffer. This must be 362* at least block->header_size bytes. 363* 364* \return - LZMA_OK: Decoding was successful. block->header_size 365* bytes were read from the input buffer. 366* - LZMA_OPTIONS_ERROR: The Block Header specifies some 367* unsupported options such as unsupported filters. This can 368* happen also if block->version was set to a too low value 369* compared to what would be required to properly represent 370* the information stored in the Block Header. 371* - LZMA_DATA_ERROR: Block Header is corrupt, for example, 372* the CRC32 doesn't match. 373* - LZMA_PROG_ERROR: Invalid arguments, for example 374* block->header_size is invalid or block->filters is NULL. 375*/ 376extern LZMA_API (lzma_ret )lzma_block_header_decode (lzma_block * block , 377const lzma_allocator * allocator ,const uint8_t * in ) 378lzma_nothrow lzma_attr_warn_unused_result ; 379 380 381/** 382* \brief Validate and set Compressed Size according to Unpadded Size 383* 384* Block Header stores Compressed Size, but Index has Unpadded Size. If the 385* application has already parsed the Index and is now decoding Blocks, 386* it can calculate Compressed Size from Unpadded Size. This function does 387* exactly that with error checking: 388* 389* - Compressed Size calculated from Unpadded Size must be positive integer, 390* that is, Unpadded Size must be big enough that after Block Header and 391* Check fields there's still at least one byte for Compressed Size. 392* 393* - If Compressed Size was present in Block Header, the new value 394* calculated from Unpadded Size is compared against the value 395* from Block Header. 396* 397* \note This function must be called _after_ decoding the Block Header 398* field so that it can properly validate Compressed Size if it 399* was present in Block Header. 400* 401* \return - LZMA_OK: block->compressed_size was set successfully. 402* - LZMA_DATA_ERROR: unpadded_size is too small compared to 403* block->header_size and lzma_check_size(block->check). 404* - LZMA_PROG_ERROR: Some values are invalid. For example, 405* block->header_size must be a multiple of four and 406* between 8 and 1024 inclusive. 407*/ 408extern LZMA_API (lzma_ret )lzma_block_compressed_size ( 409lzma_block * block ,lzma_vli unpadded_size ) 410lzma_nothrow lzma_attr_warn_unused_result ; 411 412 413/** 414* \brief Calculate Unpadded Size 415* 416* The Index field stores Unpadded Size and Uncompressed Size. The latter 417* can be taken directly from the lzma_block structure after coding a Block, 418* but Unpadded Size needs to be calculated from Block Header Size, 419* Compressed Size, and size of the Check field. This is where this function 420* is needed. 421* 422* \return Unpadded Size on success, or zero on error. 423*/ 424extern LZMA_API (lzma_vli )lzma_block_unpadded_size (const lzma_block * block ) 425lzma_nothrow lzma_attr_pure ; 426 427 428/** 429* \brief Calculate the total encoded size of a Block 430* 431* This is equivalent to lzma_block_unpadded_size() except that the returned 432* value includes the size of the Block Padding field. 433* 434* \return On success, total encoded size of the Block. On error, 435* zero is returned. 436*/ 437extern LZMA_API (lzma_vli )lzma_block_total_size (const lzma_block * block ) 438lzma_nothrow lzma_attr_pure ; 439 440 441/** 442* \brief Initialize .xz Block encoder 443* 444* Valid actions for lzma_code() are LZMA_RUN, LZMA_SYNC_FLUSH (only if the 445* filter chain supports it), and LZMA_FINISH. 446* 447* \return - LZMA_OK: All good, continue with lzma_code(). 448* - LZMA_MEM_ERROR 449* - LZMA_OPTIONS_ERROR 450* - LZMA_UNSUPPORTED_CHECK: block->check specifies a Check ID 451* that is not supported by this build of liblzma. Initializing 452* the encoder failed. 453* - LZMA_PROG_ERROR 454*/ 455extern LZMA_API (lzma_ret )lzma_block_encoder ( 456lzma_stream * strm ,lzma_block * block ) 457lzma_nothrow lzma_attr_warn_unused_result ; 458 459 460/** 461* \brief Initialize .xz Block decoder 462* 463* Valid actions for lzma_code() are LZMA_RUN and LZMA_FINISH. Using 464* LZMA_FINISH is not required. It is supported only for convenience. 465* 466* \return - LZMA_OK: All good, continue with lzma_code(). 467* - LZMA_UNSUPPORTED_CHECK: Initialization was successful, but 468* the given Check ID is not supported, thus Check will be 469* ignored. 470* - LZMA_PROG_ERROR 471* - LZMA_MEM_ERROR 472*/ 473extern LZMA_API (lzma_ret )lzma_block_decoder ( 474lzma_stream * strm ,lzma_block * block ) 475lzma_nothrow lzma_attr_warn_unused_result ; 476 477 478/** 479* \brief Calculate maximum output size for single-call Block encoding 480* 481* This is equivalent to lzma_stream_buffer_bound() but for .xz Blocks. 482* See the documentation of lzma_stream_buffer_bound(). 483*/ 484extern LZMA_API (size_t )lzma_block_buffer_bound (size_t uncompressed_size ) 485lzma_nothrow ; 486 487 488/** 489* \brief Single-call .xz Block encoder 490* 491* In contrast to the multi-call encoder initialized with 492* lzma_block_encoder(), this function encodes also the Block Header. This 493* is required to make it possible to write appropriate Block Header also 494* in case the data isn't compressible, and different filter chain has to be 495* used to encode the data in uncompressed form using uncompressed chunks 496* of the LZMA2 filter. 497* 498* When the data isn't compressible, header_size, compressed_size, and 499* uncompressed_size are set just like when the data was compressible, but 500* it is possible that header_size is too small to hold the filter chain 501* specified in block->filters, because that isn't necessarily the filter 502* chain that was actually used to encode the data. lzma_block_unpadded_size() 503* still works normally, because it doesn't read the filters array. 504* 505* \param block Block options: block->version, block->check, 506* and block->filters must have been initialized. 507* \param allocator lzma_allocator for custom allocator functions. 508* Set to NULL to use malloc() and free(). 509* \param in Beginning of the input buffer 510* \param in_size Size of the input buffer 511* \param out Beginning of the output buffer 512* \param out_pos The next byte will be written to out[*out_pos]. 513* *out_pos is updated only if encoding succeeds. 514* \param out_size Size of the out buffer; the first byte into 515* which no data is written to is out[out_size]. 516* 517* \return - LZMA_OK: Encoding was successful. 518* - LZMA_BUF_ERROR: Not enough output buffer space. 519* - LZMA_UNSUPPORTED_CHECK 520* - LZMA_OPTIONS_ERROR 521* - LZMA_MEM_ERROR 522* - LZMA_DATA_ERROR 523* - LZMA_PROG_ERROR 524*/ 525extern LZMA_API (lzma_ret )lzma_block_buffer_encode ( 526lzma_block * block ,const lzma_allocator * allocator , 527const uint8_t * in ,size_t in_size , 528uint8_t * out ,size_t * out_pos ,size_t out_size ) 529lzma_nothrow lzma_attr_warn_unused_result ; 530 531 532/** 533* \brief Single-call uncompressed .xz Block encoder 534* 535* This is like lzma_block_buffer_encode() except this doesn't try to 536* compress the data and instead encodes the data using LZMA2 uncompressed 537* chunks. The required output buffer size can be determined with 538* lzma_block_buffer_bound(). 539* 540* Since the data won't be compressed, this function ignores block->filters. 541* This function doesn't take lzma_allocator because this function doesn't 542* allocate any memory from the heap. 543*/ 544extern LZMA_API (lzma_ret )lzma_block_uncomp_encode (lzma_block * block , 545const uint8_t * in ,size_t in_size , 546uint8_t * out ,size_t * out_pos ,size_t out_size ) 547lzma_nothrow lzma_attr_warn_unused_result ; 548 549 550/** 551* \brief Single-call .xz Block decoder 552* 553* This is single-call equivalent of lzma_block_decoder(), and requires that 554* the caller has already decoded Block Header and checked its memory usage. 555* 556* \param block Block options just like with lzma_block_decoder(). 557* \param allocator lzma_allocator for custom allocator functions. 558* Set to NULL to use malloc() and free(). 559* \param in Beginning of the input buffer 560* \param in_pos The next byte will be read from in[*in_pos]. 561* *in_pos is updated only if decoding succeeds. 562* \param in_size Size of the input buffer; the first byte that 563* won't be read is in[in_size]. 564* \param out Beginning of the output buffer 565* \param out_pos The next byte will be written to out[*out_pos]. 566* *out_pos is updated only if encoding succeeds. 567* \param out_size Size of the out buffer; the first byte into 568* which no data is written to is out[out_size]. 569* 570* \return - LZMA_OK: Decoding was successful. 571* - LZMA_OPTIONS_ERROR 572* - LZMA_DATA_ERROR 573* - LZMA_MEM_ERROR 574* - LZMA_BUF_ERROR: Output buffer was too small. 575* - LZMA_PROG_ERROR 576*/ 577extern LZMA_API (lzma_ret )lzma_block_buffer_decode ( 578lzma_block * block ,const lzma_allocator * allocator , 579const uint8_t * in ,size_t * in_pos ,size_t in_size , 580uint8_t * out ,size_t * out_pos ,size_t out_size ) 581lzma_nothrow ;