[apple/xnu.git] / bsd / man / man2 / socket.2

.\"	$NetBSD: socket.2,v 1.5 1995/02/27 12:37:53 cgd 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.
.\"
.\"     @(#)socket.2	8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt SOCKET 2
.Os BSD 4.2
.Sh NAME
.Nm socket
.Nd create an endpoint for communication
.Sh SYNOPSIS
.Fd #include <sys/socket.h>
.Ft int
.Fo socket
.Fa "int domain"
.Fa "int type"
.Fa "int protocol"
.Fc
.Sh DESCRIPTION
.Fn Socket
creates an endpoint for communication and returns a descriptor.
.Pp
The
.Fa domain
parameter specifies a communications domain within which
communication will take place; this selects the protocol family
which should be used.
These families are defined in the include file
.Ao Pa sys/socket.h Ac .
The currently understood formats are
.Pp
.Bd -literal -offset indent -compact
AF_UNIX		(UNIX internal protocols),
AF_INET		(ARPA Internet protocols),
AF_ISO		(ISO protocols),
AF_NS		(Xerox Network Systems protocols), and
AF_IMPLINK	(IMP \*(lqhost at IMP\*(rq link layer).
.Ed
.Pp
The socket has the indicated
.Fa type ,
which specifies the semantics of communication.  Currently
defined types are:
.Pp
.Bd -literal -offset indent -compact
SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
SOCK_SEQPACKET
SOCK_RDM
.Ed
.Pp
A
.Dv SOCK_STREAM
type provides sequenced, reliable,
two-way connection based byte streams.
An out-of-band data transmission mechanism may be supported.
A
.Dv SOCK_DGRAM
socket supports
datagrams (connectionless, unreliable messages of
a fixed (typically small) maximum length).
A
.Dv SOCK_SEQPACKET
socket may provide a sequenced, reliable,
two-way connection-based data transmission path for datagrams
of fixed maximum length; a consumer may be required to read
an entire packet with each read system call.
This facility is protocol specific, and presently implemented
only for
.Dv PF_NS .
.Dv SOCK_RAW
sockets provide access to internal network protocols and interfaces.
The types
.Dv SOCK_RAW ,
which is available only to the super-user, and
.Dv SOCK_RDM ,
which is planned,
but not yet implemented, are not described here.
.Pp
The
.Fa protocol
specifies a particular protocol to be used with the socket.
Normally only a single protocol exists to support a particular
socket type within a given protocol family.  However, it is possible
that many protocols may exist, in which case a particular protocol
must be specified in this manner.  The protocol number to use is
particular to the \*(lqcommunication domain\*(rq in which communication
is to take place; see
.Xr protocols 5 .
.Pp
Sockets of type
.Dv SOCK_STREAM
are full-duplex byte streams, similar
to pipes.  A stream socket must be in a
.Em connected
state before any data may be sent or received
on it.  A connection to another socket is created with a
.Xr connect 2
call.  Once connected, data may be transferred using
.Xr read 2
and
.Xr write 2
calls or some variant of the 
.Xr send 2
and
.Xr recv 2
calls.  When a session has been completed a
.Xr close 2
may be performed.
Out-of-band data may also be transmitted as described in
.Xr send 2
and received as described in
.Xr recv 2 .
.Pp
The communications protocols used to implement a
.Dv SOCK_STREAM
insure that data
is not lost or duplicated.  If a piece of data for which the
peer protocol has buffer space cannot be successfully transmitted
within a reasonable length of time, then
the connection is considered broken and calls
will indicate an error with
-1 returns and with
.Dv ETIMEDOUT
as the specific code
in the global variable
.Va errno .
The protocols optionally keep sockets
.Dq warm
by forcing transmissions
roughly every minute in the absence of other activity.
An error is then indicated if no response can be
elicited on an otherwise
idle connection for a extended period (e.g. 5 minutes).
A
.Dv SIGPIPE
signal is raised if a process sends
on a broken stream; this causes naive processes,
which do not handle the signal, to exit.
.Pp
.Dv SOCK_SEQPACKET
sockets employ the same system calls
as
.Dv SOCK_STREAM
sockets.  The only difference
is that 
.Xr read 2
calls will return only the amount of data requested,
and any remaining in the arriving packet will be discarded.
.Pp
.Dv SOCK_DGRAM
and
.Dv SOCK_RAW
sockets allow sending of datagrams to correspondents
named in
.Xr send 2
calls.  Datagrams are generally received with
.Xr recvfrom 2 ,
which returns the next datagram with its return address.
.Pp
An 
.Xr fcntl 2
call can be used to specify a process group to receive
a
.Dv SIGURG
signal when the out-of-band data arrives.
It may also enable non-blocking I/O
and asynchronous notification of I/O events
via
.Dv SIGIO .
.Pp
The operation of sockets is controlled by socket level
.Em options .
These options are defined in the file
.Ao Pa sys/socket.h Ac .
.Xr Setsockopt 2
and
.Xr getsockopt 2
are used to set and get options, respectively.
.Sh RETURN VALUES
A -1 is returned if an error occurs, otherwise the return
value is a descriptor referencing the socket.
.Sh ERRORS
The
.Fn socket
system call fails if:
.Bl -tag -width Er
.\" ===========
.It Bq Er EACCES
Permission to create a socket of the specified type and/or protocol
is denied.
.\" ===========
.It Bq Er EAFNOSUPPORT
The specified address family is not supported.
.\" ===========
.It Bq Er EISCONN
The per-process descriptor table is full.
.\" ===========
.It Bq Er EMFILE
The per-process descriptor table is full.
.\" ===========
.It Bq Er ENFILE
The system file table is full.
.\" ===========
.It Bq Er ENOBUFS
Insufficient buffer space is available.
The socket cannot be created until sufficient resources are freed.
.\" ===========
.It Bq Er ENOMEM
Insufficient memory was available to fulfill the request.
.\" ===========
.It Bq Er EPROTONOSUPPORT
The protocol type or the specified protocol is not supported
within this domain.
.\" ===========
.It Bq Er EPROTOTYPE
The socket type is not supported by the protocol.
.El
.Pp
If a new protocol family is defined,
the socreate process is free to return any desired error code.
The
.Fn socket
system call will pass this error code along
(even if it is undefined).
.Sh LEGACY SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Pp
The include file
.In sys/types.h
is necessary.
.Sh SEE ALSO
.Xr accept 2 ,
.Xr bind 2 ,
.Xr connect 2 ,
.Xr getsockname 2 ,
.Xr getsockopt 2 ,
.Xr ioctl 2 ,
.Xr listen 2 ,
.Xr read 2 ,
.Xr recv 2 ,
.Xr select 2 ,
.Xr send 2 ,
.Xr shutdown 2 ,
.Xr socketpair 2 ,
.Xr write 2 ,
.Xr getprotoent 3 ,
.Xr inet 4 ,
.Xr inet6 4 ,
.Xr unix 4 ,
.Xr compat 5
.Rs
.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
.Re
.Rs
.%T "BSD Interprocess Communication Tutorial"
.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
.Re
.Sh HISTORY
The
.Fn socket
function call appeared in
.Bx 4.2 .
Commit	Line	Data
9bccf70c A	1	.\" $NetBSD: socket.2,v 1.5 1995/02/27 12:37:53 cgd 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	.\" @(#)socket.2 8.1 (Berkeley) 6/4/93
	35	.\"
	36	.Dd June 4, 1993
	37	.Dt SOCKET 2
	38	.Os BSD 4.2
	39	.Sh NAME
	40	.Nm socket
	41	.Nd create an endpoint for communication
	42	.Sh SYNOPSIS
9bccf70c A	43	.Fd #include <sys/socket.h>
9bccf70c A	44	.Ft int
2d21ac55 A	45	.Fo socket
	46	.Fa "int domain"
	47	.Fa "int type"
	48	.Fa "int protocol"
	49	.Fc
9bccf70c A	50	.Sh DESCRIPTION
	51	.Fn Socket
	52	creates an endpoint for communication and returns a descriptor.
	53	.Pp
	54	The
	55	.Fa domain
	56	parameter specifies a communications domain within which
	57	communication will take place; this selects the protocol family
	58	which should be used.
	59	These families are defined in the include file
	60	.Ao Pa sys/socket.h Ac .
	61	The currently understood formats are
	62	.Pp
	63	.Bd -literal -offset indent -compact
	64	AF_UNIX (UNIX internal protocols),
	65	AF_INET (ARPA Internet protocols),
	66	AF_ISO (ISO protocols),
	67	AF_NS (Xerox Network Systems protocols), and
	68	AF_IMPLINK (IMP \(lqhost at IMP\(rq link layer).
	69	.Ed
	70	.Pp
	71	The socket has the indicated
	72	.Fa type ,
	73	which specifies the semantics of communication. Currently
	74	defined types are:
	75	.Pp
	76	.Bd -literal -offset indent -compact
	77	SOCK_STREAM
	78	SOCK_DGRAM
	79	SOCK_RAW
	80	SOCK_SEQPACKET
	81	SOCK_RDM
	82	.Ed
	83	.Pp
	84	A
	85	.Dv SOCK_STREAM
	86	type provides sequenced, reliable,
	87	two-way connection based byte streams.
	88	An out-of-band data transmission mechanism may be supported.
	89	A
	90	.Dv SOCK_DGRAM
	91	socket supports
	92	datagrams (connectionless, unreliable messages of
	93	a fixed (typically small) maximum length).
	94	A
	95	.Dv SOCK_SEQPACKET
	96	socket may provide a sequenced, reliable,
	97	two-way connection-based data transmission path for datagrams
	98	of fixed maximum length; a consumer may be required to read
	99	an entire packet with each read system call.
	100	This facility is protocol specific, and presently implemented
	101	only for
	102	.Dv PF_NS .
	103	.Dv SOCK_RAW
	104	sockets provide access to internal network protocols and interfaces.
	105	The types
	106	.Dv SOCK_RAW ,
	107	which is available only to the super-user, and
	108	.Dv SOCK_RDM ,
	109	which is planned,
	110	but not yet implemented, are not described here.
	111	.Pp
	112	The
	113	.Fa protocol
114	specifies a particular protocol to be used with the socket.
115	Normally only a single protocol exists to support a particular
116	socket type within a given protocol family. However, it is possible
117	that many protocols may exist, in which case a particular protocol
118	must be specified in this manner. The protocol number to use is
119	particular to the \(lqcommunication domain\(rq in which communication
120	is to take place; see
121	.Xr protocols 5 .
122	.Pp
123	Sockets of type
124	.Dv SOCK_STREAM
125	are full-duplex byte streams, similar
126	to pipes. A stream socket must be in a
127	.Em connected
128	state before any data may be sent or received
129	on it. A connection to another socket is created with a
130	.Xr connect 2
131	call. Once connected, data may be transferred using
132	.Xr read 2
133	and
134	.Xr write 2
135	calls or some variant of the
136	.Xr send 2
137	and
138	.Xr recv 2
139	calls. When a session has been completed a
140	.Xr close 2
141	may be performed.
142	Out-of-band data may also be transmitted as described in
143	.Xr send 2
144	and received as described in
145	.Xr recv 2 .
146	.Pp
147	The communications protocols used to implement a
148	.Dv SOCK_STREAM
149	insure that data
150	is not lost or duplicated. If a piece of data for which the
151	peer protocol has buffer space cannot be successfully transmitted
152	within a reasonable length of time, then
153	the connection is considered broken and calls
154	will indicate an error with
155	-1 returns and with
156	.Dv ETIMEDOUT
157	as the specific code
158	in the global variable
159	.Va errno .
160	The protocols optionally keep sockets
161	.Dq warm
162	by forcing transmissions
163	roughly every minute in the absence of other activity.
164	An error is then indicated if no response can be
165	elicited on an otherwise
166	idle connection for a extended period (e.g. 5 minutes).
167	A
168	.Dv SIGPIPE
169	signal is raised if a process sends
170	on a broken stream; this causes naive processes,
171	which do not handle the signal, to exit.
172	.Pp
173	.Dv SOCK_SEQPACKET
174	sockets employ the same system calls
175	as
176	.Dv SOCK_STREAM
177	sockets. The only difference
178	is that
179	.Xr read 2
180	calls will return only the amount of data requested,
181	and any remaining in the arriving packet will be discarded.
182	.Pp
183	.Dv SOCK_DGRAM
184	and
185	.Dv SOCK_RAW
186	sockets allow sending of datagrams to correspondents
187	named in
188	.Xr send 2
189	calls. Datagrams are generally received with
190	.Xr recvfrom 2 ,
191	which returns the next datagram with its return address.
192	.Pp
193	An
194	.Xr fcntl 2
195	call can be used to specify a process group to receive
196	a
197	.Dv SIGURG
198	signal when the out-of-band data arrives.
199	It may also enable non-blocking I/O
200	and asynchronous notification of I/O events
201	via
202	.Dv SIGIO .
203	.Pp
204	The operation of sockets is controlled by socket level
205	.Em options .
206	These options are defined in the file
207	.Ao Pa sys/socket.h Ac .
208	.Xr Setsockopt 2
209	and
210	.Xr getsockopt 2
211	are used to set and get options, respectively.
212	.Sh RETURN VALUES
213	A -1 is returned if an error occurs, otherwise the return
214	value is a descriptor referencing the socket.
215	.Sh ERRORS
216	The
217	.Fn socket
2d21ac55	218	system call fails if:
9bccf70c	219	.Bl -tag -width Er
2d21ac55 A	220	.\" ===========
	221	.It Bq Er EACCES
	222	Permission to create a socket of the specified type and/or protocol
	223	is denied.
	224	.\" ===========
	225	.It Bq Er EAFNOSUPPORT
	226	The specified address family is not supported.
	227	.\" ===========
	228	.It Bq Er EISCONN
	229	The per-process descriptor table is full.
	230	.\" ===========
9bccf70c A	231	.It Bq Er EMFILE
9bccf70c A	232	The per-process descriptor table is full.
2d21ac55	233	.\" ===========
9bccf70c A	234	.It Bq Er ENFILE
9bccf70c A	235	The system file table is full.
2d21ac55	236	.\" ===========
9bccf70c A	237	.It Bq Er ENOBUFS
	238	Insufficient buffer space is available.
	239	The socket cannot be created until sufficient resources are freed.
2d21ac55 A	240	.\" ===========
	241	.It Bq Er ENOMEM
	242	Insufficient memory was available to fulfill the request.
	243	.\" ===========
	244	.It Bq Er EPROTONOSUPPORT
	245	The protocol type or the specified protocol is not supported
	246	within this domain.
	247	.\" ===========
	248	.It Bq Er EPROTOTYPE
	249	The socket type is not supported by the protocol.
9bccf70c	250	.El
2d21ac55 A	251	.Pp
	252	If a new protocol family is defined,
	253	the socreate process is free to return any desired error code.
	254	The
	255	.Fn socket
	256	system call will pass this error code along
	257	(even if it is undefined).
	258	.Sh LEGACY SYNOPSIS
	259	.Fd #include <sys/types.h>
	260	.Fd #include <sys/socket.h>
	261	.Pp
	262	The include file
	263	.In sys/types.h
	264	is necessary.
9bccf70c A	265	.Sh SEE ALSO
	266	.Xr accept 2 ,
	267	.Xr bind 2 ,
	268	.Xr connect 2 ,
9bccf70c A	269	.Xr getsockname 2 ,
	270	.Xr getsockopt 2 ,
	271	.Xr ioctl 2 ,
	272	.Xr listen 2 ,
	273	.Xr read 2 ,
	274	.Xr recv 2 ,
	275	.Xr select 2 ,
	276	.Xr send 2 ,
	277	.Xr shutdown 2 ,
	278	.Xr socketpair 2 ,
2d21ac55 A	279	.Xr write 2 ,
	280	.Xr getprotoent 3 ,
	281	.Xr inet 4 ,
	282	.Xr inet6 4 ,
	283	.Xr unix 4 ,
	284	.Xr compat 5
9bccf70c A	285	.Rs
	286	.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
	287	.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
	288	.Re
	289	.Rs
	290	.%T "BSD Interprocess Communication Tutorial"
	291	.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
	292	.Re
	293	.Sh HISTORY
	294	The
	295	.Fn socket
	296	function call appeared in
	297	.Bx 4.2 .