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-21 17:44:42 +0100 |
commit | e1e8b3a1cfdeee34fbd51f79b8724c5a58f25c10 (patch) | |
tree | 3e195120aae0022aa282d7b5386e987bcf9ab38f /src | |
parent | e3bb1f7c927a9c34195e51c5810606227dc70e3f (diff) | |
download | libguestfs-e1e8b3a1cfdeee34fbd51f79b8724c5a58f25c10.tar.gz libguestfs-e1e8b3a1cfdeee34fbd51f79b8724c5a58f25c10.tar.xz libguestfs-e1e8b3a1cfdeee34fbd51f79b8724c5a58f25c10.zip |
docs: Document null disks.
It's always been possible to use /dev/null as a disk image.
Document this formally in the API.
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 98de389a..d51be61b 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -1250,6 +1250,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, |