1 '\" te
2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright (c) 2011 Nexenta Systems, Inc. All rights reserved.
4 .\" Copyright 1989 AT&T
5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
8 .TH TCP 7P "Jun 30, 2006"
9 .SH NAME
10 tcp, TCP \- Internet Transmission Control Protocol
11 .SH SYNOPSIS
12 .LP
13 .nf
14 \fB#include <sys/socket.h>\fR
15 .fi
16
17 .LP
18 .nf
19 \fB#include <netinet/in.h>\fR
20 .fi
21
22 .LP
23 .nf
24 \fBs = socket(AF_INET, SOCK_STREAM, 0);\fR
25 .fi
26
27 .LP
28 .nf
29 \fBs = socket(AF_INET6, SOCK_STREAM, 0);\fR
30 .fi
31
32 .LP
33 .nf
34 \fBt = t_open("/dev/tcp", O_RDWR);\fR
35 .fi
36
37 .LP
38 .nf
39 \fBt = t_open("/dev/tcp6", O_RDWR);\fR
40 .fi
41
42 .SH DESCRIPTION
43 .sp
44 .LP
45 \fBTCP\fR is the virtual circuit protocol of the Internet protocol family. It
46 provides reliable, flow-controlled, in order, two-way transmission of data. It
47 is a byte-stream protocol layered above the Internet Protocol (\fBIP\fR), or
48 the Internet Protocol Version 6 (\fBIPv6\fR), the Internet protocol family's
49 internetwork datagram delivery protocol.
50 .sp
51 .LP
52 Programs can access \fBTCP\fR using the socket interface as a \fBSOCK_STREAM\fR
53 socket type, or using the Transport Level Interface (\fBTLI\fR) where it
54 supports the connection-oriented (\fBT_COTS_ORD\fR) service type.
55 .sp
56 .LP
57 \fBTCP\fR uses \fBIP\fR's host-level addressing and adds its own per-host
58 collection of "port addresses." The endpoints of a \fBTCP\fR connection are
59 identified by the combination of an \fBIP\fR or IPv6 address and a \fBTCP\fR
60 port number. Although other protocols, such as the User Datagram Protocol
61 (UDP), may use the same host and port address format, the port space of these
62 protocols is distinct. See \fBinet\fR(7P) and \fBinet6\fR(7P) for details on
63 the common aspects of addressing in the Internet protocol family.
64 .sp
65 .LP
66 Sockets utilizing \fBTCP\fR are either "active" or "passive." Active sockets
67 initiate connections to passive sockets. Both types of sockets must have their
68 local \fBIP\fR or IPv6 address and \fBTCP\fR port number bound with the
69 \fBbind\fR(3SOCKET) system call after the socket is created. By default,
70 \fBTCP\fR sockets are active. A passive socket is created by calling the
71 \fBlisten\fR(3SOCKET) system call after binding the socket with \fBbind()\fR.
72 This establishes a queueing parameter for the passive socket. After this,
73 connections to the passive socket can be received with the
74 \fBaccept\fR(3SOCKET) system call. Active sockets use the
75 \fBconnect\fR(3SOCKET) call after binding to initiate connections.
76 .sp
77 .LP
78 By using the special value \fBINADDR_ANY\fR with \fBIP\fR, or the unspecified
79 address (all zeroes) with IPv6, the local \fBIP\fR address can be left
80 unspecified in the \fBbind()\fR call by either active or passive \fBTCP\fR
81 sockets. This feature is usually used if the local address is either unknown or
82 irrelevant. If left unspecified, the local \fBIP\fR or IPv6 address will be
83 bound at connection time to the address of the network interface used to
84 service the connection.
85 .sp
86 .LP
87 Note that no two TCP sockets can be bound to the same port unless the bound IP
88 addresses are different. IPv4 \fBINADDR_ANY\fR and IPv6 unspecified addresses
89 compare as equal to any IPv4 or IPv6 address. For example, if a socket is bound
90 to \fBINADDR_ANY\fR or unspecified address and port X, no other socket can bind
91 to port X, regardless of the binding address. This special consideration of
92 \fBINADDR_ANY\fR and unspecified address can be changed using the socket option
93 \fBSO_REUSEADDR\fR. If \fBSO_REUSEADDR\fR is set on a socket doing a bind, IPv4
94 \fBINADDR_ANY\fR and IPv6 unspecified address do not compare as equal to any IP
95 address. This means that as long as the two sockets are not both bound to
96 \fBINADDR_ANY\fR/unspecified address or the same IP address, the two sockets
97 can be bound to the same port.
98 .sp
99 .LP
100 If an application does not want to allow another socket using the
101 \fBSO_REUSEADDR\fR option to bind to a port its socket is bound to, the
102 application can set the socket level option \fBSO_EXCLBIND\fR on a socket. The
103 option values of 0 and 1 mean enabling and disabling the option respectively.
104 Once this option is enabled on a socket, no other socket can be bound to the
105 same port.
106 .sp
107 .LP
108 Once a connection has been established, data can be exchanged using the
109 \fBread\fR(2) and \fBwrite\fR(2) system calls.
110 .sp
111 .LP
112 Under most circumstances, \fBTCP\fR sends data when it is presented. When
113 outstanding data has not yet been acknowledged, \fBTCP\fR gathers small amounts
114 of output to be sent in a single packet once an acknowledgement has been
115 received. For a small number of clients, such as window systems that send a
116 stream of mouse events which receive no replies, this packetization may cause
117 significant delays. To circumvent this problem, \fBTCP\fR provides a
118 socket-level boolean option, \fBTCP_NODELAY.\fR \fBTCP_NODELAY\fR is defined in
119 \fB<netinet/tcp.h>\fR, and is set with \fBsetsockopt\fR(3SOCKET) and tested
120 with \fBgetsockopt\fR(3SOCKET). The option level for the \fBsetsockopt()\fR
121 call is the protocol number for \fBTCP,\fR available from
122 \fBgetprotobyname\fR(3SOCKET).
123 .sp
124 .LP
125 For some applications, it may be desirable for TCP not to send out data unless
126 a full TCP segment can be sent. To enable this behavior, an application can use
127 the \fBTCP_CORK\fR socket option. When \fBTCP_CORK\fR is set with a non-zero
128 value, TCP sends out a full TCP segment only. When \fBTCP_CORK\fR is set to
129 zero after it has been enabled, all buffered data is sent out (as permitted by
130 the peer's receive window and the current congestion window). \fBTCP_CORK\fR is
131 defined in <\fBnetinet/tcp.h\fR>, and is set with \fBsetsockopt\fR(3SOCKET)
132 and tested with \fBgetsockopt\fR(3SOCKET). The option level for the
133 \fBsetsockopt()\fR call is the protocol number for TCP, available from
134 \fBgetprotobyname\fR(3SOCKET).
135 .sp
136 .LP
137 The SO_RCVBUF socket level option can be used to control the window that TCP
138 advertises to the peer. IP level options may also be used with TCP. See
139 \fBip\fR(7P) and \fBip6\fR(7P).
140 .sp
141 .LP
142 Another socket level option, \fBSO_RCVBUF,\fR can be used to control the window
143 that \fBTCP\fR advertises to the peer. \fBIP\fR level options may also be used
144 with \fBTCP.\fR See \fBip\fR(7P) and \fBip6\fR(7P).
145 .sp
146 .LP
147 \fBTCP\fR provides an urgent data mechanism, which may be invoked using the
148 out-of-band provisions of \fBsend\fR(3SOCKET). The caller may mark one byte as
149 "urgent" with the \fBMSG_OOB\fR flag to \fBsend\fR(3SOCKET). This sets an
150 "urgent pointer" pointing to this byte in the \fBTCP\fR stream. The receiver on
151 the other side of the stream is notified of the urgent data by a \fBSIGURG\fR
152 signal. The \fBSIOCATMARK\fR \fBioctl\fR(2) request returns a value indicating
153 whether the stream is at the urgent mark. Because the system never returns data
154 across the urgent mark in a single \fBread\fR(2) call, it is possible to
155 advance to the urgent data in a simple loop which reads data, testing the
156 socket with the \fBSIOCATMARK\fR \fBioctl()\fR request, until it reaches the
157 mark.
158 .sp
159 .LP
160 Incoming connection requests that include an \fBIP\fR source route option are
161 noted, and the reverse source route is used in responding.
162 .sp
163 .LP
164 A checksum over all data helps \fBTCP\fR implement reliability. Using a
165 window-based flow control mechanism that makes use of positive
166 acknowledgements, sequence numbers, and a retransmission strategy, \fBTCP\fR
167 can usually recover when datagrams are damaged, delayed, duplicated or
168 delivered out of order by the underlying communication medium.
169 .sp
170 .LP
171 If the local \fBTCP\fR receives no acknowledgements from its peer for a period
172 of time, (for example, if the remote machine crashes), the connection is closed
173 and an error is returned.
174 .sp
175 .LP
176 TCP follows the congestion control algorithm described in \fIRFC 2581\fR, and
177 also supports the initial congestion window (cwnd) changes in \fIRFC 3390\fR.
178 The initial cwnd calculation can be overridden by the socket option
179 TCP_INIT_CWND. An application can use this option to set the initial cwnd to a
180 specified number of TCP segments. This applies to the cases when the connection
181 first starts and restarts after an idle period. The process must have the
182 PRIV_SYS_NET_CONFIG privilege if it wants to specify a number greater than that
183 calculated by \fIRFC 3390\fR.
184 .sp
185 .LP
186 SunOS supports \fBTCP\fR Extensions for High Performance (\fIRFC 1323\fR) which
187 includes the window scale and timestamp options, and Protection Against Wrap
188 Around Sequence Numbers (PAWS). SunOS also supports Selective Acknowledgment
189 (SACK) capabilities (RFC 2018) and Explicit Congestion Notification (ECN)
190 mechanism (\fIRFC 3168\fR).
191 .sp
192 .LP
193 Turn on the window scale option in one of the following ways:
194 .RS +4
195 .TP
196 .ie t \(bu
197 .el o
198 An application can set \fBSO_SNDBUF\fR or \fBSO_RCVBUF\fR size in the
199 \fBsetsockopt()\fR option to be larger than 64K. This must be done \fIbefore\fR
200 the program calls \fBlisten()\fR or \fBconnect()\fR, because the window scale
201 option is negotiated when the connection is established. Once the connection
202 has been made, it is too late to increase the send or receive window beyond the
203 default \fBTCP\fR limit of 64K.
204 .RE
205 .RS +4
206 .TP
207 .ie t \(bu
208 .el o
209 For all applications, use \fBndd\fR(1M) to modify the configuration parameter
210 \fBtcp_wscale_always\fR. If \fBtcp_wscale_always\fR is set to \fB1\fR, the
211 window scale option will always be set when connecting to a remote system. If
212 \fBtcp_wscale_always\fR is \fB0,\fR the window scale option will be set only if
213 the user has requested a send or receive window larger than 64K. The default
214 value of \fBtcp_wscale_always\fR is \fB1\fR.
215 .RE
216 .RS +4
217 .TP
218 .ie t \(bu
219 .el o
220 Regardless of the value of \fBtcp_wscale_always\fR, the window scale option
221 will always be included in a connect acknowledgement if the connecting system
222 has used the option.
223 .RE
224 .sp
225 .LP
226 Turn on \fBSACK\fR capabilities in the following way:
227 .RS +4
228 .TP
229 .ie t \(bu
230 .el o
231 Use \fBndd\fR to modify the configuration parameter \fBtcp_sack_permitted\fR.
232 If \fBtcp_sack_permitted\fR is set to \fB0\fR, \fBTCP\fR will not accept
233 \fBSACK\fR or send out \fBSACK\fR information. If \fBtcp_sack_permitted\fR is
234 set to \fB1\fR, \fBTCP\fR will not initiate a connection with \fBSACK\fR
235 permitted option in the \fBSYN\fR segment, but will respond with \fBSACK\fR
236 permitted option in the \fBSYN|ACK\fR segment if an incoming connection request
237 has the \fBSACK \fR permitted option. This means that \fBTCP\fR will only
238 accept \fBSACK\fR information if the other side of the connection also accepts
239 \fBSACK\fR information. If \fBtcp_sack_permitted\fR is set to \fB2\fR, it will
240 both initiate and accept connections with \fBSACK\fR information. The default
241 for \fBtcp_sack_permitted\fR is \fB2\fR (active enabled).
242 .RE
243 .sp
244 .LP
245 Turn on \fBTCP ECN\fR mechanism in the following way:
246 .RS +4
247 .TP
248 .ie t \(bu
249 .el o
250 Use \fBndd\fR to modify the configuration parameter \fBtcp_ecn_permitted\fR. If
251 \fBtcp_ecn_permitted\fR is set to \fB0\fR, \fBTCP\fR will not negotiate with a
252 peer that supports \fBECN\fR mechanism. If \fBtcp_ecn_permitted\fR is set to
253 \fB1\fR when initiating a connection, TCP will not tell a peer that it supports
254 ECN mechanism. However, it will tell a peer that it supports \fBECN\fR
255 mechanism when accepting a new incoming connection request if the peer
256 indicates that it supports \fBECN\fR mechanism in the SYN segment. If
257 tcp_ecn_permitted is set to 2, in addition to negotiating with a peer on ECN
258 mechanism when accepting connections, TCP will indicate in the outgoing SYN
259 segment that it supports \fBECN\fR mechanism when \fBTCP\fR makes active
260 outgoing connections. The default for \fBtcp_ecn_permitted\fR is 1.
261 .RE
262 .sp
263 .LP
264 Turn on the timestamp option in the following way:
265 .RS +4
266 .TP
267 .ie t \(bu
268 .el o
269 Use \fBndd\fR to modify the configuration parameter \fBtcp_tstamp_always\fR. If
270 \fBtcp_tstamp_always\fR is \fB1\fR, the timestamp option will always be set
271 when connecting to a remote machine. If \fBtcp_tstamp_always\fR is \fB0\fR, the
272 timestamp option will not be set when connecting to a remote system. The
273 default for \fBtcp_tstamp_always\fR is \fB0\fR.
274 .RE
275 .RS +4
276 .TP
277 .ie t \(bu
278 .el o
279 Regardless of the value of \fBtcp_tstamp_always\fR, the timestamp option will
280 always be included in a connect acknowledgement (and all succeeding packets) if
281 the connecting system has used the timestamp option.
282 .RE
283 .sp
284 .LP
285 Use the following procedure to turn on the timestamp option only when the
286 window scale option is in effect:
287 .RS +4
288 .TP
289 .ie t \(bu
290 .el o
291 Use \fBndd\fR to modify the configuration parameter \fBtcp_tstamp_if_wscale\fR.
292 Setting \fBtcp_tstamp_if_wscale\fR to \fB1\fR will cause the timestamp option
293 to be set when connecting to a remote system, if the window scale option has
294 been set. If \fBtcp_tstamp_if_wscale\fR is \fB0\fR, the timestamp option will
295 not be set when connecting to a remote system. The default for
296 \fBtcp_tstamp_if_wscale\fR is \fB1\fR.
297 .RE
298 .sp
299 .LP
300 Protection Against Wrap Around Sequence Numbers (PAWS) is always used when the
301 timestamp option is set.
302 .sp
303 .LP
304 SunOS also supports multiple methods of generating initial sequence numbers.
305 One of these methods is the improved technique suggested in \fBRFC\fR 1948. We
306 \fBHIGHLY\fR recommend that you set sequence number generation parameters as
307 close to boot time as possible. This prevents sequence number problems on
308 connections that use the same connection-ID as ones that used a different
309 sequence number generation. The \fBsvc:/network/initial:default\fR service
310 configures the initial sequence number generation. The service reads the value
311 contained in the configuration file \fB/etc/default/inetinit\fR to determine
312 which method to use.
313 .sp
314 .LP
315 The \fB/etc/default/inetinit\fR file is an unstable interface, and may change
316 in future releases.
317 .sp
318 .LP
319 \fBTCP\fR may be configured to report some information on connections that
320 terminate by means of an \fBRST\fR packet. By default, no logging is done. If
321 the \fBndd\fR(1M) parameter \fItcp_trace\fR is set to 1, then trace data is
322 collected for all new connections established after that time.
323 .sp
324 .LP
325 The trace data consists of the \fBTCP\fR headers and \fBIP\fR source and
326 destination addresses of the last few packets sent in each direction before RST
327 occurred. Those packets are logged in a series of \fBstrlog\fR(9F) calls. This
328 trace facility has a very low overhead, and so is superior to such utilities as
329 \fBsnoop\fR(1M) for non-intrusive debugging for connections terminating by
330 means of an \fBRST\fR.
331 .sp
332 .LP
333 SunOS supports the keep-alive mechanism described in \fIRFC 1122\fR. It is
334 enabled using the socket option SO_KEEPALIVE. When enabled, the first
335 keep-alive probe is sent out after a TCP is idle for two hours If the peer does
336 not respond to the probe within eight minutes, the TCP connection is aborted.
337 You can alter the interval for sending out the first probe using the socket
338 option TCP_KEEPALIVE_THRESHOLD. The option value is an unsigned integer in
339 milliseconds. The system default is controlled by the TCP ndd parameter
340 tcp_keepalive_interval. The minimum value is ten seconds. The maximum is ten
341 days, while the default is two hours. If you receive no response to the probe,
342 you can use the TCP_KEEPALIVE_ABORT_THRESHOLD socket option to change the time
343 threshold for aborting a TCP connection. The option value is an unsigned
344 integer in milliseconds. The value zero indicates that TCP should never time
345 out and abort the connection when probing. The system default is controlled by
346 the TCP ndd parameter tcp_keepalive_abort_interval. The default is eight
347 minutes.
348 .sp
349 .LP
350 socket options TCP_KEEPIDLE, TCP_KEEPCNT and TCP_KEEPINTVL are also supported
351 for compatibility with other Unix Flavors. TCP_KEEPIDLE option specifies the
352 interval in seconds for sending out the first keep-alive probe. TCP_KEEPCNT
353 specifies the number of keep-alive probes to be sent before aborting the
354 connection in the event of no response from peer. TCP_KEEPINTVL specifies the
355 interval in seconds between successive keep-alive probes.
356 .SH SEE ALSO
357 .sp
358 .LP
359 \fBsvcs\fR(1), \fBndd\fR(1M), \fBioctl\fR(2), \fBread\fR(2), \fBsvcadm\fR(1M),
360 \fBwrite\fR(2), \fBaccept\fR(3SOCKET), \fBbind\fR(3SOCKET),
361 \fBconnect\fR(3SOCKET), \fBgetprotobyname\fR(3SOCKET),
362 \fBgetsockopt\fR(3SOCKET), \fBlisten\fR(3SOCKET), \fBsend\fR(3SOCKET),
363 \fBsmf\fR(5), \fBinet\fR(7P), \fBinet6\fR(7P), \fBip\fR(7P), \fBip6\fR(7P)
364 .sp
365 .LP
366 Ramakrishnan, K., Floyd, S., Black, D., RFC 3168, \fIThe Addition of Explicit
367 Congestion Notification (ECN) to IP\fR, September 2001.
368 .sp
369 .LP
370 Mathias, M. and Hahdavi, J. Pittsburgh Supercomputing Center; Ford, S. Lawrence
371 Berkeley National Laboratory; Romanow, A. Sun Microsystems, Inc. \fIRFC 2018,
372 TCP Selective Acknowledgement Options\fR, October 1996.
373 .sp
374 .LP
375 Bellovin, S., \fIRFC 1948, Defending Against Sequence Number Attacks\fR, May
376 1996.
377 .sp
378 .LP
379 Jacobson, V., Braden, R., and Borman, D., \fIRFC 1323, TCP Extensions for High
380 Performance\fR, May 1992.
381 .sp
382 .LP
383 Postel, Jon, \fIRFC 793, Transmission Control Protocol - DARPA Internet Program
384 Protocol Specification\fR, Network Information Center, SRI International, Menlo
385 Park, CA., September 1981.
386 .SH DIAGNOSTICS
387 .sp
388 .LP
389 A socket operation may fail if:
390 .sp
391 .ne 2
392 .na
393 \fB\fBEISCONN\fR\fR
394 .ad
395 .RS 17n
396 A \fBconnect()\fR operation was attempted on a socket on which a
397 \fBconnect()\fR operation had already been performed.
398 .RE
399
400 .sp
401 .ne 2
402 .na
403 \fB\fBETIMEDOUT\fR\fR
404 .ad
405 .RS 17n
406 A connection was dropped due to excessive retransmissions.
407 .RE
408
409 .sp
410 .ne 2
411 .na
412 \fB\fBECONNRESET\fR\fR
413 .ad
414 .RS 17n
415 The remote peer forced the connection to be closed (usually because the remote
416 machine has lost state information about the connection due to a crash).
417 .RE
418
419 .sp
420 .ne 2
421 .na
422 \fB\fBECONNREFUSED\fR\fR
423 .ad
424 .RS 17n
425 The remote peer actively refused connection establishment (usually because no
426 process is listening to the port).
427 .RE
428
429 .sp
430 .ne 2
431 .na
432 \fB\fBEADDRINUSE\fR\fR
433 .ad
434 .RS 17n
435 A \fBbind()\fR operation was attempted on a socket with a network address/port
436 pair that has already been bound to another socket.
437 .RE
438
439 .sp
440 .ne 2
441 .na
442 \fB\fBEADDRNOTAVAIL\fR\fR
443 .ad
444 .RS 17n
445 A \fBbind()\fR operation was attempted on a socket with a network address for
446 which no network interface exists.
447 .RE
448
449 .sp
450 .ne 2
451 .na
452 \fB\fBEACCES\fR\fR
453 .ad
454 .RS 17n
455 A \fBbind()\fR operation was attempted with a "reserved" port number and the
456 effective user \fBID\fR of the process was not the privileged user.
457 .RE
458
459 .sp
460 .ne 2
461 .na
462 \fB\fBENOBUFS\fR\fR
463 .ad
464 .RS 17n
465 The system ran out of memory for internal data structures.
466 .RE
467
468 .SH NOTES
469 .sp
470 .LP
471 The \fBtcp\fR service is managed by the service management facility,
472 \fBsmf\fR(5), under the service identifier:
473 .sp
474 .in +2
475 .nf
476 svc:/network/initial:default
477 .fi
478 .in -2
479 .sp
480
481 .sp
482 .LP
483 Administrative actions on this service, such as enabling, disabling, or
484 requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
485 status can be queried using the \fBsvcs\fR(1) command.