X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=30759602f45cfe3aeb6351ad60182a2e4b78b4c8;hp=3aa806abd9c2c8c77edd9562da377f2d6ff4e5c3;hb=168cdbebb6a4ed81cb2156057b0793487e854c4a;hpb=5f9be62e68b120f51c948404e7f0cf3430962c68
diff --git a/guestfs.pod b/guestfs.pod
index 3aa806a..3075960 100644
--- a/guestfs.pod
+++ b/guestfs.pod
@@ -105,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.
@@ -142,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
@@ -274,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
@@ -424,16 +459,26 @@ help on this issue.
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. As an
-example, in Python the handle itself is replaced by an object, but we
-don't try to "object orientify" any other parts of the API.
+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.
+API is identical to the C API. C++ classes and exceptions are
+not implemented.
=item B
@@ -613,32 +658,139 @@ developer to program in confidence against libguestfs.
@STRUCTS@
-=head1 STATE MACHINE AND LOW-LEVEL EVENT API
-
-Internally, libguestfs is implemented by running a virtual machine
-using L. QEmu runs as a child process of the main program,
-and most of this discussion won't make sense unless you understand
-that the complexity is dealing with the (asynchronous) actions of the
-child process.
-
- child process
- ___________________ _________________________
- / \ / \
- | main program | | qemu +-----------------+|
- | | | | Linux kernel ||
- +-------------------+ | +-----------------+|
- | libguestfs <-------------->| guestfsd ||
- | | | +-----------------+|
- \___________________/ \_________________________/
-
-The diagram above shows libguestfs communicating with the guestfsd
-daemon running inside the qemu child process. There are several
-points of failure here: qemu can fail to start, the virtual machine
-inside qemu can fail to boot, guestfsd can fail to start or not
-establish communication, any component can start successfully but fail
-asynchronously later, and so on.
-
-=head2 STATE MACHINE
+=head1 AVAILABILITY
+
+=head2 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
+
+Using L you can test availability of
+the following groups of functions. This test queries the
+appliance to see if the appliance you are currently using
+supports the functionality.
+
+@AVAILABILITY@
+
+=head2 SINGLE CALLS AT COMPILE TIME
+
+If you need to test whether a single libguestfs function is
+available at compile time, we recommend using build tools
+such as autoconf or cmake. For example in autotools you could
+use:
+
+ AC_CHECK_LIB([guestfs],[guestfs_create])
+ AC_CHECK_FUNCS([guestfs_dd])
+
+which would result in C being either defined
+or not defined in your program.
+
+=head2 SINGLE CALLS AT RUN TIME
+
+Testing at compile time doesn't guarantee that a function really
+exists in the library. The reason is that you might be dynamically
+linked against a previous I (dynamic library)
+which doesn't have the call. This situation unfortunately results
+in a segmentation fault, which is a shortcoming of the C dynamic
+linking system itself.
+
+You can use L to test if a function is available
+at run time, as in this example program (note that you still
+need the compile time check as well):
+
+ #include
+
+ #include
+ #include
+ #include
+ #include
+ #include
+
+ main ()
+ {
+ #ifdef HAVE_GUESTFS_DD
+ void *dl;
+ int has_function;
+
+ /* Test if the function guestfs_dd is really available. */
+ dl = dlopen (NULL, RTLD_LAZY);
+ if (!dl) {
+ fprintf (stderr, "dlopen: %s\n", dlerror ());
+ exit (1);
+ }
+ has_function = dlsym (dl, "guestfs_dd") != NULL;
+ dlclose (dl);
+
+ if (!has_function)
+ printf ("this libguestfs.so does NOT have guestfs_dd function\n");
+ else {
+ printf ("this libguestfs.so has guestfs_dd function\n");
+ /* Now it's safe to call
+ guestfs_dd (g, "foo", "bar");
+ */
+ }
+ #else
+ printf ("guestfs_dd function was not found at compile time\n");
+ #endif
+ }
+
+You may think the above is an awful lot of hassle, and it is.
+There are other ways outside of the C linking system to ensure
+that this kind of incompatibility never arises, such as using
+package versioning:
+
+ Requires: libguestfs >= 1.0.80
+
+=begin html
+
+
+
+
+=end html
+
+=head1 ARCHITECTURE
+
+Internally, libguestfs is implemented by running an appliance (a
+special type of small virtual machine) using L. Qemu runs as
+a child process of the main program.
+
+ ___________________
+ / \
+ | main program |
+ | |
+ | | child process / appliance
+ | | __________________________
+ | | / qemu \
+ +-------------------+ RPC | +-----------------+ |
+ | libguestfs <--------------------> guestfsd | |
+ | | | +-----------------+ |
+ \___________________/ | | Linux kernel | |
+ | +--^--------------+ |
+ \_________|________________/
+ |
+ _______v______
+ / \
+ | Device or |
+ | disk image |
+ \______________/
+
+The library, linked to the main program, creates the child process and
+hence the appliance in the L function.
+
+Inside the appliance is a Linux kernel and a complete stack of
+userspace tools (such as LVM and ext2 programs) and a small
+controlling daemon called C. The library talks to
+C using remote procedure calls (RPC). There is a mostly
+one-to-one correspondence between libguestfs API calls and RPC calls
+to the daemon. Lastly the disk image(s) are attached to the qemu
+process which translates device access by the appliance's Linux kernel
+into accesses to the image.
+
+A common misunderstanding is that the appliance "is" the virtual
+machine. Although the disk image you are attached to might also be
+used by some virtual machine, libguestfs doesn't know or care about
+this. (But you will care if both libguestfs's qemu process and your
+virtual machine are trying to update the disk image at the same time,
+since these usually results in massive disk corruption).
+
+=head1 STATE MACHINE
libguestfs uses a state machine to model the child process: