[Libguestfs] [nbdkit PATCH 4/4] doc: More details on (lack of) dynamic sizing

We already documented in the lifetime section that .get_size is in the same boat as .can_write and friends, where the values reported may change between connections, but should generally remain constant for a given connection and that other parts of the code may cache rather than constantly re-check the callback. However, it is worth a bit more detail directly on the .get_size callback, in particular mentioning that a server that allows externally growing images is generally safe. When the NBD protocol extension for dynamic resize is finally implemented, we'll probably have to add more rules on how and when size can change. Signed-off-by: Eric Blake <eblake(a)redhat.com&gt; --- docs/nbdkit-plugin.pod | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/nbdkit-plugin.pod b/docs/nbdkit-plugin.pod index e9dc34f..15d571f 100644 --- a/docs/nbdkit-plugin.pod +++ b/docs/nbdkit-plugin.pod @@ -479,6 +479,15 @@ check for errors, but obviously this is outside the scope of nbdkit. This is called during the option negotiation phase of the protocol to get the size (in bytes) of the block device being exported. +The NBD protocol does not currently provide a way for a client to +learn about or request any dynamic size changes. Thus, although this +callback may return different values across different C<.open> calls, +other code in nbdkit may cache the size reported during open, rather +than checking for the current size. It is generally safe to report a +larger size than before (even if the client will not access beyond the +original size), but risky to shrink an image below the size in use by +any current connection. + The returned size must be E<ge> 0. If there is an error, C<.get_size> should call C<nbdkit_error> with an error message and return C<-1>. -- 2.20.1