=head1 SYNOPSIS
- guestfs_h handle = guestfs_create ();
+ #include <guestfs.h>
+
+ 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_touch (handle, "/hello");
guestfs_sync (handle);
guestfs_close (handle);
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
contribute the language bindings). 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.
+
=head1 CONNECTION MANAGEMENT
+If you are using the high-level API, then you should call the
+functions in the following order:
+
+ guestfs_h *handle = guestfs_create ();
+
+ guestfs_add_drive (handle, "guest.img");
+ /* call guestfs_add_drive additional times if the guest has
+ * multiple disks
+ */
+
+ guestfs_launch (handle);
+ guestfs_wait_ready (handle);
+
+ /* now you can examine what partitions, LVs etc are available
+ * you have to mount / at least
+ */
+ guestfs_mount (handle, "/dev/sda1", "/");
+
+ /* now you can perform actions on the guest disk image */
+ guestfs_touch (handle, "/hello");
+
+ /* you only need to call guestfs_sync if you have made
+ * changes to the guest image
+ */
+ guestfs_sync (handle);
+
+ guestfs_close (handle);
+
+C<guestfs_wait_ready> and all of the actions including C<guestfs_sync>
+are blocking calls. You can use the low-level event API to do
+non-blocking operations instead.
+
+All functions that return integers, return C<-1> on error. See
+section ERROR HANDLING below for how to handle errors.
+
+=head2 guestfs_h *
+
+C<guestfs_h> is the opaque type representing a connection handle.
+Create a handle by calling C<guestfs_create>. Call C<guestfs_close>
+to free the handle and release all resources used.
+
+Handles and operations on handles are not thread safe. However you
+can use a separate handle for each thread (but not on the same disk
+image).
+
+=head2 guestfs_create
+
+ guestfs_h *guestfs_create (void);
+
+Create a connection handle.
+You have to call C<guestfs_add_drive> on the handle at least once.
+See CONFIGURATION MANAGEMENT section below.
+This function returns a non-NULL pointer to a handle on success or
+NULL on error.
+After configuring the handle, you have to call C<guestfs_launch> and
+C<guestfs_wait_ready>.
+You may also want to configure error handling for the handle. See
+ERROR HANDLING section below.
+
+=head2 guestfs_close
+
+ void guestfs_close (guestfs_h *handle);
+
+This closes the connection handle and frees up all resources used.
+
+=head2 guestfs_launch, guestfs_wait_ready
+
+ int guestfs_launch (guestfs_h *handle);
+ int guestfs_wait_ready (guestfs_h *handle);
+
+Internally libguestfs is implemented by running a virtual machine
+using L<qemu(1)>. These calls are necessary in order to boot the
+virtual machine. More discussion of this is available in the section
+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
+will be examined or modified, and set other aspects of the L<qemu(1)>
+virtual machine that we will be running. You need to call only
+C<guestfs_add_drive> at least once for each guest image that you want
+to examine.
+
+=head2 guestfs_add_drive
+ int guestfs_add_drive (guestfs_h *handle, const char *filename);
+This function adds a virtual machine disk image C<filename> to the
+guest. The first time you call this function, the disk appears as IDE
+disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
+so on.
+You don't necessarily need to be root when using libguestfs. However
+you obviously do need sufficient permissions to access the filename
+for whatever operations you want to perform (ie. read access if you
+just want to read the image or write access if you want to modify the
+image).
+This is equivalent to the qemu parameter C<-drive file=filename>.
-=head1 HIGH-LEVEL API
+=head2 guestfs_add_cdrom
+ int guestfs_add_cdrom (guestfs_h *handle, const char *filename);
+This function adds a virtual CD-ROM disk image to the guest.
+This is equivalent to the qemu parameter C<-cdrom filename>.
+=head2 guestfs_config
+ int guestfs_config (guestfs_h *handle,
+ const char *qemu_param, const char *qemu_value);
+This can be used to add arbitrary qemu command line parameters
+of the form C<-param value>. Actually it's not quite arbitrary - we
+prevent you from setting some parameters which would interfere with
+parameters that we use.
+The first character of C<qemu_param> string must be a C<-> (dash).
+C<qemu_value> can be NULL.
=head1 ERROR HANDLING
+The convention in all functions that return C<int> is that they return
+C<-1> to indicate an error. You can get additional information on
+errors by calling C<guestfs_set_error_handler>. The default error
+handler prints the information string to C<stderr>.
+
+Out of memory errors are handled differently. The default action is
+to call L<abort(3)>. If this is undesirable, then you can set a
+handler using C<guestfs_set_out_of_memory_handler>.
+
+=head2 guestfs_set_error_handler
+
+ 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);
+
+The callback C<cb> will be called if there is an error. The
+parameters passed to the callback are an opaque data pointer and the
+error message string.
+
+The default handler prints messages on C<stderr>.
+
+If you set C<cb> to C<NULL> then I<no> handler is called and the error
+message is completely discarded.
+
+=head2 guestfs_get_error_handler
+
+ guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *handle,
+ void **data_rtn);
+
+Returns the current error handler callback.
+
+=head2 guestfs_set_out_of_memory_handler
+
+ typedef void (*guestfs_abort_cb) (void);
+ int guestfs_set_out_of_memory_handler (guestfs_h *handle,
+ guestfs_abort_cb);
+The callback C<cb> will be called if there is an out of memory
+situation. I<Note this callback must not return>.
+The default is to call L<abort(3)>.
+You cannot set C<cb> to C<NULL>. You can't ignore out of memory
+situations.
+=head2 guestfs_get_out_of_memory_handler
+
+ guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *handle);
+
+This returns the current out of memory handler.
+
+=head1 PATH
+
+Libguestfs needs a kernel and initrd.img, which it finds by looking
+along an internal path.
+
+By default it looks for these in the directory C<$libdir/guestfs>
+(eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
+
+Use C<guestfs_set_path> or set the environment variable
+C<LIBGUESTFS_PATH> to change the directories that libguestfs will
+search in. The value is a colon-separated list of paths. The current
+directory is I<not> searched unless the path contains an empty element
+or C<.>. For example C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would
+search the current directory and then C</usr/lib/guestfs>.
+
+=head2 guestfs_set_path
+
+ void guestfs_set_path (guestfs_h *handle, const char *path);
+
+Set the path that libguestfs searches for kernel and initrd.img.
+
+The default is C<$libdir/guestfs> unless overridden by setting
+C<LIBGUESTFS_PATH> environment variable.
+
+The string C<path> is stashed in the libguestfs handle, so the caller
+must make sure it remains valid for the lifetime of the handle.
+
+Setting C<path> to C<NULL> restores the default path.
+
+=head2 guestfs_get_path
+
+ const char *guestfs_get_path (guestfs_h *handle);
+
+Return the current search path.
+
+This is always non-NULL. If it wasn't set already, then this will
+return the default path.
+
+=head1 AUTOSYNC
+
+=head2 guestfs_set_autosync
+
+ void guestfs_set_autosync (guestfs_h *handle, int autosync);
+
+If C<autosync> is true, this enables autosync. Libguestfs will make a
+best effort attempt to run C<guestfs_sync> 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
+
+ void guestfs_set_verbose (guestfs_h *handle, int verbose);
+
+If C<verbose> is true, this turns on verbose messages (to C<stderr>).
+
+Verbose messages are disabled unless the environment variable
+C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
+
+=head2 guestfs_get_verbose
+
+ int guestfs_get_verbose (guestfs_h *handle);
+
+This returns the verbose messages flag.
+
+=head1 HIGH-LEVEL API ACTIONS
+
+@ACTIONS@
=head1 STATE MACHINE AND LOW-LEVEL EVENT API
that the complexity is dealing with the (asynchronous) actions of the
child process.
+ child process
+ ___________________ _________________________
+ / \ / \
+ | main program | | qemu +-----------------+|
+ | | | | Linux kernel ||
+ +-------------------+ | +-----------------+|
+ | libguestfs <-------------->| guestfsd ||
+ | | | +-----------------+|
+ \___________________/ \_________________________/
+
+The diagram above shows libguestfs communicating with the guestfsd
+daemon running inside the qemu child process. There are several
+points of failure here: qemu can fail to start, the virtual machine
+inside qemu can fail to boot, guestfsd can fail to start or not
+establish communication, any component can start successfully but fail
+asynchronously later, and so on.
+
=head2 STATE MACHINE
libguestfs uses a state machine to model the child process:
=head2 NON-BLOCKING ACTIONS
+XXX NOT IMPLEMENTED YET XXX
+
C<guestfs_set_reply_callback> is the most interesting callback to
play with, since it allows you to perform actions without blocking.
/* 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<guestfs_nb_*> and C<guestfs_nb_*_r> functions
-corresponding to (very nearly) every C<guestfs_*> action in the
-high-level API.
+corresponding to every C<guestfs_*> action in the high-level API.
=head2 guestfs_set_reply_callback
- void guestfs_set_reply_callback (guestfs_handle h,
+ 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);
received from the child process. (This corresponds to a transition
from the BUSY state to the READY state).
-Note (I<important!>) that high-level API calls overwrite this
-callback.
+Note that the C<xdr> that you get in the callback is in C<XDR_DECODE>
+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
- void guestfs_set_log_message_callback (guestfs_handle h,
+ 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);
=head2 guestfs_set_subprocess_quit_callback
- void guestfs_set_subprocess_quit_callback (guestfs_handle h,
+ 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);
C<guestfs_kill_subprocess>. (This corresponds to a transition from
any state to the CONFIG state).
-=head2 guestfs_set_ready_callback
+=head2 guestfs_set_launch_done_callback
- void guestfs_set_ready_callback (guestfs_handle h,
- guestfs_ready_cb cb,
- void *opaque);
+ 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);
The callback function C<cb> will be called when the child process
-becomes ready. (This corresponds to a transition from I<either>
-LAUNCHING I<or> BUSY to the READY state).
+becomes ready first time after it has been launched. (This
+corresponds to a transition from LAUNCHING to the READY state).
You can use this instead of C<guestfs_wait_ready> to implement a
non-blocking wait for the child process to finish booting up.
=over 4
-=item libguestfs-poll
+=item libguestfs-select
-A simple main loop that is implemented using L<poll(2)>.
+A simple main loop that is implemented using L<select(2)>.
This is the default main loop unless you call C<guestfs_set_main_loop>
or C<guestfs_glib_set_main_loop>.
=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
+=head1 ENVIRONMENT VARIABLES
-L<qemu(1)>
+=over 4
+=item LIBGUESTFS_DEBUG
+Set C<LIBGUESTFS_DEBUG=1> to enable verbose messages. This
+has the same effect as calling C<guestfs_set_verbose (handle, 1)>.
+=item LIBGUESTFS_PATH
+
+Set the path that libguestfs uses to search for kernel and initrd.img.
+See the discussion of paths in C<guestfs_set_path> above.
+
+=back
+
+=head1 SEE ALSO
+L<guestfish(1)>,
+L<qemu(1)>,
+L<febootstrap(1)>,
+L<http://et.redhat.com/~rjones/libguestfs>.
=head1 AUTHORS
git.annexia.org / libguestfs.git / blobdiff