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;
|
---|