share/man/man4/ttcp.4

   1 .\" Copyright 1994, 1995 Massachusetts Institute of Technology
   2 .\"
   3 .\" Permission to use, copy, modify, and distribute this software and
   4 .\" its documentation for any purpose and without fee is hereby
   5 .\" granted, provided that both the above copyright notice and this
   6 .\" permission notice appear in all copies, that both the above
   7 .\" copyright notice and this permission notice appear in all
   8 .\" supporting documentation, and that the name of M.I.T. not be used
   9 .\" in advertising or publicity pertaining to distribution of the
  10 .\" software without specific, written prior permission.  M.I.T. makes
  11 .\" no representations about the suitability of this software for any
  12 .\" purpose.  It is provided "as is" without express or implied
  13 .\" warranty.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
  16 .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
  17 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  18 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
  19 .\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  20 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  21 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  22 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  24 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  25 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD: src/share/man/man4/ttcp.4,v 1.8.2.6 2001/12/17 11:30:12 ru Exp $
  29 .\" $DragonFly: src/share/man/man4/ttcp.4,v 1.3 2007/07/14 21:48:15 swildner Exp $
  30 .\"
  31 .Dd January 18, 1995
  32 .Dt TTCP 4
  33 .Os
  34 .Sh NAME
  35 .Nm ttcp
  36 .Nd Transmission Control Protocol Extensions for Transactions
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In sys/socket.h
  40 .In netinet/in.h
  41 .In netinet/tcp.h
  42 .Ft int
  43 .Fn setsockopt sock IPPROTO_TCP TCP_NOPUSH &One "sizeof One"
  44 .Ft ssize_t
  45 .Fn sendto sock msg len MSG_EOF &sin "sizeof sin"
  46 .Ft ssize_t
  47 .Fn sendto sock msg len MSG_EOF 0 0
  48 .Sh DESCRIPTION
  49 .Tn T/TCP
  50 refers to a set of extensions to the
  51 .Tn TCP
  52 protocol (see
  53 .Xr tcp 4 )
  54 which permit hosts to reliably exchange a small amount of data in a
  55 two-packet exchange, thus eliminating the extra round-trip delays
  56 inherent in a standard
  57 .Tn TCP
  58 connection.  The socket interface includes modifications to support
  59 .Tn T/TCP ,
  60 detailed here for the specific case, and in the
  61 .Xr socket 2
  62 and
  63 .Xr send 2
  64 manual pages for the protocol-independent support.
  65 .Tn T/TCP
  66 is defined in RFC 1644.
  67 .Pp
  68 The
  69 .Tn T/TCP
  70 extensions work by including certain options in all segments of a
  71 particular connection, which enable the implementation to avoid the
  72 three-way handshake for all but the first connection between a pair of
  73 hosts.  These same options also make it possible to more reliably
  74 recognize old, duplicate packets, which in turn reduces the amount of
  75 time the
  76 .Tn TCP
  77 protocol must maintain state after a connection closes.  The
  78 .Va net.inet.tcp.rfc1644
  79 MIB variable can be used to disable
  80 .Tn T/TCP
  81 negotiation at run time; however, the protocol has been designed to
  82 ensure that attempts by non-T/TCP
  83 systems to communicate with T/TCP-enhanced
  84 ones automatically degenerate into standard
  85 .Tn TCP .
  86 .Sh TRANSACTION MODEL
  87 The expected model of a
  88 .Dq transaction
  89 as used by
  90 .Tn T/TCP
  91 is a fairly simple one:
  92 .Bl -enum
  93 .It
  94 A client program generates a request to be sent to the server, which
  95 is small enough to fit in a single
  96 .Tn TCP
  97 segment, and sends a SYN PUSH FIN segment with options and data to the
  98 server.
  99 .It
 100 The server program accepts the request in the same manner as for
 101 regular
 102 .Tn TCP
 103 connections, interprets it, and generates a reply which may be small
 104 enough to fit in a single segment.  If it is, the reply is sent in a
 105 single SYN PUSH FIN ACK segment with (different) options and data back
 106 to the client.  If not, then the connection degenerates into (almost)
 107 the usual case for
 108 .Tn TCP .
 109 The server then closes its socket.
 110 .It
 111 The client reads the reply and closes its socket.
 112 .El
 113 .Sh CLIENT SUPPORT
 114 Support on the client side is provided by extending the semantics of
 115 the
 116 .Xr sendto 2
 117 and
 118 .Xr sendmsg 2
 119 system calls to understand the notion of
 120 .Dq implied connect
 121 and
 122 .Dq send and shutdown .
 123 To send the request in a transaction, the
 124 .Xr sendto 2
 125 system call is typically used, as in the following example:
 126 .Bd -literal -offset indent
 127 char request[REQ_LEN];
 128 struct sockaddr_in sin;
 129 int sock, req_len;
 130
 131 sock = socket(PF_INET, SOCK_STREAM, 0);
 132
 133 /* prepare request[] and sin */
 134
 135 err = sendto(sock, request, req_len, MSG_EOF,
 136         (struct sockaddr *)&sin, sin.sin_len);
 137
 138 /* do something if error */
 139
 140 req_len = read(sock, request, sizeof request);
 141 close(sock);
 142
 143 /* do something with the reply */
 144
 145 .Ed
 146 .Pp
 147 Note that, after the
 148 call to
 149 .Fn sendto ,
 150 the socket is now in the same state as if the
 151 .Xr connect 2
 152 and
 153 .Xr shutdown 2
 154 system calls had been used.  That is to say, the only reasonable
 155 operations to perform on this socket are
 156 .Xr read 2
 157 and
 158 .Xr close 2 .
 159 (Because the client's
 160 .Tn TCP
 161 sender is already shut down, it is not possible to
 162 .Xr connect 2
 163 this socket to another destination.)
 164 .Sh SERVER SUPPORT
 165 There are two different options available for servers using
 166 .Tn T/TCP :
 167 .Bl -enum
 168 .It
 169 Set the
 170 .Dv TCP_NOPUSH
 171 socket option, and use normal
 172 .Xr write 2
 173 calls when formulating the response.
 174 .It
 175 Use
 176 .Xr sendto 2
 177 with the
 178 .Dv MSG_EOF
 179 flag, as in the client, but with the destination unspecified.
 180 .El
 181 .Pp
 182 The first option is generally the appropriate choice when converting
 183 existing servers to use
 184 .Tn T/TCP
 185 extensions; simply add a call to
 186 .Fn setsockopt sock IPPROTO_TCP TCP_NOPUSH &One "sizeof One"
 187 (where
 188 .Va One
 189 is an integer variable with a non-zero value).  The server socket must
 190 be closed before any data is sent (unless the socket buffers fill up).
 191 .Pp
 192 The second option is preferable for new servers, and is sometimes easy
 193 enough to retrofit into older servers.  In this case, where the reply
 194 phase would ordinarily have included a call to
 195 .Fn write ,
 196 one substitutes:
 197 .Pp
 198 .Dl "sendto(sock, buf, len, MSG_EOF, NULL, 0)"
 199 .Pp
 200 In this case, the reply is sent immediately, but as in the client
 201 case, the socket is no longer useful for anything and should be
 202 immediately closed.
 203 .Sh MIB VARIABLES
 204 The
 205 .Tn T/TCP
 206 extensions require the
 207 .Va net.inet.tcp.rfc1644
 208 MIB variable to be true in order for the appropriate
 209 .Tn TCP
 210 options to be sent.  See
 211 .Xr tcp 4
 212 for more information.
 213 .Sh SEE ALSO
 214 .Xr send 2 ,
 215 .Xr setsockopt 2 ,
 216 .Xr inet 4 ,
 217 .Xr tcp 4
 218 .Rs
 219 .%A R. Braden
 220 .%T "T/TCP \- TCP Extensions for Transactions"
 221 .%O RFC 1644
 222 .Re
 223 .Sh HISTORY
 224 Support for
 225 .Tn T/TCP
 226 first appeared in
 227 .Fx 2.1 ,
 228 based on code written by Bob Braden and Liming Wei at the
 229 University of Southern California, Information Sciences Institute, and
 230 ported by Andras Olah at the University of Twente.