From a7070682932717f318f57f9aca6188a954a7e9aa Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Sun, 26 Sep 2010 19:34:46 +0100 Subject: [PATCH] Document ambiguity between devices and paths in API. --- src/guestfs.pod | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/src/guestfs.pod b/src/guestfs.pod index c235383..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) 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 -- 1.8.3.1