Re: [Libguestfs] [PATCH nbdkit v4 01/15] server: Implement extents/can_extents calls for plugins and filters.

On 3/26/19 4:17 PM, Richard W.M. Jones wrote: > This pair of calls allows plugins to describe which extents in the > virtual disk are allocated, holes or zeroes. > --- > +=head2 C<.extents> > + > + int extents (void *handle, uint32_t count, uint64_t offset, > + uint32_t flags, struct nbdkit_extents *extents); > + > +During the data serving phase, this callback is used to detect > +allocated, sparse and zeroed regions of the disk. > + > +This function will not be called if C<.can_extents> returned false. > +nbdkit's default behaviour in this case is to treat the whole virtual > +disk as if it was allocated. > + > +The callback should detect and return the list of extents overlapping > +the range C<[offset...offset+count-1]>. The C<extents> parameter > +points to an opaque object which the callback should fill in by > +calling C<nbdkit_add_extent>. See L</Extents list> below. [1] > + > +If there is an error, C<.extents> should call C<nbdkit_error> with an > +error message, and C<nbdkit_set_error> to record an appropriate error > +(unless C<errno> is sufficient), then return C<-1>. > + > +=head3 Extents list > + > +The plugin C<extents> callback is passed an opaque pointer C<struct > +nbdkit_extents *extents>. This structure represents a list of > +L<filesystem extents|https://en.wikipedia.org/wiki/Extent_(file_systems)> > +describing which areas of the disk are allocated, which are sparse > +(“holes”), and, if supported, which are zeroes. > + > +The C<extents> callback should scan the disk starting at C<offset> and > +call C<nbdkit_add_extent> for each extent found. > + > +Extents overlapping the range C<[offset...offset+count-1]> should be > +returned if possible. However nbdkit ignores extents E<lt> offset so > +the plugin may, if it is easier to implement, return all extent > +information for the whole disk. The plugin may return extents beyond > +the end of the range. It may also return extent information for less > +than the whole range, but it must return at least one extent > +overlapping C<offset>. > + > +The extents B<must> be added in ascending order, and B<must> be > +contiguous. > + > +The C<flags> parameter may contain the flag C<NBDKIT_FLAG_REQ_ONE> > +which means that the client is only requesting information about the > +extent overlapping C<offset>. The plugin may ignore this flag, or as > +an optimization it may return just a single extent for C<offset>. I wonder if this paragraph belongs up at [1]. Looks good to me.