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 */
27typedef 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 */
42typedef 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 */
55typedef 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 */
284typedef 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 */
406typedef 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(). In addition, NULL
454 * is a possible value. The function should do
455 * nothing when ptr == NULL.
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 */
478typedef 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 */
521typedef 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
550 /** \private Reserved member. */
551 void *reserved_ptr1;
552
553 /** \private Reserved member. */
554 void *reserved_ptr2;
555
556 /** \private Reserved member. */
557 void *reserved_ptr3;
558
559 /** \private Reserved member. */
560 void *reserved_ptr4;
561
562 /**
563 * \brief New seek input position for LZMA_SEEK_NEEDED
564 *
565 * When lzma_code() returns LZMA_SEEK_NEEDED, the new input position
566 * needed by liblzma will be available in seek_pos. The value is
567 * guaranteed to not exceed the file size that was specified when
568 * this lzma_stream was initialized.
569 *
570 * In all other situations the value of this variable is undefined.
571 */
572 uint64_t seek_pos;
573
574 /** \private Reserved member. */
575 uint64_t reserved_int2;
576
577 /** \private Reserved member. */
578 size_t reserved_int3;
579
580 /** \private Reserved member. */
581 size_t reserved_int4;
582
583 /** \private Reserved member. */
584 lzma_reserved_enum reserved_enum1;
585
586 /** \private Reserved member. */
587 lzma_reserved_enum reserved_enum2;
588
589} lzma_stream;
590
591
592/**
593 * \brief Initialization for lzma_stream
594 *
595 * When you declare an instance of lzma_stream, you can immediately
596 * initialize it so that initialization functions know that no memory
597 * has been allocated yet:
598 *
599 * lzma_stream strm = LZMA_STREAM_INIT;
600 *
601 * If you need to initialize a dynamically allocated lzma_stream, you can use
602 * memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this
603 * violates the C standard since NULL may have different internal
604 * representation than zero, but it should be portable enough in practice.
605 * Anyway, for maximum portability, you can use something like this:
606 *
607 * lzma_stream tmp = LZMA_STREAM_INIT;
608 * *strm = tmp;
609 */
610#define LZMA_STREAM_INIT \
611 { NULL, 0, 0, NULL, 0, 0, NULL, NULL, \
612 NULL, NULL, NULL, NULL, 0, 0, 0, 0, \
613 LZMA_RESERVED_ENUM, LZMA_RESERVED_ENUM }
614
615
616/**
617 * \brief Encode or decode data
618 *
619 * Once the lzma_stream has been successfully initialized (e.g. with
620 * lzma_stream_encoder()), the actual encoding or decoding is done
621 * using this function. The application has to update strm->next_in,
622 * strm->avail_in, strm->next_out, and strm->avail_out to pass input
623 * to and get output from liblzma.
624 *
625 * See the description of the coder-specific initialization function to find
626 * out what 'action' values are supported by the coder.
627 *
628 * \param strm Pointer to lzma_stream that is at least initialized
629 * with LZMA_STREAM_INIT.
630 * \param action Action for this function to take. Must be a valid
631 * lzma_action enum value.
632 *
633 * \return Any valid lzma_ret. See the lzma_ret enum description for more
634 * information.
635 */
636extern LZMA_API(lzma_ret) lzma_code(lzma_stream *strm, lzma_action action)
637 lzma_nothrow lzma_attr_warn_unused_result;
638
639
640/**
641 * \brief Free memory allocated for the coder data structures
642 *
643 * After lzma_end(strm), strm->internal is guaranteed to be NULL. No other
644 * members of the lzma_stream structure are touched.
645 *
646 * \note zlib indicates an error if application end()s unfinished
647 * stream structure. liblzma doesn't do this, and assumes that
648 * application knows what it is doing.
649 *
650 * \param strm Pointer to lzma_stream that is at least initialized
651 * with LZMA_STREAM_INIT.
652 */
653extern LZMA_API(void) lzma_end(lzma_stream *strm) lzma_nothrow;
654
655
656/**
657 * \brief Get progress information
658 *
659 * In single-threaded mode, applications can get progress information from
660 * strm->total_in and strm->total_out. In multi-threaded mode this is less
661 * useful because a significant amount of both input and output data gets
662 * buffered internally by liblzma. This makes total_in and total_out give
663 * misleading information and also makes the progress indicator updates
664 * non-smooth.
665 *
666 * This function gives realistic progress information also in multi-threaded
667 * mode by taking into account the progress made by each thread. In
668 * single-threaded mode *progress_in and *progress_out are set to
669 * strm->total_in and strm->total_out, respectively.
670 *
671 * \param strm Pointer to lzma_stream that is at least
672 * initialized with LZMA_STREAM_INIT.
673 * \param[out] progress_in Pointer to the number of input bytes processed.
674 * \param[out] progress_out Pointer to the number of output bytes processed.
675 */
676extern LZMA_API(void) lzma_get_progress(lzma_stream *strm,
677 uint64_t *progress_in, uint64_t *progress_out) lzma_nothrow;
678
679
680/**
681 * \brief Get the memory usage of decoder filter chain
682 *
683 * This function is currently supported only when *strm has been initialized
684 * with a function that takes a memlimit argument. With other functions, you
685 * should use e.g. lzma_raw_encoder_memusage() or lzma_raw_decoder_memusage()
686 * to estimate the memory requirements.
687 *
688 * This function is useful e.g. after LZMA_MEMLIMIT_ERROR to find out how big
689 * the memory usage limit should have been to decode the input. Note that
690 * this may give misleading information if decoding .xz Streams that have
691 * multiple Blocks, because each Block can have different memory requirements.
692 *
693 * \param strm Pointer to lzma_stream that is at least initialized
694 * with LZMA_STREAM_INIT.
695 *
696 * \return How much memory is currently allocated for the filter
697 * decoders. If no filter chain is currently allocated,
698 * some non-zero value is still returned, which is less than
699 * or equal to what any filter chain would indicate as its
700 * memory requirement.
701 *
702 * If this function isn't supported by *strm or some other error
703 * occurs, zero is returned.
704 */
705extern LZMA_API(uint64_t) lzma_memusage(const lzma_stream *strm)
706 lzma_nothrow lzma_attr_pure;
707
708
709/**
710 * \brief Get the current memory usage limit
711 *
712 * This function is supported only when *strm has been initialized with
713 * a function that takes a memlimit argument.
714 *
715 * \param strm Pointer to lzma_stream that is at least initialized
716 * with LZMA_STREAM_INIT.
717 *
718 * \return On success, the current memory usage limit is returned
719 * (always non-zero). On error, zero is returned.
720 */
721extern LZMA_API(uint64_t) lzma_memlimit_get(const lzma_stream *strm)
722 lzma_nothrow lzma_attr_pure;
723
724
725/**
726 * \brief Set the memory usage limit
727 *
728 * This function is supported only when *strm has been initialized with
729 * a function that takes a memlimit argument.
730 *
731 * liblzma 5.2.3 and earlier has a bug where memlimit value of 0 causes
732 * this function to do nothing (leaving the limit unchanged) and still
733 * return LZMA_OK. Later versions treat 0 as if 1 had been specified (so
734 * lzma_memlimit_get() will return 1 even if you specify 0 here).
735 *
736 * liblzma 5.2.6 and earlier had a bug in single-threaded .xz decoder
737 * (lzma_stream_decoder()) which made it impossible to continue decoding
738 * after LZMA_MEMLIMIT_ERROR even if the limit was increased using
739 * lzma_memlimit_set(). Other decoders worked correctly.
740 *
741 * \return Possible lzma_ret values:
742 * - LZMA_OK: New memory usage limit successfully set.
743 * - LZMA_MEMLIMIT_ERROR: The new limit is too small.
744 * The limit was not changed.
745 * - LZMA_PROG_ERROR: Invalid arguments, e.g. *strm doesn't
746 * support memory usage limit.
747 */
748extern LZMA_API(lzma_ret) lzma_memlimit_set(
749 lzma_stream *strm, uint64_t memlimit) lzma_nothrow;
750