aboutsummaryrefslogtreecommitdiff
path: root/include/sqfs/meta_writer.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/sqfs/meta_writer.h')
-rw-r--r--include/sqfs/meta_writer.h143
1 files changed, 130 insertions, 13 deletions
diff --git a/include/sqfs/meta_writer.h b/include/sqfs/meta_writer.h
index b3da355..c0d5716 100644
--- a/include/sqfs/meta_writer.h
+++ b/include/sqfs/meta_writer.h
@@ -22,42 +22,159 @@
#include "sqfs/predef.h"
+/**
+ * @file meta_writer.h
+ *
+ * @brief Contains declarations for the @ref sqfs_meta_writer_t.
+ */
+
+/**
+ * @struct sqfs_meta_writer_t
+ *
+ * @brief Abstracts generating of meta data blocks, either in memory or
+ * directly on disk.
+ *
+ * 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 writer is to provide a simple append
+ * function that transparently takes care of chopping data up into blocks,
+ * compressing the blocks and pre-pending a header.
+ */
+
#ifdef __cplusplus
extern "C" {
#endif
-/* Create a meta data reader using a given compressor to compress data.
- Internally prints error message to stderr on failure.
- If keep_in_mem is true, the blocks are collected in memory and must
- be explicitly flushed to disk using meta_write_write_to_file.
-*/
+/**
+ * @brief Create a meta data writer.
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * @note The meta writer internally keeps references to the pointers passed
+ * to this function, so don't destroy them before destroying the
+ * meta writer.
+ *
+ * @param file An output file to write the data to.
+ * @param cmp A compressor to use.
+ * @param keep_in_memory Set to true to store the compressed blocks
+ * internally until they are explicilty told
+ * to write them to disk.
+ *
+ * @return A pointer to a meta writer on success, NULL on allocation failure.
+ */
SQFS_API sqfs_meta_writer_t *sqfs_meta_writer_create(sqfs_file_t *file,
sqfs_compressor_t *cmp,
bool keep_in_mem);
+/**
+ * @brief Destroy a meta data writer and free all memory used by it.
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * @param m A pointer to a meta data writer.
+ */
SQFS_API void sqfs_meta_writer_destroy(sqfs_meta_writer_t *m);
-/* Compress and flush the currently unfinished block to disk. Returns 0 on
- success, internally prints error message to stderr on failure */
+/**
+ * @brief Finish the current block, even if it isn't full yet.
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * This function forces the meta writer to compress and store the block it
+ * is currently writing to, even if it isn't full yet, and either write it
+ * out to disk (or append it to the in memory chain if told to keep blocks
+ * in memory).
+ *
+ * @param m A pointer to a meta data writer.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
SQFS_API int sqfs_meta_writer_flush(sqfs_meta_writer_t *m);
-/* Returns 0 on success. Prints error message to stderr on failure. */
+/**
+ * @brief Finish the current block, even if it isn't full yet.
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * This function forces reads a speicifed number of bytes from a given data
+ * block and appends it to the meta data block that the writer is currently
+ * working on. If the block becomes full, it is compressed, written to disk
+ * and a new block is started that the remaining data is written to.
+ *
+ * @param m A pointer to a meta data writer.
+ * @param data A pointer to a chunk of data to append to the writer.
+ * @param size The number of data bytes to append.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
SQFS_API int sqfs_meta_writer_append(sqfs_meta_writer_t *m, const void *data,
size_t size);
-/* Query the current block start position and offset within the block */
+/**
+ * @brief Query the current block start position and offset within the block
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * Get the byte offset relative to the first block that the current block will
+ * start at once it is written to disk and get the byte offset within this
+ * block that the next call to @ref sqfs_meta_writer_append will start writing
+ * data at.
+ *
+ * @param m A pointer to a meta data writer.
+ * @param block_start Returns the offset of the current block from the first.
+ * @param offset Returns an offset into the current block where the next write
+ * starts.
+ */
SQFS_API void sqfs_meta_writer_get_position(const sqfs_meta_writer_t *m,
uint64_t *block_start,
uint32_t *offset);
-/* Reset all internal state, including the current block start position. */
+/**
+ * @brief Reset all internal state, including the current block start position.
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * This functions forces the meta data writer to forget everything that
+ * happened since it was created, so it can be recycled.
+ *
+ * The data written is not lost, unless it was kept in memory and never written
+ * out to disk.
+ */
SQFS_API void sqfs_meta_writer_reset(sqfs_meta_writer_t *m);
-/* If created with keep_in_mem true, write the collected blocks to disk.
- Does not flush the current block. Writes error messages to stderr and
- returns non-zero on failure. */
+/**
+ * @brief Write all blocks collected in memory to disk
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * If the meta writer was created with the flag set to store blocks in
+ * memory instead of writing them to disk, calling this function forces
+ * the meta writer to write out all blocks it collected so far.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
SQFS_API int sqfs_meta_write_write_to_file(sqfs_meta_writer_t *m);
+/**
+ * @brief A convenience function for encoding and writing an inode
+ *
+ * @memberof sqfs_meta_writer_t
+ *
+ * The SquashFS inode table is essentially a series of meta data blocks
+ * containing variable sized inodes. This function takes a generic inode
+ * structure, encodes it and writes the result to a meta data writer
+ * using @ref sqfs_meta_writer_append internally.
+ *
+ * @param iw A pointer to a meta data writer.
+ * @param n A pointer to an inode.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
SQFS_API int sqfs_meta_writer_write_inode(sqfs_meta_writer_t *iw,
sqfs_inode_generic_t *n);