Cleanup: split "dir.h" into "dir_reader.h" and "dir_writer.h"

Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>

3 files changed, 563 insertions, 489 deletions

diff --git a/include/sqfs/dir.h b/include/sqfs/dir.h
index d57ad73..1357521 100644
--- a/include/sqfs/dir.h
+++ b/include/sqfs/dir.h
@@ -29,59 +29,6 @@
  *        declarations for the @ref sqfs_dir_writer_t.
  */
 
-/**
- * @struct sqfs_dir_writer_t
- *
- * @brief Abstracts generating of directory entries
- *
- * SquashFS stores directory entries and inodes seperated from each other. The
- * inodes are stored in a series of meta data blocks before another series of
- * meta data blocks that contain the directory entries. Directory inodes point
- * to meta data block (and offset) where its contents are listed and the
- * entries in turn point back to the inodes that represent them.
- *
- * There are some rules to this. Directory entries have to be written in
- * ASCIIbetical ordering. Up to 256 entries are preceeded by a header. The
- * entries use delta encoding for inode numbers and block locations relative to
- * the header, so every time the inodes cross a meta data block boundary, if
- * the difference in inode number gets too large, or if the entry count would
- * exceed 256, a new header has to be emitted. Even if the inode pointed to is
- * an extended type, the entry in the header still has to indicate the base
- * type.
- *
- * In addtion to that, extended directory inodes can contain an index for
- * faster lookup. The index points to each header and requires a new header to
- * be emitted if the entries cross a block boundary.
- *
- * The dir writer takes care of all of this and provides a simple interface for
- * adding entries. Internally it fills data into a meta data writer and
- * generates an index that it can, on request, write to another meta data
- * 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
 
 /**
@@ -192,440 +139,4 @@ struct sqfs_dir_index_t {
 	uint8_t name[];
 };
 
-typedef enum {
-	/**
-	 * @brief Omit device special files from the final tree.
-	 */
-	SQFS_TREE_NO_DEVICES = 0x01,
-
-	/**
-	 * @brief Omit socket files from the final tree.
-	 */
-	SQFS_TREE_NO_SOCKETS = 0x02,
-
-	/**
-	 * @brief Omit named pipes from the final tree.
-	 */
-	SQFS_TREE_NO_FIFO = 0x04,
-
-	/**
-	 * @brief Omit symbolic links from the final tree.
-	 */
-	SQFS_TREE_NO_SLINKS = 0x08,
-
-	/**
-	 * @brief Omit empty directories from the final tree.
-	 *
-	 * If a directory is not empty on-disk, but ends up empty after
-	 * applying all the other filter rules, it is also omitted.
-	 */
-	SQFS_TREE_NO_EMPTY = 0x10,
-
-	/**
-	 * @brief Do not recurse into sub directories.
-	 *
-	 * If the start node is a directory, the tree deserializer will still
-	 * recurse into it, but it will not go beyond that.
-	 */
-	SQFS_TREE_NO_RECURSE = 0x20,
-
-	/**
-	 * @brief Store the list of parent nodes all the way to the target node
-	 *
-	 * When traversing towards the selected node, also collect the chain
-	 * of parent nodes with the subtree stored at the end.
-	 */
-	SQFS_TREE_STORE_PARENTS = 0x40,
-} E_SQFS_TREE_FILTER_FLAGS;
-
-/**
- * @struct sqfs_tree_node_t
- *
- * @brief Encapsulates a node in the filesystem tree read by
- *        @ref sqfs_dir_reader_get_full_hierarchy.
- */
-struct sqfs_tree_node_t {
-	/**
-	 * @brief Pointer to parent, NULL for the root node
-	 */
-	sqfs_tree_node_t *parent;
-
-	/**
-	 * @brief For directories, a linked list of children.
-	 */
-	sqfs_tree_node_t *children;
-
-	/**
-	 * @brief Linked list next pointer for children list.
-	 */
-	sqfs_tree_node_t *next;
-
-	/**
-	 * @brief Inode representing this element in the tree.
-	 */
-	sqfs_inode_generic_t *inode;
-
-	/**
-	 * @brief Resolved 32 bit user ID from the inode
-	 */
-	uint32_t uid;
-
-	/**
-	 * @brief Resolved 32 bit group ID from the inode
-	 */
-	uint32_t gid;
-
-	/**
-	 * @brief null-terminated entry name.
-	 */
-	uint8_t name[];
-};
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-/**
- * @brief Create a directory writer.
- *
- * @memberof sqfs_dir_writer_t
- *
- * @param dm A pointer to a meta data writer that the generated directory
- *           entries should be written to.
- *
- * @return A pointer to a directory writer on success, NULL on
- *         allocation failure.
- */
-SQFS_API sqfs_dir_writer_t *sqfs_dir_writer_create(sqfs_meta_writer_t *dm);
-
-/**
- * @brief Destroy a directory writer and free all its memory.
- *
- * @memberof sqfs_dir_writer_t
- *
- * @param writer A pointer to a directory writer object.
- */
-SQFS_API void sqfs_dir_writer_destroy(sqfs_dir_writer_t *writer);
-
-/**
- * @brief Begin writing a directory, i.e. reset and initialize all internal
- *        state neccessary.
- *
- * @memberof sqfs_dir_writer_t
- *
- * @param writer A pointer to a directory writer object.
- *
- * @return Zero on success, a @ref E_SQFS_ERROR value on failure.
- */
-SQFS_API int sqfs_dir_writer_begin(sqfs_dir_writer_t *writer);
-
-/**
- * @brief Add add a directory entry.
- *
- * @memberof sqfs_dir_writer_t
- *
- * @param writer A pointer to a directory writer object.
- * @param name The name of the directory entry.
- * @param inode_num The inode number of the entry.
- * @param inode_ref A reference to the inode, i.e. the meta data block offset
- *                  is stored in bits 16 to 48 and the lower 16 bit hold an
- *                  offset into the block.
- * @param mode A file mode, i.e. type and permission bits from which the entry
- *             type is derived internally.
- *
- * @return Zero on success, a @ref E_SQFS_ERROR value on failure.
- */
-SQFS_API int sqfs_dir_writer_add_entry(sqfs_dir_writer_t *writer,
-				       const char *name,
-				       uint32_t inode_num, uint64_t inode_ref,
-				       mode_t mode);
-
-/**
- * @brief Finish writing a directory listing and write everything out to the
- *        meta data writer.
- *
- * @memberof sqfs_dir_writer_t
- *
- * @param writer A pointer to a directory writer object.
- *
- * @return Zero on success, a @ref E_SQFS_ERROR value on failure.
- */
-SQFS_API int sqfs_dir_writer_end(sqfs_dir_writer_t *writer);
-
-/**
- * @brief Get the total, uncompressed size of the last written
- *        directory in bytes.
- *
- * @memberof sqfs_dir_writer_t
- *
- * Call this function after @ref sqfs_dir_writer_end to get the uncompressed
- * size of the directory listing that is required for the directory inodes.
- * And also to determine which kind of directory inode to create.
- *
- * @param writer A pointer to a directory writer object.
- *
- * @return The size of the entire, uncompressed listing in bytes.
- */
-SQFS_API size_t sqfs_dir_writer_get_size(const sqfs_dir_writer_t *writer);
-
-/**
- * @brief Get the numer of entries written to the last directory.
- *
- * @memberof sqfs_dir_writer_t
- *
- * Call this function after @ref sqfs_dir_writer_end to get the total
- * number of entries written to the directory.
- *
- * @param writer A pointer to a directory writer object.
- *
- * @return The number of entries in the directory.
- */
-SQFS_API
-size_t sqfs_dir_writer_get_entry_count(const sqfs_dir_writer_t *writer);
-
-/**
- * @brief Get the location of the last written directory.
- *
- * @memberof sqfs_dir_writer_t
- *
- * Call this function after @ref sqfs_dir_writer_end to get the location of
- * the directory listing that is required for the directory inodes.
- *
- * @param writer A pointer to a directory writer object.
- *
- * @return A meta data reference, i.e. bits 16 to 48 contain the block start
- *         and the lower 16 bit an offset into the uncompressed block.
- */
-SQFS_API uint64_t
-sqfs_dir_writer_get_dir_reference(const sqfs_dir_writer_t *writer);
-
-/**
- * @brief Get the size of the index of the last written directory.
- *
- * @memberof sqfs_dir_writer_t
- *
- * Call this function after @ref sqfs_dir_writer_end to get the size of
- * the directory index that is required for extended directory inodes.
- *
- * @param writer A pointer to a directory writer object.
- *
- * @return The number of index entries.
- */
-SQFS_API size_t sqfs_dir_writer_get_index_size(const sqfs_dir_writer_t *writer);
-
-/**
- * @brief Write the index of the index of the last written directory to
- *        a meta data writer after the extended directory inode.
- *
- * @memberof sqfs_dir_writer_t
- *
- * @param writer A pointer to a directory writer object.
- * @param im A pointer to a meta data writer to write the index to.
- *
- * @return Zero on success, a @ref E_SQFS_ERROR value on failure.
- */
-SQFS_API int sqfs_dir_writer_write_index(const sqfs_dir_writer_t *writer,
-					 sqfs_meta_writer_t *im);
-
-/**
- * @brief Helper function for creating an inode from the last directory.
- *
- * @memberof sqfs_dir_writer_t
- *
- * Call this function after @ref sqfs_dir_writer_end to create a bare bones
- * inode structure for the directory. The directory information is filled in
- * completely and the type is set, the rest of the basic information such as
- * permission bits, owner and timestamp is left untouched.
- *
- * If the generated inode is an extended directory inode, you can use another
- * convenience function called @ref sqfs_dir_writer_write_index to write the
- * index meta data after writing the inode itself.
- *
- * @param writer A pointer to a directory writer object.
- * @param hlinks The number of hard links pointing to the directory.
- * @param xattr If set to something other than 0xFFFFFFFF, an extended
- *              directory inode is created with xattr index set.
- * @param parent_ino The inode number of the parent directory.
- *
- * @return A generic inode or NULL on allocation failure.
- */
-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);
-
-/**
- * @brief High level helper function for deserializing the entire file system
- *        hierarchy into an in-memory tree structure.
- *
- * @memberof sqfs_dir_reader_t
- *
- * This function internally navigates to a specified inode using
- * @ref sqfs_dir_reader_find_by_path and starting from that recursively
- * deserializes the entire hierarchy into a tree structure holding all inodes.
- *
- * @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. Can be set to NULL to get the root inode.
- * @param flags A combination of @ref E_SQFS_TREE_FILTER_FLAGS flags.
- * @param out Returns the top most tree node.
- *
- * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
- */
-SQFS_API int sqfs_dir_reader_get_full_hierarchy(sqfs_dir_reader_t *rd,
-						const sqfs_id_table_t *idtbl,
-						const char *path,
-						unsigned int flags,
-						sqfs_tree_node_t **out);
-
-/**
- * @brief Recursively destroy a tree of @ref sqfs_tree_node_t nodes
- *
- * This function can be used to clean up after
- * @ref sqfs_dir_reader_get_full_hierarchy.
- *
- * @param root A pointer to the root node.
- */
-SQFS_API void sqfs_dir_tree_destroy(sqfs_tree_node_t *root);
-
-#ifdef __cplusplus
-}
-#endif
-
 #endif /* SQFS_DIR_H */
diff --git a/include/sqfs/dir_reader.h b/include/sqfs/dir_reader.h
new file mode 100644
index 0000000..57b91e6
--- /dev/null
+++ b/include/sqfs/dir_reader.h
@@ -0,0 +1,326 @@
+/* SPDX-License-Identifier: LGPL-3.0-or-later */
+/*
+ * dir_reader.h - This file is part of libsquashfs
+ *
+ * Copyright (C) 2019 David Oberhollenzer <goliath@infraroot.at>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+#ifndef SQFS_DIR_READER_H
+#define SQFS_DIR_READER_H
+
+#include "sqfs/predef.h"
+
+/**
+ * @file dir_reader.h
+ *
+ * @brief Contains declarations for the @ref sqfs_dir_reader_t
+ */
+
+/**
+ * @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.
+ */
+
+/**
+ * @enum E_SQFS_TREE_FILTER_FLAGS
+ *
+ * @brief Filter flags for @ref sqfs_dir_reader_get_full_hierarchy
+ */
+typedef enum {
+	/**
+	 * @brief Omit device special files from the final tree.
+	 */
+	SQFS_TREE_NO_DEVICES = 0x01,
+
+	/**
+	 * @brief Omit socket files from the final tree.
+	 */
+	SQFS_TREE_NO_SOCKETS = 0x02,
+
+	/**
+	 * @brief Omit named pipes from the final tree.
+	 */
+	SQFS_TREE_NO_FIFO = 0x04,
+
+	/**
+	 * @brief Omit symbolic links from the final tree.
+	 */
+	SQFS_TREE_NO_SLINKS = 0x08,
+
+	/**
+	 * @brief Omit empty directories from the final tree.
+	 *
+	 * If a directory is not empty on-disk, but ends up empty after
+	 * applying all the other filter rules, it is also omitted.
+	 */
+	SQFS_TREE_NO_EMPTY = 0x10,
+
+	/**
+	 * @brief Do not recurse into sub directories.
+	 *
+	 * If the start node is a directory, the tree deserializer will still
+	 * recurse into it, but it will not go beyond that.
+	 */
+	SQFS_TREE_NO_RECURSE = 0x20,
+
+	/**
+	 * @brief Store the list of parent nodes all the way to the target node
+	 *
+	 * When traversing towards the selected node, also collect the chain
+	 * of parent nodes with the subtree stored at the end.
+	 */
+	SQFS_TREE_STORE_PARENTS = 0x40,
+} E_SQFS_TREE_FILTER_FLAGS;
+
+/**
+ * @struct sqfs_tree_node_t
+ *
+ * @brief Encapsulates a node in the filesystem tree read by
+ *        @ref sqfs_dir_reader_get_full_hierarchy.
+ */
+struct sqfs_tree_node_t {
+	/**
+	 * @brief Pointer to parent, NULL for the root node
+	 */
+	sqfs_tree_node_t *parent;
+
+	/**
+	 * @brief For directories, a linked list of children.
+	 */
+	sqfs_tree_node_t *children;
+
+	/**
+	 * @brief Linked list next pointer for children list.
+	 */
+	sqfs_tree_node_t *next;
+
+	/**
+	 * @brief Inode representing this element in the tree.
+	 */
+	sqfs_inode_generic_t *inode;
+
+	/**
+	 * @brief Resolved 32 bit user ID from the inode
+	 */
+	uint32_t uid;
+
+	/**
+	 * @brief Resolved 32 bit group ID from the inode
+	 */
+	uint32_t gid;
+
+	/**
+	 * @brief null-terminated entry name.
+	 */
+	uint8_t name[];
+};
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @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);
+
+/**
+ * @brief High level helper function for deserializing the entire file system
+ *        hierarchy into an in-memory tree structure.
+ *
+ * @memberof sqfs_dir_reader_t
+ *
+ * This function internally navigates to a specified inode using
+ * @ref sqfs_dir_reader_find_by_path and starting from that recursively
+ * deserializes the entire hierarchy into a tree structure holding all inodes.
+ *
+ * @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. Can be set to NULL to get the root inode.
+ * @param flags A combination of @ref E_SQFS_TREE_FILTER_FLAGS flags.
+ * @param out Returns the top most tree node.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_dir_reader_get_full_hierarchy(sqfs_dir_reader_t *rd,
+						const sqfs_id_table_t *idtbl,
+						const char *path,
+						unsigned int flags,
+						sqfs_tree_node_t **out);
+
+/**
+ * @brief Recursively destroy a tree of @ref sqfs_tree_node_t nodes
+ *
+ * This function can be used to clean up after
+ * @ref sqfs_dir_reader_get_full_hierarchy.
+ *
+ * @param root A pointer to the root node.
+ */
+SQFS_API void sqfs_dir_tree_destroy(sqfs_tree_node_t *root);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* SQFS_DIR_READER_H */
diff --git a/include/sqfs/dir_writer.h b/include/sqfs/dir_writer.h
new file mode 100644
index 0000000..09869a1
--- /dev/null
+++ b/include/sqfs/dir_writer.h
@@ -0,0 +1,237 @@
+/* SPDX-License-Identifier: LGPL-3.0-or-later */
+/*
+ * dir_writer.h - This file is part of libsquashfs
+ *
+ * Copyright (C) 2019 David Oberhollenzer <goliath@infraroot.at>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+#ifndef SQFS_DIR_WRITER_H
+#define SQFS_DIR_WRITER_H
+
+#include "sqfs/predef.h"
+
+/**
+ * @file dir_writer.h
+ *
+ * @brief Contains declarations for the @ref sqfs_dir_writer_t.
+ */
+
+/**
+ * @struct sqfs_dir_writer_t
+ *
+ * @brief Abstracts generating of directory entries
+ *
+ * SquashFS stores directory entries and inodes seperated from each other. The
+ * inodes are stored in a series of meta data blocks before another series of
+ * meta data blocks that contain the directory entries. Directory inodes point
+ * to meta data block (and offset) where its contents are listed and the
+ * entries in turn point back to the inodes that represent them.
+ *
+ * There are some rules to this. Directory entries have to be written in
+ * ASCIIbetical ordering. Up to 256 entries are preceeded by a header. The
+ * entries use delta encoding for inode numbers and block locations relative to
+ * the header, so every time the inodes cross a meta data block boundary, if
+ * the difference in inode number gets too large, or if the entry count would
+ * exceed 256, a new header has to be emitted. Even if the inode pointed to is
+ * an extended type, the entry in the header still has to indicate the base
+ * type.
+ *
+ * In addtion to that, extended directory inodes can contain an index for
+ * faster lookup. The index points to each header and requires a new header to
+ * be emitted if the entries cross a block boundary.
+ *
+ * The dir writer takes care of all of this and provides a simple interface for
+ * adding entries. Internally it fills data into a meta data writer and
+ * generates an index that it can, on request, write to another meta data
+ * writer used for inodes.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Create a directory writer.
+ *
+ * @memberof sqfs_dir_writer_t
+ *
+ * @param dm A pointer to a meta data writer that the generated directory
+ *           entries should be written to.
+ *
+ * @return A pointer to a directory writer on success, NULL on
+ *         allocation failure.
+ */
+SQFS_API sqfs_dir_writer_t *sqfs_dir_writer_create(sqfs_meta_writer_t *dm);
+
+/**
+ * @brief Destroy a directory writer and free all its memory.
+ *
+ * @memberof sqfs_dir_writer_t
+ *
+ * @param writer A pointer to a directory writer object.
+ */
+SQFS_API void sqfs_dir_writer_destroy(sqfs_dir_writer_t *writer);
+
+/**
+ * @brief Begin writing a directory, i.e. reset and initialize all internal
+ *        state neccessary.
+ *
+ * @memberof sqfs_dir_writer_t
+ *
+ * @param writer A pointer to a directory writer object.
+ *
+ * @return Zero on success, a @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_dir_writer_begin(sqfs_dir_writer_t *writer);
+
+/**
+ * @brief Add add a directory entry.
+ *
+ * @memberof sqfs_dir_writer_t
+ *
+ * @param writer A pointer to a directory writer object.
+ * @param name The name of the directory entry.
+ * @param inode_num The inode number of the entry.
+ * @param inode_ref A reference to the inode, i.e. the meta data block offset
+ *                  is stored in bits 16 to 48 and the lower 16 bit hold an
+ *                  offset into the block.
+ * @param mode A file mode, i.e. type and permission bits from which the entry
+ *             type is derived internally.
+ *
+ * @return Zero on success, a @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_dir_writer_add_entry(sqfs_dir_writer_t *writer,
+				       const char *name,
+				       uint32_t inode_num, uint64_t inode_ref,
+				       mode_t mode);
+
+/**
+ * @brief Finish writing a directory listing and write everything out to the
+ *        meta data writer.
+ *
+ * @memberof sqfs_dir_writer_t
+ *
+ * @param writer A pointer to a directory writer object.
+ *
+ * @return Zero on success, a @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_dir_writer_end(sqfs_dir_writer_t *writer);
+
+/**
+ * @brief Get the total, uncompressed size of the last written
+ *        directory in bytes.
+ *
+ * @memberof sqfs_dir_writer_t
+ *
+ * Call this function after @ref sqfs_dir_writer_end to get the uncompressed
+ * size of the directory listing that is required for the directory inodes.
+ * And also to determine which kind of directory inode to create.
+ *
+ * @param writer A pointer to a directory writer object.
+ *
+ * @return The size of the entire, uncompressed listing in bytes.
+ */
+SQFS_API size_t sqfs_dir_writer_get_size(const sqfs_dir_writer_t *writer);
+
+/**
+ * @brief Get the numer of entries written to the last directory.
+ *
+ * @memberof sqfs_dir_writer_t
+ *
+ * Call this function after @ref sqfs_dir_writer_end to get the total
+ * number of entries written to the directory.
+ *
+ * @param writer A pointer to a directory writer object.
+ *
+ * @return The number of entries in the directory.
+ */
+SQFS_API
+size_t sqfs_dir_writer_get_entry_count(const sqfs_dir_writer_t *writer);
+
+/**
+ * @brief Get the location of the last written directory.
+ *
+ * @memberof sqfs_dir_writer_t
+ *
+ * Call this function after @ref sqfs_dir_writer_end to get the location of
+ * the directory listing that is required for the directory inodes.
+ *
+ * @param writer A pointer to a directory writer object.
+ *
+ * @return A meta data reference, i.e. bits 16 to 48 contain the block start
+ *         and the lower 16 bit an offset into the uncompressed block.
+ */
+SQFS_API uint64_t
+sqfs_dir_writer_get_dir_reference(const sqfs_dir_writer_t *writer);
+
+/**
+ * @brief Get the size of the index of the last written directory.
+ *
+ * @memberof sqfs_dir_writer_t
+ *
+ * Call this function after @ref sqfs_dir_writer_end to get the size of
+ * the directory index that is required for extended directory inodes.
+ *
+ * @param writer A pointer to a directory writer object.
+ *
+ * @return The number of index entries.
+ */
+SQFS_API size_t sqfs_dir_writer_get_index_size(const sqfs_dir_writer_t *writer);
+
+/**
+ * @brief Write the index of the index of the last written directory to
+ *        a meta data writer after the extended directory inode.
+ *
+ * @memberof sqfs_dir_writer_t
+ *
+ * @param writer A pointer to a directory writer object.
+ * @param im A pointer to a meta data writer to write the index to.
+ *
+ * @return Zero on success, a @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_dir_writer_write_index(const sqfs_dir_writer_t *writer,
+					 sqfs_meta_writer_t *im);
+
+/**
+ * @brief Helper function for creating an inode from the last directory.
+ *
+ * @memberof sqfs_dir_writer_t
+ *
+ * Call this function after @ref sqfs_dir_writer_end to create a bare bones
+ * inode structure for the directory. The directory information is filled in
+ * completely and the type is set, the rest of the basic information such as
+ * permission bits, owner and timestamp is left untouched.
+ *
+ * If the generated inode is an extended directory inode, you can use another
+ * convenience function called @ref sqfs_dir_writer_write_index to write the
+ * index meta data after writing the inode itself.
+ *
+ * @param writer A pointer to a directory writer object.
+ * @param hlinks The number of hard links pointing to the directory.
+ * @param xattr If set to something other than 0xFFFFFFFF, an extended
+ *              directory inode is created with xattr index set.
+ * @param parent_ino The inode number of the parent directory.
+ *
+ * @return A generic inode or NULL on allocation failure.
+ */
+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);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* SQFS_DIR_WRITER_H */