xref: /freebsd/contrib/xz/src/liblzma/api/lzma/index.h (revision f126890ac5386406dadf7c4cfa9566cbb56537c5)
1 /* SPDX-License-Identifier: 0BSD */
2 
3 /**
4  * \file        lzma/index.h
5  * \brief       Handling of .xz Index and related information
6  * \note        Never include this file directly. Use <lzma.h> instead.
7  */
8 
9 /*
10  * Author: Lasse Collin
11  */
12 
13 #ifndef LZMA_H_INTERNAL
14 #	error Never include this file directly. Use <lzma.h> instead.
15 #endif
16 
17 
18 /**
19  * \brief       Opaque data type to hold the Index(es) and other information
20  *
21  * lzma_index often holds just one .xz Index and possibly the Stream Flags
22  * of the same Stream and size of the Stream Padding field. However,
23  * multiple lzma_indexes can be concatenated with lzma_index_cat() and then
24  * there may be information about multiple Streams in the same lzma_index.
25  *
26  * Notes about thread safety: Only one thread may modify lzma_index at
27  * a time. All functions that take non-const pointer to lzma_index
28  * modify it. As long as no thread is modifying the lzma_index, getting
29  * information from the same lzma_index can be done from multiple threads
30  * at the same time with functions that take a const pointer to
31  * lzma_index or use lzma_index_iter. The same iterator must be used
32  * only by one thread at a time, of course, but there can be as many
33  * iterators for the same lzma_index as needed.
34  */
35 typedef struct lzma_index_s lzma_index;
36 
37 
38 /**
39  * \brief       Iterator to get information about Blocks and Streams
40  */
41 typedef struct {
42 	struct {
43 		/**
44 		 * \brief       Pointer to Stream Flags
45 		 *
46 		 * This is NULL if Stream Flags have not been set for
47 		 * this Stream with lzma_index_stream_flags().
48 		 */
49 		const lzma_stream_flags *flags;
50 
51 		/** \private     Reserved member. */
52 		const void *reserved_ptr1;
53 
54 		/** \private     Reserved member. */
55 		const void *reserved_ptr2;
56 
57 		/** \private     Reserved member. */
58 		const void *reserved_ptr3;
59 
60 		/**
61 		 * \brief       Stream number in the lzma_index
62 		 *
63 		 * The first Stream is 1.
64 		 */
65 		lzma_vli number;
66 
67 		/**
68 		 * \brief       Number of Blocks in the Stream
69 		 *
70 		 * If this is zero, the block structure below has
71 		 * undefined values.
72 		 */
73 		lzma_vli block_count;
74 
75 		/**
76 		 * \brief       Compressed start offset of this Stream
77 		 *
78 		 * The offset is relative to the beginning of the lzma_index
79 		 * (i.e. usually the beginning of the .xz file).
80 		 */
81 		lzma_vli compressed_offset;
82 
83 		/**
84 		 * \brief       Uncompressed start offset of this Stream
85 		 *
86 		 * The offset is relative to the beginning of the lzma_index
87 		 * (i.e. usually the beginning of the .xz file).
88 		 */
89 		lzma_vli uncompressed_offset;
90 
91 		/**
92 		 * \brief       Compressed size of this Stream
93 		 *
94 		 * This includes all headers except the possible
95 		 * Stream Padding after this Stream.
96 		 */
97 		lzma_vli compressed_size;
98 
99 		/**
100 		 * \brief       Uncompressed size of this Stream
101 		 */
102 		lzma_vli uncompressed_size;
103 
104 		/**
105 		 * \brief       Size of Stream Padding after this Stream
106 		 *
107 		 * If it hasn't been set with lzma_index_stream_padding(),
108 		 * this defaults to zero. Stream Padding is always
109 		 * a multiple of four bytes.
110 		 */
111 		lzma_vli padding;
112 
113 
114 		/** \private     Reserved member. */
115 		lzma_vli reserved_vli1;
116 
117 		/** \private     Reserved member. */
118 		lzma_vli reserved_vli2;
119 
120 		/** \private     Reserved member. */
121 		lzma_vli reserved_vli3;
122 
123 		/** \private     Reserved member. */
124 		lzma_vli reserved_vli4;
125 	} stream;
126 
127 	struct {
128 		/**
129 		 * \brief       Block number in the file
130 		 *
131 		 * The first Block is 1.
132 		 */
133 		lzma_vli number_in_file;
134 
135 		/**
136 		 * \brief       Compressed start offset of this Block
137 		 *
138 		 * This offset is relative to the beginning of the
139 		 * lzma_index (i.e. usually the beginning of the .xz file).
140 		 * Normally this is where you should seek in the .xz file
141 		 * to start decompressing this Block.
142 		 */
143 		lzma_vli compressed_file_offset;
144 
145 		/**
146 		 * \brief       Uncompressed start offset of this Block
147 		 *
148 		 * This offset is relative to the beginning of the lzma_index
149 		 * (i.e. usually the beginning of the .xz file).
150 		 *
151 		 * When doing random-access reading, it is possible that
152 		 * the target offset is not exactly at Block boundary. One
153 		 * will need to compare the target offset against
154 		 * uncompressed_file_offset or uncompressed_stream_offset,
155 		 * and possibly decode and throw away some amount of data
156 		 * before reaching the target offset.
157 		 */
158 		lzma_vli uncompressed_file_offset;
159 
160 		/**
161 		 * \brief       Block number in this Stream
162 		 *
163 		 * The first Block is 1.
164 		 */
165 		lzma_vli number_in_stream;
166 
167 		/**
168 		 * \brief       Compressed start offset of this Block
169 		 *
170 		 * This offset is relative to the beginning of the Stream
171 		 * containing this Block.
172 		 */
173 		lzma_vli compressed_stream_offset;
174 
175 		/**
176 		 * \brief       Uncompressed start offset of this Block
177 		 *
178 		 * This offset is relative to the beginning of the Stream
179 		 * containing this Block.
180 		 */
181 		lzma_vli uncompressed_stream_offset;
182 
183 		/**
184 		 * \brief       Uncompressed size of this Block
185 		 *
186 		 * You should pass this to the Block decoder if you will
187 		 * decode this Block. It will allow the Block decoder to
188 		 * validate the uncompressed size.
189 		 */
190 		lzma_vli uncompressed_size;
191 
192 		/**
193 		 * \brief       Unpadded size of this Block
194 		 *
195 		 * You should pass this to the Block decoder if you will
196 		 * decode this Block. It will allow the Block decoder to
197 		 * validate the unpadded size.
198 		 */
199 		lzma_vli unpadded_size;
200 
201 		/**
202 		 * \brief       Total compressed size
203 		 *
204 		 * This includes all headers and padding in this Block.
205 		 * This is useful if you need to know how many bytes
206 		 * the Block decoder will actually read.
207 		 */
208 		lzma_vli total_size;
209 
210 		/** \private     Reserved member. */
211 		lzma_vli reserved_vli1;
212 
213 		/** \private     Reserved member. */
214 		lzma_vli reserved_vli2;
215 
216 		/** \private     Reserved member. */
217 		lzma_vli reserved_vli3;
218 
219 		/** \private     Reserved member. */
220 		lzma_vli reserved_vli4;
221 
222 		/** \private     Reserved member. */
223 		const void *reserved_ptr1;
224 
225 		/** \private     Reserved member. */
226 		const void *reserved_ptr2;
227 
228 		/** \private     Reserved member. */
229 		const void *reserved_ptr3;
230 
231 		/** \private     Reserved member. */
232 		const void *reserved_ptr4;
233 	} block;
234 
235 	/**
236 	 * \private     Internal struct.
237 	 *
238 	 * Internal data which is used to store the state of the iterator.
239 	 * The exact format may vary between liblzma versions, so don't
240 	 * touch these in any way.
241 	 */
242 	union {
243 		/** \private     Internal member. */
244 		const void *p;
245 
246 		/** \private     Internal member. */
247 		size_t s;
248 
249 		/** \private     Internal member. */
250 		lzma_vli v;
251 	} internal[6];
252 } lzma_index_iter;
253 
254 
255 /**
256  * \brief       Operation mode for lzma_index_iter_next()
257  */
258 typedef enum {
259 	LZMA_INDEX_ITER_ANY             = 0,
260 		/**<
261 		 * \brief       Get the next Block or Stream
262 		 *
263 		 * Go to the next Block if the current Stream has at least
264 		 * one Block left. Otherwise go to the next Stream even if
265 		 * it has no Blocks. If the Stream has no Blocks
266 		 * (lzma_index_iter.stream.block_count == 0),
267 		 * lzma_index_iter.block will have undefined values.
268 		 */
269 
270 	LZMA_INDEX_ITER_STREAM          = 1,
271 		/**<
272 		 * \brief       Get the next Stream
273 		 *
274 		 * Go to the next Stream even if the current Stream has
275 		 * unread Blocks left. If the next Stream has at least one
276 		 * Block, the iterator will point to the first Block.
277 		 * If there are no Blocks, lzma_index_iter.block will have
278 		 * undefined values.
279 		 */
280 
281 	LZMA_INDEX_ITER_BLOCK           = 2,
282 		/**<
283 		 * \brief       Get the next Block
284 		 *
285 		 * Go to the next Block if the current Stream has at least
286 		 * one Block left. If the current Stream has no Blocks left,
287 		 * the next Stream with at least one Block is located and
288 		 * the iterator will be made to point to the first Block of
289 		 * that Stream.
290 		 */
291 
292 	LZMA_INDEX_ITER_NONEMPTY_BLOCK  = 3
293 		/**<
294 		 * \brief       Get the next non-empty Block
295 		 *
296 		 * This is like LZMA_INDEX_ITER_BLOCK except that it will
297 		 * skip Blocks whose Uncompressed Size is zero.
298 		 */
299 
300 } lzma_index_iter_mode;
301 
302 
303 /**
304  * \brief       Mask for return value from lzma_index_checks() for check none
305  *
306  * \note        This and the other CHECK_MASK macros were added in 5.5.1alpha.
307  */
308 #define LZMA_INDEX_CHECK_MASK_NONE (UINT32_C(1) << LZMA_CHECK_NONE)
309 
310 /**
311  * \brief       Mask for return value from lzma_index_checks() for check CRC32
312  */
313 #define LZMA_INDEX_CHECK_MASK_CRC32 (UINT32_C(1) << LZMA_CHECK_CRC32)
314 
315 /**
316  * \brief       Mask for return value from lzma_index_checks() for check CRC64
317  */
318 #define LZMA_INDEX_CHECK_MASK_CRC64 (UINT32_C(1) << LZMA_CHECK_CRC64)
319 
320 /**
321  * \brief       Mask for return value from lzma_index_checks() for check SHA256
322  */
323 #define LZMA_INDEX_CHECK_MASK_SHA256 (UINT32_C(1) << LZMA_CHECK_SHA256)
324 
325 /**
326  * \brief       Calculate memory usage of lzma_index
327  *
328  * On disk, the size of the Index field depends on both the number of Records
329  * stored and the size of the Records (due to variable-length integer
330  * encoding). When the Index is kept in lzma_index structure, the memory usage
331  * depends only on the number of Records/Blocks stored in the Index(es), and
332  * in case of concatenated lzma_indexes, the number of Streams. The size in
333  * RAM is almost always significantly bigger than in the encoded form on disk.
334  *
335  * This function calculates an approximate amount of memory needed to hold
336  * the given number of Streams and Blocks in lzma_index structure. This
337  * value may vary between CPU architectures and also between liblzma versions
338  * if the internal implementation is modified.
339  *
340  * \param       streams Number of Streams
341  * \param       blocks  Number of Blocks
342  *
343  * \return      Approximate memory in bytes needed in a lzma_index structure.
344  */
345 extern LZMA_API(uint64_t) lzma_index_memusage(
346 		lzma_vli streams, lzma_vli blocks) lzma_nothrow;
347 
348 
349 /**
350  * \brief       Calculate the memory usage of an existing lzma_index
351  *
352  * This is a shorthand for lzma_index_memusage(lzma_index_stream_count(i),
353  * lzma_index_block_count(i)).
354  *
355  * \param       i   Pointer to lzma_index structure
356  *
357  * \return      Approximate memory in bytes used by the lzma_index structure.
358  */
359 extern LZMA_API(uint64_t) lzma_index_memused(const lzma_index *i)
360 		lzma_nothrow;
361 
362 
363 /**
364  * \brief       Allocate and initialize a new lzma_index structure
365  *
366  * \param       allocator   lzma_allocator for custom allocator functions.
367  *                          Set to NULL to use malloc() and free().
368  *
369  * \return      On success, a pointer to an empty initialized lzma_index is
370  *              returned. If allocation fails, NULL is returned.
371  */
372 extern LZMA_API(lzma_index *) lzma_index_init(const lzma_allocator *allocator)
373 		lzma_nothrow;
374 
375 
376 /**
377  * \brief       Deallocate lzma_index
378  *
379  * If i is NULL, this does nothing.
380  *
381  * \param       i           Pointer to lzma_index structure to deallocate
382  * \param       allocator   lzma_allocator for custom allocator functions.
383  *                          Set to NULL to use malloc() and free().
384  */
385 extern LZMA_API(void) lzma_index_end(
386 		lzma_index *i, const lzma_allocator *allocator) lzma_nothrow;
387 
388 
389 /**
390  * \brief       Add a new Block to lzma_index
391  *
392  * \param       i                 Pointer to a lzma_index structure
393  * \param       allocator         lzma_allocator for custom allocator
394  *                                functions. Set to NULL to use malloc()
395  *                                and free().
396  * \param       unpadded_size     Unpadded Size of a Block. This can be
397  *                                calculated with lzma_block_unpadded_size()
398  *                                after encoding or decoding the Block.
399  * \param       uncompressed_size Uncompressed Size of a Block. This can be
400  *                                taken directly from lzma_block structure
401  *                                after encoding or decoding the Block.
402  *
403  * Appending a new Block does not invalidate iterators. For example,
404  * if an iterator was pointing to the end of the lzma_index, after
405  * lzma_index_append() it is possible to read the next Block with
406  * an existing iterator.
407  *
408  * \return      Possible lzma_ret values:
409  *              - LZMA_OK
410  *              - LZMA_MEM_ERROR
411  *              - LZMA_DATA_ERROR: Compressed or uncompressed size of the
412  *                Stream or size of the Index field would grow too big.
413  *              - LZMA_PROG_ERROR
414  */
415 extern LZMA_API(lzma_ret) lzma_index_append(
416 		lzma_index *i, const lzma_allocator *allocator,
417 		lzma_vli unpadded_size, lzma_vli uncompressed_size)
418 		lzma_nothrow lzma_attr_warn_unused_result;
419 
420 
421 /**
422  * \brief       Set the Stream Flags
423  *
424  * Set the Stream Flags of the last (and typically the only) Stream
425  * in lzma_index. This can be useful when reading information from the
426  * lzma_index, because to decode Blocks, knowing the integrity check type
427  * is needed.
428  *
429  * \param       i              Pointer to lzma_index structure
430  * \param       stream_flags   Pointer to lzma_stream_flags structure. This
431  *                             is copied into the internal preallocated
432  *                             structure, so the caller doesn't need to keep
433  *                             the flags' data available after calling this
434  *                             function.
435  *
436  * \return      Possible lzma_ret values:
437  *              - LZMA_OK
438  *              - LZMA_OPTIONS_ERROR: Unsupported stream_flags->version.
439  *              - LZMA_PROG_ERROR
440  */
441 extern LZMA_API(lzma_ret) lzma_index_stream_flags(
442 		lzma_index *i, const lzma_stream_flags *stream_flags)
443 		lzma_nothrow lzma_attr_warn_unused_result;
444 
445 
446 /**
447  * \brief       Get the types of integrity Checks
448  *
449  * If lzma_index_stream_flags() is used to set the Stream Flags for
450  * every Stream, lzma_index_checks() can be used to get a bitmask to
451  * indicate which Check types have been used. It can be useful e.g. if
452  * showing the Check types to the user.
453  *
454  * The bitmask is 1 << check_id, e.g. CRC32 is 1 << 1 and SHA-256 is 1 << 10.
455  * These masks are defined for convenience as LZMA_INDEX_CHECK_MASK_XXX
456  *
457  * \param       i   Pointer to lzma_index structure
458  *
459  * \return      Bitmask indicating which Check types are used in the lzma_index
460  */
461 extern LZMA_API(uint32_t) lzma_index_checks(const lzma_index *i)
462 		lzma_nothrow lzma_attr_pure;
463 
464 
465 /**
466  * \brief       Set the amount of Stream Padding
467  *
468  * Set the amount of Stream Padding of the last (and typically the only)
469  * Stream in the lzma_index. This is needed when planning to do random-access
470  * reading within multiple concatenated Streams.
471  *
472  * By default, the amount of Stream Padding is assumed to be zero bytes.
473  *
474  * \return      Possible lzma_ret values:
475  *              - LZMA_OK
476  *              - LZMA_DATA_ERROR: The file size would grow too big.
477  *              - LZMA_PROG_ERROR
478  */
479 extern LZMA_API(lzma_ret) lzma_index_stream_padding(
480 		lzma_index *i, lzma_vli stream_padding)
481 		lzma_nothrow lzma_attr_warn_unused_result;
482 
483 
484 /**
485  * \brief       Get the number of Streams
486  *
487  * \param       i   Pointer to lzma_index structure
488  *
489  * \return      Number of Streams in the lzma_index
490  */
491 extern LZMA_API(lzma_vli) lzma_index_stream_count(const lzma_index *i)
492 		lzma_nothrow lzma_attr_pure;
493 
494 
495 /**
496  * \brief       Get the number of Blocks
497  *
498  * This returns the total number of Blocks in lzma_index. To get number
499  * of Blocks in individual Streams, use lzma_index_iter.
500  *
501  * \param       i   Pointer to lzma_index structure
502  *
503  * \return      Number of blocks in the lzma_index
504  */
505 extern LZMA_API(lzma_vli) lzma_index_block_count(const lzma_index *i)
506 		lzma_nothrow lzma_attr_pure;
507 
508 
509 /**
510  * \brief       Get the size of the Index field as bytes
511  *
512  * This is needed to verify the Backward Size field in the Stream Footer.
513  *
514  * \param       i   Pointer to lzma_index structure
515  *
516  * \return      Size in bytes of the Index
517  */
518 extern LZMA_API(lzma_vli) lzma_index_size(const lzma_index *i)
519 		lzma_nothrow lzma_attr_pure;
520 
521 
522 /**
523  * \brief       Get the total size of the Stream
524  *
525  * If multiple lzma_indexes have been combined, this works as if the Blocks
526  * were in a single Stream. This is useful if you are going to combine
527  * Blocks from multiple Streams into a single new Stream.
528  *
529  * \param       i   Pointer to lzma_index structure
530  *
531  * \return      Size in bytes of the Stream (if all Blocks are combined
532  *              into one Stream).
533  */
534 extern LZMA_API(lzma_vli) lzma_index_stream_size(const lzma_index *i)
535 		lzma_nothrow lzma_attr_pure;
536 
537 
538 /**
539  * \brief       Get the total size of the Blocks
540  *
541  * This doesn't include the Stream Header, Stream Footer, Stream Padding,
542  * or Index fields.
543  *
544  * \param       i   Pointer to lzma_index structure
545  *
546  * \return      Size in bytes of all Blocks in the Stream(s)
547  */
548 extern LZMA_API(lzma_vli) lzma_index_total_size(const lzma_index *i)
549 		lzma_nothrow lzma_attr_pure;
550 
551 
552 /**
553  * \brief       Get the total size of the file
554  *
555  * When no lzma_indexes have been combined with lzma_index_cat() and there is
556  * no Stream Padding, this function is identical to lzma_index_stream_size().
557  * If multiple lzma_indexes have been combined, this includes also the headers
558  * of each separate Stream and the possible Stream Padding fields.
559  *
560  * \param       i   Pointer to lzma_index structure
561  *
562  * \return      Total size of the .xz file in bytes
563  */
564 extern LZMA_API(lzma_vli) lzma_index_file_size(const lzma_index *i)
565 		lzma_nothrow lzma_attr_pure;
566 
567 
568 /**
569  * \brief       Get the uncompressed size of the file
570  *
571  * \param       i   Pointer to lzma_index structure
572  *
573  * \return      Size in bytes of the uncompressed data in the file
574  */
575 extern LZMA_API(lzma_vli) lzma_index_uncompressed_size(const lzma_index *i)
576 		lzma_nothrow lzma_attr_pure;
577 
578 
579 /**
580  * \brief       Initialize an iterator
581  *
582  * This function associates the iterator with the given lzma_index, and calls
583  * lzma_index_iter_rewind() on the iterator.
584  *
585  * This function doesn't allocate any memory, thus there is no
586  * lzma_index_iter_end(). The iterator is valid as long as the
587  * associated lzma_index is valid, that is, until lzma_index_end() or
588  * using it as source in lzma_index_cat(). Specifically, lzma_index doesn't
589  * become invalid if new Blocks are added to it with lzma_index_append() or
590  * if it is used as the destination in lzma_index_cat().
591  *
592  * It is safe to make copies of an initialized lzma_index_iter, for example,
593  * to easily restart reading at some particular position.
594  *
595  * \param       iter    Pointer to a lzma_index_iter structure
596  * \param       i       lzma_index to which the iterator will be associated
597  */
598 extern LZMA_API(void) lzma_index_iter_init(
599 		lzma_index_iter *iter, const lzma_index *i) lzma_nothrow;
600 
601 
602 /**
603  * \brief       Rewind the iterator
604  *
605  * Rewind the iterator so that next call to lzma_index_iter_next() will
606  * return the first Block or Stream.
607  *
608  * \param       iter    Pointer to a lzma_index_iter structure
609  */
610 extern LZMA_API(void) lzma_index_iter_rewind(lzma_index_iter *iter)
611 		lzma_nothrow;
612 
613 
614 /**
615  * \brief       Get the next Block or Stream
616  *
617  * \param       iter    Iterator initialized with lzma_index_iter_init()
618  * \param       mode    Specify what kind of information the caller wants
619  *                      to get. See lzma_index_iter_mode for details.
620  *
621  * \return      lzma_bool:
622  *              - true if no Block or Stream matching the mode is found.
623  *                *iter is not updated (failure).
624  *              - false if the next Block or Stream matching the mode was
625  *                found. *iter is updated (success).
626  */
627 extern LZMA_API(lzma_bool) lzma_index_iter_next(
628 		lzma_index_iter *iter, lzma_index_iter_mode mode)
629 		lzma_nothrow lzma_attr_warn_unused_result;
630 
631 
632 /**
633  * \brief       Locate a Block
634  *
635  * If it is possible to seek in the .xz file, it is possible to parse
636  * the Index field(s) and use lzma_index_iter_locate() to do random-access
637  * reading with granularity of Block size.
638  *
639  * If the target is smaller than the uncompressed size of the Stream (can be
640  * checked with lzma_index_uncompressed_size()):
641  *  - Information about the Stream and Block containing the requested
642  *    uncompressed offset is stored into *iter.
643  *  - Internal state of the iterator is adjusted so that
644  *    lzma_index_iter_next() can be used to read subsequent Blocks or Streams.
645  *
646  * If the target is greater than the uncompressed size of the Stream, *iter
647  * is not modified.
648  *
649  * \param       iter    Iterator that was earlier initialized with
650  *                      lzma_index_iter_init().
651  * \param       target  Uncompressed target offset which the caller would
652  *                      like to locate from the Stream
653  *
654  * \return      lzma_bool:
655  *              - true if the target is greater than or equal to the
656  *                uncompressed size of the Stream (failure)
657  *              - false if the target is smaller than the uncompressed size
658  *                of the Stream (success)
659  */
660 extern LZMA_API(lzma_bool) lzma_index_iter_locate(
661 		lzma_index_iter *iter, lzma_vli target) lzma_nothrow;
662 
663 
664 /**
665  * \brief       Concatenate lzma_indexes
666  *
667  * Concatenating lzma_indexes is useful when doing random-access reading in
668  * multi-Stream .xz file, or when combining multiple Streams into single
669  * Stream.
670  *
671  * \param[out]  dest      lzma_index after which src is appended
672  * \param       src       lzma_index to be appended after dest. If this
673  *                        function succeeds, the memory allocated for src
674  *                        is freed or moved to be part of dest, and all
675  *                        iterators pointing to src will become invalid.
676 * \param       allocator  lzma_allocator for custom allocator functions.
677  *                        Set to NULL to use malloc() and free().
678  *
679  * \return      Possible lzma_ret values:
680  *              - LZMA_OK: lzma_indexes were concatenated successfully.
681  *                src is now a dangling pointer.
682  *              - LZMA_DATA_ERROR: *dest would grow too big.
683  *              - LZMA_MEM_ERROR
684  *              - LZMA_PROG_ERROR
685  */
686 extern LZMA_API(lzma_ret) lzma_index_cat(lzma_index *dest, lzma_index *src,
687 		const lzma_allocator *allocator)
688 		lzma_nothrow lzma_attr_warn_unused_result;
689 
690 
691 /**
692  * \brief       Duplicate lzma_index
693  *
694  * \param       i         Pointer to lzma_index structure to be duplicated
695  * \param       allocator lzma_allocator for custom allocator functions.
696  *                        Set to NULL to use malloc() and free().
697  *
698  * \return      A copy of the lzma_index, or NULL if memory allocation failed.
699  */
700 extern LZMA_API(lzma_index *) lzma_index_dup(
701 		const lzma_index *i, const lzma_allocator *allocator)
702 		lzma_nothrow lzma_attr_warn_unused_result;
703 
704 
705 /**
706  * \brief       Initialize .xz Index encoder
707  *
708  * \param       strm        Pointer to properly prepared lzma_stream
709  * \param       i           Pointer to lzma_index which should be encoded.
710  *
711  * The valid 'action' values for lzma_code() are LZMA_RUN and LZMA_FINISH.
712  * It is enough to use only one of them (you can choose freely).
713  *
714  * \return      Possible lzma_ret values:
715  *              - LZMA_OK: Initialization succeeded, continue with lzma_code().
716  *              - LZMA_MEM_ERROR
717  *              - LZMA_PROG_ERROR
718  */
719 extern LZMA_API(lzma_ret) lzma_index_encoder(
720 		lzma_stream *strm, const lzma_index *i)
721 		lzma_nothrow lzma_attr_warn_unused_result;
722 
723 
724 /**
725  * \brief       Initialize .xz Index decoder
726  *
727  * \param       strm        Pointer to properly prepared lzma_stream
728  * \param[out]  i           The decoded Index will be made available via
729  *                          this pointer. Initially this function will
730  *                          set *i to NULL (the old value is ignored). If
731  *                          decoding succeeds (lzma_code() returns
732  *                          LZMA_STREAM_END), *i will be set to point
733  *                          to a new lzma_index, which the application
734  *                          has to later free with lzma_index_end().
735  * \param       memlimit    How much memory the resulting lzma_index is
736  *                          allowed to require. liblzma 5.2.3 and earlier
737  *                          don't allow 0 here and return LZMA_PROG_ERROR;
738  *                          later versions treat 0 as if 1 had been specified.
739  *
740  * Valid 'action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH.
741  * There is no need to use LZMA_FINISH, but it's allowed because it may
742  * simplify certain types of applications.
743  *
744  * \return      Possible lzma_ret values:
745  *              - LZMA_OK: Initialization succeeded, continue with lzma_code().
746  *              - LZMA_MEM_ERROR
747  *              - LZMA_PROG_ERROR
748  *
749  * \note        liblzma 5.2.3 and older list also LZMA_MEMLIMIT_ERROR here
750  *              but that error code has never been possible from this
751  *              initialization function.
752  */
753 extern LZMA_API(lzma_ret) lzma_index_decoder(
754 		lzma_stream *strm, lzma_index **i, uint64_t memlimit)
755 		lzma_nothrow lzma_attr_warn_unused_result;
756 
757 
758 /**
759  * \brief       Single-call .xz Index encoder
760  *
761  * \note        This function doesn't take allocator argument since all
762  *              the internal data is allocated on stack.
763  *
764  * \param       i         lzma_index to be encoded
765  * \param[out]  out       Beginning of the output buffer
766  * \param[out]  out_pos   The next byte will be written to out[*out_pos].
767  *                        *out_pos is updated only if encoding succeeds.
768  * \param       out_size  Size of the out buffer; the first byte into
769  *                        which no data is written to is out[out_size].
770  *
771  * \return      Possible lzma_ret values:
772  *              - LZMA_OK: Encoding was successful.
773  *              - LZMA_BUF_ERROR: Output buffer is too small. Use
774  *                lzma_index_size() to find out how much output
775  *                space is needed.
776  *              - LZMA_PROG_ERROR
777  *
778  */
779 extern LZMA_API(lzma_ret) lzma_index_buffer_encode(const lzma_index *i,
780 		uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow;
781 
782 
783 /**
784  * \brief       Single-call .xz Index decoder
785  *
786  * \param[out]  i           If decoding succeeds, *i will point to a new
787  *                          lzma_index, which the application has to
788  *                          later free with lzma_index_end(). If an error
789  *                          occurs, *i will be NULL. The old value of *i
790  *                          is always ignored and thus doesn't need to be
791  *                          initialized by the caller.
792  * \param[out]  memlimit    Pointer to how much memory the resulting
793  *                          lzma_index is allowed to require. The value
794  *                          pointed by this pointer is modified if and only
795  *                          if LZMA_MEMLIMIT_ERROR is returned.
796   * \param      allocator   lzma_allocator for custom allocator functions.
797  *                          Set to NULL to use malloc() and free().
798  * \param       in          Beginning of the input buffer
799  * \param       in_pos      The next byte will be read from in[*in_pos].
800  *                          *in_pos is updated only if decoding succeeds.
801  * \param       in_size     Size of the input buffer; the first byte that
802  *                          won't be read is in[in_size].
803  *
804  * \return      Possible lzma_ret values:
805  *              - LZMA_OK: Decoding was successful.
806  *              - LZMA_MEM_ERROR
807  *              - LZMA_MEMLIMIT_ERROR: Memory usage limit was reached.
808  *                The minimum required memlimit value was stored to *memlimit.
809  *              - LZMA_DATA_ERROR
810  *              - LZMA_PROG_ERROR
811  */
812 extern LZMA_API(lzma_ret) lzma_index_buffer_decode(lzma_index **i,
813 		uint64_t *memlimit, const lzma_allocator *allocator,
814 		const uint8_t *in, size_t *in_pos, size_t in_size)
815 		lzma_nothrow;
816 
817 
818 /**
819  * \brief       Initialize a .xz file information decoder
820  *
821  * This decoder decodes the Stream Header, Stream Footer, Index, and
822  * Stream Padding field(s) from the input .xz file and stores the resulting
823  * combined index in *dest_index. This information can be used to get the
824  * uncompressed file size with lzma_index_uncompressed_size(*dest_index) or,
825  * for example, to implement random access reading by locating the Blocks
826  * in the Streams.
827  *
828  * To get the required information from the .xz file, lzma_code() may ask
829  * the application to seek in the input file by returning LZMA_SEEK_NEEDED
830  * and having the target file position specified in lzma_stream.seek_pos.
831  * The number of seeks required depends on the input file and how big buffers
832  * the application provides. When possible, the decoder will seek backward
833  * and forward in the given buffer to avoid useless seek requests. Thus, if
834  * the application provides the whole file at once, no external seeking will
835  * be required (that is, lzma_code() won't return LZMA_SEEK_NEEDED).
836  *
837  * The value in lzma_stream.total_in can be used to estimate how much data
838  * liblzma had to read to get the file information. However, due to seeking
839  * and the way total_in is updated, the value of total_in will be somewhat
840  * inaccurate (a little too big). Thus, total_in is a good estimate but don't
841  * expect to see the same exact value for the same file if you change the
842  * input buffer size or switch to a different liblzma version.
843  *
844  * Valid 'action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH.
845  * You only need to use LZMA_RUN; LZMA_FINISH is only supported because it
846  * might be convenient for some applications. If you use LZMA_FINISH and if
847  * lzma_code() asks the application to seek, remember to reset 'action' back
848  * to LZMA_RUN unless you hit the end of the file again.
849  *
850  * Possible return values from lzma_code():
851  *   - LZMA_OK: All OK so far, more input needed
852  *   - LZMA_SEEK_NEEDED: Provide more input starting from the absolute
853  *     file position strm->seek_pos
854  *   - LZMA_STREAM_END: Decoding was successful, *dest_index has been set
855  *   - LZMA_FORMAT_ERROR: The input file is not in the .xz format (the
856  *     expected magic bytes were not found from the beginning of the file)
857  *   - LZMA_OPTIONS_ERROR: File looks valid but contains headers that aren't
858  *     supported by this version of liblzma
859  *   - LZMA_DATA_ERROR: File is corrupt
860  *   - LZMA_BUF_ERROR
861  *   - LZMA_MEM_ERROR
862  *   - LZMA_MEMLIMIT_ERROR
863  *   - LZMA_PROG_ERROR
864  *
865  * \param       strm        Pointer to a properly prepared lzma_stream
866  * \param[out]  dest_index  Pointer to a pointer where the decoder will put
867  *                          the decoded lzma_index. The old value
868  *                          of *dest_index is ignored (not freed).
869  * \param       memlimit    How much memory the resulting lzma_index is
870  *                          allowed to require. Use UINT64_MAX to
871  *                          effectively disable the limiter.
872  * \param       file_size   Size of the input .xz file
873  *
874  * \return      Possible lzma_ret values:
875  *              - LZMA_OK
876  *              - LZMA_MEM_ERROR
877  *              - LZMA_PROG_ERROR
878  */
879 extern LZMA_API(lzma_ret) lzma_file_info_decoder(
880 		lzma_stream *strm, lzma_index **dest_index,
881 		uint64_t memlimit, uint64_t file_size)
882 		lzma_nothrow;
883