Add support for '.' and '..' entries in sqfs_dir_reader_t

Two flags are added to the dir reader API, one for the create function
that the dir reader should report those entries and one to the open
function to suppress that if it was enabled.

To implement the feature, a mapping of visited directory inodes is
maintained internally, that mapps inode numbers to inode references.

When opening a directory, state is maintained to generate the fake
entries for '.' and '..'. Since all the other functions are based on
the open/read/rewind API, no alterations need to be made. The tree
scan function is modified, to use the suppress flag, so it does not
accidentally catch those entries.

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

1 files changed, 62 insertions, 2 deletions

diff --git a/include/sqfs/dir_reader.h b/include/sqfs/dir_reader.h
index 2ee7204..c528e33 100644
--- a/include/sqfs/dir_reader.h
+++ b/include/sqfs/dir_reader.h
@@ -148,6 +148,51 @@ struct sqfs_tree_node_t {
 	sqfs_u8 name[];
 };
 
+/**
+ * @enum SQFS_DIR_READER_FLAGS
+ *
+ * @brief Flags for @ref sqfs_dir_reader_create
+ */
+typedef enum {
+	/**
+	 * @brief Support "." and ".." directory and path entries.
+	 *
+	 * If this flag is set, the directory reader returns "." and ".."
+	 * entries when iterating over a directory, can fetch the associated
+	 * inodes if requested and supports resolving "." and ".." path
+	 * components when looking up a full path.
+	 *
+	 * In order for this to work, it internally caches the locations of
+	 * directory inodes it encounteres. This means, it only works as long
+	 * as you only use inodes fetched through the directory reader. If
+	 * given a foreign inode it hasn't seen before, it might not be able
+	 * to resolve the parent link.
+	 */
+	SQFS_DIR_READER_DOT_ENTRIES = 0x00000001,
+
+	SQFS_DIR_READER_ALL_FLAGS = 0x00000001,
+} SQFS_DIR_READER_FLAGS;
+
+/**
+ * @enum SQFS_DIR_OPEN_FLAGS
+ *
+ * @brief Flags for @ref sqfs_dir_reader_open_dir
+ */
+typedef enum {
+	/**
+	 * @brief Do not generate "." and ".." entries
+	 *
+	 * If the @ref sqfs_dir_reader_t was created with
+	 * the @ref SQFS_DIR_READER_DOT_ENTRIES flag set, "." and ".." entries
+	 * are generated when iterating over a directory. If that is not desired
+	 * in some instances, this flag can be set to suppress this behaviour
+	 * when opening a directory.
+	 */
+	SQFS_DIR_OPEN_NO_DOT_ENTRIES = 0x00000001,
+
+	SQFS_DIR_OPEN_ALL_FLAGS = 0x00000001,
+} SQFS_DIR_OPEN_FLAGS;
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -157,11 +202,15 @@ extern "C" {
  *
  * @memberof sqfs_dir_reader_t
  *
+ * The function fails if any unknown flag is set. In squashfs-tools-ng
+ * version 1.2 introduced the @ref SQFS_DIR_READER_DOT_ENTRIES flag,
+ * earlier versions require the flags field to be set to zero.
+ *
  * @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.
- * @param flags Currently must be zero or the function fails.
+ * @param flags A combination of @ref SQFS_DIR_READER_FLAGS
  *
  * @return A new directory reader on success, NULL on allocation failure.
  */
@@ -181,9 +230,20 @@ SQFS_API sqfs_dir_reader_t *sqfs_dir_reader_create(const sqfs_super_t *super,
  * After that, consequtive cals to @ref sqfs_dir_reader_read can be made
  * to iterate over the directory contents.
  *
+ * If the reader was created with the @ref SQFS_DIR_READER_DOT_ENTRIES flag
+ * set, the first two entries will be ".", referring to the directory inode
+ * itself and "..", referring to the parent directory inode. Those entries
+ * are generated artificially, as SquashFS does not store them on disk, hence
+ * extra work is required and a flag is used to enable this behaviour. By
+ * default, no such entries are generated.
+ *
+ * If this flag is set, but you wish to override that behaviour on a
+ * per-instance basis, simply set the @ref SQFS_DIR_OPEN_NO_DOT_ENTRIES flag
+ * when calling this function.
+ *
  * @param rd A pointer to a directory reader.
  * @param inode An directory or extended directory inode.
- * @param flags Currently must be zero or the function fails.
+ * @param flags A combination of @ref SQFS_DIR_OPEN_FLAGS.
  *
  * @return Zero on success, an @ref SQFS_ERROR value on failure.
  */