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 April 16, 2014
  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 .It Dv TCP_KEEPINTVL
 189 When keepalive probes are enabled, this option will set the amount of time in seconds between successive keepalives sent to probe an unresponsive peer.
 190 .It Dv TCP_KEEPCNT
 191 .Tn When keepalive probes are enabled, this option will set the number of times a keepalive probe should be repeated if the peer is not responding. After this many probes, the connection will be closed.
 192 .It Dv TCP_SENDMOREACKS
 193 When a stream of
 194 .Tn TCP
 195 data packets are received, OS X uses an algorithm to reduce the number of acknowlegements by generating a
 196 .Tn TCP
 197 acknowlegement for 8 data packets instead of acknowledging every other data packet. When this socket option is enabled, the connection will always send a
 198 .Tn TCP
 199 acknowledgement for every other data packet.
 200 .It Dv TCP_ENABLE_ECN
 201 Using Explicit Congestion Notification (ECN) on
 202 .Tn TCP
 203 allows end-to-end notification of congestion without dropping packets. Conventionally TCP/IP networks signal congestion by dropping packets. When ECN is successfully negotiated, an ECN-aware router may set a mark in the IP header instead of dropping a packet in order to signal impending congestion. The
 204 .Tn TCP
 205 receiver of the packet echoes congestion indication to the
 206 .Tn TCP
 207 sender, which reduces it's transmission rate as if it detected a dropped packet. This will avoid unnecessary retransmissions and will improve latency by saving the time required for recovering a lost packet.
 208 .It Dv TCP_NOTSENT_LOWAT
 209 The send socket buffer of a
 210 .Tn TCP sender has unsent and unacknowledged data. This option allows a
 211 .Tn TCP sender to control the amount of unsent data kept in the send socket buffer. The value of the option should be the maximum amount of unsent data in bytes. Kevent, poll and select will generate a write notification when the unsent data falls below the amount given by this option. This will allow an application to generate just-in-time fresh updates for real-time communication.
 212 .El
 213 .Pp
 214 The option level for the
 215 .Xr setsockopt 2
 216 call is the protocol number for
 217 .Tn TCP ,
 218 available from
 219 .Xr getprotobyname 3 ,
 220 or
 221 .Dv IPPROTO_TCP .
 222 All options are declared in
 223 .In netinet/tcp.h .
 224 .Pp
 225 Options at the
 226 .Tn IP
 227 transport level may be used with
 228 .Tn TCP ;
 229 see
 230 .Xr ip 4 .
 231 Incoming connection requests that are source-routed are noted,
 232 and the reverse source route is used in responding.
 233 .Ss "Non-blocking connect"
 234 .Pp
 235 When a
 236 .Tn TCP
 237 socket is set non-blocking, and the connection cannot be established immediately,
 238 .Xr connect 2
 239 returns with the error
 240 .Dv EINPROGRESS ,
 241 and the connection is established asynchronously.
 242 .Pp
 243 When the asynchronous connection completes successfully,
 244 .Xr select 2
 245 or
 246 .Xr poll 2
 247 or
 248 .Xr kqueue 2
 249 will indicate the file descriptor is ready for writing.
 250 If the connection encounters an error, the file descriptor
 251 is marked ready for both reading and writing, and the pending error
 252 can be retrieved via the socket option
 253 .Dv SO_ERROR .
 254 .Pp
 255 Note that even if the socket is non-blocking, it is possible for the connection
 256 to be established immediately. In that case
 257 .Xr connect 2
 258 does not return with
 259 .Dv EINPROGRESS .
 260 .Sh DIAGNOSTICS
 261 A socket operation may fail with one of the following errors returned:
 262 .Bl -tag -width Er
 263 .It Bq Er EISCONN
 264 when trying to establish a connection on a socket which
 265 already has one;
 266 .It Bq Er ENOBUFS
 267 when the system runs out of memory for
 268 an internal data structure;
 269 .It Bq Er ETIMEDOUT
 270 when a connection was dropped
 271 due to excessive retransmissions;
 272 .It Bq Er ECONNRESET
 273 when the remote peer
 274 forces the connection to be closed;
 275 .It Bq Er ECONNREFUSED
 276 when the remote
 277 peer actively refuses connection establishment (usually because
 278 no process is listening to the port);
 279 .It Bq Er EADDRINUSE
 280 when an attempt
 281 is made to create a socket with a port which has already been
 282 allocated;
 283 .It Bq Er EADDRNOTAVAIL
 284 when an attempt is made to create a
 285 socket with a network address for which no network interface
 286 exists;
 287 .It Bq Er EAFNOSUPPORT
 288 when an attempt is made to bind or connect a socket to a multicast
 289 address;
 290 .It Bq Er EINPROGRESS
 291 returned by
 292 .Xr connect 2
 293 when the socket is set nonblocking, and the connection cannot be
 294 immediately established;
 295 .It Bq Er EALREADY
 296 returned by
 297 .Xr connect 2
 298 when connection request is already in progress for the specified socket.
 299 .
 300 .El
 301 .Sh SEE ALSO
 302 .Xr connect 2 ,
 303 .Xr getsockopt 2 ,
 304 .Xr kqueue 2 ,
 305 .Xr poll 2 ,
 306 .Xr select 2 ,
 307 .Xr socket 2 ,
 308 .Xr sysctl 3 ,
 309 .Xr inet 4 ,
 310 .Xr inet6 4 ,
 311 .Xr ip 4 ,
 312 .Xr ip6 4 ,
 313 .Xr netintro 4 ,
 314 .Xr setkey 8
 315 .Sh HISTORY
 316 The
 317 .Tn TCP
 318 protocol appeared in
 319 .Bx 4.2 .
 320 .Pp
 321 The socket option
 322 .Dv TCP_CONNECTIONTIMEOUT
 323 first appeared in Mac OS X 10.6.