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 .\" 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.
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
32 .\" From: @(#)socket.2 8.1 (Berkeley) 6/4/93
33 .\" $FreeBSD: src/lib/libc/sys/socket.2,v 1.12.2.11 2002/12/29 16:35:34 schweikh Exp $
40 .Nd create an endpoint for communication
47 .Fn socket "int domain" "int type" "int protocol"
50 creates an endpoint for communication and returns a descriptor.
54 parameter specifies a communications domain within which
55 communication will take place; this selects the protocol family
57 These families are defined in the include file
58 .Ao Pa sys/socket.h Ac .
59 The currently understood formats are:
61 .Bd -literal -offset indent -compact
62 PF_LOCAL Host-internal protocols, formerly called PF_UNIX,
63 PF_UNIX Host-internal protocols, deprecated, use PF_LOCAL,
64 PF_INET Internet version 4 protocols,
65 PF_IMPLINK ARPAnet IMP addresses,
66 PF_PUP PUP protocols, like BSP,
67 PF_CHAOS MIT CHAOS protocols,
68 PF_NS Xerox Network Systems protocols,
70 PF_OSI Open Systems Interconnection protocols,
71 PF_ECMA European Computer Manufacturers,
72 PF_DATAKIT Datakit protocols,
73 PF_CCITT ITU-T protocols, like X.25,
76 PF_DLI DEC Direct Data Link Interface protocol,
78 PF_HYLINK NSC Hyperchannel,
79 PF_APPLETALK AppleTalk protocols,
80 PF_ROUTE Internal Routing protocol,
81 PF_LINK Link layer interface,
82 PF_XTP eXpress Transfer Protocol,
83 PF_COIP Connection-Oriented IP, aka ST II,
84 PF_CNT Computer Network Technology,
85 PF_SIP Simple Internet Protocol,
86 PF_IPX Novell Internet Packet eXchange protocol,
87 PF_RTIP Help Identify RTIP packets,
88 PF_PIP Help Identify PIP packets,
89 PF_ISDN Integrated Services Digital Network,
90 PF_KEY Internal key-management function,
91 PF_INET6 Internet version 6 protocols,
92 PF_NATM Native ATM access,
94 PF_NETGRAPH Netgraph sockets
97 The socket has the indicated
99 which specifies the semantics of communication. Currently
102 .Bd -literal -offset indent -compact
103 SOCK_STREAM Stream socket,
104 SOCK_DGRAM Datagram socket,
105 SOCK_RAW Raw-protocol interface,
106 SOCK_RDM Reliably-delivered packet,
107 SOCK_SEQPACKET Sequenced packet stream
112 type provides sequenced, reliable,
113 two-way connection based byte streams.
114 An out-of-band data transmission mechanism may be supported.
118 datagrams (connectionless, unreliable messages of
119 a fixed (typically small) maximum length).
122 socket may provide a sequenced, reliable,
123 two-way connection-based data transmission path for datagrams
124 of fixed maximum length; a consumer may be required to read
125 an entire packet with each read system call.
126 This facility is protocol specific, and presently implemented
130 sockets provide access to internal network protocols and interfaces.
133 which is available only to the super-user, and
136 but not yet implemented, are not described here.
140 specifies a particular protocol to be used with the socket.
141 Normally only a single protocol exists to support a particular
142 socket type within a given protocol family. However, it is possible
143 that many protocols may exist, in which case a particular protocol
144 must be specified in this manner. The protocol number to use is
146 .Dq "communication domain"
147 in which communication
148 is to take place; see
153 are full-duplex byte streams, similar
154 to pipes. A stream socket must be in a
156 state before any data may be sent or received
157 on it. A connection to another socket is created with a
160 Once connected, data may be transferred using
164 calls or some variant of the
169 (Some protocol families, such as the Internet family,
170 support the notion of an
171 .Dq implied connect ,
172 which permits data to be sent piggybacked onto a connect operation by
176 When a session has been completed a
179 Out-of-band data may also be transmitted as described in
181 and received as described in
184 The communications protocols used to implement a
187 is not lost or duplicated. If a piece of data for which the
188 peer protocol has buffer space cannot be successfully transmitted
189 within a reasonable length of time, then
190 the connection is considered broken and calls
191 will indicate an error with
195 in the global variable
197 The protocols optionally keep sockets
199 by forcing transmissions
200 roughly every minute in the absence of other activity.
201 An error is then indicated if no response can be
202 elicited on an otherwise
203 idle connection for a extended period (e.g. 5 minutes).
206 signal is raised if a process sends
207 on a broken stream; this causes naive processes,
208 which do not handle the signal, to exit.
211 sockets employ the same system calls
214 sockets. The only difference
217 calls will return only the amount of data requested,
218 and any remaining in the arriving packet will be discarded.
223 sockets allow sending of datagrams to correspondents
226 calls. Datagrams are generally received with
228 which returns the next datagram with its return address.
232 call can be used to specify a process group to receive
235 signal when the out-of-band data arrives.
236 It may also enable non-blocking I/O
237 and asynchronous notification of I/O events
241 The operation of sockets is controlled by socket level
243 These options are defined in the file
244 .Ao Pa sys/socket.h Ac .
248 are used to set and get options, respectively.
250 A -1 is returned if an error occurs, otherwise the return
251 value is a descriptor referencing the socket.
257 .It Bq Er EPROTONOSUPPORT
258 The protocol type or the specified protocol is not supported
261 The per-process descriptor table is full.
263 The system file table is full.
265 Permission to create a socket of the specified type and/or protocol
268 Insufficient buffer space is available.
269 The socket cannot be created until sufficient resources are freed.
291 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
296 .%T "BSD Interprocess Communication Tutorial"
303 function call appeared in