X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=b21a25ddf468665a50dff9481552721433036f41;hp=50e9f50b11ba7b60d0c38b53e4ed157b0052bf05;hb=01d613ae957431d65c700a34e369ef4c06dd6d8f;hpb=f93b234401093c63e67f2ffc254f611eee4daf7c diff --git a/src/guestfs.pod b/src/guestfs.pod index 50e9f50..b21a25d 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -770,17 +770,6 @@ The error message you get from this is also a little obscure. This could be fixed in the generator by specially marking parameters and return values which take bytes or other units. -=item Library should return errno with error messages. - -It would be a nice-to-have to be able to get the original value of -'errno' from inside the appliance along error paths (where set). -Currently L goes through hoops to try to reverse the -error message string into an errno, see the function error() in -fuse/guestmount.c. - -In libguestfs 1.5.4, the protocol was changed so that the -Linux errno is sent back from the daemon. - =item Ambiguity between devices and paths There is a subtle ambiguity in the API between a device name @@ -888,12 +877,44 @@ This closes the connection handle and frees up all resources used. =head1 ERROR HANDLING -The convention in all functions that return C is that they return -C<-1> to indicate an error. You can get additional information on -errors by calling L and/or by setting up an error -handler with L. +API functions can return errors. For example, almost all functions +that return C 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 +was a system call. + +You can get at the additional information about the last error on the +handle by calling L, L, +and/or by setting up an error handler with +L. + +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. -The default error handler prints the information string to C. +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 @@ -910,9 +931,44 @@ returns C. The lifetime of the returned string is until the next error occurs, or L 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); + +This returns the last error number (errno) that happened on C. + +If successful, an errno integer not equal to zero is returned. + +If no error, this returns 0. This call can return 0 in three +situations: + +=over 4 + +=item 1. + +There has not been any error on the handle. + +=item 2. + +There has been an error but the errno was meaningless. This +corresponds to the case where the error did not come from a +failed system call, but for some other reason. + +=item 3. + +There was an error from a failed system call, but for some +reason the errno was not captured and returned. This usually +indicates a bug in libguestfs. + +=back + +Libguestfs tries to convert the errno from inside the applicance into +a corresponding errno for the caller (not entirely trivial: the +appliance might be running a completely different operating system +from the library and error numbers are not standardized across +Un*xen). If this could not be done, then the error is translated to +C. In practice this should only happen in very rare +circumstances. =head2 guestfs_set_error_handler @@ -927,6 +983,9 @@ The callback C will be called if there is an error. The parameters passed to the callback are an opaque data pointer and the error message string. +C is not passed to the callback. To get that the callback must +call L. + Note that the message string C is freed as soon as the callback function returns, so if you want to stash it somewhere you must make your own copy.