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