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