X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=8fdc93d2703d11aeef27c9807988c415dcdc9850;hp=63bd14c43a0d74a6ac85e7e1a9db8de37bfe8500;hb=94050e0344685b6916e21581e618ad3e85795008;hpb=5de49dc0d82a86032eb51e2cb9e43813e2480594

diff --git a/guestfs.pod b/guestfs.pod
index 63bd14c..8fdc93d 100644
--- a/guestfs.pod
+++ b/guestfs.pod
@@ -6,12 +6,14 @@ guestfs - Library for accessing and modifying virtual machine images
 
 =head1 SYNOPSIS
 
- guestfs_h handle = guestfs_create ();
+ #include <guestfs.h>
+ 
+ guestfs_h *handle = guestfs_create ();
  guestfs_add_drive (handle, "guest.img");
  guestfs_launch (handle);
  guestfs_wait_ready (handle);
  guestfs_mount (handle, "/dev/sda1", "/");
- guestfs_touch_file (handle, "/hello");
+ guestfs_touch (handle, "/hello");
  guestfs_sync (handle);
  guestfs_close (handle);
 
@@ -32,44 +34,167 @@ schemes, qcow, qcow2, vmdk.
 
 Libguestfs provides ways to enumerate guest storage (eg. partitions,
 LVs, what filesystem is in each LV, etc.).  It can also run commands
-in the context of the guest.  Also you can mount guest filesystems on
-the host (requires root privs and NFS).
+in the context of the guest.  Also you can access filesystems over FTP.
 
 Libguestfs is a library that can be linked with C and C++ management
-programs (or management programs written in other languages, if people
-contribute the language bindings).  You can also use it from shell
-scripts or the command line.
+programs (or management programs written in OCaml or Perl).
+You can also use it from shell scripts or the command line.
 
-=head1 CONNECTION MANAGEMENT
+You don't need to be root to use libguestfs, although obviously you do
+need enough permissions to access the disk images.
 
+=head1 CONNECTION MANAGEMENT
 
+If you are using the high-level API, then you should call the
+functions in the following order:
 
+ guestfs_h *handle = guestfs_create ();
+ 
+ guestfs_add_drive (handle, "guest.img");
+ /* call guestfs_add_drive additional times if the guest has
+  * multiple disks
+  */
+ 
+ guestfs_launch (handle);
+ guestfs_wait_ready (handle);
 
+ /* now you can examine what partitions, LVs etc are available
+  * you have to mount / at least
+  */ 
+ guestfs_mount (handle, "/dev/sda1", "/");
 
+ /* now you can perform actions on the guest disk image */
+ guestfs_touch (handle, "/hello");
+ 
+ /* you only need to call guestfs_sync if you have made
+  * changes to the guest image
+  */
+ guestfs_sync (handle);
+ 
+ guestfs_close (handle);
 
-=head1 CONFIGURATION MANAGEMENT
+C<guestfs_wait_ready> and all of the actions including C<guestfs_sync>
+are blocking calls.  You can use the low-level event API to do
+non-blocking operations instead.
 
+All functions that return integers, return C<-1> on error.  See
+section ERROR HANDLING below for how to handle errors.
 
+=head2 guestfs_h *
 
+C<guestfs_h> is the opaque type representing a connection handle.
+Create a handle by calling C<guestfs_create>.  Call C<guestfs_close>
+to free the handle and release all resources used.
 
+Handles and operations on handles are not thread safe.  However you
+can use a separate handle for each thread (but not on the same disk
+image).
 
+=head2 guestfs_create
 
-=head1 HIGH-LEVEL API
+ guestfs_h *guestfs_create (void);
 
+Create a connection handle.
 
+You have to call C<guestfs_add_drive> on the handle at least once.
 
+This function returns a non-NULL pointer to a handle on success or
+NULL on error.
 
+After configuring the handle, you have to call C<guestfs_launch> and
+C<guestfs_wait_ready>.
 
+You may also want to configure error handling for the handle.  See
+ERROR HANDLING section below.
 
+=head2 guestfs_close
 
+ void guestfs_close (guestfs_h *handle);
 
+This closes the connection handle and frees up all resources used.
 
 =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 C<guestfs_set_error_handler>.  The default error
+handler prints the information string to C<stderr>.
+
+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 C<guestfs_set_out_of_memory_handler>.
+
+=head2 guestfs_set_error_handler
+
+ typedef void (*guestfs_error_handler_cb) (guestfs_h *handle,
+                                           void *data,
+                                           const char *msg);
+ void guestfs_set_error_handler (guestfs_h *handle,
+                                 guestfs_error_handler_cb cb,
+                                 void *data);
+
+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.
+
+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.
+
+The default handler prints messages on C<stderr>.
+
+If you set C<cb> to C<NULL> then I<no> handler is called and the error
+message is completely discarded.
+
+=head2 guestfs_get_error_handler
+
+ guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *handle,
+                                                     void **data_rtn);
+
+Returns the current error handler callback.
 
+=head2 guestfs_set_out_of_memory_handler 
 
+ typedef void (*guestfs_abort_cb) (void);
+ int guestfs_set_out_of_memory_handler (guestfs_h *handle,
+                                        guestfs_abort_cb);
 
+The callback C<cb> will be called if there is an out of memory
+situation.  I<Note this callback must not return>.
 
+The default is to call L<abort(3)>.
+
+You cannot set C<cb> to C<NULL>.  You can't ignore out of memory
+situations.
+
+=head2 guestfs_get_out_of_memory_handler
+
+ guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *handle);
+
+This returns the current out of memory handler.
+
+=head1 PATH
+
+Libguestfs needs a kernel and initrd.img, which it finds by looking
+along an internal path.
+
+By default it looks for these in the directory C<$libdir/guestfs>
+(eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
+
+Use C<guestfs_set_path> or set the environment variable
+C<LIBGUESTFS_PATH> to change the directories that libguestfs will
+search in.  The value is a colon-separated list of paths.  The current
+directory is I<not> searched unless the path contains an empty element
+or C<.>.  For example C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would
+search the current directory and then C</usr/lib/guestfs>.
+
+=head1 HIGH-LEVEL API ACTIONS
+
+@ACTIONS@
+
+=head1 STRUCTURES
+
+@STRUCTS@
 
 =head1 STATE MACHINE AND LOW-LEVEL EVENT API
 
@@ -79,6 +204,23 @@ and most of this discussion won't make sense unless you understand
 that the complexity is dealing with the (asynchronous) actions of the
 child process.
 
+                            child process
+  ___________________       _________________________
+ /                   \     /                         \
+ | main program      |     | qemu +-----------------+|
+ |                   |     |      | Linux kernel    ||
+ +-------------------+     |      +-----------------+|
+ | libguestfs     <-------------->| guestfsd        ||
+ |                   |     |      +-----------------+|
+ \___________________/     \_________________________/
+
+The diagram above shows libguestfs communicating with the guestfsd
+daemon running inside the qemu child process.  There are several
+points of failure here: qemu can fail to start, the virtual machine
+inside qemu can fail to boot, guestfsd can fail to start or not
+establish communication, any component can start successfully but fail
+asynchronously later, and so on.
+
 =head2 STATE MACHINE
 
 libguestfs uses a state machine to model the child process:
@@ -154,6 +296,8 @@ this function with C<cb> set to C<NULL>.
 
 =head2 NON-BLOCKING ACTIONS
 
+XXX NOT IMPLEMENTED YET XXX
+
 C<guestfs_set_reply_callback> is the most interesting callback to
 play with, since it allows you to perform actions without blocking.
 
@@ -172,19 +316,19 @@ For example:
    /* returns immediately */
  }
  
- my_cb (guestfs_h handle, void *data)
+ my_cb (guestfs_h *handle, void *data, XDR *xdr)
  {
-   retval = guestfs_nb_[action]_r (handle);
+   retval = guestfs_nb_[action]_r (handle, xdr);
    /* ... */
  }
 
 There are C<guestfs_nb_*> and C<guestfs_nb_*_r> functions
-corresponding to (very nearly) every C<guestfs_*> action in the
-high-level API.
+corresponding to every C<guestfs_*> action in the high-level API.
 
 =head2 guestfs_set_reply_callback
 
- void guestfs_set_reply_callback (guestfs_handle h,
+ typedef void (*guestfs_reply_cb) (guestfs_h *g, void *opaque, XDR *xdr);
+ void guestfs_set_reply_callback (guestfs_h *handle,
                                   guestfs_reply_cb cb,
                                   void *opaque);
 
@@ -192,12 +336,15 @@ The callback function C<cb> will be called whenever a reply is
 received from the child process.  (This corresponds to a transition
 from the BUSY state to the READY state).
 
-Note (I<important!>) that high-level API calls overwrite this
-callback.
+Note that the C<xdr> that you get in the callback is in C<XDR_DECODE>
+mode, and you need to consume it before you return from the callback
+function (since it gets destroyed after).
 
 =head2 guestfs_set_log_message_callback
 
- void guestfs_set_log_message_callback (guestfs_handle h,
+ typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque,
+                                         char *buf, int len);
+ void guestfs_set_log_message_callback (guestfs_h *handle,
                                         guestfs_log_message_cb cb,
                                         void *opaque);
 
@@ -211,7 +358,8 @@ discarded.
 
 =head2 guestfs_set_subprocess_quit_callback
 
- void guestfs_set_subprocess_quit_callback (guestfs_handle h,
+ typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);
+ void guestfs_set_subprocess_quit_callback (guestfs_h *handle,
                                             guestfs_subprocess_quit_cb cb,
                                             void *opaque);
 
@@ -220,15 +368,16 @@ quits, either asynchronously or if killed by
 C<guestfs_kill_subprocess>.  (This corresponds to a transition from
 any state to the CONFIG state).
 
-=head2 guestfs_set_ready_callback
+=head2 guestfs_set_launch_done_callback
 
- void guestfs_set_ready_callback (guestfs_handle h,
-                                  guestfs_ready_cb cb,
-                                  void *opaque);
+ typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);
+ void guestfs_set_launch_done_callback (guestfs_h *handle,
+                                        guestfs_ready_cb cb,
+                                        void *opaque);
 
 The callback function C<cb> will be called when the child process
-becomes ready.  (This corresponds to a transition from I<either>
-LAUNCHING I<or> BUSY to the READY state).
+becomes ready first time after it has been launched.  (This
+corresponds to a transition from LAUNCHING to the READY state).
 
 You can use this instead of C<guestfs_wait_ready> to implement a
 non-blocking wait for the child process to finish booting up.
@@ -241,9 +390,9 @@ two are provided for you:
 
 =over 4
 
-=item libguestfs-poll
+=item libguestfs-select
 
-A simple main loop that is implemented using L<poll(2)>.
+A simple main loop that is implemented using L<select(2)>.
 
 This is the default main loop unless you call C<guestfs_set_main_loop>
 or C<guestfs_glib_set_main_loop>.
@@ -320,16 +469,31 @@ function, eg. C<g_main_loop_quit>.  In those cases, ignore this call.
 
 =head2 WRITING A CUSTOM MAIN LOOP
 
-This isn't documented.  Please see the libguestfs-poll and libguestfs-glib
-implementations.
+This isn't documented.  Please see the libguestfs-select and
+libguestfs-glib implementations.
 
-=head1 SEE ALSO
+=head1 ENVIRONMENT VARIABLES
 
-L<qemu(1)>
+=over 4
 
+=item LIBGUESTFS_DEBUG
 
+Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages.  This
+has the same effect as calling C<guestfs_set_verbose (handle, 1)>.
 
+=item LIBGUESTFS_PATH
+
+Set the path that libguestfs uses to search for kernel and initrd.img.
+See the discussion of paths in section PATH above.
+
+=back
+
+=head1 SEE ALSO
 
+L<guestfish(1)>,
+L<qemu(1)>,
+L<febootstrap(1)>,
+L<http://et.redhat.com/~rjones/libguestfs>.
 
 =head1 AUTHORS