diff options
author | Richard W.M. Jones <rjones@redhat.com> | 2012-08-21 17:44:42 +0100 |
---|---|---|
committer | Richard W.M. Jones <rjones@redhat.com> | 2012-08-30 22:12:40 +0100 |
commit | af8e9839ae8123285e933ed5549d7c93dc07b197 (patch) | |
tree | f51ee8b44f14de49ea4df2b3ed80855eb4433067 /src | |
parent | fa760bbecfce4f68a372afc7128a7018edaea9c6 (diff) | |
download | libguestfs-af8e9839ae8123285e933ed5549d7c93dc07b197.tar.gz libguestfs-af8e9839ae8123285e933ed5549d7c93dc07b197.tar.xz libguestfs-af8e9839ae8123285e933ed5549d7c93dc07b197.zip |
docs: Document null disks.
It's always been possible to use /dev/null as a disk image.
Document this formally in the API.
(cherry picked from commit e1e8b3a1cfdeee34fbd51f79b8724c5a58f25c10)
Diffstat (limited to 'src')
-rw-r--r-- | src/guestfs.pod | 61 |
1 files changed, 61 insertions, 0 deletions
diff --git a/src/guestfs.pod b/src/guestfs.pod index eb74fbf6..1745bf6e 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -1169,6 +1169,67 @@ UUIDs and filesystem labels. =back +=head2 NULL DISKS + +When adding a disk using, eg., L</guestfs_add_drive>, you can +set the filename to C<"/dev/null">. This string is treated +specially by libguestfs, causing it to add a "null disk". + +A null disk has the following properties: + +=over 4 + +=item * + +A null disk will appear as a normal device, eg. in +calls to L</guestfs_list_devices>. + +=item * + +You may add C<"/dev/null"> multiple times. + +=item * + +You should not try to access a null disk in any way. For +example, you shouldn't try to read it or mount it. + +=back + +Null disks are used for three main purposes: + +=over 4 + +=item 1. + +Performance testing of libguestfs (see L<guestfs-performance(1)>). + +=item 2. + +The internal test suite. + +=item 3. + +If you want to use libguestfs APIs that don't refer to disks, since +libguestfs requires that at least one disk is added, you should add a +null disk. + +For example, to test if a feature is available, use code like this: + + guestfs_h *g; + char **groups = [ "btrfs", NULL ]; + + g = guestfs_create (); + guestfs_add_drive (g, "/dev/null"); + guestfs_launch (g); + if (guestfs_available (g, groups) == 0) { + // group(s) are available + } else { + // group(s) are not available + } + guestfs_close (g); + +=back + =head1 SECURITY This section discusses security implications of using libguestfs, |