X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=3c28b04df336fa8bc565c9e17df7b193179f9751;hp=a3ef84bb6becfa9651f3485b585cb90a7750c014;hb=843514eef9dc6d04d71e031ba9ddb16e2beb9a04;hpb=27146d368a4956a44c59d1a7fea4ab92685e080c

diff --git a/guestfs.pod b/guestfs.pod
index a3ef84b..3c28b04 100644
--- a/guestfs.pod
+++ b/guestfs.pod
@@ -34,8 +34,7 @@ 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
@@ -238,66 +237,80 @@ situations.
 
 This returns the current out of memory handler.
 
-=head1 VERBOSE MESSAGES
+=head1 PATH
 
-=head2 guestfs_set_verbose
+Libguestfs needs a kernel and initrd.img, which it finds by looking
+along an internal path.
 
- void guestfs_set_verbose (guestfs_h *handle, int verbose);
+By default it looks for these in the directory C<$libdir/guestfs>
+(eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
 
-If C<verbose> is true, this turns on verbose messages (to C<stderr>).
+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>.
 
-Verbose messages are disabled unless the environment variable
-C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
+=head2 guestfs_set_path
 
-=head2 guestfs_get_verbose
+ void guestfs_set_path (guestfs_h *handle, const char *path);
 
- int guestfs_get_verbose (guestfs_h *handle);
+Set the path that libguestfs searches for kernel and initrd.img.
 
-This returns the verbose messages flag.
+The default is C<$libdir/guestfs> unless overridden by setting
+C<LIBGUESTFS_PATH> environment variable.
 
-=head1 HIGH-LEVEL API ACTIONS
+The string C<path> is stashed in the libguestfs handle, so the caller
+must make sure it remains valid for the lifetime of the handle.
 
-=head2 guestfs_sync
+Setting C<path> to C<NULL> restores the default path.
 
- int guestfs_sync (guestfs_h *handle);
+=head2 guestfs_get_path
 
-This syncs the disk, so that any writes are flushed through to the
-underlying disk image.
+ const char *guestfs_get_path (guestfs_h *handle);
 
-You should always call this if you have modified a disk image, before
-calling C<guestfs_close>.
+Return the current search path.
 
-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+This is always non-NULL.  If it wasn't set already, then this will
+return the default path.
 
-Documentation will be auto-generated from here, including for
-guestfs_sync.
+=head1 AUTOSYNC
 
-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+=head2 guestfs_set_autosync
 
- do_[action] ([parameters])
- {
-   guestfs_set_reply_callback (handle, [action]_cb, data);
-   guestfs_nb_[action] (handle, [parameters ...]);
+ void guestfs_set_autosync (guestfs_h *handle, int autosync);
 
-   guestfs_main_loop_run (); /* --> blocks, then calls my_cb */
- }
+If C<autosync> is true, this enables autosync.  Libguestfs will make a
+best effort attempt to run C<guestfs_sync> when the handle is closed
+(also if the program exits without closing handles).
 
- [action]_cb (guestfs_h *handle, void *data)
- {
-   retval = guestfs_nb_[action]_r (handle);
-   /* ... */
-   guestfs_main_loop_quit ();
-   return retval;
- }
+=head2 guestfs_get_autosync
 
-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ int guestfs_get_autosync (guestfs_h *handle);
 
+Get the autosync flag.
 
+=head1 VERBOSE MESSAGES
 
+=head2 guestfs_set_verbose
 
+ void guestfs_set_verbose (guestfs_h *handle, int verbose);
 
+If C<verbose> is true, this turns on verbose messages (to C<stderr>).
 
+Verbose messages are disabled unless the environment variable
+C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
+
+=head2 guestfs_get_verbose
+
+ int guestfs_get_verbose (guestfs_h *handle);
+
+This returns the verbose messages flag.
+
+=head1 HIGH-LEVEL API ACTIONS
 
+@ACTIONS@
 
 =head1 STATE MACHINE AND LOW-LEVEL EVENT API
 
@@ -399,6 +412,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.
 
@@ -417,18 +432,18 @@ 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
 
+ 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);
@@ -437,8 +452,14 @@ 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 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
 
+ 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);
@@ -453,6 +474,7 @@ discarded.
 
 =head2 guestfs_set_subprocess_quit_callback
 
+ 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);
@@ -464,6 +486,7 @@ any state to the CONFIG state).
 
 =head2 guestfs_set_launch_done_callback
 
+ 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);
@@ -483,9 +506,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>.
@@ -562,16 +585,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
+
+=over 4
 
-L<qemu(1)>
+=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 C<guestfs_set_path> above.
+
+=back
+
+=head1 SEE ALSO
 
+L<guestfish(1)>,
+L<qemu(1)>,
+L<febootstrap(1)>,
+L<http://et.redhat.com/~rjones/libguestfs>.
 
 =head1 AUTHORS