X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=129c68174b8687c5e471ecd79192cad8024803f4;hp=1791545fbff9e63700f1a7683cab447a27eaf56a;hb=c9cc61940b41b1abb763a1932adfc3461372c10b;hpb=82dd4b8a308dc97acabf37551bb780434f5e497a diff --git a/guestfs.pod b/guestfs.pod index 1791545..129c681 100644 --- a/guestfs.pod +++ b/guestfs.pod @@ -34,8 +34,7 @@ schemes, qcow, qcow2, vmdk. Libguestfs provides ways to enumerate guest storage (eg. partitions, LVs, what filesystem is in each LV, etc.). It can also run commands -in the context of the guest. Also you can mount guest filesystems on -the host (requires root privs and NFS). +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 other languages, if people @@ -129,6 +128,12 @@ STATE MACHINE AND LOW-LEVEL EVENT API below. You should call these two functions after configuring the handle (eg. adding drives) but before performing any actions. +=head2 guestfs_kill_subprocess + + int guestfs_kill_subprocess (guestfs_h *handle); + +This kills the qemu subprocess. You should never need to call this. + =head1 CONFIGURATION MANAGEMENT The configuration functions allow you to configure which drive images @@ -189,7 +194,9 @@ handler using C. =head2 guestfs_set_error_handler - typedef void (*guestfs_error_handler_cb) (void *data, const char *msg); + typedef void (*guestfs_error_handler_cb) (guestfs_h *handle, + void *data, + const char *msg); void guestfs_set_error_handler (guestfs_h *handle, guestfs_error_handler_cb cb, void *data); @@ -205,7 +212,8 @@ message is completely discarded. =head2 guestfs_get_error_handler - guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *handle); + guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *handle, + void **data_rtn); Returns the current error handler callback. @@ -229,6 +237,22 @@ situations. This returns the current out of memory handler. +=head1 AUTOSYNC + +=head2 guestfs_set_autosync + + void guestfs_set_autosync (guestfs_h *handle, int autosync); + +If C is true, this enables autosync. Libguestfs will make a +best effort attempt to run C when the handle is closed +(also if the program exits without closing handles). + +=head2 guestfs_get_autosync + + int guestfs_get_autosync (guestfs_h *handle); + +Get the autosync flag. + =head1 VERBOSE MESSAGES =head2 guestfs_set_verbose @@ -248,47 +272,7 @@ This returns the verbose messages flag. =head1 HIGH-LEVEL API ACTIONS -=head2 guestfs_sync - - int guestfs_sync (guestfs_h *handle); - -This syncs the disk, so that any writes are flushed through to the -underlying disk image. - -You should always call this if you have modified a disk image, before -calling C. - -XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX - -Documentation will be auto-generated from here, including for -guestfs_sync. - -XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX - - do_[action] ([parameters]) - { - guestfs_set_reply_callback (handle, [action]_cb, data); - guestfs_nb_[action] (handle, [parameters ...]); - - guestfs_main_loop_run (); /* --> blocks, then calls my_cb */ - } - - [action]_cb (guestfs_h *handle, void *data) - { - retval = guestfs_nb_[action]_r (handle); - /* ... */ - guestfs_main_loop_quit (); - return retval; - } - -XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX - - - - - - - +@ACTIONS@ =head1 STATE MACHINE AND LOW-LEVEL EVENT API @@ -390,6 +374,8 @@ this function with C set to C. =head2 NON-BLOCKING ACTIONS +XXX NOT IMPLEMENTED YET XXX + C is the most interesting callback to play with, since it allows you to perform actions without blocking. @@ -408,18 +394,18 @@ For example: /* returns immediately */ } - my_cb (guestfs_h *handle, void *data) + my_cb (guestfs_h *handle, void *data, XDR *xdr) { - retval = guestfs_nb_[action]_r (handle); + retval = guestfs_nb_[action]_r (handle, xdr); /* ... */ } There are C and C functions -corresponding to (very nearly) every C action in the -high-level API. +corresponding to every C action in the high-level API. =head2 guestfs_set_reply_callback + typedef void (*guestfs_reply_cb) (guestfs_h *g, void *opaque, XDR *xdr); void guestfs_set_reply_callback (guestfs_h *handle, guestfs_reply_cb cb, void *opaque); @@ -428,11 +414,14 @@ The callback function C will be called whenever a reply is received from the child process. (This corresponds to a transition from the BUSY state to the READY state). -Note (I) that high-level API calls overwrite this -callback. +Note that the C that you get in the callback is in C +mode, and you need to consume it before you return from the callback +function (since it gets destroyed after). =head2 guestfs_set_log_message_callback + typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque, + char *buf, int len); void guestfs_set_log_message_callback (guestfs_h *handle, guestfs_log_message_cb cb, void *opaque); @@ -447,6 +436,7 @@ discarded. =head2 guestfs_set_subprocess_quit_callback + typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque); void guestfs_set_subprocess_quit_callback (guestfs_h *handle, guestfs_subprocess_quit_cb cb, void *opaque); @@ -458,6 +448,7 @@ any state to the CONFIG state). =head2 guestfs_set_launch_done_callback + typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque); void guestfs_set_launch_done_callback (guestfs_h *handle, guestfs_ready_cb cb, void *opaque); @@ -477,9 +468,9 @@ two are provided for you: =over 4 -=item libguestfs-poll +=item libguestfs-select -A simple main loop that is implemented using L. +A simple main loop that is implemented using L. This is the default main loop unless you call C or C. @@ -556,8 +547,8 @@ function, eg. C. In those cases, ignore this call. =head2 WRITING A CUSTOM MAIN LOOP -This isn't documented. Please see the libguestfs-poll and libguestfs-glib -implementations. +This isn't documented. Please see the libguestfs-select and +libguestfs-glib implementations. =head1 SEE ALSO