X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=d034c8e3c9d5844ddeca29cae6bbd390f634fd38;hp=423dc10e011780ea4ff959a72399427514a370a2;hb=a7070682932717f318f57f9aca6188a954a7e9aa;hpb=6d9f8f5c140c3116fb0292fcf73f560812c7d5fb

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 423dc10..d034c8e 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -747,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</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
@@ -1522,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<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
 
@@ -1536,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
@@ -1668,9 +1715,9 @@ has the same effect as calling C<guestfs_set_trace (g, 1)>.
 
 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.