X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=d034c8e3c9d5844ddeca29cae6bbd390f634fd38;hp=ccc719d7a0f7572208f58cd687f93efc1e115ee6;hb=a7070682932717f318f57f9aca6188a954a7e9aa;hpb=867319ec5f9030d3c14c32e3302606f2bf11ac27 diff --git a/src/guestfs.pod b/src/guestfs.pod index ccc719d..d034c8e 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -43,7 +43,7 @@ FUSE. 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 @@ -334,7 +334,7 @@ files. =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. @@ -626,6 +626,13 @@ For documentation see the file C. For documentation see L. +=item B + +For documentation see C 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 For documentation do: @@ -740,6 +747,37 @@ fuse/guestmount.c. 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) and a similar pathname. A file might just happen +to be called C in the directory C (consider some non-Unix +VM image). + +In the current API we usually resolve this ambiguity by having two +separate calls, for example L and +L. Some API calls are ambiguous and +(incorrectly) resolve the problem by detecting if the path supplied +begins with C. + +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), 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 @@ -940,10 +978,17 @@ Note however that you have to do C first. =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, Cguestfs.hE> defines symbols +for each C API function, such as: + + #define LIBGUESTFS_HAVE_DD 1 + +if L 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]) @@ -964,8 +1009,6 @@ You can use L to test if a function is available at run time, as in this example program (note that you still need the compile time check as well): - #include - #include #include #include @@ -974,7 +1017,7 @@ need the compile time check as well): main () { - #ifdef HAVE_GUESTFS_DD + #ifdef LIBGUESTFS_HAVE_DD void *dl; int has_function; @@ -1097,24 +1140,21 @@ causes the state to transition back to CONFIG. Configuration commands for qemu such as L 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 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 blocks until the child process is READY to +accept commands (or until some failure or timeout). L internally moves the state from CONFIG to LAUNCHING while it is running. -High-level API actions such as L 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 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 @@ -1513,10 +1553,23 @@ parameters, but with the roles of daemon and library reversed. =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) which indicates that the guest -and daemon is alive. This is what L waits for. +When the daemon launches it sends an initial word +(C) which indicates that the guest and daemon is +alive. This is what L 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, 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. + +The daemon self-limits the frequency of progress messages it sends +(see C). Not all calls generate +progress messages. =head1 MULTIPLE HANDLES AND MULTIPLE THREADS @@ -1527,6 +1580,9 @@ Only use the handle from a single thread. Either use the handle 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 @@ -1659,9 +1715,9 @@ has the same effect as calling C. Location of temporary directory, defaults to C. -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 is not large enough.