1119418Sobrien/** 266703Sarchie * \file lzma/index.h 366703Sarchie * \brief Handling of .xz Index and related information 4119418Sobrien */ 566703Sarchie 666703Sarchie/* 7119418Sobrien * Author: Lasse Collin 8284247Srpaulo * 966703Sarchie * This file has been put into the public domain. 1066703Sarchie * You can do whatever you want with this file. 1166703Sarchie * 1266703Sarchie * See ../lzma.h for information about liblzma as a whole. 1366703Sarchie */ 1466703Sarchie 1566703Sarchie#ifndef LZMA_H_INTERNAL 1666703Sarchie# error Never include this file directly. Use <lzma.h> instead. 1766703Sarchie#endif 1866703Sarchie 19284247Srpaulo 2066703Sarchie/** 2166703Sarchie * \brief Opaque data type to hold the Index(es) and other information 2266703Sarchie * 2366703Sarchie * lzma_index often holds just one .xz Index and possibly the Stream Flags 2466703Sarchie * of the same Stream and size of the Stream Padding field. However, 2566703Sarchie * multiple lzma_indexes can be concatenated with lzma_index_cat() and then 2666703Sarchie * there may be information about multiple Streams in the same lzma_index. 2766703Sarchie * 2866703Sarchie * Notes about thread safety: Only one thread may modify lzma_index at 2966703Sarchie * a time. All functions that take non-const pointer to lzma_index 3066703Sarchie * modify it. As long as no thread is modifying the lzma_index, getting 3166703Sarchie * information from the same lzma_index can be done from multiple threads 3266703Sarchie * at the same time with functions that take a const pointer to 3366703Sarchie * lzma_index or use lzma_index_iter. The same iterator must be used 3466703Sarchie * only by one thread at a time, of course, but there can be as many 3566703Sarchie * iterators for the same lzma_index as needed. 3666703Sarchie */ 3766703Sarchietypedef struct lzma_index_s lzma_index; 3866703Sarchie 39119418Sobrien 40119418Sobrien/** 41119418Sobrien * \brief Iterator to get information about Blocks and Streams 4266703Sarchie */ 4366703Sarchietypedef struct { 44119618Snjl struct { 4566703Sarchie /** 4666703Sarchie * \brief Pointer to Stream Flags 4766703Sarchie * 4866703Sarchie * This is NULL if Stream Flags have not been set for 4966703Sarchie * this Stream with lzma_index_stream_flags(). 50129879Sphk */ 5166703Sarchie const lzma_stream_flags *flags; 5274914Sjhb 5369734Sarchie const void *reserved_ptr1; 5466703Sarchie const void *reserved_ptr2; 5566703Sarchie const void *reserved_ptr3; 5666703Sarchie 5766703Sarchie /** 5866703Sarchie * \brief Stream number in the lzma_index 5966703Sarchie * 6066703Sarchie * The first Stream is 1. 61119280Simp */ 62119280Simp lzma_vli number; 6366703Sarchie 6466703Sarchie /** 6566703Sarchie * \brief Number of Blocks in the Stream 6666703Sarchie * 6766703Sarchie * If this is zero, the block structure below has 6866703Sarchie * undefined values. 6966703Sarchie */ 70321931Sgavin lzma_vli block_count; 71321931Sgavin 72321931Sgavin /** 73321931Sgavin * \brief Compressed start offset of this Stream 74321931Sgavin * 75321931Sgavin * The offset is relative to the beginning of the lzma_index 76321931Sgavin * (i.e. usually the beginning of the .xz file). 77321931Sgavin */ 78321931Sgavin lzma_vli compressed_offset; 79321931Sgavin 80321931Sgavin /** 81321931Sgavin * \brief Uncompressed start offset of this Stream 82321931Sgavin * 83321931Sgavin * The offset is relative to the beginning of the lzma_index 84321931Sgavin * (i.e. usually the beginning of the .xz file). 85321931Sgavin */ 86321931Sgavin lzma_vli uncompressed_offset; 87321931Sgavin 88321931Sgavin /** 89321931Sgavin * \brief Compressed size of this Stream 90321931Sgavin * 91321931Sgavin * This includes all headers except the possible 92321931Sgavin * Stream Padding after this Stream. 93321931Sgavin */ 94321931Sgavin lzma_vli compressed_size; 95321931Sgavin 96321931Sgavin /** 97321931Sgavin * \brief Uncompressed size of this Stream 98321931Sgavin */ 99321931Sgavin lzma_vli uncompressed_size; 100321931Sgavin 101321931Sgavin /** 102321931Sgavin * \brief Size of Stream Padding after this Stream 103321931Sgavin * 104321931Sgavin * If it hasn't been set with lzma_index_stream_padding(), 105321931Sgavin * this defaults to zero. Stream Padding is always 106321931Sgavin * a multiple of four bytes. 107345820Smav */ 10866703Sarchie lzma_vli padding; 109321931Sgavin 110321931Sgavin lzma_vli reserved_vli1; 111321931Sgavin lzma_vli reserved_vli2; 112321931Sgavin lzma_vli reserved_vli3; 113321931Sgavin lzma_vli reserved_vli4; 114321931Sgavin } stream; 115321931Sgavin 116321931Sgavin struct { 117321931Sgavin /** 118321931Sgavin * \brief Block number in the file 119321931Sgavin * 120321931Sgavin * The first Block is 1. 121321931Sgavin */ 122321931Sgavin lzma_vli number_in_file; 123321931Sgavin 124321931Sgavin /** 125321931Sgavin * \brief Compressed start offset of this Block 126321931Sgavin * 127321931Sgavin * This offset is relative to the beginning of the 128321931Sgavin * lzma_index (i.e. usually the beginning of the .xz file). 129321931Sgavin * Normally this is where you should seek in the .xz file 130321931Sgavin * to start decompressing this Block. 131321931Sgavin */ 132321931Sgavin lzma_vli compressed_file_offset; 133321931Sgavin 134321931Sgavin /** 135321931Sgavin * \brief Uncompressed start offset of this Block 136321931Sgavin * 137321931Sgavin * This offset is relative to the beginning of the lzma_index 138321931Sgavin * (i.e. usually the beginning of the .xz file). 139321931Sgavin * 140321931Sgavin * When doing random-access reading, it is possible that 141321931Sgavin * the target offset is not exactly at Block boundary. One 142321931Sgavin * will need to compare the target offset against 143321931Sgavin * uncompressed_file_offset or uncompressed_stream_offset, 144321931Sgavin * and possibly decode and throw away some amount of data 145321931Sgavin * before reaching the target offset. 146321931Sgavin */ 147321931Sgavin lzma_vli uncompressed_file_offset; 148321931Sgavin 149321931Sgavin /** 150321931Sgavin * \brief Block number in this Stream 151321931Sgavin * 152345820Smav * The first Block is 1. 153321931Sgavin */ 154321931Sgavin lzma_vli number_in_stream; 15566703Sarchie 15666703Sarchie /** 15766703Sarchie * \brief Compressed start offset of this Block 15866703Sarchie * 159147253Stakawata * This offset is relative to the beginning of the Stream 160147253Stakawata * containing this Block. 161147253Stakawata */ 162147253Stakawata lzma_vli compressed_stream_offset; 16366703Sarchie 16466703Sarchie /** 16566703Sarchie * \brief Uncompressed start offset of this Block 16666703Sarchie * 16766703Sarchie * This offset is relative to the beginning of the Stream 16866703Sarchie * containing this Block. 169147253Stakawata */ 17066703Sarchie lzma_vli uncompressed_stream_offset; 17166703Sarchie 17266703Sarchie /** 17366703Sarchie * \brief Uncompressed size of this Block 17466703Sarchie * 17566703Sarchie * You should pass this to the Block decoder if you will 17666703Sarchie * decode this Block. It will allow the Block decoder to 17766703Sarchie * validate the uncompressed size. 17866703Sarchie */ 17966703Sarchie lzma_vli uncompressed_size; 18066703Sarchie 18166703Sarchie /** 18266703Sarchie * \brief Unpadded size of this Block 183227843Smarius * 184227843Smarius * You should pass this to the Block decoder if you will 18566703Sarchie * decode this Block. It will allow the Block decoder to 18666703Sarchie * validate the unpadded size. 18766703Sarchie */ 18866703Sarchie lzma_vli unpadded_size; 18966703Sarchie 19066703Sarchie /** 19166703Sarchie * \brief Total compressed size 19266703Sarchie * 19366703Sarchie * This includes all headers and padding in this Block. 19466703Sarchie * This is useful if you need to know how many bytes 19566703Sarchie * the Block decoder will actually read. 19666703Sarchie */ 19766703Sarchie lzma_vli total_size; 19866703Sarchie 19966703Sarchie lzma_vli reserved_vli1; 200321931Sgavin lzma_vli reserved_vli2; 201321931Sgavin lzma_vli reserved_vli3; 202321931Sgavin lzma_vli reserved_vli4; 20366703Sarchie 204321931Sgavin const void *reserved_ptr1; 205321931Sgavin const void *reserved_ptr2; 206321931Sgavin const void *reserved_ptr3; 207321931Sgavin const void *reserved_ptr4; 208321931Sgavin } block; 209321931Sgavin 21066703Sarchie /* 21166703Sarchie * Internal data which is used to store the state of the iterator. 212321931Sgavin * The exact format may vary between liblzma versions, so don't 21366703Sarchie * touch these in any way. 21466703Sarchie */ 21566703Sarchie union { 21666703Sarchie const void *p; 21766703Sarchie size_t s; 21866703Sarchie lzma_vli v; 21966703Sarchie } internal[6]; 22066703Sarchie} lzma_index_iter; 22166703Sarchie 22266703Sarchie 22366703Sarchie/** 22466703Sarchie * \brief Operation mode for lzma_index_iter_next() 22566703Sarchie */ 22666703Sarchietypedef enum { 22766703Sarchie LZMA_INDEX_ITER_ANY = 0, 228296137Sjhibbits /**< 229296137Sjhibbits * \brief Get the next Block or Stream 230131070Sambrisko * 231296137Sjhibbits * Go to the next Block if the current Stream has at least 232296137Sjhibbits * one Block left. Otherwise go to the next Stream even if 23366703Sarchie * it has no Blocks. If the Stream has no Blocks 234165951Sjhb * (lzma_index_iter.stream.block_count == 0), 23566703Sarchie * lzma_index_iter.block will have undefined values. 23666703Sarchie */ 23766703Sarchie 23866703Sarchie LZMA_INDEX_ITER_STREAM = 1, 23966703Sarchie /**< 24066703Sarchie * \brief Get the next Stream 241127135Snjl * 242127135Snjl * Go to the next Stream even if the current Stream has 24366703Sarchie * unread Blocks left. If the next Stream has at least one 244165951Sjhb * Block, the iterator will point to the first Block. 24566703Sarchie * If there are no Blocks, lzma_index_iter.block will have 24666703Sarchie * undefined values. 24766703Sarchie */ 24866703Sarchie 24966703Sarchie LZMA_INDEX_ITER_BLOCK = 2, 25066703Sarchie /**< 25166703Sarchie * \brief Get the next Block 25266703Sarchie * 253165951Sjhb * Go to the next Block if the current Stream has at least 254165951Sjhb * one Block left. If the current Stream has no Blocks left, 255165951Sjhb * the next Stream with at least one Block is located and 256165951Sjhb * the iterator will be made to point to the first Block of 25766703Sarchie * that Stream. 25866703Sarchie */ 25966703Sarchie 26066703Sarchie LZMA_INDEX_ITER_NONEMPTY_BLOCK = 3 26166703Sarchie /**< 26266703Sarchie * \brief Get the next non-empty Block 26366703Sarchie * 264147253Stakawata * This is like LZMA_INDEX_ITER_BLOCK except that it will 265146996Stakawata * skip Blocks whose Uncompressed Size is zero. 266146996Stakawata */ 267146996Stakawata 268} lzma_index_iter_mode; 269 270 271/** 272 * \brief Calculate memory usage of lzma_index 273 * 274 * On disk, the size of the Index field depends on both the number of Records 275 * stored and how big values the Records store (due to variable-length integer 276 * encoding). When the Index is kept in lzma_index structure, the memory usage 277 * depends only on the number of Records/Blocks stored in the Index(es), and 278 * in case of concatenated lzma_indexes, the number of Streams. The size in 279 * RAM is almost always significantly bigger than in the encoded form on disk. 280 * 281 * This function calculates an approximate amount of memory needed hold 282 * the given number of Streams and Blocks in lzma_index structure. This 283 * value may vary between CPU architectures and also between liblzma versions 284 * if the internal implementation is modified. 285 */ 286extern LZMA_API(uint64_t) lzma_index_memusage( 287 lzma_vli streams, lzma_vli blocks) lzma_nothrow; 288 289 290/** 291 * \brief Calculate the memory usage of an existing lzma_index 292 * 293 * This is a shorthand for lzma_index_memusage(lzma_index_stream_count(i), 294 * lzma_index_block_count(i)). 295 */ 296extern LZMA_API(uint64_t) lzma_index_memused(const lzma_index *i) 297 lzma_nothrow; 298 299 300/** 301 * \brief Allocate and initialize a new lzma_index structure 302 * 303 * \return On success, a pointer to an empty initialized lzma_index is 304 * returned. If allocation fails, NULL is returned. 305 */ 306extern LZMA_API(lzma_index *) lzma_index_init(const lzma_allocator *allocator) 307 lzma_nothrow; 308 309 310/** 311 * \brief Deallocate lzma_index 312 * 313 * If i is NULL, this does nothing. 314 */ 315extern LZMA_API(void) lzma_index_end( 316 lzma_index *i, const lzma_allocator *allocator) lzma_nothrow; 317 318 319/** 320 * \brief Add a new Block to lzma_index 321 * 322 * \param i Pointer to a lzma_index structure 323 * \param allocator Pointer to lzma_allocator, or NULL to 324 * use malloc() 325 * \param unpadded_size Unpadded Size of a Block. This can be 326 * calculated with lzma_block_unpadded_size() 327 * after encoding or decoding the Block. 328 * \param uncompressed_size Uncompressed Size of a Block. This can be 329 * taken directly from lzma_block structure 330 * after encoding or decoding the Block. 331 * 332 * Appending a new Block does not invalidate iterators. For example, 333 * if an iterator was pointing to the end of the lzma_index, after 334 * lzma_index_append() it is possible to read the next Block with 335 * an existing iterator. 336 * 337 * \return - LZMA_OK 338 * - LZMA_MEM_ERROR 339 * - LZMA_DATA_ERROR: Compressed or uncompressed size of the 340 * Stream or size of the Index field would grow too big. 341 * - LZMA_PROG_ERROR 342 */ 343extern LZMA_API(lzma_ret) lzma_index_append( 344 lzma_index *i, const lzma_allocator *allocator, 345 lzma_vli unpadded_size, lzma_vli uncompressed_size) 346 lzma_nothrow lzma_attr_warn_unused_result; 347 348 349/** 350 * \brief Set the Stream Flags 351 * 352 * Set the Stream Flags of the last (and typically the only) Stream 353 * in lzma_index. This can be useful when reading information from the 354 * lzma_index, because to decode Blocks, knowing the integrity check type 355 * is needed. 356 * 357 * The given Stream Flags are copied into internal preallocated structure 358 * in the lzma_index, thus the caller doesn't need to keep the *stream_flags 359 * available after calling this function. 360 * 361 * \return - LZMA_OK 362 * - LZMA_OPTIONS_ERROR: Unsupported stream_flags->version. 363 * - LZMA_PROG_ERROR 364 */ 365extern LZMA_API(lzma_ret) lzma_index_stream_flags( 366 lzma_index *i, const lzma_stream_flags *stream_flags) 367 lzma_nothrow lzma_attr_warn_unused_result; 368 369 370/** 371 * \brief Get the types of integrity Checks 372 * 373 * If lzma_index_stream_flags() is used to set the Stream Flags for 374 * every Stream, lzma_index_checks() can be used to get a bitmask to 375 * indicate which Check types have been used. It can be useful e.g. if 376 * showing the Check types to the user. 377 * 378 * The bitmask is 1 << check_id, e.g. CRC32 is 1 << 1 and SHA-256 is 1 << 10. 379 */ 380extern LZMA_API(uint32_t) lzma_index_checks(const lzma_index *i) 381 lzma_nothrow lzma_attr_pure; 382 383 384/** 385 * \brief Set the amount of Stream Padding 386 * 387 * Set the amount of Stream Padding of the last (and typically the only) 388 * Stream in the lzma_index. This is needed when planning to do random-access 389 * reading within multiple concatenated Streams. 390 * 391 * By default, the amount of Stream Padding is assumed to be zero bytes. 392 * 393 * \return - LZMA_OK 394 * - LZMA_DATA_ERROR: The file size would grow too big. 395 * - LZMA_PROG_ERROR 396 */ 397extern LZMA_API(lzma_ret) lzma_index_stream_padding( 398 lzma_index *i, lzma_vli stream_padding) 399 lzma_nothrow lzma_attr_warn_unused_result; 400 401 402/** 403 * \brief Get the number of Streams 404 */ 405extern LZMA_API(lzma_vli) lzma_index_stream_count(const lzma_index *i) 406 lzma_nothrow lzma_attr_pure; 407 408 409/** 410 * \brief Get the number of Blocks 411 * 412 * This returns the total number of Blocks in lzma_index. To get number 413 * of Blocks in individual Streams, use lzma_index_iter. 414 */ 415extern LZMA_API(lzma_vli) lzma_index_block_count(const lzma_index *i) 416 lzma_nothrow lzma_attr_pure; 417 418 419/** 420 * \brief Get the size of the Index field as bytes 421 * 422 * This is needed to verify the Backward Size field in the Stream Footer. 423 */ 424extern LZMA_API(lzma_vli) lzma_index_size(const lzma_index *i) 425 lzma_nothrow lzma_attr_pure; 426 427 428/** 429 * \brief Get the total size of the Stream 430 * 431 * If multiple lzma_indexes have been combined, this works as if the Blocks 432 * were in a single Stream. This is useful if you are going to combine 433 * Blocks from multiple Streams into a single new Stream. 434 */ 435extern LZMA_API(lzma_vli) lzma_index_stream_size(const lzma_index *i) 436 lzma_nothrow lzma_attr_pure; 437 438 439/** 440 * \brief Get the total size of the Blocks 441 * 442 * This doesn't include the Stream Header, Stream Footer, Stream Padding, 443 * or Index fields. 444 */ 445extern LZMA_API(lzma_vli) lzma_index_total_size(const lzma_index *i) 446 lzma_nothrow lzma_attr_pure; 447 448 449/** 450 * \brief Get the total size of the file 451 * 452 * When no lzma_indexes have been combined with lzma_index_cat() and there is 453 * no Stream Padding, this function is identical to lzma_index_stream_size(). 454 * If multiple lzma_indexes have been combined, this includes also the headers 455 * of each separate Stream and the possible Stream Padding fields. 456 */ 457extern LZMA_API(lzma_vli) lzma_index_file_size(const lzma_index *i) 458 lzma_nothrow lzma_attr_pure; 459 460 461/** 462 * \brief Get the uncompressed size of the file 463 */ 464extern LZMA_API(lzma_vli) lzma_index_uncompressed_size(const lzma_index *i) 465 lzma_nothrow lzma_attr_pure; 466 467 468/** 469 * \brief Initialize an iterator 470 * 471 * \param iter Pointer to a lzma_index_iter structure 472 * \param i lzma_index to which the iterator will be associated 473 * 474 * This function associates the iterator with the given lzma_index, and calls 475 * lzma_index_iter_rewind() on the iterator. 476 * 477 * This function doesn't allocate any memory, thus there is no 478 * lzma_index_iter_end(). The iterator is valid as long as the 479 * associated lzma_index is valid, that is, until lzma_index_end() or 480 * using it as source in lzma_index_cat(). Specifically, lzma_index doesn't 481 * become invalid if new Blocks are added to it with lzma_index_append() or 482 * if it is used as the destination in lzma_index_cat(). 483 * 484 * It is safe to make copies of an initialized lzma_index_iter, for example, 485 * to easily restart reading at some particular position. 486 */ 487extern LZMA_API(void) lzma_index_iter_init( 488 lzma_index_iter *iter, const lzma_index *i) lzma_nothrow; 489 490 491/** 492 * \brief Rewind the iterator 493 * 494 * Rewind the iterator so that next call to lzma_index_iter_next() will 495 * return the first Block or Stream. 496 */ 497extern LZMA_API(void) lzma_index_iter_rewind(lzma_index_iter *iter) 498 lzma_nothrow; 499 500 501/** 502 * \brief Get the next Block or Stream 503 * 504 * \param iter Iterator initialized with lzma_index_iter_init() 505 * \param mode Specify what kind of information the caller wants 506 * to get. See lzma_index_iter_mode for details. 507 * 508 * \return If next Block or Stream matching the mode was found, *iter 509 * is updated and this function returns false. If no Block or 510 * Stream matching the mode is found, *iter is not modified 511 * and this function returns true. If mode is set to an unknown 512 * value, *iter is not modified and this function returns true. 513 */ 514extern LZMA_API(lzma_bool) lzma_index_iter_next( 515 lzma_index_iter *iter, lzma_index_iter_mode mode) 516 lzma_nothrow lzma_attr_warn_unused_result; 517 518 519/** 520 * \brief Locate a Block 521 * 522 * If it is possible to seek in the .xz file, it is possible to parse 523 * the Index field(s) and use lzma_index_iter_locate() to do random-access 524 * reading with granularity of Block size. 525 * 526 * \param iter Iterator that was earlier initialized with 527 * lzma_index_iter_init(). 528 * \param target Uncompressed target offset which the caller would 529 * like to locate from the Stream 530 * 531 * If the target is smaller than the uncompressed size of the Stream (can be 532 * checked with lzma_index_uncompressed_size()): 533 * - Information about the Stream and Block containing the requested 534 * uncompressed offset is stored into *iter. 535 * - Internal state of the iterator is adjusted so that 536 * lzma_index_iter_next() can be used to read subsequent Blocks or Streams. 537 * - This function returns false. 538 * 539 * If target is greater than the uncompressed size of the Stream, *iter 540 * is not modified, and this function returns true. 541 */ 542extern LZMA_API(lzma_bool) lzma_index_iter_locate( 543 lzma_index_iter *iter, lzma_vli target) lzma_nothrow; 544 545 546/** 547 * \brief Concatenate lzma_indexes 548 * 549 * Concatenating lzma_indexes is useful when doing random-access reading in 550 * multi-Stream .xz file, or when combining multiple Streams into single 551 * Stream. 552 * 553 * \param dest lzma_index after which src is appended 554 * \param src lzma_index to be appended after dest. If this 555 * function succeeds, the memory allocated for src 556 * is freed or moved to be part of dest, and all 557 * iterators pointing to src will become invalid. 558 * \param allocator Custom memory allocator; can be NULL to use 559 * malloc() and free(). 560 * 561 * \return - LZMA_OK: lzma_indexes were concatenated successfully. 562 * src is now a dangling pointer. 563 * - LZMA_DATA_ERROR: *dest would grow too big. 564 * - LZMA_MEM_ERROR 565 * - LZMA_PROG_ERROR 566 */ 567extern LZMA_API(lzma_ret) lzma_index_cat(lzma_index *dest, lzma_index *src, 568 const lzma_allocator *allocator) 569 lzma_nothrow lzma_attr_warn_unused_result; 570 571 572/** 573 * \brief Duplicate lzma_index 574 * 575 * \return A copy of the lzma_index, or NULL if memory allocation failed. 576 */ 577extern LZMA_API(lzma_index *) lzma_index_dup( 578 const lzma_index *i, const lzma_allocator *allocator) 579 lzma_nothrow lzma_attr_warn_unused_result; 580 581 582/** 583 * \brief Initialize .xz Index encoder 584 * 585 * \param strm Pointer to properly prepared lzma_stream 586 * \param i Pointer to lzma_index which should be encoded. 587 * 588 * The valid `action' values for lzma_code() are LZMA_RUN and LZMA_FINISH. 589 * It is enough to use only one of them (you can choose freely; use LZMA_RUN 590 * to support liblzma versions older than 5.0.0). 591 * 592 * \return - LZMA_OK: Initialization succeeded, continue with lzma_code(). 593 * - LZMA_MEM_ERROR 594 * - LZMA_PROG_ERROR 595 */ 596extern LZMA_API(lzma_ret) lzma_index_encoder( 597 lzma_stream *strm, const lzma_index *i) 598 lzma_nothrow lzma_attr_warn_unused_result; 599 600 601/** 602 * \brief Initialize .xz Index decoder 603 * 604 * \param strm Pointer to properly prepared lzma_stream 605 * \param i The decoded Index will be made available via 606 * this pointer. Initially this function will 607 * set *i to NULL (the old value is ignored). If 608 * decoding succeeds (lzma_code() returns 609 * LZMA_STREAM_END), *i will be set to point 610 * to a new lzma_index, which the application 611 * has to later free with lzma_index_end(). 612 * \param memlimit How much memory the resulting lzma_index is 613 * allowed to require. 614 * 615 * The valid `action' values for lzma_code() are LZMA_RUN and LZMA_FINISH. 616 * It is enough to use only one of them (you can choose freely; use LZMA_RUN 617 * to support liblzma versions older than 5.0.0). 618 * 619 * \return - LZMA_OK: Initialization succeeded, continue with lzma_code(). 620 * - LZMA_MEM_ERROR 621 * - LZMA_MEMLIMIT_ERROR 622 * - LZMA_PROG_ERROR 623 */ 624extern LZMA_API(lzma_ret) lzma_index_decoder( 625 lzma_stream *strm, lzma_index **i, uint64_t memlimit) 626 lzma_nothrow lzma_attr_warn_unused_result; 627 628 629/** 630 * \brief Single-call .xz Index encoder 631 * 632 * \param i lzma_index to be encoded 633 * \param out Beginning of the output buffer 634 * \param out_pos The next byte will be written to out[*out_pos]. 635 * *out_pos is updated only if encoding succeeds. 636 * \param out_size Size of the out buffer; the first byte into 637 * which no data is written to is out[out_size]. 638 * 639 * \return - LZMA_OK: Encoding was successful. 640 * - LZMA_BUF_ERROR: Output buffer is too small. Use 641 * lzma_index_size() to find out how much output 642 * space is needed. 643 * - LZMA_PROG_ERROR 644 * 645 * \note This function doesn't take allocator argument since all 646 * the internal data is allocated on stack. 647 */ 648extern LZMA_API(lzma_ret) lzma_index_buffer_encode(const lzma_index *i, 649 uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow; 650 651 652/** 653 * \brief Single-call .xz Index decoder 654 * 655 * \param i If decoding succeeds, *i will point to a new 656 * lzma_index, which the application has to 657 * later free with lzma_index_end(). If an error 658 * occurs, *i will be NULL. The old value of *i 659 * is always ignored and thus doesn't need to be 660 * initialized by the caller. 661 * \param memlimit Pointer to how much memory the resulting 662 * lzma_index is allowed to require. The value 663 * pointed by this pointer is modified if and only 664 * if LZMA_MEMLIMIT_ERROR is returned. 665 * \param allocator Pointer to lzma_allocator, or NULL to use malloc() 666 * \param in Beginning of the input buffer 667 * \param in_pos The next byte will be read from in[*in_pos]. 668 * *in_pos is updated only if decoding succeeds. 669 * \param in_size Size of the input buffer; the first byte that 670 * won't be read is in[in_size]. 671 * 672 * \return - LZMA_OK: Decoding was successful. 673 * - LZMA_MEM_ERROR 674 * - LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. 675 * The minimum required memlimit value was stored to *memlimit. 676 * - LZMA_DATA_ERROR 677 * - LZMA_PROG_ERROR 678 */ 679extern LZMA_API(lzma_ret) lzma_index_buffer_decode(lzma_index **i, 680 uint64_t *memlimit, const lzma_allocator *allocator, 681 const uint8_t *in, size_t *in_pos, size_t in_size) 682 lzma_nothrow; 683