updates for 4.3 from lapsley

[unix-history] / usr / src / share / doc / psd / 21.ipc / 2.t

diff --git a/usr/src/share/doc/psd/21.ipc/2.t b/usr/src/share/doc/psd/21.ipc/2.t
index 8f430df..297314a 100644 (file)
--- a/usr/src/share/doc/psd/21.ipc/2.t
+++ b/usr/src/share/doc/psd/21.ipc/2.t
@@ -1,3 +1,9 @@
+.\" Copyright (c) 1986 Regents of the University of California.
+.\" All rights reserved.  The Berkeley software License Agreement
+.\" specifies the terms and conditions for redistribution.
+.\"
+.\"    @(#)2.t 1.2 (Berkeley) %G%
+.\"

 .ds RH "Basics
 .bp
 .nr H1 2
 .ds RH "Basics
 .bp
 .nr H1 2


@@ -27,17 +33,26 @@ exchange data only with
 sockets in the same domain (it may be possible to cross domain
 boundaries, but only if some translation process is
 performed).  The
 sockets in the same domain (it may be possible to cross domain
 boundaries, but only if some translation process is
 performed).  The

-4.2BSD ipc supports two separate communication domains:
-the UNIX domain, and the Internet domain is used by
+4.3BSD IPC facilities support three separate communication domains:
+the UNIX domain, for on-system communication;
+the Internet domain, which is used by

 processes which communicate
 processes which communicate

-using the the DARPA standard communication protocols. 
+using the the DARPA standard communication protocols;
+and the NS domain, which is used by processes which
+communicate using the Xerox standard communication
+protocols*.
+.FS
+* See \fIInternet Transport Protocols\fP, Xerox System Integration
+Standard (XSIS)028112 for more information.  This document is
+almost a necessity for one trying to write NS applications.
+.FE

 The underlying communication
 facilities provided by these domains have a significant influence
 on the internal system implementation as well as the interface to
 socket facilities available to a user.  An example of the
 latter is that a socket \*(lqoperating\*(rq in the UNIX domain
 The underlying communication
 facilities provided by these domains have a significant influence
 on the internal system implementation as well as the interface to
 socket facilities available to a user.  An example of the
 latter is that a socket \*(lqoperating\*(rq in the UNIX domain

-sees a subset of the possible error conditions which are possible
-when operating in the Internet domain.
+sees a subset of the error conditions which are possible
+when operating in the Internet (or NS) domain.

 .NH 2
 Socket types
 .PP
 .NH 2
 Socket types
 .PP


@@ -50,13 +65,13 @@ nothing that prevents communication between sockets of different
 types should the underlying communication
 protocols support this.
 .PP
 types should the underlying communication
 protocols support this.
 .PP

-Three types of sockets currently are available to a user.
+Four types of sockets currently are available to a user.

 A \fIstream\fP socket provides for the bidirectional, reliable,
 sequenced, and unduplicated flow of data without record boundaries.
 Aside from the bidirectionality of data flow, a pair of connected
 A \fIstream\fP socket provides for the bidirectional, reliable,
 sequenced, and unduplicated flow of data without record boundaries.
 Aside from the bidirectionality of data flow, a pair of connected

-stream sockets provides an interface nearly identical to that of pipes*.
+stream sockets provides an interface nearly identical to that of pipes\(dg.

 .FS
 .FS

-* In the UNIX domain, in fact, the semantics are identical and,
+\(dg In the UNIX domain, in fact, the semantics are identical and,

 as one might expect, pipes have been implemented internally
 as simply a pair of connected stream sockets.
 .FE
 as one might expect, pipes have been implemented internally
 as simply a pair of connected stream sockets.
 .FE


@@ -83,18 +98,28 @@ communication protocols, or for gaining access to some of the more
 esoteric facilities of an existing protocol.  The use of raw sockets
 is considered in section 5.
 .PP
 esoteric facilities of an existing protocol.  The use of raw sockets
 is considered in section 5.
 .PP

-Two potential socket types which have interesting properties are
-the \fIsequenced packet\fP socket and the \fIreliably delivered
-message\fP socket.  A sequenced packet socket is identical to
-a stream socket
-with the exception that record boundaries are preserved.  This interface
-is very similar to that provided by the Xerox NS Sequenced Packet protocol.
+A \fIsequenced packet\fP socket is similar to a stream socket,
+with the exception that record boundaries are preserved.  This 
+interface is provided only as part of the NS socket abstraction,
+and is very important in most serious NS applications.
+Sequenced-packet sockets allow the user to manipulate the
+SPP or IDP headers on a packet or a group of packets either
+by writing a prototype header along with whatever data is
+to be sent, or by specifying a default header to be used with
+all outgoing data, and allows the user to receive the headers
+on incoming packets.  The use of these options is considered in
+section 5.
+.PP
+Another potential socket type which has interesting properties is
+the \fIreliably delivered
+message\fP socket.

 The reliably delivered message socket has
 similar properties to a datagram socket, but with
 The reliably delivered message socket has
 similar properties to a datagram socket, but with

-reliable delivery.  While these two socket types have been loosely defined,
-they are currently unimplemented in 4.2BSD.  As such, in this
-document we will concern ourselves
-only with the three socket types for which support exists.
+reliable delivery.  There is currently no support for this
+type of socket, but a reliably delivered message protocol
+similar to Xerox's Packet Exchange Protocol (PEX) may be
+simulated at the user level.  More information on this topic
+can be found in section 5.

 .NH 2
 Socket creation
 .PP
 .NH 2
 Socket creation
 .PP


@@ -116,8 +141,10 @@ For the UNIX domain the constant is AF_UNIX*;  for the Internet
 * The manifest constants are named AF_whatever as they indicate
 the ``address format'' to use in interpreting names.
 .FE
 * The manifest constants are named AF_whatever as they indicate
 the ``address format'' to use in interpreting names.
 .FE

-domain AF_INET.  The socket types are also defined in this file
-and one of SOCK_STREAM, SOCK_DGRAM, or SOCK_RAW must be specified.
+domain AF_INET; and for the NS domain, AF_NS.  
+The socket types are also defined in this file
+and one of SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, or SOCK_SEQPACKET
+must be specified.

 To create a stream socket in the Internet domain the following
 call might be used:
 .DS
 To create a stream socket in the Internet domain the following
 call might be used:
 .DS


@@ -125,26 +152,17 @@ s = socket(AF_INET, SOCK_STREAM, 0);
 .DE
 This call would result in a stream socket being created with the TCP
 protocol providing the underlying communication support.  To
 .DE
 This call would result in a stream socket being created with the TCP
 protocol providing the underlying communication support.  To

-create a datagram socket for on-machine use a sample call might
+create a datagram socket for on-machine use the call might

 be:
 .DS
 s = socket(AF_UNIX, SOCK_DGRAM, 0);
 .DE
 .PP
 be:
 .DS
 s = socket(AF_UNIX, SOCK_DGRAM, 0);
 .DE
 .PP

-To obtain a particular protocol one selects the protocol number,
-as defined within the communication domain.  For the Internet
-domain the available protocols are defined in <\fInetinet/in.h\fP>
-or, better yet, one may use one of the library routines
-discussed in section 3, such as  \fIgetprotobyname\fP:
-.DS
-#include <sys/types.h>
-#include <sys/socket.h>
-#include <netinet/in.h>
-#include <netdb.h>
- ...
-pp = getprotobyname("tcp");
-s = socket(AF_INET, SOCK_STREAM, pp->p_proto);
-.DE
+The default protocol (used when the \fIprotocol\fP argument to the
+\fIsocket\fP call is 0) should be correct for most every
+situation.  However, it is possible to specify a protocol
+other than the default; this will be covered in
+section 5.

 .PP
 There are several reasons a socket call may fail.  Aside from
 the rare occurrence of lack of memory (ENOBUFS), a socket
 .PP
 There are several reasons a socket call may fail.  Aside from
 the rare occurrence of lack of memory (ENOBUFS), a socket


@@ -152,41 +170,117 @@ request may fail due to a request for an unknown protocol
 (EPROTONOSUPPORT), or a request for a type of socket for
 which there is no supporting protocol (EPROTOTYPE). 
 .NH 2
 (EPROTONOSUPPORT), or a request for a type of socket for
 which there is no supporting protocol (EPROTOTYPE). 
 .NH 2

-Binding names
+Binding local names

 .PP
 A socket is created without a name.  Until a name is bound
 to a socket, processes have no way to reference it and, consequently,
 .PP
 A socket is created without a name.  Until a name is bound
 to a socket, processes have no way to reference it and, consequently,

-no messages may be received on it.  The \fIbind\fP call is used to
-assign a name to a socket:
+no messages may be received on it.
+Communicating processes are bound
+by an \fIassociation\fP.  In the Internet and NS domains,
+an association 
+is composed of local and foreign
+addresses, and local and foreign ports,
+while in the UNIX domain, an association is composed of
+local and foreign path names (the phrase ``foreign pathname''
+means a pathname created by a foreign process, not a pathname
+on a foreign system).
+Associations are always unique.  That is, in the Internet domain, there
+may never be duplicate <protocol, local address, local port, foreign
+address, foreign port> tuples.  Similarly, in the UNIX domain,
+there may never be duplicate <protocol, local pathname, foreign
+pathname> tuples, and the pathnames must (in 4.3; the situation
+may change in future releases) be unique with respect to the files
+already existing on the system.
+.PP
+The \fIbind\fP system call allows a process to specify half of
+an association, <local address, local port>
+(or <local pathname>), while the \fIconnect\fP
+and \fIaccept\fP primitives are used to complete a socket's association.
+.PP
+In the Internet domain,
+binding names to sockets can be fairly complex.
+Fortunately, it is usually not necessary to specifically bind an
+address and port number to a socket, because the
+\fIconnect\fP and \fIsend\fP calls will automatically
+bind an appropriate address if they are used with an
+unbound socket.  The process of binding names to NS
+sockets is similar in most ways to that of
+binding names to Internet sockets.
+While binding names to sockets in the
+UNIX domain is less complex, the \fIconnect\fP and \fIsend\fP
+calls can still be used to automatically bind local names.
+.PP
+The \fIbind\fP system call is used as follows:

 .DS
 bind(s, name, namelen);
 .DE
 The bound name is a variable length byte string which is interpreted
 by the supporting protocol(s).  Its interpretation may vary from
 communication domain to communication domain (this is one of
 .DS
 bind(s, name, namelen);
 .DE
 The bound name is a variable length byte string which is interpreted
 by the supporting protocol(s).  Its interpretation may vary from
 communication domain to communication domain (this is one of

-the properties which comprise the \*(lqdomain\*(rq).  In the
-UNIX domain names are path names while in the Internet domain
-names contain an Internet address and port number.
-If one wanted to bind the name \*(lq/dev/foo\*(rq to
-a UNIX domain socket, the following would be used:
+the properties which comprise the \*(lqdomain\*(rq).
+As mentioned, in the
+Internet domain names contain an Internet address and port
+number.  NS domain names contain a NS address and
+port number.  In the UNIX domain, names contain a path name and
+a family, which is always AF_UNIX.  If one wanted to bind
+the name \*(lq/tmp/foo\*(rq to a UNIX domain socket, the
+following code would be used*:
+.FS
+* Note that, although the tendency here is to call the \*(lqaddr\*(rq
+structure \*(lqsun\*(rq, doing so would cause problems if the code
+were ever ported to a Sun workstation.
+.FE

 .DS
 .DS

-bind(s, "/dev/foo", sizeof ("/dev/foo") \- 1);
+#include <sys/un.h>
+ ...
+struct sockaddr_un addr;
+ ...
+strcpy(addr.sun_path, "/tmp/foo");
+addr.sun_family = AF_UNIX;
+bind(s, (struct sockaddr *) &addr, strlen(addr.sun_path) +
+    sizeof (addr.sun_family));

 .DE
 .DE

-(Note how the null byte in the name is not counted as part of
-the name.)  In binding an Internet address things become more
-complicated.  The actual call is simple,
+Note that in determining the size of a UNIX domain address null
+bytes are not counted, which is why \fIstrlen\fP is used.  In
+the current implementation of UNIX domain IPC under 4.3BSD,
+the file name
+referred to in \fIaddr.sun_path\fP is created as a socket
+in the system file space.
+The caller must, therefore, have
+write permission in the directory where
+\fIaddr.sun_path\fP is to reside, and this file should be deleted by the
+caller when it is no longer needed.  Future versions of 4BSD
+may not create this file.
+.PP
+In binding an Internet address things become more
+complicated.  The actual call is similar,

 .DS
 #include <sys/types.h>
 #include <netinet/in.h>
  ...
 struct sockaddr_in sin;
  ...
 .DS
 #include <sys/types.h>
 #include <netinet/in.h>
  ...
 struct sockaddr_in sin;
  ...

-bind(s, &sin, sizeof (sin));
+bind(s, (struct sockaddr *) &sin, sizeof (sin));

 .DE
 but the selection of what to place in the address \fIsin\fP
 requires some discussion.  We will come back to the problem
 of formulating Internet addresses in section 3 when 
 the library routines used in name resolution are discussed.
 .DE
 but the selection of what to place in the address \fIsin\fP
 requires some discussion.  We will come back to the problem
 of formulating Internet addresses in section 3 when 
 the library routines used in name resolution are discussed.

+.PP
+Binding a NS address to a socket is even more
+difficult,
+especially since the Internet library routines do not
+work with NS hostnames.  The actual call is again similar:
+.DS
+#include <sys/types.h>
+#include <netns/ns.h>
+ ...
+struct sockaddr_ns sns;
+ ...
+bind(s, (struct sockaddr *) &sns, sizeof (sns));
+.DE
+Again, discussion of what to place in a \*(lqstruct sockaddr_ns\*(rq
+will be deferred to section 3.

 .NH 2
 Connection establishment
 .PP
 .NH 2
 Connection establishment
 .PP


@@ -200,24 +294,39 @@ on its socket.  On the client side the \fIconnect\fP call is
 used to initiate a connection.  Using the UNIX domain, this
 might appear as,
 .DS
 used to initiate a connection.  Using the UNIX domain, this
 might appear as,
 .DS

-connect(s, "server-name", sizeof ("server-name"));
+struct sockaddr_un server;
+ ...
+connect(s, (struct sockaddr *)&server, strlen(server.sun_path) +
+    sizeof (server.sun_family));

 .DE
 while in the Internet domain,
 .DS
 struct sockaddr_in server;
 .DE
 while in the Internet domain,
 .DS
 struct sockaddr_in server;

-connect(s, &server, sizeof (server));
+ ...
+connect(s, (struct sockaddr *)&server, sizeof (server));
+.DE
+and in the NS domain,
+.DS
+struct sockaddr_ns server;
+ ...
+connect(s, (struct sockaddr *)&server, sizeof (server));

 .DE
 .DE

+where \fIserver\fP in the example above would contain either the UNIX
+pathname, Internet address and port number, or NS address and
+port number of the server to which the
+client process wishes to speak.

 If the client process's socket is unbound at the time of
 the connect call,
 the system will automatically select and bind a name to
 the socket; c.f. section 5.4.
 If the client process's socket is unbound at the time of
 the connect call,
 the system will automatically select and bind a name to
 the socket; c.f. section 5.4.

-An error is returned when the connection was unsuccessful
+This is the usual way that local addresses are bound
+to a socket.
+.PP
+An error is returned if the connection was unsuccessful

 (any name automatically bound by the system, however, remains).
 Otherwise, the socket is associated with the server and
 (any name automatically bound by the system, however, remains).
 Otherwise, the socket is associated with the server and

-data transfer may begin.
-.PP
-Many errors can be returned when a connection attempt
-fails.  The most common are:
+data transfer may begin.  Some of the more common errors returned
+when a connection attempt fails are:

 .IP ETIMEDOUT
 .br
 After failing to establish a connection for a period of time,
 .IP ETIMEDOUT
 .br
 After failing to establish a connection for a period of time,


@@ -227,8 +336,8 @@ the destination host is down, or because problems in
 the network resulted in transmissions being lost.
 .IP ECONNREFUSED
 .br
 the network resulted in transmissions being lost.
 .IP ECONNREFUSED
 .br

-The host refused service for some reason.  When connecting
-to a host running 4.2BSD this is usually
+The host refused service for some reason.
+This is usually

 due to a server process
 not being present at the requested name.
 .IP "ENETDOWN or EHOSTDOWN"
 due to a server process
 not being present at the requested name.
 .IP "ENETDOWN or EHOSTDOWN"


@@ -243,7 +352,7 @@ or host is unknown (no route to the network or host is present),
 or because of status information returned by intermediate
 gateways or switching nodes.  Many times the status returned
 is not sufficient to distinguish a network being down from a
 or because of status information returned by intermediate
 gateways or switching nodes.  Many times the status returned
 is not sufficient to distinguish a network being down from a

-host being down.  In these cases the system is conservative and
+host being down, in which case the system

 indicates the entire network is unreachable.
 .PP
 For the server to receive a client's connection it must perform
 indicates the entire network is unreachable.
 .PP
 For the server to receive a client's connection it must perform


@@ -255,7 +364,8 @@ listen(s, 5);
 .DE
 The second parameter to the \fIlisten\fP call specifies the maximum
 number of outstanding connections which may be queued awaiting 
 .DE
 The second parameter to the \fIlisten\fP call specifies the maximum
 number of outstanding connections which may be queued awaiting 

-acceptance by the server process.  Should a connection be
+acceptance by the server process; this number
+may be limited by the system.  Should a connection be

 requested while the queue is full, the connection will not be
 refused, but rather the individual messages which comprise the
 request will be ignored.  This gives a harried server time to 
 requested while the queue is full, the connection will not be
 refused, but rather the individual messages which comprise the
 request will be ignored.  This gives a harried server time to 


@@ -264,7 +374,7 @@ retries the connection request.  Had the connection been returned
 with the ECONNREFUSED error, the client would be unable to tell
 if the server was up or not.  As it is now it is still possible
 to get the ETIMEDOUT error back, though this is unlikely.  The
 with the ECONNREFUSED error, the client would be unable to tell
 if the server was up or not.  As it is now it is still possible
 to get the ETIMEDOUT error back, though this is unlikely.  The

-backlog figure supplied with the listen call is limited
+backlog figure supplied with the listen call is currently limited

 by the system to a maximum of 5 pending connections on any
 one queue.  This avoids the problem of processes hogging system
 resources by setting an infinite backlog, then ignoring
 by the system to a maximum of 5 pending connections on any
 one queue.  This avoids the problem of processes hogging system
 resources by setting an infinite backlog, then ignoring


@@ -273,18 +383,26 @@ all connection requests.
 With a socket marked as listening, a server may \fIaccept\fP
 a connection:
 .DS
 With a socket marked as listening, a server may \fIaccept\fP
 a connection:
 .DS

+struct sockaddr_in from;
+ ...

 fromlen = sizeof (from);
 fromlen = sizeof (from);

-snew = accept(s, &from, &fromlen);
+newsock = accept(s, (struct sockaddr *)&from, &fromlen);

 .DE
 .DE

-A new descriptor is returned on receipt of a connection (along with
+(For the UNIX domain, \fIfrom\fP would be declared as a
+\fIstruct sockaddr_un\fP, and for the NS domain, \fIfrom\fP
+would be declared as a \fIstruct sockaddr_ns\fP,
+but nothing different would need
+to be done as far as \fIfromlen\fP is concerned.  In the examples
+which follow, only Internet routines will be discussed.)  A new
+descriptor is returned on receipt of a connection (along with

 a new socket).  If the server wishes to find out who its client is,
 it may supply a buffer for the client socket's name.  The value-result
 parameter \fIfromlen\fP is initialized by the server to indicate how
 much space is associated with \fIfrom\fP, then modified on return
 to reflect the true size of the name.  If the client's name is not
 a new socket).  If the server wishes to find out who its client is,
 it may supply a buffer for the client socket's name.  The value-result
 parameter \fIfromlen\fP is initialized by the server to indicate how
 much space is associated with \fIfrom\fP, then modified on return
 to reflect the true size of the name.  If the client's name is not

-of interest, the second parameter may be zero.
+of interest, the second parameter may be a null pointer.

 .PP
 .PP

-Accept normally blocks.  That is, the call to accept
+\fIAccept\fP normally blocks.  That is, \fIaccept\fP

 will not return until a connection is available or the system call
 is interrupted by a signal to the process.  Further, there is no
 way for a process to indicate it will accept connections from only
 will not return until a connection is available or the system call
 is interrupted by a signal to the process.  Further, there is no
 way for a process to indicate it will accept connections from only


@@ -292,7 +410,7 @@ a specific individual, or individuals.  It is up to the user process
 to consider who the connection is from and close down the connection
 if it does not wish to speak to the process.  If the server process
 wants to accept connections on more than one socket, or not block
 to consider who the connection is from and close down the connection
 if it does not wish to speak to the process.  If the server process
 wants to accept connections on more than one socket, or not block

-on the accept call there are alternatives;  they will be considered
+on the accept call, there are alternatives;  they will be considered

 in section 5.
 .NH 2
 Data transfer
 in section 5.
 .NH 2
 Data transfer


@@ -302,7 +420,7 @@ and receive data there are a number of possible calls.
 With the peer entity at each end of a connection
 anchored, a user can send or receive a message without specifying
 the peer.  As one might expect, in this case, then
 With the peer entity at each end of a connection
 anchored, a user can send or receive a message without specifying
 the peer.  As one might expect, in this case, then

-the normal \fIread\fP and \fIwrite\fP system calls are useable,
+the normal \fIread\fP and \fIwrite\fP system calls are usable,

 .DS
 write(s, buf, sizeof (buf));
 read(s, buf, sizeof (buf));
 .DS
 write(s, buf, sizeof (buf));
 read(s, buf, sizeof (buf));


@@ -316,15 +434,16 @@ recv(s, buf, sizeof (buf), flags);
 .DE
 While \fIsend\fP and \fIrecv\fP are virtually identical to
 \fIread\fP and \fIwrite\fP,
 .DE
 While \fIsend\fP and \fIrecv\fP are virtually identical to
 \fIread\fP and \fIwrite\fP,

-the extra \fIflags\fP argument is important.  The flags may be
+the extra \fIflags\fP argument is important.  The flags,
+defined in \fI<sys/socket.h>\fP, may be

 specified as a non-zero value if one or more
 of the following is required:
 .DS
 .TS
 l l.
 specified as a non-zero value if one or more
 of the following is required:
 .DS
 .TS
 l l.

-SOF_OOB        send/receive out of band data
-SOF_PREVIEW    look at data without reading
-SOF_DONTROUTE  send data without routing packets
+MSG_OOB        send/receive out of band data
+MSG_PEEK       look at data without reading
+MSG_DONTROUTE  send data without routing packets

 .TE
 .DE
 Out of band data is a notion specific to stream sockets, and one
 .TE
 .DE
 Out of band data is a notion specific to stream sockets, and one


@@ -332,7 +451,7 @@ which we will not immediately consider.  The option to have data
 sent without routing applied to the outgoing packets is currently 
 used only by the routing table management process, and is
 unlikely to be of interest to the casual user.  The ability
 sent without routing applied to the outgoing packets is currently 
 used only by the routing table management process, and is
 unlikely to be of interest to the casual user.  The ability

-to preview data is, however, of interest.  When SOF_PREVIEW
+to preview data is, however, of interest.  When MSG_PEEK

 is specified with a \fIrecv\fP call, any data present is returned
 to the user, but treated as still \*(lqunread\*(rq.  That
 is, the next \fIread\fP or \fIrecv\fP call applied to the socket will
 is specified with a \fIrecv\fP call, any data present is returned
 to the user, but treated as still \*(lqunread\*(rq.  That
 is, the next \fIread\fP or \fIrecv\fP call applied to the socket will


@@ -358,8 +477,7 @@ shutdown(s, how);
 .DE
 where \fIhow\fP is 0 if the user is no longer interested in reading
 data, 1 if no more data will be sent, or 2 if no data is to
 .DE
 where \fIhow\fP is 0 if the user is no longer interested in reading
 data, 1 if no more data will be sent, or 2 if no data is to

-be sent or received.  Applying shutdown to a socket causes
-any data queued to be immediately discarded.
+be sent or received.

 .NH 2
 Connectionless sockets
 .PP
 .NH 2
 Connectionless sockets
 .PP


@@ -377,13 +495,14 @@ have a name bound to it in order that the recipient of
 a message may identify the sender.  To send data,
 the \fIsendto\fP primitive is used,
 .DS
 a message may identify the sender.  To send data,
 the \fIsendto\fP primitive is used,
 .DS

-sendto(s, buf, buflen, flags, &to, tolen);
+sendto(s, buf, buflen, flags, (struct sockaddr *)&to, tolen);

 .DE
 The \fIs\fP, \fIbuf\fP, \fIbuflen\fP, and \fIflags\fP
 parameters are used as before. 
 The \fIto\fP and \fItolen\fP
 values are used to indicate the intended recipient of the
 .DE
 The \fIs\fP, \fIbuf\fP, \fIbuflen\fP, and \fIflags\fP
 parameters are used as before. 
 The \fIto\fP and \fItolen\fP
 values are used to indicate the intended recipient of the

-message.  When using an unreliable datagram interface, it is
+message.  When
+using an unreliable datagram interface, it is

 unlikely any errors will be reported to the sender.  Where
 information is present locally to recognize a message which may
 never be delivered (for instance when a network is unreachable),
 unlikely any errors will be reported to the sender.  Where
 information is present locally to recognize a message which may
 never be delivered (for instance when a network is unreachable),


@@ -393,15 +512,16 @@ contain an error number.
 To receive messages on an unconnected datagram socket, the
 \fIrecvfrom\fP primitive is provided:
 .DS
 To receive messages on an unconnected datagram socket, the
 \fIrecvfrom\fP primitive is provided:
 .DS

-recvfrom(s, buf, buflen, flags, &from, &fromlen);
+recvfrom(s, buf, buflen, flags, (struct sockaddr *)&from, &fromlen);

 .DE
 Once again, the \fIfromlen\fP parameter is handled in
 a value-result fashion, initially containing the size of
 .DE
 Once again, the \fIfromlen\fP parameter is handled in
 a value-result fashion, initially containing the size of

-the \fIfrom\fP buffer.
+the \fIfrom\fP buffer, and modified on return to indicate
+the actual size of the from address.

 .PP
 In addition to the two calls mentioned above, datagram
 sockets may also use the \fIconnect\fP call to associate
 .PP
 In addition to the two calls mentioned above, datagram
 sockets may also use the \fIconnect\fP call to associate

-a socket with a specific address.  In this case, any
+a socket with a specific destination address.  In this case, any

 data sent on the socket will automatically be addressed
 to the connected peer, and only data received from that
 peer will be delivered to the user.  Only one connected
 data sent on the socket will automatically be addressed
 to the connected peer, and only data received from that
 peer will be delivered to the user.  Only one connected


@@ -410,7 +530,8 @@ Connect requests on datagram sockets return immediately,
 as this simply results in the system recording
 the peer's address (as compared to a stream socket where a
 connect request initiates establishment of an end to end
 as this simply results in the system recording
 the peer's address (as compared to a stream socket where a
 connect request initiates establishment of an end to end

-connection).
+connection).  \fIAccept\fP and \fIlisten\fP are not
+used with datagram sockets.

 Other of the less
 important details of datagram sockets are described
 in section 5.
 Other of the less
 important details of datagram sockets are described
 in section 5.


@@ -422,24 +543,56 @@ is the ability to multiplex i/o requests among multiple
 sockets and/or files.  This is done using the \fIselect\fP
 call:
 .DS
 sockets and/or files.  This is done using the \fIselect\fP
 call:
 .DS

-select(nfds, &readfds, &writefds, &execptfds, &timeout);
+#define FD_SETSIZE     128   /* How many file descriptors we're interested in */
+ ...
+#include <sys/time.h>
+#include <sys/types.h>
+ ...
+
+fd_set readmask, writemask, exceptmask;
+struct timeval timeout;
+ ...
+select(nfds, &readmask, &writemask, &exceptmask, &timeout);

 .DE
 .DE

-\fISelect\fP takes as arguments three bit masks, one for
+\fISelect\fP takes as arguments pointers to three sets, one for

 the set of file descriptors for which the caller wishes to
 be able to read data on, one for those descriptors to which
 data is to be written, and one for which exceptional conditions
 the set of file descriptors for which the caller wishes to
 be able to read data on, one for those descriptors to which
 data is to be written, and one for which exceptional conditions

-are pending.  
-Bit masks are created
-by or-ing bits of the form \*(lq1 << fd\*(rq.  That is,
-a descriptor \fIfd\fP is selected if a 1 is present in
-the \fIfd\fP'th bit of the mask.
-The parameter \fInfds\fP specifies the range
+are pending; out-of-band data is the only
+exceptional condition currently implemented by the socket
+abstraction.
+If it is known that the
+that the maximum number of open file descriptors will be less than
+a given value,
+then this number should be used as the definition of FD_SETSIZE
+(which must be done before \fI<sys/types>\fP is included).
+Otherwise, it is acceptable to let FD_SETSIZE default to the
+value specified in \fI<sys/types.h>\fP.
+.PP
+Each set is actually a structure containing an array of
+long integers; the length of the array is implicitly set
+by the definition of FD_SETSIZE, and the array will be
+long enough to hold one bit for each of FD_SETSIZE file descriptors.
+If the user is not interested
+in certain conditions (i.e., read, write, or exceptions),
+the corresponding argument to the \fIselect\fP should
+be a null pointer.
+.PP
+The macros \fIFD_SET(fd, &mask)\fP and
+\fIFD_CLR(fd, &mask)\fP
+have been provided for adding and removing file descriptor
+\fIfd\fP in the set \fImask\fP.  The
+set should be zeroed before use, and
+the macro \fIFD_ZERO(&mask)\fP has been provided
+to clear the set \fImask\fP.
+The parameter \fInfds\fP in the \fIselect\fP call specifies the range

 of file descriptors  (i.e. one plus the value of the largest
 of file descriptors  (i.e. one plus the value of the largest

-descriptor) specified in a mask. 
+descriptor) specified in a set. 

 .PP
 A timeout value may be specified if the selection
 is not to last more than a predetermined period of time.  If
 .PP
 A timeout value may be specified if the selection
 is not to last more than a predetermined period of time.  If

-\fItimeout\fP is set to 0, the selection takes the form of a
+the fields in \fItimeout\fP are set to 0, the selection takes
+the form of a

 \fIpoll\fP, returning immediately.  If the last parameter is
 a null pointer, the selection will block indefinitely*.
 .FS
 \fIpoll\fP, returning immediately.  If the last parameter is
 a null pointer, the selection will block indefinitely*.
 .FS


@@ -447,9 +600,71 @@ a null pointer, the selection will block indefinitely*.
 descriptor is selectable, or when a signal is received by
 the caller, interrupting the system call.
 .FE
 descriptor is selectable, or when a signal is received by
 the caller, interrupting the system call.
 .FE

-\fISelect\fP normally returns the number of file descriptors selected.
-If the \fIselect\fP call returns due to the timeout expiring, then
-a value of \-1 is returned along with the error number EINTR.
+\fISelect\fP normally returns the number of file descriptors selected;
+if the \fIselect\fP call returns due to the timeout expiring, then
+the value 0 is returned.
+If the \fIselect\fP terminates because of an error, a \-1 is returned
+with the error number in \fIerrno\fP.
+.PP
+Assuming a successful return, the three sets will
+indicate which
+file descriptors are ready to be read from, written to, or
+have exceptional conditions pending.
+The status of a file descriptor in a select mask may be
+tested with the \fIFD_ISSET(fd, &mask)\fP macro, which
+returns a non-zero value if \fIfd\fP is a member of the set
+\fImask\fP, and 0 if it is not.
+.PP
+To determine if there are connections waiting 
+on a socket to be used with an \fIaccept\fP call,
+\fIselect\fP can be used, followed by
+a \fIFD_ISSET(fd, &mask)\fP macro to check for read
+readiness on the appropriate socket.  If \fIFD_ISSET\fP
+returns a non-zero value, indicating permission to read, then a
+connection is pending on the socket.
+.PP
+As an example, to read data from two sockets, \fIs1\fP and
+\fIs2\fP as it is available from each and with a one-second
+timeout, the following code
+might be used:
+.DS
+#include <sys/time.h>
+#include <sys/types.h>
+ ...
+fd_set read_template;
+struct timeval wait;
+ ...
+for (;;) {
+       wait.tv_sec = 1;                /* one second */
+       wait.tv_usec = 0;
+
+       FD_ZERO(&read_template);
+
+       FD_SET(s1, &read_template);
+       FD_SET(s2, &read_template);
+
+       nb = select(FD_SETSIZE, &read_template, (fd_set *) 0, (fd_set *) 0, &wait);
+       if (nb <= 0) {
+               \fIAn error occurred during the \fPselect\fI, or
+               the \fPselect\fI timed out.\fP
+       }
+
+       if (FD_ISSET(s1, &read_template)) {
+               \fISocket #1 is ready to be read from.\fP
+       }
+
+       if (FD_ISSET(s2, &read_template)) {
+               \fISocket #2 is ready to be read from.\fP
+       }
+}
+.DE
+.PP
+In 4.2, the arguments to \fIselect\fP were pointers to integers
+instead of pointers to \fIfd_set\fPs.  This type of call
+will still work as long as the number of file descriptors
+being examined is less than the number of bits in an
+integer; however, the methods illustrated above should
+be used in all current programs.

 .PP
 \fISelect\fP provides a synchronous multiplexing scheme.
 Asynchronous notification of output completion, input availability,
 .PP
 \fISelect\fP provides a synchronous multiplexing scheme.
 Asynchronous notification of output completion, input availability,