X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=e8760168570bf47bd43d98f247e62346a28eac46;hp=e3f6cf059469a2e8312dbe92094c71b845db9332;hb=d2cf9a15a9f22623dbbed33fb66c5077f1275df2;hpb=c9f1a45334efca844c8918b9f0de373f16fd9766

diff --git a/src/guestfs.pod b/src/guestfs.pod
index e3f6cf0..e876016 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -258,7 +258,11 @@ L</guestfs_tgz_out>.
 It's often the case that you want to write a file or files to the disk
 image.
 
-For small, single files, use L</guestfs_write>.
+To write a small file with fixed content, use L</guestfs_write>.  To
+create a file of all zeroes, use L</guestfs_truncate_size> (sparse) or
+L</guestfs_fallocate64> (with all disk blocks allocated).  There are a
+variety of other functions for creating test files, for example
+L</guestfs_fill> and L</guestfs_fill_pattern>.
 
 To upload a single file, use L</guestfs_upload>.  This call has no
 limits on file content or size (even files larger than 4 GB).
@@ -608,6 +612,27 @@ the error message was also unintuitive, but we have corrected this
 since.  Like the Bourne shell, we should have used C<guestfish -c
 command> to run commands.
 
+=item guestfish megabyte modifiers don't work right on all commands
+
+In recent guestfish you can use C<1M> to mean 1 megabyte (and
+similarly for other modifiers).  What guestfish actually does is to
+multiply the number part by the modifier part and pass the result to
+the C API.  However this doesn't work for a few APIs which aren't
+expecting bytes, but are already expecting some other unit
+(eg. megabytes).
+
+The most common is L</guestfs_lvcreate>.  The guestfish command:
+
+ lvcreate LV VG 100M
+
+does not do what you might expect.  Instead because
+L</guestfs_lvcreate> is already expecting megabytes, this tries to
+create a 100 I<terabyte> (100 megabytes * megabytes) logical volume.
+The error message you get from this is also a little obscure.
+
+This could be fixed in the generator by specially marking parameters
+and return values which take bytes or other units.
+
 =item Protocol limit of 256 characters for error messages
 
 This limit is both rather small and quite unnecessary.  We should be
@@ -1031,13 +1056,31 @@ any state to the CONFIG state).
 
  typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);
  void guestfs_set_launch_done_callback (guestfs_h *g,
-                                        guestfs_ready_cb cb,
+                                        guestfs_launch_done_cb cb,
                                         void *opaque);
 
 The callback function C<cb> will be called when the child process
 becomes ready first time after it has been launched.  (This
 corresponds to a transition from LAUNCHING to the READY state).
 
+=head2 guestfs_set_close_callback
+
+ typedef void (*guestfs_close_cb) (guestfs_h *g, void *opaque);
+ void guestfs_set_close_callback (guestfs_h *g,
+                                  guestfs_close_cb cb,
+                                  void *opaque);
+
+The callback function C<cb> will be called while the handle
+is being closed (synchronously from L</guestfs_close>).
+
+Note that libguestfs installs an L<atexit(3)> handler to try to
+clean up handles that are open when the program exits.  This
+means that this callback might be called indirectly from
+L<exit(3)>, which can cause unexpected problems in higher-level
+languages (eg. if your HLL interpreter has already been cleaned
+up by the time this is called, and if your callback then jumps
+into some HLL function).
+
 =head1 BLOCK DEVICE NAMING
 
 In the kernel there is now quite a profusion of schemata for naming