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