Consistently use the spelling UTF-8.
Make it clear that when a UTF-8 string is transmitted, the sender
need not transmit a terminating NUL byte, so the receiver must pay
attention to length. Require error messages to be UTF-8 (thankfully,
this would include the case of an all-ASCII LC_ALL=C strerror
message).
Clean up the wording related to NBD_REP_SERVER when there is extra
data beyond the name, calling out specifically that the extra data
is either a UTF-8 string (with no further definition), or
a specific struct defined by the particular client request. Fix
the formatting (the note about SELECT changing the semantics of
the extra data is not a field within the data).
Signed-off-by: Eric Blake <ebl...@redhat.com>
---
doc/proto.md | 46 ++++++++++++++++++++++++++++------------------
1 file changed, 28 insertions(+), 18 deletions(-)
diff --git a/doc/proto.md b/doc/proto.md
index ea7a94f..04d4a13 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -283,11 +283,13 @@ of the newstyle negotiation.
Choose the export which the client would like to use, end option
haggling, and proceed to the transmission phase. Data: name of the
- export, free-form UTF8 text (subject to limitations by server
- implementation). If the chosen export does not exist or requirements
- for the chosen export are not met (e.g., the client did not
- negotiate TLS for an export where the server requires it), the
- server should close the connection.
+ export, free-form UTF-8 text (subject to limitations by server
+ implementation). The length of the name is determined from the
+ option header, and does NOT include a NUL terminator. If the
+ chosen export does not exist or requirements for the chosen export
+ are not met (e.g., the client did not negotiate TLS for an export
+ where the server requires it), the server should close the
+ connection.
A special, "empty", name (i.e., the length field is zero and no name
is specified), is reserved for a "default" export, to be used in cases
@@ -355,21 +357,28 @@ during option haggling in the fixed newstyle negotiation.
A description of an export. Data:
- - 32 bits, length of name (unsigned)
- - Name of the export, as expected by `NBD_OPT_EXPORT_NAME`
- - If length of name < (length of reply as sent in the reply packet
- header - 4), then the rest of the data contains some undefined
- implementation-specific details about the export. This is not
- currently implemented, but future versions of nbd-server may send
- along some details about the export. If the client did not
- explicitly request otherwise, these details are defined to be
- UTF-8 encoded data suitable for direct display to a human being.
- - The experimental `SELECT` extension (see below) adds extra data to
- the end of this request.
+ - 32 bits, length of name (unsigned); MUST be no larger than the
+ reply packet header length - 4
+ - Name of the export, as expected by `NBD_OPT_EXPORT_NAME` (note
+ that the length of name does NOT include a NUL terminator)
+ - If length of name < (reply packet header length - 4), then the
+ rest of the data contains some implementation-specific details
+ about the export. This is not currently implemented, but future
+ versions of nbd-server may send along some details about the
+ export. Therefore, unless explicitly documented otherwise by a
+ particular client request, this field is defined to be UTF-8
+ encoded data suitable for direct display to a human being; a
+ client SHOULD NOT assume that the data is NUL-terminated.
+
+ The experimental `SELECT` extension (see below) is a client
+ request where the extra data has a definition other than a
+ UTF-8 message.
There are a number of error reply types, all of which are denoted by
having bit 31 set. All error replies MAY have some data set, in which
-case that data is an error message suitable for display to the user.
+case that data is an error message in UTF-8 encoding suitable for
+display to the user, although the client MUST NOT assume that a
+terminating NUL is present.
* `NBD_REP_ERR_UNSUP` (2^31 + 1)
@@ -610,7 +619,8 @@ option reply type.
- 16 bits, transmission flags
That is, the `NBD_REP_SERVER` message is extended to also include
- the data sent in reply to the `NBD_OPT_EXPORT_NAME` option.
+ the data sent in reply to the `NBD_OPT_EXPORT_NAME` option, and
+ the option reply length MUST be the length of name + 14.
- For backwards compatibility, clients should be prepared to also
handle `NBD_REP_ERR_UNSUP`. In this case, they should fall back to
using `NBD_OPT_EXPORT_NAME`.
--
2.5.5
------------------------------------------------------------------------------
Transform Data into Opportunity.
Accelerate data analysis in your applications with
Intel Data Analytics Acceleration Library.
Click to learn more.
http://pubads.g.doubleclick.net/gampad/clk?id=278785471&iu=/4140
_______________________________________________
Nbd-general mailing list
Nbd-general@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/nbd-general
