Update proto.txt

[nbd.git] / doc / proto.txt

diff --git a/doc/proto.txt b/doc/proto.txt
index d173365..4869e02 100644 (file)
--- a/doc/proto.txt
+++ b/doc/proto.txt
@@ -34,7 +34,9 @@ header consists a 32 bit magic number (magic), a 32 bit field denoting
 the request type (see below; 'type'), a 64 bit handle ('handle'), a 64
 bit data offset ('from'), and a 32 bit length ('len'). In case of a
 write request, the header is immediately followed by 'len' bytes of
-data.
+data. In the case of NBD_CMD_FLUSH, the offset and length should
+be zero (meaning "flush entire device"); other values are reserved
+for future use (e.g. for flushing specific areas without a write).
 
 The reply contains three fields: a 32 bit magic number ('magic'), a 32
 bit error code ('error'; 0, unless an error occurred in which case it is
@@ -55,7 +57,7 @@ and indicates the backing file should be fdatasync()'d to disk.
 
 The top 16 bits of the request are flags. NBD_CMD_FLAG_FUA implies
 a force unit access, and can currently only be usefully combined
-with NBD_CMD_WRITE. This is implementing using sync_file_range
+with NBD_CMD_WRITE. This is implemented using sync_file_range
 if present, else by fdatasync() of that file (note not all files
 in a multifile environment). NBD_CMD_FLAG_FUA will not be set
 unless NBD_FLAG_SEND_FUA is set.
@@ -93,10 +95,13 @@ only still supported for backwards compatibility.
 'new' style handshake
 ---------------------
 
-A client who wants to use the new style negotiation MUST connect on the
-IANA-reserved port for NBD, 10809. The server may listen on other ports
-as well, but it will use the old style handshake on those. The server
-will refuse to allow old-style negotiations on the new-style port.
+A client who wants to use the new style negotiation should connect on
+the IANA-reserved port for NBD, 10809. The server may listen on other
+ports as well, but it will use the old style handshake on those. The
+server will refuse to allow old-style negotiations on the new-style
+port. For debugging purposes, the server may change the port on which to
+listen for new-style negotiation, but this should not happen for
+production purposes.
 
 S: "NBDMAGIC" (as in the old style handshake)
 S: 0x49484156454F5054 (note different magic number)