Add comments documenting ext2fs_[reserve_]super_and_bgd_loc()

Add an explanation of exactly what ext2fs_super_and_bgd_loc() and
ext2fs_reserve_super_and_bgd_loc() do, and more importantly, exactly
what they return.  Note that most callers should *not* rely on the
return value since it's rarely useful, especially once the flex_bg
feature is enabled and inode table and allocation bitmap blocks may
not be in the block group.

Signed-off-by: "Theodore Ts'o" <tytso@mit.edu>

diff --git a/lib/ext2fs/alloc_sb.c b/lib/ext2fs/alloc_sb.c
index ef40b93..5bf2db7 100644 (file)
--- a/lib/ext2fs/alloc_sb.c
+++ b/lib/ext2fs/alloc_sb.c
@@ -27,6 +27,19 @@
 #include "ext2_fs.h"
 #include "ext2fs.h"
 
+/*
+ * This function reserves the superblock and block group descriptors
+ * for a given block group.  It currently returns the number of free
+ * blocks assuming that inode table and allocation bitmaps will be in
+ * the group.  This is not necessarily the case when the flex_bg
+ * feature is enabled, so callers should take care!  It was only
+ * really intended for use by mke2fs, and even there it's not that
+ * useful.  In the future, when we redo this function for 64-bit block
+ * numbers, we should probably return the number of blocks used by the
+ * super block and group descriptors instead.
+ *
+ * See also the comment for ext2fs_super_and_bgd_loc()
+ */
 int ext2fs_reserve_super_and_bgd(ext2_filsys fs, 
                                 dgrp_t group,
                                 ext2fs_block_bitmap bmap)

diff --git a/lib/ext2fs/closefs.c b/lib/ext2fs/closefs.c
index 086c28a..206faa6 100644 (file)
--- a/lib/ext2fs/closefs.c
+++ b/lib/ext2fs/closefs.c
@@ -45,6 +45,19 @@ int ext2fs_bg_has_super(ext2_filsys fs, int group_block)
        return 0;
 }
 
+/*
+ * This function returns the location of the superblock, block group
+ * descriptors for a given block group.  It currently returns the
+ * number of free blocks assuming that inode table and allocation
+ * bitmaps will be in the group.  This is not necessarily the case
+ * when the flex_bg feature is enabled, so callers should take care!
+ * It was only really intended for use by mke2fs, and even there it's
+ * not that useful.  In the future, when we redo this function for
+ * 64-bit block numbers, we should probably return the number of
+ * blocks used by the super block and group descriptors instead.
+ *
+ * See also the comment for ext2fs_reserve_super_and_bgd()
+ */
 int ext2fs_super_and_bgd_loc(ext2_filsys fs, 
                             dgrp_t group,
                             blk_t *ret_super_blk,