Document Transaction TCP.

1 files changed, 225 insertions, 0 deletions

diff --git a/share/man/man4/ttcp.4 b/share/man/man4/ttcp.4
new file mode 100644
index 0000000..ab585fe
--- /dev/null
+++ b/share/man/man4/ttcp.4
@@ -0,0 +1,225 @@
+.\" Copyright 1994, 1995 Massachusetts Institute of Technology
+.\"
+.\" Permission to use, copy, modify, and distribute this software and
+.\" its documentation for any purpose and without fee is hereby
+.\" granted, provided that both the above copyright notice and this
+.\" permission notice appear in all copies, that both the above
+.\" copyright notice and this permission notice appear in all
+.\" supporting documentation, and that the name of M.I.T. not be used
+.\" in advertising or publicity pertaining to distribution of the
+.\" software without specific, written prior permission.  M.I.T. makes
+.\" no representations about the suitability of this software for any
+.\" purpose.  It is provided "as is" without express or implied
+.\" warranty.
+.\" 
+.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
+.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
+.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
+.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $Id$
+.\"
+.Dd February 15, 1995
+.Dt TTCP 4
+.Os FreeBSD 2.1
+.Sh NAME
+.Nm ttcp
+.Nd Transmission Control Protocol Extensions for Transactions
+.Sh
+.Fd #include <sys/socket.h>
+.Fd #include <netinet/in.h>
+.Fd #include <netinet/tcp.h>
+.Ft int
+.Fn setsockopt sock IPPROTO_TCP TCP_NOPUSH &One "sizeof One"
+.br
+.Ft ssize_t
+.Fn sendto sock msg len MSG_EOF &sin "sizeof sin"
+.br
+.Ft ssize_t
+.Fn sendto sock msg len MSG_EOF 0 0
+.Sh DESCRIPTION
+.Tn T/TCP
+refers to a set of extensions to the
+.Tn TCP
+protocol (see
+.Xr tcp 4 )
+which permit hosts to reliably exchange a small amount of data in a
+two-packet exchange, thus eliminating the extra round-trip delays
+inherent in a standard
+.Tn TCP
+connection.  The socket interface includes modifications to support
+.Tn T/TCP , detailed here for the specific case, and in the
+.Xr socket 2
+and
+.Xr send 2
+manual pages for the protocol-independent support.
+.Tn T/TCP
+is defined in RFC 1644.
+.Pp
+The
+.Tn T/TCP
+extensions work by including certain options in all segments of a
+particular connection, which enable the implementation to avoid the
+three-way handshake for all but the first connection between a pair of
+hosts.  These same options also make it possible to more reliably
+recognize old, duplicate packets, which in turn reduces the amount of
+time the
+.Tn TCP
+protocol must maintain state after a connection closes.  The
+net.inet.tcp.rfc1644 MIB variable can be used to disable
+.Tn T/TCP
+negotiation at run time; however, the protocol has been designed to
+ensure that attempts by non-T/TCP
+systems to communicate with T/TCP-enhanced
+ones automatically degenerate into standard
+.Tn TCP .
+.Sh TRANSACTION MODEL
+The expected model of a
+.Dq transaction
+as used by
+.Tn T/TCP
+is a fairly simple one:
+.Bl -enum
+.It
+A client program generates a request to be sent to the server, which
+is small enough to fit in a single
+.Tn TCP
+segment, and sends a SYN PUSH FIN segment with options and data to the
+server.
+.It
+The server program accepts the request in the same manner as for
+regular
+.Tn TCP
+connections, interprets it, and generates a reply which may be small
+enough to fit in a single segment.  If it is, the reply is sent in a
+single SYN PUSH FIN ACK segment with (different) options and data back
+to the client.  If not, then the connection degenerates into (almost)
+the usual case for
+.Tn TCP .
+.El
+.Sh CLIENT SUPPORT
+Support on the client side is provided by extending the semantics of
+the
+.Xr sendto 2
+and
+.Xr sendmsg 2
+system calls to understand the notion of
+.Dq implied connect
+and
+.Dq send and shutdown.
+To send the request in a transaction, the
+.Xr sendto 2
+system call is typically used, as in the following example:
+.Bd -literal -offset indent
+char request[REQ_LEN];
+struct sockaddr_in sin;
+int sock, req_len;
+
+sock = socket(PF_INET, SOCK_STREAM, 0);
+
+/* prepare request[] and sin */
+
+err = sendto(sock, request, req_len, MSG_EOF, 
+	(struct sockaddr *)&sin, sin.sin_len);
+
+/* do something if error */
+
+req_len = read(sock, request, sizeof request);
+close(sock);
+
+/* do something with the reply */
+
+.Ed
+.Pp
+Note that, after the 
+call to
+.Fn sendto ,
+the socket is now in the same state as if the
+.Xr connect 2
+and
+.Xr shutdown 2
+system calls had been used.  That is to say, the only reasonable
+operations to perform on this socket are
+.Xr read 2
+and
+.Xr close 2 .
+(Because the client's 
+.Tn TCP
+sender is already shut down, it is not possible to
+.Xr connect 2
+this socket to another destination.)
+.Sh SERVER SUPPORT
+There are two different options available for servers using
+.Tn T/TCP :
+.Bl -enum
+.It
+Set the
+.Dv TCP_NOPUSH
+socket option, and use normal
+.Xr write 2
+calls when formulating the response.
+.It
+Use
+.Xr sendto 2
+with the
+.Dv MSG_EOF
+flag, as in the client, but with the destination unspecified.
+.El
+.Pp
+The first option is generally the appropriate choice when converting
+existing servers to use
+.Tn T/TCP
+extensions; simply add a call to
+.Fn setsockopt sock IPPROTO_TCP TCP_NOPUSH &One "sizeof One"
+(where
+.Va One
+is an integer variable with a non-zero value).  The server socket must
+be closed before any data is sent (unless the socket buffers fill up).
+.Pp
+The second option is preferable for new servers, and is sometimes easy
+enough to retrofit into older servers.  In this case, where the reply
+phase would ordinarily have included a call to
+.Xr write 2 ,
+one substitutes
+.Fn sendto sock reply_buf reply_len MSG_EOF "(struct sockaddr *)0" 0 .
+In this case, the reply is sent immediately, but as in the client
+case, the socket is no lnoger useful for anything and should be
+immediately closed.
+.Sh MIB VARIABLES
+The
+.Tn T/TCP
+extensions require the 
+.Dq net.inet.tcp.rfc1323
+and
+.Dq net.inet.tcp.rfc1644
+MIB variables to both be true in order for the appropriate
+.Tn TCP
+options to be sent.  See
+.Xr tcp 4
+for more information.
+.Sh SEE ALSO
+.Xr send 2 ,
+.Xr setsockopt 2 ,
+.Xr inet 4 ,
+.Xr tcp 4
+.Rs
+.%A R. Braden
+.%T "T/TCP \- TCP Extensions for Transactions"
+.%O RFC 1644
+.Re
+.Sh HISTORY
+Support for
+.Tn T/TCP
+first appeared in
+.Tn FreeBSD
+2.1, based on code written by Bob Braden and Liming Wei at the
+University of Southern California, Information Sciences Institute, and
+ported by Andras Olah at the University of Twente.