X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=de5e254372580408a254c5981be840c0f9b5c600;hp=455cd899de4c0d99ecd2de616f8e7224903dc8db;hb=43eed091129212dd29996838cf1d76af0f8fc135;hpb=4ea0abfce413767868a8f53b3d20e5d2f62dff08

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 455cd89..de5e254 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -43,7 +43,7 @@ FUSE.
 
 Libguestfs is a library that can be linked with C and C++ management
 programs (or management programs written in OCaml, Perl, Python, Ruby,
-Java, Haskell or C#).  You can also use it from shell scripts or the
+Java, PHP, Haskell or C#).  You can also use it from shell scripts or the
 command line.
 
 You don't need to be root to use libguestfs, although obviously you do
@@ -334,7 +334,7 @@ files.
 
 =head2 RUNNING COMMANDS
 
-Although libguestfs is a primarily an API for manipulating files
+Although libguestfs is primarily an API for manipulating files
 inside guest images, we also provide some limited facilities for
 running commands inside guests.
 
@@ -626,6 +626,13 @@ For documentation see the file C<guestfs.mli>.
 
 For documentation see L<Sys::Guestfs(3)>.
 
+=item B<PHP>
+
+For documentation see C<README-PHP> supplied with libguestfs
+sources or in the php-libguestfs package for your distribution.
+
+The PHP binding only works correctly on 64 bit machines.
+
 =item B<Python>
 
 For documentation do:
@@ -844,11 +851,11 @@ largest number of results.
 =head2 guestfs_set_error_handler
 
  typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
-                                           void *data,
+                                           void *opaque,
                                            const char *msg);
  void guestfs_set_error_handler (guestfs_h *g,
                                  guestfs_error_handler_cb cb,
-                                 void *data);
+                                 void *opaque);
 
 The callback C<cb> will be called if there is an error.  The
 parameters passed to the callback are an opaque data pointer and the
@@ -865,7 +872,7 @@ If you set C<cb> to C<NULL> then I<no> handler is called.
 =head2 guestfs_get_error_handler
 
  guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
-                                                     void **data_rtn);
+                                                     void **opaque_rtn);
 
 Returns the current error handler callback.
 
@@ -940,10 +947,17 @@ Note however that you have to do C<run> first.
 
 =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:
+Since version 1.5.8, C<E<lt>guestfs.hE<gt>> defines symbols
+for each C API function, such as:
+
+ #define LIBGUESTFS_HAVE_DD 1
+
+if L</guestfs_dd> is available.
+
+Before version 1.5.8, if you needed to test whether a single
+libguestfs function is available at compile time, we recommended 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])
@@ -964,8 +978,6 @@ 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>
@@ -974,7 +986,7 @@ need the compile time check as well):
  
  main ()
  {
- #ifdef HAVE_GUESTFS_DD
+ #ifdef LIBGUESTFS_HAVE_DD
    void *dl;
    int has_function;
  
@@ -1097,24 +1109,21 @@ causes the state to transition back to CONFIG.
 Configuration commands for qemu such as L</guestfs_add_drive> can only
 be issued when in the CONFIG state.
 
-The high-level API offers two calls that go from CONFIG through
-LAUNCHING to READY.  L</guestfs_launch> blocks until the child process
-is READY to accept commands (or until some failure or timeout).
+The API offers one call that goes from CONFIG through LAUNCHING to
+READY.  L</guestfs_launch> blocks until the child process is READY to
+accept commands (or until some failure or timeout).
 L</guestfs_launch> internally moves the state from CONFIG to LAUNCHING
 while it is running.
 
-High-level API actions such as L</guestfs_mount> can only be issued
-when in the READY state.  These high-level API calls block waiting for
-the command to be carried out (ie. the state to transition to BUSY and
-then back to READY).  But using the low-level event API, you get
-non-blocking versions.  (But you can still only carry out one
-operation per handle at a time - that is a limitation of the
-communications protocol we use).
+API actions such as L</guestfs_mount> can only be issued when in the
+READY state.  These API calls block waiting for the command to be
+carried out (ie. the state to transition to BUSY and then back to
+READY).  There are no non-blocking versions, and no way to issue more
+than one command per handle at the same time.
 
 Finally, the child process sends asynchronous messages back to the
-main program, such as kernel log messages.  Mostly these are ignored
-by the high-level API, but using the low-level event API you can
-register to receive these messages.
+main program, such as kernel log messages.  You can register a
+callback to receive these messages.
 
 =head2 SETTING CALLBACKS TO HANDLE EVENTS
 
@@ -1513,10 +1522,23 @@ parameters, but with the roles of daemon and library reversed.
 
 =head3 INITIAL MESSAGE
 
-Because the underlying channel (QEmu -net channel) doesn't have any
-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 L</guestfs_launch> waits for.
+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 L</guestfs_launch> waits for.
+
+=head3 PROGRESS NOTIFICATION MESSAGES
+
+The daemon may send progress notification messages at any time.  These
+are distinguished by the normal length word being replaced by
+C<GUESTFS_PROGRESS_FLAG>, followed by a fixed size progress message.
+
+The library turns them into progress callbacks (see
+C<guestfs_set_progress_callback>) if there is a callback registered,
+or discards them if not.
+
+The daemon self-limits the frequency of progress messages it sends
+(see C<daemon/proto.c:notify_progress>).  Not all calls generate
+progress messages.
 
 =head1 MULTIPLE HANDLES AND MULTIPLE THREADS
 
@@ -1527,6 +1549,9 @@ 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.
 
+See the graphical program guestfs-browser for one possible
+architecture for multithreaded programs using libvirt and libguestfs.
+
 =head1 QEMU WRAPPERS
 
 If you want to compile your own qemu, run qemu from a non-standard