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
=head2 guestfs_set_error_handler
typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
- void *data,
+ void *opaque,
const char *msg);
void guestfs_set_error_handler (guestfs_h *g,
guestfs_error_handler_cb cb,
- void *data);
+ void *opaque);
The callback C<cb> will be called if there is an error. The
parameters passed to the callback are an opaque data pointer and the
=head2 guestfs_get_error_handler
guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
- void **data_rtn);
+ void **opaque_rtn);
Returns the current error handler callback.
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