[apple/xnu.git] / bsd / man / man4 / tcp.4

.\"	$NetBSD: tcp.4,v 1.3 1994/11/30 16:22:35 jtc Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS 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.
.\"
.\"     @(#)tcp.4	8.1 (Berkeley) 6/5/93
.\"
.Dd February 28, 2007
.Dt TCP 4
.Os BSD 4.2
.Sh NAME
.Nm tcp
.Nd Internet Transmission Control Protocol
.Sh SYNOPSIS
.In sys/types.h
.In sys/socket.h
.In netinet/in.h
.Ft int
.Fn socket AF_INET SOCK_STREAM 0
.Sh DESCRIPTION
The
.Tn TCP
protocol provides reliable, flow-controlled, two-way
transmission of data.
It is a byte-stream protocol used to
support the
.Dv SOCK_STREAM
abstraction.
.Tn TCP
uses the standard
Internet address format and, in addition, provides a per-host
collection of
.Dq "port addresses" .
Thus, each address is composed
of an Internet address specifying the host and network,
with a specific
.Tn TCP
port on the host identifying the peer entity.
.Pp
Sockets utilizing the
.Tn TCP
protocol are either
.Dq active
or
.Dq passive .
Active sockets initiate connections to passive
sockets.
By default,
.Tn TCP
sockets are created active; to create a
passive socket, the
.Xr listen 2
system call must be used
after binding the socket with the
.Xr bind 2
system call.
Only passive sockets may use the
.Xr accept 2
call to accept incoming connections.
Only active sockets may use the
.Xr connect 2
call to initiate connections.
.Pp
Passive sockets may
.Dq underspecify
their location to match
incoming connection requests from multiple networks.
This technique, termed
.Dq "wildcard addressing" ,
allows a single
server to provide service to clients on multiple networks.
To create a socket which listens on all networks, the Internet
address
.Dv INADDR_ANY
must be bound.
The
.Tn TCP
port may still be specified
at this time; if the port is not specified, the system will assign one.
Once a connection has been established, the socket's address is
fixed by the peer entity's location.
The address assigned to the
socket is the address associated with the network interface
through which packets are being transmitted and received.
Normally, this address corresponds to the peer entity's network.
.Pp
.Tn TCP
supports a number of socket options which can be set with
.Xr setsockopt 2
and tested with
.Xr getsockopt 2 :
.Bl -tag -width ".Dv TCP_CONNECTIONTIMEOUT"
.It Dv TCP_NODELAY
Under most circumstances,
.Tn TCP
sends data when it is presented;
when outstanding data has not yet been acknowledged, it gathers
small amounts of output to be sent in a single packet once
an acknowledgement is received.
For a small number of clients, such as window systems
that send a stream of mouse events which receive no replies,
this packetization may cause significant delays.
The boolean option
.Dv TCP_NODELAY
defeats this algorithm.
.It Dv TCP_MAXSEG
By default, a sender- and
.No receiver- Ns Tn TCP
will negotiate among themselves to determine the maximum segment size
to be used for each connection.
The
.Dv TCP_MAXSEG
option allows the user to determine the result of this negotiation,
and to reduce it if desired.
.It Dv TCP_NOOPT
.Tn TCP
usually sends a number of options in each packet, corresponding to
various
.Tn TCP
extensions which are provided in this implementation.
The boolean option
.Dv TCP_NOOPT
is provided to disable
.Tn TCP
option use on a per-connection basis.
.It Dv TCP_NOPUSH
By convention, the
.No sender- Ns Tn TCP
will set the
.Dq push
bit, and begin transmission immediately (if permitted) at the end of
every user call to
.Xr write 2
or
.Xr writev 2 .
When this option is set to a non-zero value,
.Tn TCP
will delay sending any data at all until either the socket is closed,
or the internal send buffer is filled.
.It Dv TCP_KEEPALIVE
.Tn The
.Dv TCP_KEEPALIVE
options enable to specify the amount of time, in seconds, that the 
connection must be idle before keepalive probes (if enabled) are sent. 
The default value is specified by the 
.Tn MIB
variable
.Va net.inet.tcp.keepidle .  
.It Dv TCP_CONNECTIONTIMEOUT
.Tn The
.Dv TCP_CONNECTIONTIMEOUT
option allows to specify the timeout, in seconds, for new, non established
.Tn TCP
connections. This option can be useful for both active and passive
.Tn TCP
connections. The default value is specified by the 
.Tn MIB
variable
.Va net.inet.tcp.keepinit .
.El
.Pp
The option level for the
.Xr setsockopt 2
call is the protocol number for
.Tn TCP ,
available from
.Xr getprotobyname 3 ,
or
.Dv IPPROTO_TCP .
All options are declared in
.In netinet/tcp.h .
.Pp
Options at the
.Tn IP
transport level may be used with
.Tn TCP ;
see
.Xr ip 4 .
Incoming connection requests that are source-routed are noted,
and the reverse source route is used in responding.
.Ss "Non-blocking connect"
.Pp
When a
.Tn TCP
socket is set non-blocking, and the connection cannot be established immediatly, 
.Xr connect 2
returns with the error
.Dv EINPROGRESS ,
and the connection is established asynchronously.
.Pp
When the asynchronous connection completes successfully,
.Xr select 2
or
.Xr poll 2
or
.Xr kqueue 2
will indicate the file descriptor is ready for writing. 
If the connection encounters an error, the file descriptor 
is marked ready for both reading and writing, and the pending error 
can be retrieved via the socket option 
.Dv SO_ERROR .
.Pp
Note that even if the socket is non-blocking, it is possible for the connection 
to be established immediatly. In that case 
.Xr connect 2
does not return with 
.Dv EINPROGRESS .
.Sh DIAGNOSTICS
A socket operation may fail with one of the following errors returned:
.Bl -tag -width Er
.It Bq Er EISCONN
when trying to establish a connection on a socket which
already has one;
.It Bq Er ENOBUFS
when the system runs out of memory for
an internal data structure;
.It Bq Er ETIMEDOUT
when a connection was dropped
due to excessive retransmissions;
.It Bq Er ECONNRESET
when the remote peer
forces the connection to be closed;
.It Bq Er ECONNREFUSED
when the remote
peer actively refuses connection establishment (usually because
no process is listening to the port);
.It Bq Er EADDRINUSE
when an attempt
is made to create a socket with a port which has already been
allocated;
.It Bq Er EADDRNOTAVAIL
when an attempt is made to create a
socket with a network address for which no network interface
exists;
.It Bq Er EAFNOSUPPORT
when an attempt is made to bind or connect a socket to a multicast
address;
.It Bq Er EINPROGRESS
returned by
.Xr connect 2
when the socket is set nonblocking, and the connection cannot be 
immediately established;
.It Bq Er EALREADY
returned by
.Xr connect 2
when connection request is already in progress for the specified socket.
.
.El
.Sh SEE ALSO
.Xr connect 2 ,
.Xr getsockopt 2 ,
.Xr kqueue 2 ,
.Xr poll 2 ,
.Xr select 2 ,
.Xr socket 2 ,
.Xr sysctl 3 ,
.Xr inet 4 ,
.Xr inet6 4 ,
.Xr ip 4 ,
.Xr ip6 4 ,
.Xr netintro 4 ,
.Xr setkey 8
.Sh HISTORY
The
.Tn TCP
protocol appeared in
.Bx 4.2 .
.Pp
The socket option
.Dv TCP_CONNECTIONTIMEOUT
first appeared in Mac OS X 10.6.
Commit	Line	Data
9bccf70c A	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	.\"
b0d623f7	36	.Dd February 28, 2007
9bccf70c A	37	.Dt TCP 4
	38	.Os BSD 4.2
	39	.Sh NAME
	40	.Nm tcp
	41	.Nd Internet Transmission Control Protocol
	42	.Sh SYNOPSIS
b0d623f7 A	43	.In sys/types.h
	44	.In sys/socket.h
	45	.In netinet/in.h
9bccf70c A	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
b0d623f7 A	52	transmission of data.
b0d623f7 A	53	It is a byte-stream protocol used to
9bccf70c A	54	support the
9bccf70c A	55	.Dv SOCK_STREAM
b0d623f7 A	56	abstraction.
	57	.Tn TCP
	58	uses the standard
9bccf70c A	59	Internet address format and, in addition, provides a per-host
9bccf70c A	60	collection of
b0d623f7	61	.Dq "port addresses" .
9bccf70c	62	Thus, each address is composed
b0d623f7 A	63	of an Internet address specifying the host and network,
b0d623f7 A	64	with a specific
9bccf70c A	65	.Tn TCP
	66	port on the host identifying the peer entity.
	67	.Pp
b0d623f7 A	68	Sockets utilizing the
	69	.Tn TCP
	70	protocol are either
9bccf70c A	71	.Dq active
	72	or
	73	.Dq passive .
	74	Active sockets initiate connections to passive
b0d623f7 A	75	sockets.
b0d623f7 A	76	By default,
9bccf70c A	77	.Tn TCP
9bccf70c A	78	sockets are created active; to create a
b0d623f7	79	passive socket, the
9bccf70c A	80	.Xr listen 2
	81	system call must be used
	82	after binding the socket with the
	83	.Xr bind 2
b0d623f7 A	84	system call.
b0d623f7 A	85	Only passive sockets may use the
9bccf70c	86	.Xr accept 2
b0d623f7 A	87	call to accept incoming connections.
b0d623f7 A	88	Only active sockets may use the
9bccf70c A	89	.Xr connect 2
	90	call to initiate connections.
	91	.Pp
	92	Passive sockets may
	93	.Dq underspecify
	94	their location to match
b0d623f7 A	95	incoming connection requests from multiple networks.
	96	This technique, termed
	97	.Dq "wildcard addressing" ,
9bccf70c A	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
b0d623f7 A	103	must be bound.
b0d623f7 A	104	The
9bccf70c A	105	.Tn TCP
9bccf70c A	106	port may still be specified
b0d623f7 A	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
9bccf70c	111	socket is the address associated with the network interface
b0d623f7 A	112	through which packets are being transmitted and received.
b0d623f7 A	113	Normally, this address corresponds to the peer entity's network.
9bccf70c A	114	.Pp
9bccf70c A	115	.Tn TCP
b0d623f7	116	supports a number of socket options which can be set with
9bccf70c A	117	.Xr setsockopt 2
9bccf70c A	118	and tested with
b0d623f7 A	119	.Xr getsockopt 2 :
	120	.Bl -tag -width ".Dv TCP_CONNECTIONTIMEOUT"
	121	.It Dv TCP_NODELAY
9bccf70c A	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.
b0d623f7	131	The boolean option
9bccf70c	132	.Dv TCP_NODELAY
b0d623f7 A	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
9bccf70c	190	The option level for the
b0d623f7	191	.Xr setsockopt 2
9bccf70c A	192	call is the protocol number for
	193	.Tn TCP ,
	194	available from
b0d623f7 A	195	.Xr getprotobyname 3 ,
	196	or
	197	.Dv IPPROTO_TCP .
	198	All options are declared in
	199	.In netinet/tcp.h .
9bccf70c A	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.
b0d623f7 A	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 .
9bccf70c A	236	.Sh DIAGNOSTICS
9bccf70c A	237	A socket operation may fail with one of the following errors returned:
b0d623f7	238	.Bl -tag -width Er
9bccf70c A	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
b0d623f7	260	when an attempt is made to create a
9bccf70c	261	socket with a network address for which no network interface
b0d623f7 A	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	.
9bccf70c A	276	.El
9bccf70c A	277	.Sh SEE ALSO
b0d623f7	278	.Xr connect 2 ,
9bccf70c	279	.Xr getsockopt 2 ,
b0d623f7 A	280	.Xr kqueue 2 ,
	281	.Xr poll 2 ,
	282	.Xr select 2 ,
9bccf70c	283	.Xr socket 2 ,
b0d623f7	284	.Xr sysctl 3 ,
9bccf70c	285	.Xr inet 4 ,
b0d623f7 A	286	.Xr inet6 4 ,
	287	.Xr ip 4 ,
	288	.Xr ip6 4 ,
	289	.Xr netintro 4 ,
	290	.Xr setkey 8
9bccf70c A	291	.Sh HISTORY
9bccf70c A	292	The
b0d623f7 A	293	.Tn TCP
b0d623f7 A	294	protocol appeared in
9bccf70c	295	.Bx 4.2 .
b0d623f7 A	296	.Pp
	297	The socket option
	298	.Dv TCP_CONNECTIONTIMEOUT
	299	first appeared in Mac OS X 10.6.