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
42 .Fn socket "int domain" "int type" "int protocol"
47 creates an endpoint for communication and returns a descriptor.
51 argument specifies a communications domain within which
52 communication will take place; this selects the protocol family
54 These families are defined in the include file
56 The currently understood formats are:
58 .Bd -literal -offset indent -compact
59 PF_LOCAL Host-internal protocols (alias for PF_UNIX),
60 PF_UNIX Host-internal protocols,
61 PF_INET Internet version 4 protocols,
62 PF_INET6 Internet version 6 protocols,
63 PF_ROUTE Internal routing protocol,
64 PF_LINK Link layer interface,
65 PF_KEY Internal key-management function,
66 PF_NATM Asynchronous transfer mode protocols,
67 PF_NETGRAPH Netgraph sockets,
68 PF_IEEE80211 IEEE 802.11 wireless link-layer protocols (WiFi),
69 PF_BLUETOOTH Bluetooth protocols,
70 PF_INET_SDP OFED socket direct protocol (IPv4),
71 PF_INET6_SDP OFED socket direct protocol (IPv6)
74 Each protocol family is connected to an address family, which has the
75 same name except that the prefix is
79 Other protocol families may be also defined, beginning with
81 with corresponding address families.
83 The socket has the indicated
85 which specifies the semantics of communication.
89 .Bd -literal -offset indent -compact
90 SOCK_STREAM Stream socket,
91 SOCK_DGRAM Datagram socket,
92 SOCK_RAW Raw-protocol interface,
93 SOCK_RDM Reliably-delivered packet,
94 SOCK_SEQPACKET Sequenced packet stream
99 type provides sequenced, reliable,
100 two-way connection based byte streams.
101 An out-of-band data transmission mechanism may be supported.
105 datagrams (connectionless, unreliable messages of
106 a fixed (typically small) maximum length).
109 socket may provide a sequenced, reliable,
110 two-way connection-based data transmission path for datagrams
111 of fixed maximum length; a consumer may be required to read
112 an entire packet with each read system call.
113 This facility is protocol specific, and presently unimplemented.
115 sockets provide access to internal network protocols and interfaces.
118 which is available only to the super-user, and
121 but not yet implemented, are not described here.
123 Additionally, the following flags are allowed in the
127 .Bd -literal -offset indent -compact
128 SOCK_CLOEXEC Set close-on-exec on the new descriptor,
129 SOCK_NONBLOCK Set non-blocking mode on the new socket
135 specifies a particular protocol to be used with the socket.
136 Normally only a single protocol exists to support a particular
137 socket type within a given protocol family.
138 However, it is possible
139 that many protocols may exist, in which case a particular protocol
140 must be specified in this manner.
141 The protocol number to use is
143 .Dq "communication domain"
144 in which communication
145 is to take place; see
150 argument may be set to zero (0) to request the default
151 implementation of a socket type for the protocol, if any.
155 are full-duplex byte streams, similar
157 A stream socket must be in a
159 state before any data may be sent or received
161 A connection to another socket is created with a
164 Once connected, data may be transferred using
168 calls or some variant of the
173 (Some protocol families, such as the Internet family,
174 support the notion of an
175 .Dq implied connect ,
176 which permits data to be sent piggybacked onto a connect operation by
180 When a session has been completed a
183 Out-of-band data may also be transmitted as described in
185 and received as described in
188 The communications protocols used to implement a
191 is not lost or duplicated.
192 If a piece of data for which the
193 peer protocol has buffer space cannot be successfully transmitted
194 within a reasonable length of time, then
195 the connection is considered broken and calls
196 will indicate an error with
200 in the global variable
202 The protocols optionally keep sockets
204 by forcing transmissions
205 roughly every minute in the absence of other activity.
206 An error is then indicated if no response can be
207 elicited on an otherwise
208 idle connection for an extended period (e.g.\& 5 minutes).
211 signal is raised if a process sends
212 on a broken stream, but this behavior may be inhibited via
216 sockets employ the same system calls
223 calls will return only the amount of data requested,
224 and any remaining in the arriving packet will be discarded.
229 sockets allow sending of datagrams to correspondents
233 Datagrams are generally received with
235 which returns the next datagram with its return address.
239 system call can be used to specify a process group to receive
242 signal when the out-of-band data arrives.
243 It may also enable non-blocking I/O
244 and asynchronous notification of I/O events
248 The operation of sockets is controlled by socket level
250 These options are defined in the file
256 system calls are used to set and get options, respectively.
258 A -1 is returned if an error occurs, otherwise the return
259 value is a descriptor referencing the socket.
263 system call fails if:
266 Permission to create a socket of the specified type and/or protocol
268 .It Bq Er EAFNOSUPPORT
269 The address family (domain) is not supported or the
270 specified domain is not supported by this protocol family.
272 The per-process descriptor table is full.
274 The system file table is full.
276 Insufficient buffer space is available.
277 The socket cannot be created until sufficient resources are freed.
279 User has insufficient privileges to carry out the requested operation.
280 .It Bq Er EPROTONOSUPPORT
281 The protocol type or the specified protocol is not supported
284 The socket type is not supported by the protocol.
306 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
311 .%T "BSD Interprocess Communication Tutorial"
322 standard specifies only the
327 constants for address families, and requires the use of
335 flag is expected to conform to the next revision of the
343 constants, and other address families are
349 system call appeared in