From e33b6bf4c315a8ab3e14c55ffd52f9e82e769e4a Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Wed, 3 Nov 2010 18:29:58 +0000 Subject: [PATCH] docs: Clarify default error handler. Cherry picked from commit 01d613ae957431d65c700a34e369ef4c06dd6d8f. --- src/guestfs.pod | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) 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 and/or by setting up an error handler with L. -The default error handler prints the information string to C. +When the handle is created, a default error handler is installed which +prints the error message string to C. 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 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. If this is undesirable, then you can set a -- 1.8.3.1