Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/lzma/index.h @ 69:33d812a61356

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