/share/doc/psd/05.sysman/2.3.t

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