X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=eecf96de110de6b36c188d5205c056b673dbe346;hp=b8b8ca22b81fcc4979c35bb4a06a267459e513c1;hb=872e67ffdf6c7b19782514445d13e8f405e435c1;hpb=78f1405de05ef1f2efebafd8245658d1707e59ef diff --git a/src/guestfs.pod b/src/guestfs.pod index b8b8ca2..eecf96d 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -99,7 +99,7 @@ this: * disk image. */ guestfs_touch (g, "/hello"); - + /* This is only needed for libguestfs < 1.5.24. Since then * it is done automatically when you close the handle. See * discussion of autosync in this page. @@ -737,7 +737,7 @@ See L. =item B -See L. +See L and L. =item B @@ -932,8 +932,8 @@ architecture for multithreaded programs using libvirt and libguestfs. =head2 PATH -Libguestfs needs a kernel and initrd.img, which it finds by looking -along an internal path. +Libguestfs needs a supermin appliance, which it finds by looking along +an internal path. By default it looks for these in the directory C<$libdir/guestfs> (eg. C or C). @@ -972,6 +972,63 @@ For example: Note that libguestfs also calls qemu with the -help and -version options in order to determine features. +=head2 ATTACHING TO RUNNING DAEMONS + +I This is B and has a tendency to eat +babies. Use with caution. + +I This section explains how to attach to a running daemon +from a low level perspective. For most users, simply using virt tools +such as L with the I<--live> option will "just work". + +=head3 Using guestfs_set_attach_method + +By calling L you can change how the +library connects to the C daemon in L +(read L for some background). + +The normal attach method is C, where a small appliance is +created containing the daemon, and then the library connects to this. + +Setting attach method to C> (where I is the path of +a Unix domain socket) causes L to connect to an +existing daemon over the Unix domain socket. + +The normal use for this is to connect to a running virtual machine +that contains a C daemon, and send commands so you can read +and write files inside the live virtual machine. + +=head3 Using guestfs_add_domain with live flag + +L provides some help for getting the +correct attach method. If you pass the C option to this +function, then (if the virtual machine is running) it will +examine the libvirt XML looking for a virtio-serial channel +to connect to: + + + ... + + ... + + + + + ... + + + +L extracts C and sets the attach +method to C. + +Some of the libguestfs tools (including guestfish) support a I<--live> +option which is passed through to L thus allowing +you to attach to and modify live virtual machines. + +The virtual machine needs to have been set up beforehand so that it +has the virtio-serial channel and so that guestfsd is running inside +it. + =head2 ABI GUARANTEE We guarantee the libguestfs ABI (binary interface), for public, @@ -1626,82 +1683,71 @@ For guestfish, see L. =head2 SETTING CALLBACKS TO HANDLE EVENTS -The child process generates events in some situations. Current events -include: receiving a log message, the child process exits. - -Use the C functions to set a callback for -different types of events. - -Only I can be registered for each handle. -Calling C again overwrites the previous -callback of that type. Cancel all callbacks of this type by calling -this function with C set to C. - -=head2 guestfs_set_log_message_callback +B This section documents the generic event mechanism introduced +in libguestfs 1.10, which you should use in new code if possible. The +old functions C, +C, +C, C and +C are no longer documented in this +manual page. - typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque, - char *buf, int len); - void guestfs_set_log_message_callback (guestfs_h *g, - guestfs_log_message_cb cb, - void *opaque); +Handles generate events when certain things happen, such as log +messages being generated, progress messages during long-running +operations, or the handle being closed. The API calls described below +let you register a callback to be called when events happen. You can +register multiple callbacks (for the same, different or overlapping +sets of events), and individually remove callbacks. If callbacks are +not removed, then they remain in force until the handle is closed. -The callback function C will be called whenever qemu or the guest -writes anything to the console. +In the current implementation, events are only generated +synchronously: that means that events (and hence callbacks) can only +happen while you are in the middle of making another libguestfs call. +The callback is called in the same thread. -Use this function to capture kernel messages and similar. +Events may contain a payload, usually nothing (void), an array of 64 +bit unsigned integers, or a message buffer. Payloads are discussed +later on. -Normally there is no log message handler, and log messages are just -discarded. +=head3 CLASSES OF EVENTS -=head2 guestfs_set_subprocess_quit_callback +=over 4 - typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque); - void guestfs_set_subprocess_quit_callback (guestfs_h *g, - guestfs_subprocess_quit_cb cb, - void *opaque); +=item GUESTFS_EVENT_CLOSE +(payload type: void) -The callback function C will be called when the child process -quits, either asynchronously or if killed by -L. (This corresponds to a transition from -any state to the CONFIG state). +The callback function will be called while the handle is being closed +(synchronously from L). -=head2 guestfs_set_launch_done_callback +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). - typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque); - void guestfs_set_launch_done_callback (guestfs_h *g, - guestfs_launch_done_cb cb, - void *opaque); +If no callback is registered: the handle is closed without any +callback being invoked. -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). +=item GUESTFS_EVENT_SUBPROCESS_QUIT +(payload type: void) -=head2 guestfs_set_close_callback +The callback function will be called when the child process quits, +either asynchronously or if killed by L. +(This corresponds to a transition from any state to the CONFIG state). - typedef void (*guestfs_close_cb) (guestfs_h *g, void *opaque); - void guestfs_set_close_callback (guestfs_h *g, - guestfs_close_cb cb, - void *opaque); +If no callback is registered: the event is ignored. -The callback function C will be called while the handle -is being closed (synchronously from L). +=item GUESTFS_EVENT_LAUNCH_DONE +(payload type: void) -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). +The callback function 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_progress_callback +If no callback is registered: the event is ignored. - typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque, - int proc_nr, int serial, - uint64_t position, uint64_t total); - void guestfs_set_progress_callback (guestfs_h *g, - guestfs_progress_cb cb, - void *opaque); +=item GUESTFS_EVENT_PROGRESS +(payload type: array of 4 x uint64_t) Some long-running operations can generate progress messages. If this callback is registered, then it will be called each time a @@ -1709,7 +1755,9 @@ progress message is generated (usually two seconds after the operation started, and three times per second thereafter until it completes, although the frequency may change in future versions). -The callback receives two numbers: C and C. +The callback receives in the payload four unsigned 64 bit numbers +which are (in order): C, C, C, C. + The units of C are not defined, although for some operations C may relate in some way to the amount of data to be transferred (eg. in bytes or megabytes), and @@ -1731,24 +1779,198 @@ indicator which shows the ratio of C:C. =item * If any progress notification is sent during a call, then a final -progress notification is always sent when C = C. +progress notification is always sent when C = C +(I the call fails with an error). This is to simplify caller code, so callers can easily set the progress indicator to "100%" at the end of the operation, without requiring special code to detect this case. +=item * + +For some calls we are unable to estimate the progress of the call, but +we can still generate progress messages to indicate activity. This is +known as "pulse mode", and is directly supported by certain progress +bar implementations (eg. GtkProgressBar). + +For these calls, zero or more progress messages are generated with +C and C, followed by a final message with +C. + +As noted above, if the call fails with an error then the final message +may not be generated. + =back -The callback also receives the procedure number and serial number of -the call. These are only useful for debugging protocol issues, and -the callback can normally ignore them. The callback may want to -print these numbers in error messages or debugging messages. +The callback also receives the procedure number (C) and +serial number (C) of the call. These are only useful for +debugging protocol issues, and the callback can normally ignore them. +The callback may want to print these numbers in error messages or +debugging messages. + +If no callback is registered: progress messages are discarded. + +=item GUESTFS_EVENT_APPLIANCE +(payload type: message buffer) + +The callback function is called whenever a log message is generated by +qemu, the appliance kernel, guestfsd (daemon), or utility programs. + +If the verbose flag (L) is set before launch +(L) then additional debug messages are generated. + +If no callback is registered: the messages are discarded unless the +verbose flag is set in which case they are sent to stderr. You can +override the printing of verbose messages to stderr by setting up a +callback. + +=item GUESTFS_EVENT_LIBRARY +(payload type: message buffer) + +The callback function is called whenever a log message is generated by +the library part of libguestfs. + +If the verbose flag (L) is set then additional +debug messages are generated. + +If no callback is registered: the messages are discarded unless the +verbose flag is set in which case they are sent to stderr. You can +override the printing of verbose messages to stderr by setting up a +callback. + +=item GUESTFS_EVENT_TRACE +(payload type: message buffer) + +The callback function is called whenever a trace message is generated. +This only applies if the trace flag (L) is set. + +If no callback is registered: the messages are sent to stderr. You +can override the printing of trace messages to stderr by setting up a +callback. + +=back + +=head3 guestfs_set_event_callback + + int guestfs_set_event_callback (guestfs_h *g, + guestfs_event_callback cb, + uint64_t event_bitmask, + int flags, + void *opaque); + +This function registers a callback (C) for all event classes +in the C. + +For example, to register for all log message events, you could call +this function with the bitmask +C. To register a +single callback for all possible classes of events, use +C. + +C should always be passed as 0. + +C is an opaque pointer which is passed to the callback. You +can use it for any purpose. + +The return value is the event handle (an integer) which you can use to +delete the callback (see below). + +If there is an error, this function returns C<-1>, and sets the error +in the handle in the usual way (see L etc.) + +Callbacks remain in effect until they are deleted, or until the handle +is closed. + +In the case where multiple callbacks are registered for a particular +event class, all of the callbacks are called. The order in which +multiple callbacks are called is not defined. + +=head3 guestfs_delete_event_callback + + void guestfs_delete_event_callback (guestfs_h *g, int event_handle); + +Delete a callback that was previously registered. C +should be the integer that was returned by a previous call to +C on the same handle. + +=head3 guestfs_event_callback + + typedef void (*guestfs_event_callback) ( + guestfs_h *g, + void *opaque, + uint64_t event, + int event_handle, + int flags, + const char *buf, size_t buf_len, + const uint64_t *array, size_t array_len); + +This is the type of the event callback function that you have to +provide. + +The basic parameters are: the handle (C), the opaque user pointer +(C), the event class (eg. C), the +event handle, and C which in the current API you should ignore. + +The remaining parameters contain the event payload (if any). Each +event may contain a payload, which usually relates to the event class, +but for future proofing your code should be written to handle any +payload for any event class. + +C and C contain a message buffer (if C, +then there is no message buffer). Note that this message buffer can +contain arbitrary 8 bit data, including NUL bytes. + +C and C is an array of 64 bit unsigned integers. At +the moment this is only used for progress messages. + +=head3 EXAMPLE: CAPTURING LOG MESSAGES + +One motivation for the generic event API was to allow GUI programs to +capture debug and other messages. In libguestfs E 1.8 these were +sent unconditionally to C. + +Events associated with log messages are: C, +C and C. (Note that +error messages are not events; you must capture error messages +separately). + +Programs have to set up a callback to capture the classes of events of +interest: + + int eh = + guestfs_set_event_callback + (g, message_callback, + GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_APPLIANCE| + GUESTFS_EVENT_TRACE, + 0, NULL) == -1) + if (eh == -1) { + // handle error in the usual way + } + +The callback can then direct messages to the appropriate place. In +this example, messages are directed to syslog: + + static void + message_callback ( + guestfs_h *g, + void *opaque, + uint64_t event, + int event_handle, + int flags, + const char *buf, size_t buf_len, + const uint64_t *array, size_t array_len) + { + const int priority = LOG_USER|LOG_INFO; + if (buf_len > 0) + syslog (priority, "event 0x%lx: %s", event, buf); + } =head1 PRIVATE DATA AREA You can attach named pieces of private data to the libguestfs handle, -and fetch them by name for the lifetime of the handle. This is called -the private data area and is only available from the C API. +fetch them by name, and walk over them, for the lifetime of the +handle. This is called the private data area and is only available +from the C API. To attach a named piece of data, use the following call: @@ -1776,11 +1998,102 @@ any way. As far as libguestfs is concerned, it need not be a valid pointer at all. In particular, libguestfs does I try to free the data when the handle is closed. If the data must be freed, then the caller must either free it before calling L or must -set up a close callback to do it (see L, -and note that only one callback can be registered for a handle). +set up a close callback to do it (see L). + +To walk over all entries, use these two functions: + + void *guestfs_first_private (guestfs_h *g, const char **key_rtn); + + void *guestfs_next_private (guestfs_h *g, const char **key_rtn); + +C returns the first key, pointer pair ("first" +does not have any particular meaning -- keys are not returned in any +defined order). A pointer to the key is returned in C<*key_rtn> and +the corresponding data pointer is returned from the function. C +is returned if there are no keys stored in the handle. + +C returns the next key, pointer pair. The +return value of this function is also C is there are no further +entries to return. + +Notes about walking over entries: + +=over 4 + +=item * + +You must not call C while walking over the +entries. + +=item * + +The handle maintains an internal iterator which is reset when you call +C. This internal iterator is invalidated when +you call C. + +=item * + +If you have set the data pointer associated with a key to C, ie: + + guestfs_set_private (g, key, NULL); + +then that C is not returned when walking. + +=item * + +C<*key_rtn> is only valid until the next call to +C, C or +C. + +=back + +The following example code shows how to print all keys and data +pointers that are associated with the handle C: + + const char *key; + void *data = guestfs_first_private (g, &key); + while (data != NULL) + { + printf ("key = %s, data = %p\n", key, data); + data = guestfs_next_private (g, &key); + } + +More commonly you are only interested in keys that begin with an +application-specific prefix C. Modify the loop like so: + + const char *key; + void *data = guestfs_first_private (g, &key); + while (data != NULL) + { + if (strncmp (key, "foo_", strlen ("foo_")) == 0) + printf ("key = %s, data = %p\n", key, data); + data = guestfs_next_private (g, &key); + } -The private data area is implemented using a hash table, and should be -reasonably efficient for moderate numbers of keys. +If you need to modify keys while walking, then you have to jump back +to the beginning of the loop. For example, to delete all keys +prefixed with C: + + const char *key; + void *data; + again: + data = guestfs_first_private (g, &key); + while (data != NULL) + { + if (strncmp (key, "foo_", strlen ("foo_")) == 0) + { + guestfs_set_private (g, key, NULL); + /* note that 'key' pointer is now invalid, and so is + the internal iterator */ + goto again; + } + data = guestfs_next_private (g, &key); + } + +Note that the above loop is guaranteed to terminate because the keys +are being deleted, but other manipulations of keys within the loop +might not terminate unless you also maintain an indication of which +keys have been visited. =begin html @@ -2043,8 +2356,8 @@ are distinguished by the normal length word being replaced by C, followed by a fixed size progress message. The library turns them into progress callbacks (see -C) if there is a callback registered, -or discards them if not. +L) if there is a callback registered, or +discards them if not. The daemon self-limits the frequency of progress messages it sends (see C). Not all calls generate @@ -2483,8 +2796,8 @@ example: =item LIBGUESTFS_PATH -Set the path that libguestfs uses to search for kernel and initrd.img. -See the discussion of paths in section PATH above. +Set the path that libguestfs uses to search for a supermin appliance. +See the discussion of paths in section L above. =item LIBGUESTFS_QEMU @@ -2587,7 +2900,7 @@ Richard W.M. Jones (C) =head1 COPYRIGHT -Copyright (C) 2009-2010 Red Hat Inc. +Copyright (C) 2009-2011 Red Hat Inc. L This library is free software; you can redistribute it and/or