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);