From 5de49dc0d82a86032eb51e2cb9e43813e2480594 Mon Sep 17 00:00:00 2001 From: Richard Jones Date: Wed, 1 Apr 2009 20:29:03 +0100 Subject: Documentation of low-level API. --- guestfs.pod | 355 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 355 insertions(+) create mode 100644 guestfs.pod (limited to 'guestfs.pod') diff --git a/guestfs.pod b/guestfs.pod new file mode 100644 index 00000000..63bd14c4 --- /dev/null +++ b/guestfs.pod @@ -0,0 +1,355 @@ +=encoding utf8 + +=head1 NAME + +guestfs - Library for accessing and modifying virtual machine images + +=head1 SYNOPSIS + + guestfs_h handle = guestfs_create (); + guestfs_add_drive (handle, "guest.img"); + guestfs_launch (handle); + guestfs_wait_ready (handle); + guestfs_mount (handle, "/dev/sda1", "/"); + guestfs_touch_file (handle, "/hello"); + guestfs_sync (handle); + guestfs_close (handle); + +=head1 DESCRIPTION + +Libguestfs is a library for accessing and modifying guest disk images. +Amongst the things this is good for: making batch configuration +changes to guests, getting disk used/free statistics (see also: +virt-df), migrating between virtualization systems (see also: +virt-p2v), performing partial backups, performing partial guest +clones, cloning guests and changing registry/UUID/hostname info, and +much else besides. + +Libguestfs uses Linux kernel and qemu code, and can access any type of +guest filesystem that Linux and qemu can, including but not limited +to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition +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). + +Libguestfs is a library that can be linked with C and C++ management +programs (or management programs written in other languages, if people +contribute the language bindings). You can also use it from shell +scripts or the command line. + +=head1 CONNECTION MANAGEMENT + + + + + + +=head1 CONFIGURATION MANAGEMENT + + + + + + +=head1 HIGH-LEVEL API + + + + + + + + + +=head1 ERROR HANDLING + + + + + + +=head1 STATE MACHINE AND LOW-LEVEL EVENT API + +Internally, libguestfs is implemented by running a virtual machine +using L. QEmu runs as a child process of the main program, +and most of this discussion won't make sense unless you understand +that the complexity is dealing with the (asynchronous) actions of the +child process. + +=head2 STATE MACHINE + +libguestfs uses a state machine to model the child process: + + | + guestfs_create + | + | + ____V_____ + / \ + | CONFIG | + \__________/ + ^ ^ ^ \ + / | \ \ guestfs_launch + / | _\__V______ + / | / \ + / | | LAUNCHING | + / | \___________/ + / | / + / | guestfs_wait_ready + / | / + ______ / __|____V + / \ ------> / \ + | BUSY | | READY | + \______/ <------ \________/ + +The normal transitions are (1) CONFIG (when the handle is created, but +there is no child process), (2) LAUNCHING (when the child process is +booting up), (3) alternating between READY and BUSY as commands are +issued to, and carried out by, the child process. + +The guest may be killed by C, or may die +asynchronously at any time (eg. due to some internal error), and that +causes the state to transition back to CONFIG. + +Configuration commands for qemu such as C can only +be issued when in the CONFIG state. + +The high-level API offers two calls that go from CONFIG through +LAUNCHING to READY. C is a non-blocking call that +starts up the child process, immediately moving from CONFIG to +LAUNCHING. C blocks until the child process is +READY to accept commands (or until some failure or timeout). The +low-level event API described below provides a non-blocking way to +replace C. + +High-level API actions such as C 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). + +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. + +=head2 SETTING CALLBACKS TO HANDLE EVENTS + +The child process generates events in some situations. Current events +include: receiving a reply message after some action, receiving a log +message, the child process exits, &c. + +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 NON-BLOCKING ACTIONS + +C is the most interesting callback to +play with, since it allows you to perform actions without blocking. + +For example: + + do_it () + { + start_call (); + guestfs_main_loop_run (); /* --> blocks, then calls my_cb */ + } + + start_call () + { + guestfs_set_reply_callback (handle, my_cb, data); + guestfs_nb_[action] (handle, [other parameters ...]); + /* returns immediately */ + } + + my_cb (guestfs_h handle, void *data) + { + retval = guestfs_nb_[action]_r (handle); + /* ... */ + } + +There are C and C functions +corresponding to (very nearly) every C action in the +high-level API. + +=head2 guestfs_set_reply_callback + + void guestfs_set_reply_callback (guestfs_handle h, + guestfs_reply_cb cb, + void *opaque); + +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. + +=head2 guestfs_set_log_message_callback + + void guestfs_set_log_message_callback (guestfs_handle h, + guestfs_log_message_cb cb, + void *opaque); + +The callback function C will be called whenever qemu or the guest +writes anything to the console. + +Use this function to capture kernel messages and similar. + +Normally there is no log message handler, and log messages are just +discarded. + +=head2 guestfs_set_subprocess_quit_callback + + void guestfs_set_subprocess_quit_callback (guestfs_handle h, + guestfs_subprocess_quit_cb cb, + void *opaque); + +The callback function C will be called when the child process +quits, either asynchronously or if killed by +C. (This corresponds to a transition from +any state to the CONFIG state). + +=head2 guestfs_set_ready_callback + + void guestfs_set_ready_callback (guestfs_handle h, + guestfs_ready_cb cb, + void *opaque); + +The callback function C will be called when the child process +becomes ready. (This corresponds to a transition from I +LAUNCHING I BUSY to the READY state). + +You can use this instead of C to implement a +non-blocking wait for the child process to finish booting up. + +=head2 EVENT MAIN LOOP + +To use the low-level event API, you have to provide an event "main +loop". You can write your own, but if you don't want to write one, +two are provided for you: + +=over 4 + +=item libguestfs-poll + +A simple main loop that is implemented using L. + +This is the default main loop unless you call C +or C. + +=item libguestfs-glib + +An implementation which can be used with GLib and GTK+ programs. You +can use this to write graphical (GTK+) programs which use libguestfs +without hanging during long or slow operations. + +=back + +=head2 guestfs_set_main_loop + + void guestfs_set_main_loop (guestfs_main_loop *); + +This call sets the current main loop to the list of callbacks +contained in the C structure. + +Only one main loop implementation can be used by libguestfs, so +calling this replaces the previous one. (So this is something that +has to be done by the main program, but only the main program "knows" +that it is a GTK+ program or whatever). + +You should call this early in the main program, certainly before +calling C. + +=head2 guestfs_glib_set_main_loop + + void guestfs_glib_set_main_loop (GMainLoop *); + +This helper calls C with the correct callbacks +for integrating with the GLib main loop. + +The libguestfs-glib main loop is contained in a separate library, so +that libguestfs doesn't depend on the whole of GLib: + + #include + #include + + main () + { + GMainLoop *loop = + g_main_loop_new (g_main_context_default (), 1); + ... + guestfs_glib_set_main_loop (loop); + ... + g_main_loop_run (loop); + } + +To use this main loop you must link with C<-lguestfs-glib>. (See also +the GLib and GTK+ documentation). + +=head2 guestfs_main_loop_run + + void guestfs_main_loop_run (void); + +This calls the main loop. + +For some types of main loop you may want or prefer to call another +function, eg. C, or the main loop may already be +invoked by another part of your program. In those cases, ignore this +call. + +=head2 guestfs_main_loop_quit + + void guestfs_main_loop_quit (void); + +This instructs the main loop to quit. In other words, +C will return. + +For some types of main loop you may want or prefer to call another +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. + +=head1 SEE ALSO + +L + + + + + +=head1 AUTHORS + +Richard W.M. Jones (C) + +=head1 COPYRIGHT + +Copyright (C) 2009 Red Hat Inc. +L + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -- cgit