Implemented autosync, make it the default for guestfish.

[libguestfs.git] / guestfs.pod

diff --git a/guestfs.pod b/guestfs.pod
index 9202fb8..129c681 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
-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,6 +237,22 @@ situations.
 
 This returns the current out of memory handler.
 
+=head1 AUTOSYNC
+
+=head2 guestfs_set_autosync
+
+ void guestfs_set_autosync (guestfs_h *handle, int autosync);
+
+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).
+
+=head2 guestfs_get_autosync
+
+ int guestfs_get_autosync (guestfs_h *handle);
+
+Get the autosync flag.
+
 =head1 VERBOSE MESSAGES
 
 =head2 guestfs_set_verbose
@@ -257,47 +272,7 @@ This returns the verbose messages flag.
 
 =head1 HIGH-LEVEL API ACTIONS
 
-=head2 guestfs_sync
-
- int guestfs_sync (guestfs_h *handle);
-
-This syncs the disk, so that any writes are flushed through to the
-underlying disk image.
-
-You should always call this if you have modified a disk image, before
-calling C<guestfs_close>.
-
-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-
-Documentation will be auto-generated from here, including for
-guestfs_sync.
-
-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-
- do_[action] ([parameters])
- {
-   guestfs_set_reply_callback (handle, [action]_cb, data);
-   guestfs_nb_[action] (handle, [parameters ...]);
-
-   guestfs_main_loop_run (); /* --> blocks, then calls my_cb */
- }
-
- [action]_cb (guestfs_h *handle, void *data)
- {
-   retval = guestfs_nb_[action]_r (handle);
-   /* ... */
-   guestfs_main_loop_quit ();
-   return retval;
- }
-
-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-
-
-
-
-
-
-
+@ACTIONS@
 
 =head1 STATE MACHINE AND LOW-LEVEL EVENT API
 
@@ -399,6 +374,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 +394,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 +414,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 +436,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 +448,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);