4:19 a.m.
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 d75de8d..40a9dce 100644
--- a/generator/actions.ml
+++ b/generator/actions.ml
@@ -904,7 +904,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.
@@ -953,7 +953,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.
@@ -967,7 +967,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
@@ -1087,7 +1087,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
@@ -1106,7 +1106,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
@@ -1119,7 +1119,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
@@ -1134,7 +1134,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
@@ -1165,7 +1165,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
@@ -1209,7 +1209,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
@@ -1220,6 +1220,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.
@@ -1315,7 +1316,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.
@@ -1485,7 +1486,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
@@ -1506,7 +1507,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
@@ -1528,7 +1529,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 = "\
@@ -1626,7 +1627,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.
@@ -1729,7 +1730,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
@@ -1742,7 +1743,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
@@ -1774,7 +1775,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
@@ -1785,7 +1786,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
@@ -1798,7 +1799,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
@@ -1835,7 +1836,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
@@ -1863,7 +1864,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.
@@ -1877,7 +1878,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
@@ -1911,7 +1912,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
@@ -2695,7 +2696,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 (
@@ -2707,11 +2708,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
@@ -3492,7 +3490,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.
@@ -4186,7 +4185,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 (
@@ -4206,7 +4205,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 = "\
@@ -4220,7 +4219,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 = "\
@@ -6684,7 +6683,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 (
@@ -6693,7 +6692,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
@@ -7814,7 +7813,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 (
@@ -7823,8 +7822,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.
@@ -7832,7 +7830,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 [
@@ -7842,8 +7840,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.
@@ -9054,7 +9051,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 (
@@ -9070,7 +9067,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.
@@ -9079,6 +9076,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 283f7ac..60cbab4 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