1 /* SPDX-License-Identifier: 0BSD */ 2 3 /** 4 * \file lzma/base.h 5 * \brief Data types and functions used in many places in liblzma API 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 Boolean 20 * 21 * This is here because C89 doesn't have stdbool.h. To set a value for 22 * variables having type lzma_bool, you can use 23 * - C99's 'true' and 'false' from stdbool.h; 24 * - C++'s internal 'true' and 'false'; or 25 * - integers one (true) and zero (false). 26 */ 27 typedef unsigned char lzma_bool; 28 29 30 /** 31 * \brief Type of reserved enumeration variable in structures 32 * 33 * To avoid breaking library ABI when new features are added, several 34 * structures contain extra variables that may be used in future. Since 35 * sizeof(enum) can be different than sizeof(int), and sizeof(enum) may 36 * even vary depending on the range of enumeration constants, we specify 37 * a separate type to be used for reserved enumeration variables. All 38 * enumeration constants in liblzma API will be non-negative and less 39 * than 128, which should guarantee that the ABI won't break even when 40 * new constants are added to existing enumerations. 41 */ 42 typedef enum { 43 LZMA_RESERVED_ENUM = 0 44 } lzma_reserved_enum; 45 46 47 /** 48 * \brief Return values used by several functions in liblzma 49 * 50 * Check the descriptions of specific functions to find out which return 51 * values they can return. With some functions the return values may have 52 * more specific meanings than described here; those differences are 53 * described per-function basis. 54 */ 55 typedef enum { 56 LZMA_OK = 0, 57 /**< 58 * \brief Operation completed successfully 59 */ 60 61 LZMA_STREAM_END = 1, 62 /**< 63 * \brief End of stream was reached 64 * 65 * In encoder, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or 66 * LZMA_FINISH was finished. In decoder, this indicates 67 * that all the data was successfully decoded. 68 * 69 * In all cases, when LZMA_STREAM_END is returned, the last 70 * output bytes should be picked from strm->next_out. 71 */ 72 73 LZMA_NO_CHECK = 2, 74 /**< 75 * \brief Input stream has no integrity check 76 * 77 * This return value can be returned only if the 78 * LZMA_TELL_NO_CHECK flag was used when initializing 79 * the decoder. LZMA_NO_CHECK is just a warning, and 80 * the decoding can be continued normally. 81 * 82 * It is possible to call lzma_get_check() immediately after 83 * lzma_code has returned LZMA_NO_CHECK. The result will 84 * naturally be LZMA_CHECK_NONE, but the possibility to call 85 * lzma_get_check() may be convenient in some applications. 86 */ 87 88 LZMA_UNSUPPORTED_CHECK = 3, 89 /**< 90 * \brief Cannot calculate the integrity check 91 * 92 * The usage of this return value is different in encoders 93 * and decoders. 94 * 95 * Encoders can return this value only from the initialization 96 * function. If initialization fails with this value, the 97 * encoding cannot be done, because there's no way to produce 98 * output with the correct integrity check. 99 * 100 * Decoders can return this value only from lzma_code() and 101 * only if the LZMA_TELL_UNSUPPORTED_CHECK flag was used when 102 * initializing the decoder. The decoding can still be 103 * continued normally even if the check type is unsupported, 104 * but naturally the check will not be validated, and possible 105 * errors may go undetected. 106 * 107 * With decoder, it is possible to call lzma_get_check() 108 * immediately after lzma_code() has returned 109 * LZMA_UNSUPPORTED_CHECK. This way it is possible to find 110 * out what the unsupported Check ID was. 111 */ 112 113 LZMA_GET_CHECK = 4, 114 /**< 115 * \brief Integrity check type is now available 116 * 117 * This value can be returned only by the lzma_code() function 118 * and only if the decoder was initialized with the 119 * LZMA_TELL_ANY_CHECK flag. LZMA_GET_CHECK tells the 120 * application that it may now call lzma_get_check() to find 121 * out the Check ID. This can be used, for example, to 122 * implement a decoder that accepts only files that have 123 * strong enough integrity check. 124 */ 125 126 LZMA_MEM_ERROR = 5, 127 /**< 128 * \brief Cannot allocate memory 129 * 130 * Memory allocation failed, or the size of the allocation 131 * would be greater than SIZE_MAX. 132 * 133 * Due to internal implementation reasons, the coding cannot 134 * be continued even if more memory were made available after 135 * LZMA_MEM_ERROR. 136 */ 137 138 LZMA_MEMLIMIT_ERROR = 6, 139 /**< 140 * \brief Memory usage limit was reached 141 * 142 * Decoder would need more memory than allowed by the 143 * specified memory usage limit. To continue decoding, 144 * the memory usage limit has to be increased with 145 * lzma_memlimit_set(). 146 * 147 * liblzma 5.2.6 and earlier had a bug in single-threaded .xz 148 * decoder (lzma_stream_decoder()) which made it impossible 149 * to continue decoding after LZMA_MEMLIMIT_ERROR even if 150 * the limit was increased using lzma_memlimit_set(). 151 * Other decoders worked correctly. 152 */ 153 154 LZMA_FORMAT_ERROR = 7, 155 /**< 156 * \brief File format not recognized 157 * 158 * The decoder did not recognize the input as supported file 159 * format. This error can occur, for example, when trying to 160 * decode .lzma format file with lzma_stream_decoder, 161 * because lzma_stream_decoder accepts only the .xz format. 162 */ 163 164 LZMA_OPTIONS_ERROR = 8, 165 /**< 166 * \brief Invalid or unsupported options 167 * 168 * Invalid or unsupported options, for example 169 * - unsupported filter(s) or filter options; or 170 * - reserved bits set in headers (decoder only). 171 * 172 * Rebuilding liblzma with more features enabled, or 173 * upgrading to a newer version of liblzma may help. 174 */ 175 176 LZMA_DATA_ERROR = 9, 177 /**< 178 * \brief Data is corrupt 179 * 180 * The usage of this return value is different in encoders 181 * and decoders. In both encoder and decoder, the coding 182 * cannot continue after this error. 183 * 184 * Encoders return this if size limits of the target file 185 * format would be exceeded. These limits are huge, thus 186 * getting this error from an encoder is mostly theoretical. 187 * For example, the maximum compressed and uncompressed 188 * size of a .xz Stream is roughly 8 EiB (2^63 bytes). 189 * 190 * Decoders return this error if the input data is corrupt. 191 * This can mean, for example, invalid CRC32 in headers 192 * or invalid check of uncompressed data. 193 */ 194 195 LZMA_BUF_ERROR = 10, 196 /**< 197 * \brief No progress is possible 198 * 199 * This error code is returned when the coder cannot consume 200 * any new input and produce any new output. The most common 201 * reason for this error is that the input stream being 202 * decoded is truncated or corrupt. 203 * 204 * This error is not fatal. Coding can be continued normally 205 * by providing more input and/or more output space, if 206 * possible. 207 * 208 * Typically the first call to lzma_code() that can do no 209 * progress returns LZMA_OK instead of LZMA_BUF_ERROR. Only 210 * the second consecutive call doing no progress will return 211 * LZMA_BUF_ERROR. This is intentional. 212 * 213 * With zlib, Z_BUF_ERROR may be returned even if the 214 * application is doing nothing wrong, so apps will need 215 * to handle Z_BUF_ERROR specially. The above hack 216 * guarantees that liblzma never returns LZMA_BUF_ERROR 217 * to properly written applications unless the input file 218 * is truncated or corrupt. This should simplify the 219 * applications a little. 220 */ 221 222 LZMA_PROG_ERROR = 11, 223 /**< 224 * \brief Programming error 225 * 226 * This indicates that the arguments given to the function are 227 * invalid or the internal state of the decoder is corrupt. 228 * - Function arguments are invalid or the structures 229 * pointed by the argument pointers are invalid 230 * e.g. if strm->next_out has been set to NULL and 231 * strm->avail_out > 0 when calling lzma_code(). 232 * - lzma_* functions have been called in wrong order 233 * e.g. lzma_code() was called right after lzma_end(). 234 * - If errors occur randomly, the reason might be flaky 235 * hardware. 236 * 237 * If you think that your code is correct, this error code 238 * can be a sign of a bug in liblzma. See the documentation 239 * how to report bugs. 240 */ 241 242 LZMA_SEEK_NEEDED = 12, 243 /**< 244 * \brief Request to change the input file position 245 * 246 * Some coders can do random access in the input file. The 247 * initialization functions of these coders take the file size 248 * as an argument. No other coders can return LZMA_SEEK_NEEDED. 249 * 250 * When this value is returned, the application must seek to 251 * the file position given in lzma_stream.seek_pos. This value 252 * is guaranteed to never exceed the file size that was 253 * specified at the coder initialization. 254 * 255 * After seeking the application should read new input and 256 * pass it normally via lzma_stream.next_in and .avail_in. 257 */ 258 259 /* 260 * These enumerations may be used internally by liblzma 261 * but they will never be returned to applications. 262 */ 263 LZMA_RET_INTERNAL1 = 101, 264 LZMA_RET_INTERNAL2 = 102, 265 LZMA_RET_INTERNAL3 = 103, 266 LZMA_RET_INTERNAL4 = 104, 267 LZMA_RET_INTERNAL5 = 105, 268 LZMA_RET_INTERNAL6 = 106, 269 LZMA_RET_INTERNAL7 = 107, 270 LZMA_RET_INTERNAL8 = 108 271 } lzma_ret; 272 273 274 /** 275 * \brief The 'action' argument for lzma_code() 276 * 277 * After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, LZMA_FULL_BARRIER, 278 * or LZMA_FINISH, the same 'action' must be used until lzma_code() returns 279 * LZMA_STREAM_END. Also, the amount of input (that is, strm->avail_in) must 280 * not be modified by the application until lzma_code() returns 281 * LZMA_STREAM_END. Changing the 'action' or modifying the amount of input 282 * will make lzma_code() return LZMA_PROG_ERROR. 283 */ 284 typedef enum { 285 LZMA_RUN = 0, 286 /**< 287 * \brief Continue coding 288 * 289 * Encoder: Encode as much input as possible. Some internal 290 * buffering will probably be done (depends on the filter 291 * chain in use), which causes latency: the input used won't 292 * usually be decodeable from the output of the same 293 * lzma_code() call. 294 * 295 * Decoder: Decode as much input as possible and produce as 296 * much output as possible. 297 */ 298 299 LZMA_SYNC_FLUSH = 1, 300 /**< 301 * \brief Make all the input available at output 302 * 303 * Normally the encoder introduces some latency. 304 * LZMA_SYNC_FLUSH forces all the buffered data to be 305 * available at output without resetting the internal 306 * state of the encoder. This way it is possible to use 307 * compressed stream for example for communication over 308 * network. 309 * 310 * Only some filters support LZMA_SYNC_FLUSH. Trying to use 311 * LZMA_SYNC_FLUSH with filters that don't support it will 312 * make lzma_code() return LZMA_OPTIONS_ERROR. For example, 313 * LZMA1 doesn't support LZMA_SYNC_FLUSH but LZMA2 does. 314 * 315 * Using LZMA_SYNC_FLUSH very often can dramatically reduce 316 * the compression ratio. With some filters (for example, 317 * LZMA2), fine-tuning the compression options may help 318 * mitigate this problem significantly (for example, 319 * match finder with LZMA2). 320 * 321 * Decoders don't support LZMA_SYNC_FLUSH. 322 */ 323 324 LZMA_FULL_FLUSH = 2, 325 /**< 326 * \brief Finish encoding of the current Block 327 * 328 * All the input data going to the current Block must have 329 * been given to the encoder (the last bytes can still be 330 * pending in *next_in). Call lzma_code() with LZMA_FULL_FLUSH 331 * until it returns LZMA_STREAM_END. Then continue normally 332 * with LZMA_RUN or finish the Stream with LZMA_FINISH. 333 * 334 * This action is currently supported only by Stream encoder 335 * and easy encoder (which uses Stream encoder). If there is 336 * no unfinished Block, no empty Block is created. 337 */ 338 339 LZMA_FULL_BARRIER = 4, 340 /**< 341 * \brief Finish encoding of the current Block 342 * 343 * This is like LZMA_FULL_FLUSH except that this doesn't 344 * necessarily wait until all the input has been made 345 * available via the output buffer. That is, lzma_code() 346 * might return LZMA_STREAM_END as soon as all the input 347 * has been consumed (avail_in == 0). 348 * 349 * LZMA_FULL_BARRIER is useful with a threaded encoder if 350 * one wants to split the .xz Stream into Blocks at specific 351 * offsets but doesn't care if the output isn't flushed 352 * immediately. Using LZMA_FULL_BARRIER allows keeping 353 * the threads busy while LZMA_FULL_FLUSH would make 354 * lzma_code() wait until all the threads have finished 355 * until more data could be passed to the encoder. 356 * 357 * With a lzma_stream initialized with the single-threaded 358 * lzma_stream_encoder() or lzma_easy_encoder(), 359 * LZMA_FULL_BARRIER is an alias for LZMA_FULL_FLUSH. 360 */ 361 362 LZMA_FINISH = 3 363 /**< 364 * \brief Finish the coding operation 365 * 366 * All the input data must have been given to the encoder 367 * (the last bytes can still be pending in next_in). 368 * Call lzma_code() with LZMA_FINISH until it returns 369 * LZMA_STREAM_END. Once LZMA_FINISH has been used, 370 * the amount of input must no longer be changed by 371 * the application. 372 * 373 * When decoding, using LZMA_FINISH is optional unless the 374 * LZMA_CONCATENATED flag was used when the decoder was 375 * initialized. When LZMA_CONCATENATED was not used, the only 376 * effect of LZMA_FINISH is that the amount of input must not 377 * be changed just like in the encoder. 378 */ 379 } lzma_action; 380 381 382 /** 383 * \brief Custom functions for memory handling 384 * 385 * A pointer to lzma_allocator may be passed via lzma_stream structure 386 * to liblzma, and some advanced functions take a pointer to lzma_allocator 387 * as a separate function argument. The library will use the functions 388 * specified in lzma_allocator for memory handling instead of the default 389 * malloc() and free(). C++ users should note that the custom memory 390 * handling functions must not throw exceptions. 391 * 392 * Single-threaded mode only: liblzma doesn't make an internal copy of 393 * lzma_allocator. Thus, it is OK to change these function pointers in 394 * the middle of the coding process, but obviously it must be done 395 * carefully to make sure that the replacement 'free' can deallocate 396 * memory allocated by the earlier 'alloc' function(s). 397 * 398 * Multithreaded mode: liblzma might internally store pointers to the 399 * lzma_allocator given via the lzma_stream structure. The application 400 * must not change the allocator pointer in lzma_stream or the contents 401 * of the pointed lzma_allocator structure until lzma_end() has been used 402 * to free the memory associated with that lzma_stream. The allocation 403 * functions might be called simultaneously from multiple threads, and 404 * thus they must be thread safe. 405 */ 406 typedef struct { 407 /** 408 * \brief Pointer to a custom memory allocation function 409 * 410 * If you don't want a custom allocator, but still want 411 * custom free(), set this to NULL and liblzma will use 412 * the standard malloc(). 413 * 414 * \param opaque lzma_allocator.opaque (see below) 415 * \param nmemb Number of elements like in calloc(). liblzma 416 * will always set nmemb to 1, so it is safe to 417 * ignore nmemb in a custom allocator if you like. 418 * The nmemb argument exists only for 419 * compatibility with zlib and libbzip2. 420 * \param size Size of an element in bytes. 421 * liblzma never sets this to zero. 422 * 423 * \return Pointer to the beginning of a memory block of 424 * 'size' bytes, or NULL if allocation fails 425 * for some reason. When allocation fails, functions 426 * of liblzma return LZMA_MEM_ERROR. 427 * 428 * The allocator should not waste time zeroing the allocated buffers. 429 * This is not only about speed, but also memory usage, since the 430 * operating system kernel doesn't necessarily allocate the requested 431 * memory in physical memory until it is actually used. With small 432 * input files, liblzma may actually need only a fraction of the 433 * memory that it requested for allocation. 434 * 435 * \note LZMA_MEM_ERROR is also used when the size of the 436 * allocation would be greater than SIZE_MAX. Thus, 437 * don't assume that the custom allocator must have 438 * returned NULL if some function from liblzma 439 * returns LZMA_MEM_ERROR. 440 */ 441 void *(LZMA_API_CALL *alloc)(void *opaque, size_t nmemb, size_t size); 442 443 /** 444 * \brief Pointer to a custom memory freeing function 445 * 446 * If you don't want a custom freeing function, but still 447 * want a custom allocator, set this to NULL and liblzma 448 * will use the standard free(). 449 * 450 * \param opaque lzma_allocator.opaque (see below) 451 * \param ptr Pointer returned by lzma_allocator.alloc(), 452 * or when it is set to NULL, a pointer returned 453 * by the standard malloc(). 454 */ 455 void (LZMA_API_CALL *free)(void *opaque, void *ptr); 456 457 /** 458 * \brief Pointer passed to .alloc() and .free() 459 * 460 * opaque is passed as the first argument to lzma_allocator.alloc() 461 * and lzma_allocator.free(). This intended to ease implementing 462 * custom memory allocation functions for use with liblzma. 463 * 464 * If you don't need this, you should set this to NULL. 465 */ 466 void *opaque; 467 468 } lzma_allocator; 469 470 471 /** 472 * \brief Internal data structure 473 * 474 * The contents of this structure is not visible outside the library. 475 */ 476 typedef struct lzma_internal_s lzma_internal; 477 478 479 /** 480 * \brief Passing data to and from liblzma 481 * 482 * The lzma_stream structure is used for 483 * - passing pointers to input and output buffers to liblzma; 484 * - defining custom memory handler functions; and 485 * - holding a pointer to coder-specific internal data structures. 486 * 487 * Typical usage: 488 * 489 * - After allocating lzma_stream (on stack or with malloc()), it must be 490 * initialized to LZMA_STREAM_INIT (see LZMA_STREAM_INIT for details). 491 * 492 * - Initialize a coder to the lzma_stream, for example by using 493 * lzma_easy_encoder() or lzma_auto_decoder(). Some notes: 494 * - In contrast to zlib, strm->next_in and strm->next_out are 495 * ignored by all initialization functions, thus it is safe 496 * to not initialize them yet. 497 * - The initialization functions always set strm->total_in and 498 * strm->total_out to zero. 499 * - If the initialization function fails, no memory is left allocated 500 * that would require freeing with lzma_end() even if some memory was 501 * associated with the lzma_stream structure when the initialization 502 * function was called. 503 * 504 * - Use lzma_code() to do the actual work. 505 * 506 * - Once the coding has been finished, the existing lzma_stream can be 507 * reused. It is OK to reuse lzma_stream with different initialization 508 * function without calling lzma_end() first. Old allocations are 509 * automatically freed. 510 * 511 * - Finally, use lzma_end() to free the allocated memory. lzma_end() never 512 * frees the lzma_stream structure itself. 513 * 514 * Application may modify the values of total_in and total_out as it wants. 515 * They are updated by liblzma to match the amount of data read and 516 * written but aren't used for anything else except as a possible return 517 * values from lzma_get_progress(). 518 */ 519 typedef struct { 520 const uint8_t *next_in; /**< Pointer to the next input byte. */ 521 size_t avail_in; /**< Number of available input bytes in next_in. */ 522 uint64_t total_in; /**< Total number of bytes read by liblzma. */ 523 524 uint8_t *next_out; /**< Pointer to the next output position. */ 525 size_t avail_out; /**< Amount of free space in next_out. */ 526 uint64_t total_out; /**< Total number of bytes written by liblzma. */ 527 528 /** 529 * \brief Custom memory allocation functions 530 * 531 * In most cases this is NULL which makes liblzma use 532 * the standard malloc() and free(). 533 * 534 * \note In 5.0.x this is not a const pointer. 535 */ 536 const lzma_allocator *allocator; 537 538 /** Internal state is not visible to applications. */ 539 lzma_internal *internal; 540 541 /* 542 * Reserved space to allow possible future extensions without 543 * breaking the ABI. Excluding the initialization of this structure, 544 * you should not touch these, because the names of these variables 545 * may change. 546 */ 547 548 /** \private Reserved member. */ 549 void *reserved_ptr1; 550 551 /** \private Reserved member. */ 552 void *reserved_ptr2; 553 554 /** \private Reserved member. */ 555 void *reserved_ptr3; 556 557 /** \private Reserved member. */ 558 void *reserved_ptr4; 559 560 /** 561 * \brief New seek input position for LZMA_SEEK_NEEDED 562 * 563 * When lzma_code() returns LZMA_SEEK_NEEDED, the new input position 564 * needed by liblzma will be available seek_pos. The value is 565 * guaranteed to not exceed the file size that was specified when 566 * this lzma_stream was initialized. 567 * 568 * In all other situations the value of this variable is undefined. 569 */ 570 uint64_t seek_pos; 571 572 /** \private Reserved member. */ 573 uint64_t reserved_int2; 574 575 /** \private Reserved member. */ 576 size_t reserved_int3; 577 578 /** \private Reserved member. */ 579 size_t reserved_int4; 580 581 /** \private Reserved member. */ 582 lzma_reserved_enum reserved_enum1; 583 584 /** \private Reserved member. */ 585 lzma_reserved_enum reserved_enum2; 586 587 } lzma_stream; 588 589 590 /** 591 * \brief Initialization for lzma_stream 592 * 593 * When you declare an instance of lzma_stream, you can immediately 594 * initialize it so that initialization functions know that no memory 595 * has been allocated yet: 596 * 597 * lzma_stream strm = LZMA_STREAM_INIT; 598 * 599 * If you need to initialize a dynamically allocated lzma_stream, you can use 600 * memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this 601 * violates the C standard since NULL may have different internal 602 * representation than zero, but it should be portable enough in practice. 603 * Anyway, for maximum portability, you can use something like this: 604 * 605 * lzma_stream tmp = LZMA_STREAM_INIT; 606 * *strm = tmp; 607 */ 608 #define LZMA_STREAM_INIT \ 609 { NULL, 0, 0, NULL, 0, 0, NULL, NULL, \ 610 NULL, NULL, NULL, NULL, 0, 0, 0, 0, \ 611 LZMA_RESERVED_ENUM, LZMA_RESERVED_ENUM } 612 613 614 /** 615 * \brief Encode or decode data 616 * 617 * Once the lzma_stream has been successfully initialized (e.g. with 618 * lzma_stream_encoder()), the actual encoding or decoding is done 619 * using this function. The application has to update strm->next_in, 620 * strm->avail_in, strm->next_out, and strm->avail_out to pass input 621 * to and get output from liblzma. 622 * 623 * See the description of the coder-specific initialization function to find 624 * out what 'action' values are supported by the coder. 625 * 626 * \param strm Pointer to lzma_stream that is at least initialized 627 * with LZMA_STREAM_INIT. 628 * \param action Action for this function to take. Must be a valid 629 * lzma_action enum value. 630 * 631 * \return Any valid lzma_ret. See the lzma_ret enum description for more 632 * information. 633 */ 634 extern LZMA_API(lzma_ret) lzma_code(lzma_stream *strm, lzma_action action) 635 lzma_nothrow lzma_attr_warn_unused_result; 636 637 638 /** 639 * \brief Free memory allocated for the coder data structures 640 * 641 * After lzma_end(strm), strm->internal is guaranteed to be NULL. No other 642 * members of the lzma_stream structure are touched. 643 * 644 * \note zlib indicates an error if application end()s unfinished 645 * stream structure. liblzma doesn't do this, and assumes that 646 * application knows what it is doing. 647 * 648 * \param strm Pointer to lzma_stream that is at least initialized 649 * with LZMA_STREAM_INIT. 650 */ 651 extern LZMA_API(void) lzma_end(lzma_stream *strm) lzma_nothrow; 652 653 654 /** 655 * \brief Get progress information 656 * 657 * In single-threaded mode, applications can get progress information from 658 * strm->total_in and strm->total_out. In multi-threaded mode this is less 659 * useful because a significant amount of both input and output data gets 660 * buffered internally by liblzma. This makes total_in and total_out give 661 * misleading information and also makes the progress indicator updates 662 * non-smooth. 663 * 664 * This function gives realistic progress information also in multi-threaded 665 * mode by taking into account the progress made by each thread. In 666 * single-threaded mode *progress_in and *progress_out are set to 667 * strm->total_in and strm->total_out, respectively. 668 * 669 * \param strm Pointer to lzma_stream that is at least 670 * initialized with LZMA_STREAM_INIT. 671 * \param[out] progress_in Pointer to the number of input bytes processed. 672 * \param[out] progress_out Pointer to the number of output bytes processed. 673 */ 674 extern LZMA_API(void) lzma_get_progress(lzma_stream *strm, 675 uint64_t *progress_in, uint64_t *progress_out) lzma_nothrow; 676 677 678 /** 679 * \brief Get the memory usage of decoder filter chain 680 * 681 * This function is currently supported only when *strm has been initialized 682 * with a function that takes a memlimit argument. With other functions, you 683 * should use e.g. lzma_raw_encoder_memusage() or lzma_raw_decoder_memusage() 684 * to estimate the memory requirements. 685 * 686 * This function is useful e.g. after LZMA_MEMLIMIT_ERROR to find out how big 687 * the memory usage limit should have been to decode the input. Note that 688 * this may give misleading information if decoding .xz Streams that have 689 * multiple Blocks, because each Block can have different memory requirements. 690 * 691 * \param strm Pointer to lzma_stream that is at least initialized 692 * with LZMA_STREAM_INIT. 693 * 694 * \return How much memory is currently allocated for the filter 695 * decoders. If no filter chain is currently allocated, 696 * some non-zero value is still returned, which is less than 697 * or equal to what any filter chain would indicate as its 698 * memory requirement. 699 * 700 * If this function isn't supported by *strm or some other error 701 * occurs, zero is returned. 702 */ 703 extern LZMA_API(uint64_t) lzma_memusage(const lzma_stream *strm) 704 lzma_nothrow lzma_attr_pure; 705 706 707 /** 708 * \brief Get the current memory usage limit 709 * 710 * This function is supported only when *strm has been initialized with 711 * a function that takes a memlimit argument. 712 * 713 * \param strm Pointer to lzma_stream that is at least initialized 714 * with LZMA_STREAM_INIT. 715 * 716 * \return On success, the current memory usage limit is returned 717 * (always non-zero). On error, zero is returned. 718 */ 719 extern LZMA_API(uint64_t) lzma_memlimit_get(const lzma_stream *strm) 720 lzma_nothrow lzma_attr_pure; 721 722 723 /** 724 * \brief Set the memory usage limit 725 * 726 * This function is supported only when *strm has been initialized with 727 * a function that takes a memlimit argument. 728 * 729 * liblzma 5.2.3 and earlier has a bug where memlimit value of 0 causes 730 * this function to do nothing (leaving the limit unchanged) and still 731 * return LZMA_OK. Later versions treat 0 as if 1 had been specified (so 732 * lzma_memlimit_get() will return 1 even if you specify 0 here). 733 * 734 * liblzma 5.2.6 and earlier had a bug in single-threaded .xz decoder 735 * (lzma_stream_decoder()) which made it impossible to continue decoding 736 * after LZMA_MEMLIMIT_ERROR even if the limit was increased using 737 * lzma_memlimit_set(). Other decoders worked correctly. 738 * 739 * \return Possible lzma_ret values: 740 * - LZMA_OK: New memory usage limit successfully set. 741 * - LZMA_MEMLIMIT_ERROR: The new limit is too small. 742 * The limit was not changed. 743 * - LZMA_PROG_ERROR: Invalid arguments, e.g. *strm doesn't 744 * support memory usage limit. 745 */ 746 extern LZMA_API(lzma_ret) lzma_memlimit_set( 747 lzma_stream *strm, uint64_t memlimit) lzma_nothrow; 748