src/liblzma/api/lzma/index.h

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