Note that additional memory may be required to typecheck Augeas lenses (RHBZ#729887).
[libguestfs.git] / generator / generator_actions.ml
index 50c33a8..c684e35 100644 (file)
@@ -1,5 +1,5 @@
 (* libguestfs
- * Copyright (C) 2009-2010 Red Hat Inc.
+ * Copyright (C) 2009-2011 Red Hat Inc.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -103,7 +103,7 @@ You probably don't want to call this function.")]
  *)
 
 let non_daemon_functions = test_functions @ [
-  ("launch", (RErr, [], []), -1, [FishAlias "run"],
+  ("launch", (RErr, [], []), -1, [FishAlias "run"; Progress],
    [],
    "launch the qemu subprocess",
    "\
@@ -113,7 +113,7 @@ using L<qemu(1)>.
 You should call this after configuring the handle
 (eg. adding drives) but before performing any actions.");
 
-  ("wait_ready", (RErr, [], []), -1, [NotInFish],
+  ("wait_ready", (RErr, [], []), -1, [NotInFish; DeprecatedBy "launch"],
    [],
    "wait until the qemu subprocess launches (no op)",
    "\
@@ -155,7 +155,7 @@ and specifying the format.");
    "\
 This function adds a virtual CD-ROM disk image to the guest.
 
-This is equivalent to the qemu parameter C<-cdrom filename>.
+This is equivalent to the qemu parameter I<-cdrom filename>.
 
 Notes:
 
@@ -190,7 +190,7 @@ automatically.");
    "add qemu parameters",
    "\
 This can be used to add arbitrary qemu command line parameters
-of the form C<-param value>.  Actually it's not quite arbitrary - we
+of the form I<-param value>.  Actually it's not quite arbitrary - we
 prevent you from setting some parameters which would interfere with
 parameters that we use.
 
@@ -282,8 +282,8 @@ If C<NULL> then no options are added.");
    "set autosync mode",
    "\
 If C<autosync> is true, this enables autosync.  Libguestfs will make a
-best effort attempt to run C<guestfs_umount_all> followed by
-C<guestfs_sync> when the handle is closed
+best effort attempt to make filesystems consistent and synchronized
+when the handle is closed
 (also if the program exits without closing handles).
 
 This is enabled by default (since libguestfs 1.5.24, previously it was
@@ -300,10 +300,14 @@ Get the autosync flag.");
    [],
    "set verbose mode",
    "\
-If C<verbose> is true, this turns on verbose messages (to C<stderr>).
+If C<verbose> is true, this turns on verbose messages.
 
 Verbose messages are disabled unless the environment variable
-C<LIBGUESTFS_DEBUG> is defined and set to C<1>.");
+C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
+
+Verbose messages are normally sent to C<stderr>, unless you
+register a callback to send them somewhere else (see
+C<guestfs_set_event_callback>).");
 
   ("get_verbose", (RBool "verbose", [], []), -1, [],
    [],
@@ -469,19 +473,19 @@ see L<guestfs(3)>.");
        ["get_trace"]])],
    "enable or disable command traces",
    "\
-If the command trace flag is set to 1, then commands are
-printed on stderr before they are executed in a format
-which is very similar to the one used by guestfish.  In
-other words, you can run a program with this enabled, and
-you will get out a script which you can feed to guestfish
-to perform the same set of actions.
+If the command trace flag is set to 1, then libguestfs
+calls, parameters and return values are traced.
 
 If you want to trace C API calls into libguestfs (and
 other libraries) then possibly a better way is to use
 the external ltrace(1) command.
 
 Command traces are disabled unless the environment variable
-C<LIBGUESTFS_TRACE> is defined and set to C<1>.");
+C<LIBGUESTFS_TRACE> is defined and set to C<1>.
+
+Trace messages are normally sent to C<stderr>, unless you
+register a callback to send them somewhere else (see
+C<guestfs_set_event_callback>).");
 
   ("get_trace", (RBool "trace", [], []), -1, [],
    [],
@@ -722,9 +726,6 @@ See also C<guestfs_list_filesystems>.");
    [],
    "get type of inspected operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 This returns the type of the inspected operating system.
 Currently defined types are:
 
@@ -757,9 +758,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get architecture of inspected operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 This returns the architecture of the inspected operating system.
 The possible return values are listed under
 C<guestfs_file_architecture>.
@@ -773,9 +771,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get distro of inspected operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 This returns the distro (distribution) of the inspected operating
 system.
 
@@ -787,6 +782,10 @@ Currently defined distros are:
 
 Arch Linux.
 
+=item \"centos\"
+
+CentOS.
+
 =item \"debian\"
 
 Debian.
@@ -821,7 +820,15 @@ Some Red Hat-derived distro.
 
 =item \"rhel\"
 
-Red Hat Enterprise Linux and some derivatives.
+Red Hat Enterprise Linux.
+
+=item \"scientificlinux\"
+
+Scientific Linux.
+
+=item \"slackware\"
+
+Slackware.
 
 =item \"ubuntu\"
 
@@ -847,9 +854,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get major version of inspected operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 This returns the major version number of the inspected operating
 system.
 
@@ -868,9 +872,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get minor version of inspected operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 This returns the minor version number of the inspected operating
 system.
 
@@ -883,9 +884,6 @@ See also C<guestfs_inspect_get_major_version>.");
    [],
    "get product name of inspected operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 This returns the product name of the inspected operating
 system.  The product name is generally some freeform string
 which can be displayed to the user, but should not be
@@ -900,9 +898,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get mountpoints of inspected operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 This returns a hash of where we think the filesystems
 associated with this operating system should be mounted.
 Callers should note that this is at best an educated guess
@@ -920,6 +915,12 @@ which is the filesystem that would be mounted there
 Non-mounted devices such as swap devices are I<not>
 returned in this list.
 
+For operating systems like Windows which still use drive
+letters, this call will only return an entry for the first
+drive \"mounted on\" C</>.  For information about the
+mapping of drive letters to partitions, see
+C<guestfs_inspect_get_drive_mappings>.
+
 Please read L<guestfs(3)/INSPECTION> for more details.
 See also C<guestfs_inspect_get_filesystems>.");
 
@@ -927,9 +928,6 @@ See also C<guestfs_inspect_get_filesystems>.");
    [],
    "get filesystems associated with inspected operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 This returns a list of all the filesystems that we think
 are associated with this operating system.  This includes
 the root filesystem, other ordinary filesystems, and
@@ -1042,9 +1040,6 @@ deprecated C<guestfs_add_drive_with_if> call (q.v.)
    [],
    "get Windows systemroot of inspected operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 This returns the Windows systemroot of the inspected guest.
 The systemroot is a directory path such as C</WINDOWS>.
 
@@ -1074,7 +1069,7 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
 This returns the internal QEMU command line.  'debug' commands are
 not part of the formal API and can be removed or changed at any time.");
 
-  ("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"]), -1, [FishAlias "domain"],
+  ("add_domain", (RInt "nrdisks", [String "dom"], [String "libvirturi"; Bool "readonly"; String "iface"; Bool "live"; Bool "allowuuid"]), -1, [FishAlias "domain"],
    [],
    "add the disk(s) from a named libvirt domain",
    "\
@@ -1101,12 +1096,24 @@ we connect to the default libvirt URI (or one set through an
 environment variable, see the libvirt documentation for full
 details).
 
+The optional C<live> flag controls whether this call will try
+to connect to a running virtual machine C<guestfsd> process if
+it sees a suitable E<lt>channelE<gt> element in the libvirt
+XML definition.  The default (if the flag is omitted) is never
+to try.  See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more
+information.
+
+If the C<allowuuid> flag is true (default is false) then a UUID
+I<may> be passed instead of the domain name.  The C<dom> string is
+treated as a UUID first and looked up, and if that lookup fails
+then we treat C<dom> as a name as usual.
+
 The other optional parameters are passed directly through to
 C<guestfs_add_drive_opts>.");
 
 (*
 This interface is not quite baked yet. -- RWMJ 2010-11-11
-  ("add_libvirt_dom", (RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [Bool "readonly"; String "iface"]), -1, [NotInFish],
+  ("add_libvirt_dom", (RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [Bool "readonly"; String "iface"; Bool "live"]), -1, [NotInFish],
    [],
    "add the disk(s) from a libvirt domain",
    "\
@@ -1129,7 +1136,14 @@ from a remote libvirt connection (see L<http://libvirt.org/remote.html>)
 will fail unless those disks are accessible via the same device path
 locally too.
 
-The optional parameters are passed directly through to
+The optional C<live> flag controls whether this call will try
+to connect to a running virtual machine C<guestfsd> process if
+it sees a suitable E<lt>channelE<gt> element in the libvirt
+XML definition.  The default (if the flag is omitted) is never
+to try.  See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more
+information.
+
+The other optional parameters are passed directly through to
 C<guestfs_add_drive_opts>.");
 *)
 
@@ -1137,9 +1151,6 @@ C<guestfs_add_drive_opts>.");
    [],
    "get package format used by the operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 This function and C<guestfs_inspect_get_package_management> return
 the package format and package management tool used by the
 inspected operating system.  For example for Fedora these
@@ -1159,9 +1170,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get package management tool used by the operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 C<guestfs_inspect_get_package_format> and this function return
 the package format and package management tool used by the
 inspected operating system.  For example for Fedora these
@@ -1183,9 +1191,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get list of applications installed in the operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 Return the list of applications installed in the operating system.
 
 I<Note:> This call works differently from other parts of the
@@ -1282,9 +1287,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get hostname of the operating system",
    "\
-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-
 This function returns the hostname of the operating system
 as found by inspection of the guest's configuration files.
 
@@ -1293,6 +1295,256 @@ string C<unknown> is returned.
 
 Please read L<guestfs(3)/INSPECTION> for more details.");
 
+  ("inspect_get_format", (RString "format", [Device "root"], []), -1, [],
+   [],
+   "get format of inspected operating system",
+   "\
+This returns the format of the inspected operating system.  You
+can use it to detect install images, live CDs and similar.
+
+Currently defined formats are:
+
+=over 4
+
+=item \"installed\"
+
+This is an installed operating system.
+
+=item \"installer\"
+
+The disk image being inspected is not an installed operating system,
+but a I<bootable> install disk, live CD, or similar.
+
+=item \"unknown\"
+
+The format of this disk image is not known.
+
+=back
+
+Future versions of libguestfs may return other strings here.
+The caller should be prepared to handle any string.
+
+Please read L<guestfs(3)/INSPECTION> for more details.");
+
+  ("inspect_is_live", (RBool "live", [Device "root"], []), -1, [],
+   [],
+   "get live flag for install disk",
+   "\
+If C<guestfs_inspect_get_format> returns C<installer> (this
+is an install disk), then this returns true if a live image
+was detected on the disk.
+
+Please read L<guestfs(3)/INSPECTION> for more details.");
+
+  ("inspect_is_netinst", (RBool "netinst", [Device "root"], []), -1, [],
+   [],
+   "get netinst (network installer) flag for install disk",
+   "\
+If C<guestfs_inspect_get_format> returns C<installer> (this
+is an install disk), then this returns true if the disk is
+a network installer, ie. not a self-contained install CD but
+one which is likely to require network access to complete
+the install.
+
+Please read L<guestfs(3)/INSPECTION> for more details.");
+
+  ("inspect_is_multipart", (RBool "multipart", [Device "root"], []), -1, [],
+   [],
+   "get multipart flag for install disk",
+   "\
+If C<guestfs_inspect_get_format> returns C<installer> (this
+is an install disk), then this returns true if the disk is
+part of a set.
+
+Please read L<guestfs(3)/INSPECTION> for more details.");
+
+  ("set_attach_method", (RErr, [String "attachmethod"], []), -1, [FishAlias "attach-method"],
+   [],
+   "set the attach method",
+   "\
+Set the method that libguestfs uses to connect to the back end
+guestfsd daemon.  Possible methods are:
+
+=over 4
+
+=item C<appliance>
+
+Launch an appliance and connect to it.  This is the ordinary method
+and the default.
+
+=item C<unix:I<path>>
+
+Connect to the Unix domain socket I<path>.
+
+This method lets you connect to an existing daemon or (using
+virtio-serial) to a live guest.  For more information, see
+L<guestfs(3)/ATTACHING TO RUNNING DAEMONS>.
+
+=back");
+
+  ("get_attach_method", (RString "attachmethod", [], []), -1, [],
+   [InitNone, Always, TestOutput (
+      [["get_attach_method"]], "appliance")],
+   "get the attach method",
+   "\
+Return the current attach method.  See C<guestfs_set_attach_method>.");
+
+  ("inspect_get_product_variant", (RString "variant", [Device "root"], []), -1, [],
+   [],
+   "get product variant of inspected operating system",
+   "\
+This returns the product variant of the inspected operating
+system.
+
+For Windows guests, this returns the contents of the Registry key
+C<HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion>
+C<InstallationType> which is usually a string such as
+C<Client> or C<Server> (other values are possible).  This
+can be used to distinguish consumer and enterprise versions
+of Windows that have the same version number (for example,
+Windows 7 and Windows 2008 Server are both version 6.1,
+but the former is C<Client> and the latter is C<Server>).
+
+For enterprise Linux guests, in future we intend this to return
+the product variant such as C<Desktop>, C<Server> and so on.  But
+this is not implemented at present.
+
+If the product variant could not be determined, then the
+string C<unknown> is returned.
+
+Please read L<guestfs(3)/INSPECTION> for more details.
+See also C<guestfs_inspect_get_product_name>,
+C<guestfs_inspect_get_major_version>.");
+
+  ("inspect_get_windows_current_control_set", (RString "controlset", [Device "root"], []), -1, [],
+   [],
+   "get Windows CurrentControlSet of inspected operating system",
+   "\
+This returns the Windows CurrentControlSet of the inspected guest.
+The CurrentControlSet is a registry key name such as C<ControlSet001>.
+
+This call assumes that the guest is Windows and that the
+Registry could be examined by inspection.  If this is not
+the case then an error is returned.
+
+Please read L<guestfs(3)/INSPECTION> for more details.");
+
+  ("inspect_get_drive_mappings", (RHashtable "drives", [Device "root"], []), -1, [],
+   [],
+   "get drive letter mappings",
+   "\
+This call is useful for Windows which uses a primitive system
+of assigning drive letters (like \"C:\") to partitions.
+This inspection API examines the Windows Registry to find out
+how disks/partitions are mapped to drive letters, and returns
+a hash table as in the example below:
+
+ C      =>     /dev/vda2
+ E      =>     /dev/vdb1
+ F      =>     /dev/vdc1
+
+Note that keys are drive letters.  For Windows, the key is
+case insensitive and just contains the drive letter, without
+the customary colon separator character.
+
+In future we may support other operating systems that also used drive
+letters, but the keys for those might not be case insensitive
+and might be longer than 1 character.  For example in OS-9,
+hard drives were named C<h0>, C<h1> etc.
+
+For Windows guests, currently only hard drive mappings are
+returned.  Removable disks (eg. DVD-ROMs) are ignored.
+
+For guests that do not use drive mappings, or if the drive mappings
+could not be determined, this returns an empty hash table.
+
+Please read L<guestfs(3)/INSPECTION> for more details.
+See also C<guestfs_inspect_get_mountpoints>,
+C<guestfs_inspect_get_filesystems>.");
+
+  ("inspect_get_icon", (RBufferOut "icon", [Device "root"],  [Bool "favicon"; Bool "highquality"]), -1, [],
+   [],
+   "get the icon corresponding to this operating system",
+   "\
+This function returns an icon corresponding to the inspected
+operating system.  The icon is returned as a buffer containing a
+PNG image (re-encoded to PNG if necessary).
+
+If it was not possible to get an icon this function returns a
+zero-length (non-NULL) buffer.  I<Callers must check for this case>.
+
+Libguestfs will start by looking for a file called
+C</etc/favicon.png> or C<C:\\etc\\favicon.png>
+and if it has the correct format, the contents of this file will
+be returned.  You can disable favicons by passing the
+optional C<favicon> boolean as false (default is true).
+
+If finding the favicon fails, then we look in other places in the
+guest for a suitable icon.
+
+If the optional C<highquality> boolean is true then
+only high quality icons are returned, which means only icons of
+high resolution with an alpha channel.  The default (false) is
+to return any icon we can, even if it is of substandard quality.
+
+Notes:
+
+=over 4
+
+=item *
+
+Unlike most other inspection API calls, the guest's disks must be
+mounted up before you call this, since it needs to read information
+from the guest filesystem during the call.
+
+=item *
+
+B<Security:> The icon data comes from the untrusted guest,
+and should be treated with caution.  PNG files have been
+known to contain exploits.  Ensure that libpng (or other relevant
+libraries) are fully up to date before trying to process or
+display the icon.
+
+=item *
+
+The PNG image returned can be any size.  It might not be square.
+Libguestfs tries to return the largest, highest quality
+icon available.  The application must scale the icon to the
+required size.
+
+=item *
+
+Extracting icons from Windows guests requires the external
+C<wrestool> program from the C<icoutils> package, and
+several programs (C<bmptopnm>, C<pnmtopng>, C<pamcut>)
+from the C<netpbm> package.  These must be installed separately.
+
+=item *
+
+Operating system icons are usually trademarks.  Seek legal
+advice before using trademarks in applications.
+
+=back");
+
+  ("set_pgroup", (RErr, [Bool "pgroup"], []), -1, [FishAlias "pgroup"],
+   [],
+   "set process group flag",
+   "\
+If C<pgroup> is true, child processes are placed into
+their own process group.
+
+The practical upshot of this is that signals like C<SIGINT> (from
+users pressing C<^C>) won't be received by the child process.
+
+The default for this flag is false, because usually you want
+C<^C> to kill the subprocess.");
+
+  ("get_pgroup", (RBool "pgroup", [], []), -1, [],
+   [],
+   "get process group flag",
+   "\
+This returns the process group flag.");
+
 ]
 
 (* daemon_functions are any functions which cause some action
@@ -1300,7 +1552,7 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
  *)
 
 let daemon_functions = [
-  ("mount", (RErr, [Device "device"; String "mountpoint"], []), 1, [],
+  ("mount", (RErr, [Device "device"; String "mountpoint"], []), 1, [DeprecatedBy "mount_options"],
    [InitEmpty, Always, TestOutput (
       [["part_disk"; "/dev/sda"; "mbr"];
        ["mkfs"; "ext2"; "/dev/sda1"];
@@ -1569,7 +1821,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
 
@@ -1908,7 +2165,7 @@ example C<ext3>.");
 
   ("sfdisk", (RErr, [Device "device";
                      Int "cyls"; Int "heads"; Int "sectors";
-                     StringList "lines"], []), 43, [DangerWillRobinson],
+                     StringList "lines"], []), 43, [DangerWillRobinson; DeprecatedBy "part_add"],
    [],
    "create partitions on a block device",
    "\
@@ -2037,17 +2294,14 @@ of compressed file.
 
 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).
+(the I<-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), C<guestfs_is_zero>.");
 
   ("command", (RString "output", [StringList "arguments"], []), 50, [ProtocolLimitWarning],
    [InitScratchFS, Always, TestOutput (
@@ -2741,10 +2995,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>.
@@ -2753,7 +3006,8 @@ How many blocks are zeroed isn't specified (but it's I<not> enough
 to securely wipe the device).  It should be sufficient to remove
 any partition tables, filesystem superblocks and so on.
 
-See also: C<guestfs_zero_device>, C<guestfs_scrub_device>.");
+See also: C<guestfs_zero_device>, C<guestfs_scrub_device>,
+C<guestfs_is_zero_device>");
 
   ("grub_install", (RErr, [Pathname "root"; Device "device"], []), 86, [],
    (* See:
@@ -2999,7 +3253,7 @@ volume to match the new size of the underlying device.");
 
   ("sfdisk_N", (RErr, [Device "device"; Int "partnum";
                        Int "cyls"; Int "heads"; Int "sectors";
-                       String "line"], []), 99, [DangerWillRobinson],
+                       String "line"], []), 99, [DangerWillRobinson; DeprecatedBy "part_add"],
    [],
    "modify a single partition on a block device",
    "\
@@ -3011,7 +3265,7 @@ pass C<0> for the cyls/heads/sectors parameters.
 
 See also: C<guestfs_part_add>");
 
-  ("sfdisk_l", (RString "partitions", [Device "device"], []), 100, [],
+  ("sfdisk_l", (RString "partitions", [Device "device"], []), 100, [DeprecatedBy "part_list"],
    [],
    "display the partition table",
    "\
@@ -3048,9 +3302,6 @@ be parsed.");
    "\
 This command activates or (if C<activate> is false) deactivates
 all logical volumes in all volume groups.
-If activated, then they are made known to the
-kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
-then those devices disappear.
 
 This command is the same as running C<vgchange -a y|n>");
 
@@ -3060,9 +3311,6 @@ This command is the same as running C<vgchange -a y|n>");
    "\
 This command activates or (if C<activate> is false) deactivates
 all logical volumes in the listed volume groups C<volgroups>.
-If activated, then they are made known to the
-kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
-then those devices disappear.
 
 This command is the same as running C<vgchange -a y|n volgroups...>
 
@@ -3156,8 +3404,8 @@ See also C<guestfs_find0>.");
    "check an ext2/ext3 filesystem",
    "\
 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
-filesystem checker on C<device>, noninteractively (C<-p>),
-even if the filesystem appears to be clean (C<-f>).
+filesystem checker on C<device>, noninteractively (I<-p>),
+even if the filesystem appears to be clean (I<-f>).
 
 This command is only needed because of C<guestfs_resize2fs>
 (q.v.).  Normally you should use C<guestfs_fsck>.");
@@ -3419,7 +3667,7 @@ This command is mostly useful for interactive sessions.  It
 is I<not> intended that you try to parse the output string.
 Use C<guestfs_statvfs> from programs.");
 
-  ("du", (RInt64 "sizekb", [Pathname "path"], []), 127, [],
+  ("du", (RInt64 "sizekb", [Pathname "path"], []), 127, [Progress],
    [InitISOFS, Always, TestOutputInt (
       [["du"; "/directory"]], 2 (* ISO fs blocksize is 2K *))],
    "estimate file space usage",
@@ -3630,7 +3878,7 @@ This function is primarily intended for use by programs.  To
 get a simple list of names, use C<guestfs_ls>.  To get a printable
 directory for human consumption, use C<guestfs_ll>.");
 
-  ("sfdiskM", (RErr, [Device "device"; StringList "lines"], []), 139, [DangerWillRobinson],
+  ("sfdiskM", (RErr, [Device "device"; StringList "lines"], []), 139, [DangerWillRobinson; DeprecatedBy "part_add"],
    [],
    "create partitions on a block device",
    "\
@@ -3767,7 +4015,7 @@ pathnames, as in the example code above.
 For more details see L<https://bugzilla.redhat.com/show_bug.cgi?id=599503>
 
 Autosync [see C<guestfs_set_autosync>, this is set by default on
-handles] means that C<guestfs_umount_all> is called when the handle
+handles] can cause C<guestfs_umount_all> to be called when the handle
 is closed which can also trigger these issues.");
 
   ("rmmountpoint", (RErr, [String "exemptpath"], []), 149, [],
@@ -3933,7 +4181,7 @@ This command creates a hard link using the C<ln> command.");
    "create a hard link",
    "\
 This command creates a hard link using the C<ln -f> command.
-The C<-f> option removes the link (C<linkname>) if it exists already.");
+The I<-f> option removes the link (C<linkname>) if it exists already.");
 
   ("ln_s", (RErr, [String "target"; Pathname "linkname"], []), 166, [],
    [InitScratchFS, Always, TestOutputStruct (
@@ -3954,7 +4202,7 @@ This command creates a symbolic link using the C<ln -s> command.");
    "create a symbolic link",
    "\
 This command creates a symbolic link using the C<ln -sf> command,
-The C<-f> option removes the link (C<linkname>) if it exists already.");
+The I<-f> option removes the link (C<linkname>) if it exists already.");
 
   ("readlink", (RString "link", [Pathname "path"], []), 168, [],
    [] (* XXX tested above *),
@@ -4600,7 +4848,9 @@ Possible values for C<parttype> are:
 
 =over 4
 
-=item B<efi> | B<gpt>
+=item B<efi>
+
+=item B<gpt>
 
 Intel EFI / GPT partition table.
 
@@ -4608,7 +4858,9 @@ This is recommended for >= 2 TB partitions that will be accessed
 from Linux and Intel-based Mac OS X.  It also has limited backwards
 compatibility with the C<mbr> format.
 
-=item B<mbr> | B<msdos>
+=item B<mbr>
+
+=item B<msdos>
 
 The standard PC \"Master Boot Record\" (MBR) format used
 by MS-DOS and Windows.  This partition type will B<only> work
@@ -4626,7 +4878,9 @@ supported include:
 
 AIX disk labels.
 
-=item B<amiga> | B<rdb>
+=item B<amiga>
+
+=item B<rdb>
 
 Amiga \"Rigid Disk Block\" format.
 
@@ -4994,12 +5248,21 @@ I<xz compressed> tar file) into C<directory>.");
 This command packs the contents of C<directory> and downloads
 it to local file C<tarball> (as an xz compressed tar archive).");
 
-  ("ntfsresize", (RErr, [Device "device"], []), 231, [Optional "ntfsprogs"],
+  ("ntfsresize", (RErr, [Device "device"], []), 231, [Optional "ntfsprogs"; DeprecatedBy "ntfsresize_opts"],
    [],
    "resize an NTFS filesystem",
    "\
 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, [],
@@ -5181,7 +5444,9 @@ to ensure the length of the file is exactly C<len> bytes.");
    "create a new file",
    "\
 This call creates a file called C<path>.  The content of the
-file is the string C<content> (which can contain any 8 bit data).");
+file is the string C<content> (which can contain any 8 bit data).
+
+See also C<guestfs_write_append>.");
 
   ("pwrite", (RInt "nbytes", [Pathname "path"; BufferIn "content"; Int64 "offset"], []), 247, [ProtocolLimitWarning],
    [InitScratchFS, Always, TestOutput (
@@ -5223,7 +5488,7 @@ allows you to specify the new size (in bytes) explicitly.");
 This command is the same as C<guestfs_pvresize> except that it
 allows you to specify the new size (in bytes) explicitly.");
 
-  ("ntfsresize_size", (RErr, [Device "device"; Int64 "size"], []), 250, [Optional "ntfsprogs"],
+  ("ntfsresize_size", (RErr, [Device "device"; Int64 "size"], []), 250, [Optional "ntfsprogs"; DeprecatedBy "ntfsresize_opts"],
    [],
    "resize an NTFS filesystem (with size)",
    "\
@@ -5350,7 +5615,10 @@ encrypted to the underlying C<device> respectively.
 
 If this block device contains LVM volume groups, then
 calling C<guestfs_vgscan> followed by C<guestfs_vg_activate_all>
-will make them visible.");
+will make them visible.
+
+Use C<guestfs_list_dm_devices> to list all device mapper
+devices.");
 
   ("luks_open_ro", (RErr, [Device "device"; Key "key"; String "mapname"], []), 258, [Optional "luks"],
    [],
@@ -5608,10 +5876,10 @@ not refer to a logical volume.
 
 See also C<guestfs_is_lv>.");
 
-  ("mkfs_opts", (RErr, [String "fstype"; Device "device"], [Int "blocksize"]), 278, [],
+  ("mkfs_opts", (RErr, [String "fstype"; Device "device"], [Int "blocksize"; String "features"; Int "inode"; Int "sectorsize"]), 278, [],
    [InitEmpty, Always, TestOutput (
       [["part_disk"; "/dev/sda"; "mbr"];
-       ["mkfs_opts"; "ext2"; "/dev/sda1"; "4096"];
+       ["mkfs_opts"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""];
        ["mount_options"; ""; "/dev/sda1"; "/"];
        ["write"; "/new"; "new file contents"];
        ["cat"; "/new"]], "new file contents")],
@@ -5633,6 +5901,29 @@ for Linux ext2/3 filesystems.
 For VFAT and NTFS the C<blocksize> parameter is treated as
 the requested cluster size.
 
+For UFS block sizes, please see L<mkfs.ufs(8)>.
+
+=item C<features>
+
+This passes the I<-O> parameter to the external mkfs program.
+
+For certain filesystem types, this allows extra filesystem
+features to be selected.  See L<mke2fs(8)> and L<mkfs.ufs(8)>
+for more details.
+
+You cannot use this optional parameter with the C<gfs> or
+C<gfs2> filesystem type.
+
+=item C<inode>
+
+This passes the I<-I> parameter to the external L<mke2fs(8)> program
+which sets the inode size (only for ext2/3/4 filesystems at present).
+
+=item C<sectorsize>
+
+This passes the I<-S> parameter to external L<mkfs.ufs(8)> program,
+which sets sector size for ufs filesystem.
+
 =back");
 
   ("getxattr", (RBufferOut "xattr", [Pathname "path"; String "name"], []), 279, [Optional "linuxxattrs"],
@@ -5680,7 +5971,7 @@ See also: C<guestfs_lgetxattrs>, C<guestfs_getxattr>, L<attr(5)>.");
    "resize an ext2, ext3 or ext4 filesystem to the minimum size",
    "\
 This command is the same as C<guestfs_resize2fs>, but the filesystem
-is resized to its minimum size.  This works like the C<-M> option
+is resized to its minimum size.  This works like the I<-M> option
 to the C<resize2fs> command.
 
 To get the resulting size of the filesystem you should call
@@ -5688,6 +5979,139 @@ 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.");
 
+  ("internal_autosync", (RErr, [], []), 282, [NotInFish; NotInDocs],
+   [],
+   "internal autosync operation",
+   "\
+This command performs the autosync operation just before the
+handle is closed.  You should not call this command directly.
+Instead, use the autosync flag (C<guestfs_set_autosync>) to
+control whether or not this operation is performed when the
+handle is closed.");
+
+  ("is_zero", (RBool "zeroflag", [Pathname "path"], []), 283, [],
+   [InitISOFS, Always, TestOutputTrue (
+      [["is_zero"; "/100kallzeroes"]]);
+    InitISOFS, Always, TestOutputFalse (
+      [["is_zero"; "/100kallspaces"]])],
+   "test if a file contains all zero bytes",
+   "\
+This returns true iff the file exists and the file is empty or
+it contains all zero bytes.");
+
+  ("is_zero_device", (RBool "zeroflag", [Device "device"], []), 284, [],
+   [InitBasicFS, Always, TestOutputTrue (
+      [["umount"; "/dev/sda1"];
+       ["zero_device"; "/dev/sda1"];
+       ["is_zero_device"; "/dev/sda1"]]);
+    InitBasicFS, Always, TestOutputFalse (
+      [["is_zero_device"; "/dev/sda1"]])],
+   "test if a device contains all zero bytes",
+   "\
+This returns true iff the device exists and contains all zero bytes.
+
+Note that for large devices this can take a long time to run.");
+
+  ("list_9p", (RStringList "mounttags", [], []), 285, [],
+   [],
+   "list 9p filesystems",
+   "\
+List all 9p filesystems attached to the guest.  A list of
+mount tags is returned.");
+
+  ("mount_9p", (RErr, [String "mounttag"; String "mountpoint"], [String "options"]), 286, [],
+   [],
+   "mount 9p filesystem",
+   "\
+Mount the virtio-9p filesystem with the tag C<mounttag> on the
+directory C<mountpoint>.
+
+If required, C<trans=virtio> will be automatically added to the options.
+Any other options required can be passed in the optional C<options>
+parameter.");
+
+  ("list_dm_devices", (RStringList "devices", [], []), 287, [],
+   [],
+   "list device mapper devices",
+   "\
+List all device mapper devices.
+
+The returned list contains C</dev/mapper/*> devices, eg. ones created
+by a previous call to C<guestfs_luks_open>.
+
+Device mapper devices which correspond to logical volumes are I<not>
+returned in this list.  Call C<guestfs_lvs> if you want to list logical
+volumes.");
+
+  ("ntfsresize_opts", (RErr, [Device "device"], [Int64 "size"; Bool "force"]), 288, [Optional "ntfsprogs"],
+   [],
+   "resize an NTFS filesystem",
+   "\
+This command resizes an NTFS filesystem, expanding or
+shrinking it to the size of the underlying device.
+
+The optional parameters are:
+
+=over 4
+
+=item C<size>
+
+The new size (in bytes) of the filesystem.  If omitted, the filesystem
+is resized to fit the container (eg. partition).
+
+=item C<force>
+
+If this option is true, then force the resize of the filesystem
+even if the filesystem is marked as requiring a consistency check.
+
+After the resize operation, the filesystem is always marked
+as requiring a consistency check (for safety).  You have to boot
+into Windows to perform this check and clear this condition.
+If you I<don't> set the C<force> option then it is not
+possible to call C<guestfs_ntfsresize_opts> multiple times on a
+single filesystem without booting into Windows between each resize.
+
+=back
+
+See also L<ntfsresize(8)>.");
+
+  ("btrfs_filesystem_resize", (RErr, [Pathname "mountpoint"], [Int64 "size"]), 289, [Optional "btrfs"],
+   [],
+   "resize a btrfs filesystem",
+   "\
+This command resizes a btrfs filesystem.
+
+Note that unlike other resize calls, the filesystem has to be
+mounted and the parameter is the mountpoint not the device
+(this is a requirement of btrfs itself).
+
+The optional parameters are:
+
+=over 4
+
+=item C<size>
+
+The new size (in bytes) of the filesystem.  If omitted, the filesystem
+is resized to the maximum size.
+
+=back
+
+See also L<btrfs(8)>.");
+
+  ("write_append", (RErr, [Pathname "path"; BufferIn "content"], []), 290, [ProtocolLimitWarning],
+   [InitScratchFS, Always, TestOutput (
+      [["write"; "/write_append"; "line1\n"];
+       ["write_append"; "/write_append"; "line2\n"];
+       ["write_append"; "/write_append"; "line3a"];
+       ["write_append"; "/write_append"; "line3b\n"];
+       ["cat"; "/write_append"]], "line1\nline2\nline3aline3b\n")],
+   "append content to end of file",
+   "\
+This call appends C<content> to the end of file C<path>.  If
+C<path> does not exist, then a new file is created.
+
+See also C<guestfs_write>.");
+
 ]
 
 let all_functions = non_daemon_functions @ daemon_functions
@@ -5766,6 +6190,20 @@ them with the help of L</glob> like this:
 
  glob copy-out /home/* .");
 
+  ("display", (RErr,[], []), -1, [], [],
+   "display an image",
+   " display filename
+
+Use C<display> (a graphical display program) to display an image
+file.  It downloads the file, and runs C<display> on it.
+
+To use an alternative program, set the C<GUESTFISH_DISPLAY_IMAGE>
+environment variable.  For example to use the GNOME display program:
+
+ export GUESTFISH_DISPLAY_IMAGE=eog
+
+See also L<display(1)>.");
+
   ("echo", (RErr,[], []), -1, [], [],
    "display a line of text",
    " echo [params ...]
@@ -5862,6 +6300,17 @@ Close and reopen the libguestfs handle.  It is not necessary to use
 this normally, because the handle is closed properly when guestfish
 exits.  However this is occasionally useful for testing.");
 
+  ("setenv", (RErr,[], []), -1, [], [],
+   "set an environment variable",
+   "  setenv VAR value
+
+Set the environment variable C<VAR> to the string C<value>.
+
+To print the value of an environment variable use a shell command
+such as:
+
+ !echo $VAR");
+
   ("sparse", (RErr,[], []), -1, [], [],
    "create a sparse disk image and add",
    " sparse filename size
@@ -5896,4 +6345,10 @@ See also L<guestfs(3)/AVAILABILITY>.");
 Run the command as usual, but print the elapsed time afterwards.  This
 can be useful for benchmarking operations.");
 
+  ("unsetenv", (RErr,[], []), -1, [], [],
+   "unset an environment variable",
+   "  unsetenv VAR
+
+Remove C<VAR> from the environment.");
+
 ]