1 .\" Copyright (c) 1983, 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. 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 .sh "Interprocess communications
30 Interprocess communication primitives
34 The system provides access to an extensible set of
35 communication \fIdomains\fP. A communication domain
36 is identified by a manifest constant defined in the
37 file \fI<sys/socket.h>\fP.
38 Important standard domains supported by the system are the ``unix''
39 domain, AF_UNIX, for communication within the system, the ``Internet''
40 domain for communication in the DARPA Internet, AF_INET,
41 and the ``NS'' domain, AF_NS, for communication
42 using the Xerox Network Systems protocols.
43 Other domains can be added to the system.
45 Socket types and protocols
47 Within a domain, communication takes place between communication endpoints
48 known as \fIsockets\fP. Each socket has the potential to exchange
49 information with other sockets of an appropriate type within the domain.
51 Each socket has an associated
52 abstract type, which describes the semantics of communication using that
53 socket. Properties such as reliability, ordering, and prevention
54 of duplication of messages are determined by the type.
55 The basic set of socket types is defined in \fI<sys/socket.h>\fP:
57 /* Standard socket types */
59 #define SOCK_DGRAM 1 /* datagram */
60 #define SOCK_STREAM 2 /* virtual circuit */
61 #define SOCK_RAW 3 /* raw socket */
62 #define SOCK_RDM 4 /* reliably-delivered message */
63 #define SOCK_SEQPACKET 5 /* sequenced packets */
65 The SOCK_DGRAM type models the semantics of datagrams in network communication:
66 messages may be lost or duplicated and may arrive out-of-order.
67 A datagram socket may send messages to and receive messages from multiple
69 The SOCK_RDM type models the semantics of reliable datagrams: messages
70 arrive unduplicated and in-order, the sender is notified if
72 The \fIsend\fP and \fIreceive\fP operations (described below)
73 generate reliable/unreliable datagrams.
74 The SOCK_STREAM type models connection-based virtual circuits: two-way
75 byte streams with no record boundaries.
76 Connection setup is required before data communication may begin.
77 The SOCK_SEQPACKET type models a connection-based,
78 full-duplex, reliable, sequenced packet exchange;
79 the sender is notified if messages are lost, and messages are never
80 duplicated or presented out-of-order.
81 Users of the last two abstractions may use the facilities for
82 out-of-band transmission to send out-of-band data.
84 SOCK_RAW is used for unprocessed access to internal network layers
85 and interfaces; it has no specific semantics.
87 Other socket types can be defined.
89 Each socket may have a specific \fIprotocol\fP associated with it.
90 This protocol is used within the domain to provide the semantics
91 required by the socket type.
92 Not all socket types are supported by each domain;
93 support depends on the existence and the implementation
94 of a suitable protocol within the domain.
95 For example, within the ``Internet'' domain, the SOCK_DGRAM type may be
96 implemented by the UDP user datagram protocol, and the SOCK_STREAM
97 type may be implemented by the TCP transmission control protocol, while
98 no standard protocols to provide SOCK_RDM or SOCK_SEQPACKET sockets exist.
100 Socket creation, naming and service establishment
102 Sockets may be \fIconnected\fP or \fIunconnected\fP. An unconnected
103 socket descriptor is obtained by the \fIsocket\fP call:
105 s = socket(domain, type, protocol);
106 result int s; int domain, type, protocol;
108 The socket domain and type are as described above,
109 and are specified using the definitions from \fI<sys/socket.h>\fP.
110 The protocol may be given as 0, meaning any suitable protocol.
111 One of several possible protocols may be selected using identifiers
112 obtained from a library routine, \fIgetprotobyname\fP.
114 An unconnected socket descriptor of a connection-oriented type
115 may yield a connected socket descriptor
116 in one of two ways: either by actively connecting to another socket,
117 or by becoming associated with a name in the communications domain and
118 \fIaccepting\fP a connection from another socket.
119 Datagram sockets need not establish connections before use.
121 To accept connections or to receive datagrams,
122 a socket must first have a binding
123 to a name (or address) within the communications domain.
124 Such a binding may be established by a \fIbind\fP call:
126 bind(s, name, namelen);
127 int s; struct sockaddr *name; int namelen;
129 Datagram sockets may have default bindings established when first
130 sending data if not explicitly bound earlier.
132 a socket's bound name may be retrieved with a \fIgetsockname\fP call:
134 getsockname(s, name, namelen);
135 int s; result struct sockaddr *name; result int *namelen;
137 while the peer's name can be retrieved with \fIgetpeername\fP:
139 getpeername(s, name, namelen);
140 int s; result struct sockaddr *name; result int *namelen;
142 Domains may support sockets with several names.
144 Accepting connections
146 Once a binding is made to a connection-oriented socket,
147 it is possible to \fIlisten\fP for connections:
152 The \fIbacklog\fP specifies the maximum count of connections
153 that can be simultaneously queued awaiting acceptance.
155 An \fIaccept\fP call:
157 t = accept(s, name, anamelen);
158 result int t; int s; result struct sockaddr *name; result int *anamelen;
160 returns a descriptor for a new, connected, socket
161 from the queue of pending connections on \fIs\fP.
162 If no new connections are queued for acceptance,
163 the call will wait for a connection unless non-blocking I/O has been enabled.
167 An active connection to a named socket is made by the \fIconnect\fP call:
169 connect(s, name, namelen);
170 int s; struct sockaddr *name; int namelen;
172 Although datagram sockets do not establish connections,
173 the \fIconnect\fP call may be used with such sockets
174 to create an \fIassociation\fP with the foreign address.
175 The address is recorded for use in future \fIsend\fP calls,
176 which then need not supply destination addresses.
177 Datagrams will be received only from that peer,
178 and asynchronous error reports may be received.
180 It is also possible to create connected pairs of sockets without
181 using the domain's name space to rendezvous; this is done with the
182 \fIsocketpair\fP call\(dg:
184 \(dg 4.3BSD supports \fIsocketpair\fP creation only in the ``unix''
185 communication domain.
188 socketpair(domain, type, protocol, sv);
189 int domain, type, protocol; result int sv[2];
191 Here the returned \fIsv\fP descriptors correspond to those obtained with
192 \fIaccept\fP and \fIconnect\fP.
199 creates a pair of SOCK_STREAM sockets in the UNIX domain,
200 with pv[0] only writable and pv[1] only readable.
202 Sending and receiving data
204 Messages may be sent from a socket by:
206 cc = sendto(s, buf, len, flags, to, tolen);
207 result int cc; int s; caddr_t buf; int len, flags; caddr_t to; int tolen;
209 if the socket is not connected or:
211 cc = send(s, buf, len, flags);
212 result int cc; int s; caddr_t buf; int len, flags;
214 if the socket is connected.
215 The corresponding receive primitives are:
217 msglen = recvfrom(s, buf, len, flags, from, fromlenaddr);
218 result int msglen; int s; result caddr_t buf; int len, flags;
219 result caddr_t from; result int *fromlenaddr;
223 msglen = recv(s, buf, len, flags);
224 result int msglen; int s; result caddr_t buf; int len, flags;
227 In the unconnected case,
228 the parameters \fIto\fP and \fItolen\fP
229 specify the destination or source of the message, while
230 the \fIfrom\fP parameter stores the source of the message,
231 and \fI*fromlenaddr\fP initially gives the size of the \fIfrom\fP
232 buffer and is updated to reflect the true length of the \fIfrom\fP
235 All calls cause the message to be received in or sent from
236 the message buffer of length \fIlen\fP bytes, starting at address \fIbuf\fP.
237 The \fIflags\fP specify
238 peeking at a message without reading it or sending or receiving
239 high-priority out-of-band messages, as follows:
242 #define MSG_PEEK 0x1 /* peek at incoming message */
243 #define MSG_OOB 0x2 /* process out-of-band data */
246 Scatter/gather and exchanging access rights
248 It is possible scatter and gather data and to exchange access rights
249 with messages. When either of these operations is involved,
250 the number of parameters to the call becomes large.
251 Thus the system defines a message header structure, in \fI<sys/socket.h>\fP,
253 used to conveniently contain the parameters to the calls:
255 .if t .ta .5i 1.25i 2i 2.7i
258 caddr_t msg_name; /* optional address */
259 int msg_namelen; /* size of address */
260 struct iov *msg_iov; /* scatter/gather array */
261 int msg_iovlen; /* # elements in msg_iov */
262 caddr_t msg_accrights; /* access rights sent/received */
263 int msg_accrightslen; /* size of msg_accrights */
266 Here \fImsg_name\fP and \fImsg_namelen\fP specify the source or destination
267 address if the socket is unconnected; \fImsg_name\fP may be given as
268 a null pointer if no names are desired or required.
269 The \fImsg_iov\fP and \fImsg_iovlen\fP describe the scatter/gather
270 locations, as described in section 2.1.3.
271 Access rights to be sent along with the message are specified
272 in \fImsg_accrights\fP, which has length \fImsg_accrightslen\fP.
273 In the ``unix'' domain these are an array of integer descriptors,
274 taken from the sending process and duplicated in the receiver.
276 This structure is used in the operations \fIsendmsg\fP and \fIrecvmsg\fP:
278 sendmsg(s, msg, flags);
279 int s; struct msghdr *msg; int flags;
281 msglen = recvmsg(s, msg, flags);
282 result int msglen; int s; result struct msghdr *msg; int flags;
285 Using read and write with sockets
287 The normal UNIX \fIread\fP and \fIwrite\fP calls may be
288 applied to connected sockets and translated into \fIsend\fP and \fIreceive\fP
289 calls from or to a single area of memory and discarding any rights
290 received. A process may operate on a virtual circuit socket, a terminal
291 or a file with blocking or non-blocking input/output
292 operations without distinguishing the descriptor type.
294 Shutting down halves of full-duplex connections
296 A process that has a full-duplex socket such as a virtual circuit
297 and no longer wishes to read from or write to this socket can
300 shutdown(s, direction);
303 where \fIdirection\fP is 0 to not read further, 1 to not
304 write further, or 2 to completely shut the connection down.
305 If the underlying protocol supports unidirectional or bidirectional shutdown,
306 this indication will be passed to the peer.
307 For example, a shutdown for writing might produce an end-of-file
308 condition at the remote end.
310 Socket and protocol options
312 Sockets, and their underlying communication protocols, may
313 support \fIoptions\fP. These options may be used to manipulate
314 implementation- or protocol-specific facilities.
316 and \fIsetsockopt\fP calls are used to control options:
318 getsockopt(s, level, optname, optval, optlen)
319 int s, level, optname; result caddr_t optval; result int *optlen;
321 setsockopt(s, level, optname, optval, optlen)
322 int s, level, optname; caddr_t optval; int optlen;
324 The option \fIoptname\fP is interpreted at the indicated
325 protocol \fIlevel\fP for socket \fIs\fP. If a value is specified
326 with \fIoptval\fP and \fIoptlen\fP, it is interpreted by
327 the software operating at the specified \fIlevel\fP. The \fIlevel\fP
328 SOL_SOCKET is reserved to indicate options maintained
329 by the socket facilities. Other \fIlevel\fP values indicate
330 a particular protocol which is to act on the option request;
331 these values are normally interpreted as a ``protocol number''.
335 This section describes briefly the properties of the UNIX communications
341 the SOCK_STREAM abstraction provides pipe-like
342 facilities, while SOCK_DGRAM provides (usually)
343 reliable message-style communications.
347 Socket names are strings and may appear in the UNIX file
348 system name space through portals\(dg.
350 \(dg The 4.3BSD implementation of the UNIX domain embeds
351 bound sockets in the UNIX file system name space;
352 this may change in future releases.
355 Access rights transmission
357 The ability to pass UNIX descriptors with messages in this domain
358 allows migration of service within the system and allows
359 user processes to be used in building system facilities.
363 This section describes briefly how the Internet domain is
364 mapped to the model described in this section. More
365 information will be found in the document describing the
366 network implementation in 4.3BSD.
368 Socket types and protocols
370 SOCK_STREAM is supported by the Internet TCP protocol;
371 SOCK_DGRAM by the UDP protocol.
372 Each is layered atop the transport-level Internet Protocol (IP).
373 The Internet Control Message Protocol is implemented atop/beside IP
374 and is accessible via a raw socket.
376 has no direct Internet family analogue; a protocol
377 based on one from the XEROX NS family and layered on
378 top of IP could be implemented to fill this gap.
382 Sockets in the Internet domain have names composed of the 32 bit
383 Internet address, and a 16 bit port number.
384 Options may be used to
385 provide IP source routing or security options.
386 The 32-bit address is composed of network and host parts;
387 the network part is variable in size and is frequency encoded.
388 The host part may optionally be interpreted as a subnet field
389 plus the host on subnet; this is enabled by setting a network address
392 Access rights transmission
394 No access rights transmission facilities are provided in the Internet domain.
398 The Internet domain allows the super-user access to the raw facilities
400 These interfaces are modeled as SOCK_RAW sockets.
401 Each raw socket is associated with one IP protocol number,
402 and receives all traffic received for that protocol.
403 This allows administrative and debugging
405 and enables user-level implementations of special-purpose protocols
406 such as inter-gateway routing protocols.