[Libguestfs] APIs affected by btrfs subvolumes

[Matthew Booth]

On Tue, 2013-01-22 at 15:15 +0000, Richard W.M. Jones wrote:
> Here's my suggestion.
> 
> We add a new type 'Mountable' to the generator.  This is the same as a
> string, so it doesn't change the strict C ABI (nor the semantics --
> see below).  Certain APIs that take a Device parameter would need to
> change to take a Mountable instead.
> 
> Certain APIs that return RString/RStringList won't change their
> generator types, but what can be in the string may change.
> 
> A Mountable string is normally just a device name, eg. "/dev/sda1".
> But for special filesystems it may contain an extended string.  I
> suggest "/dev/sda1:btrfs:<subvolume_name>" for btrfs.  Other weird
> filesystems may need other extensions in future.

I'd make 1 change to this. Where a mountable isn't a bare device I'd put
the device type first as I originally proposed. The reason for this is
that a mountable doesn't necessarily reference a single block device, or
indeed any block device (think nfs and iscsi). Also, I'd differentiate
btrfs and a btrfs subvol. The former can be a bare device, the latter:

btrfsvol:<device>,<subvolume_name>

where <device> is any block device which is part of the filesystem.

> Inspection APIs take and return a Mountable (so Device "root" becomes
> Mountable "root").
> 
> 'list-filesystems' returns a list of Mountables (actually it still
> returns an RStringList, but it's a list of Mountables).

Hmm. I missed RHashtable in my search. I'd better check for others.

> 'mount' and friends take a Mountable instead of a Device.
> 
> The generator will need to make a small change in the way it checks
> the Mountable parameter at runtime (q.v. the way Device is checked
> now, eg. the macro RESOLVE_DEVICE will need another macro
> RESOLVE_MOUNTABLE).
> 
> Obviously the ABI doesn't change, since it's all still strings.  But I
> also claim that the semantics of the API don't change: Any existing
> program that works now will continue to work unchanged.  Only programs
> that would now fail (eg. they try to inspect btrfs guests) would be
> affected by this change, and in fact those programs would not need to
> be modified, they would just start to work correctly.

With the minor tweak above, I like this.

It does change the semantics slightly, though. Previously, a program
could assume that something returned by list_filesystems or inspect_os
was a block device and use it as such, whereas now it can't. However, as
you point out that was already broken. This change would mean it would
be broken differently, though. How much do we care about this?

I'm happy to start hacking on this now,

Matt