From 5b7b1c43ab85bb75bdb36844cce1cc124d5df4f2 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Fri, 9 Mar 2012 17:26:19 +0000
Subject: Document error message from resize2fs (RHBZ#755729, RHBZ#801640).

---
 generator/generator_actions.ml | 12 +++++++++---
 src/guestfs.pod                | 26 ++++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml
index 3c87d6db..4c6e704b 100644
--- a/generator/generator_actions.ml
+++ b/generator/generator_actions.ml
@@ -3502,7 +3502,9 @@ is lost.");
    "resize an ext2, ext3 or ext4 filesystem",
    "\
 This resizes an ext2, ext3 or ext4 filesystem to match the size of
-the underlying device.");
+the underlying device.
+
+See also L<guestfs(3)/RESIZE2FS ERRORS>.");
 
   ("find", (RStringList "names", [Pathname "directory"], []), 107, [ProtocolLimitWarning],
    [InitBasicFS, Always, TestOutputList (
@@ -5655,7 +5657,9 @@ See also C<guestfs_pread>, C<guestfs_pwrite_device>.");
    "resize an ext2, ext3 or ext4 filesystem (with size)",
    "\
 This command is the same as C<guestfs_resize2fs> except that it
-allows you to specify the new size (in bytes) explicitly.");
+allows you to specify the new size (in bytes) explicitly.
+
+See also L<guestfs(3)/RESIZE2FS ERRORS>.");
 
   ("pvresize_size", (RErr, [Device "device"; Int64 "size"], []), 249, [Optional "lvm2"],
    [],
@@ -6157,7 +6161,9 @@ to the C<resize2fs> command.
 To get the resulting size of the filesystem you should call
 C<guestfs_tune2fs_l> and read the C<Block size> and C<Block count>
 values.  These two numbers, multiplied together, give the
-resulting size of the minimal filesystem in bytes.");
+resulting size of the minimal filesystem in bytes.
+
+See also L<guestfs(3)/RESIZE2FS ERRORS>.");
 
   ("internal_autosync", (RErr, [], []), 282, [NotInFish; NotInDocs],
    [],
diff --git a/src/guestfs.pod b/src/guestfs.pod
index 3664ccf0..531d123b 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -703,6 +703,32 @@ ntfs-3g filesystems (using L</guestfs_getxattr>).  See:
 
 L<http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/>
 
+=head2 RESIZE2FS ERRORS
+
+The L</guestfs_resize2fs>, L</guestfs_resize2fs_size> and
+L</guestfs_resize2fs_M> calls are used to resize ext2/3/4 filesystems.
+
+The underlying program (L<resize2fs(8)>) requires that the filesystem
+is clean and recently fsck'd before you can resize it.  Also, if the
+resize operation fails for some reason, then you had to call fsck the
+filesystem again to fix it.
+
+In libguestfs C<lt> 1.17.14, you usually had to call
+L</guestfs_e2fsck_f> before the resize.  However, in C<ge> 1.17.14,
+L<e2fsck(8)> is called automatically before the resize, so you no
+longer need to do this.
+
+The L<resize2fs(8)> program can still fail, in which case it prints an
+error message similar to:
+
+ Please run 'e2fsck -fy <device>' to fix the filesystem
+ after the aborted resize operation.
+
+You can do this by calling L</guestfs_e2fsck> with the C<forceall>
+option.  However in the context of disk images, it is usually better
+to avoid this situation, eg. by rolling back to an earlier snapshot,
+or by copying and resizing and on failure going back to the original.
+
 =head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
 
 Although we don't want to discourage you from using the C API, we will
-- 
cgit