libfrog/xfs_scrub: improve iteration function documentation

Between libfrog and xfs_scrub, we have several item collection iteration
functions that take a pointer to a function that will be called for
every item in that collection.  They're not well documented, so improve
the description of when they'll be called and what kinds of return
values they expect.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Reviewed-by: Eric Sandeen <sandeen@redhat.com>
Signed-off-by: Eric Sandeen <sandeen@sandeen.net>

diff --git a/libfrog/ptvar.h b/libfrog/ptvar.h
index 42865c0b2fd3e3f6538e81094756064d3052376a..b7d02d6269e80300e596f33ff9eae1875e805710 100644 (file)
--- a/libfrog/ptvar.h
+++ b/libfrog/ptvar.h
@@ -8,11 +8,15 @@
 
 struct ptvar;
 
-typedef int (*ptvar_iter_fn)(struct ptvar *ptv, void *data, void *foreach_arg);
-
 int ptvar_alloc(size_t nr, size_t size, struct ptvar **pptv);
 void ptvar_free(struct ptvar *ptv);
 void *ptvar_get(struct ptvar *ptv, int *ret);
+
+/*
+ * Visit each per-thread value.  Return 0 to continue iteration or nonzero to
+ * stop iterating and return to the caller.
+ */
+typedef int (*ptvar_iter_fn)(struct ptvar *ptv, void *data, void *foreach_arg);
 int ptvar_foreach(struct ptvar *ptv, ptvar_iter_fn fn, void *foreach_arg);
 
 #endif /* __LIBFROG_PTVAR_H__ */

diff --git a/scrub/filemap.h b/scrub/filemap.h
index cb33172982b87b8314b3b4ddc892520635a0ea11..219be57511f050ce037f5accd8e21e4b835fad63 100644 (file)
--- a/scrub/filemap.h
+++ b/scrub/filemap.h
@@ -14,6 +14,10 @@ struct xfs_bmap {
        uint32_t        bm_flags;       /* output flags */
 };
 
+/*
+ * Visit each inode fork mapping.  Return true to continue iteration or false
+ * to stop iterating and return to the caller.
+ */
 typedef bool (*xfs_bmap_iter_fn)(struct scrub_ctx *ctx, const char *descr,
                int fd, int whichfork, struct fsxattr *fsx,
                struct xfs_bmap *bmap, void *arg);

diff --git a/scrub/inodes.h b/scrub/inodes.h
index 3341c6d9edea2d569c6ff692af63463113f61f1f..e58795e7f4c67b2ffeb7d4da5f10da455d5e2f4f 100644 (file)
--- a/scrub/inodes.h
+++ b/scrub/inodes.h
@@ -6,6 +6,12 @@
 #ifndef XFS_SCRUB_INODES_H_
 #define XFS_SCRUB_INODES_H_
 
+/*
+ * Visit each space mapping of an inode fork.  Return 0 to continue iteration
+ * or a positive error code to interrupt iteraton.  If ESTALE is returned,
+ * iteration will be restarted from the beginning of the inode allocation
+ * group.  Any other non zero value will stop iteration.
+ */
 typedef int (*xfs_inode_iter_fn)(struct scrub_ctx *ctx,
                struct xfs_handle *handle, struct xfs_bulkstat *bs, void *arg);
 

diff --git a/scrub/spacemap.h b/scrub/spacemap.h
index 8f2f0a01bdd9c2b9c4bb92084dcdc00c20c53a04..c29c43a51c4a0d7dd3485c134a3a271f3efffb16 100644 (file)
--- a/scrub/spacemap.h
+++ b/scrub/spacemap.h
@@ -6,6 +6,10 @@
 #ifndef XFS_SCRUB_SPACEMAP_H_
 #define XFS_SCRUB_SPACEMAP_H_
 
+/*
+ * Visit each space mapping in the filesystem.  Return true to continue
+ * iteration or false to stop iterating and return to the caller.
+ */
 typedef bool (*xfs_fsmap_iter_fn)(struct scrub_ctx *ctx, const char *descr,
                struct fsmap *fsr, void *arg);
 

diff --git a/scrub/vfs.h b/scrub/vfs.h
index caef8969b0ce4a180bcc8f5278e5b0d3c7284be1..af23674a7ff403fbb46ec0b04f9ef5ec9f004070 100644 (file)
--- a/scrub/vfs.h
+++ b/scrub/vfs.h
@@ -6,8 +6,18 @@
 #ifndef XFS_SCRUB_VFS_H_
 #define XFS_SCRUB_VFS_H_
 
+/*
+ * Visit a subdirectory prior to iterating entries in that subdirectory.
+ * Return true to continue iteration or false to stop iterating and return to
+ * the caller.
+ */
 typedef bool (*scan_fs_tree_dir_fn)(struct scrub_ctx *, const char *,
                int, void *);
+
+/*
+ * Visit each directory entry in a directory.  Return true to continue
+ * iteration or false to stop iterating and return to the caller.
+ */
 typedef bool (*scan_fs_tree_dirent_fn)(struct scrub_ctx *, const char *,
                int, struct dirent *, struct stat *, void *);