From: Richard W.M. Jones <rjones@redhat.com>
Date: Wed, 3 Nov 2010 18:29:58 +0000 (+0000)
Subject: docs: Clarify default error handler.
X-Git-Tag: 1.6.1~11
X-Git-Url: http://git.annexia.org/?a=commitdiff_plain;h=e33b6bf4c315a8ab3e14c55ffd52f9e82e769e4a;p=libguestfs.git

docs: Clarify default error handler.

Cherry picked from commit 01d613ae957431d65c700a34e369ef4c06dd6d8f.
---

diff --git a/src/guestfs.pod b/src/guestfs.pod
index c8196ee..7ac856c 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -894,7 +894,31 @@ get additional information on
 errors by calling L</guestfs_last_error> 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);
+   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