libio: merge directory iterator headers, document API and behavior

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

1 files changed, 188 insertions, 3 deletions

diff --git a/include/io/dir_iterator.h b/include/io/dir_iterator.h
index 7080d65..74027f5 100644
--- a/include/io/dir_iterator.h
+++ b/include/io/dir_iterator.h
@@ -9,36 +9,221 @@
 
 #include "sqfs/predef.h"
 
+/**
+ * @struct dir_entry_t
+ *
+ * @brief A directory entry returned by a @ref dir_iterator_t
+ */
 typedef struct {
+	/**
+	 * @brief Unix time stamp when the entry was last modified.
+	 *
+	 * If necessary, the OS native time stamp is converted to Unix time.
+	 */
 	sqfs_s64 mtime;
+
+	/**
+	 * @brief Device number where the entry is stored on.
+	 *
+	 * On Windows and other non-Unix OSes, a dummy value is stored here.
+	 */
 	sqfs_u64 dev;
+
+	/**
+	 * @brief Device number for device special files.
+	 *
+	 * On Windows and other non-Unix OSes, a dummy value is stored here.
+	 */
 	sqfs_u64 rdev;
+
+	/**
+	 * @brief ID of the user that owns the entry.
+	 *
+	 * On Windows and other non-Unix OSes, this always reports user 0.
+	 */
 	sqfs_u32 uid;
+
+	/**
+	 * @brief ID of the group that owns the entry.
+	 *
+	 * On Windows and other non-Unix OSes, this always reports group 0.
+	 */
 	sqfs_u32 gid;
+
+	/**
+	 * @brief Unix style permissions and entry type.
+	 *
+	 * On Windows and other non-Unix OSes, this is synthesized from the
+	 * Unix-like file type, default 0755 permissions for directories or
+	 * 0644 for files.
+	 */
 	sqfs_u16 mode;
 
+	/**
+	 * @brief Name of the entry
+	 *
+	 * On Unix-like OSes, the name is returned as-is. On systems like
+	 * Windows with encoding-aware APIs, the name is converted to UTF-8.
+	 */
 	char name[];
 } dir_entry_t;
 
+/**
+ * @interface dir_iterator_t
+ *
+ * @brief An iterator over entries in a filesystem directory.
+ */
 typedef struct dir_iterator_t {
 	sqfs_object_t obj;
 
+	/**
+	 * @brief A device number for detecting mount points and hard links.
+	 *
+	 * On Unix-like systems this exposes the underlying device number
+	 * backing this directory. Each entry returned by the iterator also
+	 * has a device number and if it is different, you found a mount point.
+	 *
+	 * The device number, combined with inode number, are also needed to
+	 * detect hard links. Entries with same device and inode number point
+	 * to the same file.
+	 */
 	sqfs_u64 dev;
 
-	int (*next)(struct dir_iterator_t *it,
-		    dir_entry_t **out);
+	/**
+	 * @brief Read the next entry and update internal state relating to it
+	 *
+	 * @param it A pointer to the iterator itself
+	 * @param out Returns a pointer to an entry on success
+	 *
+	 * @return Zero on success, postivie value if the end of the list was
+	 *         reached, negative @ref SQFS_ERROR value on failure.
+	 */
+	int (*next)(struct dir_iterator_t *it, dir_entry_t **out);
 
+	/**
+	 * @brief If the last entry was a symlink, extract the target path
+	 *
+	 * @param it A pointer to the iterator itself.
+	 * @param out Returns a pointer to a string on success. Has to be
+	 *            released with free().
+	 *
+	 * @return Zero on success, negative @ref SQFS_ERROR value on failure.
+	 */
 	int (*read_link)(struct dir_iterator_t *it, char **out);
 
+	/**
+	 * @brief If the last entry was a directory, open it.
+	 *
+	 * If next() returned a directory, this can be used to create a brand
+	 * new dir_iterator_t for it, that is independent of the current one
+	 * and returns the sub-directories entries.
+	 *
+	 * @param it A pointer to the iterator itself.
+	 * @param out Returns a pointer to a directory iterator on success.
+	 *
+	 * @return Zero on success, negative @ref SQFS_ERROR value on failure.
+	 */
 	int (*open_subdir)(struct dir_iterator_t *it,
 			   struct dir_iterator_t **out);
 } dir_iterator_t;
 
+enum {
+	DIR_SCAN_NO_SOCK = 0x0001,
+	DIR_SCAN_NO_SLINK = 0x0002,
+	DIR_SCAN_NO_FILE = 0x0004,
+	DIR_SCAN_NO_BLK = 0x0008,
+	DIR_SCAN_NO_DIR = 0x0010,
+	DIR_SCAN_NO_CHR = 0x0020,
+	DIR_SCAN_NO_FIFO = 0x0040,
+
+	DIR_SCAN_KEEP_TIME = 0x0100,
+	DIR_SCAN_KEEP_UID = 0x0200,
+	DIR_SCAN_KEEP_GID = 0x0400,
+	DIR_SCAN_KEEP_MODE = 0x0800,
+
+	DIR_SCAN_ONE_FILESYSTEM = 0x1000,
+	DIR_SCAN_NO_RECURSION = 0x2000,
+	DIR_SCAN_MATCH_FULL_PATH = 0x4000,
+};
+
+typedef struct {
+	sqfs_u32 flags;
+	sqfs_u32 def_uid;
+	sqfs_u32 def_gid;
+	sqfs_u32 def_mode;
+	sqfs_s64 def_mtime;
+
+	/**
+	 * @brief A prefix to attach to all returend paths
+	 *
+	 * If not null, this string and an additional "/" are prepended to
+	 * all entries returned by the iterator.
+	 */
+	const char *prefix;
+
+	/**
+	 * @brief A glob pattern that either the name must match
+	 *
+	 * If this is not NULL, only paths that match this globbing pattern
+	 * are returned. If the flag DIR_SCAN_MATCH_FULL_PATH is set, the
+	 * entire path must match, slashes cannot match wild card characters.
+	 * If not set, only the last part of the path is tested. The iterator
+	 * still recurses into directories, it simply doesn't report them if
+	 * they don't match.
+	 */
+	const char *name_pattern;
+} dir_tree_cfg_t;
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-dir_iterator_t *dir_iterator_create(const char *path);
+/**
+ * @brief Construct a simple directory iterator given a path
+ *
+ * On systems with encoding aware file I/O (like Windows), the path is
+ * interpreted to be UTF-8 encoded and converted to the native system API
+ * encoding to open the directory. For each directory entry, the name in
+ * the native encoding is converted back to UTF-8 when reading.
+ *
+ * The implementation returned by this is simple, non-recursive, reporting
+ * directory contents as returned by the OS native API, i.e. not sorted,
+ * and including the "." and ".." entries.
+ *
+ * @param path A path to a directory on the file system.
+ *
+ * @return A pointer to a dir_iterator_t implementation on success,
+ *         NULL on error (message is printed to stderr).
+ */
+SQFS_INTERNAL dir_iterator_t *dir_iterator_create(const char *path);
+
+/**
+ * @brief Create a stacked, recursive directory tree iterator
+ *
+ * The underlying implementation automatically recurses into sub directories
+ * and returns a flattened list of entries, where each entry represents a full
+ * path. Advanced filtering, path pre-fixing et cetera can be configured.
+ * The typical "." and ".." entries are filtered out as well.
+ *
+ * @param path A path to a directory on the file system.
+ * @param cfg A @ref dir_tree_cfg_t filtering configuration.
+ *
+ * @return A pointer to a dir_iterator_t implementation on success,
+ *         NULL on error (message is printed to stderr).
+ */
+SQFS_INTERNAL
+dir_iterator_t *dir_tree_iterator_create(const char *path,
+					 const dir_tree_cfg_t *cfg);
+
+/**
+ * @brief Skip a sub-hierarchy on a stacked iterator
+ *
+ * For an iterator returned by @ref dir_tree_iterator_create, if the last entry
+ * was a directory, do not recurse, but instead skip across the netire sub-tree.
+ *
+ * @param it A pointer to an iterator returned by @ref dir_tree_iterator_create
+ */
+SQFS_INTERNAL void dir_tree_iterator_skip(dir_iterator_t *it);
 
 #ifdef __cplusplus
 }