summaryrefslogtreecommitdiff
path: root/include/sqfs/meta_reader.h
diff options
context:
space:
mode:
authorDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-09-09 23:11:03 +0200
committerDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-09-09 23:12:08 +0200
commitc17de5d4c2699c6c5b4759f009ce8cb6560d2f13 (patch)
treeca36c1af536583856360dd6e905fe7143ee5a562 /include/sqfs/meta_reader.h
parent524869a644004b2b5eae9c6cdb14a20c0e877778 (diff)
Add doxygen annotations to all public headers
Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>
Diffstat (limited to 'include/sqfs/meta_reader.h')
-rw-r--r--include/sqfs/meta_reader.h142
1 files changed, 129 insertions, 13 deletions
diff --git a/include/sqfs/meta_reader.h b/include/sqfs/meta_reader.h
index 1a9e869..989e857 100644
--- a/include/sqfs/meta_reader.h
+++ b/include/sqfs/meta_reader.h
@@ -22,46 +22,162 @@
#include "sqfs/predef.h"
+/**
+ * @file meta_reader.h
+ *
+ * @brief Contains declarations for the @ref sqfs_meta_reader_t.
+ */
+
+/**
+ * @struct sqfs_meta_reader_t
+ *
+ * @brief Abstracts reading of meta data blocks.
+ *
+ * SquashFS stores meta data by dividing it into fixed size (8k) chunks
+ * that are written to disk with a small header indicating the on-disk
+ * size and whether it is compressed or not.
+ *
+ * Data written to meta data blocks doesn't have to be alligned, i.e.
+ * SquashFS doesn't care if an object is written across two blocks.
+ *
+ * The main task of the meta data read is to provide a simple read and seek
+ * functions that transparently take care of fetching and uncompressing blocks
+ * from disk and reading transparently across block boarders if required.
+ */
+
#ifdef __cplusplus
extern "C" {
#endif
-/* Create a meta data reader using a given compressor to extract data.
- Internally prints error message to stderr on failure.
-
- Start offset and limit can be specified to do bounds checking against
- a subregion of the filesystem image.
-*/
+/**
+ * @brief Create a meta data reader
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * @param file A pointer to a file object to read from
+ * @param cmp A compressor to use for unpacking compressed meta data blocks
+ * @param start A lower limit for the blocks to be read. Every seek to an offset
+ * below that is interpreted as an out-of-bounds read.
+ * @param limit An upper limit for the blocks to read. Every seek to an offset
+ * afer that is interpreted as an out-of-bounds read.
+ *
+ * @return A pointer to a meta data reader on success, NULL on
+ * allocation failure.
+ */
SQFS_API sqfs_meta_reader_t *sqfs_meta_reader_create(sqfs_file_t *file,
sqfs_compressor_t *cmp,
uint64_t start,
uint64_t limit);
+/**
+ * @brief Destroy a meta data reader and free all memory used by it.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * @param m A pointer to a meta data reader.
+ */
SQFS_API void sqfs_meta_reader_destroy(sqfs_meta_reader_t *m);
-/* Returns 0 on success. Internally prints to stderr on failure */
+/**
+ * @brief Seek to a specific meta data block and offset.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * The underlying block is fetched from disk and uncompressed, unless it
+ * already is the current block.
+ *
+ * @param m A pointer to a meta data reader.
+ * @param block_start Absolute position where the block header can be found.
+ * @param offset A byte offset into the uncompressed block.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
SQFS_API int sqfs_meta_reader_seek(sqfs_meta_reader_t *m, uint64_t block_start,
size_t offset);
+/**
+ * @brief Get the current position that the next read will read from.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * @param m A pointer to a meta data reader.
+ * @param block_start Absolute position where the current block is.
+ * @param offset A byte offset into the uncompressed block.
+ */
SQFS_API void sqfs_meta_reader_get_position(sqfs_meta_reader_t *m,
uint64_t *block_start,
size_t *offset);
-/* Returns 0 on success. Internally prints to stderr on failure */
+/**
+ * @brief Read a chunk of data from a meta data reader.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * If the meta data reader reaches the end of the current block before filling
+ * the destination buffer, it transparently reads the next block from disk and
+ * uncompresses it.
+ *
+ * @param m A pointer to a meta data reader.
+ * @param data A pointer to copy the data to.
+ * @param size The numbre of bytes to read.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
SQFS_API int sqfs_meta_reader_read(sqfs_meta_reader_t *m, void *data,
size_t size);
-/* Returns 0 on success. Internally prints to stderr on failure */
+/**
+ * @brief Read and decode a directory header from a meta data reader.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * This is a convenience function on to of @ref sqfs_meta_reader_read that
+ * reads and decodes a directory header from a meta data block.
+ *
+ * @param m A pointer to a meta data reader.
+ * @param hdr A pointer to a directory header to fill.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
SQFS_API int sqfs_meta_reader_read_dir_header(sqfs_meta_reader_t *m,
sqfs_dir_header_t *hdr);
-/* Entry can be freed with a single free() call.
- The function internally prints to stderr on failure */
+/**
+ * @brief Read and decode a directory header from a meta data reader.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * This is a convenience function on to of @ref sqfs_meta_reader_read that
+ * reads and decodes a directory entry.
+ *
+ * @param m A pointer to a meta data reader.
+ * @param ent Returns a pointer to a directory entry. Can be released with a
+ * single free() call.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
SQFS_API int sqfs_meta_reader_read_dir_ent(sqfs_meta_reader_t *m,
sqfs_dir_entry_t **ent);
-/* Inode can be freed with a single free() call.
- The function internally prints error message to stderr on failure. */
+/**
+ * @brief Read and decode an inode from a meta data reader.
+ *
+ * @memberof sqfs_meta_reader_t
+ *
+ * This is a convenience function on to of @ref sqfs_meta_reader_seek and
+ * @ref sqfs_meta_reader_read that reads and decodes an inode.
+ *
+ * @param ir A pointer to a meta data reader.
+ * @param super A pointer to the super block, required for figuring out the
+ * size of file inodes.
+ * @param block_start The meta data block to seek to for reading the inode.
+ * @param offset A byte offset within the uncompressed block where the
+ * inode is.
+ * @param out Returns a pointer to an inode. Can be released with a
+ * single free() call.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
SQFS_API
int sqfs_meta_reader_read_inode(sqfs_meta_reader_t *ir, sqfs_super_t *super,
uint64_t block_start, size_t offset,