X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=82fd7a1b8c6fbf7472868a13b19667f187e8e579;hp=a4d9c5724561aa8058bbfce07e004d2e677e8887;hb=60cdd02b02578b427ca3926d566811c6bb7a9970;hpb=90d06e28888d9a492560ca986dca0708f881d173

diff --git a/src/guestfs.pod b/src/guestfs.pod
index a4d9c57..82fd7a1 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
@@ -358,6 +358,11 @@ The command will be running in limited memory.
 
 =item *
 
+The network may not be available unless you enable it
+(see L</guestfs_set_network>).
+
+=item *
+
 Only supports Linux guests (not Windows, BSD, etc).
 
 =item *
@@ -621,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:
@@ -724,7 +736,7 @@ The error message you get from this is also a little obscure.
 This could be fixed in the generator by specially marking parameters
 and return values which take bytes or other units.
 
-=item Protocol should return errno with error messages.
+=item Library should return errno with error messages.
 
 It would be a nice-to-have to be able to get the original value of
 'errno' from inside the appliance along error paths (where set).
@@ -732,6 +744,9 @@ Currently L<guestmount(1)> goes through hoops to try to reverse the
 error message string into an errno, see the function error() in
 fuse/guestmount.c.
 
+In libguestfs 1.5.4, the protocol was changed so that the
+Linux errno is sent back from the daemon.
+
 =back
 
 =head2 PROTOCOL LIMITS
@@ -836,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
@@ -857,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.
 
@@ -932,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])
@@ -956,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>
@@ -966,7 +986,7 @@ need the compile time check as well):
  
  main ()
  {
- #ifdef HAVE_GUESTFS_DD
+ #ifdef LIBGUESTFS_HAVE_DD
    void *dl;
    int has_function;
  
@@ -1178,6 +1198,94 @@ languages (eg. if your HLL interpreter has already been cleaned
 up by the time this is called, and if your callback then jumps
 into some HLL function).
 
+=head2 guestfs_set_progress_callback
+
+ typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque,
+                                      int proc_nr, int serial,
+                                      uint64_t position, uint64_t total);
+ void guestfs_set_progress_callback (guestfs_h *g,
+                                     guestfs_progress_cb cb,
+                                     void *opaque);
+
+Some long-running operations can generate progress messages.  If
+this callback is registered, then it will be called each time a
+progress message is generated (usually two seconds after the
+operation started, and three times per second thereafter until
+it completes, although the frequency may change in future versions).
+
+The callback receives two numbers: C<position> and C<total>.
+The units of C<total> are not defined, although for some
+operations C<total> may relate in some way to the amount of
+data to be transferred (eg. in bytes or megabytes), and
+C<position> may be the portion which has been transferred.
+
+The only defined and stable parts of the API are:
+
+=over 4
+
+=item *
+
+The callback can display to the user some type of progress bar or
+indicator which shows the ratio of C<position>:C<total>.
+
+=item *
+
+0 E<lt>= C<position> E<lt>= C<total>
+
+=item *
+
+If any progress notification is sent during a call, then a final
+progress notification is always sent when C<position> = C<total>.
+
+This is to simplify caller code, so callers can easily set the
+progress indicator to "100%" at the end of the operation, without
+requiring special code to detect this case.
+
+=back
+
+The callback also receives the procedure number and serial number of
+the call.  These are only useful for debugging protocol issues, and
+the callback can normally ignore them.  The callback may want to
+print these numbers in error messages or debugging messages.
+
+=head1 PRIVATE DATA AREA
+
+You can attach named pieces of private data to the libguestfs handle,
+and fetch them by name for the lifetime of the handle.  This is called
+the private data area and is only available from the C API.
+
+To attach a named piece of data, use the following call:
+
+ void guestfs_set_private (guestfs_h *g, const char *key, void *data);
+
+C<key> is the name to associate with this data, and C<data> is an
+arbitrary pointer (which can be C<NULL>).  Any previous item with the
+same name is overwritten.
+
+You can use any C<key> you want, but names beginning with an
+underscore character are reserved for internal libguestfs purposes
+(for implementing language bindings).  It is recommended to prefix the
+name with some unique string to avoid collisions with other users.
+
+To retrieve the pointer, use:
+
+ void *guestfs_get_private (guestfs_h *g, const char *key);
+
+This function returns C<NULL> if either no data is found associated
+with C<key>, or if the user previously set the C<key>'s C<data>
+pointer to C<NULL>.
+
+Libguestfs does not try to look at or interpret the C<data> pointer in
+any way.  As far as libguestfs is concerned, it need not be a valid
+pointer at all.  In particular, libguestfs does I<not> try to free the
+data when the handle is closed.  If the data must be freed, then the
+caller must either free it before calling L</guestfs_close> or must
+set up a close callback to do it (see L</guestfs_set_close_callback>,
+and note that only one callback can be registered for a handle).
+
+The private data area is implemented using a hash table, and should be
+reasonably efficient for moderate numbers of keys.
+
 =head1 BLOCK DEVICE NAMING
 
 In the kernel there is now quite a profusion of schemata for naming