From 01d613ae957431d65c700a34e369ef4c06dd6d8f 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. --- src/guestfs.pod | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/src/guestfs.pod b/src/guestfs.pod index ae0c4df..b21a25d 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -889,7 +889,32 @@ handle by calling L, 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); + 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. If this is undesirable, then you can set a -- 1.8.3.1