Docs: group preformatted sections of text together.

[libguestfs.git] / guestfs.pod

diff --git a/guestfs.pod b/guestfs.pod
index 2ebcc09..d717595 100644 (file)
--- 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,35 @@ 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. */
  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);
 
@@ -253,7 +253,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
@@ -935,6 +935,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