fish: In guestfish(1) turn command references into links.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 8404e74..c85b0c5 100644 (file)
--- 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.
 
 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).
 
 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).


@@ -329,7 +333,7 @@ files.
 
 =head2 RUNNING COMMANDS
 
 
 =head2 RUNNING COMMANDS
 

-Although libguestfs is a primarily an API for manipulating files
+Although libguestfs is primarily an API for manipulating files

 inside guest images, we also provide some limited facilities for
 running commands inside guests.
 
 inside guest images, we also provide some limited facilities for
 running commands inside guests.
 


@@ -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.
 
 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
 =item Protocol limit of 256 characters for error messages
 
 This limit is both rather small and quite unnecessary.  We should be


@@ -714,11 +739,11 @@ largest number of results.
 =head2 guestfs_set_error_handler
 
  typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
 =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,
                                            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
 
 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


@@ -735,7 +760,7 @@ If you set C<cb> to C<NULL> then I<no> handler is called.
 =head2 guestfs_get_error_handler
 
  guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
 =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.
 
 
 Returns the current error handler callback.
 


@@ -801,6 +826,13 @@ supports the functionality.
 
 @AVAILABILITY@
 
 
 @AVAILABILITY@
 

+=head2 GUESTFISH supported COMMAND
+
+In L<guestfish(3)> there is a handy interactive command
+C<supported> which prints out the available groups and
+whether they are supported by this build of libguestfs.
+Note however that you have to do C<run> first.
+

 =head2 SINGLE CALLS AT COMPILE TIME
 
 If you need to test whether a single libguestfs function is
 =head2 SINGLE CALLS AT COMPILE TIME
 
 If you need to test whether a single libguestfs function is


@@ -960,24 +992,21 @@ causes the state to transition back to CONFIG.
 Configuration commands for qemu such as L</guestfs_add_drive> can only
 be issued when in the CONFIG state.
 
 Configuration commands for qemu such as L</guestfs_add_drive> can only
 be issued when in the CONFIG state.
 

-The high-level API offers two calls that go from CONFIG through
-LAUNCHING to READY.  L</guestfs_launch> blocks until the child process
-is READY to accept commands (or until some failure or timeout).
+The API offers one call that goes from CONFIG through LAUNCHING to
+READY.  L</guestfs_launch> blocks until the child process is READY to
+accept commands (or until some failure or timeout).

 L</guestfs_launch> internally moves the state from CONFIG to LAUNCHING
 while it is running.
 
 L</guestfs_launch> internally moves the state from CONFIG to LAUNCHING
 while it is running.
 

-High-level API actions such as L</guestfs_mount> can only be issued
-when in the READY state.  These high-level API calls block waiting for
-the command to be carried out (ie. the state to transition to BUSY and
-then back to READY).  But using the low-level event API, you get
-non-blocking versions.  (But you can still only carry out one
-operation per handle at a time - that is a limitation of the
-communications protocol we use).
+API actions such as L</guestfs_mount> can only be issued when in the
+READY state.  These API calls block waiting for the command to be
+carried out (ie. the state to transition to BUSY and then back to
+READY).  There are no non-blocking versions, and no way to issue more
+than one command per handle at the same time.

 
 Finally, the child process sends asynchronous messages back to the
 
 Finally, the child process sends asynchronous messages back to the

-main program, such as kernel log messages.  Mostly these are ignored
-by the high-level API, but using the low-level event API you can
-register to receive these messages.
+main program, such as kernel log messages.  You can register a
+callback to receive these messages.

 
 =head2 SETTING CALLBACKS TO HANDLE EVENTS
 
 
 =head2 SETTING CALLBACKS TO HANDLE EVENTS
 


@@ -1024,13 +1053,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,
 
  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).
 
                                         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
 =head1 BLOCK DEVICE NAMING
 
 In the kernel there is now quite a profusion of schemata for naming


@@ -1270,10 +1317,9 @@ parameters, but with the roles of daemon and library reversed.
 
 =head3 INITIAL MESSAGE
 
 
 =head3 INITIAL MESSAGE
 

-Because the underlying channel (QEmu -net channel) doesn't have any
-sort of connection control, when the daemon launches it sends an
-initial word (C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest
-and daemon is alive.  This is what L</guestfs_launch> waits for.
+When the daemon launches it sends an initial word
+(C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest and daemon is
+alive.  This is what L</guestfs_launch> waits for.

 
 =head1 MULTIPLE HANDLES AND MULTIPLE THREADS
 
 
 =head1 MULTIPLE HANDLES AND MULTIPLE THREADS
 


@@ -1284,6 +1330,9 @@ Only use the handle from a single thread.  Either use the handle
 exclusively from one thread, or provide your own mutex so that two
 threads cannot issue calls on the same handle at the same time.
 
 exclusively from one thread, or provide your own mutex so that two
 threads cannot issue calls on the same handle at the same time.
 

+See the graphical program guestfs-browser for one possible
+architecture for multithreaded programs using libvirt and libguestfs.
+

 =head1 QEMU WRAPPERS
 
 If you want to compile your own qemu, run qemu from a non-standard
 =head1 QEMU WRAPPERS
 
 If you want to compile your own qemu, run qemu from a non-standard