bsd/man/man4/tcp.4

   1 .\"     $NetBSD: tcp.4,v 1.3 1994/11/30 16:22:35 jtc Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)tcp.4       8.1 (Berkeley) 6/5/93
  35 .\"
  36 .Dd February 28, 2007
  37 .Dt TCP 4
  38 .Os BSD 4.2
  39 .Sh NAME
  40 .Nm tcp
  41 .Nd Internet Transmission Control Protocol
  42 .Sh SYNOPSIS
  43 .In sys/types.h
  44 .In sys/socket.h
  45 .In netinet/in.h
  46 .Ft int
  47 .Fn socket AF_INET SOCK_STREAM 0
  48 .Sh DESCRIPTION
  49 The
  50 .Tn TCP
  51 protocol provides reliable, flow-controlled, two-way
  52 transmission of data.
  53 It is a byte-stream protocol used to
  54 support the
  55 .Dv SOCK_STREAM
  56 abstraction.
  57 .Tn TCP
  58 uses the standard
  59 Internet address format and, in addition, provides a per-host
  60 collection of
  61 .Dq "port addresses" .
  62 Thus, each address is composed
  63 of an Internet address specifying the host and network,
  64 with a specific
  65 .Tn TCP
  66 port on the host identifying the peer entity.
  67 .Pp
  68 Sockets utilizing the
  69 .Tn TCP
  70 protocol are either
  71 .Dq active
  72 or
  73 .Dq passive .
  74 Active sockets initiate connections to passive
  75 sockets.
  76 By default,
  77 .Tn TCP
  78 sockets are created active; to create a
  79 passive socket, the
  80 .Xr listen 2
  81 system call must be used
  82 after binding the socket with the
  83 .Xr bind 2
  84 system call.
  85 Only passive sockets may use the
  86 .Xr accept 2
  87 call to accept incoming connections.
  88 Only active sockets may use the
  89 .Xr connect 2
  90 call to initiate connections.
  91 .Pp
  92 Passive sockets may
  93 .Dq underspecify
  94 their location to match
  95 incoming connection requests from multiple networks.
  96 This technique, termed
  97 .Dq "wildcard addressing" ,
  98 allows a single
  99 server to provide service to clients on multiple networks.
 100 To create a socket which listens on all networks, the Internet
 101 address
 102 .Dv INADDR_ANY
 103 must be bound.
 104 The
 105 .Tn TCP
 106 port may still be specified
 107 at this time; if the port is not specified, the system will assign one.
 108 Once a connection has been established, the socket's address is
 109 fixed by the peer entity's location.
 110 The address assigned to the
 111 socket is the address associated with the network interface
 112 through which packets are being transmitted and received.
 113 Normally, this address corresponds to the peer entity's network.
 114 .Pp
 115 .Tn TCP
 116 supports a number of socket options which can be set with
 117 .Xr setsockopt 2
 118 and tested with
 119 .Xr getsockopt 2 :
 120 .Bl -tag -width ".Dv TCP_CONNECTIONTIMEOUT"
 121 .It Dv TCP_NODELAY
 122 Under most circumstances,
 123 .Tn TCP
 124 sends data when it is presented;
 125 when outstanding data has not yet been acknowledged, it gathers
 126 small amounts of output to be sent in a single packet once
 127 an acknowledgement is received.
 128 For a small number of clients, such as window systems
 129 that send a stream of mouse events which receive no replies,
 130 this packetization may cause significant delays.
 131 The boolean option
 132 .Dv TCP_NODELAY
 133 defeats this algorithm.
 134 .It Dv TCP_MAXSEG
 135 By default, a sender- and
 136 .No receiver- Ns Tn TCP
 137 will negotiate among themselves to determine the maximum segment size
 138 to be used for each connection.
 139 The
 140 .Dv TCP_MAXSEG
 141 option allows the user to determine the result of this negotiation,
 142 and to reduce it if desired.
 143 .It Dv TCP_NOOPT
 144 .Tn TCP
 145 usually sends a number of options in each packet, corresponding to
 146 various
 147 .Tn TCP
 148 extensions which are provided in this implementation.
 149 The boolean option
 150 .Dv TCP_NOOPT
 151 is provided to disable
 152 .Tn TCP
 153 option use on a per-connection basis.
 154 .It Dv TCP_NOPUSH
 155 By convention, the
 156 .No sender- Ns Tn TCP
 157 will set the
 158 .Dq push
 159 bit, and begin transmission immediately (if permitted) at the end of
 160 every user call to
 161 .Xr write 2
 162 or
 163 .Xr writev 2 .
 164 When this option is set to a non-zero value,
 165 .Tn TCP
 166 will delay sending any data at all until either the socket is closed,
 167 or the internal send buffer is filled.
 168 .It Dv TCP_KEEPALIVE
 169 .Tn The
 170 .Dv TCP_KEEPALIVE
 171 options enable to specify the amount of time, in seconds, that the
 172 connection must be idle before keepalive probes (if enabled) are sent.
 173 The default value is specified by the
 174 .Tn MIB
 175 variable
 176 .Va net.inet.tcp.keepidle .
 177 .It Dv TCP_CONNECTIONTIMEOUT
 178 .Tn The
 179 .Dv TCP_CONNECTIONTIMEOUT
 180 option allows to specify the timeout, in seconds, for new, non established
 181 .Tn TCP
 182 connections. This option can be useful for both active and passive
 183 .Tn TCP
 184 connections. The default value is specified by the
 185 .Tn MIB
 186 variable
 187 .Va net.inet.tcp.keepinit .
 188 .El
 189 .Pp
 190 The option level for the
 191 .Xr setsockopt 2
 192 call is the protocol number for
 193 .Tn TCP ,
 194 available from
 195 .Xr getprotobyname 3 ,
 196 or
 197 .Dv IPPROTO_TCP .
 198 All options are declared in
 199 .In netinet/tcp.h .
 200 .Pp
 201 Options at the
 202 .Tn IP
 203 transport level may be used with
 204 .Tn TCP ;
 205 see
 206 .Xr ip 4 .
 207 Incoming connection requests that are source-routed are noted,
 208 and the reverse source route is used in responding.
 209 .Ss "Non-blocking connect"
 210 .Pp
 211 When a
 212 .Tn TCP
 213 socket is set non-blocking, and the connection cannot be established immediatly,
 214 .Xr connect 2
 215 returns with the error
 216 .Dv EINPROGRESS ,
 217 and the connection is established asynchronously.
 218 .Pp
 219 When the asynchronous connection completes successfully,
 220 .Xr select 2
 221 or
 222 .Xr poll 2
 223 or
 224 .Xr kqueue 2
 225 will indicate the file descriptor is ready for writing.
 226 If the connection encounters an error, the file descriptor
 227 is marked ready for both reading and writing, and the pending error
 228 can be retrieved via the socket option
 229 .Dv SO_ERROR .
 230 .Pp
 231 Note that even if the socket is non-blocking, it is possible for the connection
 232 to be established immediatly. In that case
 233 .Xr connect 2
 234 does not return with
 235 .Dv EINPROGRESS .
 236 .Sh DIAGNOSTICS
 237 A socket operation may fail with one of the following errors returned:
 238 .Bl -tag -width Er
 239 .It Bq Er EISCONN
 240 when trying to establish a connection on a socket which
 241 already has one;
 242 .It Bq Er ENOBUFS
 243 when the system runs out of memory for
 244 an internal data structure;
 245 .It Bq Er ETIMEDOUT
 246 when a connection was dropped
 247 due to excessive retransmissions;
 248 .It Bq Er ECONNRESET
 249 when the remote peer
 250 forces the connection to be closed;
 251 .It Bq Er ECONNREFUSED
 252 when the remote
 253 peer actively refuses connection establishment (usually because
 254 no process is listening to the port);
 255 .It Bq Er EADDRINUSE
 256 when an attempt
 257 is made to create a socket with a port which has already been
 258 allocated;
 259 .It Bq Er EADDRNOTAVAIL
 260 when an attempt is made to create a
 261 socket with a network address for which no network interface
 262 exists;
 263 .It Bq Er EAFNOSUPPORT
 264 when an attempt is made to bind or connect a socket to a multicast
 265 address;
 266 .It Bq Er EINPROGRESS
 267 returned by
 268 .Xr connect 2
 269 when the socket is set nonblocking, and the connection cannot be
 270 immediately established;
 271 .It Bq Er EALREADY
 272 returned by
 273 .Xr connect 2
 274 when connection request is already in progress for the specified socket.
 275 .
 276 .El
 277 .Sh SEE ALSO
 278 .Xr connect 2 ,
 279 .Xr getsockopt 2 ,
 280 .Xr kqueue 2 ,
 281 .Xr poll 2 ,
 282 .Xr select 2 ,
 283 .Xr socket 2 ,
 284 .Xr sysctl 3 ,
 285 .Xr inet 4 ,
 286 .Xr inet6 4 ,
 287 .Xr ip 4 ,
 288 .Xr ip6 4 ,
 289 .Xr netintro 4 ,
 290 .Xr setkey 8
 291 .Sh HISTORY
 292 The
 293 .Tn TCP
 294 protocol appeared in
 295 .Bx 4.2 .
 296 .Pp
 297 The socket option
 298 .Dv TCP_CONNECTIONTIMEOUT
 299 first appeared in Mac OS X 10.6.