=head1 SYNOPSIS
#include <guestfs.h>
-
+
guestfs_h *handle = guestfs_create ();
guestfs_add_drive (handle, "guest.img");
guestfs_launch (handle);
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);
=head2 DISK IMAGES
The image filename (C<"guest.img"> in the example above) could be a
-disk image from a virtual machine, a L<dd(1)> 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<dd(1)> copy of a physical hard
+disk, an actual block device, or simply an empty file of zeroes that
you have created through L<posix_fallocate(3)>. Libguestfs lets you
do useful things to all of these.
Linux LVM2 logical volumes you could refer to those instead (eg. C</dev/VG/LV>).
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<guestfs_list_partitions> and C<guestfs_lvs> to list possible
partitions and LVs, and either try mounting each to see what is
mountable, or else examine them with C<guestfs_file>. But you might
image.
For small, single files, use C<guestfs_write_file>. This call
-currently contains a bug which limited the call to plain text files
+currently contains a bug which limits the call to plain text files
(not containing ASCII NUL characters).
To upload a single file, use C<guestfs_upload>. This call has no
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<file> to B<file>
+
+Use L</guestfs_cp> to copy a single file, or
+L</guestfs_cp_a> to copy directories recursively.
+
+=item B<file or device> to B<file or device>
+
+Use L</guestfs_dd> which efficiently uses L<dd(1)>
+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</dev/VG/Copy>) must be at least as large as the
+source (C</dev/VG/Original>).
+
+=item B<file on the host> to B<file or device>
+
+Use L</guestfs_upload>. See L</UPLOADING> above.
+
+=item B<file or device> to B<file on the host>
+
+Use L</guestfs_download>. See L</DOWNLOADING> above.
+
+=back
+
=head2 LISTING FILES
C<guestfs_ll> is just designed for humans to read (mainly when using
programs L<hivexml(1)>, L<hivexget(1)> and L<virt-win-reg(1)> 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<guestfs_mount(handle,path)> is
+C<$handle-E<gt>mount($path)> in Perl, C<handle.mount(path)> in Python,
+and C<Guestfs.mount handle path> 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<C++>
+
+You can use the I<guestfs.h> header file from C++ programs. The C++
+API is identical to the C API. C++ classes and exceptions are
+not implemented.
+
+=item B<Haskell>
+
+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<Java>
+
+Full documentation is contained in the Javadoc which is distributed
+with libguestfs.
+
+=item B<OCaml>
+
+For documentation see the file C<guestfs.mli>.
+
+=item B<Perl>
+
+For documentation see L<Sys::Guestfs(3)>.
+
+=item B<Python>
+
+For documentation do:
+
+ $ python
+ >>> import guestfs
+ >>> help (guestfs)
+
+=item B<Ruby>
+
+Use the Guestfs module. There is no Ruby-specific documentation, but
+you can find examples written in Ruby in the libguestfs source.
+
+=item B<shell scripts>
+
+For documentation see L<guestfish(1)>.
+
+=back
+
=head1 CONNECTION MANAGEMENT
=head2 guestfs_h *
@STRUCTS@
+=head1 AVAILABILITY
+
+Using L</guestfs_available> 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
git.annexia.org / libguestfs.git / blobdiff