src/liblzma/api/lzma/base.h

   1 /**
   2  * \file        lzma/base.h
   3  * \brief       Data types and functions used in many places of the public API
   4  *
   5  * \author      Copyright (C) 1999-2006 Igor Pavlov
   6  * \author      Copyright (C) 2007 Lasse Collin
   7  *
   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.
  12  *
  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.
  17  */
  18
  19 #ifndef LZMA_H_INTERNAL
  20 #       error Never include this file directly. Use <lzma.h> instead.
  21 #endif
  22
  23
  24 /**
  25  * \brief       Boolean
  26  *
  27  * This is here because C89 doesn't have stdbool.h. To set a value for
  28  * variables having type lzma_bool, you can use
  29  *   - C99's `true' and `false' from stdbool.h;
  30  *   - C++'s internal `true' and `false'; or
  31  *   - integers one (true) and zero (false).
  32  */
  33 typedef unsigned char lzma_bool;
  34
  35
  36 /**
  37  * \brief       Return values used by several functions in liblzma
  38  *
  39  * Check the descriptions of specific functions to find out which return
  40  * values they can return and the exact meanings of the values in every
  41  * situation. The descriptions given here are only suggestive.
  42  */
  43 typedef enum {
  44         LZMA_OK                 =  0,
  45                 /**<
  46                  * \brief       Operation completed successfully
  47                  */
  48
  49         LZMA_STREAM_END         =  1,
  50                 /**<
  51                  * \brief       End of stream was reached
  52                  *
  53                  * The application should pick the last remaining output
  54                  * bytes from strm->next_out.
  55                  */
  56
  57         LZMA_PROG_ERROR       = -2,
  58                 /**<
  59                  * \brief       Programming error
  60                  *
  61                  * This indicates that the arguments given to the function are
  62                  * invalid or the internal state of the decoder is corrupt.
  63                  *   - Function arguments are invalid or the structures
  64                  *     pointed by the argument pointers are invalid
  65                  *     e.g. if strm->next_out has been set to NULL and
  66                  *     strm->avail_out > 0 when calling lzma_code().
  67                  *   - lzma_* functions have been called in wrong order
  68                  *     e.g. lzma_code() was called right after lzma_end().
  69                  *   - If errors occur randomly, the reason might be flaky
  70                  *     hardware.
  71                  *
  72                  * If you think that your code is correct, this error code
  73                  * can be a sign of a bug in liblzma. See the documentation
  74                  * how to report bugs.
  75                  */
  76
  77         LZMA_DATA_ERROR         = -3,
  78                 /**<
  79                  * \brief       Data is corrupt
  80                  *
  81                  * - Encoder: The input size doesn't match the uncompressed
  82                  *   size given to lzma_*_encoder_init().
  83                  * - Decoder: The input is corrupt. This includes corrupted
  84                  *   header, corrupted compressed data, and unmatching
  85                  *   integrity Check.
  86                  *
  87                  * \todo        What can be done if encoder returns this?
  88                  *              Probably can continue by fixing the input
  89                  *              amount, but make sure.
  90                  */
  91
  92         LZMA_MEM_ERROR          = -4,
  93                 /**<
  94                  * \brief       Cannot allocate memory
  95                  *
  96                  * Memory allocation failed.
  97                  */
  98
  99         LZMA_BUF_ERROR          = -5,
 100                 /**<
 101                  * \brief       No progress is possible
 102                  *
 103                  * This may happen when avail_in or avail_out is zero.
 104                  *
 105                  * \note        This error is not fatal. Coding can continue
 106                  *              normally once the reason for this error has
 107                  *              been fixed.
 108                  */
 109
 110         LZMA_HEADER_ERROR       = -6,
 111                 /**<
 112                  * \brief       Invalid or unsupported header
 113                  *
 114                  * Invalid or unsupported options, for example
 115                  *  - unsupported filter(s) or filter options; or
 116                  *  - reserved bits set in headers (decoder only).
 117                  *
 118                  * Rebuilding liblzma with more features enabled, or
 119                  * upgrading to a newer version of liblzma may help.
 120                  */
 121
 122         LZMA_UNSUPPORTED_CHECK  = -7,
 123                 /**<
 124                  * \brief       Check type is unknown
 125                  *
 126                  * The type of Check is not supported, and thus the Check
 127                  * cannot be calculated. In the encoder, this is an error.
 128                  * In the decoder, this is only a warning and decoding can
 129                  * still proceed normally (but the Check is ignored).
 130                  */
 131
 132         LZMA_FORMAT_ERROR        = -8,
 133                 /**<
 134                  * \brief       Unknown file format
 135                  */
 136
 137         LZMA_MEMLIMIT_ERROR     = -9,
 138                 /**
 139                  * \brief       Memory usage limit was reached
 140                  *
 141                  * Decoder would need more memory than allowed by the
 142                  * specified memory usage limit. To continue decoding,
 143                  * the memory usage limit has to be increased. See functions
 144                  * lzma_memlimit_get() and lzma_memlimit_set().
 145                  */
 146
 147         LZMA_NO_CHECK = -10,
 148         LZMA_SEE_CHECK = -11
 149 } lzma_ret;
 150
 151
 152 /**
 153  * \brief       The `action' argument for lzma_code()
 154  */
 155 typedef enum {
 156         LZMA_RUN = 0,
 157                 /**<
 158                  * Encoder: Encode as much input as possible. Some internal
 159                  * buffering will probably be done (depends on the filter
 160                  * chain in use), which causes latency: the input used won't
 161                  * usually be decodeable from the output of the same
 162                  * lzma_code() call.
 163                  *
 164                  * Decoder: Decode as much input as possible and produce as
 165                  * much output as possible. This action provides best
 166                  * throughput, but may introduce latency, because the
 167                  * decoder may decode more data into its internal buffers
 168                  * than that fits into next_out.
 169                  */
 170
 171         LZMA_SYNC_FLUSH = 1,
 172                 /**<
 173                  * Encoder: Makes all the data given to liblzma via next_in
 174                  * available in next_out without resetting the filters. Call
 175                  * lzma_code() with LZMA_SYNC_FLUSH until it returns
 176                  * LZMA_STREAM_END. Then continue encoding normally.
 177                  *
 178                  * \note        Synchronous flushing is supported only by
 179                  *              some filters. Some filters support it only
 180                  *              partially.
 181                  *
 182                  * Decoder: Asks the decoder to decode only as much as is
 183                  * needed to fill next_out. This decreases latency with some
 184                  * filters, but is likely to decrease also throughput. It is
 185                  * a good idea to use this flag only when it is likely that
 186                  * you don't need more output soon.
 187                  *
 188                  * \note        With decoder, this is not comparable to
 189                  *              zlib's Z_SYNC_FLUSH.
 190                  */
 191
 192         LZMA_FULL_FLUSH = 2,
 193                 /**<
 194                  * Finishes encoding of the current Data Block. All the input
 195                  * data going to the current Data Block must have been given
 196                  * to the encoder (the last bytes can still be pending in
 197                  * next_in). Call lzma_code() with LZMA_FULL_FLUSH until
 198                  * it returns LZMA_STREAM_END. Then continue normally with
 199                  * LZMA_RUN or finish the Stream with LZMA_FINISH.
 200                  *
 201                  * This action is supported only by Multi-Block Stream
 202                  * encoder. If there is no unfinished Data Block, no empty
 203                  * Data Block is created.
 204                  */
 205
 206         LZMA_FINISH = 3
 207                 /**<
 208                  * Finishes the encoding operation. All the input data must
 209                  * have been given to the encoder (the last bytes can still
 210                  * be pending in next_in). Call lzma_code() with LZMA_FINISH
 211                  * until it returns LZMA_STREAM_END.
 212                  *
 213                  * This action is not supported by decoders.
 214                  */
 215 } lzma_action;
 216
 217
 218 /**
 219  * \brief       Custom functions for memory handling
 220  *
 221  * A pointer to lzma_allocator may be passed via lzma_stream structure
 222  * to liblzma. The library will use these functions for memory handling
 223  * instead of the default malloc() and free().
 224  *
 225  * liblzma doesn't make an internal copy of lzma_allocator. Thus, it is
 226  * OK to change these function pointers in the middle of the coding
 227  * process, but obviously it must be done carefully to make sure that the
 228  * replacement `free' can deallocate memory allocated by the earlier
 229  * `alloc' function(s).
 230  */
 231 typedef struct {
 232         /**
 233          * \brief       Pointer to custom memory allocation function
 234          *
 235          * If you don't want a custom allocator, but still want
 236          * custom free(), set this to NULL and liblzma will use
 237          * the standard malloc().
 238          *
 239          * \param       opaque  lzma_allocator.opaque (see below)
 240          * \param       nmemb   Number of elements like in calloc().
 241          *                      liblzma will always set nmemb to 1.
 242          *                      This argument exists only for
 243          *                      compatibility with zlib and libbzip2.
 244          * \param       size    Size of an element in bytes.
 245          *                      liblzma never sets this to zero.
 246          *
 247          * \return      Pointer to the beginning of a memory block of
 248          *              size nmemb * size, or NULL if allocation fails
 249          *              for some reason. When allocation fails, functions
 250          *              of liblzma return LZMA_MEM_ERROR.
 251          *
 252          * For performance reasons, the allocator should not waste time
 253          * zeroing the allocated buffers. This is not only about speed, but
 254          * also memory usage, since the operating system kernel doesn't
 255          * necessarily allocate the requested memory until it is actually
 256          * used. With small input files liblzma may actually need only a
 257          * fraction of the memory that it requested for allocation.
 258          */
 259         void *(*alloc)(void *opaque, size_t nmemb, size_t size);
 260
 261         /**
 262          * \brief       Pointer to custom memory freeing function
 263          *
 264          * If you don't want a custom freeing function, but still
 265          * want a custom allocator, set this to NULL and liblzma
 266          * will use the standard free().
 267          *
 268          * \param       opaque  lzma_allocator.opaque (see below)
 269          * \param       ptr     Pointer returned by
 270          *                      lzma_allocator.alloc(), or when it
 271          *                      is set to NULL, a pointer returned
 272          *                      by the standard malloc().
 273          */
 274         void (*free)(void *opaque, void *ptr);
 275
 276         /**
 277          * \brief       Pointer passed to .alloc() and .free()
 278          *
 279          * opaque is passed as the first argument to lzma_allocator.alloc()
 280          * and lzma_allocator.free(). This intended to ease implementing
 281          * custom memory allocation functions for use with liblzma.
 282          *
 283          * If you don't need this, you should set it to NULL.
 284          */
 285         void *opaque;
 286
 287 } lzma_allocator;
 288
 289
 290 /**
 291  * \brief       Internal data structure
 292  *
 293  * The contents of this structure is not visible outside the library.
 294  */
 295 typedef struct lzma_internal_s lzma_internal;
 296
 297
 298 /**
 299  * \brief       Passing data to and from liblzma
 300  *
 301  * The lzma_stream structure is used for
 302  *   - passing pointers to input and output buffers to liblzma;
 303  *   - defining custom memory hander functions; and
 304  *   - holding a pointer to coder-specific internal data structures.
 305  *
 306  * Before calling any of the lzma_*_init() functions the first time,
 307  * the application must reset lzma_stream to LZMA_STREAM_INIT. The
 308  * lzma_*_init() function will verify the options, allocate internal
 309  * data structures and store pointer to them into `internal'. Finally
 310  * total_in and total_out are reset to zero. In contrast to zlib,
 311  * next_in and avail_in are ignored by the initialization functions.
 312  *
 313  * The actual coding is done with the lzma_code() function. Application
 314  * must update next_in, avail_in, next_out, and avail_out between
 315  * calls to lzma_decode() just like with zlib.
 316  *
 317  * In contrast to zlib, even the decoder requires that there always
 318  * is at least one byte space in next_out; if avail_out == 0,
 319  * LZMA_BUF_ERROR is returned immediatelly. This shouldn't be a problem
 320  * for most applications that already use zlib, but it's still worth
 321  * checking your application.
 322  *
 323  * Application may modify values of total_in and total_out as it wants.
 324  * They are updated by liblzma to match the amount of data read and
 325  * written, but liblzma doesn't use the values internally.
 326  *
 327  * Application must not touch the `internal' pointer.
 328  */
 329 typedef struct {
 330         const uint8_t *next_in; /**< Pointer to the next input byte. */
 331         size_t avail_in;    /**< Number of available input bytes in next_in. */
 332         uint64_t total_in;  /**< Total number of bytes read by liblzma. */
 333
 334         uint8_t *next_out;  /**< Pointer to the next output position. */
 335         size_t avail_out;   /**< Amount of free space in next_out. */
 336         uint64_t total_out; /**< Total number of bytes written by liblzma. */
 337
 338         /**
 339          * Custom memory allocation functions. Set to NULL to use
 340          * the standard malloc() and free().
 341          */
 342         lzma_allocator *allocator;
 343
 344         /** Internal state is not visible to outsiders. */
 345         lzma_internal *internal;
 346
 347         /**
 348          * Reserved space to allow possible future extensions without
 349          * breaking the ABI. Excluding the initialization of this structure,
 350          * you should not touch these, because the names of these variables
 351          * may change.
 352          */
 353         void *reserved_ptr1;
 354         void *reserved_ptr2;
 355         uint64_t reserved_int1;
 356         uint64_t reserved_int2;
 357
 358 } lzma_stream;
 359
 360
 361 /**
 362  * \brief       Initialization for lzma_stream
 363  *
 364  * When you declare an instance of lzma_stream, you can immediatelly
 365  * initialize it so that initialization functions know that no memory
 366  * has been allocated yet:
 367  *
 368  *     lzma_stream strm = LZMA_STREAM_INIT;
 369  *
 370  * If you need to initialize a dynamically allocatedlzma_stream, you can use
 371  * memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this
 372  * violates the C standard since NULL may have different internal
 373  * representation than zero, but it should be portable enough in practice.
 374  * Anyway, for maximum portability, you could use this:
 375  *
 376  *     lzma_stream tmp = LZMA_STREAM_INIT;
 377  *     *strm = tmp;
 378  */
 379 #define LZMA_STREAM_INIT \
 380         { NULL, 0, 0, NULL, 0, 0, NULL, NULL, NULL, NULL, 0, 0 }
 381
 382
 383 /**
 384  * \brief       Encodes or decodes data
 385  *
 386  * Once the lzma_stream has been successfully initialized (e.g. with
 387  * lzma_stream_encoder_single()), the actual encoding or decoding is
 388  * done using this function.
 389  *
 390  * \return      Some coders may have more exact meaning for different return
 391  *              values, which are mentioned separately in the description of
 392  *              the initialization functions. Here are the typical meanings:
 393  *              - LZMA_OK: So far all good.
 394  *              - LZMA_STREAM_END:
 395  *                  - Encoder: LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or
 396  *                    LZMA_FINISH completed.
 397  *                  - Decoder: End of uncompressed data was reached.
 398  *              - LZMA_BUF_ERROR: Unable to progress. Provide more input or
 399  *                output space, and call this function again. This cannot
 400  *                occur if both avail_in and avail_out were non-zero (or
 401  *                there's a bug in liblzma).
 402  *              - LZMA_MEM_ERROR: Unable to allocate memory. Due to lazy
 403  *                programming, the coding cannot continue even if the
 404  *                application could free more memory. The next call must
 405  *                be lzma_end() or some initialization function.
 406  *              - LZMA_DATA_ERROR:
 407  *                  - Encoder: Filter(s) cannot process the given data.
 408  *                  - Decoder: Compressed data is corrupt.
 409  *              - LZMA_HEADER_ERROR: Unsupported options. Rebuilding liblzma
 410  *                with more features enabled or upgrading to a newer version
 411  *                may help, although usually this is a sign of invalid options
 412  *                (encoder) or corrupted input data (decoder).
 413  *              - LZMA_PROG_ERROR: Invalid arguments or the internal state
 414  *                of the coder is corrupt.
 415  */
 416 extern lzma_ret lzma_code(lzma_stream *strm, lzma_action action)
 417                 lzma_attr_warn_unused_result;
 418
 419
 420 /**
 421  * \brief       Frees memory allocated for the coder data structures
 422  *
 423  * \param       strm    Pointer to lzma_stream that is at least initialized
 424  *                      with LZMA_STREAM_INIT.
 425  *
 426  * \note        zlib indicates an error if application end()s unfinished
 427  *              stream. liblzma doesn't do this, and assumes that
 428  *              application knows what it is doing.
 429  */
 430 extern void lzma_end(lzma_stream *strm);