guestfs: Remove traces of documentation for non-existent 'low-level API'

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 584e996..56c3e2f 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -331,7 +331,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.
 
@@ -610,6 +610,23 @@ the error message was also unintuitive, but we have corrected this
 since.  Like the Bourne shell, we should have used C<guestfish -c
 command> to run commands.
 
+=item Protocol limit of 256 characters for error messages
+
+This limit is both rather small and quite unnecessary.  We should be
+able to return error messages up to the length of the protocol message
+(2-4 MB).
+
+Note that we cannot change the protocol without some breakage, because
+there are distributions that repackage the Fedora appliance.
+
+=item Protocol 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).
+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.
+
 =back
 
 =head2 PROTOCOL LIMITS
@@ -699,11 +716,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
@@ -720,7 +737,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.
 
@@ -945,24 +962,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
 
@@ -1009,7 +1023,7 @@ any state to the CONFIG state).
 
  typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);
  void guestfs_set_launch_done_callback (guestfs_h *g,
-                                        guestfs_ready_cb cb,
+                                        guestfs_launch_done_cb cb,
                                         void *opaque);
 
 The callback function C<cb> will be called when the child process