contrib/xz/src/liblzma/api/lzma/block.h

   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  */
  30 typedef 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          */
  52         uint32_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          */
  72         uint32_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          */
  93         lzma_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          */
 148         lzma_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          */
 172         lzma_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          */
 200         lzma_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          */
 217         uint8_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          */
 226         void *reserved_ptr1;
 227         void *reserved_ptr2;
 228         void *reserved_ptr3;
 229         uint32_t reserved_int1;
 230         uint32_t reserved_int2;
 231         lzma_vli reserved_int3;
 232         lzma_vli reserved_int4;
 233         lzma_vli reserved_int5;
 234         lzma_vli reserved_int6;
 235         lzma_vli reserved_int7;
 236         lzma_vli reserved_int8;
 237         lzma_reserved_enum reserved_enum1;
 238         lzma_reserved_enum reserved_enum2;
 239         lzma_reserved_enum reserved_enum3;
 240         lzma_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          */
 261         lzma_bool ignore_check;
 262
 263         lzma_bool reserved_bool2;
 264         lzma_bool reserved_bool3;
 265         lzma_bool reserved_bool4;
 266         lzma_bool reserved_bool5;
 267         lzma_bool reserved_bool6;
 268         lzma_bool reserved_bool7;
 269         lzma_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  */
 309 extern LZMA_API(lzma_ret) lzma_block_header_size(lzma_block *block)
 310                 lzma_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  */
 331 extern LZMA_API(lzma_ret) lzma_block_header_encode(
 332                 const lzma_block *block, uint8_t *out)
 333                 lzma_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  */
 376 extern LZMA_API(lzma_ret) lzma_block_header_decode(lzma_block *block,
 377                 const lzma_allocator *allocator, const uint8_t *in)
 378                 lzma_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  */
 408 extern LZMA_API(lzma_ret) lzma_block_compressed_size(
 409                 lzma_block *block, lzma_vli unpadded_size)
 410                 lzma_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  */
 424 extern LZMA_API(lzma_vli) lzma_block_unpadded_size(const lzma_block *block)
 425                 lzma_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  */
 437 extern LZMA_API(lzma_vli) lzma_block_total_size(const lzma_block *block)
 438                 lzma_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 buid of liblzma. Initializing
 452  *                the encoder failed.
 453  *              - LZMA_PROG_ERROR
 454  */
 455 extern LZMA_API(lzma_ret) lzma_block_encoder(
 456                 lzma_stream *strm, lzma_block *block)
 457                 lzma_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  */
 473 extern LZMA_API(lzma_ret) lzma_block_decoder(
 474                 lzma_stream *strm, lzma_block *block)
 475                 lzma_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  */
 484 extern LZMA_API(size_t) lzma_block_buffer_bound(size_t uncompressed_size)
 485                 lzma_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  */
 525 extern LZMA_API(lzma_ret) lzma_block_buffer_encode(
 526                 lzma_block *block, const lzma_allocator *allocator,
 527                 const uint8_t *in, size_t in_size,
 528                 uint8_t *out, size_t *out_pos, size_t out_size)
 529                 lzma_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  */
 544 extern LZMA_API(lzma_ret) lzma_block_uncomp_encode(lzma_block *block,
 545                 const uint8_t *in, size_t in_size,
 546                 uint8_t *out, size_t *out_pos, size_t out_size)
 547                 lzma_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  */
 577 extern LZMA_API(lzma_ret) lzma_block_buffer_decode(
 578                 lzma_block *block, const lzma_allocator *allocator,
 579                 const uint8_t *in, size_t *in_pos, size_t in_size,
 580                 uint8_t *out, size_t *out_pos, size_t out_size)
 581                 lzma_nothrow;