1.\" Copyright (c) 1983, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" From: @(#)socket.2 8.1 (Berkeley) 6/4/93
33.\" $FreeBSD: head/lib/libc/sys/socket.2 108028 2002-12-18 09:22:32Z ru $
34.\"
35.Dd November 24, 1997
36.Dt SOCKET 2
37.Os
38.Sh NAME
39.Nm socket
40.Nd create an endpoint for communication
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In sys/types.h
45.In sys/socket.h
46.Ft int
47.Fn socket "int domain" "int type" "int protocol"
48.Sh DESCRIPTION
49The
50.Fn socket
51system call
52creates an endpoint for communication and returns a descriptor.
53.Pp
54The
55.Fa domain
56parameter specifies a communications domain within which
57communication will take place; this selects the protocol family
58which should be used.
59These families are defined in the include file
60.Ao Pa sys/socket.h Ac .
61The currently understood formats are:
62.Pp
63.Bd -literal -offset indent -compact
64PF_LOCAL Host-internal protocols, formerly called PF_UNIX,
65PF_UNIX Host-internal protocols, deprecated, use PF_LOCAL,
66PF_INET Internet version 4 protocols,
67PF_IMPLINK ARPAnet IMP addresses,
68PF_PUP PUP protocols, like BSP,
69PF_CHAOS MIT CHAOS protocols,
70PF_NS Xerox Network Systems protocols,
71PF_ISO ISO protocols,
72PF_OSI Open Systems Interconnection protocols,
73PF_ECMA European Computer Manufacturers,
74PF_DATAKIT Datakit protocols,
75PF_CCITT ITU-T protocols, like X.25,
76PF_SNA IBM SNA,
77PF_DECnet DECnet,
78PF_DLI DEC Direct Data Link Interface protocol,
79PF_LAT LAT protocol,
80PF_HYLINK NSC Hyperchannel,
81PF_APPLETALK AppleTalk protocols,
82PF_ROUTE Internal Routing protocol,
83PF_LINK Link layer interface,
84PF_XTP eXpress Transfer Protocol,
85PF_COIP Connection-Oriented IP, aka ST II,
86PF_CNT Computer Network Technology,
87PF_SIP Simple Internet Protocol,
88PF_IPX Novell Intenet Packet eXchange protocol,
89PF_RTIP Help Identify RTIP packets,
90PF_PIP Help Identify PIP packets,
91PF_ISDN Integrated Services Digital Network,
92PF_KEY Internal key-management function,
93PF_INET6 Internet version 6 protocols,
94PF_NATM Native ATM access,
95PF_ATM ATM,
96PF_NETGRAPH Netgraph sockets
97.Ed
98.Pp
99The socket has the indicated
100.Fa type ,
101which specifies the semantics of communication. Currently
102defined types are:
103.Pp
104.Bd -literal -offset indent -compact
105SOCK_STREAM Stream socket,
106SOCK_DGRAM Datagram socket,
107SOCK_RAW Raw-protocol interface,
108SOCK_RDM Reliably-delivered packet,
109SOCK_SEQPACKET Sequenced packet stream
110.Ed
111.Pp
112A
113.Dv SOCK_STREAM
114type provides sequenced, reliable,
115two-way connection based byte streams.
116An out-of-band data transmission mechanism may be supported.
117A
118.Dv SOCK_DGRAM
119socket supports
120datagrams (connectionless, unreliable messages of
121a fixed (typically small) maximum length).
122A
123.Dv SOCK_SEQPACKET
124socket may provide a sequenced, reliable,
125two-way connection-based data transmission path for datagrams
126of fixed maximum length; a consumer may be required to read
127an entire packet with each read system call.
128This facility is protocol specific, and presently implemented
129only for
130.Dv PF_NS .
131.Dv SOCK_RAW
132sockets provide access to internal network protocols and interfaces.
133The types
134.Dv SOCK_RAW ,
135which is available only to the super-user, and
136.Dv SOCK_RDM ,
137which is planned,
138but not yet implemented, are not described here.
139.Pp
140The
141.Fa protocol
142specifies a particular protocol to be used with the socket.
143Normally only a single protocol exists to support a particular
144socket type within a given protocol family. However, it is possible
145that many protocols may exist, in which case a particular protocol
146must be specified in this manner. The protocol number to use is
147particular to the
148.Dq "communication domain"
149in which communication
150is to take place; see
151.Xr protocols 5 .
152.Pp
153Sockets of type
154.Dv SOCK_STREAM
155are full-duplex byte streams, similar
156to pipes. A stream socket must be in a
157.Em connected
158state before any data may be sent or received
159on it. A connection to another socket is created with a
160.Xr connect 2
161system call.
162Once connected, data may be transferred using
163.Xr read 2
164and
165.Xr write 2
166calls or some variant of the
167.Xr send 2
168and
169.Xr recv 2
170functions.
171(Some protocol families, such as the Internet family,
172support the notion of an
173.Dq implied connect ,
174which permits data to be sent piggybacked onto a connect operation by
175using the
176.Xr sendto 2
177system call.)
178When a session has been completed a
179.Xr close 2
180may be performed.
181Out-of-band data may also be transmitted as described in
182.Xr send 2
183and received as described in
184.Xr recv 2 .
185.Pp
186The communications protocols used to implement a
187.Dv SOCK_STREAM
188insure that data
189is not lost or duplicated. If a piece of data for which the
190peer protocol has buffer space cannot be successfully transmitted
191within a reasonable length of time, then
192the connection is considered broken and calls
193will indicate an error with
194-1 returns and with
195.Er ETIMEDOUT
196as the specific code
197in the global variable
198.Va errno .
199The protocols optionally keep sockets
200.Dq warm
201by forcing transmissions
202roughly every minute in the absence of other activity.
203An error is then indicated if no response can be
204elicited on an otherwise
205idle connection for a extended period (e.g. 5 minutes).
206A
207.Dv SIGPIPE
208signal is raised if a process sends
209on a broken stream; this causes naive processes,
210which do not handle the signal, to exit.
211.Pp
212.Dv SOCK_SEQPACKET
213sockets employ the same system calls
214as
215.Dv SOCK_STREAM
216sockets. The only difference
217is that
218.Xr read 2
219calls will return only the amount of data requested,
220and any remaining in the arriving packet will be discarded.
221.Pp
222.Dv SOCK_DGRAM
223and
224.Dv SOCK_RAW
225sockets allow sending of datagrams to correspondents
226named in
227.Xr send 2
228calls. Datagrams are generally received with
229.Xr recvfrom 2 ,
230which returns the next datagram with its return address.
231.Pp
232An
233.Xr fcntl 2
234system call can be used to specify a process group to receive
235a
236.Dv SIGURG
237signal when the out-of-band data arrives.
238It may also enable non-blocking I/O
239and asynchronous notification of I/O events
240via
241.Dv SIGIO .
242.Pp
243The operation of sockets is controlled by socket level
244.Em options .
245These options are defined in the file
246.Ao Pa sys/socket.h Ac .
247.Xr Setsockopt 2
248and
249.Xr getsockopt 2
250are used to set and get options, respectively.
251.Sh RETURN VALUES
252A -1 is returned if an error occurs, otherwise the return
253value is a descriptor referencing the socket.
254.Sh ERRORS
255The
256.Fn socket
257system call fails if:
258.Bl -tag -width Er
259.It Bq Er EPROTONOSUPPORT
260The protocol type or the specified protocol is not supported
261within this domain.
262.It Bq Er EMFILE
263The per-process descriptor table is full.
264.It Bq Er ENFILE
265The system file table is full.
266.It Bq Er EACCES
267Permission to create a socket of the specified type and/or protocol
268is denied.
269.It Bq Er ENOBUFS
270Insufficient buffer space is available.
271The socket cannot be created until sufficient resources are freed.
272.El
273.Sh SEE ALSO
274.Xr accept 2 ,
275.Xr bind 2 ,
276.Xr connect 2 ,
277.Xr getpeername 2 ,
278.Xr getsockname 2 ,
279.Xr getsockopt 2 ,
280.Xr ioctl 2 ,
281.Xr listen 2 ,
282.Xr read 2 ,
283.Xr recv 2 ,
284.Xr select 2 ,
285.Xr send 2 ,
286.Xr shutdown 2 ,
287.Xr socketpair 2 ,
288.Xr write 2 ,
289.Xr getprotoent 3 ,
290.Xr netgraph 4 ,
291.Xr protocols 5
292.Rs
293.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
294.%B PS1
295.%N 7
296.Re
297.Rs
298.%T "BSD Interprocess Communication Tutorial"
299.%B PS1
300.%N 8
301.Re
302.Sh HISTORY
303The
304.Fn socket
305system call appeared in
306.Bx 4.2 .
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" From: @(#)socket.2 8.1 (Berkeley) 6/4/93
33.\" $FreeBSD: head/lib/libc/sys/socket.2 108028 2002-12-18 09:22:32Z ru $
34.\"
35.Dd November 24, 1997
36.Dt SOCKET 2
37.Os
38.Sh NAME
39.Nm socket
40.Nd create an endpoint for communication
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In sys/types.h
45.In sys/socket.h
46.Ft int
47.Fn socket "int domain" "int type" "int protocol"
48.Sh DESCRIPTION
49The
50.Fn socket
51system call
52creates an endpoint for communication and returns a descriptor.
53.Pp
54The
55.Fa domain
56parameter specifies a communications domain within which
57communication will take place; this selects the protocol family
58which should be used.
59These families are defined in the include file
60.Ao Pa sys/socket.h Ac .
61The currently understood formats are:
62.Pp
63.Bd -literal -offset indent -compact
64PF_LOCAL Host-internal protocols, formerly called PF_UNIX,
65PF_UNIX Host-internal protocols, deprecated, use PF_LOCAL,
66PF_INET Internet version 4 protocols,
67PF_IMPLINK ARPAnet IMP addresses,
68PF_PUP PUP protocols, like BSP,
69PF_CHAOS MIT CHAOS protocols,
70PF_NS Xerox Network Systems protocols,
71PF_ISO ISO protocols,
72PF_OSI Open Systems Interconnection protocols,
73PF_ECMA European Computer Manufacturers,
74PF_DATAKIT Datakit protocols,
75PF_CCITT ITU-T protocols, like X.25,
76PF_SNA IBM SNA,
77PF_DECnet DECnet,
78PF_DLI DEC Direct Data Link Interface protocol,
79PF_LAT LAT protocol,
80PF_HYLINK NSC Hyperchannel,
81PF_APPLETALK AppleTalk protocols,
82PF_ROUTE Internal Routing protocol,
83PF_LINK Link layer interface,
84PF_XTP eXpress Transfer Protocol,
85PF_COIP Connection-Oriented IP, aka ST II,
86PF_CNT Computer Network Technology,
87PF_SIP Simple Internet Protocol,
88PF_IPX Novell Intenet Packet eXchange protocol,
89PF_RTIP Help Identify RTIP packets,
90PF_PIP Help Identify PIP packets,
91PF_ISDN Integrated Services Digital Network,
92PF_KEY Internal key-management function,
93PF_INET6 Internet version 6 protocols,
94PF_NATM Native ATM access,
95PF_ATM ATM,
96PF_NETGRAPH Netgraph sockets
97.Ed
98.Pp
99The socket has the indicated
100.Fa type ,
101which specifies the semantics of communication. Currently
102defined types are:
103.Pp
104.Bd -literal -offset indent -compact
105SOCK_STREAM Stream socket,
106SOCK_DGRAM Datagram socket,
107SOCK_RAW Raw-protocol interface,
108SOCK_RDM Reliably-delivered packet,
109SOCK_SEQPACKET Sequenced packet stream
110.Ed
111.Pp
112A
113.Dv SOCK_STREAM
114type provides sequenced, reliable,
115two-way connection based byte streams.
116An out-of-band data transmission mechanism may be supported.
117A
118.Dv SOCK_DGRAM
119socket supports
120datagrams (connectionless, unreliable messages of
121a fixed (typically small) maximum length).
122A
123.Dv SOCK_SEQPACKET
124socket may provide a sequenced, reliable,
125two-way connection-based data transmission path for datagrams
126of fixed maximum length; a consumer may be required to read
127an entire packet with each read system call.
128This facility is protocol specific, and presently implemented
129only for
130.Dv PF_NS .
131.Dv SOCK_RAW
132sockets provide access to internal network protocols and interfaces.
133The types
134.Dv SOCK_RAW ,
135which is available only to the super-user, and
136.Dv SOCK_RDM ,
137which is planned,
138but not yet implemented, are not described here.
139.Pp
140The
141.Fa protocol
142specifies a particular protocol to be used with the socket.
143Normally only a single protocol exists to support a particular
144socket type within a given protocol family. However, it is possible
145that many protocols may exist, in which case a particular protocol
146must be specified in this manner. The protocol number to use is
147particular to the
148.Dq "communication domain"
149in which communication
150is to take place; see
151.Xr protocols 5 .
152.Pp
153Sockets of type
154.Dv SOCK_STREAM
155are full-duplex byte streams, similar
156to pipes. A stream socket must be in a
157.Em connected
158state before any data may be sent or received
159on it. A connection to another socket is created with a
160.Xr connect 2
161system call.
162Once connected, data may be transferred using
163.Xr read 2
164and
165.Xr write 2
166calls or some variant of the
167.Xr send 2
168and
169.Xr recv 2
170functions.
171(Some protocol families, such as the Internet family,
172support the notion of an
173.Dq implied connect ,
174which permits data to be sent piggybacked onto a connect operation by
175using the
176.Xr sendto 2
177system call.)
178When a session has been completed a
179.Xr close 2
180may be performed.
181Out-of-band data may also be transmitted as described in
182.Xr send 2
183and received as described in
184.Xr recv 2 .
185.Pp
186The communications protocols used to implement a
187.Dv SOCK_STREAM
188insure that data
189is not lost or duplicated. If a piece of data for which the
190peer protocol has buffer space cannot be successfully transmitted
191within a reasonable length of time, then
192the connection is considered broken and calls
193will indicate an error with
194-1 returns and with
195.Er ETIMEDOUT
196as the specific code
197in the global variable
198.Va errno .
199The protocols optionally keep sockets
200.Dq warm
201by forcing transmissions
202roughly every minute in the absence of other activity.
203An error is then indicated if no response can be
204elicited on an otherwise
205idle connection for a extended period (e.g. 5 minutes).
206A
207.Dv SIGPIPE
208signal is raised if a process sends
209on a broken stream; this causes naive processes,
210which do not handle the signal, to exit.
211.Pp
212.Dv SOCK_SEQPACKET
213sockets employ the same system calls
214as
215.Dv SOCK_STREAM
216sockets. The only difference
217is that
218.Xr read 2
219calls will return only the amount of data requested,
220and any remaining in the arriving packet will be discarded.
221.Pp
222.Dv SOCK_DGRAM
223and
224.Dv SOCK_RAW
225sockets allow sending of datagrams to correspondents
226named in
227.Xr send 2
228calls. Datagrams are generally received with
229.Xr recvfrom 2 ,
230which returns the next datagram with its return address.
231.Pp
232An
233.Xr fcntl 2
234system call can be used to specify a process group to receive
235a
236.Dv SIGURG
237signal when the out-of-band data arrives.
238It may also enable non-blocking I/O
239and asynchronous notification of I/O events
240via
241.Dv SIGIO .
242.Pp
243The operation of sockets is controlled by socket level
244.Em options .
245These options are defined in the file
246.Ao Pa sys/socket.h Ac .
247.Xr Setsockopt 2
248and
249.Xr getsockopt 2
250are used to set and get options, respectively.
251.Sh RETURN VALUES
252A -1 is returned if an error occurs, otherwise the return
253value is a descriptor referencing the socket.
254.Sh ERRORS
255The
256.Fn socket
257system call fails if:
258.Bl -tag -width Er
259.It Bq Er EPROTONOSUPPORT
260The protocol type or the specified protocol is not supported
261within this domain.
262.It Bq Er EMFILE
263The per-process descriptor table is full.
264.It Bq Er ENFILE
265The system file table is full.
266.It Bq Er EACCES
267Permission to create a socket of the specified type and/or protocol
268is denied.
269.It Bq Er ENOBUFS
270Insufficient buffer space is available.
271The socket cannot be created until sufficient resources are freed.
272.El
273.Sh SEE ALSO
274.Xr accept 2 ,
275.Xr bind 2 ,
276.Xr connect 2 ,
277.Xr getpeername 2 ,
278.Xr getsockname 2 ,
279.Xr getsockopt 2 ,
280.Xr ioctl 2 ,
281.Xr listen 2 ,
282.Xr read 2 ,
283.Xr recv 2 ,
284.Xr select 2 ,
285.Xr send 2 ,
286.Xr shutdown 2 ,
287.Xr socketpair 2 ,
288.Xr write 2 ,
289.Xr getprotoent 3 ,
290.Xr netgraph 4 ,
291.Xr protocols 5
292.Rs
293.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
294.%B PS1
295.%N 7
296.Re
297.Rs
298.%T "BSD Interprocess Communication Tutorial"
299.%B PS1
300.%N 8
301.Re
302.Sh HISTORY
303The
304.Fn socket
305system call appeared in
306.Bx 4.2 .