2 .\" Must use -- tbl and pic -- with this one
4 .\" @(#)rpc.prog.ms 2.3 88/08/11 4.0 RPCSRC
8 .if \\n%=1 .tl ''- % -''
12 .\" prevent excess underlining in nroff
14 .OH 'Remote Procedure Call Programming Guide''Page %'
15 .EH 'Page %''Remote Procedure Call Programming Guide'
17 \&Remote Procedure Call Programming Guide
19 .IX "Network Programming" "" "" "" PAGE MAJOR
20 .IX "RPC Programming Guide"
22 This document assumes a working knowledge of network theory. It is
23 intended for programmers who wish to write network applications using
24 remote procedure calls (explained below), and who want to understand
25 the RPC mechanisms usually hidden by the
29 is described in detail in the previous chapter, the
30 .I "\fBrpcgen\fP \fIProgramming Guide\fP".
34 .IX rpcgen "" \fIrpcgen\fP
35 Before attempting to write a network application, or to convert an
36 existing non-network application to run over the network, you may want to
37 understand the material in this chapter. However, for most applications,
38 you can circumvent the need to cope with the details presented here by using
41 .I "Generating XDR Routines"
42 section of that chapter contains the complete source for a working RPC
43 service\(ema remote directory listing service which uses
45 to generate XDR routines as well as client and server stubs.
48 What are remote procedure calls? Simply put, they are the high-level
49 communications paradigm used in the operating system.
50 RPC presumes the existence of
51 low-level networking mechanisms (such as TCP/IP and UDP/IP), and upon them
52 it implements a logical client to server communications system designed
53 specifically for the support of network applications. With RPC, the client
54 makes a procedure call to send a data packet to the server. When the
55 packet arrives, the server calls a dispatch routine, performs whatever
56 service is requested, sends back the reply, and the procedure call returns
63 The RPC interface can be seen as being divided into three layers.\**
65 For a complete specification of the routines in the remote procedure
71 .I "The Highest Layer:"
72 .IX RPC "The Highest Layer"
73 The highest layer is totally transparent to the operating system,
74 machine and network upon which is is run. It's probably best to
75 think of this level as a way of
78 a \fIpart of\fP RPC proper. Programmers who write RPC routines
79 should (almost) always make this layer available to others by way
80 of a simple C front end that entirely hides the networking.
82 To illustrate, at this level a program can simply make a call to
84 a C routine which returns the number of users on a remote machine.
85 The user is not explicitly aware of using RPC \(em they simply
86 call a procedure, just as they would call
89 .I "The Middle Layer:"
90 .IX RPC "The Middle Layer"
91 The middle layer is really \*QRPC proper.\*U Here, the user doesn't
92 need to consider details about sockets, the UNIX system, or other low-level
93 implementation mechanisms. They simply make remote procedure calls
94 to routines on other machines. The selling point here is simplicity.
95 It's this layer that allows RPC to pass the \*Qhello world\*U test \(em
96 simple things should be simple. The middle-layer routines are used
97 for most applications.
99 RPC calls are made with the system routines
104 The first two of these are the most fundamental:
106 obtains a unique system-wide procedure-identification number, and
108 actually executes a remote procedure call. At the middle level, a
111 is implemented by way of these two routines.
113 The middle layer is unfortunately rarely used in serious programming
114 due to its inflexibility (simplicity). It does not allow timeout
115 specifications or the choice of transport. It allows no UNIX
116 process control or flexibility in case of errors. It doesn't support
117 multiple kinds of call authentication. The programmer rarely needs
118 all these kinds of control, but one or two of them is often necessary.
120 .I "The Lowest Layer:"
121 .IX RPC "The Lowest Layer"
122 The lowest layer does allow these details to be controlled by the
123 programmer, and for that reason it is often necessary. Programs
124 written at this level are also most efficient, but this is rarely a
125 real issue \(em since RPC clients and servers rarely generate
128 Although this document only discusses the interface to C,
129 remote procedure calls can be made from any language.
130 Even though this document discusses RPC
131 when it is used to communicate
132 between processes on different machines,
133 it works just as well for communication
134 between different processes on the same machine.
141 Here is a diagram of the RPC paradigm:
143 \fBFigure 1-1\fI Network Communication with the Remote Reocedure Call\fR
146 L1: arrow down 1i "client " rjust "program " rjust
147 L2: line right 1.5i "\fIcallrpc\fP" "function"
148 move up 1.5i; line dotted down 6i; move up 4.5i
150 L3: arrow down 1i "invoke " rjust "service " rjust
151 L4: arrow right 1.5i "call" "service"
152 L5: arrow down 1i " service" ljust " executes" ljust
153 L6: arrow left 1.5i "\fIreturn\fP" "answer"
154 L7: arrow down 1i "request " rjust "completed " rjust
156 arrow left 1.5i "\fIreturn\fP" "reply"
157 L9: arrow down 1i "program " rjust "continues " rjust
158 line dashed down from L2 to L9
159 line dashed down from L4 to L7
160 line dashed up 1i from L3 "service " rjust "daemon " rjust
161 arrow dashed down 1i from L8
162 move right 1i from L3
163 box invis "Machine B"
164 move left 1.2i from L2; move down
165 box invis "Machine A"
170 \&Higher Layers of RPC
173 .IX "highest layer of RPC"
174 .IX RPC "highest layer"
176 Imagine you're writing a program that needs to know
177 how many users are logged into a remote machine.
178 You can do this by calling the RPC library routine
180 as illustrated below:
193 fprintf(stderr, "usage: rnusers hostname\en");
196 if ((num = rnusers(argv[1])) < 0) {
197 fprintf(stderr, "error: rnusers\en");
200 printf("%d users on %s\en", num, argv[1]);
205 RPC library routines such as
207 are in the RPC services library
209 Thus, the program above should be compiled with
212 % cc \fIprogram.c -lrpcsvc\fP
215 like the other RPC library routines, is documented in section 3R
217 .I "System Interface Manual for the Sun Workstation" ,
218 the same section which documents the standard Sun RPC services.
222 manual page for an explanation of the documentation strategy
223 for these services and their RPC protocols.
225 Here are some of the RPC service library routines available to the
228 \fBTable 3-3\fI RPC Service Library Routines\fR
236 rnusers&Return number of users on remote machine
237 rusers&Return information about users on remote machine
238 havedisk&Determine if remote machine has disk
239 rstats&Get performance data from remote kernel
240 rwall&Write to specified remote machines
241 yppasswd&Update user password in Yellow Pages
244 Other RPC services \(em for example
250 \(em are not available to the C programmer as library routines.
252 have RPC program numbers so they can be invoked with
254 which will be discussed in the next section. Most of them also
257 protocol description files. (The
259 protocol compiler radically simplifies the process of developing
260 network applications.
261 See the \fBrpcgen\fI Programming Guide\fR
262 for detailed information about
266 protocol description files).
270 .IX "intermediate layer of RPC"
271 .IX "RPC" "intermediate layer"
273 The simplest interface, which explicitly makes RPC calls, uses the
278 Using this method, the number of remote users can be gotten as follows:
284 #include <rpcsvc/rusers.h>
290 unsigned long nusers;
294 fprintf(stderr, "usage: nusers hostname\en");
297 if (stat = callrpc(argv[1],
298 RUSERSPROG, RUSERSVERS, RUSERSPROC_NUM,
299 xdr_void, 0, xdr_u_long, &nusers) != 0) {
303 printf("%d users on %s\en", nusers, argv[1]);
308 Each RPC procedure is uniquely defined by a program number,
309 version number, and procedure number. The program number
310 specifies a group of related remote procedures, each of
311 which has a different procedure number. Each program also
312 has a version number, so when a minor change is made to a
313 remote service (adding a new procedure, for example), a new
314 program number doesn't have to be assigned. When you want
315 to call a procedure to find the number of remote users, you
316 look up the appropriate program, version and procedure numbers
317 in a manual, just as you look up the name of a memory allocator
318 when you want to allocate memory.
320 The simplest way of making remote procedure calls is with the the RPC
323 It has eight parameters. The first is the name of the remote server
324 machine. The next three parameters are the program, version, and procedure
325 numbers\(emtogether they identify the procedure to be called.
326 The fifth and sixth parameters are an XDR filter and an argument to
327 be encoded and passed to the remote procedure.
328 The final two parameters are a filter for decoding the results
329 returned by the remote procedure and a pointer to the place where
330 the procedure's results are to be stored. Multiple arguments and
331 results are handled by embedding them in structures. If
333 completes successfully, it returns zero; else it returns a nonzero
334 value. The return codes (of type
335 .IX "enum clnt_stat (in RPC programming)" "" "\fIenum clnt_stat\fP (in RPC programming)"
336 cast into an integer) are found in
339 Since data types may be represented differently on different machines,
341 needs both the type of the RPC argument, as well as
342 a pointer to the argument itself (and similarly for the result). For
344 the return value is an
350 as its first return parameter, which says
351 that the result is of type
355 as its second return parameter,
356 which is a pointer to where the long result will be placed. Since
358 takes no argument, the argument parameter of
363 After trying several times to deliver a message, if
365 gets no answer, it returns with an error code.
366 The delivery mechanism is UDP,
367 which stands for User Datagram Protocol.
368 Methods for adjusting the number of retries
369 or for using a different protocol require you to use the lower
370 layer of the RPC library, discussed later in this document.
371 The remote server procedure
372 corresponding to the above might look like this:
381 unsigned long nusers;
385 * Code here to compute the number of users
386 * and place result in variable \fInusers\fP.
389 return((char *)&nusers);
393 It takes one argument, which is a pointer to the input
394 of the remote procedure call (ignored in our example),
395 and it returns a pointer to the result.
396 In the current version of C,
397 character pointers are the generic pointers,
398 so both the input argument and the return value are cast to
401 Normally, a server registers all of the RPC calls it plans
402 to handle, and then goes into an infinite loop waiting to service requests.
403 In this example, there is only a single procedure
404 to register, so the main body of the server would look like this:
411 #include <rpcsvc/rusers.h>
417 registerrpc(RUSERSPROG, RUSERSVERS, RUSERSPROC_NUM,
418 nuser, xdr_void, xdr_u_long);
419 svc_run(); /* \fINever returns\fP */
420 fprintf(stderr, "Error: svc_run returned!\en");
427 routine registers a C procedure as corresponding to a
428 given RPC procedure number. The first three parameters,
433 are the program, version, and procedure numbers
434 of the remote procedure to be registered;
436 is the name of the local procedure that implements the remote
441 are the XDR filters for the remote procedure's arguments and
442 results, respectively. (Multiple arguments or multiple results
443 are passed as structures).
445 Only the UDP transport mechanism can use
447 thus, it is always safe in conjunction with calls generated by
451 Warning: the UDP transport mechanism can only deal with
452 arguments and results less than 8K bytes in length.
455 After registering the local procedure, the server program's
458 the RPC library's remote procedure dispatcher. It is this
459 function that calls the remote procedures in response to RPC
460 call messages. Note that the dispatcher takes care of decoding
461 remote procedure arguments and encoding results, using the XDR
462 filters specified when the remote procedure was registered.
464 \&Assigning Program Numbers
465 .IX "program number assignment"
466 .IX "assigning program numbers"
468 Program numbers are assigned in groups of
470 according to the following chart:
473 0x0 - 0x1fffffff \fRDefined by Sun\fP
474 0x20000000 - 0x3fffffff \fRDefined by user\fP
475 0x40000000 - 0x5fffffff \fRTransient\fP
476 0x60000000 - 0x7fffffff \fRReserved\fP
477 0x80000000 - 0x9fffffff \fRReserved\fP
478 0xa0000000 - 0xbfffffff \fRReserved\fP
479 0xc0000000 - 0xdfffffff \fRReserved\fP
480 0xe0000000 - 0xffffffff \fRReserved\fP
483 Sun Microsystems administers the first group of numbers, which
484 should be identical for all Sun customers. If a customer
485 develops an application that might be of general interest, that
486 application should be given an assigned number in the first
487 range. The second group of numbers is reserved for specific
488 customer applications. This range is intended primarily for
489 debugging new programs. The third group is reserved for
490 applications that generate program numbers dynamically. The
491 final groups are reserved for future use, and should not be
494 To register a protocol specification, send a request by network
502 Mountain View, CA 94043
504 Please include a compilable
506 \*Q.x\*U file describing your protocol.
507 You will be given a unique program number in return.
508 .IX RPC administration
509 .IX administration "of RPC"
511 The RPC program numbers and protocol specifications
512 of standard Sun RPC services can be
513 found in the include files in
514 .I "/usr/include/rpcsvc" .
515 These services, however, constitute only a small subset
516 of those which have been registered. The complete list of
517 registered programs, as of the time when this manual was
520 \fBTable 3-2\fI RPC Registered Programs\fR
525 RPC Number&Program&Description
529 100000&PMAPPROG&portmapper
530 100001&RSTATPROG&remote stats
531 100002&RUSERSPROG&remote users
533 100004&YPPROG&Yellow Pages
534 100005&MOUNTPROG&mount daemon
535 100006&DBXPROG&remote dbx
536 100007&YPBINDPROG&yp binder
537 100008&WALLPROG&shutdown msg
538 100009&YPPASSWDPROG&yppasswd server
539 100010ÐERSTATPROGðer stats
540 100011&RQUOTAPROG&disk quotas
541 100012&SPRAYPROG&spray packets
542 100013&IBM3270PROG&3270 mapper
543 100014&IBMRJEPROG&RJE mapper
544 100015&SELNSVCPROG&selection service
545 100016&RDATABASEPROG&remote database access
546 100017&REXECPROG&remote execution
547 100018&ALICEPROG&Alice Office Automation
548 100019&SCHEDPROG&scheduling service
549 100020&LOCKPROG&local lock manager
550 100021&NETLOCKPROG&network lock manager
551 100022&X25PROG&x.25 inr protocol
552 100023&STATMON1PROG&status monitor 1
553 100024&STATMON2PROG&status monitor 2
554 100025&SELNLIBPROG&selection library
555 100026&BOOTPARAMPROG&boot parameters service
556 100027&MAZEPROG&mazewars game
557 100028&YPUPDATEPROG&yp update
558 100029&KEYSERVEPROG&key server
559 100030&SECURECMDPROG&secure login
560 100031&NETFWDIPROG&nfs net forwarder init
561 100032&NETFWDTPROG&nfs net forwarder trans
562 100033&SUNLINKMAP_PROG&sunlink MAP
563 100034&NETMONPROG&network monitor
564 100035&DBASEPROG&lightweight database
565 100036&PWDAUTHPROG&password authorization
566 100037&TFSPROG&translucent file svc
567 100038&NSEPROG&nse server
568 100039&NSE_ACTIVATE_PROG&nse activate daemon
570 150001&PCNFSDPROG&pc passwd authorization
572 200000&PYRAMIDLOCKINGPROG&Pyramid-locking
573 200001&PYRAMIDSYS5&Pyramid-sys5
574 200002&CADDS_IMAGE&CV cadds_image
576 300001&ADT_RFLOCKPROG&ADT file locking
579 \&Passing Arbitrary Data Types
580 .IX "arbitrary data types"
582 In the previous example, the RPC call passes a single
584 RPC can handle arbitrary data structures, regardless of
585 different machines' byte orders or structure layout conventions,
586 by always converting them to a network standard called
587 .I "External Data Representation"
589 sending them over the wire.
590 The process of converting from a particular machine representation
591 to XDR format is called
593 and the reverse process is called
595 The type field parameters of
599 can be a built-in procedure like
601 in the previous example, or a user supplied one.
602 XDR has these built-in type routines:
603 .IX RPC "built-in routines"
606 xdr_int() xdr_u_int() xdr_enum()
607 xdr_long() xdr_u_long() xdr_bool()
608 xdr_short() xdr_u_short() xdr_wrapstring()
609 xdr_char() xdr_u_char()
611 Note that the routine
613 exists, but cannot be used with
617 which only pass two parameters to their XDR routines.
619 has only two parameters, and is thus OK. It calls
622 As an example of a user-defined type routine,
623 if you wanted to send the structure
636 callrpc(hostname, PROGNUM, VERSNUM, PROCNUM,
637 xdr_simple, &simple ...);
647 xdr_simple(xdrsp, simplep)
649 struct simple *simplep;
651 if (!xdr_int(xdrsp, &simplep->a))
653 if (!xdr_short(xdrsp, &simplep->b))
659 An XDR routine returns nonzero (true in the sense of C) if it
660 completes successfully, and zero otherwise.
661 A complete description of XDR is in the
662 .I "XDR Protocol Specification"
663 section of this manual, only few implementation examples are
666 In addition to the built-in primitives,
667 there are also the prefabricated building blocks:
670 xdr_array() xdr_bytes() xdr_reference()
671 xdr_vector() xdr_union() xdr_pointer()
672 xdr_string() xdr_opaque()
674 To send a variable array of integers,
675 you might package them up as a structure like this
683 and make an RPC call such as
686 callrpc(hostname, PROGNUM, VERSNUM, PROCNUM,
687 xdr_varintarr, &arr...);
695 xdr_varintarr(xdrsp, arrp)
697 struct varintarr *arrp;
699 return (xdr_array(xdrsp, &arrp->data, &arrp->arrlnth,
700 MAXLEN, sizeof(int), xdr_int));
703 This routine takes as parameters the XDR handle,
704 a pointer to the array, a pointer to the size of the array,
705 the maximum allowable array size,
706 the size of each array element,
707 and an XDR routine for handling each array element.
710 If the size of the array is known in advance, one can use
712 which serializes fixed-length arrays.
718 xdr_intarr(xdrsp, intarr)
724 return (xdr_vector(xdrsp, intarr, SIZE, sizeof(int),
730 XDR always converts quantities to 4-byte multiples when serializing.
731 Thus, if either of the examples above involved characters
732 instead of integers, each character would occupy 32 bits.
733 That is the reason for the XDR routine
737 except that it packs characters;
739 has four parameters, similar to the first four parameters of
741 For null-terminated strings, there is also the
743 routine, which is the same as
745 without the length parameter.
746 On serializing it gets the string length from
748 and on deserializing it creates a null-terminated string.
750 Here is a final example that calls the previously written
752 as well as the built-in functions
756 which chases pointers:
760 struct finalexample {
762 struct simple *simplep;
765 xdr_finalexample(xdrsp, finalp)
767 struct finalexample *finalp;
770 if (!xdr_string(xdrsp, &finalp->string, MAXSTRLEN))
772 if (!xdr_reference(xdrsp, &finalp->simplep,
773 sizeof(struct simple), xdr_simple);
778 Note that we could as easily call
783 \&Lowest Layer of RPC
784 .IX "lowest layer of RPC"
785 .IX "RPC" "lowest layer"
787 In the examples given so far,
788 RPC takes care of many details automatically for you.
789 In this section, we'll show you how you can change the defaults
790 by using lower layers of the RPC library.
791 It is assumed that you are familiar with sockets
792 and the system calls for dealing with them.
794 There are several occasions when you may need to use lower layers of
795 RPC. First, you may need to use TCP, since the higher layer uses UDP,
796 which restricts RPC calls to 8K bytes of data. Using TCP permits calls
797 to send long streams of data.
798 For an example, see the
800 section below. Second, you may want to allocate and free memory
801 while serializing or deserializing with XDR routines.
802 There is no call at the higher level to let
803 you free memory explicitly.
804 For more explanation, see the
805 .I "Memory Allocation with XDR"
807 Third, you may need to perform authentication
808 on either the client or server side, by supplying
809 credentials or verifying them.
810 See the explanation in the
814 \&More on the Server Side
815 .IX RPC "server side"
819 program shown below does the same thing as the one using
821 above, but is written using a lower layer of the RPC package:
828 #include <rpcsvc/rusers.h>
835 transp = svcudp_create(RPC_ANYSOCK);
837 fprintf(stderr, "can't create an RPC server\en");
840 pmap_unset(RUSERSPROG, RUSERSVERS);
841 if (!svc_register(transp, RUSERSPROG, RUSERSVERS,
842 nuser, IPPROTO_UDP)) {
843 fprintf(stderr, "can't register RUSER service\en");
846 svc_run(); /* \fINever returns\fP */
847 fprintf(stderr, "should never reach this point\en");
851 struct svc_req *rqstp;
854 unsigned long nusers;
856 switch (rqstp->rq_proc) {
858 if (!svc_sendreply(transp, xdr_void, 0))
859 fprintf(stderr, "can't reply to RPC call\en");
864 * Code here to compute the number of users
865 * and assign it to the variable \fInusers\fP
868 if (!svc_sendreply(transp, xdr_u_long, &nusers))
869 fprintf(stderr, "can't reply to RPC call\en");
872 svcerr_noproc(transp);
878 First, the server gets a transport handle, which is used
879 for receiving and replying to RPC messages.
884 If you require a more reliable protocol, call
891 the RPC library creates a socket
892 on which to receive and reply to RPC calls. Otherwise,
894 expects its argument to be a valid socket number.
895 If you specify your own socket, it can be bound or unbound.
896 If it is bound to a port by the user, the port numbers of
900 (the low-level client routine) must match.
902 If the user specifies the
904 argument, the RPC library routines will open sockets.
905 Otherwise they will expect the user to do so. The routines
909 will cause the RPC library routines to
911 their socket if it is not bound already.
913 A service may choose to register its port number with the
914 local portmapper service. This is done is done by specifying
915 a non-zero protocol number in
917 Incidently, a client can discover the server's port number by
918 consulting the portmapper on their server's machine. This can
919 be done automatically by specifying a zero port number in
922 .I clnttcp_create ().
926 the next step is to call
930 server crashed earlier,
931 any previous trace of it is erased before restarting.
936 from the port mapper's tables.
938 Finally, we associate the program number for
942 The final argument to
944 is normally the protocol being used,
945 which, in this case, is
949 there are no XDR routines involved
950 in the registration process.
951 Also, registration is done on the program,
952 rather than procedure, level.
956 must call and dispatch the appropriate XDR routines
957 based on the procedure number.
959 two things are handled by
963 handles automatically.
964 The first is that procedure
966 (currently zero) returns with no results.
967 This can be used as a simple test
968 for detecting if a remote program is running.
969 Second, there is a check for invalid procedure numbers.
972 is called to handle the error.
975 The user service routine serializes the results and returns
976 them to the RPC caller via
978 Its first parameter is the
980 handle, the second is the XDR routine,
981 and the third is a pointer to the data to be returned.
982 Not illustrated above is how a server
983 handles an RPC program that receives data.
984 As an example, we can add a procedure
986 which has an argument
992 depending on whether there are nusers logged on.
993 It would look like this:
997 case RUSERSPROC_BOOL: {
1001 if (!svc_getargs(transp, xdr_u_int, &nuserquery) {
1002 svcerr_decode(transp);
1007 * Code to set \fInusers\fP = number of users
1010 if (nuserquery == nusers)
1014 if (!svc_sendreply(transp, xdr_bool, &bool)) {
1015 fprintf(stderr, "can't reply to RPC call\en");
1023 The relevant routine is
1027 handle, the XDR routine,
1028 and a pointer to where the input is to be placed as arguments.
1030 \&Memory Allocation with XDR
1031 .IX "memory allocation with XDR"
1032 .IX XDR "memory allocation"
1034 XDR routines not only do input and output,
1035 they also do memory allocation.
1036 This is why the second parameter of
1038 is a pointer to an array, rather than the array itself.
1043 allocates space for the array and returns a pointer to it,
1044 putting the size of the array in the third argument.
1045 As an example, consider the following XDR routine
1047 which deals with a fixed array of bytes with length
1052 xdr_chararr1(xdrsp, chararr)
1061 return (xdr_bytes(xdrsp, &p, &len, SIZE));
1064 If space has already been allocated in
1066 it can be called from a server like this:
1072 svc_getargs(transp, xdr_chararr1, chararr);
1074 If you want XDR to do the allocation,
1075 you would have to rewrite this routine in the following way:
1079 xdr_chararr2(xdrsp, chararrp)
1086 return (xdr_bytes(xdrsp, charrarrp, &len, SIZE));
1089 Then the RPC call might look like this:
1096 svc_getargs(transp, xdr_chararr2, &arrptr);
1099 * Use the result here
1102 svc_freeargs(transp, xdr_chararr2, &arrptr);
1104 Note that, after being used, the character array can be freed with
1107 will not attempt to free any memory if the variable indicating it
1108 is NULL. For example, in the the routine
1109 .I xdr_finalexample (),
1112 was NULL, then it would not be freed. The same is true for
1113 .I finalp->simplep .
1115 To summarize, each XDR routine is responsible
1116 for serializing, deserializing, and freeing memory.
1117 When an XDR routine is called from
1119 the serializing part is used.
1122 the deserializer is used.
1123 And when called from
1125 the memory deallocator is used. When building simple examples like those
1126 in this section, a user doesn't have to worry
1127 about the three modes.
1129 .I "External Data Representation: Sun Technical Notes"
1130 for examples of more sophisticated XDR routines that determine
1131 which of the three modes they are in and adjust their behavior accordingly.
1135 .IX RPC "calling side"
1139 you have no control over the RPC delivery
1140 mechanism or the socket used to transport the data.
1141 To illustrate the layer of RPC that lets you adjust these
1142 parameters, consider the following code to call the
1150 #include <rpc/rpc.h>
1152 #include <rpcsvc/rusers.h>
1153 #include <sys/socket.h>
1154 #include <sys/time.h>
1162 struct timeval pertry_timeout, total_timeout;
1163 struct sockaddr_in server_addr;
1164 int sock = RPC_ANYSOCK;
1165 register CLIENT *client;
1166 enum clnt_stat clnt_stat;
1167 unsigned long nusers;
1170 fprintf(stderr, "usage: nusers hostname\en");
1173 if ((hp = gethostbyname(argv[1])) == NULL) {
1174 fprintf(stderr, "can't get addr for %s\en",argv[1]);
1177 pertry_timeout.tv_sec = 3;
1178 pertry_timeout.tv_usec = 0;
1179 bcopy(hp->h_addr, (caddr_t)&server_addr.sin_addr,
1181 server_addr.sin_family = AF_INET;
1182 server_addr.sin_port = 0;
1183 if ((client = clntudp_create(&server_addr, RUSERSPROG,
1184 RUSERSVERS, pertry_timeout, &sock)) == NULL) {
1185 clnt_pcreateerror("clntudp_create");
1188 total_timeout.tv_sec = 20;
1189 total_timeout.tv_usec = 0;
1190 clnt_stat = clnt_call(client, RUSERSPROC_NUM, xdr_void,
1191 0, xdr_u_long, &nusers, total_timeout);
1192 if (clnt_stat != RPC_SUCCESS) {
1193 clnt_perror(client, "rpc");
1196 clnt_destroy(client);
1203 The low-level version of
1209 pointer rather than a host name. The parameters to
1213 pointer, the procedure number,
1214 the XDR routine for serializing the argument,
1215 a pointer to the argument,
1216 the XDR routine for deserializing the return value,
1217 a pointer to where the return value will be placed,
1218 and the time in seconds to wait for a reply.
1222 pointer is encoded with the transport mechanism.
1224 uses UDP, thus it calls
1228 pointer. To get TCP (Transmission Control Protocol), you would use
1229 .I clnttcp_create() .
1233 are the server address, the program number, the version number,
1234 a timeout value (between tries), and a pointer to a socket.
1235 The final argument to
1237 is the total time to wait for a response.
1238 Thus, the number of tries is the
1240 timeout divided by the
1247 always deallocates the space associated with the
1249 handle. It closes the socket associated with the
1251 handle, however, only if the RPC library opened it. It the
1252 socket was opened by the user, it stays open. This makes it
1253 possible, in cases where there are multiple client handles
1254 using the same socket, to destroy one handle without closing
1255 the socket that other handles are using.
1257 To make a stream connection, the call to
1259 is replaced with a call to
1260 .I clnttcp_create() .
1263 clnttcp_create(&server_addr, prognum, versnum, &sock,
1264 inputsize, outputsize);
1266 There is no timeout argument; instead, the receive and send buffer
1267 sizes must be specified. When the
1269 call is made, a TCP connection is established.
1270 All RPC calls using that
1272 handle would use this connection.
1273 The server side of an RPC call using TCP has
1276 .I svctcp_create() .
1279 transp = svctcp_create(RPC_ANYSOCK, 0, 0);
1281 The last two arguments to
1283 are send and receive sizes respectively. If `0' is specified for
1284 either of these, the system chooses a reasonable default.
1287 \&Other RPC Features
1288 .IX "RPC" "miscellaneous features"
1289 .IX "miscellaneous RPC features"
1291 This section discusses some other aspects of RPC
1292 that are occasionally useful.
1294 \&Select on the Server Side
1295 .IX RPC select() RPC \fIselect()\fP
1296 .IX select() "" \fIselect()\fP "on the server side"
1298 Suppose a process is processing RPC requests
1299 while performing some other activity.
1300 If the other activity involves periodically updating a data structure,
1301 the process can set an alarm signal before calling
1303 But if the other activity
1304 involves waiting on a file descriptor, the
1318 int dtbsz = getdtablesize();
1322 switch (select(dtbsz, &readfds, NULL,NULL,NULL)) {
1332 svc_getreqset(&readfds);
1345 All you need to know are the file descriptors
1346 of the socket(s) associated with the programs you are waiting on.
1347 Thus you can have your own
1349 .IX select() "" \fIselect()\fP
1350 that waits on both the RPC socket,
1351 and your own descriptors. Note that
1353 is a bit mask of all the file descriptors that RPC is using for
1354 services. It can change everytime that
1356 RPC library routine is called, because descriptors are constantly
1357 being opened and closed, for example for TCP connections.
1365 is a daemon that converts RPC program numbers
1366 into DARPA protocol port numbers; see the
1368 man page. You can't do broadcast RPC without the portmapper.
1369 Here are the main differences between
1370 broadcast RPC and normal RPC calls:
1372 Normal RPC expects one answer, whereas
1373 broadcast RPC expects many answers
1374 (one or more answer from each responding machine).
1376 Broadcast RPC can only be supported by packet-oriented (connectionless)
1377 transport protocols like UPD/IP.
1379 The implementation of broadcast RPC
1380 treats all unsuccessful responses as garbage by filtering them out.
1381 Thus, if there is a version mismatch between the
1382 broadcaster and a remote service,
1383 the user of broadcast RPC never knows.
1385 All broadcast messages are sent to the portmap port.
1386 Thus, only services that register themselves with their portmapper
1387 are accessible via the broadcast RPC mechanism.
1389 Broadcast requests are limited in size to the MTU (Maximum Transfer
1390 Unit) of the local network. For Ethernet, the MTU is 1500 bytes.
1393 \&Broadcast RPC Synopsis
1394 .IX "broadcast RPC" synopsis
1395 .IX "RPC" "broadcast synopsis"
1399 #include <rpc/pmap_clnt.h>
1401 enum clnt_stat clnt_stat;
1403 clnt_stat = clnt_broadcast(prognum, versnum, procnum,
1404 inproc, in, outproc, out, eachresult)
1405 u_long prognum; /* \fIprogram number\fP */
1406 u_long versnum; /* \fIversion number\fP */
1407 u_long procnum; /* \fIprocedure number\fP */
1408 xdrproc_t inproc; /* \fIxdr routine for args\fP */
1409 caddr_t in; /* \fIpointer to args\fP */
1410 xdrproc_t outproc; /* \fIxdr routine for results\fP */
1411 caddr_t out; /* \fIpointer to results\fP */
1412 bool_t (*eachresult)();/* \fIcall with each result gotten\fP */
1417 is called each time a valid result is obtained.
1418 It returns a boolean that indicates
1419 whether or not the user wants more responses.
1425 done = eachresult(resultsp, raddr)
1427 struct sockaddr_in *raddr; /* \fIAddr of responding machine\fP */
1433 then broadcasting stops and
1435 returns successfully.
1436 Otherwise, the routine waits for another response.
1437 The request is rebroadcast
1438 after a few seconds of waiting.
1439 If no responses come back,
1440 the routine returns with
1447 The RPC architecture is designed so that clients send a call message,
1448 and wait for servers to reply that the call succeeded.
1449 This implies that clients do not compute
1450 while servers are processing a call.
1451 This is inefficient if the client does not want or need
1452 an acknowledgement for every message sent.
1453 It is possible for clients to continue computing
1454 while waiting for a response,
1455 using RPC batch facilities.
1457 RPC messages can be placed in a \*Qpipeline\*U of calls
1458 to a desired server; this is called batching.
1459 Batching assumes that:
1460 1) each RPC call in the pipeline requires no response from the server,
1461 and the server does not send a response message; and
1462 2) the pipeline of calls is transported on a reliable
1463 byte stream transport such as TCP/IP.
1464 Since the server does not respond to every call,
1465 the client can generate new calls in parallel
1466 with the server executing previous calls.
1467 Furthermore, the TCP/IP implementation can buffer up
1468 many call messages, and send them to the server in one
1470 system call. This overlapped execution
1471 greatly decreases the interprocess communication overhead of
1472 the client and server processes,
1473 and the total elapsed time of a series of calls.
1475 Since the batched calls are buffered,
1476 the client should eventually do a nonbatched call
1477 in order to flush the pipeline.
1479 A contrived example of batching follows.
1480 Assume a string rendering service (like a window system)
1481 has two similar calls: one renders a string and returns void results,
1482 while the other renders a string and remains silent.
1483 The service (using the TCP/IP transport) may look like:
1488 #include <rpc/rpc.h>
1489 #include <suntool/windows.h>
1491 void windowdispatch();
1497 transp = svctcp_create(RPC_ANYSOCK, 0, 0);
1498 if (transp == NULL){
1499 fprintf(stderr, "can't create an RPC server\en");
1502 pmap_unset(WINDOWPROG, WINDOWVERS);
1503 if (!svc_register(transp, WINDOWPROG, WINDOWVERS,
1504 windowdispatch, IPPROTO_TCP)) {
1505 fprintf(stderr, "can't register WINDOW service\en");
1508 svc_run(); /* \fINever returns\fP */
1509 fprintf(stderr, "should never reach this point\en");
1513 windowdispatch(rqstp, transp)
1514 struct svc_req *rqstp;
1519 switch (rqstp->rq_proc) {
1521 if (!svc_sendreply(transp, xdr_void, 0))
1522 fprintf(stderr, "can't reply to RPC call\en");
1525 if (!svc_getargs(transp, xdr_wrapstring, &s)) {
1526 fprintf(stderr, "can't decode arguments\en");
1529 * Tell caller he screwed up
1532 svcerr_decode(transp);
1537 * Code here to render the string \fIs\fP
1540 if (!svc_sendreply(transp, xdr_void, NULL))
1541 fprintf(stderr, "can't reply to RPC call\en");
1543 case RENDERSTRING_BATCHED:
1544 if (!svc_getargs(transp, xdr_wrapstring, &s)) {
1545 fprintf(stderr, "can't decode arguments\en");
1548 * We are silent in the face of protocol errors
1555 * Code here to render string s, but send no reply!
1560 svcerr_noproc(transp);
1565 * Now free string allocated while decoding arguments
1568 svc_freeargs(transp, xdr_wrapstring, &s);
1571 Of course the service could have one procedure
1572 that takes the string and a boolean
1573 to indicate whether or not the procedure should respond.
1575 In order for a client to take advantage of batching,
1576 the client must perform RPC calls on a TCP-based transport
1577 and the actual calls must have the following attributes:
1578 1) the result's XDR routine must be zero
1580 and 2) the RPC call's timeout must be zero.
1583 Here is an example of a client that uses batching to render a
1584 bunch of strings; the batching is flushed when the client gets
1585 a null string (EOF):
1591 #include <rpc/rpc.h>
1592 #include <sys/socket.h>
1593 #include <sys/time.h>
1595 #include <suntool/windows.h>
1602 struct timeval pertry_timeout, total_timeout;
1603 struct sockaddr_in server_addr;
1604 int sock = RPC_ANYSOCK;
1605 register CLIENT *client;
1606 enum clnt_stat clnt_stat;
1607 char buf[1000], *s = buf;
1609 if ((client = clnttcp_create(&server_addr,
1610 WINDOWPROG, WINDOWVERS, &sock, 0, 0)) == NULL) {
1611 perror("clnttcp_create");
1614 total_timeout.tv_sec = 0;
1615 total_timeout.tv_usec = 0;
1616 while (scanf("%s", s) != EOF) {
1617 clnt_stat = clnt_call(client, RENDERSTRING_BATCHED,
1618 xdr_wrapstring, &s, NULL, NULL, total_timeout);
1619 if (clnt_stat != RPC_SUCCESS) {
1620 clnt_perror(client, "batched rpc");
1625 /* \fINow flush the pipeline\fP */
1627 total_timeout.tv_sec = 20;
1628 clnt_stat = clnt_call(client, NULLPROC, xdr_void, NULL,
1629 xdr_void, NULL, total_timeout);
1630 if (clnt_stat != RPC_SUCCESS) {
1631 clnt_perror(client, "rpc");
1634 clnt_destroy(client);
1640 Since the server sends no message,
1641 the clients cannot be notified of any of the failures that may occur.
1642 Therefore, clients are on their own when it comes to handling errors.
1644 The above example was completed to render
1645 all of the (2000) lines in the file
1647 The rendering service did nothing but throw the lines away.
1648 The example was run in the following four configurations:
1649 1) machine to itself, regular RPC;
1650 2) machine to itself, batched RPC;
1651 3) machine to another, regular RPC; and
1652 4) machine to another, batched RPC.
1653 The results are as follows:
1662 only requires six seconds.
1663 These timings show the advantage of protocols
1664 that allow for overlapped execution,
1665 though these protocols are often hard to design.
1668 .IX "authentication"
1669 .IX "RPC" "authentication"
1671 In the examples presented so far,
1672 the caller never identified itself to the server,
1673 and the server never required an ID from the caller.
1674 Clearly, some network services, such as a network filesystem,
1675 require stronger security than what has been presented so far.
1677 In reality, every RPC call is authenticated by
1678 the RPC package on the server, and similarly,
1679 the RPC client package generates and sends authentication parameters.
1680 Just as different transports (TCP/IP or UDP/IP)
1681 can be used when creating RPC clients and servers,
1682 different forms of authentication can be associated with RPC clients;
1683 the default authentication type used as a default is type
1686 The authentication subsystem of the RPC package is open ended.
1687 That is, numerous types of authentication are easy to support.
1689 \&UNIX Authentication
1690 .IX "UNIX Authentication"
1691 .IP "\fIThe Client Side\fP"
1693 When a caller creates a new RPC client handle as in:
1696 clnt = clntudp_create(address, prognum, versnum,
1699 the appropriate transport instance defaults
1700 the associate authentication handle to be
1703 clnt->cl_auth = authnone_create();
1705 The RPC client can choose to use
1707 style authentication by setting
1709 after creating the RPC client handle:
1712 clnt->cl_auth = authunix_create_default();
1714 This causes each RPC call associated with
1716 to carry with it the following authentication credentials structure:
1721 * UNIX style credentials.
1724 struct authunix_parms {
1725 u_long aup_time; /* \fIcredentials creation time\fP */
1726 char *aup_machname; /* \fIhost name where client is\fP */
1727 int aup_uid; /* \fIclient's UNIX effective uid\fP */
1728 int aup_gid; /* \fIclient's current group id\fP */
1729 u_int aup_len; /* \fIelement length of aup_gids\fP */
1730 int *aup_gids; /* \fIarray of groups user is in\fP */
1733 These fields are set by
1734 .I authunix_create_default()
1735 by invoking the appropriate system calls.
1736 Since the RPC user created this new style of authentication,
1737 the user is responsible for destroying it with:
1740 auth_destroy(clnt->cl_auth);
1742 This should be done in all cases, to conserve memory.
1744 .IP "\fIThe Server Side\fP"
1746 Service implementors have a harder time dealing with authentication issues
1747 since the RPC package passes the service dispatch routine a request
1748 that has an arbitrary authentication style associated with it.
1749 Consider the fields of a request handle passed to a service dispatch routine:
1754 * An RPC Service request
1758 u_long rq_prog; /* \fIservice program number\fP */
1759 u_long rq_vers; /* \fIservice protocol vers num\fP */
1760 u_long rq_proc; /* \fIdesired procedure number\fP */
1761 struct opaque_auth rq_cred; /* \fIraw credentials from wire\fP */
1762 caddr_t rq_clntcred; /* \fIcredentials (read only)\fP */
1767 is mostly opaque, except for one field of interest:
1768 the style or flavor of authentication credentials:
1773 * Authentication info. Mostly opaque to the programmer.
1776 struct opaque_auth {
1777 enum_t oa_flavor; /* \fIstyle of credentials\fP */
1778 caddr_t oa_base; /* \fIaddress of more auth stuff\fP */
1779 u_int oa_length; /* \fInot to exceed \fIMAX_AUTH_BYTES */
1783 The RPC package guarantees the following
1784 to the service dispatch routine:
1788 is well formed. Thus the service implementor may inspect the request's
1789 .I rq_cred.oa_flavor
1790 to determine which style of authentication the caller used.
1791 The service implementor may also wish to inspect the other fields of
1793 if the style is not one of the styles supported by the RPC package.
1799 or points to a well formed structure
1800 that corresponds to a supported style of authentication credentials.
1803 style is currently supported, so (currently)
1805 could be cast to a pointer to an
1811 the service implementor may wish to inspect the other (opaque) fields of
1813 in case the service knows about a new type of authentication
1814 that the RPC package does not know about.
1816 Our remote users service example can be extended so that
1817 it computes results for all users except UID 16:
1822 nuser(rqstp, transp)
1823 struct svc_req *rqstp;
1826 struct authunix_parms *unix_cred;
1828 unsigned long nusers;
1832 * we don't care about authentication for null proc
1835 if (rqstp->rq_proc == NULLPROC) {
1836 if (!svc_sendreply(transp, xdr_void, 0)) {
1837 fprintf(stderr, "can't reply to RPC call\en");
1847 switch (rqstp->rq_cred.oa_flavor) {
1850 (struct authunix_parms *)rqstp->rq_clntcred;
1851 uid = unix_cred->aup_uid;
1855 svcerr_weakauth(transp);
1858 switch (rqstp->rq_proc) {
1859 case RUSERSPROC_NUM:
1862 * make sure caller is allowed to call this proc
1866 svcerr_systemerr(transp);
1871 * Code here to compute the number of users
1872 * and assign it to the variable \fInusers\fP
1875 if (!svc_sendreply(transp, xdr_u_long, &nusers)) {
1876 fprintf(stderr, "can't reply to RPC call\en");
1881 svcerr_noproc(transp);
1887 A few things should be noted here.
1888 First, it is customary not to check
1889 the authentication parameters associated with the
1891 (procedure number zero).
1892 Second, if the authentication parameter's type is not suitable
1893 for your service, you should call
1894 .I svcerr_weakauth() .
1895 And finally, the service protocol itself should return status
1896 for access denied; in the case of our example, the protocol
1897 does not have such a status, so we call the service primitive
1898 .I svcerr_systemerr()
1901 The last point underscores the relation between
1902 the RPC authentication package and the services;
1905 and not with individual services'
1906 .I "access control" .
1907 The services themselves must implement their own access control policies
1908 and reflect these policies as return statuses in their protocols.
1910 \&DES Authentication
1912 .IX RPC authentication
1914 UNIX authentication is quite easy to defeat. Instead of using
1915 .I authunix_create_default (),
1917 .I authunix_create()
1918 and then modify the RPC authentication handle it returns by filling in
1919 whatever user ID and hostname they wish the server to think they have.
1920 DES authentication is thus recommended for people who want more security
1921 than UNIX authentication offers.
1923 The details of the DES authentication protocol are complicated and
1924 are not explained here.
1926 .I "Remote Procedure Calls: Protocol Specification"
1929 In order for DES authentication to work, the
1931 daemon must be running on both the server and client machines. The
1932 users on these machines need public keys assigned by the network
1933 administrator in the
1935 database. And, they need to have decrypted their secret keys
1936 using their login password. This automatically happens when one
1939 or can be done manually using
1942 .I "Network Services"
1945 explains more how to setup secure networking.
1947 .IP "\fIClient Side\fP"
1949 If a client wishes to use DES authentication, it must set its
1950 authentication handle appropriately. Here is an example:
1953 authdes_create(servername, 60, &server_addr, NULL);
1955 The first argument is the network name or \*Qnetname\*U of the owner of
1956 the server process. Typically, server processes are root processes
1957 and their netname can be derived using the following call:
1959 char servername[MAXNETNAMELEN];
1961 host2netname(servername, rhostname, NULL);
1965 is the hostname of the machine the server process is running on.
1969 to contain this root process's netname. If the
1970 server process was run by a regular user, one could use the call
1972 instead. Here is an example for a server process with the same user
1975 char servername[MAXNETNAMELEN];
1977 user2netname(servername, getuid(), NULL);
1979 The last argument to both of these calls,
1983 is the name of the naming domain where the server is located. The
1985 used here means \*Quse the local domain name.\*U
1987 The second argument to
1989 is a lifetime for the credential. Here it is set to sixty
1990 seconds. What that means is that the credential will expire 60
1991 seconds from now. If some mischievous user tries to reuse the
1992 credential, the server RPC subsystem will recognize that it has
1993 expired and not grant any requests. If the same mischievous user
1994 tries to reuse the credential within the sixty second lifetime,
1995 he will still be rejected because the server RPC subsystem
1996 remembers which credentials it has already seen in the near past,
1997 and will not grant requests to duplicates.
1999 The third argument to
2001 is the address of the host to synchronize with. In order for DES
2002 authentication to work, the server and client must agree upon the
2003 time. Here we pass the address of the server itself, so the
2004 client and server will both be using the same time: the server's
2005 time. The argument can be
2007 which means \*Qdon't bother synchronizing.\*U You should only do this
2008 if you are sure the client and server are already synchronized.
2010 The final argument to
2012 is the address of a DES encryption key to use for encrypting
2013 timestamps and data. If this argument is
2015 as it is in this example, a random key will be chosen. The client
2016 may find out the encryption key being used by consulting the
2018 field of the authentication handle.
2020 .IP "\fIServer Side\fP"
2022 The server side is a lot simpler than the client side. Here is the
2023 previous example rewritten to use
2031 #include <sys/time.h>
2032 #include <rpc/auth_des.h>
2035 nuser(rqstp, transp)
2036 struct svc_req *rqstp;
2039 struct authdes_cred *des_cred;
2046 * we don't care about authentication for null proc
2050 if (rqstp->rq_proc == NULLPROC) {
2051 /* \fIsame as before\fP */
2059 switch (rqstp->rq_cred.oa_flavor) {
2062 (struct authdes_cred *) rqstp->rq_clntcred;
2063 if (! netname2user(des_cred->adc_fullname.name,
2064 &uid, &gid, &gidlen, gidlist))
2066 fprintf(stderr, "unknown user: %s\en",
2067 des_cred->adc_fullname.name);
2068 svcerr_systemerr(transp);
2074 svcerr_weakauth(transp);
2080 * The rest is the same as before
2085 Note the use of the routine
2089 it takes a network ID and converts to a unix ID.
2091 also supplies the group IDs which we don't use in this example,
2092 but which may be useful to other UNIX programs.
2095 .IX inetd "" "using \fIinetd\fP"
2097 An RPC server can be started from
2099 The only difference from the usual code is that the service
2100 creation routine should be called in the following form:
2104 transp = svcudp_create(0); /* \fIFor UDP\fP */
2105 transp = svctcp_create(0,0,0); /* \fIFor listener TCP sockets\fP */
2106 transp = svcfd_create(0,0,0); /* \fIFor connected TCP sockets\fP */
2110 passes a socket as file descriptor 0.
2117 svc_register(transp, PROGNUM, VERSNUM, service, 0);
2119 with the final flag as 0,
2120 since the program would already be registered by
2122 Remember that if you want to exit
2123 from the server process and return control to
2125 you need to explicitly exit, since
2129 The format of entries in
2131 for RPC services is in one of the following two forms:
2135 p_name/version dgram rpc/udp wait/nowait user server args
2136 p_name/version stream rpc/tcp wait/nowait user server args
2140 is the symbolic name of the program as it appears in
2143 is the program implementing the server,
2148 are the program and version numbers of the service.
2149 For more information, see
2152 If the same program handles multiple versions,
2153 then the version number can be a range,
2158 rstatd/1-2 dgram rpc/udp wait root /usr/etc/rpc.rstatd
2166 .IX "RPC" "versions"
2168 By convention, the first version number of program
2172 and the most recent version is
2174 Suppose there is a new version of the
2176 program that returns an
2180 If we name this version
2182 then a server that wants to support both versions
2183 would do a double register.
2187 if (!svc_register(transp, RUSERSPROG, RUSERSVERS_ORIG,
2188 nuser, IPPROTO_TCP)) {
2189 fprintf(stderr, "can't register RUSER service\en");
2192 if (!svc_register(transp, RUSERSPROG, RUSERSVERS_SHORT,
2193 nuser, IPPROTO_TCP)) {
2194 fprintf(stderr, "can't register RUSER service\en");
2198 Both versions can be handled by the same C procedure:
2203 nuser(rqstp, transp)
2204 struct svc_req *rqstp;
2207 unsigned long nusers;
2208 unsigned short nusers2;
2210 switch (rqstp->rq_proc) {
2212 if (!svc_sendreply(transp, xdr_void, 0)) {
2213 fprintf(stderr, "can't reply to RPC call\en");
2217 case RUSERSPROC_NUM:
2220 * Code here to compute the number of users
2221 * and assign it to the variable \fInusers\fP
2225 switch (rqstp->rq_vers) {
2226 case RUSERSVERS_ORIG:
2227 if (!svc_sendreply(transp, xdr_u_long,
2229 fprintf(stderr,"can't reply to RPC call\en");
2232 case RUSERSVERS_SHORT:
2233 if (!svc_sendreply(transp, xdr_u_short,
2235 fprintf(stderr,"can't reply to RPC call\en");
2240 svcerr_noproc(transp);
2251 Here is an example that is essentially
2253 The initiator of the RPC
2255 call takes its standard input and sends it to the server
2257 which prints it on standard output.
2258 The RPC call uses TCP.
2259 This also illustrates an XDR procedure that behaves differently
2260 on serialization than on deserialization.
2267 * on decode, read from wire, write onto fp
2268 * on encode, read from fp, write onto wire
2272 #include <rpc/rpc.h>
2279 char buf[BUFSIZ], *p;
2281 if (xdrs->x_op == XDR_FREE)/* nothing to free */
2284 if (xdrs->x_op == XDR_ENCODE) {
2285 if ((size = fread(buf, sizeof(char), BUFSIZ,
2286 fp)) == 0 && ferror(fp)) {
2287 fprintf(stderr, "can't fread\en");
2292 if (!xdr_bytes(xdrs, &p, &size, BUFSIZ))
2296 if (xdrs->x_op == XDR_DECODE) {
2297 if (fwrite(buf, sizeof(char), size,
2299 fprintf(stderr, "can't fwrite\en");
2313 * The sender routines
2318 #include <rpc/rpc.h>
2319 #include <sys/socket.h>
2320 #include <sys/time.h>
2330 fprintf(stderr, "usage: %s servername\en", argv[0]);
2333 if ((err = callrpctcp(argv[1], RCPPROG, RCPPROC,
2334 RCPVERS, xdr_rcp, stdin, xdr_void, 0) != 0)) {
2336 fprintf(stderr, "can't make RPC call\en");
2342 callrpctcp(host, prognum, procnum, versnum,
2343 inproc, in, outproc, out)
2344 char *host, *in, *out;
2345 xdrproc_t inproc, outproc;
2347 struct sockaddr_in server_addr;
2348 int socket = RPC_ANYSOCK;
2349 enum clnt_stat clnt_stat;
2351 register CLIENT *client;
2352 struct timeval total_timeout;
2354 if ((hp = gethostbyname(host)) == NULL) {
2355 fprintf(stderr, "can't get addr for '%s'\en", host);
2358 bcopy(hp->h_addr, (caddr_t)&server_addr.sin_addr,
2360 server_addr.sin_family = AF_INET;
2361 server_addr.sin_port = 0;
2362 if ((client = clnttcp_create(&server_addr, prognum,
2363 versnum, &socket, BUFSIZ, BUFSIZ)) == NULL) {
2364 perror("rpctcp_create");
2367 total_timeout.tv_sec = 20;
2368 total_timeout.tv_usec = 0;
2369 clnt_stat = clnt_call(client, procnum,
2370 inproc, in, outproc, out, total_timeout);
2371 clnt_destroy(client);
2372 return (int)clnt_stat;
2381 * The receiving routines
2385 #include <rpc/rpc.h>
2389 register SVCXPRT *transp;
2390 int rcp_service(), xdr_rcp();
2392 if ((transp = svctcp_create(RPC_ANYSOCK,
2393 BUFSIZ, BUFSIZ)) == NULL) {
2394 fprintf("svctcp_create: error\en");
2397 pmap_unset(RCPPROG, RCPVERS);
2398 if (!svc_register(transp,
2399 RCPPROG, RCPVERS, rcp_service, IPPROTO_TCP)) {
2400 fprintf(stderr, "svc_register: error\en");
2403 svc_run(); /* \fInever returns\fP */
2404 fprintf(stderr, "svc_run should never return\en");
2407 rcp_service(rqstp, transp)
2408 register struct svc_req *rqstp;
2409 register SVCXPRT *transp;
2411 switch (rqstp->rq_proc) {
2413 if (svc_sendreply(transp, xdr_void, 0) == 0) {
2414 fprintf(stderr, "err: rcp_service");
2419 if (!svc_getargs(transp, xdr_rcp, stdout)) {
2420 svcerr_decode(transp);
2423 if (!svc_sendreply(transp, xdr_void, 0)) {
2424 fprintf(stderr, "can't reply\en");
2429 svcerr_noproc(transp);
2436 \&Callback Procedures
2437 .IX RPC "callback procedures"
2439 Occasionally, it is useful to have a server become a client,
2440 and make an RPC call back to the process which is its client.
2441 An example is remote debugging,
2442 where the client is a window system program,
2443 and the server is a debugger running on the remote machine.
2445 the user clicks a mouse button at the debugging window,
2446 which converts this to a debugger command,
2447 and then makes an RPC call to the server
2448 (where the debugger is actually running),
2449 telling it to execute that command.
2450 However, when the debugger hits a breakpoint, the roles are reversed,
2451 and the debugger wants to make an rpc call to the window program,
2452 so that it can inform the user that a breakpoint has been reached.
2454 In order to do an RPC callback,
2455 you need a program number to make the RPC call on.
2456 Since this will be a dynamically generated program number,
2457 it should be in the transient range,
2458 .I "0x40000000 - 0x5fffffff" .
2461 returns a valid program number in the transient range,
2462 and registers it with the portmapper.
2463 It only talks to the portmapper running on the same machine as the
2465 routine itself. The call to
2467 is a test and set operation,
2468 in that it indivisibly tests whether a program number
2469 has already been registered,
2470 and if it has not, then reserves it. On return, the
2472 argument will contain a socket that can be used
2473 as the argument to an
2483 #include <rpc/rpc.h>
2484 #include <sys/socket.h>
2486 gettransient(proto, vers, sockp)
2487 int proto, vers, *sockp;
2489 static int prognum = 0x40000000;
2490 int s, len, socktype;
2491 struct sockaddr_in addr;
2495 socktype = SOCK_DGRAM;
2498 socktype = SOCK_STREAM;
2501 fprintf(stderr, "unknown protocol type\en");
2504 if (*sockp == RPC_ANYSOCK) {
2505 if ((s = socket(AF_INET, socktype, 0)) < 0) {
2513 addr.sin_addr.s_addr = 0;
2514 addr.sin_family = AF_INET;
2519 * may be already bound, so don't check for error
2522 bind(s, &addr, len);
2523 if (getsockname(s, &addr, &len)< 0) {
2524 perror("getsockname");
2527 while (!pmap_set(prognum++, vers, proto,
2528 ntohs(addr.sin_port))) continue;
2538 is necessary to ensure that the port number in
2539 .I "addr.sin_port" ,
2542 byte order, is passed in
2548 man page for more details on the conversion of network
2549 addresses from network to host byte order.
2552 The following pair of programs illustrate how to use the
2555 The client makes an RPC call to the server,
2556 passing it a transient program number.
2557 Then the client waits around to receive a callback
2558 from the server at that program number.
2559 The server registers the program
2561 so that it can receive the RPC call
2562 informing it of the callback program number.
2563 Then at some random time (on receiving an
2565 signal in this example), it sends a callback RPC call,
2566 using the program number it received earlier.
2576 #include <rpc/rpc.h>
2586 gethostname(hostname, sizeof(hostname));
2588 x = gettransient(IPPROTO_UDP, 1, &s);
2589 fprintf(stderr, "client gets prognum %d\en", x);
2590 if ((xprt = svcudp_create(s)) == NULL) {
2591 fprintf(stderr, "rpc_server: svcudp_create\en");
2595 /* protocol is 0 - gettransient does registering
2598 (void)svc_register(xprt, x, 1, callback, 0);
2599 ans = callrpc(hostname, EXAMPLEPROG, EXAMPLEVERS,
2600 EXAMPLEPROC_CALLBACK, xdr_int, &x, xdr_void, 0);
2601 if ((enum clnt_stat) ans != RPC_SUCCESS) {
2602 fprintf(stderr, "call: ");
2604 fprintf(stderr, "\en");
2607 fprintf(stderr, "Error: svc_run shouldn't return\en");
2610 callback(rqstp, transp)
2611 register struct svc_req *rqstp;
2612 register SVCXPRT *transp;
2614 switch (rqstp->rq_proc) {
2616 if (!svc_sendreply(transp, xdr_void, 0)) {
2617 fprintf(stderr, "err: exampleprog\en");
2622 if (!svc_getargs(transp, xdr_void, 0)) {
2623 svcerr_decode(transp);
2626 fprintf(stderr, "client got callback\en");
2627 if (!svc_sendreply(transp, xdr_void, 0)) {
2628 fprintf(stderr, "err: exampleprog");
2645 #include <rpc/rpc.h>
2646 #include <sys/signal.h>
2651 int pnum; /* \fIprogram number for callback routine\fP */
2655 gethostname(hostname, sizeof(hostname));
2656 registerrpc(EXAMPLEPROG, EXAMPLEVERS,
2657 EXAMPLEPROC_CALLBACK, getnewprog, xdr_int, xdr_void);
2658 fprintf(stderr, "server going into svc_run\en");
2659 signal(SIGALRM, docallback);
2662 fprintf(stderr, "Error: svc_run shouldn't return\en");
2669 pnum = *(int *)pnump;
2677 ans = callrpc(hostname, pnum, 1, 1, xdr_void, 0,
2680 fprintf(stderr, "server: ");
2682 fprintf(stderr, "\en");