[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[Libguestfs] [PATCH 02/12] generator: Convert relevant arguments from Device to Mountable



This change updates the api style of all apis which should take Mountable
descriptions rather than block devices. It also updates the documentation
accordingly, but doesn't implement any functional changes.
---
 generator/actions.ml | 86 ++++++++++++++++++++++++++--------------------------
 src/guestfs.pod      | 31 +++++++++++++++++++
 2 files changed, 74 insertions(+), 43 deletions(-)

diff --git a/generator/actions.ml b/generator/actions.ml
index 711f97e..4f613db 100644
--- a/generator/actions.ml
+++ b/generator/actions.ml
@@ -909,7 +909,7 @@ See also C<guestfs_list_filesystems>." };
 
   { defaults with
     name = "inspect_get_type";
-    style = RString "name", [Device "root"], [];
+    style = RString "name", [Mountable "root"], [];
     shortdesc = "get type of inspected operating system";
     longdesc = "\
 This returns the type of the inspected operating system.
@@ -958,7 +958,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_get_arch";
-    style = RString "arch", [Device "root"], [];
+    style = RString "arch", [Mountable "root"], [];
     shortdesc = "get architecture of inspected operating system";
     longdesc = "\
 This returns the architecture of the inspected operating system.
@@ -972,7 +972,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_get_distro";
-    style = RString "distro", [Device "root"], [];
+    style = RString "distro", [Mountable "root"], [];
     shortdesc = "get distro of inspected operating system";
     longdesc = "\
 This returns the distro (distribution) of the inspected operating
@@ -1092,7 +1092,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_get_major_version";
-    style = RInt "major", [Device "root"], [];
+    style = RInt "major", [Mountable "root"], [];
     shortdesc = "get major version of inspected operating system";
     longdesc = "\
 This returns the major version number of the inspected operating
@@ -1111,7 +1111,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_get_minor_version";
-    style = RInt "minor", [Device "root"], [];
+    style = RInt "minor", [Mountable "root"], [];
     shortdesc = "get minor version of inspected operating system";
     longdesc = "\
 This returns the minor version number of the inspected operating
@@ -1124,7 +1124,7 @@ See also C<guestfs_inspect_get_major_version>." };
 
   { defaults with
     name = "inspect_get_product_name";
-    style = RString "product", [Device "root"], [];
+    style = RString "product", [Mountable "root"], [];
     shortdesc = "get product name of inspected operating system";
     longdesc = "\
 This returns the product name of the inspected operating
@@ -1139,7 +1139,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_get_mountpoints";
-    style = RHashtable "mountpoints", [Device "root"], [];
+    style = RHashtable "mountpoints", [Mountable "root"], [];
     shortdesc = "get mountpoints of inspected operating system";
     longdesc = "\
 This returns a hash of where we think the filesystems
@@ -1170,7 +1170,7 @@ See also C<guestfs_inspect_get_filesystems>." };
 
   { defaults with
     name = "inspect_get_filesystems";
-    style = RStringList "filesystems", [Device "root"], [];
+    style = RStringList "filesystems", [Mountable "root"], [];
     shortdesc = "get filesystems associated with inspected operating system";
     longdesc = "\
 This returns a list of all the filesystems that we think
@@ -1214,7 +1214,7 @@ This returns the enable network flag." };
     shortdesc = "list filesystems";
     longdesc = "\
 This inspection command looks for filesystems on partitions,
-block devices and logical volumes, returning a list of devices
+block devices and logical volumes, returning a list of C<mountables>
 containing filesystems and their type.
 
 The return value is a hash, where the keys are the devices
@@ -1225,6 +1225,7 @@ For example:
  \"/dev/sda2\" => \"ext2\"
  \"/dev/vg_guest/lv_root\" => \"ext4\"
  \"/dev/vg_guest/lv_swap\" => \"swap\"
+ \"btrfsvol:/dev/sda3/root\" => \"btrfs\"
 
 The value can have the special value \"unknown\", meaning the
 content of the device is undetermined or empty.
@@ -1320,7 +1321,7 @@ See L<guestfs(3)/DISK LABELS>.
 
   { defaults with
     name = "inspect_get_windows_systemroot";
-    style = RString "systemroot", [Device "root"], [];
+    style = RString "systemroot", [Mountable "root"], [];
     shortdesc = "get Windows systemroot of inspected operating system";
     longdesc = "\
 This returns the Windows systemroot of the inspected guest.
@@ -1490,7 +1491,7 @@ C<guestfs_add_drive_opts>." };
 
   { defaults with
     name = "inspect_get_package_format";
-    style = RString "packageformat", [Device "root"], [];
+    style = RString "packageformat", [Mountable "root"], [];
     shortdesc = "get package format used by the operating system";
     longdesc = "\
 This function and C<guestfs_inspect_get_package_management> return
@@ -1511,7 +1512,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_get_package_management";
-    style = RString "packagemanagement", [Device "root"], [];
+    style = RString "packagemanagement", [Mountable "root"], [];
     shortdesc = "get package management tool used by the operating system";
     longdesc = "\
 C<guestfs_inspect_get_package_format> and this function return
@@ -1533,7 +1534,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_list_applications";
-    style = RStructList ("applications", "application"), [Device "root"], [];
+    style = RStructList ("applications", "application"), [Mountable "root"], [];
     deprecated_by = Some "inspect_list_applications2";
     shortdesc = "get list of applications installed in the operating system";
     longdesc = "\
@@ -1631,7 +1632,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_list_applications2";
-    style = RStructList ("applications2", "application2"), [Device "root"], [];
+    style = RStructList ("applications2", "application2"), [Mountable "root"], [];
     shortdesc = "get list of applications installed in the operating system";
     longdesc = "\
 Return the list of applications installed in the operating system.
@@ -1734,7 +1735,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_get_hostname";
-    style = RString "hostname", [Device "root"], [];
+    style = RString "hostname", [Mountable "root"], [];
     shortdesc = "get hostname of the operating system";
     longdesc = "\
 This function returns the hostname of the operating system
@@ -1747,7 +1748,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_get_format";
-    style = RString "format", [Device "root"], [];
+    style = RString "format", [Mountable "root"], [];
     shortdesc = "get format of inspected operating system";
     longdesc = "\
 This returns the format of the inspected operating system.  You
@@ -1779,7 +1780,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_is_live";
-    style = RBool "live", [Device "root"], [];
+    style = RBool "live", [Mountable "root"], [];
     shortdesc = "get live flag for install disk";
     longdesc = "\
 If C<guestfs_inspect_get_format> returns C<installer> (this
@@ -1790,7 +1791,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_is_netinst";
-    style = RBool "netinst", [Device "root"], [];
+    style = RBool "netinst", [Mountable "root"], [];
     shortdesc = "get netinst (network installer) flag for install disk";
     longdesc = "\
 If C<guestfs_inspect_get_format> returns C<installer> (this
@@ -1803,7 +1804,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_is_multipart";
-    style = RBool "multipart", [Device "root"], [];
+    style = RBool "multipart", [Mountable "root"], [];
     shortdesc = "get multipart flag for install disk";
     longdesc = "\
 If C<guestfs_inspect_get_format> returns C<installer> (this
@@ -1840,7 +1841,7 @@ See C<guestfs_set_attach_method> and L<guestfs(3)/ATTACH METHOD>." };
 
   { defaults with
     name = "inspect_get_product_variant";
-    style = RString "variant", [Device "root"], [];
+    style = RString "variant", [Mountable "root"], [];
     shortdesc = "get product variant of inspected operating system";
     longdesc = "\
 This returns the product variant of the inspected operating
@@ -1868,7 +1869,7 @@ C<guestfs_inspect_get_major_version>." };
 
   { defaults with
     name = "inspect_get_windows_current_control_set";
-    style = RString "controlset", [Device "root"], [];
+    style = RString "controlset", [Mountable "root"], [];
     shortdesc = "get Windows CurrentControlSet of inspected operating system";
     longdesc = "\
 This returns the Windows CurrentControlSet of the inspected guest.
@@ -1882,7 +1883,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
 
   { defaults with
     name = "inspect_get_drive_mappings";
-    style = RHashtable "drives", [Device "root"], [];
+    style = RHashtable "drives", [Mountable "root"], [];
     shortdesc = "get drive letter mappings";
     longdesc = "\
 This call is useful for Windows which uses a primitive system
@@ -1916,7 +1917,7 @@ C<guestfs_inspect_get_filesystems>." };
 
   { defaults with
     name = "inspect_get_icon";
-    style = RBufferOut "icon", [Device "root"],  [OBool "favicon"; OBool "highquality"];
+    style = RBufferOut "icon", [Mountable "root"],  [OBool "favicon"; OBool "highquality"];
     shortdesc = "get the icon corresponding to this operating system";
     longdesc = "\
 This function returns an icon corresponding to the inspected
@@ -2700,7 +2701,7 @@ Get the directory used by the handle to store the appliance cache." };
 let daemon_functions = [
   { defaults with
     name = "mount";
-    style = RErr, [Device "device"; String "mountpoint"], [];
+    style = RErr, [Mountable "mountable"; String "mountpoint"], [];
     proc_nr = Some 1;
     tests = [
       InitEmpty, Always, TestOutput (
@@ -2712,11 +2713,8 @@ let daemon_functions = [
     ];
     shortdesc = "mount a guest disk at a position in the filesystem";
     longdesc = "\
-Mount a guest disk at a position in the filesystem.  Block devices
-are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
-the guest.  If those block devices contain partitions, they will have
-the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
-names can be used.
+Mount C<mountable> at a position in the filesystem.  See L</MOUNTABLES> for a
+description of the format of C<mountable>.
 
 The rules are the same as for L<mount(2)>:  A filesystem must
 first be mounted on C</> before others can be mounted.  Other
@@ -3497,7 +3495,8 @@ contains the filesystem." };
     shortdesc = "show mounted filesystems";
     longdesc = "\
 This returns the list of currently mounted filesystems.  It returns
-the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
+the list of C<mountables> (eg. C</dev/sda1>, C</dev/VG/LV>,
+C<btrfsvol:/dev/sda3/root>).
 
 Some internal mounts are not shown.
 
@@ -4191,7 +4190,7 @@ it to local file C<tarball>." };
 
   { defaults with
     name = "mount_ro";
-    style = RErr, [Device "device"; String "mountpoint"], [];
+    style = RErr, [Mountable "mountable"; String "mountpoint"], [];
     proc_nr = Some 73;
     tests = [
       InitBasicFS, Always, TestLastFail (
@@ -4211,7 +4210,7 @@ mounts the filesystem with the read-only (I<-o ro>) flag." };
 
   { defaults with
     name = "mount_options";
-    style = RErr, [String "options"; Device "device"; String "mountpoint"], [];
+    style = RErr, [String "options"; Mountable "mountable"; String "mountpoint"], [];
     proc_nr = Some 74;
     shortdesc = "mount a guest disk with mount options";
     longdesc = "\
@@ -4225,7 +4224,7 @@ the filesystem uses)." };
 
   { defaults with
     name = "mount_vfs";
-    style = RErr, [String "options"; String "vfstype"; Device "device"; String "mountpoint"], [];
+    style = RErr, [String "options"; String "vfstype"; Mountable "mountable"; String "mountpoint"], [];
     proc_nr = Some 75;
     shortdesc = "mount a guest disk with mount options and vfstype";
     longdesc = "\
@@ -6691,7 +6690,7 @@ See also C<guestfs_realpath>." };
 
   { defaults with
     name = "vfs_type";
-    style = RString "fstype", [Device "device"], [];
+    style = RString "fstype", [Mountable "mountable"], [];
     proc_nr = Some 198;
     tests = [
       InitScratchFS, Always, TestOutput (
@@ -6700,7 +6699,7 @@ See also C<guestfs_realpath>." };
     shortdesc = "get the Linux VFS type corresponding to a mounted device";
     longdesc = "\
 This command gets the filesystem type corresponding to
-the filesystem on C<device>.
+the filesystem on C<mountable>.
 
 For most filesystems, the result is the name of the Linux
 VFS module which would be used to mount this filesystem
@@ -7822,7 +7821,7 @@ a file in the host and attach it as a device." };
 
   { defaults with
     name = "vfs_label";
-    style = RString "label", [Device "device"], [];
+    style = RString "label", [Mountable "mountable"], [];
     proc_nr = Some 253;
     tests = [
       InitBasicFS, Always, TestOutput (
@@ -7831,8 +7830,7 @@ a file in the host and attach it as a device." };
     ];
     shortdesc = "get the filesystem label";
     longdesc = "\
-This returns the filesystem label of the filesystem on
-C<device>.
+This returns the label of the filesystem on C<mountable>.
 
 If the filesystem is unlabeled, this returns the empty string.
 
@@ -7840,7 +7838,7 @@ To find a filesystem from the label, use C<guestfs_findfs_label>." };
 
   { defaults with
     name = "vfs_uuid";
-    style = RString "uuid", [Device "device"], [];
+    style = RString "uuid", [Mountable "mountable"], [];
     proc_nr = Some 254;
     tests =
       (let uuid = uuidgen () in [
@@ -7850,8 +7848,7 @@ To find a filesystem from the label, use C<guestfs_findfs_label>." };
        ]);
     shortdesc = "get the filesystem UUID";
     longdesc = "\
-This returns the filesystem UUID of the filesystem on
-C<device>.
+This returns the filesystem UUID of the filesystem on C<mountable>.
 
 If the filesystem does not have a UUID, this returns the empty string.
 
@@ -9062,7 +9059,7 @@ any existing contents of this device." };
 
   { defaults with
     name = "set_label";
-    style = RErr, [Device "device"; String "label"], [];
+    style = RErr, [Mountable "mountable"; String "label"], [];
     proc_nr = Some 310;
     tests = [
       InitBasicFS, Always, TestOutput (
@@ -9078,7 +9075,7 @@ any existing contents of this device." };
     ];
     shortdesc = "set filesystem label";
     longdesc = "\
-Set the filesystem label on C<device> to C<label>.
+Set the filesystem label on C<mountable> to C<label>.
 
 Only some filesystem types support labels, and libguestfs supports
 setting labels on only a subset of these.
@@ -9087,6 +9084,9 @@ On ext2/3/4 filesystems, labels are limited to 16 bytes.
 
 On NTFS filesystems, labels are limited to 128 unicode characters.
 
+Setting the label on a btrfs subvolume will set the label on its parent
+filesystem.
+
 To read the label on a filesystem, call C<guestfs_vfs_label>." };
 
   { defaults with
diff --git a/src/guestfs.pod b/src/guestfs.pod
index 93fc061..85d0d8f 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -182,6 +182,37 @@ particular L<virt-inspector(1)>.
 To mount a filesystem read-only, use L</guestfs_mount_ro>.  There are
 several other variations of the C<guestfs_mount_*> call.
 
+=head2 MOUNTABLES
+
+A mountable describes the location of a mountable filesystem. Two types of
+mountable are currently supported:
+
+=over
+
+=item Device name
+
+This is the name of a block device in the current session.  Block devices are
+named C</dev/sda>, C</dev/sdb> and so on, as they were added to the guest.  If
+those block devices contain partitions, they will have the usual names (eg.
+C</dev/sda1>).  Also LVM C</dev/VG/LV>-style names can be used.
+
+=item Btrfs Subvolume
+
+A btrfs subvolume comprises a block device containing a btrfs
+filesystem, and the name of a subvolume on that filesystem. It is written as:
+
+ btrfsvol:<block device>/<subvolume>
+
+where C<block device> is the same format as for L</Device name>. For example, to
+specify the subvolume 'root' on the btrfs filesystem on /dev/sda3 would be:
+
+ btrfsvol:/dev/sda3/root
+
+Note that a btrfs filesystem which spans several block devices is mountable by
+specifying any single component block device.
+
+=back
+
 =head2 FILESYSTEM ACCESS AND MODIFICATION
 
 The majority of the libguestfs API consists of fairly low-level calls
-- 
1.8.1


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]