20060303-partial

1 files changed, 78 insertions, 0 deletions

diff --git a/man/5/flush b/man/5/flush
new file mode 100644
index 00000000..48c2d306
--- /dev/null
+++ b/man/5/flush
@@ -0,0 +1,78 @@
+.TH FLUSH 5
+.SH NAME
+flush \- abort a message
+.SH SYNOPSIS
+.ta \w'\fLTflush 'u
+.IR size [4]
+.B Tflush
+.IR tag [2]
+.IR oldtag [2]
+.br
+.IR size [4]
+.B Rflush
+.IR tag [2]
+.SH DESCRIPTION
+When the response to a request is no longer needed, such as when
+a user interrupts a process doing a
+.IR sys-read (2),
+a
+.B Tflush
+request is sent to the server to purge the pending response.
+The message being flushed is identified by
+.IR oldtag .
+The semantics of
+.B flush
+depends on messages arriving in order.
+.PP
+The server must answer the
+.B flush
+message immediately.
+If it recognizes
+.I oldtag
+as the tag of a pending transaction, it should abort any pending response
+and discard that tag.
+In either case, it should respond with an
+.B Rflush
+echoing the
+.I tag
+(not
+.IR oldtag )
+of the
+.B Tflush
+message.
+A
+.B Tflush
+can never be responded to by an
+.B Rerror
+message.
+.PP
+When the client sends a 
+.BR Tflush ,
+it must wait to receive the corresponding
+.B Rflush
+before reusing
+.I oldtag
+for subsequent messages.
+If a response to the flushed request is received before the
+.BR Rflush ,
+the client must honor the response
+as if it had not been flushed,
+since the completed request may signify a state change in the server.
+For instance,
+.B Tcreate
+may have created a file and
+.B Twalk
+may have allocated a fid.
+If no response is received before the
+.BR Rflush ,
+the flushed transaction is considered to have been cancelled,
+and should be treated as though it had never been sent.
+.PP
+Several exceptional conditions are handled correctly by the above specification:
+sending multiple flushes for a single tag,
+flushing after a transaction is completed,
+flushing a
+.BR Tflush ,
+and flushing an invalid tag.
+.SH SEE ALSO
+.IR sys-read (2).