LIBGUESTFS_PATH implementation.

[libguestfs.git] / guestfs.pod

diff --git a/guestfs.pod b/guestfs.pod
index a3ef84b..3c28b04 100644 (file)
--- 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
 
 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
 
 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.
 
 
 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
 
 
 =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
 
 
 =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.
 
 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 */
  }
  
    /* 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
    /* ... */
  }
 
 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
 
 
 =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);
  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).
 
 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
 
 =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);
  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
 
 
 =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);
  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
 
 
 =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);
  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
 
 
 =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>.
 
 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
 
 
 =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
 
 
 =head1 AUTHORS