guestfs(3): Document that old callback functions still work.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 4e216f1..e546029 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -354,7 +354,7 @@ doing:
 
  guestfs_download (g, filename, "/dev/stdout");
 
-and you can write tar output to a pipe C<fd> by doing:
+and you can write tar output to a file descriptor C<fd> by doing:
 
  char devfd[64];
  snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
@@ -775,6 +775,9 @@ them.
 
 =item Autosync / forgetting to sync.
 
+I<Update:> Autosync is enabled by default for all API users starting
+from libguestfs 1.5.24.  This section only applies to older versions.
+
 When modifying a filesystem from C or another language, you B<must>
 unmount all filesystems and call L</guestfs_sync> explicitly before
 you close the libguestfs handle.  You can also call:
@@ -793,9 +796,6 @@ Note that in L<guestfish(3)> autosync is the default.  So quick and
 dirty guestfish scripts that forget to sync will work just fine, which
 can make this very puzzling if you are trying to debug a problem.
 
-Update: Autosync is enabled by default for all API users starting from
-libguestfs 1.5.24.
-
 =item Mount option C<-o sync> should not be the default.
 
 If you use L</guestfs_mount>, then C<-o sync,noatime> are added
@@ -1285,7 +1285,7 @@ Create a handle by calling L</guestfs_create>.  Call L</guestfs_close>
 to free the handle and release all resources used.
 
 For information on using multiple handles and threads, see the section
-L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
+L</MULTIPLE HANDLES AND MULTIPLE THREADS> above.
 
 =head2 guestfs_create
 
@@ -1293,15 +1293,16 @@ L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
 
 Create a connection handle.
 
-You have to call L</guestfs_add_drive_opts> (or one of the equivalent
-calls) on the handle at least once.
+On success this returns a non-NULL pointer to a handle.  On error it
+returns NULL.
 
-This function returns a non-NULL pointer to a handle on success or
-NULL on error.
+You have to "configure" the handle after creating it.  This includes
+calling L</guestfs_add_drive_opts> (or one of the equivalent calls) on
+the handle at least once.
 
 After configuring the handle, you have to call L</guestfs_launch>.
 
-You may also want to configure error handling for the handle.  See
+You may also want to configure error handling for the handle.  See the
 L</ERROR HANDLING> section below.
 
 =head2 guestfs_close
@@ -1310,6 +1311,12 @@ L</ERROR HANDLING> section below.
 
 This closes the connection handle and frees up all resources used.
 
+If autosync was set on the handle and the handle was launched, then
+this implicitly calls various functions to unmount filesystems and
+sync the disk.  See L</guestfs_set_autosync> for more details.
+
+If a close callback was set on the handle, then it is called.
+
 =head1 ERROR HANDLING
 
 API functions can return errors.  For example, almost all functions
@@ -1665,7 +1672,8 @@ old functions C<guestfs_set_log_message_callback>,
 C<guestfs_set_subprocess_quit_callback>,
 C<guestfs_set_launch_done_callback>, C<guestfs_set_close_callback> and
 C<guestfs_set_progress_callback> are no longer documented in this
-manual page.
+manual page.  Because of the ABI guarantee, the old functions continue
+to work.
 
 Handles generate events when certain things happen, such as log
 messages being generated, progress messages during long-running