![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to rpc.prog CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / librpc / doc|
Return to rpc.prog CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / librpc / doc |
1.1 root 1: .OH 'RPC Programming''Page \\\\n(PN'
2: .EH 'Page \\\\n(PN''RPC Programming'
3: .OF 'Sun Microsystems''Release 2.0'
4: .EF 'Release 2.0''Sun Microsystems'
5: .RP
6: .rm DY
7: .TL
8: .ps 20
9: Remote Procedure Call
10: .sp.5
11: Programming Guide
12: .
13: .H 1 "Introduction"
14: .LP
15: Programs that communicate over a network
16: need a paradigm for communication.
17: A low-level mechanism might
18: send a signal on the arrival of incoming packets,
19: causing a network signal handler to execute.
20: A high-level mechanism would be the Ada
21: .L rendezvous .
22: The method used at Sun is the
23: Remote Procedure Call (RPC) paradigm,
24: in which a client communicates with a server.
25: In this process,
26: the client first calls a procedure to send a data packet to the server.
27: When the packet arrives, the server calls a dispatch routine,
28: performs whatever service is requested, sends back the reply,
29: and the procedure call returns to the client.
30: .LP
31: The RPC interface is divided into three layers.
32: The highest layer is totally transparent to the programmer.
33: To illustrate,
34: at this level a program can contain a call to
35: .L rnusers() ,
36: which returns the number of users on a remote machine.
37: You don't have to be aware that RPC is being used,
38: since you simply make the call in a program,
39: just as you would call
40: .L malloc() .
41: .LP
42: At the middle layer, the routines
43: .L registerrpc()
44: and
45: .L callrpc()
46: are used to make RPC calls:
47: .L registerrpc()
48: obtains a unique system-wide number, while
49: .L callrpc()
50: executes a remote procedure call.
51: The
52: .L rnusers()
53: call is implemented using these two routines
54: The middle-layer routines are designed for most common applications,
55: and shield the user from knowing about sockets.
56: .LP
57: The lowest layer is used for more sophisticated applications,
58: which may want to alter the defaults of the routines.
59: At this layer, you can explicitly manipulate
60: sockets used for transmitting RPC messages.
61: This level should be avoided if possible.
62: .LP
63: Section 2 of this manual illustrates use of the highest two layers
64: while Section 3 presents the low-level interface.
65: Section 4 of the manual discusses miscellaneous topics.
66: The final section summarizes
67: all the entry points into the RPC system.
68: .LP
69: Although this document only discusses the interface to C,
70: remote procedure calls can be made from any language.
71: Even though this document discusses RPC
72: when it is used to communicate
73: between processes on different machines,
74: it works just as well for communication
75: between different processes on the same machine.
76: .bp
77: .
78: .H 1 "Introductory Examples"
79: .H 2 "Highest Layer"
80: .LP
81: Imagine you're writing a program that needs to know
82: how many users are logged into a remote machine.
83: You can do this by calling the library routine
84: .L rnusers() ,
85: as illustrated below:
86: .LS
87: #include <stdio.h>
88: .sp.5
89: main(argc, argv)
90: int argc;
91: char **argv;
92: {
93: unsigned num;
94: .sp.5
95: if (argc < 2) {
96: fprintf(stderr, "usage: rnusers hostname\en");
97: exit(1);
98: }
99: if ((num = rnusers(argv[1])) < 0) {
100: fprintf(stderr, "error: rnusers\en");
101: exit(-1);
102: }
103: printf("%d users on %s\en", num, argv[1]);
104: exit(0);
105: }
106: .LE
107: RPC library routines such as
108: .L rnusers()
109: are included in the C library
110: .L libc.a .
111: Thus, the program above could be compiled with
112: .LS
113: % cc \fIprogram.c\fP
114: .LE
115: Some other library routines are
116: .L rstat()
117: to gather remote performance statistics, and
118: .L ypmatch()
119: to glean information from the yellow pages (YP).
120: The YP library routines are documented on the manual page
121: .I ypclnt (3N).
122: .bp
123: .
124: .H 2 "Intermediate Layer"
125: .LP
126: The simplest interface, which explicitly makes RPC
127: calls, uses the functions
128: .L callrpc()
129: and
130: .L registerrpc() .
131: Using this method, another way to get the number of remote users is:
132: .LS
133: #include <stdio.h>
134: #include <rpcsvc/rusers.h>
135: .sp.5
136: main(argc, argv)
137: int argc;
138: char **argv;
139: {
140: unsigned long nusers;
141: .sp.5
142: if (argc < 2) {
143: fprintf(stderr, "usage: nusers hostname\en");
144: exit(-1);
145: }
146: if (callrpc(argv[1], RUSERSPROG, RUSERSVERS, RUSERSPROC_NUM,
147: xdr_void, 0, xdr_u_long, &nusers) != 0) {
148: fprintf(stderr, "error: callrpc\en");
149: exit(1);
150: }
151: printf("number of users on %s is %d\en", argv[1], nusers);
152: exit(0);
153: }
154: .LE
155: A program number, version number, and procedure number
156: defines each RPC procedure.
157: The program number defines a group
158: of related remote procedures, each of which has a different
159: procedure number.
160: Each program also has a version number,
161: so when a minor change is made to a remote service
162: (adding a new procedure, for example),
163: a new program number doesn't have to be assigned.
164: When you want to call a procedure to
165: find the number of remote users, you look up the appropriate
166: program, version and procedure numbers
167: in a manual, similar to when you look up the name of memory
168: allocator when you want to allocate memory.
169: .LP
170: The simplest routine in the RPC library
171: used to make remote procedure calls is
172: .L callrpc() .
173: It has eight parameters.
174: The first is the name of the remote machine.
175: The next three parameters
176: are the program, version, and procedure numbers.
177: The following two parameters
178: define the argument of the RPC call, and the final two parameters
179: are for the return value of the call.
180: If it completes successfully,
181: .L callrpc()
182: returns zero, but nonzero otherwise.
183: The exact meaning of the return codes is found in
184: .L <rpc/clnt.h> ,
185: and is in fact an
186: .L "enum clnt_stat"
187: cast into an integer.
188: .LP
189: Since data types may be represented differently on different machines,
190: .L callrpc()
191: needs both the type of the RPC argument, as well as
192: a pointer to the argument itself (and similarly for the result).
193: For RUSERSPROC_NUM, the return value is an
194: .L "unsigned long" ,
195: so
196: .L callrpc()
197: has
198: .L xdr_u_long
199: as its first return parameter, which says
200: that the result is of type
201: .L "unsigned long",
202: and
203: .L &nusers
204: as its second return parameter,
205: which is a pointer to where the long result will be placed.
206: Since RUSERSPROC_NUM takes no argument, the argument parameter of
207: .L callrpc()
208: is
209: .L xdr_void .
210: .LP
211: After trying several times to deliver a message, if
212: .L callrpc()
213: gets no answer, it returns with an error code.
214: The delivery mechanism is UDP,
215: which stands for User Datagram Protocol.
216: Methods for adjusting the number of retries
217: or for using a different protocol require you to use the lower
218: layer of the RPC library, discussed later in this document.
219: The remote server procedure
220: corresponding to the above might look like this:
221: .LS
222: char *
223: nuser(indata)
224: char *indata;
225: {
226: static int nusers;
227: .sp.5
228: /*
229: * code here to compute the number of users
230: * and place result in variable nusers
231: */
232: return ((char *)&nusers);
233: }
234: .LE
235: .LP
236: It takes one argument, which is a pointer to the input
237: of the remote procedure call (ignored in our example),
238: and it returns a pointer to the result.
239: In the current version of C,
240: character pointers are the generic pointers,
241: so both the input argument and the return value are cast to
242: .L "char *" .
243: .LP
244: Normally, a server registers all of the RPC calls it plans
245: to handle, and then goes into an infinite loop waiting to service requests.
246: In this example, there is only a single procedure
247: to register, so the main body of the server would look like this:
248: .LS
249: #include <stdio.h>
250: #include <rpcsvc/rusers.h>
251: .sp.5
252: char *nuser();
253: .sp.5
254: main()
255: {
256: registerrpc(RUSERSPROG, RUSERSVERS, RUSERSPROC_NUM, nuser,
257: xdr_void, xdr_u_long);
258: svc_run(); /* never returns */
259: fprintf(stderr, "Error: svc_run returned!\en");
260: exit(1);
261: }
262: .LE
263: .LP
264: The
265: .L registerrpc()
266: routine establishes what C procedure
267: corresponds to each RPC procedure number.
268: The first three parameters,
269: RUSERPROG, RUSERSVERS, and RUSERSPROC_NUM
270: are the program, version, and procedure numbers
271: of the remote procedure to be registered;
272: .L nuser
273: is the name of the C procedure implementing it;
274: and
275: .L xdr_void
276: and
277: .L xdr_u_long
278: are the types of the input to and output from the procedure.
279: .LP
280: Only the UDP transport mechanism can use
281: .L registerrpc() ;
282: thus, it is always safe in conjunction with calls generated by
283: .L callrpc() .
284: .LP
285: Warning: the UDP transport mechanism can only deal with
286: arguments and results less than 8K bytes in length.
287: .
288: .H 2 "Assigning Program Numbers"
289: .LP
290: Program numbers are assigned in groups of 0x20000000 (536870912)
291: according to the following chart:
292: .LS
293: 0 - 1fffffff defined by sun
294: 20000000 - 3fffffff defined by user
295: 40000000 - 5fffffff transient
296: 60000000 - 7fffffff reserved
297: 80000000 - 9fffffff reserved
298: a0000000 - bfffffff reserved
299: c0000000 - dfffffff reserved
300: e0000000 - ffffffff reserved
301: .LE
302: Sun Microsystems administers the first group of numbers,
303: which should be identical for all Sun customers.
304: If a customer develops an application that might be of general
305: interest, that application should be given an assigned number
306: in the first range.
307: The second group of numbers is reserved for specific customer
308: applications.
309: This range is intended primarily for debugging new programs.
310: The third group is reserved for applications that
311: generate program numbers dynamically.
312: The final groups
313: are reserved for future use, and should not be used.
314: .LP
315: The exact registration process for Sun defined numbers is yet
316: to be established.
317: .
318: .H 2 "Passing Arbitrary Data Types"
319: .LP
320: In the previous example, the RPC call passes a single
321: .L "unsigned long."
322: RPC can handle arbitrary data structures, regardless of
323: different machines' byte orders or structure layout conventions,
324: by always converting them to a network standard called
325: .I "eXternal Data Representation"
326: (XDR) before
327: sending them over the wire.
328: The process of converting from a particular machine representation
329: to XDR format is called
330: .I serializing ,
331: and the reverse process is called
332: .I deserializing .
333: The type field parameters of
334: .L callrpc()
335: and
336: .L registerrpc()
337: can be a built-in procedure like
338: .L xdr_u_long()
339: in the previous example, or a user supplied one.
340: XDR has these built-in type routines:
341: .LS
342: xdr_int() xdr_u_int() xdr_enum()
343: xdr_long() xdr_u_long() xdr_bool()
344: xdr_short() xdr_u_short() xdr_string()
345: .LE
346: As an example of a user-defined type routine,
347: if you wanted to send the structure
348: .LS
349: struct simple {
350: int a;
351: short b;
352: } simple;
353: .LE
354: then you would call
355: .L callrpc
356: as
357: .LS
358: callrpc(hostname, PROGNUM, VERSNUM, PROCNUM, xdr_simple, &simple ...);
359: .LE
360: where
361: .L xdr_simple()
362: is written as:
363: .LS
364: #include <rpc/rpc.h>
365: .sp.5
366: xdr_simple(xdrsp, simplep)
367: XDR *xdrsp;
368: struct simple *simplep;
369: {
370: if (!xdr_int(xdrsp, &simplep->a))
371: return (0);
372: if (!xdr_short(xdrsp, &simplep->b))
373: return (0);
374: return (1);
375: }
376: .LE
377: .LP
378: An XDR routine returns nonzero (true in the sense of C)
379: if it completes successfully, and zero otherwise.
380: A complete description of XDR is in the
381: .I "XDR Protocol Specification" ,
382: so this section only gives a few examples of XDR implementation.
383: .LP
384: In addition to the built-in primitives,
385: there are also the prefabricated building blocks:
386: .LS
387: xdr_array() xdr_bytes()
388: xdr_reference() xdr_union()
389: .LE
390: To send a variable array of integers,
391: you might package them up as a structure like this
392: .LS
393: struct varintarr {
394: int *data;
395: int arrlnth;
396: } arr;
397: .LE
398: and make an RPC call such as
399: .LS
400: callrpc(hostname, PROGNUM, VERSNUM, PROCNUM, xdr_varintarr, &arr...);
401: .LE
402: with
403: .L xdr_varintarr()
404: defined as:
405: .LS
406: xdr_varintarr(xdrsp, varintarr)
407: XDR *xdrsp;
408: struct varintarr *arrp;
409: {
410: xdr_array(xdrsp, &arrp->data, &arrp->arrlnth, MAXLEN,
411: sizeof(int), xdr_int);
412: }
413: .LE
414: This routine takes as parameters the XDR handle,
415: a pointer to the array, a pointer to the size of the array,
416: the maximum allowable array size,
417: the size of each array element,
418: and an XDR routine for handling each array element.
419: .LP
420: If the size of the array is known in advance, then
421: the following could also be used to send
422: out an array of length SIZE:
423: .LS
424: int intarr[SIZE];
425: .sp.5
426: xdr_intarr(xdrsp, intarr)
427: XDR *xdrsp;
428: int intarr[];
429: {
430: int i;
431: .sp.5
432: for (i = 0; i < SIZE; i++) {
433: if (!xdr_int(xdrsp, &intarr[i]))
434: return (0);
435: }
436: return (1);
437: }
438: .LE
439: .LP
440: XDR always converts quantities to 4-byte multiples when deserializing.
441: Thus, if either of the examples above involved characters
442: instead of integers, each character would occupy 32 bits.
443: That is the reason for the XDR routine
444: .L xdr_bytes() ,
445: which is like
446: .L xdr_array()
447: except that it packs characters.
448: It has four parameters,
449: the same as the first four parameters of
450: .L xdr_array() .
451: For null-terminated strings, there is also the
452: .L xdr_string()
453: routine, which is the same as
454: .L xdr_bytes()
455: without the length parameter.
456: On serializing it gets the string length from
457: .L strlen() ,
458: and on deserializing it creates a null-terminated string.
459: .LP
460: Here is a final example that calls the previously written
461: .L xdr_simple()
462: as well as the built-in functions
463: .L xdr_string()
464: and
465: .L xdr_reference() ,
466: which chases pointers:
467: .LS
468: struct finalexample {
469: char *string;
470: struct simple *simplep;
471: } finalexample;
472: .LE
473: .LS
474: xdr_finalexample(xdrsp, finalp)
475: XDR *xdrsp;
476: struct finalexample *finalp;
477: {
478: int i;
479: .sp.5
480: if (!xdr_string(xdrsp, &finalp->string, MAXSTRLEN))
481: return (0);
482: if (!xdr_reference(xdrsp, &finalp->simplep,
483: sizeof(struct simple), xdr_simple);
484: return (0);
485: return (1);
486: }
487: .LE
488: .bp
489: .
490: .H 1 "Lower Layers of RPC"
491: .LP
492: In the examples given so far,
493: RPC takes care of many details automatically for you.
494: In this section, we'll show you how you can change the defaults
495: by using lower layers of the RPC library.
496: It is assumed that you are familiar with sockets
497: and the system calls for dealing with them.
498: If not, consult
499: .I "The IPC Tutorial" .
500: .H 2 "More on the Server Side"
501: .LP
502: There are a number of assumptions built into
503: .L registerrpc() .
504: One is that you are using the UDP datagram protocol.
505: Another is that
506: you don't want to do anything unusual while deserializing,
507: since the deserialization process happens automatically
508: before the user's server routine is called.
509: The server for the
510: .L nusers
511: program shown below
512: is written using a lower layer of the RPC package,
513: which does not make these assumptions.
514: .LS
515: #include <stdio.h>
516: #include <rpc/rpc.h>
517: #include <rpcsvc/rusers.h>
518: .sp.5
519: int nuser();
520: .sp.5
521: main()
522: {
523: SVCXPRT *transp;
524: .sp.5
525: transp = svcudp_create(RPC_ANYSOCK);
526: if (transp == NULL){
527: fprintf(stderr, "couldn't create an RPC server\en");
528: exit(1);
529: }
530: pmap_unset(RUSERSPROG, RUSERSVERS);
531: if (!svc_register(transp, RUSERSPROG, RUSERSVERS, nuser,
532: IPPROTO_UDP)) {
533: fprintf(stderr, "couldn't register RUSER service\en");
534: exit(1);
535: }
536: svc_run(); /* never returns */
537: fprintf(stderr, "should never reach this point\en");
538: }
539: .LE
540: .LS
541: nuser(rqstp, tranp)
542: struct svc_req *rqstp;
543: SVCXPRT *transp;
544: {
545: unsigned long nusers;
546: .sp.5
547: switch (rqstp->rq_proc) {
548: case NULLPROC:
549: if (!svc_sendreply(transp, xdr_void, 0)) {
550: fprintf(stderr, "couldn't reply to RPC call\en");
551: exit(1);
552: }
553: return;
554: case RUSERSPROC_NUM:
555: /*
556: * code here to compute the number of users
557: * and put in variable nusers
558: */
559: if (!svc_sendreply(transp, xdr_u_long, &nusers) {
560: fprintf(stderr, "couldn't reply to RPC call\en");
561: exit(1);
562: }
563: return;
564: default:
565: svcerr_noproc(transp);
566: return;
567: }
568: }
569: .LE
570: .LP
571: First, the server gets a transport handle, which is used
572: for sending out RPC messages.
573: .L registerrpc()
574: uses
575: .L svcudp_create()
576: to get a UDP handle.
577: If you require a reliable protocol, call
578: .L svctcp_create()
579: instead.
580: If the argument to
581: .L svcudp_create()
582: is RPC_ANYSOCK,
583: the RPC library creates a socket
584: on which to send out RPC calls.
585: Otherwise,
586: .L svcudp_create()
587: expects its argument to be a valid socket number.
588: If you specify your own socket, it can be bound or unbound.
589: If it is bound to a port by the user, the port numbers of
590: .L svcudp_create()
591: and
592: .L clntudp_create()
593: (the low-level client routine) must match.
594: .LP
595: When the user specifies RPC_ANYSOCK for a socket
596: or gives an unbound socket, the system determines
597: port numbers in the following way:
598: when a server starts up,
599: it advertises to a port mapper demon on its local machine,
600: which picks a port number for the RPC procedure
601: if the socket specified to
602: .L svcudp_create()
603: isn't already bound.
604: When the
605: .L clntudp_create()
606: call is made with an unbound socket,
607: the system queries the port mapper on
608: the machine to which the call is being made,
609: and gets the appropriate port number.
610: If the port mapper is not running
611: or has no port corresponding to the RPC call,
612: the RPC call fails.
613: Users can make RPC calls
614: to the port mapper themselves.
615: The appropriate procedure
616: numbers are in the include file
617: .L <rpc/pmap_prot.h> .
618: .LP
619: After creating an SVCXPRT, the next step is to call
620: .L pmap_unset()
621: so that if the
622: .L nusers
623: server crashed earlier,
624: any previous trace of it is erased before restarting.
625: More precisely,
626: .L pmap_unset()
627: erases the entry for RUSERS from the port mapper's tables.
628: .LP
629: Finally, we associate the program number for
630: .L nusers
631: with the procedure
632: .L nuser() .
633: The final argument to
634: .L svc_register()
635: is normally the protocol being used,
636: which, in this case, is IPPROTO_UDP.
637: Notice that unlike
638: .L registerrpc() ,
639: there are no XDR routines involved
640: in the registration process.
641: Also, registration is done on the program,
642: rather than procedure, level.
643: .LP
644: The user routine
645: .L nuser()
646: must call and dispatch the appropriate XDR routines
647: based on the procedure number.
648: Note that
649: two things are handled by
650: .L nuser()
651: that
652: .L registerrpc()
653: handles automatically.
654: The first is that procedure NULLPROC
655: (currently zero) returns with no arguments.
656: This can be used as a simple test
657: for detecting if a remote program is running.
658: Second, there is a check for invalid procedure numbers.
659: If one is detected,
660: .L svcerr_noproc()
661: is called to handle the error.
662: .LP
663: The user service routine serializes the results and returns
664: them to the RPC caller via
665: .L svc_sendreply() .
666: Its first parameter is the SVCXPRT handle,
667: the second is the XDR routine,
668: and the third is a pointer to the data to be returned.
669: Not illustrated above is how a server
670: handles an RPC program that passes data.
671: As an example, we can add a procedure RUSERSPROC_BOOL,
672: which has an argument
673: .L nusers ,
674: and returns TRUE or FALSE depending on
675: whether there are nusers logged on.
676: It would look like this:
677: .LS
678: case RUSERSPROC_BOOL: {
679: int bool;
680: unsigned nuserquery;
681: .sp.5
682: if (!svc_getargs(transp, xdr_u_int, &nuserquery) {
683: svcerr_decode(transp);
684: return;
685: }
686: /*
687: * code to set nusers = number of users
688: */
689: if (nuserquery == nusers)
690: bool = TRUE;
691: else
692: bool = FALSE;
693: if (!svc_sendreply(transp, xdr_bool, &bool){
694: fprintf(stderr, "couldn't reply to RPC call\en");
695: exit(1);
696: }
697: return;
698: }
699: .LE
700: .LP
701: The relevant routine is
702: .L svc_getargs() ,
703: which takes an SVCXPRT handle, the XDR routine,
704: and a pointer to where the input is to be placed as arguments.
705: .H 2 "Memory Allocation with XDR"
706: .LP
707: XDR routines not only do input and output,
708: they also do memory allocation.
709: This is why the second parameter of
710: .L xdr_array()
711: is a pointer to an array, rather than the array itself.
712: If it is NULL, then
713: .L xdr_array()
714: allocates space for the array and returns a pointer to it,
715: putting the size of the array in the third argument.
716: As an example, consider the following XDR routine
717: .L xdr_chararr1() ,
718: which deals with a fixed array of bytes with length SIZE:
719: .LS
720: xdr_chararr1(xdrsp, chararr)
721: XDR *xdrsp;
722: char chararr[];
723: {
724: char *p;
725: int len;
726: .sp.5
727: p = chararr;
728: len = SIZE;
729: return (xdr_bytes(xdrsp, &p, &len, SIZE));
730: }
731: .LE
732: It might be called from a server like this,
733: .LS
734: char chararr[SIZE];
735: .sp.5
736: svc_getargs(transp, xdr_chararr1, chararr);
737: .LE
738: where
739: .L chararr
740: has already allocated space.
741: If you want XDR to do the allocation,
742: you would have to rewrite this routine in the following way:
743: .LS
744: xdr_chararr2(xdrsp, chararrp)
745: XDR *xdrsp;
746: char **chararrp;
747: {
748: int len;
749: .sp.5
750: len = SIZE;
751: return (xdr_bytes(xdrsp, charrarrp, &len, SIZE));
752: }
753: .LE
754: Then the RPC call might look like this:
755: .LS
756: char *arrptr;
757: .sp.5
758: arrptr = NULL;
759: svc_getargs(transp, xdr_chararr2, &arrptr);
760: /*
761: * use the result here
762: */
763: svc_freeargs(xdrsp, xdr_chararr2, &arrptr);
764: .LE
765: After using the character array, it can be freed with
766: .L svc_freeargs() .
767: In the routine
768: .L xdr_finalexample()
769: given earlier, if
770: .L finalp->string
771: was NULL in the call
772: .LS
773: svc_getargs(transp, xdr_finalexample, &finalp);
774: .LE
775: then
776: .LS
777: svc_freeargs(xdrsp, xdr_finalexample, &finalp);
778: .LE
779: frees the array allocated to hold
780: .L finalp->string ;
781: otherwise, it frees nothing.
782: The same is true for
783: .L finalp->simplep .
784: .LP
785: To summarize, each XDR routine is responsible
786: for serializing, deserializing, and allocating memory.
787: When an XDR routine is called from
788: .L callrpc() ,
789: the serializing part is used.
790: When called from
791: .L svc_getargs() ,
792: the deserializer is used.
793: And when called from
794: .L svc_freeargs() ,
795: the memory deallocator is used.
796: When building simple examples like those in this section,
797: a user doesn't have to worry about the three modes.
798: The XDR reference manual has examples of more
799: sophisticated XDR routines that
800: determine which of the three modes they are in
801: to function correctly.
802: .
803: .H 2 "The Calling Side"
804: .LP
805: When you use
806: .L callrpc,
807: you have no control over the RPC delivery
808: mechanism or the socket used to transport the data.
809: To illustrate the layer of RPC that lets you adjust these
810: parameters, consider the following code to call the
811: .L nusers
812: service:
813: .LS
814: #include <stdio.h>
815: #include <rpc/rpc.h>
816: #include <rpcsvc/rusers.h>
817: #include <sys/socket.h>
818: #include <sys/time.h>
819: #include <netdb.h>
820: .sp.5
821: main(argc, argv)
822: int argc;
823: char **argv;
824: {
825: struct hostent *hp;
826: struct timeval pertry_timeout, total_timeout;
827: struct sockaddr_in server_addr;
828: int addrlen, sock = RPC_ANYSOCK;
829: register CLIENT *client;
830: enum clnt_stat clnt_stat;
831: unsigned long nusers;
832: .sp.5
833: if (argc < 2) {
834: fprintf(stderr, "usage: nusers hostname\en");
835: exit(-1);
836: }
837: if ((hp = gethostbyname(argv[1])) == NULL) {
838: fprintf(stderr, "cannot get addr for '%s'\en", argv[1]);
839: exit(-1);
840: }
841: pertry_timeout.tv_sec = 3;
842: pertry_timeout.tv_usec = 0;
843: addrlen = sizeof(struct sockaddr_in);
844: bcopy(hp->h_addr, (caddr_t)&server_addr.sin_addr, hp->h_length);
845: server_addr.sin_family = AF_INET;
846: server_addr.sin_port = 0;
847: if ((client = clntudp_create(&server_addr, RUSERSPROG,
848: RUSERSVERS, pertry_timeout, &sock)) == NULL) {
849: perror("clntudp_create");
850: exit(-1);
851: }
852: total_timeout.tv_sec = 20;
853: total_timeout.tv_usec = 0;
854: clnt_stat = clnt_call(client, RUSERSPROC_NUM, xdr_void, 0,
855: xdr_u_long, &nusers, total_timeout);
856: if (clnt_stat != RPC_SUCCESS) {
857: clnt_perror(client, "rpc");
858: exit(-1);
859: }
860: clnt_destroy(client);
861: }
862: .LE
863: The low-level version of
864: .L callrpc()
865: is
866: .L clnt_call() ,
867: which takes a CLIENT pointer rather than a host name.
868: The parameters to
869: .L clnt_call()
870: are a CLIENT pointer, the procedure number,
871: the XDR routine for serializing the argument,
872: a pointer to the argument,
873: the XDR routine for deserializing the return value,
874: a pointer to where the return value will be placed,
875: and the time in seconds to wait for a reply.
876: .LP
877: The CLIENT pointer is encoded with
878: the transport mechanism.
879: .L callrpc()
880: uses UDP, thus it calls
881: .L clntudp_create()
882: to get a CLIENT pointer.
883: To get TCP (Transport Control Protocol), you would use
884: .L clnttcp_create() .
885: .LP
886: The parameters to
887: .L clntudp_create()
888: are the server address, the length of the server address,
889: the program number, the version number,
890: a timeout value (between tries), and a pointer to a socket.
891: The final argument to
892: .L clnt_call()
893: is the total time to wait for a response.
894: Thus, the number of tries is the
895: .L clnt_call()
896: timeout divided by the
897: .L clntudp_create()
898: timeout.
899: .LP
900: There is one thing to note when using the
901: .L clnt_destroy()
902: call.
903: It deallocates any space associated with the CLIENT handle,
904: but it does not close the socket associated with it,
905: which was passed as an argument to
906: .L clntudp_create() .
907: The reason is that if
908: there are multiple client handles using the same socket,
909: then it is possible to close one handle
910: without destroying the socket that other handles
911: are using.
912: .LP
913: To make a stream connection, the call to
914: .L clntudp_create()
915: is replaced with a call to
916: .L clnttcp_create().
917: .LS
918: clnttcp_create(&server_addr, prognum, versnum, &socket, inputsize,
919: outputsize);
920: .LE
921: There is no timeout argument; instead, the receive and send buffer
922: sizes must be specified. When the
923: .L clnttcp_create()
924: call is made, a TCP connection is established.
925: All RPC calls using that CLIENT handle would use this connection.
926: The server side of an RPC call using TCP has
927: .L svcudp_create()
928: replaced by
929: .L svctcp_create() .
930: .bp
931: .
932: .H 1 "Other RPC Features"
933: .LP
934: This section discusses some other aspects of RPC
935: that are occasionally useful.
936: .
937: .H 2 "Select on the Server Side"
938: .LP
939: Suppose a process is processing RPC requests
940: while performing some other activity.
941: If the other activity involves periodically updating a data structure,
942: the process can set an alarm signal before calling
943: .L svc_run() .
944: But if the other activity
945: involves waiting on a a file descriptor, the
946: .L svc_run()
947: call won't work.
948: The code for
949: .L svc_run()
950: is as follows:
951: .LS
952: void
953: svc_run()
954: {
955: int readfds;
956: .sp.5
957: for (;;) {
958: readfds = svc_fds;
959: switch (select(32, &readfds, NULL, NULL, NULL)) {
960: .sp.5
961: case -1:
962: if (errno == EINTR)
963: continue;
964: perror("rstat: select");
965: return;
966: case 0:
967: break;
968: default:
969: svc_getreq(readfds);
970: }
971: }
972: }
973: .LE
974: .LP
975: You can bypass
976: .L svc_run()
977: and call
978: .L svc_getreq()
979: yourself.
980: All you need to know are the file descriptors
981: of the socket(s) associated with the programs you are waiting on.
982: Thus you can have your own
983: .L select()
984: that waits on both the RPC socket,
985: and your own descriptors.
986: .
987: .H 2 "Broadcast RPC"
988: .LP
989: The
990: .L pmap
991: and RPC protocols implement broadcast RPC.
992: Here are the main differences between broadcast RPC
993: and normal RPC calls:
994: .IP 1)
995: Normal RPC expects one answer, whereas
996: broadcast RPC expects many answers
997: (one or more answer from each responding machine).
998: .IP 2)
999: Broadcast RPC can only be supported by packet-oriented (connectionless)
1000: transport protocols like UPD/IP.
1001: .IP 3)
1002: The implementation of broadcast RPC
1003: treats all unsuccessful responses as garbage by filtering them out.
1004: Thus, if there is a version mismatch between the
1005: broadcaster and a remote service,
1006: the user of broadcast RPC never knows.
1007: .IP 4)
1008: All broadcast messages are sent to the portmap port.
1009: Thus, only services that register themselves with their portmapper
1010: are accessible via the broadcast RPC mechanism.
1011: .
1012: .H 3 "Broadcast RPC Synopsis"
1013: .LP
1014: .LS
1015: #include <rpc/pmap_clnt.h>
1016: .sp.5
1017: enum clnt_stat clnt_stat;
1018: .sp.5
1019: clnt_stat =
1020: clnt_broadcast(prog, vers, proc, xargs, argsp, xresults, resultsp, eachresult)
1021: u_long prog; /* program number */
1022: u_long vers; /* version number */
1023: u_long proc; /* procedure number */
1024: xdrproc_t xargs; /* xdr routine for args */
1025: caddr_t argsp; /* pointer to args */
1026: xdrproc_t xresults; /* xdr routine for results */
1027: caddr_t resultsp; /* pointer to results */
1028: bool_t (*eachresult)(); /* call with each result obtained */
1029: .LE
1030: The procedure
1031: .L eachresult()
1032: is called each time a valid result is obtained.
1033: It returns a boolean that indicates
1034: whether or not the client wants more responses.
1035: .LS
1036: bool_t done;
1037: .sp.5
1038: done =
1039: eachresult(resultsp, raddr)
1040: caddr_t resultsp;
1041: struct sockaddr_in *raddr; /* address of machine that sent response */
1042: .LE
1043: If
1044: .L done
1045: is TRUE, then broadcasting stops and
1046: .L clnt_broadcast()
1047: returns successfully.
1048: Otherwise, the routine waits for another response.
1049: The request is rebroadcast
1050: after a few seconds of waiting.
1051: If no responses come back,
1052: the routine returns with RPC_TIMEDOUT.
1053: To interpret
1054: .L clnt_stat
1055: errors, feed the error code to
1056: .L clnt_perrno() .
1057: .
1058: .H 2 "Batching"
1059: .LP
1060: The RPC architecture is designed so that clients send a call message,
1061: and wait for servers to reply that the call succeeded.
1062: This implies that clients do not compute
1063: while servers are processing a call.
1064: This is inefficient if the client does not want or need
1065: an acknowledgement for every message sent.
1066: It is possible for clients to continue computing
1067: while waiting for a response,
1068: using RPC batch facilities.
1069: .LP
1070: RPC messages can be placed in a ``pipeline'' of calls
1071: to a desired server; this is called batching.
1072: Batching assumes that:
1073: 1) each RPC call in the pipeline requires no response from the server,
1074: and the server does not send a response message; and
1075: 2) the pipeline of calls is transported on a reliable
1076: byte stream transport such as TCP/IP.
1077: Since the server does not respond to every call,
1078: the client can generate new calls in parallel
1079: with the server executing previous calls.
1080: Furthermore, the TCP/IP implementation can buffer up
1081: many call messages, and send them to the server in one
1082: .L write
1083: system call. This overlapped execution
1084: greatly decreases the interprocess communication overhead of
1085: the client and server processes,
1086: and the total elapsed time of a series of calls.
1087: .LP
1088: Since the batched calls are buffered,
1089: the client should eventually do a legitimate call
1090: in order to flush the pipeline.
1091: .LP
1092: A contrived example of batching follows.
1093: Assume a string rendering service (like a window system)
1094: has two similar calls: one renders a string and returns void results,
1095: while the other renders a string and remains silent.
1096: The service (using the TCP/IP transport) may look like:
1097: .LS
1098: #include <stdio.h>
1099: #include <rpc/rpc.h>
1100: #include <rpcsvc/windows.h>
1101: .sp.5
1102: void windowdispatch();
1103: .sp.5
1104: main()
1105: {
1106: SVCXPRT *transp;
1107: .sp.5
1108: transp = svctcp_create(RPC_ANYSOCK, 0, 0);
1109: if (transp == NULL){
1110: fprintf(stderr, "couldn't create an RPC server\en");
1111: exit(1);
1112: }
1113: pmap_unset(WINDOWPROG, WINDOWVERS);
1114: if (!svc_register(transp, WINDOWPROG, WINDOWVERS, windowdispatch,
1115: IPPROTO_TCP)) {
1116: fprintf(stderr, "couldn't register WINDOW service\en");
1117: exit(1);
1118: }
1119: svc_run(); /* never returns */
1120: fprintf(stderr, "should never reach this point\en");
1121: }
1122: .LE
1123: .LS no
1124: void
1125: windowdispatch(rqstp, transp)
1126: struct svc_req *rqstp;
1127: SVCXPRT *transp;
1128: {
1129: char *s = NULL;
1130: .sp.5
1131: switch (rqstp->rq_proc) {
1132: case NULLPROC:
1133: if (!svc_sendreply(transp, xdr_void, 0)) {
1134: fprintf(stderr, "couldn't reply to RPC call\en");
1135: exit(1);
1136: }
1137: return;
1138: case RENDERSTRING:
1139: if (!svc_getargs(transp, xdr_wrapstring, &s)) {
1140: fprintf(stderr, "couldn't decode arguments\en");
1141: svcerr_decode(transp); /* tell caller he screwed up */
1142: break;
1143: }
1144: /*
1145: * call here to to render the string s
1146: */
1147: if (!svc_sendreply(transp, xdr_void, NULL)) {
1148: fprintf(stderr, "couldn't reply to RPC call\en");
1149: exit(1);
1150: }
1151: break;
1152: case RENDERSTRING_BATCHED:
1153: if (!svc_getargs(transp, xdr_wrapstring, &s)) {
1154: fprintf(stderr, "couldn't decode arguments\en");
1155: /*
1156: * we are silent in the face of protocol errors
1157: */
1158: break;
1159: }
1160: /*
1161: * call here to to render the string s,
1162: * but sends no reply!
1163: */
1164: break;
1165: default:
1166: svcerr_noproc(transp);
1167: return;
1168: }
1169: /*
1170: * now free string allocated while decoding arguments
1171: */
1172: svc_freeargs(transp, xdr_wrapstring, &s);
1173: }
1174: .LE
1175: Of course the service could have one procedure
1176: that takes the string and a boolean
1177: to indicate whether or not the procedure should respond.
1178: .LP
1179: In order for a client to take advantage of batching,
1180: the client must perform RPC calls on a TCP-based transport
1181: and the actual calls must have the following attributes:
1182: 1) the result's XDR routine must be zero (NULL), and
1183: 2) the RPC call's timeout must be zero.
1184: .LP
1185: Here is an example of a client that uses batching
1186: to render a bunch of strings;
1187: the batching is flushed when the client gets a null string:
1188: .LS
1189: #include <stdio.h>
1190: #include <rpc/rpc.h>
1191: #include <rpcsvc/windows.h>
1192: #include <sys/socket.h>
1193: #include <sys/time.h>
1194: #include <netdb.h>
1195: .sp.5
1196: main(argc, argv)
1197: int argc;
1198: char **argv;
1199: {
1200: struct hostent *hp;
1201: struct timeval pertry_timeout, total_timeout;
1202: struct sockaddr_in server_addr;
1203: int addrlen, sock = RPC_ANYSOCK;
1204: register CLIENT *client;
1205: enum clnt_stat clnt_stat;
1206: char buf[1000];
1207: char *s = buf;
1208: .sp.5
1209: /*
1210: * initial as in example 3.3
1211: */
1212: if ((client = clnttcp_create(&server_addr, WINDOWPROG,
1213: WINDOWVERS, &sock, 0, 0)) == NULL) {
1214: perror("clnttcp_create");
1215: exit(-1);
1216: }
1217: total_timeout.tv_sec = 0;
1218: total_timeout.tv_usec = 0;
1219: while (scanf("%s", s) != EOF) {
1220: clnt_stat = clnt_call(client, RENDERSTRING_BATCHED,
1221: xdr_wrapstring, &s, NULL, NULL, total_timeout);
1222: if (clnt_stat != RPC_SUCCESS) {
1223: clnt_perror(client, "batched rpc");
1224: exit(-1);
1225: }
1226: }
1227: /*
1228: * now flush the pipeline
1229: */
1230: total_timeout.tv_sec = 20;
1231: clnt_stat = clnt_call(client, NULLPROC,
1232: xdr_void, NULL, xdr_void, NULL, total_timeout);
1233: if (clnt_stat != RPC_SUCCESS) {
1234: clnt_perror(client, "rpc");
1235: exit(-1);
1236: }
1237:
1238: clnt_destroy(client);
1239: }
1240: .LE
1241: Since the server sends no message,
1242: the clients cannot be notified of any of the failures that may occur.
1243: Therefore, clients are on their own when it comes to handling errors.
1244: .LP
1245: The above example was completed to render
1246: all of the (2000) lines in the file
1247: .I /etc/termcap .
1248: The rendering service did nothing but to throw the lines away.
1249: The example was run in the following four configurations:
1250: 1) machine to itself, regular RPC;
1251: 2) machine to itself, batched RPC;
1252: 3) machine to another, regular RPC; and
1253: 4) machine to another, batched RPC.
1254: The results are as follows:
1255: 1) 50 seconds;
1256: 2) 16 seconds;
1257: 3) 52 seconds;
1258: 4) 10 seconds.
1259: Running
1260: .L fscanf()
1261: on
1262: .I /etc/termcap
1263: only requires six seconds.
1264: These timings show the advantage of protocols
1265: that allow for overlapped execution,
1266: though these protocols are often hard to design.
1267: .
1268: .H 2 "Authentication"
1269: .LP
1270: In the examples presented so far,
1271: the caller never identified itself to the server,
1272: and the server never required an ID from the caller.
1273: Clearly, some network services, such as a network filesystem,
1274: require stronger security than what has been presented so far.
1275: .LP
1276: In reality, every RPC call is authenticated by
1277: the RPC package on the server, and similarly,
1278: the RPC client package generates and sends authentication parameters.
1279: Just as different transports (TCP/IP or UDP/IP)
1280: can be used when creating RPC clients and servers,
1281: different forms of authentication can be associated with RPC clients;
1282: the default authentication type used as a default is type
1283: .I none .
1284: .LP
1285: The authentication subsystem of the RPC package is open ended.
1286: That is, numerous types of authentication are easy to support.
1287: However, this section deals only with
1288: .I unix
1289: type authentication, which besides
1290: .I none
1291: is the only supported type.
1292: .
1293: .H 3 "The Client Side"
1294: .LP
1295: When a caller creates a new RPC client handle as in:
1296: .LS
1297: clnt = clntudp_create(address, prognum, versnum, wait, sockp)
1298: .LE
1299: the appropriate transport instance defaults
1300: the associate authentication handle to be
1301: .LS
1302: clnt->cl_auth = authnone_create();
1303: .LE
1304: The RPC client can choose to use
1305: .I unix
1306: style authentication by setting
1307: .L clnt->cl_auth
1308: after creating the RPC client handle:
1309: .LS
1310: clnt->cl_auth = authunix_create_default();
1311: .LE
1312: This causes each RPC call associated with
1313: .L clnt
1314: to carry with it the following authentication credentials structure:
1315: .LS
1316: /*
1317: * Unix style credentials.
1318: */
1319: struct authunix_parms {
1320: u_long aup_time; /* credentials creation time */
1321: char *aup_machname; /* host name of where the client is calling */
1322: int aup_uid; /* client's UNIX effective uid */
1323: int aup_gid; /* client's current UNIX group id */
1324: u_int aup_len; /* the element length of aup_gids array */
1325: int *aup_gids; /* array of 4.2 groups to which user belongs */
1326: };
1327: .LE
1328: These fields are set by
1329: .L authunix_create_default()
1330: by invoking the appropriate system calls.
1331: .LP
1332: Since the RPC user created this new style of authentication,
1333: he is responsible for destroying it with:
1334: .LS
1335: auth_destroy(clnt->cl_auth);
1336: .LE
1337: .
1338: .H 3 "The Server Side"
1339: .LP
1340: Service implementors have a harder time dealing with authentication issues
1341: since the RPC package passes the service dispatch routine a request
1342: that has an arbitrary authentication style associated with it.
1343: Consider the fields of a request handle passed to a service dispatch routine:
1344: .LS
1345: /*
1346: * An RPC Service request
1347: */
1348: struct svc_req {
1349: u_long rq_prog; /* service program number */
1350: u_long rq_vers; /* service protocol version number*/
1351: u_long rq_proc; /* the desired procedure number*/
1352: struct opaque_auth rq_cred; /* raw credentials from the ``wire'' */
1353: caddr_t rq_clntcred; /* read only, cooked credentials */
1354: };
1355: .LE
1356: The
1357: .L rq_cred
1358: is mostly opaque, except for one field of interest:
1359: the style of authentication credentials:
1360: .LS
1361: /*
1362: * Authentication info. Mostly opaque to the programmer.
1363: */
1364: struct opaque_auth {
1365: enum_t oa_flavor; /* style of credentials */
1366: caddr_t oa_base; /* address of more auth stuff */
1367: u_int oa_length; /* not to exceed MAX_AUTH_BYTES */
1368: };
1369: .LE
1370: The RPC package guarantees the following
1371: to the service dispatch routine:
1372: .IP 1)
1373: That the request's
1374: .L rq_cred
1375: is well formed. Thus the service implementor may inspect the request's
1376: .L rq_cred.oa_flavor
1377: to determine which style of authentication the caller used.
1378: The service implementor may also wish to inspect the other fields of
1379: .L rq_cred
1380: if the style is not one of the styles supported by the RPC package.
1381: .IP 2)
1382: That the request's
1383: .L rq_clntcred
1384: field is either NULL or points to a well formed structure
1385: that corresponds to a supported style of authentication credentials.
1386: Remember that only
1387: .I unix
1388: style is currently supported, so (currently)
1389: .L rq_clntcred
1390: could be cast to a pointer to an
1391: .L authunix_parms
1392: structure. If
1393: .L rq_clntcred
1394: is NULL, the service implementor may wish to inspect
1395: the other (opaque) fileds of
1396: .L rq_cred
1397: in case the service knows about a new type of authentication
1398: that the RPC package does not know about.
1399: .LP
1400: Our remote users service example can be extended so that
1401: it computes results for all users except UID 16:
1402: .LS
1403: nuser(rqstp, tranp)
1404: struct svc_req *rqstp;
1405: SVCXPRT *transp;
1406: {
1407: struct authunix_parms *unix_cred;
1408: int uid;
1409: unsigned long nusers;
1410: .sp.5
1411: /*
1412: * we don't care about authentication for the null procedure
1413: */
1414: if (rqstp->rq_proc == NULLPROC) {
1415: if (!svc_sendreply(transp, xdr_void, 0)) {
1416: fprintf(stderr, "couldn't reply to RPC call\en");
1417: exit(1);
1418: }
1419: return;
1420: }
1421: /*
1422: * now get the uid
1423: */
1424: switch (rqstp->rq_cred.oa_flavor) {
1425: case AUTH_UNIX:
1426: unix_cred = (struct authunix_parms *) rqstp->rq_clntcred;
1427: uid = unix_cred->aup_uid;
1428: break;
1429: case AUTH_NULL:
1430: default:
1431: svcerr_weakauth(transp);
1432: return;
1433: }
1434: switch (rqstp->rq_proc) {
1435: case RUSERSPROC_NUM:
1436: /*
1437: * make sure the caller is allow to call this procedure.
1438: */
1439: if (uid == 16) {
1440: svcerr_systemerr(transp);
1441: return;
1442: }
1443: /*
1444: * code here to compute the number of users
1445: * and put in variable nusers
1446: */
1447: if (!svc_sendreply(transp, xdr_u_long, &nusers) {
1448: fprintf(stderr, "couldn't reply to RPC call\en");
1449: exit(1);
1450: }
1451: return;
1452: default:
1453: svcerr_noproc(transp);
1454: return;
1455: }
1456: }
1457: .LE
1458: A few things should be noted here.
1459: First, it is customary not to check the authentication parameters
1460: associated with the NULLPROC (procedure number zero).
1461: Second, if the authentication parameter's type is not suitable
1462: for your service, you should call
1463: .L svcerr_weakauth() .
1464: And finally, the service protocol itself should return status
1465: for access denied; in the case of our example, the protocol
1466: does not have such a status, so we call the service primitive
1467: .L svcerr_systemerr()
1468: instead.
1469: .LP
1470: The last point underscores the relation between
1471: the RPC authentication package and the services;
1472: RPC deals only with authentication and not with
1473: individual services' access control.
1474: The services themselves must implement their own access control policies
1475: and reflect these policies as return statuses in their protocols.
1476: .
1477: .H 2 "Using Inetd"
1478: .LP
1479: An RPC server can be started from
1480: .L inetd .
1481: The only difference
1482: from the usual code is that
1483: .L svcudp_create()
1484: should be called as
1485: .LS
1486: transp = svcudp_create(0);
1487: .LE
1488: since
1489: .L inet
1490: passes a socket as file descriptor 0.
1491: Also,
1492: .L svc_register()
1493: should be called as
1494: .LS
1495: svc_register(PROGNUM, VERSNUM, service, transp, 0);
1496: .LE
1497: with the final flag as 0,
1498: since the program would already be registered by
1499: .L inetd .
1500: Remember that if you want to exit
1501: from the server process and return control to
1502: .L inet ,
1503: you need to explicitly exit, since
1504: .L svc_run()
1505: never returns.
1506: .LP
1507: The format of entries in /etc/servers for RPC services is
1508: .LS
1509: rpc udp \fIserver \0program \0version\fP
1510: .LE
1511: where
1512: .I server
1513: is the C code implementing the server,
1514: and
1515: .I program
1516: and
1517: .I version
1518: are the program and version numbers of the service.
1519: The key word
1520: .L udp
1521: can be replaced by
1522: .L tcp
1523: for TCP-based RPC services.
1524: .LP
1525: If the same program handles multiple versions,
1526: then the version number can be a range,
1527: as in this example:
1528: .LS
1529: rpc udp /usr/etc/rstatd 100001 1-2
1530: .LE
1531: .bp
1532: .
1533: .H 1 "More Examples"
1534: .H 2 "Versions"
1535: .LP
1536: By convention, the first version number of program FOO is
1537: FOOVERS_ORIG and the most recent version is FOOVERS.
1538: Suppose there is a new version of the
1539: .L user
1540: program that returns an
1541: .L "unsigned short"
1542: rather than a
1543: .L long .
1544: If we name this version
1545: RUSERSVERS_SHORT, then
1546: a server that wants to support both versions
1547: would do a double register.
1548: .LS
1549: .sp.5
1550: if (!svc_register(transp, RUSERSPROG, RUSERSVERS_ORIG, nuser,
1551: IPPROTO_TCP)) {
1552: fprintf(stderr, "couldn't register RUSER service\en");
1553: exit(1);
1554: }
1555: if (!svc_register(transp, RUSERSPROG, RUSERSVERS_SHORT, nuser,
1556: IPPROTO_TCP)) {
1557: fprintf(stderr, "couldn't register RUSER service\en");
1558: exit(1);
1559: }
1560: .LE
1561: .bp
1562: Both versions can be handled by the same C procedure:
1563: .LS 0
1564: nuser(rqstp, tranp)
1565: struct svc_req *rqstp;
1566: SVCXPRT *transp;
1567: {
1568: unsigned long nusers;
1569: unsigned short nusers2
1570: .sp.5
1571: switch (rqstp->rq_proc) {
1572: case NULLPROC:
1573: if (!svc_sendreply(transp, xdr_void, 0)) {
1574: fprintf(stderr, "couldn't reply to RPC call\en");
1575: exit(1);
1576: }
1577: return;
1578: case RUSERSPROC_NUM:
1579: /*
1580: * code here to compute the number of users
1581: * and put in variable nusers
1582: */
1583: nusers2 = nusers;
1584: if (rqstp->rq_vers == RUSERSVERS_ORIG)
1585: if (!svc_sendreply(transp, xdr_u_long, &nusers) {
1586: fprintf(stderr, "couldn't reply to RPC call\en");
1587: exit(1);
1588: }
1589: else
1590: if (!svc_sendreply(transp, xdr_u_short, &nusers2) {
1591: fprintf(stderr, "couldn't reply to RPC call\en");
1592: exit(1);
1593: return;
1594: default:
1595: svcerr_noproc(transp);
1596: return;
1597: }
1598: }
1599: .LE
1600: .H 2 "TCP"
1601: .LP
1602: Here is an example that is essentially
1603: .L rcp .
1604: The initiator of the RPC
1605: .L snd()
1606: call takes its standard input and sends it to the server
1607: .L rcv() ,
1608: which prints it on standard output.
1609: The RPC call uses TCP.
1610: This also illustrates an XDR procedure that behaves differently
1611: on serialization than on deserialization.
1612: .LS 0
1613: /*
1614: * The xdr routine:
1615: *
1616: * on decode, read from wire, write onto fp
1617: * on encode, read from fp, write onto wire
1618: */
1619: #include <stdio.h>
1620: #include <rpc/rpc.h>
1621: .sp.5
1622: xdr_rcp(xdrs, fp)
1623: XDR *xdrs;
1624: FILE *fp;
1625: {
1626: unsigned long size;
1627: char buf[MAXCHUNK], *p;
1628: .sp.5
1629: if (xdrs->x_op == XDR_FREE)/* nothing to free */
1630: return 1;
1631: while (1) {
1632: if (xdrs->x_op == XDR_ENCODE) {
1633: if ((size = fread (buf, sizeof(char), MAXCHUNK, fp))
1634: == 0 && ferror(fp)) {
1635: fprintf(stderr, "couldn't fread\en");
1636: exit(1);
1637: }
1638: }
1639: p = buf;
1640: if (!xdr_bytes(xdrs, &p, &size, MAXCHUNK))
1641: return 0;
1642: if (size == 0)
1643: return 1;
1644: if (xdrs->x_op == XDR_DECODE) {
1645: if (fwrite(buf, sizeof(char), size, fp) != size) {
1646: fprintf(stderr, "couldn't fwrite\en");
1647: exit(1);
1648: }
1649: }
1650: }
1651: }
1652: .LE
1653: .LS 0
1654: /*
1655: * The sender routines
1656: */
1657: #include <stdio.h>
1658: #include <netdb.h>
1659: #include <rpc/rpc.h>
1660: #include <sys/socket.h>
1661: #include <sys/time.h>
1662: .sp.5
1663: main(argc, argv)
1664: int argc;
1665: char **argv;
1666: {
1667: int err;
1668: .sp.5
1669: if (argc < 2) {
1670: fprintf(stderr, "usage: %s server-name\en", argv[0]);
1671: exit(-1);
1672: }
1673: if ((err = callrpctcp(argv[1], RCPPROG, RCPPROC_FP, RCPVERS,
1674: xdr_rcp, stdin, xdr_void, 0) != 0)) {
1675: clnt_perrno(err);
1676: fprintf(stderr, " couldn't make RPC call\en");
1677: exit(1);
1678: }
1679: }
1680: .sp.5
1681: callrpctcp(host, prognum, procnum, versnum, inproc, in, outproc, out)
1682: char *host, *in, *out;
1683: xdrproc_t inproc, outproc;
1684: {
1685: struct sockaddr_in server_addr;
1686: int socket = RPC_ANYSOCK;
1687: enum clnt_stat clnt_stat;
1688: struct hostent *hp;
1689: register CLIENT *client;
1690: struct timeval total_timeout;
1691: .sp.5
1692: if ((hp = gethostbyname(host)) == NULL) {
1693: fprintf(stderr, "cannot get addr for '%s'\en", host);
1694: exit(-1);
1695: }
1696: bcopy(hp->h_addr, (caddr_t)&server_addr.sin_addr, hp->h_length);
1697: server_addr.sin_family = AF_INET;
1698: server_addr.sin_port = 0;
1699: if ((client = clnttcp_create(&server_addr, prognum,
1700: versnum, &socket, BUFSIZ, BUFSIZ)) == NULL) {
1701: perror("rpctcp_create");
1702: exit(-1);
1703: }
1704: total_timeout.tv_sec = 20;
1705: total_timeout.tv_usec = 0;
1706: clnt_stat = clnt_call(client, procnum, inproc, in, outproc, out, total_timeout);
1707: clnt_destroy(client)
1708: return (int)clnt_stat;
1709: }
1710: .LE
1711: .LS 0
1712: /*
1713: * The receiving routines
1714: */
1715: #include <stdio.h>
1716: #include <rpc/rpc.h>
1717: .sp.5
1718: main()
1719: {
1720: register SVCXPRT *transp;
1721: .sp.5
1722: if ((transp = svctcp_create(RPC_ANYSOCK, 1024, 1024)) == NULL) {
1723: fprintf("svctcp_create: error\en");
1724: exit(1);
1725: }
1726: pmap_unset(RCPPROG, RCPVERS);
1727: if (!svc_register(transp, RCPPROG, RCPVERS, rcp_service, IPPROTO_TCP)) {
1728: fprintf(stderr, "svc_register: error\en");
1729: exit(1);
1730: }
1731: svc_run(); /* never returns */
1732: fprintf(stderr, "svc_run should never return\en");
1733: }
1734: .sp.5
1735: rcp_service(rqstp, transp)
1736: register struct svc_req *rqstp;
1737: register SVCXPRT *transp;
1738: {
1739: switch (rqstp->rq_proc) {
1740: case NULLPROC:
1741: if (svc_sendreply(transp, xdr_void, 0) == 0) {
1742: fprintf(stderr, "err: rcp_service");
1743: exit(1);
1744: }
1745: return;
1746: case RCPPROC_FP:
1747: if (!svc_getargs(transp, xdr_rcp, stdout)) {
1748: svcerr_decode(transp);
1749: return;
1750: }
1751: if (!svc_sendreply(transp, xdr_void, 0)) {
1752: fprintf(stderr, "can't reply\en");
1753: return;
1754: }
1755: exit(0);
1756: default:
1757: svcerr_noproc(transp);
1758: return;
1759: }
1760: }
1761: .LE
1762: .H 2 "Callback Procedures"
1763: .LP
1764: Occasionally, it is useful to have a server become a client,
1765: and make an RPC call back the process which is its client.
1766: An example is remote debugging,
1767: where the client is a window system program,
1768: and the server is a debugger running on the remote machine.
1769: Most of the time,
1770: the user clicks a mouse button at the debugging window,
1771: which converts this to a debugger command,
1772: and then makes an RPC call to the server
1773: (where the debugger is actually running),
1774: telling it to execute that command.
1775: However, when the debugger hits a breakpoint, the roles are reversed,
1776: and the debugger wants to make an rpc call to the window program,
1777: so that it can inform the user that a breakpoint has been reached.
1778: .LP
1779: In order to do an RPC callback,
1780: you need a program number to make the RPC call on.
1781: Since this will be a dynamically generated program number,
1782: it should be in the transient range, 0x40000000 - 0x5fffffff.
1783: The routine
1784: .L gettransient()
1785: returns a valid program number in the transient range,
1786: and registers it with the portmapper.
1787: It only talks to the portmapper running on the same machine as the
1788: .L gettransient()
1789: routine itself.
1790: The call to
1791: .L pmap_set()
1792: is a test and set operation,
1793: in that it indivisibly tests whether a program number
1794: has already been registered,
1795: and if it has not, then reserves it.
1796: On return, the
1797: .L sockp
1798: argument will contain a socket that can be used
1799: as the argument to an
1800: .L svcudp_create()
1801: or
1802: .L svctcp_create()
1803: call.
1804: .LS
1805: #include <stdio.h>
1806: #include <rpc/rpc.h>
1807: #include <sys/socket.h>
1808: .sp.5
1809: gettransient(proto, vers, sockp)
1810: int *sockp;
1811: {
1812: static int prognum = 0x40000000;
1813: int s, len, socktype;
1814: struct sockaddr_in addr;
1815: .sp.5
1816: switch(proto) {
1817: case IPPROTO_UDP:
1818: socktype = SOCK_DGRAM;
1819: break;
1820: case IPPROTO_TCP:
1821: socktype = SOCK_STREAM;
1822: break;
1823: default:
1824: fprintf(stderr, "unknown protocol type\en");
1825: return 0;
1826: }
1827: if (*sockp == RPC_ANYSOCK) {
1828: if ((s = socket(AF_INET, socktype, 0)) < 0) {
1829: perror("socket");
1830: return (0);
1831: }
1832: *sockp = s;
1833: }
1834: else
1835: s = *sockp;
1836: addr.sin_addr.s_addr = 0;
1837: addr.sin_family = AF_INET;
1838: addr.sin_port = 0;
1839: len = sizeof(addr);
1840: /*
1841: * may be already bound, so don't check for err
1842: */
1843: bind(s, &addr, len);
1844: if (getsockname(s, &addr, &len)< 0) {
1845: perror("getsockname");
1846: return (0);
1847: }
1848: while (pmap_set(prognum++, vers, proto, addr.sin_port) == 0)
1849: continue;
1850: return (prognum-1);
1851: }
1852: .LE
1853: The following pair of programs illustrate how to use the
1854: .L gettransient()
1855: routine.
1856: The client makes an RPC call to the server,
1857: passing it a transient program number.
1858: Then the client waits around to receive a callback
1859: from the server at that program number.
1860: The server registers the program EXAMPELPROG,
1861: so that it can receive the RPC call
1862: informing it of the callback program number.
1863: Then at some random time (on receiving an ALRM signal in this example),
1864: it sends a callback RPC call,
1865: using the program number it received earlier.
1866: .LS
1867: /*
1868: * client
1869: */
1870: #include <stdio.h>
1871: #include <rpc/rpc.h>
1872: .sp.5
1873: int callback();
1874: char hostname[256];
1875: .sp.5
1876: main(argc, argv)
1877: char **argv;
1878: {
1879: int x, ans, s;
1880: SVCXPRT *xprt;
1881: .sp.5
1882: gethostname(hostname, sizeof(hostname));
1883: s = RPC_ANYSOCK;
1884: x = gettransient(IPPROTO_UDP, 1, &s);
1885: fprintf(stderr, "client gets prognum %d\en", x);
1886:
1887: if ((xprt = svcudp_create(s)) == NULL) {
1888: fprintf(stderr, "rpc_server: svcudp_create\en");
1889: exit(1);
1890: }
1891: (void)svc_register(xprt, x, 1, callback, 0);
1892:
1893: ans = callrpc(hostname, EXAMPLEPROG, EXAMPLEPROC_CALLBACK,
1894: EXAMPLEVERS, xdr_int, &x, xdr_void, 0);
1895: if (ans != 0) {
1896: fprintf(stderr, "call: ");
1897: clnt_perrno(ans);
1898: fprintf(stderr, "\en");
1899: }
1900: svc_run();
1901: fprintf(stderr, "Error: svc_run shouldn't have returned\en");
1902: }
1903: .LE
1904: .LS
1905: callback(rqstp, transp)
1906: register struct svc_req *rqstp;
1907: register SVCXPRT *transp;
1908: {
1909: switch (rqstp->rq_proc) {
1910: case 0:
1911: if (svc_sendreply(transp, xdr_void, 0) == FALSE) {
1912: fprintf(stderr, "err: rusersd\en");
1913: exit(1);
1914: }
1915: exit(0);
1916: case 1:
1917: if (!svc_getargs(transp, xdr_void, 0)) {
1918: svcerr_decode(transp);
1919: exit(1);
1920: }
1921: fprintf(stderr, "client got callback\en");
1922: if (svc_sendreply(transp, xdr_void, 0) == FALSE) {
1923: fprintf(stderr, "err: rusersd");
1924: exit(1);
1925: }
1926: }
1927: }
1928: .LE
1929: .LS
1930: /*
1931: * server
1932: */
1933: #include <stdio.h>
1934: #include <rpc/rpc.h>
1935: #include <sys/signal.h>
1936: .sp.5
1937: char *getnewprog();
1938: char hostname[256];
1939: int docallback();
1940: int pnum; /*program number for callback routine */
1941: .sp.5
1942: main(argc, argv)
1943: char **argv;
1944: {
1945: gethostname(hostname, sizeof(hostname));
1946: registerrpc(EXAMPLEPROG, EXAMPLEPROC_CALLBACK, EXAMPLEVERS,
1947: getnewprog, xdr_int, xdr_void);
1948: fprintf(stderr, "server going into svc_run\en");
1949: alarm(10);
1950: signal(SIGALRM, docallback);
1951: svc_run();
1952: fprintf(stderr, "Error: svc_run shouldn't have returned\en");
1953: }
1954: .sp.5
1955: char *
1956: getnewprog(pnump)
1957: char *pnump;
1958: {
1959: pnum = *(int *)pnump;
1960: return NULL;
1961: }
1962: .sp.5
1963: docallback()
1964: {
1965: int ans;
1966: .sp.5
1967: ans = callrpc(hostname, pnum, 1, 1, xdr_void, 0, xdr_void, 0);
1968: if (ans != 0) {
1969: fprintf(stderr, "server: ");
1970: clnt_perrno(ans);
1971: fprintf(stderr, "\en");
1972: }
1973: }
1974: .LE
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.