summaryrefslogtreecommitdiff
path: root/include/sqfs
diff options
context:
space:
mode:
Diffstat (limited to 'include/sqfs')
-rw-r--r--include/sqfs/dir.h159
-rw-r--r--include/sqfs/error.h4
-rw-r--r--include/sqfs/predef.h1
3 files changed, 164 insertions, 0 deletions
diff --git a/include/sqfs/dir.h b/include/sqfs/dir.h
index 18950df..d8603d7 100644
--- a/include/sqfs/dir.h
+++ b/include/sqfs/dir.h
@@ -59,6 +59,29 @@
* writer used for inodes.
*/
+/**
+ * @struct sqfs_dir_reader_t
+ *
+ * @brief Abstracts reading of directory entries
+ *
+ * SquashFS stores directory listings and inode structures seperated from
+ * each other in meta data blocks.
+ *
+ * The sqfs_dir_reader_t abstracts access to the filesystem tree in a SquashFS
+ * through a fairly simple interface. It keeps two meta data readers internally
+ * for reading directory listings and inodes. Externally, it offers a few
+ * simple functions for iterating over the contents of a directory that
+ * completely take care of fetching/decoding headers and sifting through the
+ * multi level hierarchie used for storing them on disk.
+ *
+ * See @ref sqfs_dir_writer_t for an overview on how directory entries are
+ * stored in SquashFS.
+ *
+ * The reader also abstracts easy access to the underlying inodes, allowing
+ * direct access to the inode referred to by a directory entry.
+ */
+
+
#define SQFS_MAX_DIR_ENT 256
/**
@@ -341,6 +364,142 @@ SQFS_API sqfs_inode_generic_t
*sqfs_dir_writer_create_inode(const sqfs_dir_writer_t *writer, size_t hlinks,
uint32_t xattr, uint32_t parent_ino);
+/**
+ * @brief Create a directory reader.
+ *
+ * @memberof sqfs_dir_reader_t
+ *
+ * @param super A pointer to the super block. Kept internally an used for
+ * resolving table positions.
+ * @param cmp A compressor to use for unpacking meta data blocks.
+ * @param file The input file to read from.
+ *
+ * @return A new directory reader on success, NULL on allocation failure.
+ */
+SQFS_API sqfs_dir_reader_t *sqfs_dir_reader_create(const sqfs_super_t *super,
+ sqfs_compressor_t *cmp,
+ sqfs_file_t *file);
+
+/**
+ * @brief Cleanup a directory reader and free all its memory.
+ *
+ * @memberof sqfs_dir_reader_t
+ */
+SQFS_API void sqfs_dir_reader_destroy(sqfs_dir_reader_t *rd);
+
+/**
+ * @brief Navigate a directory reader to the location of a directory
+ * represented by an inode.
+ *
+ * @memberof sqfs_dir_reader_t
+ *
+ * This function seeks to the meta data block containing the directory
+ * listing that the given inode referes to and resets the internal state.
+ * After that, consequtive cals to @ref sqfs_dir_reader_read can be made
+ * to iterate over the directory contents.
+ *
+ * @param rd A pointer to a directory reader.
+ * @param inode An directory or extended directory inode.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_dir_reader_open_dir(sqfs_dir_reader_t *rd,
+ const sqfs_inode_generic_t *inode);
+
+/**
+ * @brief Reset a directory reader back to the beginning of the listing.
+ *
+ * @memberof sqfs_dir_reader_t
+ *
+ * @param rd A pointer to a directory reader.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_dir_reader_rewind(sqfs_dir_reader_t *rd);
+
+/**
+ * @brief Seek through the current directory listing to locate an
+ * entry by name.
+ *
+ * @memberof sqfs_dir_reader_t
+ *
+ * @param rd A pointer to a directory reader.
+ * @param name The name of the entry to find.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_dir_reader_find(sqfs_dir_reader_t *rd, const char *name);
+
+/**
+ * @brief Read a directory entry and advance the internal position indicator
+ * to the next one.
+ *
+ * @memberof sqfs_dir_reader_t
+ *
+ * Call this function repeatedly to iterate over a directory listing. It
+ * returns a positive number to indicate that it couldn't fetch any more data
+ * because the end of the listing was reached. A negative value indicates an
+ * error.
+ *
+ * After calling this function, you can use @ref sqfs_dir_reader_get_inode to
+ * read the full inode structure that the current entry referes to.
+ *
+ * @param rd A pointer to a directory reader.
+ * @param out Returns a pointer to a directory entry on success that can be
+ * freed with a single free call.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure, a positive
+ * number if the end of the current directory listing has been reached.
+ */
+SQFS_API int sqfs_dir_reader_read(sqfs_dir_reader_t *rd,
+ sqfs_dir_entry_t **out);
+
+/**
+ * @brief Read the inode that the current directory entry points to.
+ *
+ * @memberof sqfs_dir_reader_t
+ *
+ * @param rd A pointer to a directory reader.
+ * @param out Returns a pointer to a generic inode that can be freed with a
+ * single free call.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_dir_reader_get_inode(sqfs_dir_reader_t *rd,
+ sqfs_inode_generic_t **inode);
+
+/**
+ * @brief Read the root inode using the location given by the super block.
+ *
+ * @memberof sqfs_dir_reader_t
+ *
+ * @param rd A pointer to a directory reader.
+ * @param out Returns a pointer to a generic inode that can be freed with a
+ * single free call.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_dir_reader_get_root_inode(sqfs_dir_reader_t *rd,
+ sqfs_inode_generic_t **inode);
+
+/**
+ * @brief Find an inode through path traversal from the root node downwards.
+ *
+ * @memberof sqfs_dir_reader_t
+ *
+ * @param rd A pointer to a directory reader.
+ * @param path A path to resolve into an inode. Forward or backward slashes can
+ * be used to seperate path components. Resolving '.' or '..' is
+ * not supported.
+ * @param out Returns a pointer to a generic inode that can be freed with a
+ * single free call.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_dir_reader_find_by_path(sqfs_dir_reader_t *rd,
+ const char *path,
+ sqfs_inode_generic_t **out);
+
#ifdef __cplusplus
}
#endif
diff --git a/include/sqfs/error.h b/include/sqfs/error.h
index a9a0acf..ddfeadd 100644
--- a/include/sqfs/error.h
+++ b/include/sqfs/error.h
@@ -103,6 +103,10 @@ typedef enum {
* legal range (4k to 1M).
*/
SQFS_ERROR_SUPER_BLOCK_SIZE = -11,
+
+ SQFS_ERROR_NOT_DIR = -12,
+
+ SQFS_ERROR_NO_ENTRY = -13,
} E_SQFS_ERROR;
#endif /* SQFS_ERROR_H */
diff --git a/include/sqfs/predef.h b/include/sqfs/predef.h
index 95d907f..4041a57 100644
--- a/include/sqfs/predef.h
+++ b/include/sqfs/predef.h
@@ -63,6 +63,7 @@ typedef struct sqfs_block_processor_t sqfs_block_processor_t;
typedef struct sqfs_compressor_config_t sqfs_compressor_config_t;
typedef struct sqfs_compressor_t sqfs_compressor_t;
typedef struct sqfs_dir_writer_t sqfs_dir_writer_t;
+typedef struct sqfs_dir_reader_t sqfs_dir_reader_t;
typedef struct sqfs_id_table_t sqfs_id_table_t;
typedef struct sqfs_meta_reader_t sqfs_meta_reader_t;
typedef struct sqfs_meta_writer_t sqfs_meta_writer_t;