[Libguestfs] [libnbd PATCH] docs: Mention explicit and inherent limits on lengths

[Eric Blake]

On Fri, Dec 03, 2021 at 01:50:36PM +0100, Laszlo Ersek wrote:
> > @@ -1822,6 +1822,12 @@ error.  See also L<nbd_pread_structured(3)>, if finer visibility is
> >  required into the server's replies, or if you want to use
> >  C<LIBNBD_CMD_FLAG_DF>.
> > 
> > +Note that libnbd currently enforces a maximum read buffer of 64MiB,
> > +even if the server would permit a larger buffer in a single transaction;
> > +attempts to exceed this will result in an C<ERANGE> error.  The server
> > +may enforce a smaller limit, which can be learned with
> > +L<nbd_get_block_size(3)>.
> > +
> >  The C<flags> parameter must be C<0> for now (it exists for future NBD
> >  protocol extensions)."
> >  ^ strict_call_description;
> 
> This hunk is for pread, OK.
...

> 
> Request for the future:
> 
> - please let us document the affected functions (function descriptions)
> in the commit message, or else

Always a good idea, regardless of your next suggestion (since your
next one is not an out-of-the-box solution).

> 
> - please let us figure out a pattern for git-diff that lets us see the
> affected functions directly in the diff (in the @@ hunk headers).
> 
> For example, we could put the following in the .gitattributes file, in
> the libnbd project root (or else in each local .git/info/attributes):
> 
>   API.ml diff=api
> 
> and then
> 
>   git config diff.api.xfuncname '^  "[^"]*", \{$'

Cool.  Even better: '^(let .*=|"[^"]*", \{$)', which also gives
context for top-level OCaml let statements.

I'll propose that as another patch shortly.  The problem is we have no
where to automate this into a new developer's workflow (we don't have
a bootstrap script they are required to run), so the best we can do is
document and hope they read it.  Then again, there are currently very
few active libnbd developers, all of whom will read this message and
make the right tweaks...

> 
> With that in place, your patch is formatted (e.g. by git-show) with the
> following hunk headers:
> 
> @@ -1822,6 +1822,12 @@   "pread", {
> @@ -1898,6 +1904,12 @@   "pread_structured", {
> @@ -1924,6 +1936,12 @@   "pwrite", {
> @@ -2007,6 +2025,12 @@   "trim", {
> @@ -2032,6 +2056,12 @@   "cache", {
> @@ -2055,6 +2085,13 @@   "zero", {
> @@ -2088,6 +2125,12 @@   "block_status", {
> 
> Acked-by: Laszlo Ersek <lersek at redhat.com>

Thanks.  Now in as commit 430ed75eb0

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org