[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 March 18, 2015
.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 type
.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
or
.Xr connectx 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 connectx 2 ,
.Xr disconnectx 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	.\"
3e170ce0	36	.Dd March 18, 2015
9bccf70c	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	50	.Sh DESCRIPTION
3e170ce0	51	.Fn socket
9bccf70c A	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
3e170ce0 A	83	.\"SOCK_SEQPACKET
3e170ce0 A	84	.\"SOCK_RDM
9bccf70c A	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).
3e170ce0 A	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 .
9bccf70c A	106	.Dv SOCK_RAW
9bccf70c A	107	sockets provide access to internal network protocols and interfaces.
3e170ce0	108	The type
9bccf70c	109	.Dv SOCK_RAW ,
3e170ce0 A	110	which is available only to the super-user.
	111	.\" , and
	112	.\" .Dv SOCK_RDM ,
	113	.\" which is planned,
	114	.\" but not yet implemented, are not described here.
9bccf70c A	115	.Pp
	116	The
	117	.Fa protocol
	118	specifies a particular protocol to be used with the socket.
	119	Normally only a single protocol exists to support a particular
	120	socket type within a given protocol family. However, it is possible
	121	that many protocols may exist, in which case a particular protocol
	122	must be specified in this manner. The protocol number to use is
	123	particular to the \(lqcommunication domain\(rq in which communication
	124	is to take place; see
	125	.Xr protocols 5 .
	126	.Pp
	127	Sockets of type
	128	.Dv SOCK_STREAM
	129	are full-duplex byte streams, similar
	130	to pipes. A stream socket must be in a
	131	.Em connected
	132	state before any data may be sent or received
	133	on it. A connection to another socket is created with a
	134	.Xr connect 2
3e170ce0 A	135	or
3e170ce0 A	136	.Xr connectx 2
9bccf70c A	137	call. Once connected, data may be transferred using
	138	.Xr read 2
	139	and
	140	.Xr write 2
	141	calls or some variant of the
	142	.Xr send 2
	143	and
	144	.Xr recv 2
	145	calls. When a session has been completed a
	146	.Xr close 2
	147	may be performed.
	148	Out-of-band data may also be transmitted as described in
	149	.Xr send 2
	150	and received as described in
	151	.Xr recv 2 .
	152	.Pp
	153	The communications protocols used to implement a
	154	.Dv SOCK_STREAM
	155	insure that data
	156	is not lost or duplicated. If a piece of data for which the
	157	peer protocol has buffer space cannot be successfully transmitted
	158	within a reasonable length of time, then
	159	the connection is considered broken and calls
	160	will indicate an error with
	161	-1 returns and with
	162	.Dv ETIMEDOUT
	163	as the specific code
	164	in the global variable
	165	.Va errno .
	166	The protocols optionally keep sockets
	167	.Dq warm
	168	by forcing transmissions
	169	roughly every minute in the absence of other activity.
	170	An error is then indicated if no response can be
	171	elicited on an otherwise
	172	idle connection for a extended period (e.g. 5 minutes).
	173	A
	174	.Dv SIGPIPE
	175	signal is raised if a process sends
	176	on a broken stream; this causes naive processes,
	177	which do not handle the signal, to exit.
3e170ce0 A	178	.\" .Pp
	179	.\" .Dv SOCK_SEQPACKET
	180	.\" sockets employ the same system calls
	181	.\" as
	182	.\" .Dv SOCK_STREAM
	183	.\" sockets. The only difference
	184	.\" is that
	185	.\" .Xr read 2
	186	.\" calls will return only the amount of data requested,
	187	.\" and any remaining in the arriving packet will be discarded.
9bccf70c A	188	.Pp
	189	.Dv SOCK_DGRAM
	190	and
	191	.Dv SOCK_RAW
	192	sockets allow sending of datagrams to correspondents
	193	named in
	194	.Xr send 2
	195	calls. Datagrams are generally received with
	196	.Xr recvfrom 2 ,
	197	which returns the next datagram with its return address.
	198	.Pp
	199	An
	200	.Xr fcntl 2
	201	call can be used to specify a process group to receive
	202	a
	203	.Dv SIGURG
	204	signal when the out-of-band data arrives.
	205	It may also enable non-blocking I/O
	206	and asynchronous notification of I/O events
	207	via
	208	.Dv SIGIO .
	209	.Pp
	210	The operation of sockets is controlled by socket level
	211	.Em options .
	212	These options are defined in the file
	213	.Ao Pa sys/socket.h Ac .
	214	.Xr Setsockopt 2
	215	and
	216	.Xr getsockopt 2
	217	are used to set and get options, respectively.
	218	.Sh RETURN VALUES
	219	A -1 is returned if an error occurs, otherwise the return
	220	value is a descriptor referencing the socket.
	221	.Sh ERRORS
	222	The
	223	.Fn socket
2d21ac55	224	system call fails if:
9bccf70c	225	.Bl -tag -width Er
2d21ac55 A	226	.\" ===========
	227	.It Bq Er EACCES
	228	Permission to create a socket of the specified type and/or protocol
	229	is denied.
	230	.\" ===========
	231	.It Bq Er EAFNOSUPPORT
	232	The specified address family is not supported.
	233	.\" ===========
9bccf70c A	234	.It Bq Er EMFILE
9bccf70c A	235	The per-process descriptor table is full.
2d21ac55	236	.\" ===========
9bccf70c A	237	.It Bq Er ENFILE
9bccf70c A	238	The system file table is full.
2d21ac55	239	.\" ===========
9bccf70c A	240	.It Bq Er ENOBUFS
	241	Insufficient buffer space is available.
	242	The socket cannot be created until sufficient resources are freed.
2d21ac55 A	243	.\" ===========
	244	.It Bq Er ENOMEM
	245	Insufficient memory was available to fulfill the request.
	246	.\" ===========
	247	.It Bq Er EPROTONOSUPPORT
	248	The protocol type or the specified protocol is not supported
	249	within this domain.
	250	.\" ===========
	251	.It Bq Er EPROTOTYPE
	252	The socket type is not supported by the protocol.
9bccf70c	253	.El
2d21ac55 A	254	.Pp
	255	If a new protocol family is defined,
	256	the socreate process is free to return any desired error code.
	257	The
	258	.Fn socket
	259	system call will pass this error code along
	260	(even if it is undefined).
	261	.Sh LEGACY SYNOPSIS
	262	.Fd #include <sys/types.h>
	263	.Fd #include <sys/socket.h>
	264	.Pp
	265	The include file
	266	.In sys/types.h
	267	is necessary.
9bccf70c A	268	.Sh SEE ALSO
	269	.Xr accept 2 ,
	270	.Xr bind 2 ,
	271	.Xr connect 2 ,
3e170ce0 A	272	.Xr connectx 2 ,
3e170ce0 A	273	.Xr disconnectx 2 ,
9bccf70c A	274	.Xr getsockname 2 ,
	275	.Xr getsockopt 2 ,
	276	.Xr ioctl 2 ,
	277	.Xr listen 2 ,
	278	.Xr read 2 ,
	279	.Xr recv 2 ,
	280	.Xr select 2 ,
	281	.Xr send 2 ,
	282	.Xr shutdown 2 ,
	283	.Xr socketpair 2 ,
2d21ac55 A	284	.Xr write 2 ,
	285	.Xr getprotoent 3 ,
	286	.Xr inet 4 ,
	287	.Xr inet6 4 ,
	288	.Xr unix 4 ,
	289	.Xr compat 5
9bccf70c A	290	.Rs
	291	.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
	292	.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
	293	.Re
	294	.Rs
	295	.%T "BSD Interprocess Communication Tutorial"
	296	.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
	297	.Re
	298	.Sh HISTORY
	299	The
	300	.Fn socket
	301	function call appeared in
	302	.Bx 4.2 .