X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=30759602f45cfe3aeb6351ad60182a2e4b78b4c8;hp=bfd472e4959cc1eb175e4848296e118768926205;hb=168cdbebb6a4ed81cb2156057b0793487e854c4a;hpb=c2cbf9cd082e2cca69481e31ebd9bafda879fa22

diff --git a/guestfs.pod b/guestfs.pod
index bfd472e..3075960 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>
-
+ 
  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<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.
 
@@ -140,7 +142,7 @@ first disk image that we added (C</dev/sda>).  If the disk contains
 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
@@ -253,7 +255,7 @@ It's often the case that you want to write a file or files to the disk
 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
@@ -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<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
@@ -417,6 +454,70 @@ yourself, and then pass them to C<libhivex> functions.  See also the
 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 *
@@ -557,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(1)>.  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</guestfs_available> 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<HAVE_GUESTFS_DD> 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<libguestfs.so> (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<dlopen(3)> 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 <config.h>
+ 
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <unistd.h>
+ #include <dlfcn.h>
+ #include <guestfs.h>
+ 
+ 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
+
+<!-- old anchor for the next section -->
+<a name="state_machine_and_low_level_event_api"/>
+
+=end html
+
+=head1 ARCHITECTURE
+
+Internally, libguestfs is implemented by running an appliance (a
+special type of small virtual machine) using L<qemu(1)>.  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</guestfs_launch> 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<guestfsd>.  The library talks to
+C<guestfsd> 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: