[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 
.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
PF_LOCAL	Host-internal protocols, formerly called PF_UNIX,
PF_UNIX		Host-internal protocols, deprecated, use PF_LOCAL,
PF_INET		Internet version 4 protocols,
PF_ROUTE	Internal Routing protocol,
PF_KEY		Internal key-management function,
PF_INET6	Internet version 6 protocols,
PF_SYSTEM	System domain,
PF_NDRV		Raw access to network device
.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 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
b0d623f7	38	.Os
9bccf70c A	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
b0d623f7 A	64	PF_LOCAL Host-internal protocols, formerly called PF_UNIX,
	65	PF_UNIX Host-internal protocols, deprecated, use PF_LOCAL,
	66	PF_INET Internet version 4 protocols,
	67	PF_ROUTE Internal Routing protocol,
	68	PF_KEY Internal key-management function,
	69	PF_INET6 Internet version 6 protocols,
	70	PF_SYSTEM System domain,
	71	PF_NDRV Raw access to network device
9bccf70c A	72	.Ed
	73	.Pp
	74	The socket has the indicated
	75	.Fa type ,
	76	which specifies the semantics of communication. Currently
	77	defined types are:
	78	.Pp
	79	.Bd -literal -offset indent -compact
	80	SOCK_STREAM
	81	SOCK_DGRAM
	82	SOCK_RAW
	83	SOCK_SEQPACKET
	84	SOCK_RDM
	85	.Ed
	86	.Pp
	87	A
	88	.Dv SOCK_STREAM
	89	type provides sequenced, reliable,
	90	two-way connection based byte streams.
	91	An out-of-band data transmission mechanism may be supported.
	92	A
	93	.Dv SOCK_DGRAM
	94	socket supports
	95	datagrams (connectionless, unreliable messages of
	96	a fixed (typically small) maximum length).
	97	A
	98	.Dv SOCK_SEQPACKET
	99	socket may provide a sequenced, reliable,
	100	two-way connection-based data transmission path for datagrams
	101	of fixed maximum length; a consumer may be required to read
	102	an entire packet with each read system call.
	103	This facility is protocol specific, and presently implemented
	104	only for
	105	.Dv PF_NS .
	106	.Dv SOCK_RAW
	107	sockets provide access to internal network protocols and interfaces.
	108	The types
	109	.Dv SOCK_RAW ,
	110	which is available only to the super-user, and
	111	.Dv SOCK_RDM ,
	112	which is planned,
	113	but not yet implemented, are not described here.
	114	.Pp
	115	The
	116	.Fa protocol
	117	specifies a particular protocol to be used with the socket.
	118	Normally only a single protocol exists to support a particular
	119	socket type within a given protocol family. However, it is possible
	120	that many protocols may exist, in which case a particular protocol
	121	must be specified in this manner. The protocol number to use is
	122	particular to the \(lqcommunication domain\(rq in which communication
	123	is to take place; see
	124	.Xr protocols 5 .
	125	.Pp
	126	Sockets of type
	127	.Dv SOCK_STREAM
	128	are full-duplex byte streams, similar
	129	to pipes. A stream socket must be in a
	130	.Em connected
	131	state before any data may be sent or received
	132	on it. A connection to another socket is created with a
	133	.Xr connect 2
	134	call. Once connected, data may be transferred using
	135	.Xr read 2
136	and
137	.Xr write 2
138	calls or some variant of the
139	.Xr send 2
140	and
141	.Xr recv 2
142	calls. When a session has been completed a
143	.Xr close 2
144	may be performed.
145	Out-of-band data may also be transmitted as described in
146	.Xr send 2
147	and received as described in
148	.Xr recv 2 .
149	.Pp
150	The communications protocols used to implement a
151	.Dv SOCK_STREAM
152	insure that data
153	is not lost or duplicated. If a piece of data for which the
154	peer protocol has buffer space cannot be successfully transmitted
155	within a reasonable length of time, then
156	the connection is considered broken and calls
157	will indicate an error with
158	-1 returns and with
159	.Dv ETIMEDOUT
160	as the specific code
161	in the global variable
162	.Va errno .
163	The protocols optionally keep sockets
164	.Dq warm
165	by forcing transmissions
166	roughly every minute in the absence of other activity.
167	An error is then indicated if no response can be
168	elicited on an otherwise
169	idle connection for a extended period (e.g. 5 minutes).
170	A
171	.Dv SIGPIPE
172	signal is raised if a process sends
173	on a broken stream; this causes naive processes,
174	which do not handle the signal, to exit.
175	.Pp
176	.Dv SOCK_SEQPACKET
177	sockets employ the same system calls
178	as
179	.Dv SOCK_STREAM
180	sockets. The only difference
181	is that
182	.Xr read 2
183	calls will return only the amount of data requested,
184	and any remaining in the arriving packet will be discarded.
185	.Pp
186	.Dv SOCK_DGRAM
187	and
188	.Dv SOCK_RAW
189	sockets allow sending of datagrams to correspondents
190	named in
191	.Xr send 2
192	calls. Datagrams are generally received with
193	.Xr recvfrom 2 ,
194	which returns the next datagram with its return address.
195	.Pp
196	An
197	.Xr fcntl 2
198	call can be used to specify a process group to receive
199	a
200	.Dv SIGURG
201	signal when the out-of-band data arrives.
202	It may also enable non-blocking I/O
203	and asynchronous notification of I/O events
204	via
205	.Dv SIGIO .
206	.Pp
207	The operation of sockets is controlled by socket level
208	.Em options .
209	These options are defined in the file
210	.Ao Pa sys/socket.h Ac .
211	.Xr Setsockopt 2
212	and
213	.Xr getsockopt 2
214	are used to set and get options, respectively.
215	.Sh RETURN VALUES
216	A -1 is returned if an error occurs, otherwise the return
217	value is a descriptor referencing the socket.
218	.Sh ERRORS
219	The
220	.Fn socket
2d21ac55	221	system call fails if:
9bccf70c	222	.Bl -tag -width Er
2d21ac55 A	223	.\" ===========
	224	.It Bq Er EACCES
	225	Permission to create a socket of the specified type and/or protocol
	226	is denied.
	227	.\" ===========
	228	.It Bq Er EAFNOSUPPORT
	229	The specified address family is not supported.
	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 .