BSD 4_4 release

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

diff --git a/usr/src/share/doc/psd/21.ipc/3.t b/usr/src/share/doc/psd/21.ipc/3.t
index b14c361..0d429cf 100644 (file)
--- a/usr/src/share/doc/psd/21.ipc/3.t
+++ b/usr/src/share/doc/psd/21.ipc/3.t
@@ -1,4 +1,37 @@
-.ds RH "Network Library Routines
+.\" Copyright (c) 1986, 1993
+.\"    The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"    @(#)3.t 8.1 (Berkeley) 6/8/93
+.\"
+.\".ds RH "Network Library Routines

 .bp
 .nr H1 3
 .nr H2 0
 .bp
 .nr H1 3
 .nr H2 0


@@ -17,16 +50,13 @@ interprocess communication facilities in a distributed
 environment.  To aid in this task a number of routines
 have been added to the standard C run-time library.
 In this section we will consider the new routines provided
 environment.  To aid in this task a number of routines
 have been added to the standard C run-time library.
 In this section we will consider the new routines provided

-to manipulate network addresses.  While the 4.2BSD networking
-facilities support only the DARPA standard Internet protocols,
-these routines have been designed with flexibility in mind.
-As more communication protocols become available, we hope
-the same user interface will be maintained in accessing
-network-related address data bases.  The only difference
-should be the values returned to the user.  Since these
-values are normally supplied the system, users should
-not need to be directly aware of the communication protocol
-and/or naming conventions in use.
+to manipulate network addresses.  While the 4.4BSD networking
+facilities support the Internet protocols
+and the Xerox NS protocols,
+most of the routines presented
+in this section do not apply to the NS domain.  Unless otherwise
+stated, it should be assumed that the routines presented in this
+section do not apply to the NS domain.

 .PP
 Locating a service on a remote host requires many levels of
 mapping before client and server may
 .PP
 Locating a service on a remote host requires many levels of
 mapping before client and server may


@@ -37,9 +67,9 @@ This name, and the name of the peer host, must then be translated
 into network \fIaddresses\fP which are not necessarily suitable
 for human consumption.  Finally, the address must then used in locating
 a physical \fIlocation\fP and \fIroute\fP to the service.  The
 into network \fIaddresses\fP which are not necessarily suitable
 for human consumption.  Finally, the address must then used in locating
 a physical \fIlocation\fP and \fIroute\fP to the service.  The

-specifics of these three mappings is likely to vary between
+specifics of these three mappings are likely to vary between

 network architectures.  For instance, it is desirable for a network
 network architectures.  For instance, it is desirable for a network

-to not require hosts
+to not require hosts to

 be named in such a way that their physical location is known by
 the client host.  Instead, underlying services in the network
 may discover the actual location of the host at the time a client
 be named in such a way that their physical location is known by
 the client host.  Instead, underlying services in the network
 may discover the actual location of the host at the time a client


@@ -59,68 +89,111 @@ routines.
 .NH 2
 Host names
 .PP
 .NH 2
 Host names
 .PP

-A host name to address mapping is represented by
+An Internet host name to address mapping is represented by

 the \fIhostent\fP structure:
 .DS
 the \fIhostent\fP structure:
 .DS

-.DT
+.if t .ta 0.6i 1.1i 2.6i

 struct hostent {
        char    *h_name;        /* official name of host */
        char    **h_aliases;    /* alias list */
 struct hostent {
        char    *h_name;        /* official name of host */
        char    **h_aliases;    /* alias list */

-       int     h_addrtype;     /* host address type */
+       int     h_addrtype;     /* host address type (e.g., AF_INET) */

        int     h_length;       /* length of address */
        int     h_length;       /* length of address */

-       char    *h_addr;        /* address */
+       char    **h_addr_list;  /* list of addresses, null terminated */

 };
 };

+
+#define        h_addr  h_addr_list[0]  /* first address, network byte order */

 .DE
 .DE

-The official name of the host and its public aliases are
-returned, along with a variable length address and address
-type.  The routine \fIgethostbyname\fP(3N) takes a host name
+The routine \fIgethostbyname\fP(3N) takes an Internet host name

 and returns a \fIhostent\fP structure,
 while the routine \fIgethostbyaddr\fP(3N)
 and returns a \fIhostent\fP structure,
 while the routine \fIgethostbyaddr\fP(3N)

-maps host addresses into a \fIhostent\fP structure.  It is possible
+maps Internet host addresses into a \fIhostent\fP structure.
+.PP
+The official name of the host and its public aliases are
+returned by these routines,
+along with the address type (family) and a null terminated list of
+variable length address.  This list of addresses is
+required because it is possible

 for a host to have many addresses, all having the same name.
 for a host to have many addresses, all having the same name.

-\fIGethostybyname\fP returns the first matching entry in the data
-base file \fI/etc/hosts\fP; if this is unsuitable, the lower level
-routine \fIgethostent\fP(3N) may be used.  For example, to
-obtain a \fIhostent\fP structure for a
-host on a particular network the following routine might be
-used (for simplicity, only Internet addresses are considered):
+The \fIh_addr\fP definition is provided for backward compatibility,
+and is defined to be the first address in the list of addresses
+in the \fIhostent\fP structure.
+.PP
+The database for these calls is provided either by the
+file \fI/etc/hosts\fP (\fIhosts\fP\|(5)),
+or by use of a nameserver, \fInamed\fP\|(8).
+Because of the differences in these databases and their access protocols,
+the information returned may differ.
+When using the host table version of \fIgethostbyname\fP,
+only one address will be returned, but all listed aliases will be included.
+The nameserver version may return alternate addresses,
+but will not provide any aliases other than one given as argument.
+.PP
+Unlike Internet names, NS names are always mapped into host
+addresses by the use of a standard NS \fIClearinghouse service\fP,
+a distributed name and authentication server.  The algorithms
+for mapping NS names to addresses via a Clearinghouse are
+rather complicated, and the routines are not part of the
+standard libraries.  The user-contributed Courier (Xerox
+remote procedure call protocol) compiler contains routines
+to accomplish this mapping; see the documentation and
+examples provided therein for more information.  It is
+expected that almost all software that has to communicate
+using NS will need to use the facilities of
+the Courier compiler.
+.PP
+An NS host address is represented by the following:
+.DS
+union ns_host {
+       u_char  c_host[6];
+       u_short s_host[3];
+};
+
+union ns_net {
+       u_char  c_net[4];
+       u_short s_net[2];
+};
+
+struct ns_addr {
+       union ns_net    x_net;
+       union ns_host   x_host;
+       u_short x_port;
+};
+.DE
+The following code fragment inserts a known NS address into
+a \fIns_addr\fP:

 .DS
 .DS

-.if t .ta .5i 1.0i 1.5i 2.0i
-.\" 3.5i went to 3.8i
-.if n .ta .7i 1.4i 2.1i 2.8i 3.5i 4.2i

 #include <sys/types.h>
 #include <sys/socket.h>
 #include <sys/types.h>
 #include <sys/socket.h>

-#include <netinet/in.h>
-#include <netdb.h>
+#include <netns/ns.h>

  ...
  ...

-struct hostent *
-gethostbynameandnet(name, net)
-       char *name;
-       int net;
-{
-       register struct hostent *hp;
-       register char **cp;
+u_long netnum;
+struct sockaddr_ns dst;
+ ...
+bzero((char *)&dst, sizeof(dst));

 
 

-       sethostent(0);
-       while ((hp = gethostent()) != NULL) {
-               if (hp->h_addrtype != AF_INET)
-                       continue;
-               if (strcmp(name, hp->h_name)) {
-                       for (cp = hp->h_aliases; cp && *cp != NULL; cp++)
-                               if (strcmp(name, *cp) == 0)
-                                       goto found;
-                       continue;
-               }
-       found:
-               if (in_netof(*(struct in_addr *)hp->h_addr)) == net)
-                       break;
-       }
-       endhostent(0);
-       return (hp);
-}
+/*
+ * There is no convenient way to assign a long
+ * integer to a ``union ns_net'' at present; in
+ * the future, something will hopefully be provided,
+ * but this is the portable way to go for now.
+ * The network number below is the one for the NS net
+ * that the desired host (gyre) is on.
+ */
+netnum = htonl(2266);
+dst.sns_addr.x_net = *(union ns_net *) &netnum;
+dst.sns_family = AF_NS;
+
+/*
+ * host 2.7.1.0.2a.18 == "gyre:Computer Science:UofMaryland"
+ */
+dst.sns_addr.x_host.c_host[0] = 0x02;
+dst.sns_addr.x_host.c_host[1] = 0x07;
+dst.sns_addr.x_host.c_host[2] = 0x01;
+dst.sns_addr.x_host.c_host[3] = 0x00;
+dst.sns_addr.x_host.c_host[4] = 0x2a;
+dst.sns_addr.x_host.c_host[5] = 0x18;
+dst.sns_addr.x_port = htons(75);

 .DE
 .DE

-(\fIin_netof\fP(3N) is a standard routine which returns
-the network portion of an Internet address.)

 .NH 2
 Network names
 .PP
 .NH 2
 Network names
 .PP


@@ -137,16 +210,27 @@ struct    netent {
        char    *n_name;        /* official name of net */
        char    **n_aliases;    /* alias list */
        int     n_addrtype;     /* net address type */
        char    *n_name;        /* official name of net */
        char    **n_aliases;    /* alias list */
        int     n_addrtype;     /* net address type */

-       int     n_net;  /* network # */
+       int     n_net;  /* network number, host byte order */

 };
 .DE
 The routines \fIgetnetbyname\fP(3N), \fIgetnetbynumber\fP(3N),
 and \fIgetnetent\fP(3N) are the network counterparts to the
 };
 .DE
 The routines \fIgetnetbyname\fP(3N), \fIgetnetbynumber\fP(3N),
 and \fIgetnetent\fP(3N) are the network counterparts to the

-host routines described above.
+host routines described above.  The routines extract their
+information from \fI/etc/networks\fP.
+.PP
+NS network numbers are determined either by asking your local
+Xerox Network Administrator (and hardcoding the information
+into your code), or by querying the Clearinghouse for addresses.
+The internetwork router is the only process
+that needs to manipulate network numbers on a regular basis; if
+a process wishes to communicate with a machine, it should ask the
+Clearinghouse for that machine's address (which will include
+the net number).

 .NH 2
 Protocol names
 .PP
 .NH 2
 Protocol names
 .PP

-For protocols the \fIprotoent\fP structure defines the
+For protocols, which are defined in \fI/etc/protocols\fP,
+the \fIprotoent\fP structure defines the

 protocol-name mapping
 used with the routines \fIgetprotobyname\fP(3N),
 \fIgetprotobynumber\fP(3N),
 protocol-name mapping
 used with the routines \fIgetprotobyname\fP(3N),
 \fIgetprotobynumber\fP(3N),


@@ -156,9 +240,13 @@ and \fIgetprotoent\fP(3N):
 struct protoent {
        char    *p_name;        /* official protocol name */
        char    **p_aliases;    /* alias list */
 struct protoent {
        char    *p_name;        /* official protocol name */
        char    **p_aliases;    /* alias list */

-       int     p_proto;        /* protocol # */
+       int     p_proto;        /* protocol number */

 };
 .DE
 };
 .DE

+.PP
+In the NS domain, protocols are indicated by the "client type"
+field of a IDP header.  No protocol database exists; see section
+5 for more information.

 .NH 2
 Service names
 .PP
 .NH 2
 Service names
 .PP


@@ -166,17 +254,17 @@ Information regarding services is a bit more complicated.  A service
 is expected to reside at a specific \*(lqport\*(rq and employ
 a particular communication protocol.  This view is consistent with
 the Internet domain, but inconsistent with other network architectures.
 is expected to reside at a specific \*(lqport\*(rq and employ
 a particular communication protocol.  This view is consistent with
 the Internet domain, but inconsistent with other network architectures.

-Further, a service may reside on multiple ports or support multiple
-protocols.  If either of these occurs, the higher level library routines
-will have to be bypassed in favor of homegrown routines similar in
-spirit to the \*(lqgethostbynameandnet\*(rq routine described above.
+Further, a service may reside on multiple ports.
+If this occurs, the higher level library routines
+will have to be bypassed or extended.
+Services available are contained in the file \fI/etc/services\fP.

 A service mapping is described by the \fIservent\fP structure,
 .DS
 .DT
 struct servent {
        char    *s_name;        /* official service name */
        char    **s_aliases;    /* alias list */
 A service mapping is described by the \fIservent\fP structure,
 .DS
 .DT
 struct servent {
        char    *s_name;        /* official service name */
        char    **s_aliases;    /* alias list */

-       int     s_port; /* port # */
+       int     s_port; /* port number, network byte order */

        char    *s_proto;       /* protocol to use */
 };
 .DE
        char    *s_proto;       /* protocol to use */
 };
 .DE


@@ -184,7 +272,7 @@ The routine \fIgetservbyname\fP(3N) maps service
 names to a servent structure by specifying a service name and,
 optionally, a qualifying protocol.  Thus the call
 .DS
 names to a servent structure by specifying a service name and,
 optionally, a qualifying protocol.  Thus the call
 .DS

-sp = getservbyname("telnet", (char *)0);
+sp = getservbyname("telnet", (char *) 0);

 .DE
 returns the service specification for a telnet server using
 any protocol, while the call
 .DE
 returns the service specification for a telnet server using
 any protocol, while the call


@@ -196,10 +284,19 @@ The routines \fIgetservbyport\fP(3N) and \fIgetservent\fP(3N) are
 also provided.  The \fIgetservbyport\fP routine has an interface similar
 to that provided by \fIgetservbyname\fP; an optional protocol name may
 be specified to qualify lookups.
 also provided.  The \fIgetservbyport\fP routine has an interface similar
 to that provided by \fIgetservbyname\fP; an optional protocol name may
 be specified to qualify lookups.

+.PP
+In the NS domain, services are handled by a central dispatcher
+provided as part of the Courier remote procedure call facilities.
+Again, the reader is referred to the Courier compiler documentation
+and to the Xerox standard*
+.FS
+* \fICourier: The Remote Procedure Call Protocol\fP, XSIS 038112.
+.FE
+for further details.

 .NH 2
 Miscellaneous
 .PP
 .NH 2
 Miscellaneous
 .PP

-With the support routines described above, an application program
+With the support routines described above, an Internet application program

 should rarely have to deal directly
 with addresses.  This allows
 services to be developed as much as possible in a network independent
 should rarely have to deal directly
 with addresses.  This allows
 services to be developed as much as possible in a network independent


@@ -209,63 +306,13 @@ addresses when naming services and sockets there will always some
 network dependency in a program.  For example, the normal
 code included in client programs, such as the remote login program,
 is of the form shown in Figure 1.
 network dependency in a program.  For example, the normal
 code included in client programs, such as the remote login program,
 is of the form shown in Figure 1.

-.KF
-.DS
-.if t .ta .5i 1.0i 1.5i 2.0i
-.if n .ta .7i 1.4i 2.1i 2.8i
-#include <sys/types.h>
-#include <sys/socket.h>
-#include <netinet/in.h>
-#include <stdio.h>
-#include <netdb.h>
- ...
-main(argc, argv)
-       char *argv[];
-{
-       struct sockaddr_in sin;
-       struct servent *sp;
-       struct hostent *hp;
-       int s;
-       ...
-       sp = getservbyname("login", "tcp");
-       if (sp == NULL) {
-               fprintf(stderr, "rlogin: tcp/login: unknown service\en");
-               exit(1);
-       }
-       hp = gethostbyname(argv[1]);
-       if (hp == NULL) {
-               fprintf(stderr, "rlogin: %s: unknown host\en", argv[1]);
-               exit(2);
-       }
-       bzero((char *)&sin, sizeof (sin));
-       bcopy(hp->h_addr, (char *)&sin.sin_addr, hp->h_length);
-       sin.sin_family = hp->h_addrtype;
-       sin.sin_port = sp->s_port;
-       s = socket(AF_INET, SOCK_STREAM, 0);
-       if (s < 0) {
-               perror("rlogin: socket");
-               exit(3);
-       }
-       ...
-       if (connect(s, (char *)&sin, sizeof (sin)) < 0) {
-               perror("rlogin: connect");
-               exit(5);
-       }
-       ...
-}
-.DE
-.ce
-Figure 1.  Remote login client code.
-.KE

 (This example will be considered in more detail in section 4.)
 .PP
 If we wanted to make the remote login program independent of the 
 Internet protocols and addressing scheme we would be forced to add
 a layer of routines which masked the network dependent aspects from
 the mainstream login code.  For the current facilities available in
 (This example will be considered in more detail in section 4.)
 .PP
 If we wanted to make the remote login program independent of the 
 Internet protocols and addressing scheme we would be forced to add
 a layer of routines which masked the network dependent aspects from
 the mainstream login code.  For the current facilities available in

-the system this does not appear to be worthwhile.  Perhaps when the
-system is adapted to different network architectures the utilities
-will be reorganized more cleanly.
+the system this does not appear to be worthwhile.

 .PP
 Aside from the address-related data base routines, there are several
 other routines available in the run-time library which are of interest
 .PP
 Aside from the address-related data base routines, there are several
 other routines available in the run-time library which are of interest


@@ -295,9 +342,10 @@ Table 1.  C run-time routines.
 .KE
 .PP
 The byte swapping routines are provided because the operating
 .KE
 .PP
 The byte swapping routines are provided because the operating

-system expects addresses to be supplied in network order.  On a
-VAX, or machine with similar architecture, this
-is usually reversed.  Consequently,
+system expects addresses to be supplied in network order (aka ``big-endian'' order).  On
+``little-endian'' architectures, such as Intel x86 and VAX,
+host byte ordering is different than
+network byte ordering.  Consequently,

 programs are sometimes required to byte swap quantities.  The
 library routines which return network addresses provide them
 in network order so that they may simply be copied into the structures
 programs are sometimes required to byte swap quantities.  The
 library routines which return network addresses provide them
 in network order so that they may simply be copied into the structures


@@ -308,5 +356,54 @@ code would be required:
 .DS
 printf("port number %d\en", ntohs(sp->s_port));
 .DE
 .DS
 printf("port number %d\en", ntohs(sp->s_port));
 .DE

-On machines other than the VAX these routines are defined as null
+On machines where unneeded these routines are defined as null

 macros.
 macros.

+.DS
+.if t .ta .5i 1.0i 1.5i 2.0i
+.if n .ta .7i 1.4i 2.1i 2.8i
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <netinet/in.h>
+#include <stdio.h>
+#include <netdb.h>
+ ...
+main(argc, argv)
+       int argc;
+       char *argv[];
+{
+       struct sockaddr_in server;
+       struct servent *sp;
+       struct hostent *hp;
+       int s;
+       ...
+       sp = getservbyname("login", "tcp");
+       if (sp == NULL) {
+               fprintf(stderr, "rlogin: tcp/login: unknown service\en");
+               exit(1);
+       }
+       hp = gethostbyname(argv[1]);
+       if (hp == NULL) {
+               fprintf(stderr, "rlogin: %s: unknown host\en", argv[1]);
+               exit(2);
+       }
+       bzero((char *)&server, sizeof (server));
+       bcopy(hp->h_addr, (char *)&server.sin_addr, hp->h_length);
+       server.sin_family = hp->h_addrtype;
+       server.sin_port = sp->s_port;
+       s = socket(AF_INET, SOCK_STREAM, 0);
+       if (s < 0) {
+               perror("rlogin: socket");
+               exit(3);
+       }
+       ...
+       /* Connect does the bind() for us */
+
+       if (connect(s, (char *)&server, sizeof (server)) < 0) {
+               perror("rlogin: connect");
+               exit(5);
+       }
+       ...
+}
+.DE
+.ce
+Figure 1.  Remote login client code.