1 /* SPDX-License-Identifier: 0BSD */ 2 3 /** 4 * \file lzma/index.h 5 * \brief Handling of .xz Index and related information 6 * \note Never include this file directly. Use <lzma.h> instead. 7 */ 8 9 /* 10 * Author: Lasse Collin 11 */ 12 13 #ifndef LZMA_H_INTERNAL 14 # error Never include this file directly. Use <lzma.h> instead. 15 #endif 16 17 18 /** 19 * \brief Opaque data type to hold the Index(es) and other information 20 * 21 * lzma_index often holds just one .xz Index and possibly the Stream Flags 22 * of the same Stream and size of the Stream Padding field. However, 23 * multiple lzma_indexes can be concatenated with lzma_index_cat() and then 24 * there may be information about multiple Streams in the same lzma_index. 25 * 26 * Notes about thread safety: Only one thread may modify lzma_index at 27 * a time. All functions that take non-const pointer to lzma_index 28 * modify it. As long as no thread is modifying the lzma_index, getting 29 * information from the same lzma_index can be done from multiple threads 30 * at the same time with functions that take a const pointer to 31 * lzma_index or use lzma_index_iter. The same iterator must be used 32 * only by one thread at a time, of course, but there can be as many 33 * iterators for the same lzma_index as needed. 34 */ 35 typedef struct lzma_index_s lzma_index; 36 37 38 /** 39 * \brief Iterator to get information about Blocks and Streams 40 */ 41 typedef struct { 42 struct { 43 /** 44 * \brief Pointer to Stream Flags 45 * 46 * This is NULL if Stream Flags have not been set for 47 * this Stream with lzma_index_stream_flags(). 48 */ 49 const lzma_stream_flags *flags; 50 51 /** \private Reserved member. */ 52 const void *reserved_ptr1; 53 54 /** \private Reserved member. */ 55 const void *reserved_ptr2; 56 57 /** \private Reserved member. */ 58 const void *reserved_ptr3; 59 60 /** 61 * \brief Stream number in the lzma_index 62 * 63 * The first Stream is 1. 64 */ 65 lzma_vli number; 66 67 /** 68 * \brief Number of Blocks in the Stream 69 * 70 * If this is zero, the block structure below has 71 * undefined values. 72 */ 73 lzma_vli block_count; 74 75 /** 76 * \brief Compressed start offset of this Stream 77 * 78 * The offset is relative to the beginning of the lzma_index 79 * (i.e. usually the beginning of the .xz file). 80 */ 81 lzma_vli compressed_offset; 82 83 /** 84 * \brief Uncompressed start offset of this Stream 85 * 86 * The offset is relative to the beginning of the lzma_index 87 * (i.e. usually the beginning of the .xz file). 88 */ 89 lzma_vli uncompressed_offset; 90 91 /** 92 * \brief Compressed size of this Stream 93 * 94 * This includes all headers except the possible 95 * Stream Padding after this Stream. 96 */ 97 lzma_vli compressed_size; 98 99 /** 100 * \brief Uncompressed size of this Stream 101 */ 102 lzma_vli uncompressed_size; 103 104 /** 105 * \brief Size of Stream Padding after this Stream 106 * 107 * If it hasn't been set with lzma_index_stream_padding(), 108 * this defaults to zero. Stream Padding is always 109 * a multiple of four bytes. 110 */ 111 lzma_vli padding; 112 113 114 /** \private Reserved member. */ 115 lzma_vli reserved_vli1; 116 117 /** \private Reserved member. */ 118 lzma_vli reserved_vli2; 119 120 /** \private Reserved member. */ 121 lzma_vli reserved_vli3; 122 123 /** \private Reserved member. */ 124 lzma_vli reserved_vli4; 125 } stream; 126 127 struct { 128 /** 129 * \brief Block number in the file 130 * 131 * The first Block is 1. 132 */ 133 lzma_vli number_in_file; 134 135 /** 136 * \brief Compressed start offset of this Block 137 * 138 * This offset is relative to the beginning of the 139 * lzma_index (i.e. usually the beginning of the .xz file). 140 * Normally this is where you should seek in the .xz file 141 * to start decompressing this Block. 142 */ 143 lzma_vli compressed_file_offset; 144 145 /** 146 * \brief Uncompressed start offset of this Block 147 * 148 * This offset is relative to the beginning of the lzma_index 149 * (i.e. usually the beginning of the .xz file). 150 * 151 * When doing random-access reading, it is possible that 152 * the target offset is not exactly at Block boundary. One 153 * will need to compare the target offset against 154 * uncompressed_file_offset or uncompressed_stream_offset, 155 * and possibly decode and throw away some amount of data 156 * before reaching the target offset. 157 */ 158 lzma_vli uncompressed_file_offset; 159 160 /** 161 * \brief Block number in this Stream 162 * 163 * The first Block is 1. 164 */ 165 lzma_vli number_in_stream; 166 167 /** 168 * \brief Compressed start offset of this Block 169 * 170 * This offset is relative to the beginning of the Stream 171 * containing this Block. 172 */ 173 lzma_vli compressed_stream_offset; 174 175 /** 176 * \brief Uncompressed start offset of this Block 177 * 178 * This offset is relative to the beginning of the Stream 179 * containing this Block. 180 */ 181 lzma_vli uncompressed_stream_offset; 182 183 /** 184 * \brief Uncompressed size of this Block 185 * 186 * You should pass this to the Block decoder if you will 187 * decode this Block. It will allow the Block decoder to 188 * validate the uncompressed size. 189 */ 190 lzma_vli uncompressed_size; 191 192 /** 193 * \brief Unpadded size of this Block 194 * 195 * You should pass this to the Block decoder if you will 196 * decode this Block. It will allow the Block decoder to 197 * validate the unpadded size. 198 */ 199 lzma_vli unpadded_size; 200 201 /** 202 * \brief Total compressed size 203 * 204 * This includes all headers and padding in this Block. 205 * This is useful if you need to know how many bytes 206 * the Block decoder will actually read. 207 */ 208 lzma_vli total_size; 209 210 /** \private Reserved member. */ 211 lzma_vli reserved_vli1; 212 213 /** \private Reserved member. */ 214 lzma_vli reserved_vli2; 215 216 /** \private Reserved member. */ 217 lzma_vli reserved_vli3; 218 219 /** \private Reserved member. */ 220 lzma_vli reserved_vli4; 221 222 /** \private Reserved member. */ 223 const void *reserved_ptr1; 224 225 /** \private Reserved member. */ 226 const void *reserved_ptr2; 227 228 /** \private Reserved member. */ 229 const void *reserved_ptr3; 230 231 /** \private Reserved member. */ 232 const void *reserved_ptr4; 233 } block; 234 235 /** 236 * \private Internal data 237 * 238 * Internal data which is used to store the state of the iterator. 239 * The exact format may vary between liblzma versions, so don't 240 * touch these in any way. 241 */ 242 union { 243 /** \private Internal member. */ 244 const void *p; 245 246 /** \private Internal member. */ 247 size_t s; 248 249 /** \private Internal member. */ 250 lzma_vli v; 251 } internal[6]; 252 } lzma_index_iter; 253 254 255 /** 256 * \brief Operation mode for lzma_index_iter_next() 257 */ 258 typedef enum { 259 LZMA_INDEX_ITER_ANY = 0, 260 /**< 261 * \brief Get the next Block or Stream 262 * 263 * Go to the next Block if the current Stream has at least 264 * one Block left. Otherwise go to the next Stream even if 265 * it has no Blocks. If the Stream has no Blocks 266 * (lzma_index_iter.stream.block_count == 0), 267 * lzma_index_iter.block will have undefined values. 268 */ 269 270 LZMA_INDEX_ITER_STREAM = 1, 271 /**< 272 * \brief Get the next Stream 273 * 274 * Go to the next Stream even if the current Stream has 275 * unread Blocks left. If the next Stream has at least one 276 * Block, the iterator will point to the first Block. 277 * If there are no Blocks, lzma_index_iter.block will have 278 * undefined values. 279 */ 280 281 LZMA_INDEX_ITER_BLOCK = 2, 282 /**< 283 * \brief Get the next Block 284 * 285 * Go to the next Block if the current Stream has at least 286 * one Block left. If the current Stream has no Blocks left, 287 * the next Stream with at least one Block is located and 288 * the iterator will be made to point to the first Block of 289 * that Stream. 290 */ 291 292 LZMA_INDEX_ITER_NONEMPTY_BLOCK = 3 293 /**< 294 * \brief Get the next non-empty Block 295 * 296 * This is like LZMA_INDEX_ITER_BLOCK except that it will 297 * skip Blocks whose Uncompressed Size is zero. 298 */ 299 300 } lzma_index_iter_mode; 301 302 303 /** 304 * \brief Mask for return value from lzma_index_checks() for check none 305 * 306 * \note This and the other CHECK_MASK macros were added in 5.5.1alpha. 307 */ 308 #define LZMA_INDEX_CHECK_MASK_NONE (UINT32_C(1) << LZMA_CHECK_NONE) 309 310 /** 311 * \brief Mask for return value from lzma_index_checks() for check CRC32 312 */ 313 #define LZMA_INDEX_CHECK_MASK_CRC32 (UINT32_C(1) << LZMA_CHECK_CRC32) 314 315 /** 316 * \brief Mask for return value from lzma_index_checks() for check CRC64 317 */ 318 #define LZMA_INDEX_CHECK_MASK_CRC64 (UINT32_C(1) << LZMA_CHECK_CRC64) 319 320 /** 321 * \brief Mask for return value from lzma_index_checks() for check SHA256 322 */ 323 #define LZMA_INDEX_CHECK_MASK_SHA256 (UINT32_C(1) << LZMA_CHECK_SHA256) 324 325 /** 326 * \brief Calculate memory usage of lzma_index 327 * 328 * On disk, the size of the Index field depends on both the number of Records 329 * stored and the size of the Records (due to variable-length integer 330 * encoding). When the Index is kept in lzma_index structure, the memory usage 331 * depends only on the number of Records/Blocks stored in the Index(es), and 332 * in case of concatenated lzma_indexes, the number of Streams. The size in 333 * RAM is almost always significantly bigger than in the encoded form on disk. 334 * 335 * This function calculates an approximate amount of memory needed to hold 336 * the given number of Streams and Blocks in lzma_index structure. This 337 * value may vary between CPU architectures and also between liblzma versions 338 * if the internal implementation is modified. 339 * 340 * \param streams Number of Streams 341 * \param blocks Number of Blocks 342 * 343 * \return Approximate memory in bytes needed in a lzma_index structure. 344 */ 345 extern LZMA_API(uint64_t) lzma_index_memusage( 346 lzma_vli streams, lzma_vli blocks) lzma_nothrow; 347 348 349 /** 350 * \brief Calculate the memory usage of an existing lzma_index 351 * 352 * This is a shorthand for lzma_index_memusage(lzma_index_stream_count(i), 353 * lzma_index_block_count(i)). 354 * 355 * \param i Pointer to lzma_index structure 356 * 357 * \return Approximate memory in bytes used by the lzma_index structure. 358 */ 359 extern LZMA_API(uint64_t) lzma_index_memused(const lzma_index *i) 360 lzma_nothrow; 361 362 363 /** 364 * \brief Allocate and initialize a new lzma_index structure 365 * 366 * \param allocator lzma_allocator for custom allocator functions. 367 * Set to NULL to use malloc() and free(). 368 * 369 * \return On success, a pointer to an empty initialized lzma_index is 370 * returned. If allocation fails, NULL is returned. 371 */ 372 extern LZMA_API(lzma_index *) lzma_index_init(const lzma_allocator *allocator) 373 lzma_nothrow; 374 375 376 /** 377 * \brief Deallocate lzma_index 378 * 379 * If i is NULL, this does nothing. 380 * 381 * \param i Pointer to lzma_index structure to deallocate 382 * \param allocator lzma_allocator for custom allocator functions. 383 * Set to NULL to use malloc() and free(). 384 */ 385 extern LZMA_API(void) lzma_index_end( 386 lzma_index *i, const lzma_allocator *allocator) lzma_nothrow; 387 388 389 /** 390 * \brief Add a new Block to lzma_index 391 * 392 * \param i Pointer to a lzma_index structure 393 * \param allocator lzma_allocator for custom allocator 394 * functions. Set to NULL to use malloc() 395 * and free(). 396 * \param unpadded_size Unpadded Size of a Block. This can be 397 * calculated with lzma_block_unpadded_size() 398 * after encoding or decoding the Block. 399 * \param uncompressed_size Uncompressed Size of a Block. This can be 400 * taken directly from lzma_block structure 401 * after encoding or decoding the Block. 402 * 403 * Appending a new Block does not invalidate iterators. For example, 404 * if an iterator was pointing to the end of the lzma_index, after 405 * lzma_index_append() it is possible to read the next Block with 406 * an existing iterator. 407 * 408 * \return Possible lzma_ret values: 409 * - LZMA_OK 410 * - LZMA_MEM_ERROR 411 * - LZMA_DATA_ERROR: Compressed or uncompressed size of the 412 * Stream or size of the Index field would grow too big. 413 * - LZMA_PROG_ERROR 414 */ 415 extern LZMA_API(lzma_ret) lzma_index_append( 416 lzma_index *i, const lzma_allocator *allocator, 417 lzma_vli unpadded_size, lzma_vli uncompressed_size) 418 lzma_nothrow lzma_attr_warn_unused_result; 419 420 421 /** 422 * \brief Set the Stream Flags 423 * 424 * Set the Stream Flags of the last (and typically the only) Stream 425 * in lzma_index. This can be useful when reading information from the 426 * lzma_index, because to decode Blocks, knowing the integrity check type 427 * is needed. 428 * 429 * \param i Pointer to lzma_index structure 430 * \param stream_flags Pointer to lzma_stream_flags structure. This 431 * is copied into the internal preallocated 432 * structure, so the caller doesn't need to keep 433 * the flags' data available after calling this 434 * function. 435 * 436 * \return Possible lzma_ret values: 437 * - LZMA_OK 438 * - LZMA_OPTIONS_ERROR: Unsupported stream_flags->version. 439 * - LZMA_PROG_ERROR 440 */ 441 extern LZMA_API(lzma_ret) lzma_index_stream_flags( 442 lzma_index *i, const lzma_stream_flags *stream_flags) 443 lzma_nothrow lzma_attr_warn_unused_result; 444 445 446 /** 447 * \brief Get the types of integrity Checks 448 * 449 * If lzma_index_stream_flags() is used to set the Stream Flags for 450 * every Stream, lzma_index_checks() can be used to get a bitmask to 451 * indicate which Check types have been used. It can be useful e.g. if 452 * showing the Check types to the user. 453 * 454 * The bitmask is 1 << check_id, e.g. CRC32 is 1 << 1 and SHA-256 is 1 << 10. 455 * These masks are defined for convenience as LZMA_INDEX_CHECK_MASK_XXX 456 * 457 * \param i Pointer to lzma_index structure 458 * 459 * \return Bitmask indicating which Check types are used in the lzma_index 460 */ 461 extern LZMA_API(uint32_t) lzma_index_checks(const lzma_index *i) 462 lzma_nothrow lzma_attr_pure; 463 464 465 /** 466 * \brief Set the amount of Stream Padding 467 * 468 * Set the amount of Stream Padding of the last (and typically the only) 469 * Stream in the lzma_index. This is needed when planning to do random-access 470 * reading within multiple concatenated Streams. 471 * 472 * By default, the amount of Stream Padding is assumed to be zero bytes. 473 * 474 * \return Possible lzma_ret values: 475 * - LZMA_OK 476 * - LZMA_DATA_ERROR: The file size would grow too big. 477 * - LZMA_PROG_ERROR 478 */ 479 extern LZMA_API(lzma_ret) lzma_index_stream_padding( 480 lzma_index *i, lzma_vli stream_padding) 481 lzma_nothrow lzma_attr_warn_unused_result; 482 483 484 /** 485 * \brief Get the number of Streams 486 * 487 * \param i Pointer to lzma_index structure 488 * 489 * \return Number of Streams in the lzma_index 490 */ 491 extern LZMA_API(lzma_vli) lzma_index_stream_count(const lzma_index *i) 492 lzma_nothrow lzma_attr_pure; 493 494 495 /** 496 * \brief Get the number of Blocks 497 * 498 * This returns the total number of Blocks in lzma_index. To get number 499 * of Blocks in individual Streams, use lzma_index_iter. 500 * 501 * \param i Pointer to lzma_index structure 502 * 503 * \return Number of blocks in the lzma_index 504 */ 505 extern LZMA_API(lzma_vli) lzma_index_block_count(const lzma_index *i) 506 lzma_nothrow lzma_attr_pure; 507 508 509 /** 510 * \brief Get the size of the Index field as bytes 511 * 512 * This is needed to verify the Backward Size field in the Stream Footer. 513 * 514 * \param i Pointer to lzma_index structure 515 * 516 * \return Size in bytes of the Index 517 */ 518 extern LZMA_API(lzma_vli) lzma_index_size(const lzma_index *i) 519 lzma_nothrow lzma_attr_pure; 520 521 522 /** 523 * \brief Get the total size of the Stream 524 * 525 * If multiple lzma_indexes have been combined, this works as if the Blocks 526 * were in a single Stream. This is useful if you are going to combine 527 * Blocks from multiple Streams into a single new Stream. 528 * 529 * \param i Pointer to lzma_index structure 530 * 531 * \return Size in bytes of the Stream (if all Blocks are combined 532 * into one Stream). 533 */ 534 extern LZMA_API(lzma_vli) lzma_index_stream_size(const lzma_index *i) 535 lzma_nothrow lzma_attr_pure; 536 537 538 /** 539 * \brief Get the total size of the Blocks 540 * 541 * This doesn't include the Stream Header, Stream Footer, Stream Padding, 542 * or Index fields. 543 * 544 * \param i Pointer to lzma_index structure 545 * 546 * \return Size in bytes of all Blocks in the Stream(s) 547 */ 548 extern LZMA_API(lzma_vli) lzma_index_total_size(const lzma_index *i) 549 lzma_nothrow lzma_attr_pure; 550 551 552 /** 553 * \brief Get the total size of the file 554 * 555 * When no lzma_indexes have been combined with lzma_index_cat() and there is 556 * no Stream Padding, this function is identical to lzma_index_stream_size(). 557 * If multiple lzma_indexes have been combined, this includes also the headers 558 * of each separate Stream and the possible Stream Padding fields. 559 * 560 * \param i Pointer to lzma_index structure 561 * 562 * \return Total size of the .xz file in bytes 563 */ 564 extern LZMA_API(lzma_vli) lzma_index_file_size(const lzma_index *i) 565 lzma_nothrow lzma_attr_pure; 566 567 568 /** 569 * \brief Get the uncompressed size of the file 570 * 571 * \param i Pointer to lzma_index structure 572 * 573 * \return Size in bytes of the uncompressed data in the file 574 */ 575 extern LZMA_API(lzma_vli) lzma_index_uncompressed_size(const lzma_index *i) 576 lzma_nothrow lzma_attr_pure; 577 578 579 /** 580 * \brief Initialize an iterator 581 * 582 * This function associates the iterator with the given lzma_index, and calls 583 * lzma_index_iter_rewind() on the iterator. 584 * 585 * This function doesn't allocate any memory, thus there is no 586 * lzma_index_iter_end(). The iterator is valid as long as the 587 * associated lzma_index is valid, that is, until lzma_index_end() or 588 * using it as source in lzma_index_cat(). Specifically, lzma_index doesn't 589 * become invalid if new Blocks are added to it with lzma_index_append() or 590 * if it is used as the destination in lzma_index_cat(). 591 * 592 * It is safe to make copies of an initialized lzma_index_iter, for example, 593 * to easily restart reading at some particular position. 594 * 595 * \param iter Pointer to a lzma_index_iter structure 596 * \param i lzma_index to which the iterator will be associated 597 */ 598 extern LZMA_API(void) lzma_index_iter_init( 599 lzma_index_iter *iter, const lzma_index *i) lzma_nothrow; 600 601 602 /** 603 * \brief Rewind the iterator 604 * 605 * Rewind the iterator so that next call to lzma_index_iter_next() will 606 * return the first Block or Stream. 607 * 608 * \param iter Pointer to a lzma_index_iter structure 609 */ 610 extern LZMA_API(void) lzma_index_iter_rewind(lzma_index_iter *iter) 611 lzma_nothrow; 612 613 614 /** 615 * \brief Get the next Block or Stream 616 * 617 * \param iter Iterator initialized with lzma_index_iter_init() 618 * \param mode Specify what kind of information the caller wants 619 * to get. See lzma_index_iter_mode for details. 620 * 621 * \return lzma_bool: 622 * - true if no Block or Stream matching the mode is found. 623 * *iter is not updated (failure). 624 * - false if the next Block or Stream matching the mode was 625 * found. *iter is updated (success). 626 */ 627 extern LZMA_API(lzma_bool) lzma_index_iter_next( 628 lzma_index_iter *iter, lzma_index_iter_mode mode) 629 lzma_nothrow lzma_attr_warn_unused_result; 630 631 632 /** 633 * \brief Locate a Block 634 * 635 * If it is possible to seek in the .xz file, it is possible to parse 636 * the Index field(s) and use lzma_index_iter_locate() to do random-access 637 * reading with granularity of Block size. 638 * 639 * If the target is smaller than the uncompressed size of the Stream (can be 640 * checked with lzma_index_uncompressed_size()): 641 * - Information about the Stream and Block containing the requested 642 * uncompressed offset is stored into *iter. 643 * - Internal state of the iterator is adjusted so that 644 * lzma_index_iter_next() can be used to read subsequent Blocks or Streams. 645 * 646 * If the target is greater than the uncompressed size of the Stream, *iter 647 * is not modified. 648 * 649 * \param iter Iterator that was earlier initialized with 650 * lzma_index_iter_init(). 651 * \param target Uncompressed target offset which the caller would 652 * like to locate from the Stream 653 * 654 * \return lzma_bool: 655 * - true if the target is greater than or equal to the 656 * uncompressed size of the Stream (failure) 657 * - false if the target is smaller than the uncompressed size 658 * of the Stream (success) 659 */ 660 extern LZMA_API(lzma_bool) lzma_index_iter_locate( 661 lzma_index_iter *iter, lzma_vli target) lzma_nothrow; 662 663 664 /** 665 * \brief Concatenate lzma_indexes 666 * 667 * Concatenating lzma_indexes is useful when doing random-access reading in 668 * multi-Stream .xz file, or when combining multiple Streams into single 669 * Stream. 670 * 671 * \param[out] dest lzma_index after which src is appended 672 * \param src lzma_index to be appended after dest. If this 673 * function succeeds, the memory allocated for src 674 * is freed or moved to be part of dest, and all 675 * iterators pointing to src will become invalid. 676 * \param allocator lzma_allocator for custom allocator functions. 677 * Set to NULL to use malloc() and free(). 678 * 679 * \return Possible lzma_ret values: 680 * - LZMA_OK: lzma_indexes were concatenated successfully. 681 * src is now a dangling pointer. 682 * - LZMA_DATA_ERROR: *dest would grow too big. 683 * - LZMA_MEM_ERROR 684 * - LZMA_PROG_ERROR 685 */ 686 extern LZMA_API(lzma_ret) lzma_index_cat(lzma_index *dest, lzma_index *src, 687 const lzma_allocator *allocator) 688 lzma_nothrow lzma_attr_warn_unused_result; 689 690 691 /** 692 * \brief Duplicate lzma_index 693 * 694 * \param i Pointer to lzma_index structure to be duplicated 695 * \param allocator lzma_allocator for custom allocator functions. 696 * Set to NULL to use malloc() and free(). 697 * 698 * \return A copy of the lzma_index, or NULL if memory allocation failed. 699 */ 700 extern LZMA_API(lzma_index *) lzma_index_dup( 701 const lzma_index *i, const lzma_allocator *allocator) 702 lzma_nothrow lzma_attr_warn_unused_result; 703 704 705 /** 706 * \brief Initialize .xz Index encoder 707 * 708 * \param strm Pointer to properly prepared lzma_stream 709 * \param i Pointer to lzma_index which should be encoded. 710 * 711 * The valid 'action' values for lzma_code() are LZMA_RUN and LZMA_FINISH. 712 * It is enough to use only one of them (you can choose freely). 713 * 714 * \return Possible lzma_ret values: 715 * - LZMA_OK: Initialization succeeded, continue with lzma_code(). 716 * - LZMA_MEM_ERROR 717 * - LZMA_PROG_ERROR 718 */ 719 extern LZMA_API(lzma_ret) lzma_index_encoder( 720 lzma_stream *strm, const lzma_index *i) 721 lzma_nothrow lzma_attr_warn_unused_result; 722 723 724 /** 725 * \brief Initialize .xz Index decoder 726 * 727 * \param strm Pointer to properly prepared lzma_stream 728 * \param[out] i The decoded Index will be made available via 729 * this pointer. Initially this function will 730 * set *i to NULL (the old value is ignored). If 731 * decoding succeeds (lzma_code() returns 732 * LZMA_STREAM_END), *i will be set to point 733 * to a new lzma_index, which the application 734 * has to later free with lzma_index_end(). 735 * \param memlimit How much memory the resulting lzma_index is 736 * allowed to require. liblzma 5.2.3 and earlier 737 * don't allow 0 here and return LZMA_PROG_ERROR; 738 * later versions treat 0 as if 1 had been specified. 739 * 740 * Valid 'action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. 741 * There is no need to use LZMA_FINISH, but it's allowed because it may 742 * simplify certain types of applications. 743 * 744 * \return Possible lzma_ret values: 745 * - LZMA_OK: Initialization succeeded, continue with lzma_code(). 746 * - LZMA_MEM_ERROR 747 * - LZMA_PROG_ERROR 748 * 749 * \note liblzma 5.2.3 and older list also LZMA_MEMLIMIT_ERROR here 750 * but that error code has never been possible from this 751 * initialization function. 752 */ 753 extern LZMA_API(lzma_ret) lzma_index_decoder( 754 lzma_stream *strm, lzma_index **i, uint64_t memlimit) 755 lzma_nothrow lzma_attr_warn_unused_result; 756 757 758 /** 759 * \brief Single-call .xz Index encoder 760 * 761 * \note This function doesn't take allocator argument since all 762 * the internal data is allocated on stack. 763 * 764 * \param i lzma_index to be encoded 765 * \param[out] out Beginning of the output buffer 766 * \param[out] out_pos The next byte will be written to out[*out_pos]. 767 * *out_pos is updated only if encoding succeeds. 768 * \param out_size Size of the out buffer; the first byte into 769 * which no data is written to is out[out_size]. 770 * 771 * \return Possible lzma_ret values: 772 * - LZMA_OK: Encoding was successful. 773 * - LZMA_BUF_ERROR: Output buffer is too small. Use 774 * lzma_index_size() to find out how much output 775 * space is needed. 776 * - LZMA_PROG_ERROR 777 * 778 */ 779 extern LZMA_API(lzma_ret) lzma_index_buffer_encode(const lzma_index *i, 780 uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow; 781 782 783 /** 784 * \brief Single-call .xz Index decoder 785 * 786 * \param[out] i If decoding succeeds, *i will point to a new 787 * lzma_index, which the application has to 788 * later free with lzma_index_end(). If an error 789 * occurs, *i will be NULL. The old value of *i 790 * is always ignored and thus doesn't need to be 791 * initialized by the caller. 792 * \param[out] memlimit Pointer to how much memory the resulting 793 * lzma_index is allowed to require. The value 794 * pointed by this pointer is modified if and only 795 * if LZMA_MEMLIMIT_ERROR is returned. 796 * \param allocator lzma_allocator for custom allocator functions. 797 * Set to NULL to use malloc() and free(). 798 * \param in Beginning of the input buffer 799 * \param in_pos The next byte will be read from in[*in_pos]. 800 * *in_pos is updated only if decoding succeeds. 801 * \param in_size Size of the input buffer; the first byte that 802 * won't be read is in[in_size]. 803 * 804 * \return Possible lzma_ret values: 805 * - LZMA_OK: Decoding was successful. 806 * - LZMA_MEM_ERROR 807 * - LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. 808 * The minimum required memlimit value was stored to *memlimit. 809 * - LZMA_DATA_ERROR 810 * - LZMA_PROG_ERROR 811 */ 812 extern LZMA_API(lzma_ret) lzma_index_buffer_decode(lzma_index **i, 813 uint64_t *memlimit, const lzma_allocator *allocator, 814 const uint8_t *in, size_t *in_pos, size_t in_size) 815 lzma_nothrow; 816 817 818 /** 819 * \brief Initialize a .xz file information decoder 820 * 821 * This decoder decodes the Stream Header, Stream Footer, Index, and 822 * Stream Padding field(s) from the input .xz file and stores the resulting 823 * combined index in *dest_index. This information can be used to get the 824 * uncompressed file size with lzma_index_uncompressed_size(*dest_index) or, 825 * for example, to implement random access reading by locating the Blocks 826 * in the Streams. 827 * 828 * To get the required information from the .xz file, lzma_code() may ask 829 * the application to seek in the input file by returning LZMA_SEEK_NEEDED 830 * and having the target file position specified in lzma_stream.seek_pos. 831 * The number of seeks required depends on the input file and how big buffers 832 * the application provides. When possible, the decoder will seek backward 833 * and forward in the given buffer to avoid useless seek requests. Thus, if 834 * the application provides the whole file at once, no external seeking will 835 * be required (that is, lzma_code() won't return LZMA_SEEK_NEEDED). 836 * 837 * The value in lzma_stream.total_in can be used to estimate how much data 838 * liblzma had to read to get the file information. However, due to seeking 839 * and the way total_in is updated, the value of total_in will be somewhat 840 * inaccurate (a little too big). Thus, total_in is a good estimate but don't 841 * expect to see the same exact value for the same file if you change the 842 * input buffer size or switch to a different liblzma version. 843 * 844 * Valid 'action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. 845 * You only need to use LZMA_RUN; LZMA_FINISH is only supported because it 846 * might be convenient for some applications. If you use LZMA_FINISH and if 847 * lzma_code() asks the application to seek, remember to reset 'action' back 848 * to LZMA_RUN unless you hit the end of the file again. 849 * 850 * Possible return values from lzma_code(): 851 * - LZMA_OK: All OK so far, more input needed 852 * - LZMA_SEEK_NEEDED: Provide more input starting from the absolute 853 * file position strm->seek_pos 854 * - LZMA_STREAM_END: Decoding was successful, *dest_index has been set 855 * - LZMA_FORMAT_ERROR: The input file is not in the .xz format (the 856 * expected magic bytes were not found from the beginning of the file) 857 * - LZMA_OPTIONS_ERROR: File looks valid but contains headers that aren't 858 * supported by this version of liblzma 859 * - LZMA_DATA_ERROR: File is corrupt 860 * - LZMA_BUF_ERROR 861 * - LZMA_MEM_ERROR 862 * - LZMA_MEMLIMIT_ERROR 863 * - LZMA_PROG_ERROR 864 * 865 * \param strm Pointer to a properly prepared lzma_stream 866 * \param[out] dest_index Pointer to a pointer where the decoder will put 867 * the decoded lzma_index. The old value 868 * of *dest_index is ignored (not freed). 869 * \param memlimit How much memory the resulting lzma_index is 870 * allowed to require. Use UINT64_MAX to 871 * effectively disable the limiter. 872 * \param file_size Size of the input .xz file 873 * 874 * \return Possible lzma_ret values: 875 * - LZMA_OK 876 * - LZMA_MEM_ERROR 877 * - LZMA_PROG_ERROR 878 */ 879 extern LZMA_API(lzma_ret) lzma_file_info_decoder( 880 lzma_stream *strm, lzma_index **dest_index, 881 uint64_t memlimit, uint64_t file_size) 882 lzma_nothrow; 883