Libguestfs is a library that can be linked with C and C++ management
programs (or management programs written in OCaml, Perl, Python, Ruby,
-Java, Haskell or C#). You can also use it from shell scripts or the
+Java, PHP, Haskell or C#). 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
=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.
For documentation see L<Sys::Guestfs(3)>.
+=item B<PHP>
+
+For documentation see C<README-PHP> supplied with libguestfs
+sources or in the php-libguestfs package for your distribution.
+
+The PHP binding only works correctly on 64 bit machines.
+
=item B<Python>
For documentation do:
In libguestfs 1.5.4, the protocol was changed so that the
Linux errno is sent back from the daemon.
+=item Ambiguity between devices and paths
+
+There is a subtle ambiguity in the API between a device name
+(eg. C</dev/sdb2>) and a similar pathname. A file might just happen
+to be called C<sdb2> in the directory C</dev> (consider some non-Unix
+VM image).
+
+In the current API we usually resolve this ambiguity by having two
+separate calls, for example L</guestfs_checksum> and
+L</guestfs_checksum_device>. Some API calls are ambiguous and
+(incorrectly) resolve the problem by detecting if the path supplied
+begins with C</dev/>.
+
+To avoid both the ambiguity and the need to duplicate some calls, we
+could make paths/devices into structured names. One way to do this
+would be to use a notation like grub (C<hd(0,0)>), although nobody
+really likes this aspect of grub. Another way would be to use a
+structured type, equivalent to this OCaml type:
+
+ type path = Path of string | Device of int | Partition of int * int
+
+which would allow you to pass arguments like:
+
+ Path "/foo/bar"
+ Device 1 (* /dev/sdb, or perhaps /dev/sda *)
+ Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
+ Path "/dev/sdb2" (* not a device *)
+
+As you can see there are still problems to resolve even with this
+representation. Also consider how it might work in guestfish.
+
=back
=head2 PROTOCOL LIMITS
=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<cb> will be called if there is an error. The
parameters passed to the callback are an opaque data pointer and the
=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.
=head2 SINGLE CALLS AT COMPILE TIME
-If you need to test whether a single libguestfs function is
-available at compile time, we recommend using build tools
-such as autoconf or cmake. For example in autotools you could
-use:
+Since version 1.5.8, C<E<lt>guestfs.hE<gt>> defines symbols
+for each C API function, such as:
+
+ #define LIBGUESTFS_HAVE_DD 1
+
+if L</guestfs_dd> is available.
+
+Before version 1.5.8, if you needed to test whether a single
+libguestfs function is available at compile time, we recommended using
+build tools such as autoconf or cmake. For example in autotools you
+could use:
AC_CHECK_LIB([guestfs],[guestfs_create])
AC_CHECK_FUNCS([guestfs_dd])
at run time, as in this example program (note that you still
need the compile time check as well):
- #include <config.h>
-
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
main ()
{
- #ifdef HAVE_GUESTFS_DD
+ #ifdef LIBGUESTFS_HAVE_DD
void *dl;
int has_function;
Configuration commands for qemu such as L</guestfs_add_drive> 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</guestfs_launch> 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</guestfs_launch> blocks until the child process is READY to
+accept commands (or until some failure or timeout).
L</guestfs_launch> internally moves the state from CONFIG to LAUNCHING
while it is running.
-High-level API actions such as L</guestfs_mount> 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</guestfs_mount> 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
the callback can normally ignore them. The callback may want to
print these numbers in error messages or debugging messages.
+=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.
+
+To attach a named piece of data, use the following call:
+
+ void guestfs_set_private (guestfs_h *g, const char *key, void *data);
+
+C<key> is the name to associate with this data, and C<data> is an
+arbitrary pointer (which can be C<NULL>). Any previous item with the
+same name is overwritten.
+
+You can use any C<key> you want, but names beginning with an
+underscore character are reserved for internal libguestfs purposes
+(for implementing language bindings). It is recommended to prefix the
+name with some unique string to avoid collisions with other users.
+
+To retrieve the pointer, use:
+
+ void *guestfs_get_private (guestfs_h *g, const char *key);
+
+This function returns C<NULL> if either no data is found associated
+with C<key>, or if the user previously set the C<key>'s C<data>
+pointer to C<NULL>.
+
+Libguestfs does not try to look at or interpret the C<data> pointer in
+any way. As far as libguestfs is concerned, it need not be a valid
+pointer at all. In particular, libguestfs does I<not> 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</guestfs_close> or must
+set up a close callback to do it (see L</guestfs_set_close_callback>,
+and note that only one callback can be registered for a handle).
+
+The private data area is implemented using a hash table, and should be
+reasonably efficient for moderate numbers of keys.
+
=head1 BLOCK DEVICE NAMING
In the kernel there is now quite a profusion of schemata for naming
=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<GUESTFS_LAUNCH_FLAG>) which indicates that the guest
-and daemon is alive. This is what L</guestfs_launch> waits for.
+When the daemon launches it sends an initial word
+(C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest and daemon is
+alive. This is what L</guestfs_launch> waits for.
+
+=head3 PROGRESS NOTIFICATION MESSAGES
+
+The daemon may send progress notification messages at any time. These
+are distinguished by the normal length word being replaced by
+C<GUESTFS_PROGRESS_FLAG>, followed by a fixed size progress message.
+
+The library turns them into progress callbacks (see
+C<guestfs_set_progress_callback>) if there is a callback registered,
+or discards them if not.
+
+The daemon self-limits the frequency of progress messages it sends
+(see C<daemon/proto.c:notify_progress>). Not all calls generate
+progress messages.
=head1 MULTIPLE HANDLES AND MULTIPLE THREADS
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
Location of temporary directory, defaults to C</tmp>.
-If libguestfs was compiled to use the supermin appliance then each
-handle will require rather a large amount of space in this directory
-for short periods of time (~ 80 MB). You can use C<$TMPDIR> to
+If libguestfs was compiled to use the supermin appliance then the
+real appliance is cached in this directory, shared between all
+handles belonging to the same EUID. You can use C<$TMPDIR> to
configure another directory to use in case C</tmp> is not large
enough.
git.annexia.org / libguestfs.git / blobdiff