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