New API: list-dm-devices (RHBZ#688062).

[libguestfs.git] / generator / generator_actions.ml

diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml
index 634ceeb..aedbeda 100644 (file)
--- a/generator/generator_actions.ml
+++ b/generator/generator_actions.ml
@@ -726,9 +726,6 @@ See also C<guestfs_list_filesystems>.");
    [],
    "get type of inspected operating system",
    "\
    [],
    "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:
 
 This returns the type of the inspected operating system.
 Currently defined types are:
 


@@ -761,9 +758,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get architecture of inspected operating system",
    "\
    [],
    "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>.
 This returns the architecture of the inspected operating system.
 The possible return values are listed under
 C<guestfs_file_architecture>.


@@ -777,9 +771,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get distro of inspected operating system",
    "\
    [],
    "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.
 
 This returns the distro (distribution) of the inspected operating
 system.
 


@@ -863,9 +854,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get major version of inspected operating system",
    "\
    [],
    "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.
 
 This returns the major version number of the inspected operating
 system.
 


@@ -884,9 +872,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get minor version of inspected operating system",
    "\
    [],
    "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.
 
 This returns the minor version number of the inspected operating
 system.
 


@@ -899,9 +884,6 @@ See also C<guestfs_inspect_get_major_version>.");
    [],
    "get product name of inspected operating system",
    "\
    [],
    "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
 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


@@ -916,9 +898,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get mountpoints of inspected operating system",
    "\
    [],
    "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
 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


@@ -949,9 +928,6 @@ See also C<guestfs_inspect_get_filesystems>.");
    [],
    "get filesystems associated with inspected operating system",
    "\
    [],
    "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
 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


@@ -1064,9 +1040,6 @@ deprecated C<guestfs_add_drive_with_if> call (q.v.)
    [],
    "get Windows systemroot of inspected operating system",
    "\
    [],
    "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>.
 
 This returns the Windows systemroot of the inspected guest.
 The systemroot is a directory path such as C</WINDOWS>.
 


@@ -1178,9 +1151,6 @@ C<guestfs_add_drive_opts>.");
    [],
    "get package format used by the operating system",
    "\
    [],
    "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
 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


@@ -1200,9 +1170,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get package management tool used by the operating system",
    "\
    [],
    "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
 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


@@ -1224,9 +1191,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get list of applications installed in the operating system",
    "\
    [],
    "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
 Return the list of applications installed in the operating system.
 
 I<Note:> This call works differently from other parts of the


@@ -1323,9 +1287,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get hostname of the operating system",
    "\
    [],
    "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.
 
 This function returns the hostname of the operating system
 as found by inspection of the guest's configuration files.
 


@@ -1338,9 +1299,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get format of inspected operating system",
    "\
    [],
    "get format 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 format of the inspected operating system.  You
 can use it to detect install images, live CDs and similar.
 
 This returns the format of the inspected operating system.  You
 can use it to detect install images, live CDs and similar.
 


@@ -1372,9 +1330,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get live flag for install disk",
    "\
    [],
    "get live flag for install disk",
    "\

-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-

 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.
 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.


@@ -1385,9 +1340,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get netinst (network installer) flag for install disk",
    "\
    [],
    "get netinst (network installer) flag for install disk",
    "\

-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-

 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
 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


@@ -1400,9 +1352,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get multipart flag for install disk",
    "\
    [],
    "get multipart flag for install disk",
    "\

-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-

 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.
 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.


@@ -1444,9 +1393,6 @@ Return the current attach method.  See C<guestfs_set_attach_method>.");
    [],
    "get product variant of inspected operating system",
    "\
    [],
    "get product variant 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 variant of the inspected operating
 system.
 
 This returns the product variant of the inspected operating
 system.
 


@@ -1474,9 +1420,6 @@ C<guestfs_inspect_get_major_version>.");
    [],
    "get Windows CurrentControlSet of inspected operating system",
    "\
    [],
    "get Windows CurrentControlSet 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 CurrentControlSet of the inspected guest.
 The CurrentControlSet is a registry key name such as C<ControlSet001>.
 
 This returns the Windows CurrentControlSet of the inspected guest.
 The CurrentControlSet is a registry key name such as C<ControlSet001>.
 


@@ -1490,9 +1433,6 @@ Please read L<guestfs(3)/INSPECTION> for more details.");
    [],
    "get drive letter mappings",
    "\
    [],
    "get drive letter mappings",
    "\

-This function should only be called with a root device string
-as returned by C<guestfs_inspect_os>.
-

 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
 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


@@ -1522,6 +1462,70 @@ Please read L<guestfs(3)/INSPECTION> for more details.
 See also C<guestfs_inspect_get_mountpoints>,
 C<guestfs_inspect_get_filesystems>.");
 
 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");
+

 ]
 
 (* daemon_functions are any functions which cause some action
 ]
 
 (* daemon_functions are any functions which cause some action


@@ -3274,9 +3278,6 @@ be parsed.");
    "\
 This command activates or (if C<activate> is false) deactivates
 all logical volumes in all volume groups.
    "\
 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>");
 
 
 This command is the same as running C<vgchange -a y|n>");
 


@@ -3286,9 +3287,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>.
    "\
 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...>
 
 
 This command is the same as running C<vgchange -a y|n volgroups...>
 


@@ -5576,7 +5574,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>
 
 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"],
    [],
 
   ("luks_open_ro", (RErr, [Device "device"; Key "key"; String "mapname"], []), 258, [Optional "luks"],
    [],


@@ -5834,10 +5835,10 @@ not refer to a logical volume.
 
 See also C<guestfs_is_lv>.");
 
 
 See also C<guestfs_is_lv>.");
 

-  ("mkfs_opts", (RErr, [String "fstype"; Device "device"], [Int "blocksize"; String "features"]), 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"];
    [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")],
        ["mount_options"; ""; "/dev/sda1"; "/"];
        ["write"; "/new"; "new file contents"];
        ["cat"; "/new"]], "new file contents")],


@@ -5872,6 +5873,16 @@ for more details.
 You cannot use this optional parameter with the C<gfs> or
 C<gfs2> filesystem type.
 
 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"],
 =back");
 
   ("getxattr", (RBufferOut "xattr", [Pathname "path"; String "name"], []), 279, [Optional "linuxxattrs"],


@@ -5967,6 +5978,30 @@ Note that for large devices this can take a long time to run.");
 List all 9p filesystems attached to the guest.  A list of
 mount tags is returned.");
 
 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.");
+

 ]
 
 let all_functions = non_daemon_functions @ daemon_functions
 ]
 
 let all_functions = non_daemon_functions @ daemon_functions


@@ -6045,6 +6080,20 @@ them with the help of L</glob> like this:
 
  glob copy-out /home/* .");
 
 
  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 ...]
   ("echo", (RErr,[], []), -1, [], [],
    "display a line of text",
    " echo [params ...]