Bug: Segfault in Perl bindings.

[libguestfs.git] / guestfs.pod

diff --git a/guestfs.pod b/guestfs.pod
index a462431..9cef777 100644 (file)
--- a/guestfs.pod
+++ b/guestfs.pod
@@ -37,7 +37,7 @@ LVs, what filesystem is in each LV, etc.).  It can also run commands
 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 OCaml, Perl or Python).
+programs (or management programs written in OCaml, Perl, Python, Ruby or Java).
 You can also use it from shell scripts or the command line.
 
 You don't need to be root to use libguestfs, although obviously you do
@@ -518,8 +518,8 @@ For ordinary functions, the request message is:
 
  total length (header + arguments,
       but not including the length word itself)
- struct guestfs_message_header
- struct guestfs_<foo>_args
+ struct guestfs_message_header (encoded as XDR)
+ struct guestfs_<foo>_args (encoded as XDR)
 
 The total length field allows the daemon to allocate a fixed size
 buffer into which it slurps the rest of the message.  As a result, the
@@ -538,8 +538,8 @@ The reply message for ordinary functions is:
 
  total length (header + ret,
       but not including the length word itself)
- struct guestfs_message_header
- struct guestfs_<foo>_ret
+ struct guestfs_message_header (encoded as XDR)
+ struct guestfs_<foo>_ret (encoded as XDR)
 
 As above the C<guestfs_I<foo>_ret> structure may be completely omitted
 for functions that return no formal return values.
@@ -552,8 +552,8 @@ message is slightly changed:
 
  total length (header + error,
       but not including the length word itself)
- struct guestfs_message_header
- struct guestfs_message_error
+ struct guestfs_message_header (encoded as XDR)
+ struct guestfs_message_error (encoded as XDR)
 
 The C<guestfs_message_error> structure contains the error message as a
 string.
@@ -567,19 +567,29 @@ is followed by a sequence of file chunks.
  total length (header + arguments,
       but not including the length word itself,
       and not including the chunks)
- struct guestfs_message_header
- struct guestfs_<foo>_args
+ struct guestfs_message_header (encoded as XDR)
+ struct guestfs_<foo>_args (encoded as XDR)
  sequence of chunks for FileIn param #0
  sequence of chunks for FileIn param #1 etc.
 
-The sequence of chunks is a sequence of C<struct guestfs_chunk>.  A
+The "sequence of chunks" is:
+
+ length of chunk (not including length word itself)
+ struct guestfs_chunk (encoded as XDR)
+ length of chunk
+ struct guestfs_chunk (encoded as XDR)
+   ...
+ length of chunk
+ struct guestfs_chunk (with data.data_len == 0)
+
+The final chunk has the C<data_len> field set to zero.  Additionally a
 flag is set in the final chunk to indicate either successful
 completion or early cancellation.
 
 At time of writing there are no functions that have more than one
 FileIn parameter.  However this is (theoretically) supported, by
-sending the chunks for each FileIn parameter one after another (from
-left to right).
+sending the sequence of chunks for each FileIn parameter one after
+another (from left to right).
 
 Both the library (sender) I<and> the daemon (receiver) may cancel the
 transfer.  The library does this by sending a chunk with a special
@@ -610,11 +620,42 @@ parameters, but with the roles of daemon and library reversed.
  total length (header + ret,
       but not including the length word itself,
       and not including the chunks)
- struct guestfs_message_header
- struct guestfs_<foo>_ret
+ struct guestfs_message_header (encoded as XDR)
+ struct guestfs_<foo>_ret (encoded as XDR)
  sequence of chunks for FileOut param #0
  sequence of chunks for FileOut param #1 etc.
 
+=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 C<guestfs_wait_ready> waits for.
+
+=head1 QEMU WRAPPERS
+
+If you want to compile your own qemu, run qemu from a non-standard
+location, or pass extra arguments to qemu, then you can write a
+shell-script wrapper around qemu.
+
+There is one important rule to remember: you I<must C<exec qemu>> as
+the last command in the shell script (so that qemu replaces the shell
+and becomes the direct child of the libguestfs-using program).  If you
+don't do this, then the qemu process won't be cleaned up correctly.
+
+Here is an example of a wrapper, where I have built my own copy of
+qemu from source:
+
+ #!/bin/sh -
+ qemudir=/home/rjones/d/qemu
+ exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
+
+Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>,
+and then use it by setting the LIBGUESTFS_QEMU environment variable.
+For example:
+
+ LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
+
 =head1 ENVIRONMENT VARIABLES
 
 =over 4
@@ -629,6 +670,14 @@ has the same effect as calling C<guestfs_set_verbose (handle, 1)>.
 Set the path that libguestfs uses to search for kernel and initrd.img.
 See the discussion of paths in section PATH above.
 
+=item LIBGUESTFS_QEMU
+
+Set the default qemu binary that libguestfs uses.  If not set, then
+the qemu which was found at compile time by the configure script is
+used.
+
+See also L<QEMU WRAPPERS> above.
+
 =back
 
 =head1 SEE ALSO