X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=0e7079c231afcb8631d962671ca478fb1f1bc5a3;hp=2ebcc090113a365e4be5f8eae6f90a5103117792;hb=09d7b265e6a0b78592b0a8cc78d9382fd5cb680b;hpb=38d8943009e3a637e56af6adb43f6c12a7a357c7

diff --git a/guestfs.pod b/guestfs.pod
index 2ebcc09..0e7079c 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
@@ -417,6 +419,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 *
@@ -935,6 +1001,15 @@ sort of connection control, when the daemon launches it sends an
 initial word (C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest
 and daemon is alive.  This is what C<guestfs_launch> waits for.
 
+=head1 MULTIPLE HANDLES AND MULTIPLE THREADS
+
+All high-level libguestfs actions are synchronous.  If you want
+to use libguestfs asynchronously then you must create a thread.
+
+Only use the handle from a single thread.  Either use the handle
+exclusively from one thread, or provide your own mutex so that two
+threads cannot issue calls on the same handle at the same time.
+
 =head1 QEMU WRAPPERS
 
 If you want to compile your own qemu, run qemu from a non-standard