X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=56a840fa74852b6da1420c0396d288dd9ae08c77;hp=db8887e8d043fee67869b34e0955b6cf6107808c;hb=8dfae186196e6cd740c1db0e0be2b5ac94b87993;hpb=13465753d3ed056609ec1e3137750a05d0497a66 diff --git a/guestfs.pod b/guestfs.pod index db8887e..56a840f 100644 --- a/guestfs.pod +++ b/guestfs.pod @@ -37,8 +37,8 @@ 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). -You can also use it from shell scripts or the command line. +programs (or management programs written in OCaml, Perl, Python, Ruby, Java +or Haskell). 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 need enough permissions to access the disk images. @@ -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__args + struct guestfs_message_header (encoded as XDR) + struct guestfs__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__ret + struct guestfs_message_header (encoded as XDR) + struct guestfs__ret (encoded as XDR) As above the C_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 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__args + struct guestfs_message_header (encoded as XDR) + struct guestfs__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. 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 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 the daemon (receiver) may cancel the transfer. The library does this by sending a chunk with a special @@ -610,8 +620,8 @@ 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__ret + struct guestfs_message_header (encoded as XDR) + struct guestfs__ret (encoded as XDR) sequence of chunks for FileOut param #0 sequence of chunks for FileOut param #1 etc. @@ -622,6 +632,30 @@ sort of connection control, when the daemon launches it sends an initial word (C) which indicates that the guest and daemon is alive. This is what C 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> 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 (or wherever), C, +and then use it by setting the LIBGUESTFS_QEMU environment variable. +For example: + + LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish + =head1 ENVIRONMENT VARIABLES =over 4 @@ -636,6 +670,18 @@ has the same effect as calling C. 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 above. + +=item LIBGUESTFS_APPEND + +Pass additional options to the guest kernel. + =back =head1 SEE ALSO @@ -645,6 +691,34 @@ L, L, L. +=head1 BUGS + +To get a list of bugs against libguestfs use this link: + +L + +To report a new bug against libguestfs use this link: + +L + +When reporting a bug, please check: + +=over 4 + +=item * + +That the bug hasn't been reported already. + +=item * + +That you are testing a recent version. + +=item * + +Describe the bug accurately, and give a way to reproduce it. + +=back + =head1 AUTHORS Richard W.M. Jones (C)