Version 1.8.16.

[libguestfs.git] / generator / generator_actions.ml

diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml
index 085d329..781142d 100644 (file)
--- a/generator/generator_actions.ml
+++ b/generator/generator_actions.ml
@@ -1569,7 +1569,12 @@ do not overwrite original.  Overrides C<AUG_SAVE_BACKUP>.
 
 =item C<AUG_TYPE_CHECK> = 4
 
-Typecheck lenses (can be expensive).
+Typecheck lenses.
+
+This option is only useful when debugging Augeas lenses.  Use
+of this option may require additional memory for the libguestfs
+appliance.  You may need to set the C<LIBGUESTFS_MEMSIZE>
+environment variable or call C<guestfs_set_memsize>.
 
 =item C<AUG_NO_STDINC> = 8
 
@@ -2039,15 +2044,12 @@ The exact command which runs is C<file -zb path>.  Note in
 particular that the filename is not prepended to the output
 (the C<-b> option).
 
-This command can also be used on C</dev/> devices
-(and partitions, LV names).  You can for example use this
-to determine if a device contains a filesystem, although
-it's usually better to use C<guestfs_vfs_type>.
+The output depends on the output of the underlying L<file(1)>
+command and it can change in future in ways beyond our control.
+In other words, the output is not guaranteed by the ABI.
 
-If the C<path> does not begin with C</dev/> then
-this command only works for the content of regular files.
-For other file types (directory, symbolic link etc) it
-will just return the string C<directory> etc.");
+See also: L<file(1)>, C<guestfs_vfs_type>, C<guestfs_lstat>,
+C<guestfs_is_file>, C<guestfs_is_blockdev> (etc).");
 
   ("command", (RString "output", [StringList "arguments"], []), 50, [ProtocolLimitWarning],
    [InitScratchFS, Always, TestOutput (
@@ -2741,10 +2743,9 @@ Checking or repairing NTFS volumes is not supported
 This command is entirely equivalent to running C<fsck -a -t fstype device>.");
 
   ("zero", (RErr, [Device "device"], []), 85, [Progress],
-   [InitBasicFS, Always, TestOutput (
+   [InitBasicFS, Always, TestRun (
       [["umount"; "/dev/sda1"];
-       ["zero"; "/dev/sda1"];
-       ["file"; "/dev/sda1"]], "data")],
+       ["zero"; "/dev/sda1"]])],
    "write zeroes to the device",
    "\
 This command writes zeroes over the first few blocks of C<device>.
@@ -2755,7 +2756,7 @@ any partition tables, filesystem superblocks and so on.
 
 See also: C<guestfs_zero_device>, C<guestfs_scrub_device>.");
 
-  ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [],
+  ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [Optional "grub"],
    (* See:
     * https://bugzilla.redhat.com/show_bug.cgi?id=484986
     * https://bugzilla.redhat.com/show_bug.cgi?id=479760
@@ -2765,12 +2766,32 @@ See also: C<guestfs_zero_device>, C<guestfs_scrub_device>.");
        ["write"; "/boot/grub/device.map"; "(hd0) /dev/vda"];
        ["grub_install"; "/"; "/dev/vda"];
        ["is_dir"; "/boot"]])],
-   "install GRUB",
+   "install GRUB 1",
    "\
-This command installs GRUB (the Grand Unified Bootloader) on
+This command installs GRUB 1 (the Grand Unified Bootloader) on
 C<device>, with the root directory being C<root>.
 
-Note: If grub-install reports the error
+Notes:
+
+=over 4
+
+=item *
+
+There is currently no way in the API to install grub2, which
+is used by most modern Linux guests.  It is possible to run
+the grub2 command from the guest, although see the
+caveats in L<guestfs(3)/RUNNING COMMANDS>.
+
+=item *
+
+This uses C<grub-install> from the host.  Unfortunately grub is
+not always compatible with itself, so this only works in rather
+narrow circumstances.  Careful testing with each guest version
+is advisable.
+
+=item *
+
+If grub-install reports the error
 \"No suitable drive was found in the generated device map.\"
 it may be that you need to create a C</boot/grub/device.map>
 file first that contains the mapping between grub device names
@@ -2779,7 +2800,9 @@ a file containing:
 
  (hd0) /dev/vda
 
-replacing C</dev/vda> with the name of the installation device.");
+replacing C</dev/vda> with the name of the installation device.
+
+=back");
 
   ("cp", (RErr, [Pathname "src"; Pathname "dest"], []), 87, [],
    [InitScratchFS, Always, TestOutput (
@@ -5000,6 +5023,15 @@ it to local file C<tarball> (as an xz compressed tar archive).");
    "\
 This command resizes an NTFS filesystem, expanding or
 shrinking it to the size of the underlying device.
+
+I<Note:> After the resize operation, the filesystem is marked
+as requiring a consistency check (for safety).  You have to boot
+into Windows to perform this check and clear this condition.
+Furthermore, ntfsresize refuses to resize filesystems
+which have been marked in this way.  So in effect it is
+not possible to call ntfsresize multiple times on a single
+filesystem without booting into Windows between each resize.
+
 See also L<ntfsresize(8)>.");
 
   ("vgscan", (RErr, [], []), 232, [],