Libguestfs - Sep 2019 - [PATCH libnbd] docs: Document limits on export name.

This commit documents the limits on export name, encoding, etc.
---
 generator/generator | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/generator/generator b/generator/generator
index a72f36c..87a8cdf 100755
--- a/generator/generator
+++ b/generator/generator
@@ -1066,10 +1066,16 @@ C<\"nbd2\">, etc.";
     longdesc = "\
 For servers which require an export name or can serve different
 content on different exports, set the C<export_name> to
-connect to.  This is only relevant for the newstyle protocol.
+connect to.  The default is the empty string C<\"\">.
+
+This is only relevant when connecting to servers using the
+newstyle protocol as the oldstyle protocol did not support
+export names.  The NBD protocol limits export names to
+4096 bytes, but servers may not support the full length.
+The encoding of export names is always UTF-8.
+
 This call may be skipped if using L<nbd_connect_uri(3)> to connect
-to a URI that includes an export name.  The default is to use
-the empty string.";
+to a URI that includes an export name.";
   };
 
   "get_export_name", {
-- 
2.23.0

On 9/17/19 3:32 AM, Richard W.M. Jones wrote:
> This commit documents the limits on export name, encoding, etc.
> ---
>  generator/generator | 12 +++++++++---
>  1 file changed, 9 insertions(+), 3 deletions(-)
> 
ACK.
> diff --git a/generator/generator b/generator/generator
> index a72f36c..87a8cdf 100755
> --- a/generator/generator
> +++ b/generator/generator
> @@ -1066,10 +1066,16 @@ C<\"nbd2\">, etc.";
>      longdesc = "\
>  For servers which require an export name or can serve different
>  content on different exports, set the C<export_name> to
> -connect to.  This is only relevant for the newstyle protocol.
> +connect to.  The default is the empty string C<\"\">.
> +
> +This is only relevant when connecting to servers using the
> +newstyle protocol as the oldstyle protocol did not support
> +export names.  The NBD protocol limits export names to
> +4096 bytes, but servers may not support the full length.
Too true - in the other thread, you pointed out that nbdkit currently
includes overhead bytes so the real limit is slightly less; and qemu's
limit is closer to 512 bytes.
> +The encoding of export names is always UTF-8.
> +
>  This call may be skipped if using L<nbd_connect_uri(3)> to connect
> -to a URI that includes an export name.  The default is to use
> -the empty string.";
> +to a URI that includes an export name.";
Probably also worth a see_also = ["L<nbd_connect_uri(3)>"] while
you're
touching this.

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

On 9/17/19 6:38 AM, Eric Blake wrote:
>> +++ b/generator/generator
>> @@ -1066,10 +1066,16 @@ C<\"nbd2\">, etc.";
>>      longdesc = "\
>>  For servers which require an export name or can serve different
>>  content on different exports, set the C<export_name> to
>> -connect to.  This is only relevant for the newstyle protocol.
>> +connect to.  The default is the empty string C<\"\">.
>> +
>> +This is only relevant when connecting to servers using the
>> +newstyle protocol as the oldstyle protocol did not support
>> +export names.  The NBD protocol limits export names to
>> +4096 bytes, but servers may not support the full length.
nbd_add_meta_context deserves the same text.  I'm adding that now...

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