Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/lzma/base.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/base.h
jpayne@69 5 * \brief Data types and functions used in many places in liblzma API
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 Boolean
jpayne@69 20 *
jpayne@69 21 * This is here because C89 doesn't have stdbool.h. To set a value for
jpayne@69 22 * variables having type lzma_bool, you can use
jpayne@69 23 * - C99's 'true' and 'false' from stdbool.h;
jpayne@69 24 * - C++'s internal 'true' and 'false'; or
jpayne@69 25 * - integers one (true) and zero (false).
jpayne@69 26 */
jpayne@69 27 typedef unsigned char lzma_bool;
jpayne@69 28
jpayne@69 29
jpayne@69 30 /**
jpayne@69 31 * \brief Type of reserved enumeration variable in structures
jpayne@69 32 *
jpayne@69 33 * To avoid breaking library ABI when new features are added, several
jpayne@69 34 * structures contain extra variables that may be used in future. Since
jpayne@69 35 * sizeof(enum) can be different than sizeof(int), and sizeof(enum) may
jpayne@69 36 * even vary depending on the range of enumeration constants, we specify
jpayne@69 37 * a separate type to be used for reserved enumeration variables. All
jpayne@69 38 * enumeration constants in liblzma API will be non-negative and less
jpayne@69 39 * than 128, which should guarantee that the ABI won't break even when
jpayne@69 40 * new constants are added to existing enumerations.
jpayne@69 41 */
jpayne@69 42 typedef enum {
jpayne@69 43 LZMA_RESERVED_ENUM = 0
jpayne@69 44 } lzma_reserved_enum;
jpayne@69 45
jpayne@69 46
jpayne@69 47 /**
jpayne@69 48 * \brief Return values used by several functions in liblzma
jpayne@69 49 *
jpayne@69 50 * Check the descriptions of specific functions to find out which return
jpayne@69 51 * values they can return. With some functions the return values may have
jpayne@69 52 * more specific meanings than described here; those differences are
jpayne@69 53 * described per-function basis.
jpayne@69 54 */
jpayne@69 55 typedef enum {
jpayne@69 56 LZMA_OK = 0,
jpayne@69 57 /**<
jpayne@69 58 * \brief Operation completed successfully
jpayne@69 59 */
jpayne@69 60
jpayne@69 61 LZMA_STREAM_END = 1,
jpayne@69 62 /**<
jpayne@69 63 * \brief End of stream was reached
jpayne@69 64 *
jpayne@69 65 * In encoder, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or
jpayne@69 66 * LZMA_FINISH was finished. In decoder, this indicates
jpayne@69 67 * that all the data was successfully decoded.
jpayne@69 68 *
jpayne@69 69 * In all cases, when LZMA_STREAM_END is returned, the last
jpayne@69 70 * output bytes should be picked from strm->next_out.
jpayne@69 71 */
jpayne@69 72
jpayne@69 73 LZMA_NO_CHECK = 2,
jpayne@69 74 /**<
jpayne@69 75 * \brief Input stream has no integrity check
jpayne@69 76 *
jpayne@69 77 * This return value can be returned only if the
jpayne@69 78 * LZMA_TELL_NO_CHECK flag was used when initializing
jpayne@69 79 * the decoder. LZMA_NO_CHECK is just a warning, and
jpayne@69 80 * the decoding can be continued normally.
jpayne@69 81 *
jpayne@69 82 * It is possible to call lzma_get_check() immediately after
jpayne@69 83 * lzma_code has returned LZMA_NO_CHECK. The result will
jpayne@69 84 * naturally be LZMA_CHECK_NONE, but the possibility to call
jpayne@69 85 * lzma_get_check() may be convenient in some applications.
jpayne@69 86 */
jpayne@69 87
jpayne@69 88 LZMA_UNSUPPORTED_CHECK = 3,
jpayne@69 89 /**<
jpayne@69 90 * \brief Cannot calculate the integrity check
jpayne@69 91 *
jpayne@69 92 * The usage of this return value is different in encoders
jpayne@69 93 * and decoders.
jpayne@69 94 *
jpayne@69 95 * Encoders can return this value only from the initialization
jpayne@69 96 * function. If initialization fails with this value, the
jpayne@69 97 * encoding cannot be done, because there's no way to produce
jpayne@69 98 * output with the correct integrity check.
jpayne@69 99 *
jpayne@69 100 * Decoders can return this value only from lzma_code() and
jpayne@69 101 * only if the LZMA_TELL_UNSUPPORTED_CHECK flag was used when
jpayne@69 102 * initializing the decoder. The decoding can still be
jpayne@69 103 * continued normally even if the check type is unsupported,
jpayne@69 104 * but naturally the check will not be validated, and possible
jpayne@69 105 * errors may go undetected.
jpayne@69 106 *
jpayne@69 107 * With decoder, it is possible to call lzma_get_check()
jpayne@69 108 * immediately after lzma_code() has returned
jpayne@69 109 * LZMA_UNSUPPORTED_CHECK. This way it is possible to find
jpayne@69 110 * out what the unsupported Check ID was.
jpayne@69 111 */
jpayne@69 112
jpayne@69 113 LZMA_GET_CHECK = 4,
jpayne@69 114 /**<
jpayne@69 115 * \brief Integrity check type is now available
jpayne@69 116 *
jpayne@69 117 * This value can be returned only by the lzma_code() function
jpayne@69 118 * and only if the decoder was initialized with the
jpayne@69 119 * LZMA_TELL_ANY_CHECK flag. LZMA_GET_CHECK tells the
jpayne@69 120 * application that it may now call lzma_get_check() to find
jpayne@69 121 * out the Check ID. This can be used, for example, to
jpayne@69 122 * implement a decoder that accepts only files that have
jpayne@69 123 * strong enough integrity check.
jpayne@69 124 */
jpayne@69 125
jpayne@69 126 LZMA_MEM_ERROR = 5,
jpayne@69 127 /**<
jpayne@69 128 * \brief Cannot allocate memory
jpayne@69 129 *
jpayne@69 130 * Memory allocation failed, or the size of the allocation
jpayne@69 131 * would be greater than SIZE_MAX.
jpayne@69 132 *
jpayne@69 133 * Due to internal implementation reasons, the coding cannot
jpayne@69 134 * be continued even if more memory were made available after
jpayne@69 135 * LZMA_MEM_ERROR.
jpayne@69 136 */
jpayne@69 137
jpayne@69 138 LZMA_MEMLIMIT_ERROR = 6,
jpayne@69 139 /**<
jpayne@69 140 * \brief Memory usage limit was reached
jpayne@69 141 *
jpayne@69 142 * Decoder would need more memory than allowed by the
jpayne@69 143 * specified memory usage limit. To continue decoding,
jpayne@69 144 * the memory usage limit has to be increased with
jpayne@69 145 * lzma_memlimit_set().
jpayne@69 146 *
jpayne@69 147 * liblzma 5.2.6 and earlier had a bug in single-threaded .xz
jpayne@69 148 * decoder (lzma_stream_decoder()) which made it impossible
jpayne@69 149 * to continue decoding after LZMA_MEMLIMIT_ERROR even if
jpayne@69 150 * the limit was increased using lzma_memlimit_set().
jpayne@69 151 * Other decoders worked correctly.
jpayne@69 152 */
jpayne@69 153
jpayne@69 154 LZMA_FORMAT_ERROR = 7,
jpayne@69 155 /**<
jpayne@69 156 * \brief File format not recognized
jpayne@69 157 *
jpayne@69 158 * The decoder did not recognize the input as supported file
jpayne@69 159 * format. This error can occur, for example, when trying to
jpayne@69 160 * decode .lzma format file with lzma_stream_decoder,
jpayne@69 161 * because lzma_stream_decoder accepts only the .xz format.
jpayne@69 162 */
jpayne@69 163
jpayne@69 164 LZMA_OPTIONS_ERROR = 8,
jpayne@69 165 /**<
jpayne@69 166 * \brief Invalid or unsupported options
jpayne@69 167 *
jpayne@69 168 * Invalid or unsupported options, for example
jpayne@69 169 * - unsupported filter(s) or filter options; or
jpayne@69 170 * - reserved bits set in headers (decoder only).
jpayne@69 171 *
jpayne@69 172 * Rebuilding liblzma with more features enabled, or
jpayne@69 173 * upgrading to a newer version of liblzma may help.
jpayne@69 174 */
jpayne@69 175
jpayne@69 176 LZMA_DATA_ERROR = 9,
jpayne@69 177 /**<
jpayne@69 178 * \brief Data is corrupt
jpayne@69 179 *
jpayne@69 180 * The usage of this return value is different in encoders
jpayne@69 181 * and decoders. In both encoder and decoder, the coding
jpayne@69 182 * cannot continue after this error.
jpayne@69 183 *
jpayne@69 184 * Encoders return this if size limits of the target file
jpayne@69 185 * format would be exceeded. These limits are huge, thus
jpayne@69 186 * getting this error from an encoder is mostly theoretical.
jpayne@69 187 * For example, the maximum compressed and uncompressed
jpayne@69 188 * size of a .xz Stream is roughly 8 EiB (2^63 bytes).
jpayne@69 189 *
jpayne@69 190 * Decoders return this error if the input data is corrupt.
jpayne@69 191 * This can mean, for example, invalid CRC32 in headers
jpayne@69 192 * or invalid check of uncompressed data.
jpayne@69 193 */
jpayne@69 194
jpayne@69 195 LZMA_BUF_ERROR = 10,
jpayne@69 196 /**<
jpayne@69 197 * \brief No progress is possible
jpayne@69 198 *
jpayne@69 199 * This error code is returned when the coder cannot consume
jpayne@69 200 * any new input and produce any new output. The most common
jpayne@69 201 * reason for this error is that the input stream being
jpayne@69 202 * decoded is truncated or corrupt.
jpayne@69 203 *
jpayne@69 204 * This error is not fatal. Coding can be continued normally
jpayne@69 205 * by providing more input and/or more output space, if
jpayne@69 206 * possible.
jpayne@69 207 *
jpayne@69 208 * Typically the first call to lzma_code() that can do no
jpayne@69 209 * progress returns LZMA_OK instead of LZMA_BUF_ERROR. Only
jpayne@69 210 * the second consecutive call doing no progress will return
jpayne@69 211 * LZMA_BUF_ERROR. This is intentional.
jpayne@69 212 *
jpayne@69 213 * With zlib, Z_BUF_ERROR may be returned even if the
jpayne@69 214 * application is doing nothing wrong, so apps will need
jpayne@69 215 * to handle Z_BUF_ERROR specially. The above hack
jpayne@69 216 * guarantees that liblzma never returns LZMA_BUF_ERROR
jpayne@69 217 * to properly written applications unless the input file
jpayne@69 218 * is truncated or corrupt. This should simplify the
jpayne@69 219 * applications a little.
jpayne@69 220 */
jpayne@69 221
jpayne@69 222 LZMA_PROG_ERROR = 11,
jpayne@69 223 /**<
jpayne@69 224 * \brief Programming error
jpayne@69 225 *
jpayne@69 226 * This indicates that the arguments given to the function are
jpayne@69 227 * invalid or the internal state of the decoder is corrupt.
jpayne@69 228 * - Function arguments are invalid or the structures
jpayne@69 229 * pointed by the argument pointers are invalid
jpayne@69 230 * e.g. if strm->next_out has been set to NULL and
jpayne@69 231 * strm->avail_out > 0 when calling lzma_code().
jpayne@69 232 * - lzma_* functions have been called in wrong order
jpayne@69 233 * e.g. lzma_code() was called right after lzma_end().
jpayne@69 234 * - If errors occur randomly, the reason might be flaky
jpayne@69 235 * hardware.
jpayne@69 236 *
jpayne@69 237 * If you think that your code is correct, this error code
jpayne@69 238 * can be a sign of a bug in liblzma. See the documentation
jpayne@69 239 * how to report bugs.
jpayne@69 240 */
jpayne@69 241
jpayne@69 242 LZMA_SEEK_NEEDED = 12,
jpayne@69 243 /**<
jpayne@69 244 * \brief Request to change the input file position
jpayne@69 245 *
jpayne@69 246 * Some coders can do random access in the input file. The
jpayne@69 247 * initialization functions of these coders take the file size
jpayne@69 248 * as an argument. No other coders can return LZMA_SEEK_NEEDED.
jpayne@69 249 *
jpayne@69 250 * When this value is returned, the application must seek to
jpayne@69 251 * the file position given in lzma_stream.seek_pos. This value
jpayne@69 252 * is guaranteed to never exceed the file size that was
jpayne@69 253 * specified at the coder initialization.
jpayne@69 254 *
jpayne@69 255 * After seeking the application should read new input and
jpayne@69 256 * pass it normally via lzma_stream.next_in and .avail_in.
jpayne@69 257 */
jpayne@69 258
jpayne@69 259 /*
jpayne@69 260 * These enumerations may be used internally by liblzma
jpayne@69 261 * but they will never be returned to applications.
jpayne@69 262 */
jpayne@69 263 LZMA_RET_INTERNAL1 = 101,
jpayne@69 264 LZMA_RET_INTERNAL2 = 102,
jpayne@69 265 LZMA_RET_INTERNAL3 = 103,
jpayne@69 266 LZMA_RET_INTERNAL4 = 104,
jpayne@69 267 LZMA_RET_INTERNAL5 = 105,
jpayne@69 268 LZMA_RET_INTERNAL6 = 106,
jpayne@69 269 LZMA_RET_INTERNAL7 = 107,
jpayne@69 270 LZMA_RET_INTERNAL8 = 108
jpayne@69 271 } lzma_ret;
jpayne@69 272
jpayne@69 273
jpayne@69 274 /**
jpayne@69 275 * \brief The 'action' argument for lzma_code()
jpayne@69 276 *
jpayne@69 277 * After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, LZMA_FULL_BARRIER,
jpayne@69 278 * or LZMA_FINISH, the same 'action' must be used until lzma_code() returns
jpayne@69 279 * LZMA_STREAM_END. Also, the amount of input (that is, strm->avail_in) must
jpayne@69 280 * not be modified by the application until lzma_code() returns
jpayne@69 281 * LZMA_STREAM_END. Changing the 'action' or modifying the amount of input
jpayne@69 282 * will make lzma_code() return LZMA_PROG_ERROR.
jpayne@69 283 */
jpayne@69 284 typedef enum {
jpayne@69 285 LZMA_RUN = 0,
jpayne@69 286 /**<
jpayne@69 287 * \brief Continue coding
jpayne@69 288 *
jpayne@69 289 * Encoder: Encode as much input as possible. Some internal
jpayne@69 290 * buffering will probably be done (depends on the filter
jpayne@69 291 * chain in use), which causes latency: the input used won't
jpayne@69 292 * usually be decodeable from the output of the same
jpayne@69 293 * lzma_code() call.
jpayne@69 294 *
jpayne@69 295 * Decoder: Decode as much input as possible and produce as
jpayne@69 296 * much output as possible.
jpayne@69 297 */
jpayne@69 298
jpayne@69 299 LZMA_SYNC_FLUSH = 1,
jpayne@69 300 /**<
jpayne@69 301 * \brief Make all the input available at output
jpayne@69 302 *
jpayne@69 303 * Normally the encoder introduces some latency.
jpayne@69 304 * LZMA_SYNC_FLUSH forces all the buffered data to be
jpayne@69 305 * available at output without resetting the internal
jpayne@69 306 * state of the encoder. This way it is possible to use
jpayne@69 307 * compressed stream for example for communication over
jpayne@69 308 * network.
jpayne@69 309 *
jpayne@69 310 * Only some filters support LZMA_SYNC_FLUSH. Trying to use
jpayne@69 311 * LZMA_SYNC_FLUSH with filters that don't support it will
jpayne@69 312 * make lzma_code() return LZMA_OPTIONS_ERROR. For example,
jpayne@69 313 * LZMA1 doesn't support LZMA_SYNC_FLUSH but LZMA2 does.
jpayne@69 314 *
jpayne@69 315 * Using LZMA_SYNC_FLUSH very often can dramatically reduce
jpayne@69 316 * the compression ratio. With some filters (for example,
jpayne@69 317 * LZMA2), fine-tuning the compression options may help
jpayne@69 318 * mitigate this problem significantly (for example,
jpayne@69 319 * match finder with LZMA2).
jpayne@69 320 *
jpayne@69 321 * Decoders don't support LZMA_SYNC_FLUSH.
jpayne@69 322 */
jpayne@69 323
jpayne@69 324 LZMA_FULL_FLUSH = 2,
jpayne@69 325 /**<
jpayne@69 326 * \brief Finish encoding of the current Block
jpayne@69 327 *
jpayne@69 328 * All the input data going to the current Block must have
jpayne@69 329 * been given to the encoder (the last bytes can still be
jpayne@69 330 * pending in *next_in). Call lzma_code() with LZMA_FULL_FLUSH
jpayne@69 331 * until it returns LZMA_STREAM_END. Then continue normally
jpayne@69 332 * with LZMA_RUN or finish the Stream with LZMA_FINISH.
jpayne@69 333 *
jpayne@69 334 * This action is currently supported only by Stream encoder
jpayne@69 335 * and easy encoder (which uses Stream encoder). If there is
jpayne@69 336 * no unfinished Block, no empty Block is created.
jpayne@69 337 */
jpayne@69 338
jpayne@69 339 LZMA_FULL_BARRIER = 4,
jpayne@69 340 /**<
jpayne@69 341 * \brief Finish encoding of the current Block
jpayne@69 342 *
jpayne@69 343 * This is like LZMA_FULL_FLUSH except that this doesn't
jpayne@69 344 * necessarily wait until all the input has been made
jpayne@69 345 * available via the output buffer. That is, lzma_code()
jpayne@69 346 * might return LZMA_STREAM_END as soon as all the input
jpayne@69 347 * has been consumed (avail_in == 0).
jpayne@69 348 *
jpayne@69 349 * LZMA_FULL_BARRIER is useful with a threaded encoder if
jpayne@69 350 * one wants to split the .xz Stream into Blocks at specific
jpayne@69 351 * offsets but doesn't care if the output isn't flushed
jpayne@69 352 * immediately. Using LZMA_FULL_BARRIER allows keeping
jpayne@69 353 * the threads busy while LZMA_FULL_FLUSH would make
jpayne@69 354 * lzma_code() wait until all the threads have finished
jpayne@69 355 * until more data could be passed to the encoder.
jpayne@69 356 *
jpayne@69 357 * With a lzma_stream initialized with the single-threaded
jpayne@69 358 * lzma_stream_encoder() or lzma_easy_encoder(),
jpayne@69 359 * LZMA_FULL_BARRIER is an alias for LZMA_FULL_FLUSH.
jpayne@69 360 */
jpayne@69 361
jpayne@69 362 LZMA_FINISH = 3
jpayne@69 363 /**<
jpayne@69 364 * \brief Finish the coding operation
jpayne@69 365 *
jpayne@69 366 * All the input data must have been given to the encoder
jpayne@69 367 * (the last bytes can still be pending in next_in).
jpayne@69 368 * Call lzma_code() with LZMA_FINISH until it returns
jpayne@69 369 * LZMA_STREAM_END. Once LZMA_FINISH has been used,
jpayne@69 370 * the amount of input must no longer be changed by
jpayne@69 371 * the application.
jpayne@69 372 *
jpayne@69 373 * When decoding, using LZMA_FINISH is optional unless the
jpayne@69 374 * LZMA_CONCATENATED flag was used when the decoder was
jpayne@69 375 * initialized. When LZMA_CONCATENATED was not used, the only
jpayne@69 376 * effect of LZMA_FINISH is that the amount of input must not
jpayne@69 377 * be changed just like in the encoder.
jpayne@69 378 */
jpayne@69 379 } lzma_action;
jpayne@69 380
jpayne@69 381
jpayne@69 382 /**
jpayne@69 383 * \brief Custom functions for memory handling
jpayne@69 384 *
jpayne@69 385 * A pointer to lzma_allocator may be passed via lzma_stream structure
jpayne@69 386 * to liblzma, and some advanced functions take a pointer to lzma_allocator
jpayne@69 387 * as a separate function argument. The library will use the functions
jpayne@69 388 * specified in lzma_allocator for memory handling instead of the default
jpayne@69 389 * malloc() and free(). C++ users should note that the custom memory
jpayne@69 390 * handling functions must not throw exceptions.
jpayne@69 391 *
jpayne@69 392 * Single-threaded mode only: liblzma doesn't make an internal copy of
jpayne@69 393 * lzma_allocator. Thus, it is OK to change these function pointers in
jpayne@69 394 * the middle of the coding process, but obviously it must be done
jpayne@69 395 * carefully to make sure that the replacement 'free' can deallocate
jpayne@69 396 * memory allocated by the earlier 'alloc' function(s).
jpayne@69 397 *
jpayne@69 398 * Multithreaded mode: liblzma might internally store pointers to the
jpayne@69 399 * lzma_allocator given via the lzma_stream structure. The application
jpayne@69 400 * must not change the allocator pointer in lzma_stream or the contents
jpayne@69 401 * of the pointed lzma_allocator structure until lzma_end() has been used
jpayne@69 402 * to free the memory associated with that lzma_stream. The allocation
jpayne@69 403 * functions might be called simultaneously from multiple threads, and
jpayne@69 404 * thus they must be thread safe.
jpayne@69 405 */
jpayne@69 406 typedef struct {
jpayne@69 407 /**
jpayne@69 408 * \brief Pointer to a custom memory allocation function
jpayne@69 409 *
jpayne@69 410 * If you don't want a custom allocator, but still want
jpayne@69 411 * custom free(), set this to NULL and liblzma will use
jpayne@69 412 * the standard malloc().
jpayne@69 413 *
jpayne@69 414 * \param opaque lzma_allocator.opaque (see below)
jpayne@69 415 * \param nmemb Number of elements like in calloc(). liblzma
jpayne@69 416 * will always set nmemb to 1, so it is safe to
jpayne@69 417 * ignore nmemb in a custom allocator if you like.
jpayne@69 418 * The nmemb argument exists only for
jpayne@69 419 * compatibility with zlib and libbzip2.
jpayne@69 420 * \param size Size of an element in bytes.
jpayne@69 421 * liblzma never sets this to zero.
jpayne@69 422 *
jpayne@69 423 * \return Pointer to the beginning of a memory block of
jpayne@69 424 * 'size' bytes, or NULL if allocation fails
jpayne@69 425 * for some reason. When allocation fails, functions
jpayne@69 426 * of liblzma return LZMA_MEM_ERROR.
jpayne@69 427 *
jpayne@69 428 * The allocator should not waste time zeroing the allocated buffers.
jpayne@69 429 * This is not only about speed, but also memory usage, since the
jpayne@69 430 * operating system kernel doesn't necessarily allocate the requested
jpayne@69 431 * memory in physical memory until it is actually used. With small
jpayne@69 432 * input files, liblzma may actually need only a fraction of the
jpayne@69 433 * memory that it requested for allocation.
jpayne@69 434 *
jpayne@69 435 * \note LZMA_MEM_ERROR is also used when the size of the
jpayne@69 436 * allocation would be greater than SIZE_MAX. Thus,
jpayne@69 437 * don't assume that the custom allocator must have
jpayne@69 438 * returned NULL if some function from liblzma
jpayne@69 439 * returns LZMA_MEM_ERROR.
jpayne@69 440 */
jpayne@69 441 void *(LZMA_API_CALL *alloc)(void *opaque, size_t nmemb, size_t size);
jpayne@69 442
jpayne@69 443 /**
jpayne@69 444 * \brief Pointer to a custom memory freeing function
jpayne@69 445 *
jpayne@69 446 * If you don't want a custom freeing function, but still
jpayne@69 447 * want a custom allocator, set this to NULL and liblzma
jpayne@69 448 * will use the standard free().
jpayne@69 449 *
jpayne@69 450 * \param opaque lzma_allocator.opaque (see below)
jpayne@69 451 * \param ptr Pointer returned by lzma_allocator.alloc(),
jpayne@69 452 * or when it is set to NULL, a pointer returned
jpayne@69 453 * by the standard malloc().
jpayne@69 454 */
jpayne@69 455 void (LZMA_API_CALL *free)(void *opaque, void *ptr);
jpayne@69 456
jpayne@69 457 /**
jpayne@69 458 * \brief Pointer passed to .alloc() and .free()
jpayne@69 459 *
jpayne@69 460 * opaque is passed as the first argument to lzma_allocator.alloc()
jpayne@69 461 * and lzma_allocator.free(). This intended to ease implementing
jpayne@69 462 * custom memory allocation functions for use with liblzma.
jpayne@69 463 *
jpayne@69 464 * If you don't need this, you should set this to NULL.
jpayne@69 465 */
jpayne@69 466 void *opaque;
jpayne@69 467
jpayne@69 468 } lzma_allocator;
jpayne@69 469
jpayne@69 470
jpayne@69 471 /**
jpayne@69 472 * \brief Internal data structure
jpayne@69 473 *
jpayne@69 474 * The contents of this structure is not visible outside the library.
jpayne@69 475 */
jpayne@69 476 typedef struct lzma_internal_s lzma_internal;
jpayne@69 477
jpayne@69 478
jpayne@69 479 /**
jpayne@69 480 * \brief Passing data to and from liblzma
jpayne@69 481 *
jpayne@69 482 * The lzma_stream structure is used for
jpayne@69 483 * - passing pointers to input and output buffers to liblzma;
jpayne@69 484 * - defining custom memory handler functions; and
jpayne@69 485 * - holding a pointer to coder-specific internal data structures.
jpayne@69 486 *
jpayne@69 487 * Typical usage:
jpayne@69 488 *
jpayne@69 489 * - After allocating lzma_stream (on stack or with malloc()), it must be
jpayne@69 490 * initialized to LZMA_STREAM_INIT (see LZMA_STREAM_INIT for details).
jpayne@69 491 *
jpayne@69 492 * - Initialize a coder to the lzma_stream, for example by using
jpayne@69 493 * lzma_easy_encoder() or lzma_auto_decoder(). Some notes:
jpayne@69 494 * - In contrast to zlib, strm->next_in and strm->next_out are
jpayne@69 495 * ignored by all initialization functions, thus it is safe
jpayne@69 496 * to not initialize them yet.
jpayne@69 497 * - The initialization functions always set strm->total_in and
jpayne@69 498 * strm->total_out to zero.
jpayne@69 499 * - If the initialization function fails, no memory is left allocated
jpayne@69 500 * that would require freeing with lzma_end() even if some memory was
jpayne@69 501 * associated with the lzma_stream structure when the initialization
jpayne@69 502 * function was called.
jpayne@69 503 *
jpayne@69 504 * - Use lzma_code() to do the actual work.
jpayne@69 505 *
jpayne@69 506 * - Once the coding has been finished, the existing lzma_stream can be
jpayne@69 507 * reused. It is OK to reuse lzma_stream with different initialization
jpayne@69 508 * function without calling lzma_end() first. Old allocations are
jpayne@69 509 * automatically freed.
jpayne@69 510 *
jpayne@69 511 * - Finally, use lzma_end() to free the allocated memory. lzma_end() never
jpayne@69 512 * frees the lzma_stream structure itself.
jpayne@69 513 *
jpayne@69 514 * Application may modify the values of total_in and total_out as it wants.
jpayne@69 515 * They are updated by liblzma to match the amount of data read and
jpayne@69 516 * written but aren't used for anything else except as a possible return
jpayne@69 517 * values from lzma_get_progress().
jpayne@69 518 */
jpayne@69 519 typedef struct {
jpayne@69 520 const uint8_t *next_in; /**< Pointer to the next input byte. */
jpayne@69 521 size_t avail_in; /**< Number of available input bytes in next_in. */
jpayne@69 522 uint64_t total_in; /**< Total number of bytes read by liblzma. */
jpayne@69 523
jpayne@69 524 uint8_t *next_out; /**< Pointer to the next output position. */
jpayne@69 525 size_t avail_out; /**< Amount of free space in next_out. */
jpayne@69 526 uint64_t total_out; /**< Total number of bytes written by liblzma. */
jpayne@69 527
jpayne@69 528 /**
jpayne@69 529 * \brief Custom memory allocation functions
jpayne@69 530 *
jpayne@69 531 * In most cases this is NULL which makes liblzma use
jpayne@69 532 * the standard malloc() and free().
jpayne@69 533 *
jpayne@69 534 * \note In 5.0.x this is not a const pointer.
jpayne@69 535 */
jpayne@69 536 const lzma_allocator *allocator;
jpayne@69 537
jpayne@69 538 /** Internal state is not visible to applications. */
jpayne@69 539 lzma_internal *internal;
jpayne@69 540
jpayne@69 541 /*
jpayne@69 542 * Reserved space to allow possible future extensions without
jpayne@69 543 * breaking the ABI. Excluding the initialization of this structure,
jpayne@69 544 * you should not touch these, because the names of these variables
jpayne@69 545 * may change.
jpayne@69 546 */
jpayne@69 547
jpayne@69 548 /** \private Reserved member. */
jpayne@69 549 void *reserved_ptr1;
jpayne@69 550
jpayne@69 551 /** \private Reserved member. */
jpayne@69 552 void *reserved_ptr2;
jpayne@69 553
jpayne@69 554 /** \private Reserved member. */
jpayne@69 555 void *reserved_ptr3;
jpayne@69 556
jpayne@69 557 /** \private Reserved member. */
jpayne@69 558 void *reserved_ptr4;
jpayne@69 559
jpayne@69 560 /**
jpayne@69 561 * \brief New seek input position for LZMA_SEEK_NEEDED
jpayne@69 562 *
jpayne@69 563 * When lzma_code() returns LZMA_SEEK_NEEDED, the new input position
jpayne@69 564 * needed by liblzma will be available seek_pos. The value is
jpayne@69 565 * guaranteed to not exceed the file size that was specified when
jpayne@69 566 * this lzma_stream was initialized.
jpayne@69 567 *
jpayne@69 568 * In all other situations the value of this variable is undefined.
jpayne@69 569 */
jpayne@69 570 uint64_t seek_pos;
jpayne@69 571
jpayne@69 572 /** \private Reserved member. */
jpayne@69 573 uint64_t reserved_int2;
jpayne@69 574
jpayne@69 575 /** \private Reserved member. */
jpayne@69 576 size_t reserved_int3;
jpayne@69 577
jpayne@69 578 /** \private Reserved member. */
jpayne@69 579 size_t reserved_int4;
jpayne@69 580
jpayne@69 581 /** \private Reserved member. */
jpayne@69 582 lzma_reserved_enum reserved_enum1;
jpayne@69 583
jpayne@69 584 /** \private Reserved member. */
jpayne@69 585 lzma_reserved_enum reserved_enum2;
jpayne@69 586
jpayne@69 587 } lzma_stream;
jpayne@69 588
jpayne@69 589
jpayne@69 590 /**
jpayne@69 591 * \brief Initialization for lzma_stream
jpayne@69 592 *
jpayne@69 593 * When you declare an instance of lzma_stream, you can immediately
jpayne@69 594 * initialize it so that initialization functions know that no memory
jpayne@69 595 * has been allocated yet:
jpayne@69 596 *
jpayne@69 597 * lzma_stream strm = LZMA_STREAM_INIT;
jpayne@69 598 *
jpayne@69 599 * If you need to initialize a dynamically allocated lzma_stream, you can use
jpayne@69 600 * memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this
jpayne@69 601 * violates the C standard since NULL may have different internal
jpayne@69 602 * representation than zero, but it should be portable enough in practice.
jpayne@69 603 * Anyway, for maximum portability, you can use something like this:
jpayne@69 604 *
jpayne@69 605 * lzma_stream tmp = LZMA_STREAM_INIT;
jpayne@69 606 * *strm = tmp;
jpayne@69 607 */
jpayne@69 608 #define LZMA_STREAM_INIT \
jpayne@69 609 { NULL, 0, 0, NULL, 0, 0, NULL, NULL, \
jpayne@69 610 NULL, NULL, NULL, NULL, 0, 0, 0, 0, \
jpayne@69 611 LZMA_RESERVED_ENUM, LZMA_RESERVED_ENUM }
jpayne@69 612
jpayne@69 613
jpayne@69 614 /**
jpayne@69 615 * \brief Encode or decode data
jpayne@69 616 *
jpayne@69 617 * Once the lzma_stream has been successfully initialized (e.g. with
jpayne@69 618 * lzma_stream_encoder()), the actual encoding or decoding is done
jpayne@69 619 * using this function. The application has to update strm->next_in,
jpayne@69 620 * strm->avail_in, strm->next_out, and strm->avail_out to pass input
jpayne@69 621 * to and get output from liblzma.
jpayne@69 622 *
jpayne@69 623 * See the description of the coder-specific initialization function to find
jpayne@69 624 * out what 'action' values are supported by the coder.
jpayne@69 625 *
jpayne@69 626 * \param strm Pointer to lzma_stream that is at least initialized
jpayne@69 627 * with LZMA_STREAM_INIT.
jpayne@69 628 * \param action Action for this function to take. Must be a valid
jpayne@69 629 * lzma_action enum value.
jpayne@69 630 *
jpayne@69 631 * \return Any valid lzma_ret. See the lzma_ret enum description for more
jpayne@69 632 * information.
jpayne@69 633 */
jpayne@69 634 extern LZMA_API(lzma_ret) lzma_code(lzma_stream *strm, lzma_action action)
jpayne@69 635 lzma_nothrow lzma_attr_warn_unused_result;
jpayne@69 636
jpayne@69 637
jpayne@69 638 /**
jpayne@69 639 * \brief Free memory allocated for the coder data structures
jpayne@69 640 *
jpayne@69 641 * After lzma_end(strm), strm->internal is guaranteed to be NULL. No other
jpayne@69 642 * members of the lzma_stream structure are touched.
jpayne@69 643 *
jpayne@69 644 * \note zlib indicates an error if application end()s unfinished
jpayne@69 645 * stream structure. liblzma doesn't do this, and assumes that
jpayne@69 646 * application knows what it is doing.
jpayne@69 647 *
jpayne@69 648 * \param strm Pointer to lzma_stream that is at least initialized
jpayne@69 649 * with LZMA_STREAM_INIT.
jpayne@69 650 */
jpayne@69 651 extern LZMA_API(void) lzma_end(lzma_stream *strm) lzma_nothrow;
jpayne@69 652
jpayne@69 653
jpayne@69 654 /**
jpayne@69 655 * \brief Get progress information
jpayne@69 656 *
jpayne@69 657 * In single-threaded mode, applications can get progress information from
jpayne@69 658 * strm->total_in and strm->total_out. In multi-threaded mode this is less
jpayne@69 659 * useful because a significant amount of both input and output data gets
jpayne@69 660 * buffered internally by liblzma. This makes total_in and total_out give
jpayne@69 661 * misleading information and also makes the progress indicator updates
jpayne@69 662 * non-smooth.
jpayne@69 663 *
jpayne@69 664 * This function gives realistic progress information also in multi-threaded
jpayne@69 665 * mode by taking into account the progress made by each thread. In
jpayne@69 666 * single-threaded mode *progress_in and *progress_out are set to
jpayne@69 667 * strm->total_in and strm->total_out, respectively.
jpayne@69 668 *
jpayne@69 669 * \param strm Pointer to lzma_stream that is at least
jpayne@69 670 * initialized with LZMA_STREAM_INIT.
jpayne@69 671 * \param[out] progress_in Pointer to the number of input bytes processed.
jpayne@69 672 * \param[out] progress_out Pointer to the number of output bytes processed.
jpayne@69 673 */
jpayne@69 674 extern LZMA_API(void) lzma_get_progress(lzma_stream *strm,
jpayne@69 675 uint64_t *progress_in, uint64_t *progress_out) lzma_nothrow;
jpayne@69 676
jpayne@69 677
jpayne@69 678 /**
jpayne@69 679 * \brief Get the memory usage of decoder filter chain
jpayne@69 680 *
jpayne@69 681 * This function is currently supported only when *strm has been initialized
jpayne@69 682 * with a function that takes a memlimit argument. With other functions, you
jpayne@69 683 * should use e.g. lzma_raw_encoder_memusage() or lzma_raw_decoder_memusage()
jpayne@69 684 * to estimate the memory requirements.
jpayne@69 685 *
jpayne@69 686 * This function is useful e.g. after LZMA_MEMLIMIT_ERROR to find out how big
jpayne@69 687 * the memory usage limit should have been to decode the input. Note that
jpayne@69 688 * this may give misleading information if decoding .xz Streams that have
jpayne@69 689 * multiple Blocks, because each Block can have different memory requirements.
jpayne@69 690 *
jpayne@69 691 * \param strm Pointer to lzma_stream that is at least initialized
jpayne@69 692 * with LZMA_STREAM_INIT.
jpayne@69 693 *
jpayne@69 694 * \return How much memory is currently allocated for the filter
jpayne@69 695 * decoders. If no filter chain is currently allocated,
jpayne@69 696 * some non-zero value is still returned, which is less than
jpayne@69 697 * or equal to what any filter chain would indicate as its
jpayne@69 698 * memory requirement.
jpayne@69 699 *
jpayne@69 700 * If this function isn't supported by *strm or some other error
jpayne@69 701 * occurs, zero is returned.
jpayne@69 702 */
jpayne@69 703 extern LZMA_API(uint64_t) lzma_memusage(const lzma_stream *strm)
jpayne@69 704 lzma_nothrow lzma_attr_pure;
jpayne@69 705
jpayne@69 706
jpayne@69 707 /**
jpayne@69 708 * \brief Get the current memory usage limit
jpayne@69 709 *
jpayne@69 710 * This function is supported only when *strm has been initialized with
jpayne@69 711 * a function that takes a memlimit argument.
jpayne@69 712 *
jpayne@69 713 * \param strm Pointer to lzma_stream that is at least initialized
jpayne@69 714 * with LZMA_STREAM_INIT.
jpayne@69 715 *
jpayne@69 716 * \return On success, the current memory usage limit is returned
jpayne@69 717 * (always non-zero). On error, zero is returned.
jpayne@69 718 */
jpayne@69 719 extern LZMA_API(uint64_t) lzma_memlimit_get(const lzma_stream *strm)
jpayne@69 720 lzma_nothrow lzma_attr_pure;
jpayne@69 721
jpayne@69 722
jpayne@69 723 /**
jpayne@69 724 * \brief Set the memory usage limit
jpayne@69 725 *
jpayne@69 726 * This function is supported only when *strm has been initialized with
jpayne@69 727 * a function that takes a memlimit argument.
jpayne@69 728 *
jpayne@69 729 * liblzma 5.2.3 and earlier has a bug where memlimit value of 0 causes
jpayne@69 730 * this function to do nothing (leaving the limit unchanged) and still
jpayne@69 731 * return LZMA_OK. Later versions treat 0 as if 1 had been specified (so
jpayne@69 732 * lzma_memlimit_get() will return 1 even if you specify 0 here).
jpayne@69 733 *
jpayne@69 734 * liblzma 5.2.6 and earlier had a bug in single-threaded .xz decoder
jpayne@69 735 * (lzma_stream_decoder()) which made it impossible to continue decoding
jpayne@69 736 * after LZMA_MEMLIMIT_ERROR even if the limit was increased using
jpayne@69 737 * lzma_memlimit_set(). Other decoders worked correctly.
jpayne@69 738 *
jpayne@69 739 * \return Possible lzma_ret values:
jpayne@69 740 * - LZMA_OK: New memory usage limit successfully set.
jpayne@69 741 * - LZMA_MEMLIMIT_ERROR: The new limit is too small.
jpayne@69 742 * The limit was not changed.
jpayne@69 743 * - LZMA_PROG_ERROR: Invalid arguments, e.g. *strm doesn't
jpayne@69 744 * support memory usage limit.
jpayne@69 745 */
jpayne@69 746 extern LZMA_API(lzma_ret) lzma_memlimit_set(
jpayne@69 747 lzma_stream *strm, uint64_t memlimit) lzma_nothrow;