summaryrefslogtreecommitdiff
path: root/include
diff options
context:
space:
mode:
authorDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-05-20 11:56:28 +0200
committerDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-05-20 12:02:53 +0200
commit13cc42ce135155f0437298540b0bc5a821d7a644 (patch)
tree18acd391d928db760a73d8b7c5231899ec7e7812 /include
parentc2e01ed987e942005fa66f11d96b8edb1d930c99 (diff)
cleanup: remove overly excessive comments
Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>
Diffstat (limited to 'include')
-rw-r--r--include/compress.h87
-rw-r--r--include/frag_reader.h61
-rw-r--r--include/fstree.h400
-rw-r--r--include/id_table.h90
-rw-r--r--include/meta_reader.h111
-rw-r--r--include/meta_writer.h59
-rw-r--r--include/squashfs.h3
-rw-r--r--include/str_table.h57
-rw-r--r--include/table.h30
-rw-r--r--include/util.h67
10 files changed, 229 insertions, 736 deletions
diff --git a/include/compress.h b/include/compress.h
index a8542f2..4c1ec8b 100644
--- a/include/compress.h
+++ b/include/compress.h
@@ -11,86 +11,39 @@
typedef struct compressor_t compressor_t;
-/**
- * @struct compressor_t
- *
- * @brief Encapsultes a compressor with a simple interface to compress or
- * uncompress/extract blocks of data
- */
+/* Encapsultes a compressor with a simple interface to compress or
+ uncompress/extract blocks of data. */
struct compressor_t {
- /**
- * @brief Write compressor options to the output file if necessary
- *
- * @param cmp A pointer to the compressor object
- * @param fd The file descriptor to write to
- *
- * @return The number of bytes written or -1 on failure
- */
+ /* Write compressor options to the output file if necessary.
+ Returns the number of bytes written or -1 on failure.
+ Internally prints error messages to stderr. */
int (*write_options)(compressor_t *cmp, int fd);
- /**
- * @brief Read compressor options to the input file
- *
- * @param cmp A pointer to the compressor object
- * @param fd The file descriptor to write to
- *
- * @return Zero on success, -1 on failure
- */
+ /* Read compressor options to the input file.
+ Returns zero on success, -1 on failure.
+ Internally prints error messages to stderr. */
int (*read_options)(compressor_t *cmp, int fd);
- /**
- * @brief Compress or uncompress a chunk of data
- *
- * @param cmp A pointer to the compressor object
- * @param in A pointer to the input buffer
- * @param size The number of bytes in the input buffer to process
- * @param out A pointer to the output buffer
- * @param outsize The number of bytes available in the output buffer
- *
- * @return On success, the number of bytes written to the output
- * buffer, -1 on failure, 0 if the output buffer was too small.
- * The compressor also returns 0 if the compressed result ends
- * up larger than the original input.
- */
+ /*
+ Compress or uncompress a chunk of data.
+
+ Returns the number of bytes written to the output buffer, -1 on
+ failure or 0 if the output buffer was too small.
+ The compressor also returns 0 if the compressed result ends
+ up larger than the original input.
+
+ Internally prints compressor specific error messages to stderr.
+ */
ssize_t (*do_block)(compressor_t *cmp, const uint8_t *in, size_t size,
uint8_t *out, size_t outsize);
- /**
- * @brief Destroy a compressor object and free up all memory it uses
- *
- * @param cmp A pointer to the compressor object
- */
void (*destroy)(compressor_t *stream);
};
-/**
- * @brief Check if a given compressor is available
- *
- * @memberof compressor_t
- *
- * This function checks if a given compressor is available, since some
- * compressors may not be supported yet, or simply disabled in the
- * compile configuration.
- *
- * @param id A SquashFS compressor id
- *
- * @return true if the given compressor is available
- */
bool compressor_exists(E_SQFS_COMPRESSOR id);
-/**
- * @brief Create a compressor object
- *
- * @memberof compressor_t
- *
- * @param id A SquashFS compressor id
- * @param compress true if the resulting object should compress data, false
- * if it should actually extract already compressed blocks.
- * @param block_size The configured block size for the SquashFS image. May be
- * of interest to some compressors.
- *
- * @return A pointer to a new compressor object or NULL on failure.
- */
+/* block_size is the configured block size for the SquashFS image. Needed
+ by some compressors to set internal defaults. */
compressor_t *compressor_create(E_SQFS_COMPRESSOR id, bool compress,
size_t block_size);
diff --git a/include/frag_reader.h b/include/frag_reader.h
index 8a3d4cc..623cc8d 100644
--- a/include/frag_reader.h
+++ b/include/frag_reader.h
@@ -8,11 +8,7 @@
#include <stdint.h>
#include <stddef.h>
-/**
- * @struct frag_reader_t
- *
- * @brief A simple interface for accessing fragments in a SquashFS image
- */
+/* A simple interface for accessing fragments in a SquashFS image */
typedef struct {
sqfs_fragment_t *tbl;
size_t num_fragments;
@@ -25,51 +21,26 @@ typedef struct {
uint8_t buffer[];
} frag_reader_t;
-/**
- * @brief Create a fragment reader
- *
- * @memberof frag_reader_t
- *
- * This function internally reads and decodes the fragment table from the
- * image and prints error messages to stderr on the way if it fails.
- *
- * @param super A pointer to the SquashFS super block read from the image
- * @param fd A file descriptor of opened the SquashFS image
- * @param cmp A pointer to a compressor object to be used for reading meta
- * data blocks from the image.
- *
- * @return A pointer to a new fragment reader or NULL on failure
- */
+/* Reads and decodes the fragment table from the image. Cleans up after itself
+ and prints error messages to stderr on the way if it fails. */
frag_reader_t *frag_reader_create(sqfs_super_t *super, int fd,
compressor_t *cmp);
-/**
- * @brief Destroy a fragment reader and free all memory it uses
- *
- * @memberof frag_reader_t
- *
- * @param f A pointer to a fragment reader object
- */
void frag_reader_destroy(frag_reader_t *f);
-/**
- * @brief Read tail-end packed data from a fragment
- *
- * @memberof frag_reader_t
- *
- * This function internally takes care of loading and uncompressing the
- * fragment block (which is skipped if it has already been loaded earlier).
- * It prints error messages to stderr on the way if it fails, including such
- * errors as trying to index beyond the fragment table.
- *
- * @param f A pointer to a fragment reader object
- * @param index A fragment index such as stored in an inode
- * @param offset A byte offset into the fragment block addressed by the index
- * @param buffer A pointer to a destination buffer to copy decoded data to
- * @param size The number of bytes to copy into the destination buffer
- *
- * @return Zero on success, -1 on failure
- */
+/*
+ Read data from a fragment.
+
+ The function takes care of loading and uncompressing the fragment block
+ (which is skipped if it has already been loaded earlier).
+
+ `index` is a fragment index from an inode, `offset` is a byte offset into
+ the fragment block and `size` is the number of bytes to copy into the
+ destination buffer.
+
+ Returns 0 on success. Prints error messages to stderr on failure (including
+ index out of bounds).
+*/
int frag_reader_read(frag_reader_t *f, size_t index, size_t offset,
void *buffer, size_t size);
diff --git a/include/fstree.h b/include/fstree.h
index 4986ec2..27cb39d 100644
--- a/include/fstree.h
+++ b/include/fstree.h
@@ -19,238 +19,146 @@ typedef struct dir_info_t dir_info_t;
typedef struct fstree_t fstree_t;
typedef struct tree_xattr_t tree_xattr_t;
-/**
- * @struct tree_xattr_t
- *
- * @brief Encapsulates a set of key-value pairs attached to a @ref tree_node_t
- */
+/* Encapsulates a set of key-value pairs attached to a tree_node_t */
struct tree_xattr_t {
+ /* Number of key-value pairs */
size_t num_attr;
+
+ /* Total size of the array, i.e. it's capacity */
size_t max_attr;
+ /* Offset of the meta data block where the pairs are stored */
uint64_t block;
+
+ /* Offset into a meta data block where the pairs start */
uint32_t offset;
+
+ /* Number of bytes written to disk */
uint32_t size;
- /**
- * @brief Incremental index within all xattr blocks
- */
+ /* Incremental index within all xattr blocks */
size_t index;
- /**
- * @brief Back reference to the tree node this was created for
- */
+ /* Back reference to the tree node this was created for */
tree_node_t *owner;
- /**
- * @brief linked list pointer of list of attributes in @ref fstree_t
- */
+ /* linked list pointer of list of attributes in @ref fstree_t */
tree_xattr_t *next;
- /**
- * @brief An array with pairs of key-value tupples
- *
- * Each key-value tupple is encoded as (key << 32) | value.
- */
+ /* Array with pairs of key-value tupples.
+ Each key-value tupple is encoded as (key << 32) | value. */
uint64_t ref[];
};
-/**
- * @struct file_info_t
- *
- * @brief Additional meta data stored in a @ref tree_node_t for regular files
- */
+/* Additional meta data stored in a tree_node_t for regular files. */
struct file_info_t {
+ /* Path to the input file. */
char *input_file;
- /**
- * @brief Linked list pointer for aggregating fragments
- *
- * When writing out data blocks, files that don't have a multiple of
- * the block size have their tail ends gathered in a fragment block.
- * A linked list is used to keep track of which files share the same
- * fragment block.
- */
+ /* Linked list pointer for aggregating fragments
+
+ When writing out data blocks, files that don't have a multiple of
+ the block size have their tail ends gathered in a fragment block.
+ A linked list is used to keep track of which files share the same
+ fragment block. */
file_info_t *frag_next;
- /**
- * @brief Total size of the file in bytes
- */
uint64_t size;
- /**
- * @brief Absolute position of the first data block
- */
+ /* Absolute position of the first data block. */
uint64_t startblock;
- /**
- * @brief Fragment index
- *
- * If the size is not a multiple of the block size, this holds an
- * index into the fragment table.
- */
+ /* If the size is not a multiple of the block size, this holds an
+ index into the fragment table. */
uint32_t fragment;
- /**
- * @brief Byte offset into the fragment block
- *
- * If the size is not a multiple of the block size, this holds an
- * offset into the fragment block.
- */
+ /* Byte offset into the fragment block. */
uint32_t fragment_offset;
- /**
- * @brief Stores the compressed file block sizes
- *
- * For each full data block, stores the compressed size. Bit number
- * 24 is set if the block is stored uncompressed.
- */
+ /* For each full data block, stores the compressed size.
+ Bit (1 << 24) is set if the block is stored uncompressed. */
uint32_t blocksizes[];
};
-/**
- * @struct dir_info_t
- *
- * @brief Additional meta data stored in a @ref tree_node_t for directories
- */
+/* Additional meta data stored in a tree_node_t for directories */
struct dir_info_t {
- /**
- * @brief Pointer to the head of the linked list of children
- */
+ /* Linked list head for children in the directory */
tree_node_t *children;
- /**
- * @brief Size of the directory
- *
- * Computed and updated on the fly while writing directory
- * meta data to disk.
- */
+ /* Size on disk. Computed and updated on the fly while writing
+ directory meta data to disk. */
uint64_t size;
- /**
- * @brief Start block offset, relative to directory table start
- *
- * Offset of the compressed meta data block where the directory
- * listing is stored in the SquashFS image.
- */
+ /* Start block offset, relative to directory table start. */
uint64_t start_block;
- /**
- * @brief Byte offset into the uncompressed meta data block
- *
- * Points at where in the meta data block the directory listing begins.
- */
+ /* Byte offset into the uncompressed meta data block. */
uint32_t block_offset;
- /**
- * @brief Set to true for implicitly generated directories
- */
+ /* Set to true for implicitly generated directories. */
bool created_implicitly;
};
-/**
- * @struct tree_node_t
- *
- * @brief A node in a file system tree
- */
+/* A node in a file system tree */
struct tree_node_t {
- /**
- * @brief Linked list pointer to the next node in the same directory
- */
+ /* Parent directory children linked list pointer. */
tree_node_t *next;
- /**
- * @brief Pointer to directory node that this node is in
- *
- * This is NULL only for the root node
- */
+ /* Root node has this set to NULL. */
tree_node_t *parent;
- /**
- * @brief Pointer into the payload area where the node name is stored
- *
- * For the root node, this points to an empty string
- */
+ /* For the root node, this points to an empty string. */
char *name;
- /**
- * @brief A pointer to an extended attribute array or NULL if unused
- */
+ /*
+ A pointer to an extended attribute array or NULL if unused.
+
+ This field is not stored in-line and taken care of by the generic
+ fstree cleanup code, since it is generatde after the tree already
+ exists and shared across multiple nodes.
+ */
tree_xattr_t *xattr;
uint32_t uid;
uint32_t gid;
uint16_t mode;
- /**
- * @brief SquashFS inode refernce number
- *
- * This is computed and stored here on the fly when writing inodes
- * generated from tree nodes to the SquashFS image.
- *
- * An inode reference is the 32 bit offset of the compressed meta data
- * block, shifted left by 16 and ored with a 13 bit offset into the
- * uncompressed meta data block.
- */
+ /* SquashFS inode refernce number. 32 bit offset of the meta data
+ block start (relative to inode table start), shifted left by 16
+ and ored with a 13 bit offset into the uncompressed meta data block.
+
+ Generated on the fly when writing inodes. */
uint64_t inode_ref;
- /**
- * @brief inode number
- *
- * This is computed and stored here on the fly when writing inodes
- * generated from tree nodes to the SquashFS image.
- */
+ /* Inode number. Generated on the fly when writing inodes. */
uint32_t inode_num;
- /**
- * @brief SquashFS inode type used for this tree node
- *
- * This is computed and stored here on the fly when writing inodes
- * generated from tree nodes to the SquashFS image. It can't be
- * easily determined in advance since it depends also on the size
- * of the node, which means for directories the size of the directory
- * entries once written to disk.
- *
- * All code that actually processes tree nodes should use the mode
- * field instead (mode & S_IFMT gives us the node type). It is stored
- * here when generating inodes since we need it later on to generate
- * directory entries.
- */
+ /* SquashFS inode type used for this tree node.
+
+ Generated on the fly when writing inodes. It can't be easily
+ determined in advance since it depends also on the size of the
+ node, which means for directories the size of the directory
+ entries once written to disk.
+
+ All code that actually processes tree nodes should use the mode
+ field instead (mode & S_IFMT gives us the node type). It is stored
+ here when generating inodes since we need it later on to generate
+ directory entries.
+ */
int type;
+ /* Type specific data. Pointers are into payload area blow. */
union {
- /**
- * @brief Pointer into payload area storing directory meta data
- */
dir_info_t *dir;
-
- /**
- * @brief Pointer into payload area storing file meta data
- */
file_info_t *file;
-
- /**
- * @brief Pointer into payload area storing symlink target
- */
char *slink_target;
-
- /**
- * @brief A device number for device special files
- */
uint64_t devno;
} data;
- /**
- * @brief Additional data stored in the tree node
- */
uint8_t payload[];
};
-/**
- * @struct fstree_t
- *
- * @brief Encapsulates a file system tree
- */
+/* Encapsulates a file system tree */
struct fstree_t {
uint32_t default_uid;
uint32_t default_gid;
@@ -265,157 +173,81 @@ struct fstree_t {
tree_xattr_t *xattr;
};
-/**
- * @brief Initialize an fstree object
- *
- * @memberof fstree_t
- *
- * Initializing means copying over the default values and creating a root node.
- * On error, an error message is written to stderr.
- *
- * @param fs A pointer to an uninitialized fstree object
- * @param block_size The data block size for regular files
- * @param mtime Default modification time stamp to use on all nodes
- * @param default_mode Default permission bits to use on implicitly created
- * directories.
- * @param default_uid Default UID to set on implicitly created directories.
- * @param default_gid Default GID to set on implicitly created directories.
- *
- * @return Zero on success, -1 on failure
- */
+/*
+ Initializing means copying over the default values and creating a root node.
+ On error, an error message is written to stderr.
+
+ `block_size` is the the data block size for regular files.
+
+ Returns 0 on success.
+*/
int fstree_init(fstree_t *fs, size_t block_size, uint32_t mtime,
uint16_t default_mode, uint32_t default_uid,
uint32_t default_gid);
-/**
- * @brief Clean up an fstree object and free all memory it uses
- *
- * @memberof fstree_t
- *
- * This function also recursively frees all tree nodes.
- *
- * @param fs A pointer to an fstree object
- */
void fstree_cleanup(fstree_t *fs);
-/**
- * @brief Add a generic node to an fstree object
- *
- * @memberof fstree_t
- *
- * The new node is inserted by path. If some components of the path don't
- * exist, they are created as directories with default permissions, like
- * mkdir -p would, and marked as implcitily created. A subsequent call that
- * tries to create an existing tree node will fail, except if the target
- * is an implicitly created directory node and the call tries to create it
- * as a directory. This will simply overwrite the permissions and ownership.
- * The implicitly created flag is then cleared and subsequent attempts to
- * create this directory again will also fail.
- *
- * This function does not print anything to stderr, instead it sets an
- * appropriate errno value.
- *
- * @param fs A pointer to an fstree object
- * @param path The path of the new object to insert
- * @param mode Specifies both access permission and what kind of node
- * to create
- * @param uid The user id that owns the new node
- * @param gid The group id that owns the new node
- * @param extra_len An additional number of bytes to allocate for payload data
- *
- * @return A pointer to the new tree node or NULL on failure
- */
+/*
+ Add a generic node to an fstree.
+
+ The new node is inserted by path. If some components of the path don't
+ exist, they are created as directories with default permissions, like
+ mkdir -p would, and marked as implcitily created. A subsequent call that
+ tries to create an existing tree node will fail, except if the target
+ is an implicitly created directory node and the call tries to create it
+ as a directory (this will simply overwrite the permissions and ownership).
+ The implicitly created flag is then cleared. Subsequent attempts to create
+ an existing directory again will then also fail.
+
+ This function does not print anything to stderr, instead it sets an
+ appropriate errno value.
+
+ `extra_len` specifies an additional number of bytes to allocate for payload
+ data in the tree node.
+*/
tree_node_t *fstree_add(fstree_t *fs, const char *path, uint16_t mode,
uint32_t uid, uint32_t gid, size_t extra_len);
-/**
- * @brief A wrappter around @ref fstree_add for regular files
- *
- * @memberof fstree_t
- *
- * This function internally computes the number of extra payload bytes
- * requiered and sets up the payload pointers propperly, as they are
- * different than for other types of nodes.
- *
- * @return A pointer to the new tree node or NULL on failure
- */
+/*
+ A wrappter around fstree_add for regular files.
+
+ This function internally computes the number of extra payload bytes
+ requiered and sets up the payload pointers propperly.
+*/
tree_node_t *fstree_add_file(fstree_t *fs, const char *path, uint16_t mode,
uint32_t uid, uint32_t gid, uint64_t filesz,
const char *input);
-/**
- * @brief Add an extended attribute key value pair to a tree node
- *
- * @memberof fstree_t
- *
- * @param fs A pointer to the fstree object
- * @param node A pointer to the tree node to attach attributes to
- * @param key The xattr key with namespace prefix
- * @param value The xattr value string
- *
- * @return Zero on success, -1 on failure (prints error to stderr)
- */
+/*
+ Add an extended attribute key value pair to a tree node.
+
+ Returns 0 on success, prints error to stderr on failure.
+*/
int fstree_add_xattr(fstree_t *fs, tree_node_t *node,
const char *key, const char *value);
-/**
- * @brief Recompute index number of all xattr blocks
- *
- * @memberof fstree_t
- *
- * @param fs A pointer to the fstree object
- */
+/* Recompute running index number of all xattr blocks. */
void fstree_xattr_reindex(fstree_t *fs);
-/**
- * @brief Remove dupliciate xattr listings
- *
- * @memberof fstree_t
- *
- * If two tree nodes have pointers to distinct @ref tree_xattr_t listings that
- * turn out to be equivalent, throw one of the two away and make both nodes
- * point to the same instance.
- */
+/* Sort and dedupliciate xattr blocks, then recumpute the index numbers. */
void fstree_xattr_deduplicate(fstree_t *fs);
-/**
- * @brief Load an fstree from a text file describing it
- *
- * @memberof fstree_t
- *
- * This function parses the file format accepted by gensquashfs and restores
- * a file system tree from it.
- *
- * On failure, an error report with filename and line number is written
- * to stderr.
- *
- * @param fs A pointer to an fstree object that is already initialized
- * prior to calling this function.
- * @param filename The path to the input file to process.
- *
- * @return Zero on success, -1 on failure.
+/*
+ Parses the file format accepted by gensquashfs and produce a file system
+ tree from it.
+
+ On failure, an error report with filename and line number is written
+ to stderr.
+
+ Returns 0 on success.
*/
int fstree_from_file(fstree_t *fs, const char *filename);
-/**
- * @brief Lexicographically sort all directory contents
- *
- * @memberof fstree_t
- *
- * @param fs A pointer to an fstree object
- */
+/* Lexicographically sort all directory contents. */
void fstree_sort(fstree_t *fs);
-/**
- * @brief Add labels from an SELinux labeling file to all tree nodes
- *
- * @memberof fstree_t
- *
- * @param fs A pointer to an fstree object
- * @param filename The name of the SELinux context file
- *
- * @return Zero on success, -1 on failure
- */
+/* Add labels from an SELinux labeling file to all tree nodes.
+ Returns 0 on success. Internally prints errors to stderr. */
int fstree_relabel_selinux(fstree_t *fs, const char *filename);
#endif /* FSTREE_H */
diff --git a/include/id_table.h b/include/id_table.h
index 788519c..911c829 100644
--- a/include/id_table.h
+++ b/include/id_table.h
@@ -7,101 +7,35 @@
#include "compress.h"
-/**
- * @struct id_table_t
- *
- * @brief Encapsulates the ID table used by SquashFS
- */
+/* Encapsulates the ID table used by SquashFS */
typedef struct {
- /**
- * @brief Array of unique 32 bit IDs
- */
+ /* Array of unique 32 bit IDs */
uint32_t *ids;
- /**
- * @brief Number of 32 bit IDs stored in the array
- */
+ /* Number of 32 bit IDs stored in the array */
size_t num_ids;
- /**
- * @brief Actual size of the array, i.e. maximum available
- */
+ /* Actual size of the array, i.e. maximum available */
size_t max_ids;
} id_table_t;
-/**
- * @brief Initialize an ID table
- *
- * @memberof id_table_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * @param tbl A pointer to an uninitialized ID table
- *
- * @return Zero on success, -1 on failure
- */
+/* Returns 0 on success. Prints error message to stderr on failure. */
int id_table_init(id_table_t *tbl);
-/**
- * @brief Cleanup and free an ID table
- *
- * @memberof id_table_t
- *
- * @param tbl A pointer to an ID table
- */
void id_table_cleanup(id_table_t *tbl);
-/**
- * @brief Resolve a 32 bit to a 16 bit table index
- *
- * @memberof id_table_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * @param tbl A pointer to an ID table
- * @param id A 32 bit ID to resolve
- * @param out Returns the 16 bit table index
- *
- * @return Zero on success, -1 on failure
- */
+/* Resolve a 32 bit to a 16 bit table index.
+ Returns 0 on success. Internally prints errors to stderr. */
int id_table_id_to_index(id_table_t *tbl, uint32_t id, uint16_t *out);
-/**
- * @brief Write an ID table to a SquashFS image
- *
- * @memberof id_table_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * @param tbl A pointer to an ID table
- * @param outfd A file descriptor to write the data to
- * @param super A pointer to the SquashFS super block to store the ID table
- * offset in
- * @param cmp A pointer to the compressor to use for compressing the ID
- * table meta data blocks
- *
- * @return Zero on success, -1 on failure
- */
+/* Write an ID table to a SquashFS image.
+ Returns 0 on success. Internally prints error message to stderr. */
int id_table_write(id_table_t *tbl, int outfd, sqfs_super_t *super,
compressor_t *cmp);
-/**
- * @brief Read an ID table from a SquashFS image
- *
- * @memberof id_table_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * @param tbl A pointer to an ID table
- * @param fd A file descriptor to read the data from
- * @param super A pointer to the SquashFS super block that tells us where
- * the ID table is stored
- * @param cmp A pointer to the compressor to use for extracting the ID
- * table meta data blocks
- *
- * @return Zero on success, -1 on failure
- */
+/* Read an ID table from a SquashFS image.
+ Returns 0 on success. Internally prints error messages to stderr. */
int id_table_read(id_table_t *tbl, int fd, sqfs_super_t *super,
- compressor_t *cmp);
+ compressor_t *cmp);
#endif /* ID_TABLE_H */
diff --git a/include/meta_reader.h b/include/meta_reader.h
index a662959..16003f6 100644
--- a/include/meta_reader.h
+++ b/include/meta_reader.h
@@ -7,124 +7,31 @@
typedef struct meta_reader_t meta_reader_t;
-/**
- * @brief Create a meta data reader
- *
- * @memberof meta_reader_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * @param fd The underlying file descriptor to read from
- * @param cmp A pointer to a compressor to use for extracting the data
- *
- * @return A pointer to a meta data reader, NULL on failure
- */
+/* Create a meta data reader using a given compressor to extract data.
+ Internally prints error message to stderr on failure. */
meta_reader_t *meta_reader_create(int fd, compressor_t *cmp);
-/**
- * @brief Destroy a meta data reader and free all memory used by it
- *
- * @memberof meta_reader_t
- *
- * @param m A pointer to a meta data reader
- */
void meta_reader_destroy(meta_reader_t *m);
-/**
- * @brief Seek to a specific meta data block and offset
- *
- * @memberof meta_reader_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * @param m A pointer to a meta data reader
- * @param block_start The absolute position of the 16 bit header right before
- * the compressed data block
- * @param offset A byte offset into the data block
- *
- * @return Zero on success, -1 on failure
- */
+/* Returns 0 on success. Internally prints to stderr on failure */
int meta_reader_seek(meta_reader_t *m, uint64_t block_start,
size_t offset);
-/**
- * @brief Read a chunk of data from a meta data block
- *
- * @memberof meta_reader_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * If the end of the block is reached, this function transparently tries to
- * interpret the data after the current block as a further meta data block,
- * i.e. it can transparently read across multiple meta data blocks.
- *
- * @param m A pointer to a meta data reader
- * @param data A pointer to a memory block to write the data to
- * @param size The number of bytes to read
- *
- * @return Zero on success, -1 on failure
- */
+/* Returns 0 on success. Internally prints to stderr on failure */
int meta_reader_read(meta_reader_t *m, void *data, size_t size);
-/**
- * @brief Read an inode from a meta data block
- *
- * @memberof meta_reader_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * This function is a conveniance wrapper around @ref meta_reader_read that
- * reads and decodes an entire SquashFS inode. It first reads the common inode
- * header, interprets it and reads the additional, type dependend data.
- *
- * @param ir A pointer to a meta data reader
- * @param super A pointer to the SquashFS super block
- * @param block_start A byte offset relative to the inode table start where
- * the meta data containing the inode starts
- * @param offset A byte offset into the uncompressed meta data block
- * where the inode is stored
- *
- * @return A pointer to the decoded inode or NULL on failure. Can be freed
- * with a single free call.
- */
+/* Inode can be freed with a single free() call.
+ The function internally prints error message to stderr on failure. */
sqfs_inode_generic_t *meta_reader_read_inode(meta_reader_t *ir,
sqfs_super_t *super,
uint64_t block_start,
size_t offset);
-/**
- * @brief Read a directory header from a meta data block
- *
- * @memberof meta_reader_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * This function is a conveniance wrapper around @ref meta_reader_read that
- * reads and decodes a SquashFS directory header.
- *
- * @param m A pointer to a meta data reader
- * @param hdr A pointer to a directory header structure to write the decoded
- * data to
- *
- * @return Zero on success, -1 on failure
- */
+/* Returns 0 on success. Internally prints to stderr on failure */
int meta_reader_read_dir_header(meta_reader_t *m, sqfs_dir_header_t *hdr);
-/**
- * @brief Read a directory entry from a meta data block
- *
- * @memberof meta_reader_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * This function is a conveniance wrapper around @ref meta_reader_read that
- * reads and decodes a SquashFS directory entry.
- *
- * @param m A pointer to a meta data reader
- *
- * @return A pointer to a directory entry or NULL on failure. Can be freed
- * with a single free call.
- */
+/* Entry can be freed with a single free() call.
+ The function internally prints to stderr on failure */
sqfs_dir_entry_t *meta_reader_read_dir_ent(meta_reader_t *m);
#endif /* META_READER_H */
diff --git a/include/meta_writer.h b/include/meta_writer.h
index 6bcb29b..7036b6a 100644
--- a/include/meta_writer.h
+++ b/include/meta_writer.h
@@ -7,69 +7,24 @@
typedef struct meta_writer_t meta_writer_t;
-/**
- * @brief Create a meta data writer
- *
- * @memberof meta_writer_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * @param fd The underlying file descriptor to write from
- * @param cmp A pointer to a compressor to use for compressing the data
- *
- * @return A pointer to a meta data writer, NULL on failure
- */
+/* Create a meta data reader using a given compressor to compress data.
+ Internally prints error message to stderr on failure. */
meta_writer_t *meta_writer_create(int fd, compressor_t *cmp);
-/**
- * @brief Destroy a meta data writer and free all memory used by it
- *
- * @memberof meta_writer_t
- *
- * @param m A pointer to a meta data reader
- */
void meta_writer_destroy(meta_writer_t *m);
-/**
- * @brief Flush the currently unfinished meta data block to disk
- *
- * @memberof meta_writer_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * If data has been collected in the block buffer but it is not complete yet,
- * this function tries to compress it and write it out anyway and reset the
- * internal counters.
- *
- * @param m A pointer to a meta data reader
- *
- * @return Zero on success, -1 on failure
- */
+/* Compress and flush the currently unfinished block to disk. Returns 0 on
+ success, internally prints error message to stderr on failure */
int meta_writer_flush(meta_writer_t *m);
-/**
- * @brief Append data to the current meta data block
- *
- * @memberof meta_writer_t
- *
- * @note This function internally prints error message to stderr on failure
- *
- * This function appends the input data to an internal meta data buffer. If
- * the internal buffer is full, it is compressed and written to disk using
- * @ref meta_writer flush, i.e. the function allows for transparent writing
- * across meta data blocks.
- *
- * @param m A pointer to a meta data reader
- * @param data A pointer to the data block to append
- * @param size The number of bytes to read from the data blob
- *
- * @return Zero on success, -1 on failure
- */
+/* Returns 0 on success. Prints error message to stderr on failure. */
int meta_writer_append(meta_writer_t *m, const void *data, size_t size);
+/* Query the current block start position and offset within the block */
void meta_writer_get_position(const meta_writer_t *m, uint64_t *block_start,
uint32_t *offset);
+/* Reset all internal state, including the current block start position. */
void meta_writer_reset(meta_writer_t *m);
#endif /* META_WRITER_H */
diff --git a/include/squashfs.h b/include/squashfs.h
index 5574b29..f9df73d 100644
--- a/include/squashfs.h
+++ b/include/squashfs.h
@@ -240,11 +240,14 @@ typedef enum {
SQUASHFS_XATTR_PREFIX_MASK = 0xFF,
} E_SQFS_XATTR_TYPE;
+/* Returns 0 on success. Prints error messages to stderr on failure. */
int sqfs_super_init(sqfs_super_t *super, size_t block_size, uint32_t mtime,
E_SQFS_COMPRESSOR compressor);
+/* Returns 0 on success. Prints error messages to stderr on failure. */
int sqfs_super_write(sqfs_super_t *super, int fd);
+/* Returns 0 on success. Prints error messages to stderr on failure. */
int sqfs_super_read(sqfs_super_t *super, int fd);
#endif /* SQUASHFS_H */
diff --git a/include/str_table.h b/include/str_table.h
index b0d83f1..db36c5b 100644
--- a/include/str_table.h
+++ b/include/str_table.h
@@ -8,14 +8,9 @@ typedef struct str_bucket_t {
size_t index;
} str_bucket_t;
-/**
- * @struct str_table_t
- *
- * @brief A data structure that manages incremental, unique IDs for strings
- *
- * A string table allocates IDs for strings, and provides fast lookup for ID by
- * string and string by ID.
- */
+/* Stores strings in a hash table and assigns an incremental, unique ID to
+ each string. Subsequent additions return the existing ID. The ID can be
+ used for (hopefully) constant time lookup of the original string. */
typedef struct {
str_bucket_t **buckets;
size_t num_buckets;
@@ -25,52 +20,18 @@ typedef struct {
size_t max_strings;
} str_table_t;
-/**
- * @brief Initialize a string table
- *
- * @memberof str_table_t
- *
- * @param size The number of hash table buckets to use internally
- *
- * @return Zero on success, -1 on failure (reports error to stderr)
- */
+/* `size` is the number of hash table buckets to use internally.
+ Returns 0 on success. Internally writes errors to stderr. */
int str_table_init(str_table_t *table, size_t size);
-/**
- * @brief Free all memory used by a string table
- *
- * @memberof str_table_t
- *
- * @param table A pointer to a string table object
- */
void str_table_cleanup(str_table_t *table);
-/**
- * @brief Resolve a string to an incremental, unique ID
- *
- * @memberof str_table_t
- *
- * If the string is passed to this function for the first time, a new ID
- * is allocated for the string.
- *
- * @param table A pointer to a string table object
- * @param str A pointer to a string to resolve
- * @param idx Returns the unique ID of the string
- *
- * @return Zero on success, -1 on failure (reports error to stderr)
- */
+/* Resolve a string to an incremental, unique ID
+ Returns 0 on success. Internally writes errors to stderr. */
int str_table_get_index(str_table_t *table, const char *str, size_t *idx);
-/**
- * @brief Resolve a unique ID to the string it represents
- *
- * @memberof str_table_t
- *
- * @param table A pointer to a string table object
- * @param index The ID to resolve
- *
- * @return A pointer to the string or NULL if it hasn't been added yet
- */
+/* Resolve a unique ID to the string it represents.
+ Returns NULL if the ID is unknown, i.e. out of bounds. */
const char *str_table_get_string(str_table_t *table, size_t index);
#endif /* STR_TABLE_H */
diff --git a/include/table.h b/include/table.h
index ed2cb4a..6d61c85 100644
--- a/include/table.h
+++ b/include/table.h
@@ -8,26 +8,16 @@
#include <stdint.h>
#include <stddef.h>
-/**
- * @brief Convenience function for writing meta data to a SquashFS image
- *
- * @note This function internally prints error message to stderr on failure
- *
- * This function internally creates a meta data writer and writes 'count'
- * blocks of data from 'data' to it, each 'entsize' bytes in size. For each
- * meta data block, it remembers the 64 bit start address, writes out all
- * addresses to the and returns the location where the address list starts.
- * For instance, the fragment table and ID table are stored in this format.
- *
- * @param outfd The file descriptor to write to
- * @param super A pointer to the SquashFS super block
- * @param data A pointer to the data to write out
- * @param entsize The size of each data record
- * @param count The number of data records to write out
- * @param startblock Returns the location of the lookup table
- * @param cmp A pointer to the compressor to use for the meta data writer
- *
- * @return Zero on success, -1 on failure
+/*
+ Convenience function for writing meta data to a SquashFS image
+
+ This function internally creates a meta data writer and writes 'count'
+ blocks of data from 'data' to it, each 'entsize' bytes in size. For each
+ meta data block, it remembers the 64 bit start address, writes out all
+ addresses to an uncompressed address list and returns the location where
+ the address list starts.
+
+ Returns 0 on success. Internally prints error messages to stderr.
*/
int sqfs_write_table(int outfd, sqfs_super_t *super, const void *data,
size_t entsize, size_t count, uint64_t *startblock,
diff --git a/include/util.h b/include/util.h
index 4857539..f618f81 100644
--- a/include/util.h
+++ b/include/util.h
@@ -4,54 +4,41 @@
#include <sys/types.h>
-/**
- * @brief Turn a file path to a more usefull form
- *
- * Removes all preceeding and trailing slashes, shortens all sequences of
- * slashes to a single slash and returns failure state if one of the path
- * components is '..' or '.'.
- *
- * @param filename A pointer to the path to work on
- *
- * @return Zero on success, -1 on failure
- */
+/*
+ Removes all preceeding and trailing slashes, shortens all sequences of
+ slashes to a single slash and returns failure state if one of the path
+ components is '..' or '.'.
+
+ Returns 0 on success.
+*/
int canonicalize_name(char *filename);
-/**
- * @brief Write data to a file
- *
- * This is a wrapper around the Unix write() system call. It retries the write
- * if it is interrupted by a signal or only part of the data was written.
- */
+/*
+ A wrapper around the write() system call. It retries the write if it is
+ interrupted by a signal or only part of the data was written.
+*/
ssize_t write_retry(int fd, void *data, size_t size);
-/**
- * @brief Read data from a file
- *
- * This is a wrapper around the Unix read() system call. It retries the read
- * if it is interrupted by a signal or less than the desired size was read.
- */
+/*
+ A wrapper around the read() system call. It retries the read if it is
+ interrupted by a signal or less than the desired size was read.
+*/
ssize_t read_retry(int fd, void *buffer, size_t size);
-/**
- * @brief A common implementation of the '--version' command line argument
- *
- * Prints out version information. The program name is extracted from the
- * BSD style __progname global variable.
- */
+/*
+ A common implementation of the '--version' command line flag.
+
+ Prints out version information. The program name is extracted from the
+ BSD style __progname global variable.
+*/
void print_version(void);
-/**
- * @brief Create a directory and all its parents
- *
- * This is a wrapper around mkdir() that behaves like 'mkdir -p'. It tries to
- * create every component of the given path and treats already existing entries
- * as success.
- *
- * @param path A path to create
- *
- * @return Zero on success, -1 on failure
- */
+/*
+ A wrapper around mkdir() that behaves like 'mkdir -p'. It tries to create
+ every component of the given path and skips already existing entries.
+
+ Returns 0 on success.
+*/
int mkdir_p(const char *path);
#endif /* UTIL_H */