diff options
Diffstat (limited to 'share/doc/psd/21.ipc/3.t')
| -rw-r--r-- | share/doc/psd/21.ipc/3.t | 407 |
1 files changed, 0 insertions, 407 deletions
diff --git a/share/doc/psd/21.ipc/3.t b/share/doc/psd/21.ipc/3.t deleted file mode 100644 index 42ba6799e26..00000000000 --- a/share/doc/psd/21.ipc/3.t +++ /dev/null @@ -1,407 +0,0 @@ -.\" $OpenBSD: 3.t,v 1.3 2003/06/02 23:30:10 millert Exp $ -.\" -.\" 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. 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 -.LG -.B -.ce -3. NETWORK LIBRARY ROUTINES -.sp 2 -.R -.NL -.PP -The discussion in section 2 indicated the possible need to -locate and construct network addresses when using the -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 -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 -communicate. A service is assigned a name which is intended -for human consumption; e.g. \*(lqthe \fIlogin server\fP on host -monet\*(rq. -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 -specifics of these three mappings are likely to vary between -network architectures. For instance, it is desirable for a network -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 -host wishes to communicate. This ability to have hosts named in -a location independent manner may induce overhead in connection -establishment, as a discovery process must take place, -but allows a host to be physically mobile without requiring it to -notify its clientele of its current location. -.PP -Standard routines are provided for: mapping host names -to network addresses, network names to network numbers, -protocol names to protocol numbers, and service names -to port numbers and the appropriate protocol to -use in communicating with the server process. The -file <\fInetdb.h\fP> must be included when using any of these -routines. -.NH 2 -Host names -.PP -An Internet host name to address mapping is represented by -the \fIhostent\fP structure: -.DS -.if t .ta 0.6i 1.1i 2.6i -struct hostent { - char *h_name; /* official name of host */ - char **h_aliases; /* alias list */ - int h_addrtype; /* host address type (e.g., AF_INET) */ - int h_length; /* length of address */ - char **h_addr_list; /* list of addresses, null terminated */ -}; - -#define h_addr h_addr_list[0] /* first address, network byte order */ -.DE -The routine \fIgethostbyname\fP(3N) takes an Internet host name -and returns a \fIhostent\fP structure, -while the routine \fIgethostbyaddr\fP(3N) -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. -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 -#include <sys/types.h> -#include <sys/socket.h> -#include <netns/ns.h> - ... -u_long netnum; -struct sockaddr_ns dst; - ... -bzero((char *)&dst, sizeof(dst)); - -/* - * 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 -.NH 2 -Network names -.PP -As for host names, routines for mapping network names to numbers, -and back, are provided. These routines return a \fInetent\fP -structure: -.DS -.DT -/* - * Assumption here is that a network number - * fits in 32 bits -- probably a poor one. - */ -struct netent { - char *n_name; /* official name of net */ - char **n_aliases; /* alias list */ - int n_addrtype; /* net address type */ - 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 -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 -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), -and \fIgetprotoent\fP(3N): -.DS -.DT -struct protoent { - char *p_name; /* official protocol name */ - char **p_aliases; /* alias list */ - int p_proto; /* protocol number */ -}; -.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 -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. -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 */ - int s_port; /* port number, network byte order */ - char *s_proto; /* protocol to use */ -}; -.DE -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 -sp = getservbyname("telnet", (char *) 0); -.DE -returns the service specification for a telnet server using -any protocol, while the call -.DS -sp = getservbyname("telnet", "tcp"); -.DE -returns only that telnet server which uses the TCP protocol. -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. -.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 -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 -fashion. It is clear, however, that purging all network dependencies -is very difficult. So long as the user is required to supply network -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. -(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. -.PP -Aside from the address-related data base routines, there are several -other routines available in the run-time library which are of interest -to users. These are intended mostly to simplify manipulation of -names and addresses. Table 1 summarizes the routines -for manipulating variable length byte strings and handling byte -swapping of network addresses and values. -.KF -.DS B -.TS -box; -l | l -l | l. -Call Synopsis -_ -bcmp(s1, s2, n) compare byte-strings; 0 if same, not 0 otherwise -bcopy(s1, s2, n) copy n bytes from s1 to s2 -bzero(base, n) zero-fill n bytes starting at base -htonl(val) convert 32-bit quantity from host to network byte order -htons(val) convert 16-bit quantity from host to network byte order -ntohl(val) convert 32-bit quantity from network to host byte order -ntohs(val) convert 16-bit quantity from network to host byte order -.TE -.DE -.ce -Table 1. C run-time routines. -.KE -.PP -The byte swapping routines are provided because the operating -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 -provided to the system. This implies users should encounter the -byte swapping problem only when \fIinterpreting\fP network addresses. -For example, if an Internet port is to be printed out the following -code would be required: -.DS -printf("port number %d\en", ntohs(sp->s_port)); -.DE -On machines where unneeded these routines are defined as null -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. |