Miscellaneous corrections.
authorroland <roland>
Tue, 10 Nov 1992 00:32:54 +0000 (00:32 +0000)
committerroland <roland>
Tue, 10 Nov 1992 00:32:54 +0000 (00:32 +0000)
Problem areas marked with "@c !!!".

manual/socket.texi

index 5af646d..3df83bd 100644 (file)
@@ -19,10 +19,15 @@ Not all operating systems support sockets.  The GNU library provides
 the header file @file{sys/sockets.h} on all systems, and the socket
 functions always exist, but if the system does not really support
 sockets, these functions always fail.
+@c !!! a future release may omit them from the library instead of having
+@c stub functions.
 
 @strong{Incomplete:} We do not currently document the facilities for
 broadcast messages or for configuring internet interfaces.
 
+@c !!! I think we should use `name space' instead of `namespace' in this
+@c chapter. -rm
+
 @menu
 * Socket Concepts::    Basic concepts you need to know about.
 * Communication Styles::Stream communication, datagrams, and other styles.
@@ -81,8 +86,8 @@ freely.  Other styles are like mailing letters---you specify a
 destination address for each message you send.
 @end itemize
 
-@cindex namespace (of sockets)
-@cindex domains (of sockets)
+@cindex namespace (of socket)
+@cindex domain (of socket)
 @cindex socket namespace
 @cindex socket domain
 You must also choose a @dfn{namespace} for naming the socket.  A
@@ -96,15 +101,15 @@ usage of the same term.
 @cindex protocol (of socket)
 @cindex socket protocol
 Finally you must next choose the @dfn{protocol} to carry out the
-communication.  A protocol is a complex set of rules which were
-designed to be used as a complete whole.  Each protocol is valid for a
-particular namespace and communication style; a namespace is sometimes
-called a @dfn{protocol family} because of this.
+communication.  The protocol determines what low-level mechanism is used
+to transmit and receive data.  Each protocol is valid for a particular
+namespace and communication style; a namespace is sometimes called a
+@dfn{protocol family} because of this.
 
-The rules of a protocol apply to the data passing between two
-computers; most of these rules are handled by the operating system,
-and you need not know about them.  What you do need to know about
-protocols is this:
+The rules of a protocol apply to the data passing between two programs,
+perhaps on different computers; most of these rules are handled by the
+operating system, and you need not know about them.  What you do need to
+know about protocols is this:
 
 @itemize @bullet
 @item
@@ -135,9 +140,9 @@ defined in @file{sys/socket.h}.
 @comment sys/socket.h
 @comment BSD
 @deftypevr Macro int SOCK_STREAM
-The @code{SOCK_STREAM} style is like a pipe; it operates over a
-connection with a particular remote socket, and transmits data
-reliably as a stream of bytes.
+The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs});
+it operates over a connection with a particular remote socket, and
+transmits data reliably as a stream of bytes.
 
 Use of this style is covered in detail in @ref{Connections}.
 @end deftypevr
@@ -146,8 +151,8 @@ Use of this style is covered in detail in @ref{Connections}.
 @comment BSD
 @deftypevr Macro int SOCK_DGRAM
 The @code{SOCK_DGRAM} style is used for sending
-individually-addressed packets, unreliably.  It is the diametrical
-opposite of @code{SOCK_STREAM}.
+individually-addressed packets, unreliably.  
+It is the diametrical opposite of @code{SOCK_STREAM}.
 
 Each time you write data to a socket of this kind, that data becomes
 one packet.  Since @code{SOCK_DGRAM} sockets do not have connections,
@@ -231,15 +236,21 @@ specify an address for other sockets, but this is usually pointless;
 the first time you send data from a socket, or use it to initiate a
 connection, the system assigns an automatically generated address if
 you have not specified one.
+@c !!! some higher-level protocols may care about the client's port
+@c number.  for example, the rsh and rlogin protocols look at the
+@c client's port number and don't trust it (to log in without a
+@c password) unless it is < 1024 (meaning root on client machine).
 
-The details of socket addresses vary depending on namespace you are
-using.  @xref{File Namespace}, or @ref{Internet Namespace}, for
-specific information.
+The details of socket addresses vary depending on what namespace you are
+using.  @xref{File Namespace}, or @ref{Internet Namespace}, for specific
+information.
 
 Regardless of the namespace, you use the same functions @code{bind} and
 @code{getsockname} to set and examine a socket's address.  These
 functions use a generic data type, @code{struct sockaddr}, to
 represent the address.
+@c !!! i this is misleading: `struct sockaddr' is in fact never used; it
+@c exists for casting pointers to.
 
 @menu
 * Address Formats::            About @code{struct sockaddr}.
@@ -258,12 +269,21 @@ are using.
 
 Thus, the usual practice is to construct an address in the proper
 namespace-specific type, then cast a pointer to @code{struct sockaddr *}
-when you call @code{bind}.  Likewise, you would cast the result of
-@code{getsockname} to the proper namespace-specific data type in order to
-examine its components meaningfully.  The one piece of information
-that you can get with the @code{struct sockaddr} data type is the
-@dfn{address format} designator which tells you which data type to use
-to understand the address fully.
+when you call @code{bind}.  
+@c !!! this next sentence sounds like you do:
+@c  struct sockaddr addr;
+@c  getsockname (..., &addr, ...);
+@c  ((struct sockaddr_in *) &addr)->...
+@c rather than the actual:
+@c  struct sockaddr_in addr;
+@c  getsockname (..., (struct sockaddr *) &addr, ...)
+@c  addr....
+Likewise, you would cast the result of @code{getsockname} to the proper
+namespace-specific data type in order to examine its components
+meaningfully.
+The one piece of information that you can get with the @code{struct
+sockaddr} data type is the @dfn{address format} designator which tells
+you which data type to use to understand the address fully.
 
 @pindex sys/socket.h
 The symbols in this section are defined in the header file
@@ -275,7 +295,7 @@ The symbols in this section are defined in the header file
 The @code{struct sockaddr} type itself has the following members:
 
 @table @code
-@item unsigned short int sa_family
+@item short int sa_family
 This is the code for the address format of this address.  It
 identifies the format of the data which follows.
 
@@ -286,7 +306,6 @@ This is the actual socket address data, which is format-dependent.
 
 These symbolic constants designate particular address formats:
 
-@c ??? Roland, please define AF_FILE
 @comment sys/socket.h
 @comment GNU
 @deftypevr Macro int AF_FILE
@@ -348,6 +367,7 @@ The socket @var{socket} already has an address.
 You do not have permission to access the requested address.  (In the
 Internet domain, only the super-user is allowed to specify a port
 number in the range 0 through 1023.)
+@c !!! this needs an xref to where priv. port #s are explained
 @end table
 
 Additional conditions may be possible depending on the particular namespace
@@ -365,16 +385,17 @@ Internet socket.  The prototype for this function is in the header file
 @comment sys/socket.h
 @comment BSD
 @deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, size_t *@var{length_ptr})
-The @code{getsockname} information returns information about the
+The @code{getsockname} function returns information about the
 address of the socket @var{socket} in the locations specified by the
 @var{addr} and @var{length_ptr} arguments.  Note that the
 @var{length_ptr} is a pointer; you should initialize it to be the
 allocation size of @var{addr}, and on return it contains the actual
 size of the address data.
 
-The format of the address data depends on the socket namespace.  For a
-given namespace, the length of the information is fixed, so normally you
-can know exactly how much space is needed and can provide that much.
+The format of the address data depends on the socket namespace.  The
+length of the information is usually fixed for a given namespace, so
+normally you can know exactly how much space is needed and can provide
+that much.
 
 The return value is @code{0} on success and @code{-1} on error.  The
 following @code{errno} error conditions are defined for this function:
@@ -400,6 +421,9 @@ find a file's name from a descriptor for that file.
 @cindex file namespace, for sockets
 
 This section describes the details of the file namespace, @code{PF_FILE}.
+@c !!! it might be good to somewhere state that all the PF_* and AF_*
+@c constants are the same.  I don't even know where one is supposed to
+@c use PF_foo and where AF_foo.
 
 @menu
 * Concepts: File Namespace Concepts.
@@ -433,8 +457,7 @@ number if you want it to have one.
 
 After you close a socket in the file namespace, you should delete the
 file name from the file system.  Use @code{unlink} or @code{remove} to
-do this; see @ref{Deleting Files}.  Files that represent sockets are
-deleted automatically when the system is rebooted.
+do this; see @ref{Deleting Files}.
 
 The file namespace supports just one protocol for any communication
 style; it is protocol number @code{0}.
@@ -453,7 +476,6 @@ To create a socket in the file namespace, use the constant
 This designates the file namespace, in which socket addresses are file
 names.
 @end deftypevr
-@c ??? Roland, please define PF_FILE
 
 @comment sys/socket.h
 @comment BSD
@@ -498,42 +520,9 @@ the file name string.
 Here is an example showing how to create and name a socket in the file
 namespace.
 
-@comment This example is from lsockserver.c.
+@c !!! I changed the example to use offsetof; that should be explained
 @example
-#include <sys/socket.h>
-#include <stdio.h>
-#include <sys/un.h>
-#include <errno.h>
-#include <stdlib.h>
-
-int 
-make_named_socket (const char *filename)
-@{
-  struct sockaddr_un name;
-  int sock, status;
-  size_t size;
-
-  /* @r{Create the socket.} */
-  
-  sock = socket (PF_UNIX, SOCK_DGRAM, 0);
-  if (sock < 0) @{
-    perror ("socket");
-    exit (EXIT_FAILURE);
-  @}
-
-  /* @r{Bind a name to the socket.} */
-
-  name.sun_family = AF_FILE;
-  strcpy (name.sun_path, filename);
-  size = strlen (name.sun_path) + sizeof (name.sun_family);
-  status = bind (sock, (struct sockaddr *)&name, size);
-  if (size < 0) @{
-    perror ("bind");
-    exit (EXIT_FAILURE);
-  @}
-
-  return sock;
-@}
+@include makefsock.c.texi
 @end example
 
 @node Internet Namespace
@@ -589,7 +578,7 @@ for information about this.
 In the Internet namespace, a socket address consists of a host address
 and a port on that host.  In addition, the protocol you choose serves
 effectively as a part of the address because local port numbers are
-meaningful given within a particular protocol.
+meaningful only within a particular protocol.
 
 The data type for representing socket addresses in the Internet namespace
 is defined in the header file @file{netinet/in.h}.
@@ -624,6 +613,8 @@ you are using an Internet namespace socket address.
 @node Host Addresses
 @subsection Host Addresses
 
+@c !!! there should be a paragraph here that says something or other.
+
 @menu
 * Abstract Host Addresses::    What a host number consists of.
 * Data type: Host Address Data Type.   Data type for a host number.
@@ -648,8 +639,8 @@ discussed in @ref{Host Names}.
 
 @cindex network number
 @cindex local network address number
-An Internet host address is a number containing of four bytes of data,
-and consists of a @dfn{network number} and a @dfn{local network address
+An Internet host address is a number containing four bytes of data, and
+consists of a @dfn{network number} and a @dfn{local network address
 number} within that network.  Network numbers are registered with the
 Network Information Center (NIC), and are divided into three
 classes---A, B, and C.  The local network address numbers of individual
@@ -676,6 +667,8 @@ Since a single machine can be a member of multiple networks, it can
 have multiple Internet host addresses.  However, there is never
 supposed to be more than one machine with the same host address.
 
+@c !!! this section could document the IN_CLASS* macros in <netinet/in.h>.
+
 @cindex standard dot notation, for Internet addresses
 @cindex dot notation, for Internet addresses
 There are four forms of the @dfn{standard numbers-and-dots notation}
@@ -708,6 +701,9 @@ radix is assumed.
 @node Host Address Data Type
 @subsubsection Host Address Data Type
 
+@c !!! all this union frobbing is not necessary.  struct in_addr has one
+@c member: "unsigned long int s_addr".
+
 Internet host addresses are represented internally with the data type
 @code{struct in_addr}, though in some situations an @code{unsigned
 long int} is used instead.  Unfortunately, the interfaces to the
@@ -745,6 +741,8 @@ is not unusual), using @code{INADDR_ANY} allows the system to choose
 whichever address makes communication most efficient.
 @end deftypevr
 
+@c !!! list also INADDR_LOOPBACK, INADDR_NONE, INADDR_BROADCAST
+
 @node Host Address Functions
 @subsubsection Host Address Functions
 
@@ -752,13 +750,13 @@ whichever address makes communication most efficient.
 These additional functions for manipulating Internet addresses are
 declared in @file{arpa/inet.h}.  They represent Internet addresses in
 network byte order; they represent network numbers and
-local-address-within-network numbers in host byte order.  @xref{Byte
-Order}.
+local-address-within-network numbers in host byte order.
+@xref{Byte Order}, for an explanation of network and host byte order.
 
 @comment arpa/inet.h
 @comment BSD
 @deftypefun {unsigned long int} inet_addr (const char *@var{name})
-This function converts the Internet host address address @var{name}
+This function converts the Internet host address @var{name}
 from the standard numbers-and-dots notation into binary data.
 If the input is not valid, @code{inet_addr} returns @code{-1}.
 @end deftypefun
@@ -814,7 +812,7 @@ you can also refer to a host by a symbolic name.  The advantage of a
 symbolic name is that it is usually easier to remember.  For example,
 the machine with Internet address @samp{128.52.46.32} is also known as
 @samp{churchy.gnu.ai.mit.edu}; and other machines in the @samp{gnu.ai.mit.edu}
-domeain can reference it simply as @samp{churchy}.
+domain can refer to it simply as @samp{churchy}.
 
 @pindex /etc/hosts
 @pindex netdb.h
@@ -822,8 +820,11 @@ Internally, the system uses a database to keep track of the mapping
 between host names and host numbers.  This database is usually either
 the file @file{/etc/hosts} or an equivalent provided by a name server.
 The functions and other symbols for accessing this database are declared
-in @file{netdb.h}.  They are all BSD features, controlled by
-@code{_BSD_SOURCE} and @code{_GNU_SOURCE}.
+in @file{netdb.h}. 
+@c !!! lack of _BSD_SOURCE does not turn these off; the header files
+@c that do not exist in ansi or posix don't pay attention to the macros.
+They are all BSD features, controlled by @code{_BSD_SOURCE} and
+@code{_GNU_SOURCE}.
 
 @comment netdb.h
 @comment BSD
@@ -842,6 +843,8 @@ vector of strings.
 @item int h_addrtype
 This is the host address type; its value is always @code{AF_INET}.
 @xref{Socket Addresses}.
+@c !!! this really is a general mechanism that can work for things other
+@c than inet; xns for example.
 
 @item int h_length
 This is the length, in bytes, of each address.
@@ -860,7 +863,7 @@ first host address.
 As far as the host database is concerned, each address is just a block
 of memory @code{h_length} bytes long.  But in other contexts there is an
 implicit assumption that you can convert this to a @code{struct in_addr} or
-a @code{unsigned long int}.  Host addresses in a @code{struct hostent}
+an @code{unsigned long int}.  Host addresses in a @code{struct hostent}
 structure are always given in network byte order; see @ref{Byte Order}.
 
 You can use @code{gethostbyname} or @code{gethostbyaddr} to search the
@@ -939,6 +942,8 @@ in using these functions, because they are not reentrant.
 This function opens the hosts database to begin scanning it.  You can
 then call @code{gethostent} to read the entries.
 
+@c !!! the flag has different meaning if using the DNS.
+
 If the @var{stayopen} argument is nonzero, this sets a flag so that
 subsequent calls to @code{gethostbyname} or @code{gethostbyaddr} will
 not close the database (as they usually would).  This makes for more
@@ -973,6 +978,7 @@ Port numbers less than 1024 are reserved for standard servers, such as
 of these, and you can use the @code{getservbyname} function to map a
 service name onto a port number; see @ref{Services Database}.
 
+@c !!! netinet/in.h defines IPPORT_USERRESERVED as 5000, not 50000.
 If you write a server that is not one of the standard ones defined in
 the database, you must choose a port number for it.  Use a number
 greater than 50,000; such numbers are reserved for servers and won't
@@ -1087,14 +1093,14 @@ reopening the database for each call.
 
 @comment netdb.h
 @comment BSD
-@deftypefun {struct servent *} getservent ()
+@deftypefun {struct servent *} getservent (void)
 This function returns the next entry in the services database.  If
 there are no more entries, it returns a null pointer.
 @end deftypefun
 
 @comment netdb.h
 @comment BSD
-@deftypefun void endservent ()
+@deftypefun void endservent (void)
 This function closes the services database.
 @end deftypefun
 
@@ -1113,16 +1119,16 @@ order), and others put it last (``little-endian'' order).
 @cindex network byte order
 So that machines with different byte order conventions can
 communicate, the Internet protocols specify a canonical byte order
-convention for data transmitted over the network.  This is calledq
+convention for data transmitted over the network.  This is known
 as the @dfn{network byte order}.
 
 When establishing an Internet socket connection, you must make sure that
-the byte ordering of the data in the @code{sin_port} and @code{sin_addr}
-members of the @code{sockaddr_in} structure are represented in the
-network byte order.  If you are encoding integer data in the messages
-sent through the socket, you should convert this to network byte order
-too.  If you don't do this, your program may fail when running on or
-talking to other kinds of machines.
+the data in the @code{sin_port} and @code{sin_addr} members of the
+@code{sockaddr_in} structure are represented in the network byte order.
+If you are encoding integer data in the messages sent through the
+socket, you should convert this to network byte order too.  If you don't
+do this, your program may fail when running on or talking to other kinds
+of machines.
 
 If you use @code{getservbyname} and @code{gethostbyname} or
 @code{inet_addr} to get the port number and host address, the values are
@@ -1210,8 +1216,8 @@ These are alternate names for the protocol, specified as an array of
 strings.  The last element of the array is a null pointer.
 
 @item int p_proto
-This is the protocol number; use this member as the @var{protocol}
-argument to @code{socket}.
+This is the protocol number (in host byte order); use this member as the
+@var{protocol} argument to @code{socket}.
 @end table
 @end deftp
 
@@ -1254,14 +1260,14 @@ reopening the database for each call.
 
 @comment netdb.h
 @comment BSD
-@deftypefun {struct protoent *} getprotoent ()
+@deftypefun {struct protoent *} getprotoent (void)
 This function returns the next entry in the protocols database.  It
 returns a null pointer if there are no more entries.
 @end deftypefun
 
 @comment netdb.h
 @comment BSD
-@deftypefun void endprotoent ()
+@deftypefun void endprotoent (void)
 This function closes the protocols database.
 @end deftypefun
 
@@ -1269,73 +1275,29 @@ This function closes the protocols database.
 @subsection Internet Socket Example
 
 Here is an example showing how to create and name a socket in the
-Internet namespace.  Since the newly created socket exists on the machine
+Internet namespace.  
+@c !!! this sentence doesn't say anything useful.  i think the IP
+@c address you bind with determines where you will accept connections
+@c from.  this should be explained elsewhere.
+Since the newly created socket exists on the machine
 that the program is running on, this example uses @code{INADDR_ANY} as
 the host address.
 
-@comment This example is from isockserver.c.
 @example
-#include <sys/socket.h>
-#include <netdb.h>
-#include <netinet/in.h>
-#include <sys/types.h>
-#include <stdio.h>
-#include <errno.h>
-#include <stdlib.h>
-
-int 
-make_socket (unsigned short int port)
-@{
-  int sock, status;
-  struct sockaddr_in name;
-  unsigned long int addr;
-
-  /* @r{Create the socket.} */
-  sock = socket (PF_INET, SOCK_STREAM, 0);
-  if (sock < 0) @{
-    perror ("socket");
-    exit (EXIT_FAILURE);
-  @}
-
-  /* @r{Give the socket a name.} */
-  name.sin_family = AF_INET;
-  name.sin_port = htons (port);
-  addr = htonl (INADDR_ANY);
-  memcpy (&name.sin_addr, &addr, sizeof (addr));
-  status = bind (sock, (struct sockaddr *)&name, sizeof (name));
-  if (status < 0) @{
-    perror ("bind");
-    exit (EXIT_FAILURE);
-  @}
-
-  return sock;
-@}
+@include makeisock.c.texi
 @end example
 
 Here is another example, showing how you can fill in a @code{sockaddr_in}
 structure, given a host name string and a port number:
 
-@comment This example is from isockclient.c.
 @example
-void 
-init_sockaddr (struct sockaddr_in *name, const char *hostname,
-               unsigned short int port)
-@{
-  struct hostent *hostinfo;
-
-  name->sin_family = AF_INET;
-  name->sin_port = htons (PORT);
-  hostinfo = gethostbyname (SERVERHOST);
-  if (!hostinfo) @{
-    fprintf (stderr, "Unknown host %s.\n", SERVERHOST);
-    exit (EXIT_FAILURE);
-  @}
-  memcpy (&name->sin_addr, hostinfo->h_addr, sizeof (unsigned long int));
-@}
+@include isockaddr.c.texi
 @end example
 
 @node Open/Close Sockets
-@section Open/Close Sockets
+@section Opening and Closing Sockets
+
+@c !!! need some text here.
 
 @menu
 * Creating a Socket::           How to open a socket.
@@ -1370,8 +1332,8 @@ conditions are defined for this function:
 
 @table @code
 @item EPROTONOSUPPORT
-The @var{protocol} or @var{style} is not supported by the namespace
-@var{namespace}.
+The @var{protocol} or @var{style} is not supported by the
+@var{namespace} specified.
 
 @item EMFILE
 The process already has too many file descriptors open.
@@ -1433,7 +1395,7 @@ waiting to be sent.  Stop looking for acknowledgement of data already
 sent; don't retransmit it if it is lost.
 
 @item 2
-Stop reception and transmission.
+Stop both reception and transmission.
 @end table
 
 The return value is @code{0} on success and @code{-1} on failure.  The
@@ -1462,6 +1424,8 @@ sockets.  It is very similar to a pipe and is used in much the same way.
 Socket pairs are created with the @code{socketpair} function, declared
 in @file{sys/socket.h}.  (Compare this function with the @code{pipe}
 function; see @ref{Creating a Pipe}.)
+@c !!! should say how a socketpair differs from a pipe; perhaps give
+@c example of pipe implemented with socketpair.
 @pindex sys/socket.h
 
 @comment sys/socket.h
@@ -1571,6 +1535,9 @@ Normally, @code{connect} waits until the server responds to the
 request before it returns.  You can set nonblocking mode on the socket
 @var{socket} to make @code{connect} return immediately without waiting
 for the response.
+@c !!! xref to setting nonblock mode.
+@c !!! how do you tell when it has finished connecting?  I suspect the
+@c way you do it is select for writing.
 
 The normal return value from @code{connect} is @code{0}.  If an error
 occurs, @code{connect} returns @code{-1}.  The following @code{errno}
@@ -1632,6 +1599,7 @@ connect to a port; any process on any machine can make a connection to
 your server.  If you want to restrict access to your server, make it
 examine the addresses associated with connection requests or implement
 some other handshaking or identification protocol.
+@c !!! i think normal file protections apply for AF_FILE
 
 @comment sys/socket.h
 @comment BSD
@@ -1663,7 +1631,7 @@ The socket @var{socket} does not support this operation.
 @cindex sockets, accepting connections
 @cindex accepting connections
 
-When a server received a connection request, it can complete the
+When a server receives a connection request, it can complete the
 connection by accepting the request.  Use the function @code{accept}
 to do this.
 
@@ -1692,8 +1660,9 @@ socket @var{socket}.
 The @code{accept} function waits if there are no connections pending,
 unless the socket @var{socket} has nonblocking mode set.  @xref{File
 Status Flags}, in regard to nonblocking mode.
+@c !!! mention using select to find when connection pending.
 
-The @var{sockaddr} and @var{length_ptr} arguments are used to return
+The @var{addr} and @var{length_ptr} arguments are used to return
 information about the name of the client socket that initiated the
 connection.  @xref{Socket Addresses}, for information about the format
 of the information.
@@ -1782,7 +1751,7 @@ an additional argument which you can use to specify various flags to
 control the special I/O modes.  For example, you can specify the
 @code{MSG_OOB} flag to read or write out-of-band data, the
 @code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag
-to control inclusing of routing information on output.
+to control inclusion of routing information on output.
 
 @menu
 * Sending Data::               Sending data with @code{write}.
@@ -1800,6 +1769,7 @@ as well use @code{write} instead of @code{send}; see @ref{I/O
 Primitives}.  If the socket was connected but the connection has broken,
 you get a @code{SIGPIPE} signal for any use of @code{send} or
 @code{write}.
+@c !!! xref to where SIGPIPE is explained in detail.
 
 @comment sys/socket.h
 @comment BSD
@@ -1837,6 +1807,7 @@ message is too large for this to be possible.
 Nonblocking mode has been set on the socket, and the write operation
 would block.  (Normally @code{send} blocks until the operation can be
 completed.)
+@c !!! xref to nonblocking mode
 
 @item ENOBUFS
 There is not enough internal buffer space available.
@@ -1848,7 +1819,7 @@ You never connected this socket.
 This socket was connected but the connection is now broken.  In this
 case, @code{send} generates a @code{SIGPIPE} signal first; if that
 signal is ignored or blocked, or if its handler returns, then
-@code{send}f fails with @code{EPIPE}.
+@code{send} fails with @code{EPIPE}.
 @end table
 @end deftypefun
 
@@ -1882,6 +1853,7 @@ The descriptor @var{socket} is not a socket.
 Nonblocking mode has been set on the socket, and the read operation
 would block.  (Normally, @code{recv} blocks until there is input available
 to be read.)
+@c !!! xref to nonblocking mode
 
 @item EINTR
 The operation was interrupted by a signal before any data was read.
@@ -1931,61 +1903,8 @@ stream socket in the Internet namespace.  It doesn't do anything
 particularly interesting once it has connected to the server; it just
 sends a text string to the server and exits.
 
-@comment This example is from isockclient.c.
 @example
-#include <sys/socket.h>
-#include <netdb.h>
-#include <netinet/in.h>
-#include <sys/types.h>
-#include <stdio.h>
-#include <errno.h>
-#include <stdlib.h>
-
-#define PORT 2222
-#define MESSAGE "Yow!!! Are we having fun yet?!?"
-#define SERVERHOST "churchy.gnu.ai.mit.edu"
-
-void 
-write_to_server (int filedes)
-@{
-  int nbytes;
-
-  nbytes = write (filedes, MESSAGE, strlen (MESSAGE) + 1);
-  if (nbytes < 0) @{
-    perror ("write");
-    exit (EXIT_FAILURE);
-  @}
-@}
-
-
-void 
-main ()
-@{
-  int sock;
-  int status;
-  struct sockaddr_in servername;
-
-  /* @r{Create the socket.}  */
-  sock = socket (PF_INET, SOCK_STREAM, 0);
-  if (sock < 0) @{
-    perror ("socket (client)");
-    exit (EXIT_FAILURE);
-  @}
-
-  /* @r{Connect to the server.}  */
-  init_sockaddr (&servername, SERVERHOST, PORT);
-  status = connect (sock, (struct sockaddr *) &servername,
-                    sizeof (servername));
-  if (status < 0) @{
-    perror ("connect (client)");
-    exit (EXIT_FAILURE);
-  @}
-
-  /* @r{Send data to the server.}  */
-  write_to_server (sock);
-  close (sock);
-  exit (EXIT_SUCCESS);
-@}
+@include inetclient.c.texi
 @end example
 
 @node Server Example
@@ -2001,107 +1920,14 @@ additional connection requests.
 
 This particular server doesn't do anything interesting once it has
 gotten a message from a client.  It does close the socket for that
-client when it detects and end-of-file condition (resulting from the
+client when it detects an end-of-file condition (resulting from the
 client shutting down its end of the connection).
 
 This program uses @code{make_socket} and @code{init_sockaddr} to set
 up the socket address; see @ref{Inet Example}.
 
-@comment This example is isockserver.c.
 @example
-#include <sys/socket.h>
-#include <netdb.h>
-#include <netinet/in.h>
-#include <sys/types.h>
-#include <stdio.h>
-#include <errno.h>
-#include <stdlib.h>
-
-#define PORT 2222
-#define MAXMSG 512
-
-int
-read_from_client (int filedes)
-@{
-  char buffer[MAXMSG];
-  int nbytes;
-
-  nbytes = read (filedes, buffer, MAXMSG);
-  if (nbytes < 0) @{
-    /* @r{Read error.} */
-    perror ("read");
-    exit (EXIT_FAILURE);
-  @}
-  else if (nbytes == 0) @{
-    /* @r{End-of-file.} */
-    return -1;
-  @}
-  else @{
-    /* @r{Data read.} */
-    fprintf (stderr, "Server:  got message: %s\n", buffer);
-    return 0;
-  @}
-@}
-
-void
-main ()
-@{
-  int sock;
-  int status;
-  fd_set active_fd_set, read_fd_set;
-  int i;
-  struct sockaddr_in clientname;
-  size_t size;
-
-  /* @r{Create the socket and set it up to accept connections.} */
-  sock = make_socket (PORT);
-  status = listen (sock, 1);
-  if (status < 0) @{
-    perror ("listen");
-    exit (EXIT_FAILURE);
-  @}
-
-  /* @r{Initialize the set of active sockets.} */
-  FD_ZERO (&active_fd_set);
-  FD_SET (sock, &active_fd_set);
-
-  while (1) @{
-    /* @r{Block until input arrives on one or more active sockets.} */
-    memcpy (&read_fd_set, &active_fd_set, sizeof (active_fd_set));
-    status = select (FD_SETSIZE, &read_fd_set, NULL, NULL, NULL);
-    if (status < 0) @{
-      perror ("select");
-      exit (EXIT_FAILURE);
-    @}
-    /* @r{Service all the sockets with input pending.} */
-    for (i=0; i<FD_SETSIZE; i++)  @{
-      if (FD_ISSET (i, &read_fd_set)) @{
-
-        /* @r{Connection request on original socket.} */
-        if (i == sock) @{
-          size = sizeof (clientname);
-          status = accept (sock, (struct sockaddr *)&clientname, &size);
-          if (status < 0) @{
-            perror ("accept");
-            exit (EXIT_FAILURE);
-          @}
-          fprintf (stderr, "Server: connection from host %s, port %d.\n",
-                   inet_ntoa (clientname.sin_addr),
-                   ntohs (clientname.sin_port));
-          FD_SET (status, &active_fd_set);
-        @}
-
-        /* @r{Data arriving on an already-connected socket.} */
-        else @{
-          if (read_from_client (i) < 0) @{
-            close (i);
-            FD_CLR (i, &active_fd_set);
-          @}
-        @}
-      @}
-    @}
-  @}
-@}
+@include inetserver.c.texi
 @end example
 
 @node Out-of-Band Data
@@ -2160,25 +1986,26 @@ out-of-band mark:
 int
 discard_until_mark (int socket)
 @{
-  while (1) @{
-    /* @r{This is not an arbitrary limit; any size will do.}  */
-    char buffer[1024];
-    int result, success;
-
-    /* @r{If we have reached the mark, return.}  */
-    success = ioctl (socket, SIOCATMARK, &result);
-    if (success < 0)
-      perror ("ioctl");
-    if (result)
-      return;
-
-    /* @r{Otherwise, read a bunch of ordinary data and discard it.}
-       @r{This is guaranteed not to read past the mark}
-       @r{if it starts before the mark.}  */
-    success = read (socket, buffer, sizeof buffer);
-    if (success < 0)
-      perror ("read");
-  @}
+  while (1)
+    @{
+      /* @r{This is not an arbitrary limit; any size will do.}  */
+      char buffer[1024];
+      int result, success;
+
+      /* @r{If we have reached the mark, return.}  */
+      success = ioctl (socket, SIOCATMARK, &result);
+      if (success < 0)
+        perror ("ioctl");
+      if (result)
+        return;
+
+      /* @r{Otherwise, read a bunch of ordinary data and discard it.}
+         @r{This is guaranteed not to read past the mark}
+         @r{if it starts before the mark.}  */
+      success = read (socket, buffer, sizeof buffer);
+      if (success < 0)
+        perror ("read");
+    @}
 @}
 @end example
 
@@ -2212,59 +2039,62 @@ read_oob (int socket)
   struct buffer *tail = 0;
   struct buffer *list = 0;
 
-  while (1) @{
-    /* @r{This is an arbitrary limit.}
-       @r{Does anyone know how to do this without a limit?}  */
-    char *buffer = (char *) xmalloc (1024);
-    struct buffer *link;
-    int success;
-    int result;
-
-    /* @r{Try again to read the out-of-band data.}  */
-    success = recv (socket, buffer, sizeof buffer, MSG_OOB);
-    if (success >= 0) @{
-      /* @r{We got it, so return it.}  */
-      struct buffer *link
-        = (struct buffer *) xmalloc (sizeof (struct buffer));
-      link->buffer = buffer;
-      link->size = success;
-      link->next = list;
-      return link;
-    @}
-
-    /* @r{If we fail, see if we are at the mark.}  */
-    success = ioctl (socket, SIOCATMARK, &result);
-    if (success < 0)
-      perror ("ioctl");
-    if (result) @{
-      /* @r{At the mark; skipping past more ordinary data cannot help.}
-         @r{So just wait a while.}  */
-      sleep (1);
-      continue;
-    @}
+  while (1)
+    @{
+      /* @r{This is an arbitrary limit.}
+         @r{Does anyone know how to do this without a limit?}  */
+      char *buffer = (char *) xmalloc (1024);
+      struct buffer *link;
+      int success;
+      int result;
+
+      /* @r{Try again to read the out-of-band data.}  */
+      success = recv (socket, buffer, sizeof buffer, MSG_OOB);
+      if (success >= 0)
+        @{
+          /* @r{We got it, so return it.}  */
+          struct buffer *link
+            = (struct buffer *) xmalloc (sizeof (struct buffer));
+          link->buffer = buffer;
+          link->size = success;
+          link->next = list;
+          return link;
+        @}
 
-    /* @r{Otherwise, read a bunch of ordinary data and save it.}
-       @r{This is guaranteed not to read past the mark}
-       @r{if it starts before the mark.}  */
-    success = read (socket, buffer, sizeof buffer);
-    if (success < 0)
-      perror ("read");
+      /* @r{If we fail, see if we are at the mark.}  */
+      success = ioctl (socket, SIOCATMARK, &result);
+      if (success < 0)
+        perror ("ioctl");
+      if (result)
+        @{
+          /* @r{At the mark; skipping past more ordinary data cannot help.}
+             @r{So just wait a while.}  */
+          sleep (1);
+          continue;
+        @}
 
-    /* @r{Save this data in the buffer list.}  */
-    @{
-      struct buffer *link
-        = (struct buffer *) xmalloc (sizeof (struct buffer));
-      link->buffer = buffer;
-      link->size = success;
-
-      /* @r{Add the new link to the end of the list.}  */
-      if (tail)
-        tail->next = link;
-      else
-        list = link;
-      tail = link;
+      /* @r{Otherwise, read a bunch of ordinary data and save it.}
+         @r{This is guaranteed not to read past the mark}
+         @r{if it starts before the mark.}  */
+      success = read (socket, buffer, sizeof buffer);
+      if (success < 0)
+        perror ("read");
+
+      /* @r{Save this data in the buffer list.}  */
+      @{
+        struct buffer *link
+          = (struct buffer *) xmalloc (sizeof (struct buffer));
+        link->buffer = buffer;
+        link->size = success;
+
+        /* @r{Add the new link to the end of the list.}  */
+        if (tail)
+          tail->next = link;
+        else
+          list = link;
+        tail = link;
+      @}
     @}
-  @}
 @}
 @end example
 
@@ -2343,7 +2173,7 @@ also tells you where it was sent from.  This function is declared in
 
 @comment sys/socket.h
 @comment BSD
-@deftypefun int recvfrom (int @var{socket}, void *@var{buffer}. size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, size_t *@var{length_ptr})
+@deftypefun int recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, size_t *@var{length_ptr})
 The @code{recvfrom} function reads one packet from the socket
 @var{socket} into the buffer @var{buffer}.  The @var{size} argument
 specifies the maximum number of bytes to be read.
@@ -2375,6 +2205,7 @@ you don't want to specify @var{flags} (@pxref{I/O Primitives}).
 @c sendmsg and recvmsg are like readv and writev in that they
 @c use a series of buffers.  It's not clear this is worth
 @c supporting or that we support them.
+@c !!! they can do more; it is hairy
 
 @comment sys/socket.h
 @comment BSD
@@ -2405,52 +2236,8 @@ messages to arrive, bouncing each message back to the sender.
 Obviously, this isn't a particularly useful program, but it does show
 the general ideas involved.
 
-@comment This example is from lsockserver.c.
 @example
-#include <sys/socket.h>
-#include <sys/un.h>
-#include <stdio.h>
-#include <errno.h>
-#include <stdlib.h>
-
-#define SERVER "/tmp/serversocket"
-#define MAXMSG 512
-
-void 
-main ()
-@{
-  int sock;
-  char message[MAXMSG];
-  struct sockaddr_un name;
-  size_t size;
-  int nbytes;
-
-  /* @r{Make the socket, then loop endlessly.} */
-
-  sock = make_named_socket (SERVER);
-  while (1) @{
-
-    /* @r{Wait for a datagram.} */
-    size = sizeof (name);
-    nbytes = recvfrom (sock, message, MAXMSG, 0,
-                       (struct sockaddr *)&name, &size);
-    if (nbytes < 0) @{
-      perror ("recfrom (server)");
-      exit (EXIT_FAILURE);
-    @}
-
-    /* @r{Give a diagnostic message.} */
-    fprintf (stderr, "Server: got message: %s\n", message);
-
-    /* @r{Bounce the message back to the sender.} */
-    nbytes = sendto (sock, message, nbytes, 0,
-                     (struct sockaddr *)&name, size);
-    if (nbytes < 0) @{
-      perror ("sendto (server)");
-      exit (EXIT_FAILURE);
-    @}
-  @}
-@}
+@include fileserver.c.texi
 @end example
 
 @node Example Receiver
@@ -2465,58 +2252,8 @@ a message back to the client.  Since the socket has no associated
 connection state, the only way the server can do this is by
 referencing the name of the client.
 
-@comment This example is from lsockclient.c.
 @example
-#include <sys/socket.h>
-#include <sys/un.h>
-#include <stdio.h>
-#include <errno.h>
-#include <stdlib.h>
-
-#define SERVER "/tmp/serversocket"
-#define CLIENT "/tmp/mysocket"
-#define MAXMSG 512
-#define MESSAGE "Yow!!! Are we having fun yet?!?"
-
-void 
-main ()
-@{
-  int sock;
-  char message[MAXMSG];
-  struct sockaddr_un name;
-  size_t size;
-  int nbytes;
-
-  /* @r{Make the socket.} */
-  sock = make_named_socket (CLIENT);
-
-  /* @r{Initialize the server socket address.} */
-  name.sun_family = AF_FILE;
-  strcpy (name.sun_path, SERVER);
-  size = strlen (name.sun_path) + sizeof (name.sun_family);
-
-  /* @r{Send the datagram.} */
-  nbytes = sendto (sock, MESSAGE, strlen (MESSAGE) + 1, 0,
-                   (struct sockaddr *)&name, size);
-  if (nbytes < 0) @{
-    perror ("sendto (client)");
-    exit (EXIT_FAILURE);
-  @}
-
-  /* @r{Wait for a reply.} */   
-  nbytes = recvfrom (sock, message, MAXMSG, 0, NULL, 0);
-  if (nbytes < 0) @{
-    perror ("recfrom (client)");
-    exit (EXIT_FAILURE);
-  @}
-
-  /* @r{Print a diagnostic message.} */
-  fprintf (stderr, "Client: got message: %s\n", message);
-
-  /* @r{Clean up.} */
-  close (sock);
-  remove (CLIENT);
-@}
+@include fileclient.c.texi
 @end example
 
 Keep in mind that datagram socket communications are unreliable.  In
@@ -2529,20 +2266,23 @@ for the reply, and in case of timeout either resend the message or
 shut down the socket and exit.
 
 @node Inetd
-@section The Inetd Daemon
+@section The @code{inetd} Daemon
 
 We've explained above how to write a server program that does its own
 listening.  Such a server must already be running in order for anyone
 to connect to it.
 
 Another way to provide service for an Internet port is to let the
-daemon program Inetd do the listening.  Inetd is a program that runs
+daemon program @code{inetd} do the listening.  @code{inetd} is a program that runs
 all the time and listens for messages on a specified set of ports.
 When it receives a message, it accepts the connection and then forks a
 child process to run the corresponding server program.  You specify
 the ports and their programs in the file @file{/etc/inetd.conf}.
 @c ??? Supposedly listen is not permitted for conectionless styles.
 @c ??? So what does Inetd do to wait for a message to arrive?
+@c !!! inetd does select for reading; this tells you when a
+@c connection-oriented socket can be accepted from, or when a
+@c connectionless socket can be read from.
 
 @menu
 * Inetd Servers::
@@ -2550,9 +2290,9 @@ the ports and their programs in the file @file{/etc/inetd.conf}.
 @end menu
 
 @node Inetd Servers
-@subsection Inetd Servers
+@subsection @code{inetd} Servers
 
-Writing a server program to be run by Inetd is very simple.  Each time
+Writing a server program to be run by @code{inetd} is very simple.  Each time
 someone requests a connection to the appropriate port, a new server
 process starts.  The connection already exists at this time; the
 socket is available as the standard input descriptor and as the
@@ -2560,21 +2300,21 @@ standard output descriptor (descriptors 0 and 1) in the server
 process.  So the server program can begin reading and writing data
 right away.  Often the program needs only the ordinary I/O facilities;
 in fact, a general-purpose filter program that knows nothing about
-sockets can work as a byte stream server run by Inetd.
+sockets can work as a byte stream server run by @code{inetd}.
 
-You can also use Inetd for servers that use connectionless
-communication styles.  For these servers, Inetd does not try to accept
+You can also use @code{inetd} for servers that use connectionless
+communication styles.  For these servers, @code{inetd} does not try to accept
 a connection, since no connection is possible.  It just starts the
 server program, which can read the incoming datagram packet from
 descriptor 0.  The server program can handle one request and then
 exit, or you can choose to write it to keep reading more requests
 until no more arrive, and then exit.  You must specify which of these
-two techniques the server uses, when you configure Inetd.
+two techniques the server uses, when you configure @code{inetd}.
 
 @node Configuring Inetd
-@subsection Configuring Inetd
+@subsection Configuring @code{inetd}
 
-The file @file{/etc/inetd.conf} tells Inetd which ports to listen to
+The file @file{/etc/inetd.conf} tells @code{inetd} which ports to listen to
 and what server programs to run for them.  Normally each entry in the
 file is one line, but you can split it onto multiple lines provided
 all but the first line of the entry start with whitespace.  Lines that
@@ -2583,8 +2323,8 @@ start with @samp{#} are comments.
 Here are two standard entries in @file{/etc/inetd.conf}:
 
 @smallexample
-ftp    stream  tcp     nowait  root    /usr/local/etc/ftpd     ftpd
-talk   dgram   udp     wait    root    /usr/etc/talkd          talkd
+ftp    stream  tcp     nowait  root    /libexec/ftpd   ftpd
+talk   dgram   udp     wait    root    /libexec/talkd  talkd
 @end smallexample
 
 An entry has this format:
@@ -2595,8 +2335,8 @@ An entry has this format:
 
 The @var{service} field says which service this program provides.  It
 should be the name of a service defined in @file{/etc/services}.
-Inetd uses @var{service} to decide which ports to listen to for this
-entry.
+@code{inetd} uses @var{service} to decide which port to listen on for
+this entry.
 
 The fields @var{style} and @var{protocol} specify the communication
 style and the protocol to use for the listening socket.  The style
@@ -2609,11 +2349,11 @@ byte stream connections and @samp{udp} for unreliable datagrams.
 The @var{wait} field should be either @samp{wait} or @samp{nowait}.
 Use @samp{wait} if @var{style} is a connectionless style and the
 server, once started, handles multiple requests, as many as come in.
-Use @samp{nowait} if Inetd should start a new process for each message
+Use @samp{nowait} if @code{inetd} should start a new process for each message
 or request that comes in.  If @var{style} uses connections, then
 @var{wait} @strong{must} be @samp{nowait}.
 
-@var{user} is the user name that the server should run as.  Inetd runs
+@var{user} is the user name that the server should run as.  @code{inetd} runs
 as root, so it can set the user ID of its children arbitrarily.  It's
 best to avoid using @samp{root} for @var{user} if you can; but some
 servers, such as Telnet and FTP, read a username and password
@@ -2628,10 +2368,12 @@ command-line arguments of @var{program}.  The first word in
 @var{arguments} is argument zero, which should by convention be the
 program name itself (sans directories).
 
-If you edit @file{/etc/inetd.conf}, you can tell Inetd to reread the
-file and obey its new contents by sending the Inetd process the
+If you edit @file{/etc/inetd.conf}, you can tell @code{inetd} to reread the
+file and obey its new contents by sending the @code{inetd} process the
 @code{SIGHUP} signal.  You'll have to use @code{ps} to determine the
-process ID of the Inetd process, as it is not fixed.
+process ID of the @code{inetd} process, as it is not fixed.
+
+@c !!! could document /etc/inetd.sec
 
 @node Socket Options
 @section Socket Options
@@ -2719,20 +2461,23 @@ header file @file{sys/socket.h}.
 @comment sys/socket.h
 @comment BSD
 @item SO_DEBUG
-This option toggles recording of debugging information in the
-underlying protocol modules.  The value has type @code{int}; a nonzero
-value means ``yes''.
+@c Extra blank line here makes the table look better.
+
+This option toggles recording of debugging information in the underlying
+protocol modules.  The value has type @code{int}; a nonzero value means
+``yes''.
+@c !!! should say how this is used
 
 @comment sys/socket.h
 @comment BSD
 @item SO_REUSEADDR
-This option controls whether @code{bind} should permit reuse of local
-addresses for this socket.  If you enable this option, you can
-actually have two sockets with the same Internet port number; but the
-system won't allow you to use the two identically-named sockets in a
-way that would confuse the Internet.  The reason for this option is
-that some higher-level Internet protocols, including FTP, require you
-to keep reusing the same socket number.
+This option controls whether @code{bind} (@pxref{Setting Address})
+should permit reuse of local addresses for this socket.  If you enable
+this option, you can actually have two sockets with the same Internet
+port number; but the system won't allow you to use the two
+identically-named sockets in a way that would confuse the Internet.  The
+reason for this option is that some higher-level Internet protocols,
+including FTP, require you to keep reusing the same socket number.
 
 The value has type @code{int}; a nonzero value means ``yes''.
 
@@ -2795,15 +2540,14 @@ nonzero value means ``yes''.
 @comment BSD
 @item SO_SNDBUF
 This option gets or sets the size of the output buffer.  The value is an
-@code{int}, which is the size in bytes.
+@code{size_t}, which is the size in bytes.
 
 @comment sys/socket.h
 @comment BSD
 @item SO_RCVBUF
 This option gets or sets the size of the input buffer.  The value is an
-@code{int}, which is the size in bytes.
+@code{size_t}, which is the size in bytes.
 
-@comment ??? SO_STYLE is not yet defined.
 @comment sys/socket.h
 @comment GNU
 @item SO_STYLE
@@ -2819,9 +2563,12 @@ style; see @ref{Communication Styles}.
 @comment sys/socket.h
 @comment BSD 
 @item SO_ERROR
+@c Extra blank line here makes the table look better.
+
 This option can be used with @code{getsockopt} only.  It is used to reset
 the error status of the socket.  The value is an @code{int}, which represents
 the previous error status.
+@c !!! what is "socket error status"?  this is never defined.
 @end table
 
 @node Networks Database
@@ -2832,13 +2579,15 @@ the previous error status.
 
 @pindex /etc/networks
 @pindex netdb.h
-Many systems come with a database that records a list of networks
-known to the system developer.  This is usually kept either in the
-file @file{/etc/networks} or in an equivalent from a name server.  We
-know of no practical use for this database, but historically there
-have been functions in the library to access it.  We provide these
-functions for compatibility, and thus we document them here.  They are
-declared in @file{netdb.h}.
+Many systems come with a database that records a list of networks known
+to the system developer.  This is usually kept either in the file
+@file{/etc/networks} or in an equivalent from a name server.  We know of
+no practical use for this database, but historically there have been
+functions in the library to access it.  We provide these functions for
+compatibility, and thus we document them here.  They are declared in
+@file{netdb.h}.
+@c !!! the database is useful for network routing frobbing programs
+@c (e.g., `route').
 
 @comment netdb.h
 @comment BSD
@@ -2906,13 +2655,13 @@ reopening the database for each call.
 
 @comment netdb.h
 @comment BSD
-@deftypefun {struct netent *} getnetent ()
+@deftypefun {struct netent *} getnetent (void)
 This function returns the next entry in the networks database.  It
 returns a null pointer if there are no more entries.
 @end deftypefun
 
 @comment netdb.h
 @comment BSD
-@deftypefun void endnetent ()
+@deftypefun void endnetent (void)
 This function closes the networks database.
 @end deftypefun