/build/buildd/xz-utils-4.999.9beta+20091116/src/liblzma/api/lzma/index.h File Reference

Handling of .xz Index lists. More...

Data Structures

struct  lzma_index_record
 Index Record and its location. More...

Typedefs

typedef struct lzma_index_s lzma_index
 Opaque data type to hold the Index.

Functions

uint64_t lzma_index_memusage (lzma_vli record_count) lzma_nothrow
 Calculate memory usage for Index with given number of Records.
lzma_indexlzma_index_init (lzma_index *i, lzma_allocator *allocator) lzma_nothrow
 Allocate and initialize a new lzma_index structure.
void lzma_index_end (lzma_index *i, lzma_allocator *allocator) lzma_nothrow
 Deallocate the Index.
lzma_ret lzma_index_append (lzma_index *i, lzma_allocator *allocator, lzma_vli unpadded_size, lzma_vli uncompressed_size) lzma_nothrow lzma_attr_warn_unused_result
 Add a new Record to an Index.
lzma_vli lzma_index_count (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the number of Records.
lzma_vli lzma_index_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the size of the Index field as bytes.
lzma_vli lzma_index_total_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the total size of the Blocks.
lzma_vli lzma_index_stream_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the total size of the Stream.
lzma_vli lzma_index_file_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the total size of the file.
lzma_vli lzma_index_uncompressed_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the uncompressed size of the Stream.
lzma_bool lzma_index_read (lzma_index *i, lzma_index_record *record) lzma_nothrow lzma_attr_warn_unused_result
 Get the next Record from the Index.
void lzma_index_rewind (lzma_index *i) lzma_nothrow
 Rewind the Index.
lzma_bool lzma_index_locate (lzma_index *i, lzma_index_record *record, lzma_vli target) lzma_nothrow
 Locate a Record.
lzma_ret lzma_index_cat (lzma_index *lzma_restrict dest, lzma_index *lzma_restrict src, lzma_allocator *allocator, lzma_vli padding) lzma_nothrow lzma_attr_warn_unused_result
 Concatenate Indexes of two Streams.
lzma_indexlzma_index_dup (const lzma_index *i, lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Duplicate an Index list.
lzma_bool lzma_index_equal (const lzma_index *a, const lzma_index *b) lzma_nothrow lzma_attr_pure
 Compare if two Index lists are identical.
lzma_ret lzma_index_encoder (lzma_stream *strm, lzma_index *i) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Index encoder.
lzma_ret lzma_index_decoder (lzma_stream *strm, lzma_index **i, uint64_t memlimit) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Index decoder.
lzma_ret lzma_index_buffer_encode (lzma_index *i, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Single-call .xz Index encoder.
lzma_ret lzma_index_buffer_decode (lzma_index **i, uint64_t *memlimit, lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size) lzma_nothrow
 Single-call .xz Index decoder.

Detailed Description

Handling of .xz Index lists.


Typedef Documentation

typedef struct lzma_index_s lzma_index

Opaque data type to hold the Index.


Function Documentation

uint64_t lzma_index_memusage ( lzma_vli  record_count  ) 

Calculate memory usage for Index with given number of Records.

On disk, the size of the Index field depends on both the number of Records stored and how big values the Records store (due to variable-length integer encoding). When the Index is kept in lzma_index structure, the memory usage depends only on the number of Records stored in the Index. The size in RAM is almost always a lot bigger than in encoded form on disk.

This function calculates an approximate amount of memory needed hold the given number of Records in lzma_index structure. This value may vary between liblzma versions if the internal implementation is modified.

If you want to know how much memory an existing lzma_index structure is using, use lzma_index_memusage(lzma_index_count(i)).

References INDEX_GROUP_SIZE, and LZMA_VLI_MAX.

Referenced by lzma_index_buffer_decode().

lzma_index* lzma_index_init ( lzma_index i,
lzma_allocator allocator 
)

Allocate and initialize a new lzma_index structure.

If i is NULL, a new lzma_index structure is allocated, initialized, and a pointer to it returned. If allocation fails, NULL is returned.

If i is non-NULL, it is reinitialized and the same pointer returned. In this case, return value cannot be NULL or a different pointer than the i that was given as an argument.

References lzma_alloc().

Referenced by lzma_stream_buffer_encode().

void lzma_index_end ( lzma_index i,
lzma_allocator allocator 
)

Deallocate the Index.

If i is NULL, this does nothing.

Referenced by lzma_index_buffer_decode(), lzma_index_dup(), and lzma_stream_buffer_encode().

lzma_ret lzma_index_append ( lzma_index i,
lzma_allocator allocator,
lzma_vli  unpadded_size,
lzma_vli  uncompressed_size 
)

Add a new Record to an Index.

Parameters:
i Pointer to a lzma_index structure
allocator Pointer to lzma_allocator, or NULL to use malloc()
unpadded_size Unpadded Size of a Block. This can be calculated with lzma_block_unpadded_size() after encoding or decoding the Block.
uncompressed_size Uncompressed Size of a Block. This can be taken directly from lzma_block structure after encoding or decoding the Block.

Appending a new Record does not affect the read position.

Returns:
- LZMA_OK
  • LZMA_MEM_ERROR
  • LZMA_DATA_ERROR: Compressed or uncompressed size of the Stream or size of the Index field would grow too big.
  • LZMA_PROG_ERROR

References index_append_real(), LZMA_DATA_ERROR, lzma_index_file_size(), lzma_index_size(), LZMA_OK, LZMA_PROG_ERROR, LZMA_VLI_MAX, and lzma_vli_size().

Referenced by lzma_stream_buffer_encode().

lzma_vli lzma_index_count ( const lzma_index i  ) 

Get the number of Records.

lzma_vli lzma_index_size ( const lzma_index i  ) 

Get the size of the Index field as bytes.

This is needed to verify the Backward Size field in the Stream Footer.

Referenced by lzma_index_append(), lzma_index_buffer_encode(), and lzma_stream_buffer_encode().

lzma_vli lzma_index_total_size ( const lzma_index i  ) 

Get the total size of the Blocks.

This doesn't include the Stream Header, Stream Footer, Stream Padding, or Index fields.

lzma_vli lzma_index_stream_size ( const lzma_index i  ) 

Get the total size of the Stream.

If multiple Indexes have been combined, this works as if the Blocks were in a single Stream.

References LZMA_STREAM_HEADER_SIZE.

lzma_vli lzma_index_file_size ( const lzma_index i  ) 

Get the total size of the file.

When no Indexes have been combined with lzma_index_cat(), this function is identical to lzma_index_stream_size(). If multiple Indexes have been combined, this includes also the headers of each separate Stream and the possible Stream Padding fields.

References LZMA_STREAM_HEADER_SIZE.

Referenced by lzma_index_append().

lzma_vli lzma_index_uncompressed_size ( const lzma_index i  ) 

Get the uncompressed size of the Stream.

lzma_bool lzma_index_read ( lzma_index i,
lzma_index_record record 
)

Get the next Record from the Index.

References init_current(), next_group(), and set_info().

void lzma_index_rewind ( lzma_index i  ) 

Rewind the Index.

Rewind the Index so that next call to lzma_index_read() will return the first Record.

lzma_bool lzma_index_locate ( lzma_index i,
lzma_index_record record,
lzma_vli  target 
)

Locate a Record.

When the Index is available, it is possible to do random-access reading with granularity of Block size.

Parameters:
i Pointer to lzma_index structure
record Pointer to a structure to hold the search results
target Uncompressed target offset which the caller would like to locate from the Stream

If the target is smaller than the uncompressed size of the Stream (can be checked with lzma_index_uncompressed_size()):

  • Information about the Record containing the requested uncompressed offset is stored into *record.
  • Read offset will be adjusted so that calling lzma_index_read() can be used to read subsequent Records.
  • This function returns false.

If target is greater than the uncompressed size of the Stream, *record and the read position are not modified, and this function returns true.

References init_current(), next_group(), previous_group(), and set_info().

lzma_ret lzma_index_cat ( lzma_index *lzma_restrict  dest,
lzma_index *lzma_restrict  src,
lzma_allocator allocator,
lzma_vli  padding 
)

Concatenate Indexes of two Streams.

Concatenating Indexes is useful when doing random-access reading in multi-Stream .xz file, or when combining multiple Streams into single Stream.

Parameters:
dest Destination Index after which src is appended
src Source Index. If this function succeeds, the memory allocated for src is freed or moved to be part of dest.
allocator Custom memory allocator; can be NULL to use malloc() and free().
padding Size of the Stream Padding field between Streams. This must be a multiple of four.
Returns:
- LZMA_OK: Indexes concatenated successfully. src is now a dangling pointer.
  • LZMA_DATA_ERROR: *dest would grow too big.
  • LZMA_MEM_ERROR
  • LZMA_PROG_ERROR
lzma_index* lzma_index_dup ( const lzma_index i,
lzma_allocator allocator 
)

Duplicate an Index list.

Makes an identical copy of the Index. Also the read position is copied.

Returns:
A copy of the Index, or NULL if memory allocation failed.

References lzma_index_s::current, lzma_index_s::group, lzma_index_s::head, lzma_index_group_s::last, lzma_alloc(), lzma_index_end(), lzma_index_group_s::next, lzma_index_group_s::paddings, lzma_index_group_s::prev, lzma_index_s::tail, lzma_index_group_s::uncompressed_sums, and lzma_index_group_s::unpadded_sums.

lzma_bool lzma_index_equal ( const lzma_index a,
const lzma_index b 
)

Compare if two Index lists are identical.

Read positions are not compared.

Returns:
True if *a and *b are equal, false otherwise.

References lzma_index_group_s::last, lzma_index_group_s::next, lzma_index_group_s::paddings, lzma_index_group_s::uncompressed_sums, and lzma_index_group_s::unpadded_sums.

lzma_ret lzma_index_encoder ( lzma_stream strm,
lzma_index i 
)

Initialize .xz Index encoder.

Parameters:
strm Pointer to properly prepared lzma_stream
i Pointer to lzma_index which should be encoded. The read position will be at the end of the Index after lzma_code() has returned LZMA_STREAM_END.

The only valid action value for lzma_code() is LZMA_RUN.

Returns:
- LZMA_OK: Initialization succeeded, continue with lzma_code().
  • LZMA_MEM_ERROR
  • LZMA_PROG_ERROR

References lzma_next_strm_init, LZMA_OK, and LZMA_RUN.

lzma_ret lzma_index_decoder ( lzma_stream strm,
lzma_index **  i,
uint64_t  memlimit 
)

Initialize .xz Index decoder.

Parameters:
strm Pointer to properly prepared lzma_stream
i Pointer to a pointer that will be made to point to the final decoded Index once lzma_code() has returned LZMA_STREAM_END. That is, lzma_index_decoder() always takes care of allocating a new lzma_index structure, and *i doesn't need to be initialized by the caller.
memlimit How much memory the resulting Index is allowed to require.

The only valid action value for lzma_code() is LZMA_RUN.

Returns:
- LZMA_OK: Initialization succeeded, continue with lzma_code().
  • LZMA_MEM_ERROR
  • LZMA_MEMLIMIT_ERROR
  • LZMA_PROG_ERROR
Note:
The memory usage limit is checked early in the decoding (within the first dozen input bytes or so). The actual memory is allocated later in smaller pieces. If the memory usage limit is modified with lzma_memlimit_set() after a part of the Index has already been decoded, the new limit may get ignored.

References lzma_next_strm_init, LZMA_OK, and LZMA_RUN.

lzma_ret lzma_index_buffer_encode ( lzma_index i,
uint8_t *  out,
size_t *  out_pos,
size_t  out_size 
)

Single-call .xz Index encoder.

Parameters:
i Index to be encoded. The read position will be at the end of the Index if encoding succeeds, or at unspecified position in case an error occurs.
out Beginning of the output buffer
out_pos The next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_size Size of the out buffer; the first byte into which no data is written to is out[out_size].
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_BUF_ERROR: Output buffer is too small. Use lzma_index_size() to find out how much output space is needed.
  • LZMA_PROG_ERROR
Note:
This function doesn't take allocator argument since all the internal data is allocated on stack.

References LZMA_BUF_ERROR, lzma_index_size(), LZMA_OK, LZMA_PROG_ERROR, LZMA_RUN, and LZMA_STREAM_END.

Referenced by lzma_stream_buffer_encode().

lzma_ret lzma_index_buffer_decode ( lzma_index **  i,
uint64_t *  memlimit,
lzma_allocator allocator,
const uint8_t *  in,
size_t *  in_pos,
size_t  in_size 
)

Single-call .xz Index decoder.

Parameters:
i Pointer to a pointer that will be made to point to the final decoded Index if decoding is successful. That is, lzma_index_buffer_decode() always takes care of allocating a new lzma_index structure, and *i doesn't need to be initialized by the caller.
memlimit Pointer to how much memory the resulting Index is allowed to require. The value pointed by this pointer is modified if and only if LZMA_MEMLIMIT_ERROR is returned.
allocator Pointer to lzma_allocator, or NULL to use malloc()
in Beginning of the input buffer
in_pos The next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_size Size of the input buffer; the first byte that won't be read is in[in_size].
Returns:
- LZMA_OK: Decoding was successful.
  • LZMA_MEM_ERROR
  • LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. The minimum required memlimit value was stored to *memlimit.
  • LZMA_DATA_ERROR
  • LZMA_PROG_ERROR

References lzma_coder_s::count, LZMA_DATA_ERROR, lzma_index_end(), lzma_index_memusage(), LZMA_OK, LZMA_PROG_ERROR, LZMA_RUN, LZMA_STREAM_END, and return_if_error.


Generated on Mon Dec 21 22:54:40 2009 for XZ Utils by  doxygen 1.6.1