xz-utils (5.4.5)
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;
Browse
Usage
Versions