1 | /** |
2 | * \file lzma/index.h |
3 | * \brief Handling of .xz Index and related information |
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 Opaque data type to hold the Index(es) and other information |
22 | * |
23 | * lzma_index often holds just one .xz Index and possibly the Stream Flags |
24 | * of the same Stream and size of the Stream Padding field. However, |
25 | * multiple lzma_indexes can be concatenated with lzma_index_cat() and then |
26 | * there may be information about multiple Streams in the same lzma_index. |
27 | * |
28 | * Notes about thread safety: Only one thread may modify lzma_index at |
29 | * a time. All functions that take non-const pointer to lzma_index |
30 | * modify it. As long as no thread is modifying the lzma_index, getting |
31 | * information from the same lzma_index can be done from multiple threads |
32 | * at the same time with functions that take a const pointer to |
33 | * lzma_index or use lzma_index_iter. The same iterator must be used |
34 | * only by one thread at a time, of course, but there can be as many |
35 | * iterators for the same lzma_index as needed. |
36 | */ |
37 | typedef struct lzma_index_s lzma_index; |
38 | |
39 | |
40 | /** |
41 | * \brief Iterator to get information about Blocks and Streams |
42 | */ |
43 | typedef struct { |
44 | struct { |
45 | /** |
46 | * \brief Pointer to Stream Flags |
47 | * |
48 | * This is NULL if Stream Flags have not been set for |
49 | * this Stream with lzma_index_stream_flags(). |
50 | */ |
51 | const lzma_stream_flags *flags; |
52 | |
53 | const void *reserved_ptr1; |
54 | const void *reserved_ptr2; |
55 | const void *reserved_ptr3; |
56 | |
57 | /** |
58 | * \brief Stream number in the lzma_index |
59 | * |
60 | * The first Stream is 1. |
61 | */ |
62 | lzma_vli number; |
63 | |
64 | /** |
65 | * \brief Number of Blocks in the Stream |
66 | * |
67 | * If this is zero, the block structure below has |
68 | * undefined values. |
69 | */ |
70 | lzma_vli block_count; |
71 | |
72 | /** |
73 | * \brief Compressed start offset of this Stream |
74 | * |
75 | * The offset is relative to the beginning of the lzma_index |
76 | * (i.e. usually the beginning of the .xz file). |
77 | */ |
78 | lzma_vli compressed_offset; |
79 | |
80 | /** |
81 | * \brief Uncompressed start offset of this Stream |
82 | * |
83 | * The offset is relative to the beginning of the lzma_index |
84 | * (i.e. usually the beginning of the .xz file). |
85 | */ |
86 | lzma_vli uncompressed_offset; |
87 | |
88 | /** |
89 | * \brief Compressed size of this Stream |
90 | * |
91 | * This includes all headers except the possible |
92 | * Stream Padding after this Stream. |
93 | */ |
94 | lzma_vli compressed_size; |
95 | |
96 | /** |
97 | * \brief Uncompressed size of this Stream |
98 | */ |
99 | lzma_vli uncompressed_size; |
100 | |
101 | /** |
102 | * \brief Size of Stream Padding after this Stream |
103 | * |
104 | * If it hasn't been set with lzma_index_stream_padding(), |
105 | * this defaults to zero. Stream Padding is always |
106 | * a multiple of four bytes. |
107 | */ |
108 | lzma_vli padding; |
109 | |
110 | lzma_vli reserved_vli1; |
111 | lzma_vli reserved_vli2; |
112 | lzma_vli reserved_vli3; |
113 | lzma_vli reserved_vli4; |
114 | } stream; |
115 | |
116 | struct { |
117 | /** |
118 | * \brief Block number in the file |
119 | * |
120 | * The first Block is 1. |
121 | */ |
122 | lzma_vli number_in_file; |
123 | |
124 | /** |
125 | * \brief Compressed start offset of this Block |
126 | * |
127 | * This offset is relative to the beginning of the |
128 | * lzma_index (i.e. usually the beginning of the .xz file). |
129 | * Normally this is where you should seek in the .xz file |
130 | * to start decompressing this Block. |
131 | */ |
132 | lzma_vli compressed_file_offset; |
133 | |
134 | /** |
135 | * \brief Uncompressed start offset of this Block |
136 | * |
137 | * This offset is relative to the beginning of the lzma_index |
138 | * (i.e. usually the beginning of the .xz file). |
139 | * |
140 | * When doing random-access reading, it is possible that |
141 | * the target offset is not exactly at Block boundary. One |
142 | * will need to compare the target offset against |
143 | * uncompressed_file_offset or uncompressed_stream_offset, |
144 | * and possibly decode and throw away some amount of data |
145 | * before reaching the target offset. |
146 | */ |
147 | lzma_vli uncompressed_file_offset; |
148 | |
149 | /** |
150 | * \brief Block number in this Stream |
151 | * |
152 | * The first Block is 1. |
153 | */ |
154 | lzma_vli number_in_stream; |
155 | |
156 | /** |
157 | * \brief Compressed start offset of this Block |
158 | * |
159 | * This offset is relative to the beginning of the Stream |
160 | * containing this Block. |
161 | */ |
162 | lzma_vli compressed_stream_offset; |
163 | |
164 | /** |
165 | * \brief Uncompressed start offset of this Block |
166 | * |
167 | * This offset is relative to the beginning of the Stream |
168 | * containing this Block. |
169 | */ |
170 | lzma_vli uncompressed_stream_offset; |
171 | |
172 | /** |
173 | * \brief Uncompressed size of this Block |
174 | * |
175 | * You should pass this to the Block decoder if you will |
176 | * decode this Block. It will allow the Block decoder to |
177 | * validate the uncompressed size. |
178 | */ |
179 | lzma_vli uncompressed_size; |
180 | |
181 | /** |
182 | * \brief Unpadded size of this Block |
183 | * |
184 | * You should pass this to the Block decoder if you will |
185 | * decode this Block. It will allow the Block decoder to |
186 | * validate the unpadded size. |
187 | */ |
188 | lzma_vli unpadded_size; |
189 | |
190 | /** |
191 | * \brief Total compressed size |
192 | * |
193 | * This includes all headers and padding in this Block. |
194 | * This is useful if you need to know how many bytes |
195 | * the Block decoder will actually read. |
196 | */ |
197 | lzma_vli total_size; |
198 | |
199 | lzma_vli reserved_vli1; |
200 | lzma_vli reserved_vli2; |
201 | lzma_vli reserved_vli3; |
202 | lzma_vli reserved_vli4; |
203 | |
204 | const void *reserved_ptr1; |
205 | const void *reserved_ptr2; |
206 | const void *reserved_ptr3; |
207 | const void *reserved_ptr4; |
208 | } block; |
209 | |
210 | /* |
211 | * Internal data which is used to store the state of the iterator. |
212 | * The exact format may vary between liblzma versions, so don't |
213 | * touch these in any way. |
214 | */ |
215 | union { |
216 | const void *p; |
217 | size_t s; |
218 | lzma_vli v; |
219 | } internal[6]; |
220 | } lzma_index_iter; |
221 | |
222 | |
223 | /** |
224 | * \brief Operation mode for lzma_index_iter_next() |
225 | */ |
226 | typedef enum { |
227 | LZMA_INDEX_ITER_ANY = 0, |
228 | /**< |
229 | * \brief Get the next Block or Stream |
230 | * |
231 | * Go to the next Block if the current Stream has at least |
232 | * one Block left. Otherwise go to the next Stream even if |
233 | * it has no Blocks. If the Stream has no Blocks |
234 | * (lzma_index_iter.stream.block_count == 0), |
235 | * lzma_index_iter.block will have undefined values. |
236 | */ |
237 | |
238 | LZMA_INDEX_ITER_STREAM = 1, |
239 | /**< |
240 | * \brief Get the next Stream |
241 | * |
242 | * Go to the next Stream even if the current Stream has |
243 | * unread Blocks left. If the next Stream has at least one |
244 | * Block, the iterator will point to the first Block. |
245 | * If there are no Blocks, lzma_index_iter.block will have |
246 | * undefined values. |
247 | */ |
248 | |
249 | LZMA_INDEX_ITER_BLOCK = 2, |
250 | /**< |
251 | * \brief Get the next Block |
252 | * |
253 | * Go to the next Block if the current Stream has at least |
254 | * one Block left. If the current Stream has no Blocks left, |
255 | * the next Stream with at least one Block is located and |
256 | * the iterator will be made to point to the first Block of |
257 | * that Stream. |
258 | */ |
259 | |
260 | LZMA_INDEX_ITER_NONEMPTY_BLOCK = 3 |
261 | /**< |
262 | * \brief Get the next non-empty Block |
263 | * |
264 | * This is like LZMA_INDEX_ITER_BLOCK except that it will |
265 | * skip Blocks whose Uncompressed Size is zero. |
266 | */ |
267 | |
268 | } lzma_index_iter_mode; |
269 | |
270 | |
271 | /** |
272 | * \brief Calculate memory usage of lzma_index |
273 | * |
274 | * On disk, the size of the Index field depends on both the number of Records |
275 | * stored and how big values the Records store (due to variable-length integer |
276 | * encoding). When the Index is kept in lzma_index structure, the memory usage |
277 | * depends only on the number of Records/Blocks stored in the Index(es), and |
278 | * in case of concatenated lzma_indexes, the number of Streams. The size in |
279 | * RAM is almost always significantly bigger than in the encoded form on disk. |
280 | * |
281 | * This function calculates an approximate amount of memory needed hold |
282 | * the given number of Streams and Blocks in lzma_index structure. This |
283 | * value may vary between CPU architectures and also between liblzma versions |
284 | * if the internal implementation is modified. |
285 | */ |
286 | extern LZMA_API(uint64_t) lzma_index_memusage( |
287 | lzma_vli streams, lzma_vli blocks) lzma_nothrow; |
288 | |
289 | |
290 | /** |
291 | * \brief Calculate the memory usage of an existing lzma_index |
292 | * |
293 | * This is a shorthand for lzma_index_memusage(lzma_index_stream_count(i), |
294 | * lzma_index_block_count(i)). |
295 | */ |
296 | extern LZMA_API(uint64_t) lzma_index_memused(const lzma_index *i) |
297 | lzma_nothrow; |
298 | |
299 | |
300 | /** |
301 | * \brief Allocate and initialize a new lzma_index structure |
302 | * |
303 | * \return On success, a pointer to an empty initialized lzma_index is |
304 | * returned. If allocation fails, NULL is returned. |
305 | */ |
306 | extern LZMA_API(lzma_index *) lzma_index_init(const lzma_allocator *allocator) |
307 | lzma_nothrow; |
308 | |
309 | |
310 | /** |
311 | * \brief Deallocate lzma_index |
312 | * |
313 | * If i is NULL, this does nothing. |
314 | */ |
315 | extern LZMA_API(void) lzma_index_end( |
316 | lzma_index *i, const lzma_allocator *allocator) lzma_nothrow; |
317 | |
318 | |
319 | /** |
320 | * \brief Add a new Block to lzma_index |
321 | * |
322 | * \param i Pointer to a lzma_index structure |
323 | * \param allocator Pointer to lzma_allocator, or NULL to |
324 | * use malloc() |
325 | * \param unpadded_size Unpadded Size of a Block. This can be |
326 | * calculated with lzma_block_unpadded_size() |
327 | * after encoding or decoding the Block. |
328 | * \param uncompressed_size Uncompressed Size of a Block. This can be |
329 | * taken directly from lzma_block structure |
330 | * after encoding or decoding the Block. |
331 | * |
332 | * Appending a new Block does not invalidate iterators. For example, |
333 | * if an iterator was pointing to the end of the lzma_index, after |
334 | * lzma_index_append() it is possible to read the next Block with |
335 | * an existing iterator. |
336 | * |
337 | * \return - LZMA_OK |
338 | * - LZMA_MEM_ERROR |
339 | * - LZMA_DATA_ERROR: Compressed or uncompressed size of the |
340 | * Stream or size of the Index field would grow too big. |
341 | * - LZMA_PROG_ERROR |
342 | */ |
343 | extern LZMA_API(lzma_ret) lzma_index_append( |
344 | lzma_index *i, const lzma_allocator *allocator, |
345 | lzma_vli unpadded_size, lzma_vli uncompressed_size) |
346 | lzma_nothrow lzma_attr_warn_unused_result; |
347 | |
348 | |
349 | /** |
350 | * \brief Set the Stream Flags |
351 | * |
352 | * Set the Stream Flags of the last (and typically the only) Stream |
353 | * in lzma_index. This can be useful when reading information from the |
354 | * lzma_index, because to decode Blocks, knowing the integrity check type |
355 | * is needed. |
356 | * |
357 | * The given Stream Flags are copied into internal preallocated structure |
358 | * in the lzma_index, thus the caller doesn't need to keep the *stream_flags |
359 | * available after calling this function. |
360 | * |
361 | * \return - LZMA_OK |
362 | * - LZMA_OPTIONS_ERROR: Unsupported stream_flags->version. |
363 | * - LZMA_PROG_ERROR |
364 | */ |
365 | extern LZMA_API(lzma_ret) lzma_index_stream_flags( |
366 | lzma_index *i, const lzma_stream_flags *stream_flags) |
367 | lzma_nothrow lzma_attr_warn_unused_result; |
368 | |
369 | |
370 | /** |
371 | * \brief Get the types of integrity Checks |
372 | * |
373 | * If lzma_index_stream_flags() is used to set the Stream Flags for |
374 | * every Stream, lzma_index_checks() can be used to get a bitmask to |
375 | * indicate which Check types have been used. It can be useful e.g. if |
376 | * showing the Check types to the user. |
377 | * |
378 | * The bitmask is 1 << check_id, e.g. CRC32 is 1 << 1 and SHA-256 is 1 << 10. |
379 | */ |
380 | extern LZMA_API(uint32_t) lzma_index_checks(const lzma_index *i) |
381 | lzma_nothrow lzma_attr_pure; |
382 | |
383 | |
384 | /** |
385 | * \brief Set the amount of Stream Padding |
386 | * |
387 | * Set the amount of Stream Padding of the last (and typically the only) |
388 | * Stream in the lzma_index. This is needed when planning to do random-access |
389 | * reading within multiple concatenated Streams. |
390 | * |
391 | * By default, the amount of Stream Padding is assumed to be zero bytes. |
392 | * |
393 | * \return - LZMA_OK |
394 | * - LZMA_DATA_ERROR: The file size would grow too big. |
395 | * - LZMA_PROG_ERROR |
396 | */ |
397 | extern LZMA_API(lzma_ret) lzma_index_stream_padding( |
398 | lzma_index *i, lzma_vli stream_padding) |
399 | lzma_nothrow lzma_attr_warn_unused_result; |
400 | |
401 | |
402 | /** |
403 | * \brief Get the number of Streams |
404 | */ |
405 | extern LZMA_API(lzma_vli) lzma_index_stream_count(const lzma_index *i) |
406 | lzma_nothrow lzma_attr_pure; |
407 | |
408 | |
409 | /** |
410 | * \brief Get the number of Blocks |
411 | * |
412 | * This returns the total number of Blocks in lzma_index. To get number |
413 | * of Blocks in individual Streams, use lzma_index_iter. |
414 | */ |
415 | extern LZMA_API(lzma_vli) lzma_index_block_count(const lzma_index *i) |
416 | lzma_nothrow lzma_attr_pure; |
417 | |
418 | |
419 | /** |
420 | * \brief Get the size of the Index field as bytes |
421 | * |
422 | * This is needed to verify the Backward Size field in the Stream Footer. |
423 | */ |
424 | extern LZMA_API(lzma_vli) lzma_index_size(const lzma_index *i) |
425 | lzma_nothrow lzma_attr_pure; |
426 | |
427 | |
428 | /** |
429 | * \brief Get the total size of the Stream |
430 | * |
431 | * If multiple lzma_indexes have been combined, this works as if the Blocks |
432 | * were in a single Stream. This is useful if you are going to combine |
433 | * Blocks from multiple Streams into a single new Stream. |
434 | */ |
435 | extern LZMA_API(lzma_vli) lzma_index_stream_size(const lzma_index *i) |
436 | lzma_nothrow lzma_attr_pure; |
437 | |
438 | |
439 | /** |
440 | * \brief Get the total size of the Blocks |
441 | * |
442 | * This doesn't include the Stream Header, Stream Footer, Stream Padding, |
443 | * or Index fields. |
444 | */ |
445 | extern LZMA_API(lzma_vli) lzma_index_total_size(const lzma_index *i) |
446 | lzma_nothrow lzma_attr_pure; |
447 | |
448 | |
449 | /** |
450 | * \brief Get the total size of the file |
451 | * |
452 | * When no lzma_indexes have been combined with lzma_index_cat() and there is |
453 | * no Stream Padding, this function is identical to lzma_index_stream_size(). |
454 | * If multiple lzma_indexes have been combined, this includes also the headers |
455 | * of each separate Stream and the possible Stream Padding fields. |
456 | */ |
457 | extern LZMA_API(lzma_vli) lzma_index_file_size(const lzma_index *i) |
458 | lzma_nothrow lzma_attr_pure; |
459 | |
460 | |
461 | /** |
462 | * \brief Get the uncompressed size of the file |
463 | */ |
464 | extern LZMA_API(lzma_vli) lzma_index_uncompressed_size(const lzma_index *i) |
465 | lzma_nothrow lzma_attr_pure; |
466 | |
467 | |
468 | /** |
469 | * \brief Initialize an iterator |
470 | * |
471 | * \param iter Pointer to a lzma_index_iter structure |
472 | * \param i lzma_index to which the iterator will be associated |
473 | * |
474 | * This function associates the iterator with the given lzma_index, and calls |
475 | * lzma_index_iter_rewind() on the iterator. |
476 | * |
477 | * This function doesn't allocate any memory, thus there is no |
478 | * lzma_index_iter_end(). The iterator is valid as long as the |
479 | * associated lzma_index is valid, that is, until lzma_index_end() or |
480 | * using it as source in lzma_index_cat(). Specifically, lzma_index doesn't |
481 | * become invalid if new Blocks are added to it with lzma_index_append() or |
482 | * if it is used as the destination in lzma_index_cat(). |
483 | * |
484 | * It is safe to make copies of an initialized lzma_index_iter, for example, |
485 | * to easily restart reading at some particular position. |
486 | */ |
487 | extern LZMA_API(void) lzma_index_iter_init( |
488 | lzma_index_iter *iter, const lzma_index *i) lzma_nothrow; |
489 | |
490 | |
491 | /** |
492 | * \brief Rewind the iterator |
493 | * |
494 | * Rewind the iterator so that next call to lzma_index_iter_next() will |
495 | * return the first Block or Stream. |
496 | */ |
497 | extern LZMA_API(void) lzma_index_iter_rewind(lzma_index_iter *iter) |
498 | lzma_nothrow; |
499 | |
500 | |
501 | /** |
502 | * \brief Get the next Block or Stream |
503 | * |
504 | * \param iter Iterator initialized with lzma_index_iter_init() |
505 | * \param mode Specify what kind of information the caller wants |
506 | * to get. See lzma_index_iter_mode for details. |
507 | * |
508 | * \return If next Block or Stream matching the mode was found, *iter |
509 | * is updated and this function returns false. If no Block or |
510 | * Stream matching the mode is found, *iter is not modified |
511 | * and this function returns true. If mode is set to an unknown |
512 | * value, *iter is not modified and this function returns true. |
513 | */ |
514 | extern LZMA_API(lzma_bool) lzma_index_iter_next( |
515 | lzma_index_iter *iter, lzma_index_iter_mode mode) |
516 | lzma_nothrow lzma_attr_warn_unused_result; |
517 | |
518 | |
519 | /** |
520 | * \brief Locate a Block |
521 | * |
522 | * If it is possible to seek in the .xz file, it is possible to parse |
523 | * the Index field(s) and use lzma_index_iter_locate() to do random-access |
524 | * reading with granularity of Block size. |
525 | * |
526 | * \param iter Iterator that was earlier initialized with |
527 | * lzma_index_iter_init(). |
528 | * \param target Uncompressed target offset which the caller would |
529 | * like to locate from the Stream |
530 | * |
531 | * If the target is smaller than the uncompressed size of the Stream (can be |
532 | * checked with lzma_index_uncompressed_size()): |
533 | * - Information about the Stream and Block containing the requested |
534 | * uncompressed offset is stored into *iter. |
535 | * - Internal state of the iterator is adjusted so that |
536 | * lzma_index_iter_next() can be used to read subsequent Blocks or Streams. |
537 | * - This function returns false. |
538 | * |
539 | * If target is greater than the uncompressed size of the Stream, *iter |
540 | * is not modified, and this function returns true. |
541 | */ |
542 | extern LZMA_API(lzma_bool) lzma_index_iter_locate( |
543 | lzma_index_iter *iter, lzma_vli target) lzma_nothrow; |
544 | |
545 | |
546 | /** |
547 | * \brief Concatenate lzma_indexes |
548 | * |
549 | * Concatenating lzma_indexes is useful when doing random-access reading in |
550 | * multi-Stream .xz file, or when combining multiple Streams into single |
551 | * Stream. |
552 | * |
553 | * \param dest lzma_index after which src is appended |
554 | * \param src lzma_index to be appended after dest. If this |
555 | * function succeeds, the memory allocated for src |
556 | * is freed or moved to be part of dest, and all |
557 | * iterators pointing to src will become invalid. |
558 | * \param allocator Custom memory allocator; can be NULL to use |
559 | * malloc() and free(). |
560 | * |
561 | * \return - LZMA_OK: lzma_indexes were concatenated successfully. |
562 | * src is now a dangling pointer. |
563 | * - LZMA_DATA_ERROR: *dest would grow too big. |
564 | * - LZMA_MEM_ERROR |
565 | * - LZMA_PROG_ERROR |
566 | */ |
567 | extern LZMA_API(lzma_ret) lzma_index_cat(lzma_index *dest, lzma_index *src, |
568 | const lzma_allocator *allocator) |
569 | lzma_nothrow lzma_attr_warn_unused_result; |
570 | |
571 | |
572 | /** |
573 | * \brief Duplicate lzma_index |
574 | * |
575 | * \return A copy of the lzma_index, or NULL if memory allocation failed. |
576 | */ |
577 | extern LZMA_API(lzma_index *) lzma_index_dup( |
578 | const lzma_index *i, const lzma_allocator *allocator) |
579 | lzma_nothrow lzma_attr_warn_unused_result; |
580 | |
581 | |
582 | /** |
583 | * \brief Initialize .xz Index encoder |
584 | * |
585 | * \param strm Pointer to properly prepared lzma_stream |
586 | * \param i Pointer to lzma_index which should be encoded. |
587 | * |
588 | * The valid `action' values for lzma_code() are LZMA_RUN and LZMA_FINISH. |
589 | * It is enough to use only one of them (you can choose freely; use LZMA_RUN |
590 | * to support liblzma versions older than 5.0.0). |
591 | * |
592 | * \return - LZMA_OK: Initialization succeeded, continue with lzma_code(). |
593 | * - LZMA_MEM_ERROR |
594 | * - LZMA_PROG_ERROR |
595 | */ |
596 | extern LZMA_API(lzma_ret) lzma_index_encoder( |
597 | lzma_stream *strm, const lzma_index *i) |
598 | lzma_nothrow lzma_attr_warn_unused_result; |
599 | |
600 | |
601 | /** |
602 | * \brief Initialize .xz Index decoder |
603 | * |
604 | * \param strm Pointer to properly prepared lzma_stream |
605 | * \param i The decoded Index will be made available via |
606 | * this pointer. Initially this function will |
607 | * set *i to NULL (the old value is ignored). If |
608 | * decoding succeeds (lzma_code() returns |
609 | * LZMA_STREAM_END), *i will be set to point |
610 | * to a new lzma_index, which the application |
611 | * has to later free with lzma_index_end(). |
612 | * \param memlimit How much memory the resulting lzma_index is |
613 | * allowed to require. |
614 | * |
615 | * The valid `action' values for lzma_code() are LZMA_RUN and LZMA_FINISH. |
616 | * It is enough to use only one of them (you can choose freely; use LZMA_RUN |
617 | * to support liblzma versions older than 5.0.0). |
618 | * |
619 | * \return - LZMA_OK: Initialization succeeded, continue with lzma_code(). |
620 | * - LZMA_MEM_ERROR |
621 | * - LZMA_MEMLIMIT_ERROR |
622 | * - LZMA_PROG_ERROR |
623 | */ |
624 | extern LZMA_API(lzma_ret) lzma_index_decoder( |
625 | lzma_stream *strm, lzma_index **i, uint64_t memlimit) |
626 | lzma_nothrow lzma_attr_warn_unused_result; |
627 | |
628 | |
629 | /** |
630 | * \brief Single-call .xz Index encoder |
631 | * |
632 | * \param i lzma_index to be encoded |
633 | * \param out Beginning of the output buffer |
634 | * \param out_pos The next byte will be written to out[*out_pos]. |
635 | * *out_pos is updated only if encoding succeeds. |
636 | * \param out_size Size of the out buffer; the first byte into |
637 | * which no data is written to is out[out_size]. |
638 | * |
639 | * \return - LZMA_OK: Encoding was successful. |
640 | * - LZMA_BUF_ERROR: Output buffer is too small. Use |
641 | * lzma_index_size() to find out how much output |
642 | * space is needed. |
643 | * - LZMA_PROG_ERROR |
644 | * |
645 | * \note This function doesn't take allocator argument since all |
646 | * the internal data is allocated on stack. |
647 | */ |
648 | extern LZMA_API(lzma_ret) lzma_index_buffer_encode(const lzma_index *i, |
649 | uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow; |
650 | |
651 | |
652 | /** |
653 | * \brief Single-call .xz Index decoder |
654 | * |
655 | * \param i If decoding succeeds, *i will point to a new |
656 | * lzma_index, which the application has to |
657 | * later free with lzma_index_end(). If an error |
658 | * occurs, *i will be NULL. The old value of *i |
659 | * is always ignored and thus doesn't need to be |
660 | * initialized by the caller. |
661 | * \param memlimit Pointer to how much memory the resulting |
662 | * lzma_index is allowed to require. The value |
663 | * pointed by this pointer is modified if and only |
664 | * if LZMA_MEMLIMIT_ERROR is returned. |
665 | * \param allocator Pointer to lzma_allocator, or NULL to use malloc() |
666 | * \param in Beginning of the input buffer |
667 | * \param in_pos The next byte will be read from in[*in_pos]. |
668 | * *in_pos is updated only if decoding succeeds. |
669 | * \param in_size Size of the input buffer; the first byte that |
670 | * won't be read is in[in_size]. |
671 | * |
672 | * \return - LZMA_OK: Decoding was successful. |
673 | * - LZMA_MEM_ERROR |
674 | * - LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. |
675 | * The minimum required memlimit value was stored to *memlimit. |
676 | * - LZMA_DATA_ERROR |
677 | * - LZMA_PROG_ERROR |
678 | */ |
679 | extern LZMA_API(lzma_ret) lzma_index_buffer_decode(lzma_index **i, |
680 | uint64_t *memlimit, const lzma_allocator *allocator, |
681 | const uint8_t *in, size_t *in_pos, size_t in_size) |
682 | lzma_nothrow; |
683 | |