1 .\" Copyright (c) 1983, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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 .\" 4. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" From: @(#)socket.2 8.1 (Berkeley) 6/4/93
36 .Nd create an endpoint for communication
43 .Fn socket "int domain" "int type" "int protocol"
48 creates an endpoint for communication and returns a descriptor.
52 argument specifies a communications domain within which
53 communication will take place; this selects the protocol family
55 These families are defined in the include file
57 The currently understood formats are:
59 .Bd -literal -offset indent -compact
60 PF_LOCAL Host-internal protocols (alias for PF_UNIX),
61 PF_UNIX Host-internal protocols,
62 PF_INET Internet version 4 protocols,
63 PF_INET6 Internet version 6 protocols,
64 PF_ROUTE Internal routing protocol,
65 PF_LINK Link layer interface,
66 PF_KEY Internal key-management function,
67 PF_NATM Asynchronous transfer mode protocols,
68 PF_NETGRAPH Netgraph sockets,
69 PF_IEEE80211 IEEE 802.11 wireless link-layer protocols (WiFi),
70 PF_BLUETOOTH Bluetooth protocols,
71 PF_INET_SDP OFED socket direct protocol (IPv4),
72 PF_INET6_SDP OFED socket direct protocol (IPv6)
75 Each protocol family is connected to an address family, which has the
76 same name except that the prefix is
80 Other protocol families may be also defined, beginning with
82 with corresponding address families.
84 The socket has the indicated
86 which specifies the semantics of communication.
90 .Bd -literal -offset indent -compact
91 SOCK_STREAM Stream socket,
92 SOCK_DGRAM Datagram socket,
93 SOCK_RAW Raw-protocol interface,
94 SOCK_RDM Reliably-delivered packet,
95 SOCK_SEQPACKET Sequenced packet stream
100 type provides sequenced, reliable,
101 two-way connection based byte streams.
102 An out-of-band data transmission mechanism may be supported.
106 datagrams (connectionless, unreliable messages of
107 a fixed (typically small) maximum length).
110 socket may provide a sequenced, reliable,
111 two-way connection-based data transmission path for datagrams
112 of fixed maximum length; a consumer may be required to read
113 an entire packet with each read system call.
114 This facility is protocol specific, and presently unimplemented.
116 sockets provide access to internal network protocols and interfaces.
119 which is available only to the super-user, and
122 but not yet implemented, are not described here.
124 Additionally, the following flags are allowed in the
128 .Bd -literal -offset indent -compact
129 SOCK_CLOEXEC Set close-on-exec on the new descriptor,
130 SOCK_NONBLOCK Set non-blocking mode on the new socket
136 specifies a particular protocol to be used with the socket.
137 Normally only a single protocol exists to support a particular
138 socket type within a given protocol family.
139 However, it is possible
140 that many protocols may exist, in which case a particular protocol
141 must be specified in this manner.
142 The protocol number to use is
144 .Dq "communication domain"
145 in which communication
146 is to take place; see
151 argument may be set to zero (0) to request the default
152 implementation of a socket type for the protocol, if any.
156 are full-duplex byte streams, similar
158 A stream socket must be in a
160 state before any data may be sent or received
162 A connection to another socket is created with a
165 Once connected, data may be transferred using
169 calls or some variant of the
174 (Some protocol families, such as the Internet family,
175 support the notion of an
176 .Dq implied connect ,
177 which permits data to be sent piggybacked onto a connect operation by
181 When a session has been completed a
184 Out-of-band data may also be transmitted as described in
186 and received as described in
189 The communications protocols used to implement a
192 is not lost or duplicated.
193 If a piece of data for which the
194 peer protocol has buffer space cannot be successfully transmitted
195 within a reasonable length of time, then
196 the connection is considered broken and calls
197 will indicate an error with
201 in the global variable
203 The protocols optionally keep sockets
205 by forcing transmissions
206 roughly every minute in the absence of other activity.
207 An error is then indicated if no response can be
208 elicited on an otherwise
209 idle connection for an extended period (e.g.\& 5 minutes).
212 signal is raised if a process sends
213 on a broken stream, but this behavior may be inhibited via
217 sockets employ the same system calls
224 calls will return only the amount of data requested,
225 and any remaining in the arriving packet will be discarded.
230 sockets allow sending of datagrams to correspondents
234 Datagrams are generally received with
236 which returns the next datagram with its return address.
240 system call can be used to specify a process group to receive
243 signal when the out-of-band data arrives.
244 It may also enable non-blocking I/O
245 and asynchronous notification of I/O events
249 The operation of sockets is controlled by socket level
251 These options are defined in the file
257 system calls are used to set and get options, respectively.
259 A -1 is returned if an error occurs, otherwise the return
260 value is a descriptor referencing the socket.
264 system call fails if:
267 Permission to create a socket of the specified type and/or protocol
269 .It Bq Er EAFNOSUPPORT
270 The address family (domain) is not supported or the
271 specified domain is not supported by this protocol family.
273 The per-process descriptor table is full.
275 The system file table is full.
277 Insufficient buffer space is available.
278 The socket cannot be created until sufficient resources are freed.
280 User has insufficient privileges to carry out the requested operation.
281 .It Bq Er EPROTONOSUPPORT
282 The protocol type or the specified protocol is not supported
285 The socket type is not supported by the protocol.
307 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
312 .%T "BSD Interprocess Communication Tutorial"
323 standard specifies only the
328 constants for address families, and requires the use of
336 flag is expected to conform to the next revision of the
344 constants, and other address families are
350 system call appeared in