3 * \brief Handling of .xz Index lists
5 * \author Copyright (C) 1999-2006 Igor Pavlov
6 * \author Copyright (C) 2007 Lasse Collin
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
19 #ifndef LZMA_H_INTERNAL
20 # error Never include this file directly. Use <lzma.h> instead.
25 * \brief Opaque data type to hold the Index
27 typedef struct lzma_index_s lzma_index;
31 * \brief Index Record and its location
35 * \brief Total encoded size of a Block including Block Padding
37 * This value is useful if you need to know the actual size of the
38 * Block that the Block decoder will read.
43 * \brief Encoded size of a Block excluding Block Padding
45 * This value is stored in the Index. When doing random-access
46 * reading, you should give this value to the Block decoder along
47 * with uncompressed_size.
49 lzma_vli unpadded_size;
52 * \brief Uncompressed Size of a Block
54 lzma_vli uncompressed_size;
57 * Offset of the first byte of a Block relative to the beginning
58 * of the Stream, or if there are multiple Indexes combined,
59 * relative to the beginning of the first Stream.
61 lzma_vli stream_offset;
66 lzma_vli uncompressed_offset;
72 * \brief Calculate memory usage for Index with given number of Records
74 * On disk, the size of the Index field depends on both the number of Records
75 * stored and how big values the Records store (due to variable-length integer
76 * encoding). When the Index is kept in lzma_index structure, the memory usage
77 * depends only on the number of Records stored in the Index. The size in RAM
78 * is almost always a lot bigger than in encoded form on disk.
80 * This function calculates an approximate amount of memory needed hold the
81 * given number of Records in lzma_index structure. This value may vary
82 * between liblzma versions if the internal implementation is modified.
84 * If you want to know how much memory an existing lzma_index structure is
85 * using, use lzma_index_memusage(lzma_index_count(i)).
87 extern LZMA_API(uint64_t) lzma_index_memusage(lzma_vli record_count);
91 * \brief Allocate and initialize a new lzma_index structure
93 * If i is NULL, a new lzma_index structure is allocated, initialized,
94 * and a pointer to it returned. If allocation fails, NULL is returned.
96 * If i is non-NULL, it is reinitialized and the same pointer returned.
97 * In this case, return value cannot be NULL or a different pointer than
98 * the i that was given as an argument.
100 extern LZMA_API(lzma_index *) lzma_index_init(
101 lzma_index *i, lzma_allocator *allocator)
102 lzma_attr_warn_unused_result;
106 * \brief Deallocate the Index
108 * If i is NULL, this does nothing.
110 extern LZMA_API(void) lzma_index_end(lzma_index *i, lzma_allocator *allocator);
114 * \brief Add a new Record to an Index
116 * \param i Pointer to a lzma_index structure
117 * \param allocator Pointer to lzma_allocator, or NULL to
119 * \param unpadded_size Unpadded Size of a Block. This can be
120 * calculated with lzma_block_unpadded_size()
121 * after encoding or decoding the Block.
122 * \param uncompressed_size Uncompressed Size of a Block. This can be
123 * taken directly from lzma_block structure
124 * after encoding or decoding the Block.
126 * Appending a new Record does not affect the read position.
130 * - LZMA_DATA_ERROR: Compressed or uncompressed size of the
131 * Stream or size of the Index field would grow too big.
134 extern LZMA_API(lzma_ret) lzma_index_append(
135 lzma_index *i, lzma_allocator *allocator,
136 lzma_vli unpadded_size, lzma_vli uncompressed_size)
137 lzma_attr_warn_unused_result;
141 * \brief Get the number of Records
143 extern LZMA_API(lzma_vli) lzma_index_count(const lzma_index *i) lzma_attr_pure;
147 * \brief Get the size of the Index field as bytes
149 * This is needed to verify the Backward Size field in the Stream Footer.
151 extern LZMA_API(lzma_vli) lzma_index_size(const lzma_index *i) lzma_attr_pure;
155 * \brief Get the total size of the Blocks
157 * This doesn't include the Stream Header, Stream Footer, Stream Padding,
160 extern LZMA_API(lzma_vli) lzma_index_total_size(const lzma_index *i)
165 * \brief Get the total size of the Stream
167 * If multiple Indexes have been combined, this works as if the Blocks
168 * were in a single Stream.
170 extern LZMA_API(lzma_vli) lzma_index_stream_size(const lzma_index *i)
175 * \brief Get the total size of the file
177 * When no Indexes have been combined with lzma_index_cat(), this function is
178 * identical to lzma_index_stream_size(). If multiple Indexes have been
179 * combined, this includes also the headers of each separate Stream and the
180 * possible Stream Padding fields.
182 extern LZMA_API(lzma_vli) lzma_index_file_size(const lzma_index *i)
187 * \brief Get the uncompressed size of the Stream
189 extern LZMA_API(lzma_vli) lzma_index_uncompressed_size(const lzma_index *i)
194 * \brief Get the next Record from the Index
196 extern LZMA_API(lzma_bool) lzma_index_read(
197 lzma_index *i, lzma_index_record *record)
198 lzma_attr_warn_unused_result;
202 * \brief Rewind the Index
204 * Rewind the Index so that next call to lzma_index_read() will return the
207 extern LZMA_API(void) lzma_index_rewind(lzma_index *i);
211 * \brief Locate a Record
213 * When the Index is available, it is possible to do random-access reading
214 * with granularity of Block size.
216 * \param i Pointer to lzma_index structure
217 * \param record Pointer to a structure to hold the search results
218 * \param target Uncompressed target offset which the caller would
219 * like to locate from the Stream
221 * If the target is smaller than the uncompressed size of the Stream (can be
222 * checked with lzma_index_uncompressed_size()):
223 * - Information about the Record containing the requested uncompressed
224 * offset is stored into *record.
225 * - Read offset will be adjusted so that calling lzma_index_read() can be
226 * used to read subsequent Records.
227 * - This function returns false.
229 * If target is greater than the uncompressed size of the Stream, *record
230 * and the read position are not modified, and this function returns true.
232 extern LZMA_API(lzma_bool) lzma_index_locate(
233 lzma_index *i, lzma_index_record *record, lzma_vli target)
234 lzma_attr_warn_unused_result;
238 * \brief Concatenate Indexes of two Streams
242 * \param dest Destination Index after which src is appended
243 * \param src Source Index. The memory allocated for this is
244 * either moved to be part of *dest or freed if and
245 * only if the function call succeeds, and src will
246 * be an invalid pointer.
247 * \param allocator Custom memory allocator; can be NULL to use
248 * malloc() and free().
249 * \param padding Size of the Stream Padding field between Streams.
250 * This must be a multiple of four.
252 * \return - LZMA_OK: Indexes concatenated successfully.
253 * - LZMA_DATA_ERROR: *dest would grow too big.
257 extern LZMA_API(lzma_ret) lzma_index_cat(lzma_index *lzma_restrict dest,
258 lzma_index *lzma_restrict src,
259 lzma_allocator *allocator, lzma_vli padding)
260 lzma_attr_warn_unused_result;
264 * \brief Duplicate an Index list
266 * Makes an identical copy of the Index. Also the read position is copied.
268 * \return A copy of the Index, or NULL if memory allocation failed.
270 extern LZMA_API(lzma_index *) lzma_index_dup(
271 const lzma_index *i, lzma_allocator *allocator)
272 lzma_attr_warn_unused_result;
276 * \brief Compare if two Index lists are identical
278 * \return True if *a and *b are equal, false otherwise.
280 extern LZMA_API(lzma_bool) lzma_index_equal(
281 const lzma_index *a, const lzma_index *b)
286 * \brief Initialize Index encoder
288 * \param strm Pointer to properly prepared lzma_stream
289 * \param i Pointer to lzma_index which should be encoded.
290 * The read position will be at the end of the Index
291 * after lzma_code() has returned LZMA_STREAM_END.
293 * The only valid action value for lzma_code() is LZMA_RUN.
295 * \return - LZMA_OK: Initialization succeeded, continue with lzma_code().
299 extern LZMA_API(lzma_ret) lzma_index_encoder(lzma_stream *strm, lzma_index *i)
300 lzma_attr_warn_unused_result;
304 * \brief Initialize Index decoder
306 * \param strm Pointer to properly prepared lzma_stream
307 * \param i Pointer to a pointer that will be made to point
308 * to the final decoded Index once lzma_code() has
309 * returned LZMA_STREAM_END. That is,
310 * lzma_index_decoder() always takes care of
311 * allocating a new lzma_index structure, and *i
312 * doesn't need to be initialized by the caller.
313 * \param memlimit How much memory the resulting Index is allowed
316 * The only valid action value for lzma_code() is LZMA_RUN.
318 * \return - LZMA_OK: Initialization succeeded, continue with lzma_code().
320 * - LZMA_MEMLIMIT_ERROR
323 * \note The memory usage limit is checked early in the decoding
324 * (within the first dozen input bytes or so). The actual memory
325 * is allocated later in smaller pieces. If the memory usage
326 * limit is modified after decoding a part of the Index already,
327 * the new limit may be ignored.
329 extern LZMA_API(lzma_ret) lzma_index_decoder(
330 lzma_stream *strm, lzma_index **i, uint64_t memlimit)
331 lzma_attr_warn_unused_result;
335 * \brief Single-call Index encoder
337 * \param i Index to be encoded. The read position will be at
338 * the end of the Index if encoding succeeds, or at
339 * unspecified position in case an error occurs.
340 * \param out Beginning of the output buffer
341 * \param out_pos The next byte will be written to out[*out_pos].
342 * *out_pos is updated only if encoding succeeds.
343 * \param out_size Size of the out buffer; the first byte into
344 * which no data is written to is out[out_size].
346 * \return - LZMA_OK: Encoding was successful.
347 * - LZMA_BUF_ERROR: Output buffer is too small. Use
348 * lzma_index_size() to find out how much output
352 * \note This function doesn't take allocator argument since all
353 * the internal data is allocated on stack.
355 extern LZMA_API(lzma_ret) lzma_index_buffer_encode(lzma_index *i,
356 uint8_t *out, size_t *out_pos, size_t out_size);
360 * \brief Single-call Index decoder
362 * \param i Pointer to a pointer that will be made to point
363 * to the final decoded Index if decoding is
364 * successful. That is, lzma_index_buffer_decode()
365 * always takes care of allocating a new
366 * lzma_index structure, and *i doesn't need to be
367 * initialized by the caller.
368 * \param memlimit Pointer to how much memory the resulting Index
369 * is allowed to require. The value pointed by
370 * this pointer is modified if and only if
371 * LZMA_MEMLIMIT_ERROR is returned.
372 * \param allocator Pointer to lzma_allocator, or NULL to use malloc()
373 * \param in Beginning of the input buffer
374 * \param in_pos The next byte will be read from in[*in_pos].
375 * *in_pos is updated only if decoding succeeds.
376 * \param in_size Size of the input buffer; the first byte that
377 * won't be read is in[in_size].
379 * \return - LZMA_OK: Decoding was successful.
381 * - LZMA_MEMLIMIT_ERROR: Memory usage limit was reached.
382 * The minimum required memlimit value was stored to *memlimit.
386 extern LZMA_API(lzma_ret) lzma_index_buffer_decode(
387 lzma_index **i, uint64_t *memlimit, lzma_allocator *allocator,
388 const uint8_t *in, size_t *in_pos, size_t in_size);