X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=src%2Fguestfs.pod;h=c85b0c598f97d89292f15cb9748f1cdeef61d681;hb=7a5a9886a33c2f0294d4cae3d9a0c99c47acf695;hp=8404e742948277b4cf17106e333081053c9178d3;hpb=3920ad95f6b2db8fbf20aa26692877a09070cb04;p=libguestfs.git diff --git a/src/guestfs.pod b/src/guestfs.pod index 8404e74..c85b0c5 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -258,7 +258,11 @@ L. It's often the case that you want to write a file or files to the disk image. -For small, single files, use L. +To write a small file with fixed content, use L. To +create a file of all zeroes, use L (sparse) or +L (with all disk blocks allocated). There are a +variety of other functions for creating test files, for example +L and L. To upload a single file, use L. This call has no limits on file content or size (even files larger than 4 GB). @@ -329,7 +333,7 @@ files. =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. @@ -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 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. The guestfish command: + + lvcreate LV VG 100M + +does not do what you might expect. Instead because +L is already expecting megabytes, this tries to +create a 100 I (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 @@ -714,11 +739,11 @@ largest number of results. =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 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 to C then I handler is called. =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. @@ -801,6 +826,13 @@ supports the functionality. @AVAILABILITY@ +=head2 GUESTFISH supported COMMAND + +In L there is a handy interactive command +C which prints out the available groups and +whether they are supported by this build of libguestfs. +Note however that you have to do C first. + =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 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 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 blocks until the child process is READY to +accept commands (or until some failure or timeout). L internally moves the state from CONFIG to LAUNCHING while it is running. -High-level API actions such as L 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 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 -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 @@ -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, - guestfs_ready_cb cb, + guestfs_launch_done_cb cb, void *opaque); The callback function C 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 will be called while the handle +is being closed (synchronously from L). + +Note that libguestfs installs an L 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, 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 @@ -1270,10 +1317,9 @@ parameters, but with the roles of daemon and library reversed. =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) which indicates that the guest -and daemon is alive. This is what L waits for. +When the daemon launches it sends an initial word +(C) which indicates that the guest and daemon is +alive. This is what L waits for. =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. +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