X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=9717543e4ce4de05f09c8695de322a887ec04490;hp=da0312864253817d7a98663f7df115d7de75441f;hb=7e3d76e41b3c2862ae04744b01e5e23b245393e4;hpb=2066805a5d93b62beaf6653324715f0b62b06a05

diff --git a/src/guestfs.pod b/src/guestfs.pod
index da03128..9717543 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -877,8 +877,8 @@ This closes the connection handle and frees up all resources used.
 
 =head1 ERROR HANDLING
 
-The convention in all functions that return C<int> is that they return
-C<-1> to indicate an error.
+API functions can return errors.  For example, almost all functions
+that return C<int> will return C<-1> to indicate an error.
 
 Additional information is available for errors: an error message
 string and optionally an error number (errno) if the thing that failed
@@ -889,12 +889,43 @@ handle by calling L</guestfs_last_error>, L</guestfs_last_errno>,
 and/or by setting up an error handler with
 L</guestfs_set_error_handler>.
 
-The default error handler prints the information string to C<stderr>.
+When the handle is created, a default error handler is installed which
+prints the error message string to C<stderr>.  For small short-running
+command line programs it is sufficient to do:
+
+ if (guestfs_launch (g) == -1)
+   exit (EXIT_FAILURE);
+
+since the default error handler will ensure that an error message has
+been printed to C<stderr> before the program exits.
+
+For other programs the caller will almost certainly want to install an
+alternate error handler or do error handling in-line like this:
+
+ g = guestfs_create ();
+ 
+ /* This disables the default behaviour of printing errors
+    on stderr. */
+ guestfs_set_error_handler (g, NULL, NULL);
+ 
+ if (guestfs_launch (g) == -1) {
+   /* Examine the error message and print it etc. */
+   char *msg = guestfs_last_error (g);
+   int errnum = guestfs_last_errno (g);
+   fprintf (stderr, "%s\n", msg);
+   /* ... */
+  }
 
 Out of memory errors are handled differently.  The default action is
 to call L<abort(3)>.  If this is undesirable, then you can set a
 handler using L</guestfs_set_out_of_memory_handler>.
 
+L</guestfs_create> returns C<NULL> if the handle cannot be created,
+and because there is no handle if this happens there is no way to get
+additional error information.  However L</guestfs_create> is supposed
+to be a lightweight operation which can only fail because of
+insufficient memory (it returns NULL in this case).
+
 =head2 guestfs_last_error
 
  const char *guestfs_last_error (guestfs_h *g);
@@ -906,10 +937,6 @@ returns C<NULL>.
 The lifetime of the returned string is until the next error occurs, or
 L</guestfs_close> is called.
 
-The error string is not localized (ie. is always in English), because
-this makes searching for error messages in search engines give the
-largest number of results.
-
 =head2 guestfs_last_errno
 
  int guestfs_last_errno (guestfs_h *g);