X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=7b6a34e390356844a7e0aefa4883a1440fceb742;hp=dcfa51c9989abad13f9011f42f914443bb2f4646;hb=22e531bc459309d9a871a845cfacd1396ff5b7e4;hpb=259f78cfa70af5505b8172bb81a3d1e2d7581bb5 diff --git a/guestfs.pod b/guestfs.pod index dcfa51c..7b6a34e 100644 --- a/guestfs.pod +++ b/guestfs.pod @@ -7,7 +7,7 @@ guestfs - Library for accessing and modifying virtual machine images =head1 SYNOPSIS #include - + guestfs_h *handle = guestfs_create (); guestfs_add_drive (handle, "guest.img"); guestfs_launch (handle); @@ -60,35 +60,37 @@ and finally closing the handle. So the general structure of all libguestfs-using programs looks like this: guestfs_h *handle = guestfs_create (); - + /* Call guestfs_add_drive additional times if there are * multiple disk images. */ guestfs_add_drive (handle, "guest.img"); - + /* Most manipulation calls won't work until you've launched * the handle. You have to do this _after_ adding drives * and _before_ other commands. */ guestfs_launch (handle); - + /* Now you can examine what partitions, LVs etc are available. */ char **partitions = guestfs_list_partitions (handle); char **logvols = guestfs_lvs (handle); - + /* To access a filesystem in the image, you must mount it. */ guestfs_mount (handle, "/dev/sda1", "/"); - - /* Now you can perform filesystem actions on the guest disk image. */ + + /* Now you can perform filesystem actions on the guest + * disk image. + */ guestfs_touch (handle, "/hello"); - + /* You only need to call guestfs_sync if you have made * changes to the guest image. */ guestfs_sync (handle); - + /* Close the handle. */ guestfs_close (handle); @@ -103,8 +105,8 @@ return error indications. =head2 DISK IMAGES The image filename (C<"guest.img"> in the example above) could be a -disk image from a virtual machine, a L copy of a physical block -device, an actual block device, or simply an empty file of zeroes that +disk image from a virtual machine, a L copy of a physical hard +disk, an actual block device, or simply an empty file of zeroes that you have created through L. Libguestfs lets you do useful things to all of these. @@ -140,7 +142,7 @@ first disk image that we added (C). If the disk contains Linux LVM2 logical volumes you could refer to those instead (eg. C). If you are given a disk image and you don't know what it contains then -you have to find out. Libguestfs can also do that: use +you have to find out. Libguestfs can do that too: use C and C to list possible partitions and LVs, and either try mounting each to see what is mountable, or else examine them with C. But you might @@ -272,6 +274,41 @@ non-portable between kernel versions, and they don't support labels or UUIDs. If you want to pre-build an image or you need to mount it using a label or UUID, use an ISO image instead. +=head2 COPYING + +There are various different commands for copying between files and +devices and in and out of the guest filesystem. These are summarised +in the table below. + +=over 4 + +=item B to B + +Use L to copy a single file, or +L to copy directories recursively. + +=item B to B + +Use L which efficiently uses L +to copy between files and devices in the guest. + +Example: duplicate the contents of an LV: + + guestfs_dd (g, "/dev/VG/Original", "/dev/VG/Copy"); + +The destination (C) must be at least as large as the +source (C). + +=item B to B + +Use L. See L above. + +=item B to B + +Use L. See L above. + +=back + =head2 LISTING FILES C is just designed for humans to read (mainly when using @@ -417,6 +454,70 @@ yourself, and then pass them to C functions. See also the programs L, L and L for more help on this issue. +=head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES + +Although we don't want to discourage you from using the C API, we will +mention here that the same API is also available in other languages. + +The API is broadly identical in all supported languages. This means +that the C call C is +C<$handle-Emount($path)> in Perl, C in Python, +and C in OCaml. In other words, a +straightforward, predictable isomorphism between each language. + +Error messages are automatically transformed +into exceptions if the language supports it. + +We don't try to "object orientify" parts of the API in OO languages, +although contributors are welcome to write higher level APIs above +what we provide in their favourite languages if they wish. + +=over 4 + +=item B + +You can use the I header file from C++ programs. The C++ +API is identical to the C API. C++ classes and exceptions are +not implemented. + +=item B + +This is the only language binding that is incomplete. Only calls +which return simple integers have been bound in Haskell, and we are +looking for help to complete this binding. + +=item B + +Full documentation is contained in the Javadoc which is distributed +with libguestfs. + +=item B + +For documentation see the file C. + +=item B + +For documentation see L. + +=item B + +For documentation do: + + $ python + >>> import guestfs + >>> help (guestfs) + +=item B + +Use the Guestfs module. There is no Ruby-specific documentation, but +you can find examples written in Ruby in the libguestfs source. + +=item B + +For documentation see L. + +=back + =head1 CONNECTION MANAGEMENT =head2 guestfs_h * @@ -557,6 +658,13 @@ developer to program in confidence against libguestfs. @STRUCTS@ +=head1 AVAILABILITY + +Using L you can test availability of +the following groups of functions: + +@AVAILABILITY@ + =head1 STATE MACHINE AND LOW-LEVEL EVENT API Internally, libguestfs is implemented by running a virtual machine