SqshFileIterator Struct Reference

An iterator over the contents of a file. More...

#include <sqsh_file_private.h>

Public Member Functions
SQSH_NO_UNUSED struct SqshFileIterator *	sqsh_file_iterator_new (const struct SqshFile *file, int *err)
	Creates a new SqshFileIterator struct and initializes it.
SQSH_NO_UNUSED bool	sqsh_file_iterator_next (struct SqshFileIterator *iterator, size_t desired_size, int *err)
	Reads a certain amount of data from the file iterator.
SQSH_NO_UNUSED bool	sqsh_file_iterator_is_zero_block (const struct SqshFileIterator *iterator)
	Checks if the current block is a zero block.
SQSH_NO_UNUSED int	sqsh_file_iterator_skip (struct SqshFileIterator *iterator, sqsh_index_t *offset, size_t desired_size)
	Skips blocks until the block containing the offset is reached. Note that calling this function will invalidate the data pointer returned by sqsh_file_iterator_data().
SQSH_NO_UNUSED int	sqsh_file_iterator_skip2 (struct SqshFileIterator *iterator, uint64_t *offset, size_t desired_size)
	Skips blocks until the block containing the offset is reached. Note that calling this function will invalidate the data pointer returned by sqsh_file_iterator_data().
SQSH_NO_UNUSED const uint8_t *	sqsh_file_iterator_data (const struct SqshFileIterator *iterator)
	Gets a pointer to the current data in the file iterator.
SQSH_NO_UNUSED size_t	sqsh_file_iterator_block_size (const struct SqshFileIterator *iterator)
	Returns the block size of the file iterator.
SQSH_NO_UNUSED size_t	sqsh_file_iterator_size (const struct SqshFileIterator *iterator)
	Gets the size of the data currently in the file iterator.
int	sqsh_file_iterator_free (struct SqshFileIterator *iterator)
	Frees the resources used by a SqshFileIterator struct.

Detailed Description

An iterator over the contents of a file.

Definition at line 126 of file sqsh_file_private.h.

Member Function Documentation

sqsh_file_iterator_block_size()

SQSH_NO_UNUSED size_t sqsh_file_iterator_block_size

(

const struct SqshFileIterator *

iterator

)

Returns the block size of the file iterator.

Parameters

[in]

iterator

The file iterator to get the size from.

Returns

The size of the data currently in the file iterator.

sqsh_file_iterator_data()

SQSH_NO_UNUSED const uint8_t * sqsh_file_iterator_data

(

const struct SqshFileIterator *

iterator

)

Gets a pointer to the current data in the file iterator.

Parameters

[in]

iterator

The file iterator to get data from.

Returns

A pointer to the current data in the file iterator.

sqsh_file_iterator_free()

int sqsh_file_iterator_free

(

struct SqshFileIterator *

iterator

)

Frees the resources used by a SqshFileIterator struct.

Parameters

[in,out]

iterator

The file iterator to free.

Returns

0 on success, less than 0 on error.

sqsh_file_iterator_is_zero_block()

SQSH_NO_UNUSED bool sqsh_file_iterator_is_zero_block

(

const struct SqshFileIterator *

iterator

)

Checks if the current block is a zero block.

Parameters

[in]

iterator

The file iterator to check.

Returns

true if the current block is a zero block, false otherwise.

sqsh_file_iterator_new()

SQSH_NO_UNUSED struct SqshFileIterator * sqsh_file_iterator_new	(	const struct SqshFile *	file,
		int *	err )

Creates a new SqshFileIterator struct and initializes it.

Parameters

[in]	file	The file context to retrieve the file contents from.
[out]	err	Pointer to an int where the error code will be stored.

Returns

A pointer to the newly created and initialized SqshFileIterator struct.

sqsh_file_iterator_next()

SQSH_NO_UNUSED bool sqsh_file_iterator_next	(	struct SqshFileIterator *	iterator,
		size_t	desired_size,
		int *	err )

Reads a certain amount of data from the file iterator.

Parameters

[in,out]	iterator	The file iterator to read data from.
[in]	desired_size	The desired size of the data to read. May be more or less than the actual size of the data read.
[out]	err	Pointer to an int where the error code will be stored.

Return values

true	When the iterator was advanced
false	When the iterator is at the end and no more entries are available or if an error occured.

sqsh_file_iterator_size()

SQSH_NO_UNUSED size_t sqsh_file_iterator_size

(

const struct SqshFileIterator *

iterator

)

Gets the size of the data currently in the file iterator.

Parameters

[in]

iterator

The file iterator to get the size from.

Returns

The size of the data currently in the file iterator.

sqsh_file_iterator_skip()

SQSH_NO_UNUSED int sqsh_file_iterator_skip	(	struct SqshFileIterator *	iterator,
		sqsh_index_t *	offset,
		size_t	desired_size )

Skips blocks until the block containing the offset is reached. Note that calling this function will invalidate the data pointer returned by sqsh_file_iterator_data().

Deprecated

Since 1.5.0. Use sqsh_file_iterator_skip2() instead.

The offset is relative to the beginning of the current block or, if the iterator hasn't been forwarded with previous calls to sqsh_file_iterator_skip() or sqsh_file_iterator_next() the beginning of the first block.

After calling this function offset is updated to the same position relative to the new block. See this visualisation:

current_block: |<--- block 8000 --->|
                          offset = 10000 --^
-->  sqsh_file_iterator_skip(i, &offset, 1)
current_block:                      |<--- block 8000 --->|
                           offset = 2000 --^

If libsqsh can map more than one block at once, it will do so until desired_size is reached. Note that desired_size is only a hint and libsqsh may return more or less data than requested.

Parameters

[in,out]	iterator	The file iterator to skip data in.
[in,out]	offset	The offset that is contained in the block to skip to.
[in]	desired_size	The desired size of the data to read.

Returns

0 on success, less than 0 on error.

sqsh_file_iterator_skip2()

SQSH_NO_UNUSED int sqsh_file_iterator_skip2	(	struct SqshFileIterator *	iterator,
		uint64_t *	offset,
		size_t	desired_size )

Skips blocks until the block containing the offset is reached. Note that calling this function will invalidate the data pointer returned by sqsh_file_iterator_data().

The offset is relative to the beginning of the current block or, if the iterator hasn't been forwarded with previous calls to sqsh_file_iterator_skip() or sqsh_file_iterator_next() the beginning of the first block.

After calling this function offset is updated to the same position relative to the new block. See this visualisation:

current_block: |<--- block 8000 --->|
                          offset = 10000 --^
-->  sqsh_file_iterator_skip(i, &offset, 1)
current_block:                      |<--- block 8000 --->|
                           offset = 2000 --^

If libsqsh can map more than one block at once, it will do so until desired_size is reached. Note that desired_size is only a hint and libsqsh may return more or less data than requested.

Parameters

[in,out]	iterator	The file iterator to skip data in.
[in,out]	offset	The offset that is contained in the block to skip to.
[in]	desired_size	The desired size of the data to read.

Returns

0 on success, less than 0 on error.

---

The documentation for this struct was generated from the following files:

• libsqsh/include/sqsh_file_private.h
• include/sqsh_file.h