docs: Clarify, not every function that returns int returns -1 for errors.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 305aa38..dd06880 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -390,6 +390,22 @@ an X86 host).
 For SELinux guests, you may need to enable SELinux and load policy
 first.  See L</SELINUX> in this manpage.
 
 For SELinux guests, you may need to enable SELinux and load policy
 first.  See L</SELINUX> in this manpage.
 

+=item *
+
+I<Security:> It is not safe to run commands from untrusted, possibly
+malicious guests.  These commands may attempt to exploit your program
+by sending unexpected output.  They could also try to exploit the
+Linux kernel or qemu provided by the libguestfs appliance.  They could
+use the network provided by the libguestfs appliance to bypass
+ordinary network partitions and firewalls.  They could use the
+elevated privileges or different SELinux context of your program
+to their advantage.
+
+A secure alternative is to use libguestfs to install a "firstboot"
+script (a script which runs when the guest next boots normally), and
+to have this script run the commands you want in the normal context of
+the running guest, network security and so on.
+

 =back
 
 The two main API calls to run commands are L</guestfs_command> and
 =back
 
 The two main API calls to run commands are L</guestfs_command> and


@@ -754,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.
 
 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<guestmount(1)> 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
 =item Ambiguity between devices and paths
 
 There is a subtle ambiguity in the API between a device name


@@ -872,10 +877,17 @@ This closes the connection handle and frees up all resources used.
 
 =head1 ERROR HANDLING
 
 
 =head1 ERROR HANDLING
 

-The convention in all functions that return C<int> is that they return
-C<-1> to indicate an error.  You can 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>.
+API functions can return errors.  For example, almost all functions
+that return C<int> 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</guestfs_last_error>, L</guestfs_last_errno>,
+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>.
 
 
 The default error handler prints the information string to C<stderr>.
 


@@ -898,6 +910,45 @@ 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.
 
 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<g>.
+
+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<EINVAL>.  In practice this should only happen in very rare
+circumstances.
+

 =head2 guestfs_set_error_handler
 
  typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
 =head2 guestfs_set_error_handler
 
  typedef void (*guestfs_error_handler_cb) (guestfs_h *g,


@@ -911,6 +962,9 @@ The callback C<cb> will be called if there is an error.  The
 parameters passed to the callback are an opaque data pointer and the
 error message string.
 
 parameters passed to the callback are an opaque data pointer and the
 error message string.
 

+C<errno> is not passed to the callback.  To get that the callback must
+call L</guestfs_last_errno>.
+

 Note that the message string C<msg> is freed as soon as the callback
 function returns, so if you want to stash it somewhere you must make
 your own copy.
 Note that the message string C<msg> is freed as soon as the callback
 function returns, so if you want to stash it somewhere you must make
 your own copy.