src/liblzma/api/lzma/index.h

   1 /**
   2  * \file        lzma/index.h
   3  * \brief       Handling of .xz Index lists
   4  */
   5
   6 /*
   7  * Author: Lasse Collin
   8  *
   9  * This file has been put into the public domain.
  10  * You can do whatever you want with this file.
  11  *
  12  * See ../lzma.h for information about liblzma as a whole.
  13  */
  14
  15 #ifndef LZMA_H_INTERNAL
  16 #       error Never include this file directly. Use <lzma.h> instead.
  17 #endif
  18
  19
  20 /**
  21  * \brief       Opaque data type to hold the Index
  22  */
  23 typedef struct lzma_index_s lzma_index;
  24
  25
  26 /**
  27  * \brief       Index Record and its location
  28  */
  29 typedef struct {
  30         /**
  31          * \brief       Total encoded size of a Block including Block Padding
  32          *
  33          * This value is useful if you need to know the actual size of the
  34          * Block that the Block decoder will read.
  35          */
  36         lzma_vli total_size;
  37
  38         /**
  39          * \brief       Encoded size of a Block excluding Block Padding
  40          *
  41          * This value is stored in the Index. When doing random-access
  42          * reading, you should give this value to the Block decoder along
  43          * with uncompressed_size.
  44          */
  45         lzma_vli unpadded_size;
  46
  47         /**
  48          * \brief       Uncompressed Size of a Block
  49          */
  50         lzma_vli uncompressed_size;
  51
  52         /**
  53          * \brief       Compressed offset in the Stream(s)
  54          *
  55          * This is the offset of the first byte of the Block, that is,
  56          * where you need to seek to decode the Block. The offset
  57          * is relative to the beginning of the Stream, or if there are
  58          * multiple Indexes combined, relative to the beginning of the
  59          * first Stream.
  60          */
  61         lzma_vli stream_offset;
  62
  63         /**
  64          * \brief       Uncompressed offset
  65          *
  66          * When doing random-access reading, it is possible that the target
  67          * offset is not exactly at Block boundary. One will need to compare
  68          * the target offset against uncompressed_offset, and possibly decode
  69          * and throw away some amount of data before reaching the target
  70          * offset.
  71          */
  72         lzma_vli uncompressed_offset;
  73
  74 } lzma_index_record;
  75
  76
  77 /**
  78  * \brief       Calculate memory usage for Index with given number of Records
  79  *
  80  * On disk, the size of the Index field depends on both the number of Records
  81  * stored and how big values the Records store (due to variable-length integer
  82  * encoding). When the Index is kept in lzma_index structure, the memory usage
  83  * depends only on the number of Records stored in the Index. The size in RAM
  84  * is almost always a lot bigger than in encoded form on disk.
  85  *
  86  * This function calculates an approximate amount of memory needed hold the
  87  * given number of Records in lzma_index structure. This value may vary
  88  * between liblzma versions if the internal implementation is modified.
  89  *
  90  * If you want to know how much memory an existing lzma_index structure is
  91  * using, use lzma_index_memusage(lzma_index_count(i)).
  92  */
  93 extern LZMA_API(uint64_t) lzma_index_memusage(lzma_vli record_count)
  94                 lzma_nothrow;
  95
  96
  97 /**
  98  * \brief       Allocate and initialize a new lzma_index structure
  99  *
 100  * If i is NULL, a new lzma_index structure is allocated, initialized,
 101  * and a pointer to it returned. If allocation fails, NULL is returned.
 102  *
 103  * If i is non-NULL, it is reinitialized and the same pointer returned.
 104  * In this case, return value cannot be NULL or a different pointer than
 105  * the i that was given as an argument.
 106  */
 107 extern LZMA_API(lzma_index *) lzma_index_init(
 108                 lzma_index *i, lzma_allocator *allocator) lzma_nothrow;
 109
 110
 111 /**
 112  * \brief       Deallocate the Index
 113  *
 114  * If i is NULL, this does nothing.
 115  */
 116 extern LZMA_API(void) lzma_index_end(lzma_index *i, lzma_allocator *allocator)
 117                 lzma_nothrow;
 118
 119
 120 /**
 121  * \brief       Add a new Record to an Index
 122  *
 123  * \param       i                 Pointer to a lzma_index structure
 124  * \param       allocator         Pointer to lzma_allocator, or NULL to
 125  *                                use malloc()
 126  * \param       unpadded_size     Unpadded Size of a Block. This can be
 127  *                                calculated with lzma_block_unpadded_size()
 128  *                                after encoding or decoding the Block.
 129  * \param       uncompressed_size Uncompressed Size of a Block. This can be
 130  *                                taken directly from lzma_block structure
 131  *                                after encoding or decoding the Block.
 132  *
 133  * Appending a new Record does not affect the read position.
 134  *
 135  * \return      - LZMA_OK
 136  *              - LZMA_MEM_ERROR
 137  *              - LZMA_DATA_ERROR: Compressed or uncompressed size of the
 138  *                Stream or size of the Index field would grow too big.
 139  *              - LZMA_PROG_ERROR
 140  */
 141 extern LZMA_API(lzma_ret) lzma_index_append(
 142                 lzma_index *i, lzma_allocator *allocator,
 143                 lzma_vli unpadded_size, lzma_vli uncompressed_size)
 144                 lzma_nothrow lzma_attr_warn_unused_result;
 145
 146
 147 /**
 148  * \brief       Get the number of Records
 149  */
 150 extern LZMA_API(lzma_vli) lzma_index_count(const lzma_index *i)
 151                 lzma_nothrow lzma_attr_pure;
 152
 153
 154 /**
 155  * \brief       Get the size of the Index field as bytes
 156  *
 157  * This is needed to verify the Backward Size field in the Stream Footer.
 158  */
 159 extern LZMA_API(lzma_vli) lzma_index_size(const lzma_index *i)
 160                 lzma_nothrow lzma_attr_pure;
 161
 162
 163 /**
 164  * \brief       Get the total size of the Blocks
 165  *
 166  * This doesn't include the Stream Header, Stream Footer, Stream Padding,
 167  * or Index fields.
 168  */
 169 extern LZMA_API(lzma_vli) lzma_index_total_size(const lzma_index *i)
 170                 lzma_nothrow lzma_attr_pure;
 171
 172
 173 /**
 174  * \brief       Get the total size of the Stream
 175  *
 176  * If multiple Indexes have been combined, this works as if the Blocks
 177  * were in a single Stream.
 178  */
 179 extern LZMA_API(lzma_vli) lzma_index_stream_size(const lzma_index *i)
 180                 lzma_nothrow lzma_attr_pure;
 181
 182
 183 /**
 184  * \brief       Get the total size of the file
 185  *
 186  * When no Indexes have been combined with lzma_index_cat(), this function is
 187  * identical to lzma_index_stream_size(). If multiple Indexes have been
 188  * combined, this includes also the headers of each separate Stream and the
 189  * possible Stream Padding fields.
 190  */
 191 extern LZMA_API(lzma_vli) lzma_index_file_size(const lzma_index *i)
 192                 lzma_nothrow lzma_attr_pure;
 193
 194
 195 /**
 196  * \brief       Get the uncompressed size of the Stream
 197  */
 198 extern LZMA_API(lzma_vli) lzma_index_uncompressed_size(const lzma_index *i)
 199                 lzma_nothrow lzma_attr_pure;
 200
 201
 202 /**
 203  * \brief       Get the next Record from the Index
 204  */
 205 extern LZMA_API(lzma_bool) lzma_index_read(
 206                 lzma_index *i, lzma_index_record *record)
 207                 lzma_nothrow lzma_attr_warn_unused_result;
 208
 209
 210 /**
 211  * \brief       Rewind the Index
 212  *
 213  * Rewind the Index so that next call to lzma_index_read() will return the
 214  * first Record.
 215  */
 216 extern LZMA_API(void) lzma_index_rewind(lzma_index *i) lzma_nothrow;
 217
 218
 219 /**
 220  * \brief       Locate a Record
 221  *
 222  * When the Index is available, it is possible to do random-access reading
 223  * with granularity of Block size.
 224  *
 225  * \param       i       Pointer to lzma_index structure
 226  * \param       record  Pointer to a structure to hold the search results
 227  * \param       target  Uncompressed target offset which the caller would
 228  *                      like to locate from the Stream
 229  *
 230  * If the target is smaller than the uncompressed size of the Stream (can be
 231  * checked with lzma_index_uncompressed_size()):
 232  *  - Information about the Record containing the requested uncompressed
 233  *    offset is stored into *record.
 234  *  - Read offset will be adjusted so that calling lzma_index_read() can be
 235  *    used to read subsequent Records.
 236  *  - This function returns false.
 237  *
 238  * If target is greater than the uncompressed size of the Stream, *record
 239  * and the read position are not modified, and this function returns true.
 240  */
 241 extern LZMA_API(lzma_bool) lzma_index_locate(
 242                 lzma_index *i, lzma_index_record *record, lzma_vli target)
 243                 lzma_nothrow;
 244
 245
 246 /**
 247  * \brief       Concatenate Indexes of two Streams
 248  *
 249  * Concatenating Indexes is useful when doing random-access reading in
 250  * multi-Stream .xz file, or when combining multiple Streams into single
 251  * Stream.
 252  *
 253  * \param       dest      Destination Index after which src is appended
 254  * \param       src       Source Index. If this function succeeds, the
 255  *                        memory allocated for src is freed or moved to
 256  *                        be part of dest.
 257  * \param       allocator Custom memory allocator; can be NULL to use
 258  *                        malloc() and free().
 259  * \param       padding   Size of the Stream Padding field between Streams.
 260  *                        This must be a multiple of four.
 261  *
 262  * \return      - LZMA_OK: Indexes concatenated successfully. src is now
 263  *                a dangling pointer.
 264  *              - LZMA_DATA_ERROR: *dest would grow too big.
 265  *              - LZMA_MEM_ERROR
 266  *              - LZMA_PROG_ERROR
 267  */
 268 extern LZMA_API(lzma_ret) lzma_index_cat(lzma_index *lzma_restrict dest,
 269                 lzma_index *lzma_restrict src,
 270                 lzma_allocator *allocator, lzma_vli padding)
 271                 lzma_nothrow lzma_attr_warn_unused_result;
 272
 273
 274 /**
 275  * \brief       Duplicate an Index list
 276  *
 277  * Makes an identical copy of the Index. Also the read position is copied.
 278  *
 279  * \return      A copy of the Index, or NULL if memory allocation failed.
 280  */
 281 extern LZMA_API(lzma_index *) lzma_index_dup(
 282                 const lzma_index *i, lzma_allocator *allocator)
 283                 lzma_nothrow lzma_attr_warn_unused_result;
 284
 285
 286 /**
 287  * \brief       Compare if two Index lists are identical
 288  *
 289  * Read positions are not compared.
 290  *
 291  * \return      True if *a and *b are equal, false otherwise.
 292  */
 293 extern LZMA_API(lzma_bool) lzma_index_equal(
 294                 const lzma_index *a, const lzma_index *b)
 295                 lzma_nothrow lzma_attr_pure;
 296
 297
 298 /**
 299  * \brief       Initialize .xz Index encoder
 300  *
 301  * \param       strm        Pointer to properly prepared lzma_stream
 302  * \param       i           Pointer to lzma_index which should be encoded.
 303  *                          The read position will be at the end of the Index
 304  *                          after lzma_code() has returned LZMA_STREAM_END.
 305  *
 306  * The only valid action value for lzma_code() is LZMA_RUN.
 307  *
 308  * \return      - LZMA_OK: Initialization succeeded, continue with lzma_code().
 309  *              - LZMA_MEM_ERROR
 310  *              - LZMA_PROG_ERROR
 311  */
 312 extern LZMA_API(lzma_ret) lzma_index_encoder(lzma_stream *strm, lzma_index *i)
 313                 lzma_nothrow lzma_attr_warn_unused_result;
 314
 315
 316 /**
 317  * \brief       Initialize .xz Index decoder
 318  *
 319  * \param       strm        Pointer to properly prepared lzma_stream
 320  * \param       i           Pointer to a pointer that will be made to point
 321  *                          to the final decoded Index once lzma_code() has
 322  *                          returned LZMA_STREAM_END. That is,
 323  *                          lzma_index_decoder() always takes care of
 324  *                          allocating a new lzma_index structure, and *i
 325  *                          doesn't need to be initialized by the caller.
 326  * \param       memlimit    How much memory the resulting Index is allowed
 327  *                          to require.
 328  *
 329  * The only valid action value for lzma_code() is LZMA_RUN.
 330  *
 331  * \return      - LZMA_OK: Initialization succeeded, continue with lzma_code().
 332  *              - LZMA_MEM_ERROR
 333  *              - LZMA_MEMLIMIT_ERROR
 334  *              - LZMA_PROG_ERROR
 335  *
 336  * \note        The memory usage limit is checked early in the decoding
 337  *              (within the first dozen input bytes or so). The actual memory
 338  *              is allocated later in smaller pieces. If the memory usage
 339  *              limit is modified with lzma_memlimit_set() after a part
 340  *              of the Index has already been decoded, the new limit may
 341  *              get ignored.
 342  */
 343 extern LZMA_API(lzma_ret) lzma_index_decoder(
 344                 lzma_stream *strm, lzma_index **i, uint64_t memlimit)
 345                 lzma_nothrow lzma_attr_warn_unused_result;
 346
 347
 348 /**
 349  * \brief       Single-call .xz Index encoder
 350  *
 351  * \param       i         Index to be encoded. The read position will be at
 352  *                        the end of the Index if encoding succeeds, or at
 353  *                        unspecified position in case an error occurs.
 354  * \param       out       Beginning of the output buffer
 355  * \param       out_pos   The next byte will be written to out[*out_pos].
 356  *                        *out_pos is updated only if encoding succeeds.
 357  * \param       out_size  Size of the out buffer; the first byte into
 358  *                        which no data is written to is out[out_size].
 359  *
 360  * \return      - LZMA_OK: Encoding was successful.
 361  *              - LZMA_BUF_ERROR: Output buffer is too small. Use
 362  *                lzma_index_size() to find out how much output
 363  *                space is needed.
 364  *              - LZMA_PROG_ERROR
 365  *
 366  * \note        This function doesn't take allocator argument since all
 367  *              the internal data is allocated on stack.
 368  */
 369 extern LZMA_API(lzma_ret) lzma_index_buffer_encode(lzma_index *i,
 370                 uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow;
 371
 372
 373 /**
 374  * \brief       Single-call .xz Index decoder
 375  *
 376  * \param       i           Pointer to a pointer that will be made to point
 377  *                          to the final decoded Index if decoding is
 378  *                          successful. That is, lzma_index_buffer_decode()
 379  *                          always takes care of allocating a new
 380  *                          lzma_index structure, and *i doesn't need to be
 381  *                          initialized by the caller.
 382  * \param       memlimit    Pointer to how much memory the resulting Index
 383  *                          is allowed to require. The value pointed by
 384  *                          this pointer is modified if and only if
 385  *                          LZMA_MEMLIMIT_ERROR is returned.
 386  * \param       allocator   Pointer to lzma_allocator, or NULL to use malloc()
 387  * \param       in          Beginning of the input buffer
 388  * \param       in_pos      The next byte will be read from in[*in_pos].
 389  *                          *in_pos is updated only if decoding succeeds.
 390  * \param       in_size     Size of the input buffer; the first byte that
 391  *                          won't be read is in[in_size].
 392  *
 393  * \return      - LZMA_OK: Decoding was successful.
 394  *              - LZMA_MEM_ERROR
 395  *              - LZMA_MEMLIMIT_ERROR: Memory usage limit was reached.
 396  *                The minimum required memlimit value was stored to *memlimit.
 397  *              - LZMA_DATA_ERROR
 398  *              - LZMA_PROG_ERROR
 399  */
 400 extern LZMA_API(lzma_ret) lzma_index_buffer_decode(lzma_index **i,
 401                 uint64_t *memlimit, lzma_allocator *allocator,
 402                 const uint8_t *in, size_t *in_pos, size_t in_size)
 403                 lzma_nothrow;