diff options
Diffstat (limited to 'include/sqfs/meta_writer.h')
| -rw-r--r-- | include/sqfs/meta_writer.h | 143 |
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); |