3 * \brief Data types and functions used in many places of the public API
5 * \author Copyright (C) 1999-2006 Igor Pavlov
6 * \author Copyright (C) 2007 Lasse Collin
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
19 #ifndef LZMA_H_INTERNAL
20 # error Never include this file directly. Use <lzma.h> instead.
27 * This is here because C89 doesn't have stdbool.h. To set a value for
28 * variables having type lzma_bool, you can use
29 * - C99's `true' and `false' from stdbool.h;
30 * - C++'s internal `true' and `false'; or
31 * - integers one (true) and zero (false).
33 typedef unsigned char lzma_bool;
37 * \brief Type of reserved enumeration variable in structures
39 * To avoid breaking library ABI when new features are added, several
40 * structures contain extra variables that may be used in future. Since
41 * sizeof(enum) can be different than sizeof(int), and sizeof(enum) may
42 * even vary depending on the range of enumeration constants, we specify
43 * a separate type to be used for reserved enumeration variables. All
44 * enumeration constants in liblzma API will be non-negative and less
45 * than 128, which should guarantee that the ABI won't break even when
46 * new constants are added to existing enumerations.
49 LZMA_RESERVED_ENUM = 0
54 * \brief Return values used by several functions in liblzma
56 * Check the descriptions of specific functions to find out which return
57 * values they can return. With some functions the return values may have
58 * more specific meanings than described here; those differences are
59 * described per-function basis.
64 * \brief Operation completed successfully
69 * \brief End of stream was reached
71 * In encoder, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or
72 * LZMA_FINISH was finished. In decoder, this indicates
73 * that all the data was successfully decoded.
75 * In all cases, when LZMA_STREAM_END is returned, the last
76 * output bytes should be picked from strm->next_out.
81 * \brief Input stream has no integrity check
83 * This return value can be returned only if the
84 * LZMA_TELL_NO_CHECK flag was used when initializing
85 * the decoder. LZMA_NO_CHECK is just a warning, and
86 * the decoding can be continued normally.
88 * It is possible to call lzma_get_check() immediatelly after
89 * lzma_code has returned LZMA_NO_CHECK. The result will
90 * naturally be LZMA_CHECK_NONE, but the possibility to call
91 * lzma_get_check() may be convenient in some applications.
94 LZMA_UNSUPPORTED_CHECK = 3,
96 * \brief Cannot calculate the integrity check
98 * The usage of this return value is slightly different in
99 * encoders and decoders.
101 * Encoders can return this value only from the initialization
102 * function. If initialization fails with this value, the
103 * encoding cannot be done, because there's no way to produce
104 * output with the correct integrity check.
106 * Decoders can return this value only from the lzma_code
107 * function and only if the LZMA_TELL_UNSUPPORTED_CHECK flag
108 * was used when initializing the decoder. The decoding can
109 * still be continued normally even if the check type is
110 * unsupported, but naturally the check will not be validated,
111 * and possible errors may go undetected.
113 * With decoder, it is possible to call lzma_get_check()
114 * immediatelly after lzma_code has returned
115 * LZMA_UNSUPPORTED_CHECK. This way it is possible to find
116 * out what the unsupported Check ID was.
121 * \brief Integrity check type is now available
123 * This value can be returned only by the lzma_code() function
124 * and only if the decoder was initialized with the
125 * LZMA_TELL_ANY_CHECK flag. LZMA_GET_CHECK tells the
126 * application that it may now call lzma_get_check() to find
127 * out the Check ID. This can be used, for example, to
128 * implement a decoder that accepts only files that have
129 * strong enough integrity check.
134 * \brief Cannot allocate memory
136 * Memory allocation failed, or the size of the allocation
137 * would be greater than SIZE_MAX.
139 * Due to lazy coding, the coding cannot be continued even
140 * if more memory were made available after LZMA_MEM_ERROR.
143 LZMA_MEMLIMIT_ERROR = 6,
145 * \brief Memory usage limit was reached
147 * Decoder would need more memory than allowed by the
148 * specified memory usage limit. To continue decoding,
149 * the memory usage limit has to be increased. See functions
150 * lzma_memlimit_get() and lzma_memlimit_set().
153 LZMA_FORMAT_ERROR = 7,
155 * \brief Unknown file format
157 * The decoder did not recognize the input as supported file
158 * format. This error can occur, for example, when trying to
159 * decode LZMA_Alone format file with lzma_stream_decoder,
160 * because lzma_stream_decoder accepts only the new .lzma
164 LZMA_OPTIONS_ERROR = 8,
166 * \brief Invalid or unsupported options
168 * Invalid or unsupported options, for example
169 * - unsupported filter(s) or filter options; or
170 * - reserved bits set in headers (decoder only).
172 * Rebuilding liblzma with more features enabled, or
173 * upgrading to a newer version of liblzma may help.
178 * \brief Data is corrupt
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.
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 Stream created with lzma_stream_encoder is
189 * 2^63 - 1 bytes (one byte less than 8 EiB).
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.
198 * \brief No progress is possible
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.
205 * This error is not fatal. Coding can be continued normally
206 * by providing more input and/or more output space, if
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 by design.
214 * With zlib, Z_BUF_ERROR may be returned even if the
215 * application is doing nothing wrong. 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.
222 LZMA_PROG_ERROR = 11,
224 * \brief Programming error
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
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.
245 * \brief The `action' argument for lzma_code()
247 * After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or LZMA_FINISH,
248 * the same `action' must is used until lzma_code() returns LZMA_STREAM_END.
249 * Also, the amount of input (that is, strm->avail_in) must not be modified
250 * by the application until lzma_code() returns LZMA_STREAM_END. Changing the
251 * `action' or modifying the amount of input will make lzma_code() return
257 * \brief Continue coding
259 * Encoder: Encode as much input as possible. Some internal
260 * buffering will probably be done (depends on the filter
261 * chain in use), which causes latency: the input used won't
262 * usually be decodeable from the output of the same
265 * Decoder: Decode as much input as possible and produce as
266 * much output as possible. This action provides best
267 * throughput, but may introduce latency, because the
268 * decoder may decode more data into its internal buffers
269 * than that fits into next_out.
274 * \brief Make all the input available at output
276 * Normally the encoder introduces some latency.
277 * LZMA_SYNC_FLUSH forces all the buffered data to be
278 * available at output without resetting the internal
279 * state of the encoder. This way it is possible to use
280 * compressed stream for example for communication over
283 * Only some filters support LZMA_SYNC_FLUSH. Trying to use
284 * LZMA_SYNC_FLUSH with filters that don't support it will
285 * make lzma_code() return LZMA_OPTIONS_ERROR. For example,
286 * LZMA1 doesn't support LZMA_SYNC_FLUSH but LZMA2 does.
288 * Using LZMA_SYNC_FLUSH very often can dramatically reduce
289 * the compression ratio. With some filters (for example,
290 * LZMA2), finetuning the compression options may help
291 * mitigate this problem significantly.
293 * Decoders don't support LZMA_SYNC_FLUSH.
298 * \brief Make all the input available at output
300 * This is like LZMA_SYNC_FLUSH except that this resets the
301 * internal encoder state.
305 * Finishes encoding of the current Data Block. All the input
306 * data going to the current Data Block must have been given
307 * to the encoder (the last bytes can still be pending in
308 * next_in). Call lzma_code() with LZMA_FULL_FLUSH until
309 * it returns LZMA_STREAM_END. Then continue normally with
310 * LZMA_RUN or finish the Stream with LZMA_FINISH.
312 * This action is supported only by Stream encoder and easy
313 * encoder (which uses Stream encoder). If there is no
314 * unfinished Block, no empty Block is created.
319 * \brief Finish the coding operation
324 * Finishes the coding operation. All the input data must
325 * have been given to the encoder (the last bytes can still
326 * be pending in next_in). Call lzma_code() with LZMA_FINISH
327 * until it returns LZMA_STREAM_END. Once LZMA_FINISH has
328 * been used, the amount of input must no longer be changed
329 * by the application.
331 * When decoding, using LZMA_FINISH is optional unless the
332 * LZMA_CONCATENATED flag was used when the decoder was
333 * initialized. When LZMA_CONCATENATED was not used, the only
334 * effect of LZMA_FINISH is that the amount of input must not
335 * be changed just like in the encoder.
341 * \brief Custom functions for memory handling
343 * A pointer to lzma_allocator may be passed via lzma_stream structure
344 * to liblzma, and some advanced function take pointer lzma_allocator as
345 * a separate function argument. The library will use the functions
346 * specified in lzma_allocator for memory handling instead of the default
347 * malloc() and free().
349 * liblzma doesn't make an internal copy of lzma_allocator. Thus, it is
350 * OK to change these function pointers in the middle of the coding
351 * process, but obviously it must be done carefully to make sure that the
352 * replacement `free' can deallocate memory allocated by the earlier
353 * `alloc' function(s).
357 * \brief Pointer to custom memory allocation function
359 * If you don't want a custom allocator, but still want
360 * custom free(), set this to NULL and liblzma will use
361 * the standard malloc().
363 * \param opaque lzma_allocator.opaque (see below)
364 * \param nmemb Number of elements like in calloc().
365 * liblzma will always set nmemb to 1.
366 * This argument exists only for
367 * compatibility with zlib and libbzip2.
368 * \param size Size of an element in bytes.
369 * liblzma never sets this to zero.
371 * \return Pointer to the beginning of a memory block of
372 * size nmemb * size, or NULL if allocation fails
373 * for some reason. When allocation fails, functions
374 * of liblzma return LZMA_MEM_ERROR.
376 * For performance reasons, the allocator should not waste time
377 * zeroing the allocated buffers. This is not only about speed, but
378 * also memory usage, since the operating system kernel doesn't
379 * necessarily allocate the requested memory until it is actually
380 * used. With small input files liblzma may actually need only a
381 * fraction of the memory that it requested for allocation.
383 * \note LZMA_MEM_ERROR is also used when the size of the
384 * allocation would be greater than SIZE_MAX. Thus,
385 * don't assume that the custom allocator must have
386 * returned NULL if some function from liblzma
387 * returns LZMA_MEM_ERROR.
389 void *(*alloc)(void *opaque, size_t nmemb, size_t size);
392 * \brief Pointer to custom memory freeing function
394 * If you don't want a custom freeing function, but still
395 * want a custom allocator, set this to NULL and liblzma
396 * will use the standard free().
398 * \param opaque lzma_allocator.opaque (see below)
399 * \param ptr Pointer returned by lzma_allocator.alloc(),
400 * or when it is set to NULL, a pointer returned
401 * by the standard malloc().
403 void (*free)(void *opaque, void *ptr);
406 * \brief Pointer passed to .alloc() and .free()
408 * opaque is passed as the first argument to lzma_allocator.alloc()
409 * and lzma_allocator.free(). This intended to ease implementing
410 * custom memory allocation functions for use with liblzma.
412 * If you don't need this, you should set this to NULL.
420 * \brief Internal data structure
422 * The contents of this structure is not visible outside the library.
424 typedef struct lzma_internal_s lzma_internal;
428 * \brief Passing data to and from liblzma
430 * The lzma_stream structure is used for
431 * - passing pointers to input and output buffers to liblzma;
432 * - defining custom memory hander functions; and
433 * - holding a pointer to coder-specific internal data structures.
437 * - After allocating lzma_stream (on stack or with malloc()), it must be
438 * initialized to LZMA_STREAM_INIT (see LZMA_STREAM_INIT for details).
440 * - Initialize a coder to the lzma_stream, for example by using
441 * lzma_easy_encoder() or lzma_auto_decoder(). In contrast to zlib,
442 * strm->next_in and strm->next_out are ignored by all initialization
443 * functions, thus it is safe to not initialize them yet. The
444 * initialization functions always set strm->total_in and strm->total_out
447 * - Use lzma_code() to do the actual work.
449 * - Once the coding has been finished, the existing lzma_stream can be
450 * reused. It is OK to reuse lzma_stream with different initialization
451 * function without calling lzma_end() first. Old allocations are
452 * automatically freed.
454 * - Finally, use lzma_end() to free the allocated memory.
456 * Application may modify values of total_in and total_out as it wants.
457 * They are updated by liblzma to match the amount of data read and
458 * written, but liblzma doesn't use the values internally.
461 const uint8_t *next_in; /**< Pointer to the next input byte. */
462 size_t avail_in; /**< Number of available input bytes in next_in. */
463 uint64_t total_in; /**< Total number of bytes read by liblzma. */
465 uint8_t *next_out; /**< Pointer to the next output position. */
466 size_t avail_out; /**< Amount of free space in next_out. */
467 uint64_t total_out; /**< Total number of bytes written by liblzma. */
470 * Custom memory allocation functions. Set to NULL to use
471 * the standard malloc() and free().
473 lzma_allocator *allocator;
475 /** Internal state is not visible to applications. */
476 lzma_internal *internal;
479 * Reserved space to allow possible future extensions without
480 * breaking the ABI. Excluding the initialization of this structure,
481 * you should not touch these, because the names of these variables
486 uint64_t reserved_int1;
487 uint64_t reserved_int2;
488 lzma_reserved_enum reserved_enum1;
489 lzma_reserved_enum reserved_enum2;
495 * \brief Initialization for lzma_stream
497 * When you declare an instance of lzma_stream, you can immediatelly
498 * initialize it so that initialization functions know that no memory
499 * has been allocated yet:
501 * lzma_stream strm = LZMA_STREAM_INIT;
503 * If you need to initialize a dynamically allocated lzma_stream, you can use
504 * memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this
505 * violates the C standard since NULL may have different internal
506 * representation than zero, but it should be portable enough in practice.
507 * Anyway, for maximum portability, you can use something like this:
509 * lzma_stream tmp = LZMA_STREAM_INIT;
512 #define LZMA_STREAM_INIT \
513 { NULL, 0, 0, NULL, 0, 0, NULL, NULL, NULL, NULL, 0, 0, 0, 0 }
517 * \brief Encodes or decodes data
519 * Once the lzma_stream has been successfully initialized (e.g. with
520 * lzma_stream_encoder()), the actual encoding or decoding is done
521 * using this function. The application has to update strm->next_in,
522 * strm->avail_in, strm->next_out, and strm->avail_out to pass input
523 * to and get output from liblzma.
525 * See the description of the coder-specific initialization function to find
526 * out what `action' values are supported by the coder. See documentation of
527 * lzma_ret for the possible return values.
529 extern lzma_ret lzma_code(lzma_stream *strm, lzma_action action)
530 lzma_attr_warn_unused_result;
534 * \brief Frees memory allocated for the coder data structures
536 * \param strm Pointer to lzma_stream that is at least initialized
537 * with LZMA_STREAM_INIT.
539 * \note zlib indicates an error if application end()s unfinished
540 * stream. liblzma doesn't do this, and assumes that
541 * application knows what it is doing.
543 extern void lzma_end(lzma_stream *strm);