Annotation of src/share/doc/psd/21.ipc/3.t, Revision 1.3
1.3 ! agc 1: .\" $NetBSD: 3.t,v 1.2 1998/01/09 06:55:12 perry Exp $
1.2 perry 2: .\"
1.1 cgd 3: .\" Copyright (c) 1986, 1993
4: .\" The Regents of the University of California. All rights reserved.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.3 ! agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
1.2 perry 30: .\" @(#)3.t 8.2 (Berkeley) 6/1/94
1.1 cgd 31: .\"
32: .\".ds RH "Network Library Routines
33: .nr H1 3
34: .nr H2 0
35: .LG
1.2 perry 36: .sp 2
1.1 cgd 37: .B
38: .ce
39: 3. NETWORK LIBRARY ROUTINES
40: .sp 2
41: .R
42: .NL
43: .PP
44: The discussion in section 2 indicated the possible need to
45: locate and construct network addresses when using the
46: interprocess communication facilities in a distributed
47: environment. To aid in this task a number of routines
48: have been added to the standard C run-time library.
49: In this section we will consider the new routines provided
50: to manipulate network addresses. While the 4.4BSD networking
51: facilities support the Internet protocols
52: and the Xerox NS protocols,
53: most of the routines presented
54: in this section do not apply to the NS domain. Unless otherwise
55: stated, it should be assumed that the routines presented in this
56: section do not apply to the NS domain.
57: .PP
58: Locating a service on a remote host requires many levels of
59: mapping before client and server may
60: communicate. A service is assigned a name which is intended
61: for human consumption; e.g. \*(lqthe \fIlogin server\fP on host
62: monet\*(rq.
63: This name, and the name of the peer host, must then be translated
64: into network \fIaddresses\fP which are not necessarily suitable
65: for human consumption. Finally, the address must then used in locating
66: a physical \fIlocation\fP and \fIroute\fP to the service. The
67: specifics of these three mappings are likely to vary between
68: network architectures. For instance, it is desirable for a network
69: to not require hosts to
70: be named in such a way that their physical location is known by
71: the client host. Instead, underlying services in the network
72: may discover the actual location of the host at the time a client
73: host wishes to communicate. This ability to have hosts named in
74: a location independent manner may induce overhead in connection
75: establishment, as a discovery process must take place,
76: but allows a host to be physically mobile without requiring it to
77: notify its clientele of its current location.
78: .PP
79: Standard routines are provided for: mapping host names
80: to network addresses, network names to network numbers,
81: protocol names to protocol numbers, and service names
82: to port numbers and the appropriate protocol to
83: use in communicating with the server process. The
84: file <\fInetdb.h\fP> must be included when using any of these
85: routines.
86: .NH 2
87: Host names
88: .PP
89: An Internet host name to address mapping is represented by
90: the \fIhostent\fP structure:
91: .DS
92: .if t .ta 0.6i 1.1i 2.6i
93: struct hostent {
94: char *h_name; /* official name of host */
95: char **h_aliases; /* alias list */
96: int h_addrtype; /* host address type (e.g., AF_INET) */
97: int h_length; /* length of address */
98: char **h_addr_list; /* list of addresses, null terminated */
99: };
100:
101: #define h_addr h_addr_list[0] /* first address, network byte order */
102: .DE
103: The routine \fIgethostbyname\fP(3N) takes an Internet host name
104: and returns a \fIhostent\fP structure,
105: while the routine \fIgethostbyaddr\fP(3N)
106: maps Internet host addresses into a \fIhostent\fP structure.
107: .PP
108: The official name of the host and its public aliases are
109: returned by these routines,
110: along with the address type (family) and a null terminated list of
111: variable length address. This list of addresses is
112: required because it is possible
113: for a host to have many addresses, all having the same name.
114: The \fIh_addr\fP definition is provided for backward compatibility,
115: and is defined to be the first address in the list of addresses
116: in the \fIhostent\fP structure.
117: .PP
118: The database for these calls is provided either by the
119: file \fI/etc/hosts\fP (\fIhosts\fP\|(5)),
120: or by use of a nameserver, \fInamed\fP\|(8).
121: Because of the differences in these databases and their access protocols,
122: the information returned may differ.
123: When using the host table version of \fIgethostbyname\fP,
124: only one address will be returned, but all listed aliases will be included.
125: The nameserver version may return alternate addresses,
126: but will not provide any aliases other than one given as argument.
127: .PP
128: Unlike Internet names, NS names are always mapped into host
129: addresses by the use of a standard NS \fIClearinghouse service\fP,
130: a distributed name and authentication server. The algorithms
131: for mapping NS names to addresses via a Clearinghouse are
132: rather complicated, and the routines are not part of the
133: standard libraries. The user-contributed Courier (Xerox
134: remote procedure call protocol) compiler contains routines
135: to accomplish this mapping; see the documentation and
136: examples provided therein for more information. It is
137: expected that almost all software that has to communicate
138: using NS will need to use the facilities of
139: the Courier compiler.
140: .PP
141: An NS host address is represented by the following:
142: .DS
143: union ns_host {
144: u_char c_host[6];
145: u_short s_host[3];
146: };
147:
148: union ns_net {
149: u_char c_net[4];
150: u_short s_net[2];
151: };
152:
153: struct ns_addr {
154: union ns_net x_net;
155: union ns_host x_host;
156: u_short x_port;
157: };
158: .DE
159: The following code fragment inserts a known NS address into
160: a \fIns_addr\fP:
161: .DS
162: #include <sys/types.h>
163: #include <sys/socket.h>
164: #include <netns/ns.h>
165: ...
166: u_long netnum;
167: struct sockaddr_ns dst;
168: ...
169: bzero((char *)&dst, sizeof(dst));
170:
171: /*
172: * There is no convenient way to assign a long
173: * integer to a ``union ns_net'' at present; in
174: * the future, something will hopefully be provided,
175: * but this is the portable way to go for now.
176: * The network number below is the one for the NS net
177: * that the desired host (gyre) is on.
178: */
179: netnum = htonl(2266);
180: dst.sns_addr.x_net = *(union ns_net *) &netnum;
181: dst.sns_family = AF_NS;
182:
183: /*
184: * host 2.7.1.0.2a.18 == "gyre:Computer Science:UofMaryland"
185: */
186: dst.sns_addr.x_host.c_host[0] = 0x02;
187: dst.sns_addr.x_host.c_host[1] = 0x07;
188: dst.sns_addr.x_host.c_host[2] = 0x01;
189: dst.sns_addr.x_host.c_host[3] = 0x00;
190: dst.sns_addr.x_host.c_host[4] = 0x2a;
191: dst.sns_addr.x_host.c_host[5] = 0x18;
192: dst.sns_addr.x_port = htons(75);
193: .DE
194: .NH 2
195: Network names
196: .PP
197: As for host names, routines for mapping network names to numbers,
198: and back, are provided. These routines return a \fInetent\fP
199: structure:
200: .DS
201: .DT
202: /*
203: * Assumption here is that a network number
204: * fits in 32 bits -- probably a poor one.
205: */
206: struct netent {
207: char *n_name; /* official name of net */
208: char **n_aliases; /* alias list */
209: int n_addrtype; /* net address type */
210: int n_net; /* network number, host byte order */
211: };
212: .DE
213: The routines \fIgetnetbyname\fP(3N), \fIgetnetbynumber\fP(3N),
214: and \fIgetnetent\fP(3N) are the network counterparts to the
215: host routines described above. The routines extract their
216: information from \fI/etc/networks\fP.
217: .PP
218: NS network numbers are determined either by asking your local
219: Xerox Network Administrator (and hardcoding the information
220: into your code), or by querying the Clearinghouse for addresses.
221: The internetwork router is the only process
222: that needs to manipulate network numbers on a regular basis; if
223: a process wishes to communicate with a machine, it should ask the
224: Clearinghouse for that machine's address (which will include
225: the net number).
226: .NH 2
227: Protocol names
228: .PP
229: For protocols, which are defined in \fI/etc/protocols\fP,
230: the \fIprotoent\fP structure defines the
231: protocol-name mapping
232: used with the routines \fIgetprotobyname\fP(3N),
233: \fIgetprotobynumber\fP(3N),
234: and \fIgetprotoent\fP(3N):
235: .DS
236: .DT
237: struct protoent {
238: char *p_name; /* official protocol name */
239: char **p_aliases; /* alias list */
240: int p_proto; /* protocol number */
241: };
242: .DE
243: .PP
244: In the NS domain, protocols are indicated by the "client type"
245: field of a IDP header. No protocol database exists; see section
246: 5 for more information.
247: .NH 2
248: Service names
249: .PP
250: Information regarding services is a bit more complicated. A service
251: is expected to reside at a specific \*(lqport\*(rq and employ
252: a particular communication protocol. This view is consistent with
253: the Internet domain, but inconsistent with other network architectures.
254: Further, a service may reside on multiple ports.
255: If this occurs, the higher level library routines
256: will have to be bypassed or extended.
257: Services available are contained in the file \fI/etc/services\fP.
258: A service mapping is described by the \fIservent\fP structure,
259: .DS
260: .DT
261: struct servent {
262: char *s_name; /* official service name */
263: char **s_aliases; /* alias list */
264: int s_port; /* port number, network byte order */
265: char *s_proto; /* protocol to use */
266: };
267: .DE
268: The routine \fIgetservbyname\fP(3N) maps service
269: names to a servent structure by specifying a service name and,
270: optionally, a qualifying protocol. Thus the call
271: .DS
272: sp = getservbyname("telnet", (char *) 0);
273: .DE
274: returns the service specification for a telnet server using
275: any protocol, while the call
276: .DS
277: sp = getservbyname("telnet", "tcp");
278: .DE
279: returns only that telnet server which uses the TCP protocol.
280: The routines \fIgetservbyport\fP(3N) and \fIgetservent\fP(3N) are
281: also provided. The \fIgetservbyport\fP routine has an interface similar
282: to that provided by \fIgetservbyname\fP; an optional protocol name may
283: be specified to qualify lookups.
284: .PP
285: In the NS domain, services are handled by a central dispatcher
286: provided as part of the Courier remote procedure call facilities.
287: Again, the reader is referred to the Courier compiler documentation
288: and to the Xerox standard*
289: .FS
290: * \fICourier: The Remote Procedure Call Protocol\fP, XSIS 038112.
291: .FE
292: for further details.
293: .NH 2
294: Miscellaneous
295: .PP
296: With the support routines described above, an Internet application program
297: should rarely have to deal directly
298: with addresses. This allows
299: services to be developed as much as possible in a network independent
300: fashion. It is clear, however, that purging all network dependencies
301: is very difficult. So long as the user is required to supply network
302: addresses when naming services and sockets there will always some
303: network dependency in a program. For example, the normal
304: code included in client programs, such as the remote login program,
305: is of the form shown in Figure 1.
306: (This example will be considered in more detail in section 4.)
307: .PP
308: If we wanted to make the remote login program independent of the
309: Internet protocols and addressing scheme we would be forced to add
310: a layer of routines which masked the network dependent aspects from
311: the mainstream login code. For the current facilities available in
312: the system this does not appear to be worthwhile.
313: .PP
314: Aside from the address-related data base routines, there are several
315: other routines available in the run-time library which are of interest
316: to users. These are intended mostly to simplify manipulation of
317: names and addresses. Table 1 summarizes the routines
318: for manipulating variable length byte strings and handling byte
319: swapping of network addresses and values.
320: .KF
321: .DS B
322: .TS
323: box;
324: l | l
325: l | l.
326: Call Synopsis
327: _
328: bcmp(s1, s2, n) compare byte-strings; 0 if same, not 0 otherwise
329: bcopy(s1, s2, n) copy n bytes from s1 to s2
330: bzero(base, n) zero-fill n bytes starting at base
331: htonl(val) convert 32-bit quantity from host to network byte order
332: htons(val) convert 16-bit quantity from host to network byte order
333: ntohl(val) convert 32-bit quantity from network to host byte order
334: ntohs(val) convert 16-bit quantity from network to host byte order
335: .TE
336: .DE
337: .ce
338: Table 1. C run-time routines.
339: .KE
340: .PP
341: The byte swapping routines are provided because the operating
342: system expects addresses to be supplied in network order (aka ``big-endian'' order). On
343: ``little-endian'' architectures, such as Intel x86 and VAX,
344: host byte ordering is different than
345: network byte ordering. Consequently,
346: programs are sometimes required to byte swap quantities. The
347: library routines which return network addresses provide them
348: in network order so that they may simply be copied into the structures
349: provided to the system. This implies users should encounter the
350: byte swapping problem only when \fIinterpreting\fP network addresses.
351: For example, if an Internet port is to be printed out the following
352: code would be required:
353: .DS
354: printf("port number %d\en", ntohs(sp->s_port));
355: .DE
356: On machines where unneeded these routines are defined as null
357: macros.
358: .DS
359: .if t .ta .5i 1.0i 1.5i 2.0i
360: .if n .ta .7i 1.4i 2.1i 2.8i
361: #include <sys/types.h>
362: #include <sys/socket.h>
363: #include <netinet/in.h>
364: #include <stdio.h>
365: #include <netdb.h>
366: ...
367: main(argc, argv)
368: int argc;
369: char *argv[];
370: {
371: struct sockaddr_in server;
372: struct servent *sp;
373: struct hostent *hp;
374: int s;
375: ...
376: sp = getservbyname("login", "tcp");
377: if (sp == NULL) {
378: fprintf(stderr, "rlogin: tcp/login: unknown service\en");
379: exit(1);
380: }
381: hp = gethostbyname(argv[1]);
382: if (hp == NULL) {
383: fprintf(stderr, "rlogin: %s: unknown host\en", argv[1]);
384: exit(2);
385: }
386: bzero((char *)&server, sizeof (server));
387: bcopy(hp->h_addr, (char *)&server.sin_addr, hp->h_length);
388: server.sin_family = hp->h_addrtype;
389: server.sin_port = sp->s_port;
390: s = socket(AF_INET, SOCK_STREAM, 0);
391: if (s < 0) {
392: perror("rlogin: socket");
393: exit(3);
394: }
395: ...
396: /* Connect does the bind() for us */
397:
398: if (connect(s, (char *)&server, sizeof (server)) < 0) {
399: perror("rlogin: connect");
400: exit(5);
401: }
402: ...
403: }
404: .DE
405: .ce
406: Figure 1. Remote login client code.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to 3.t CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / share / doc / psd / 21.ipc