.\".\" Must use -- tbl and pic -- with this one.\".\" @(#)rpc.prog.ms	2.3 88/08/11 4.0 RPCSRC.de BT.if \\n%=1 .tl ''- % -''...IX "Network Programming" "" "" "" PAGE MAJOR.nr OF 0.ND.\" prevent excess underlining in nroff.if n .fp 2 R.OH 'Remote Procedure Call Programming Guide''Page %'.EH 'Page %''Remote Procedure Call Programming Guide'.SH\&Remote Procedure Call Programming Guide.nr OF 1.IX "RPC Programming Guide".LPThis document assumes a working knowledge of network theory.  It isintended for programmers who wish to write network applications usingremote procedure calls (explained below), and who want to understandthe RPC mechanisms usually hidden by the.I rpcgen(1) protocol compiler..I rpcgen is described in detail in the previous chapter, the.I "\fBrpcgen\fP \fIProgramming Guide\fP"..SHNote:.I.IX rpcgen "" \fIrpcgen\fPBefore attempting to write a network application, or to convert anexisting non-network application to run over the network, you may want tounderstand the material in this chapter.  However, for most applications,you can circumvent the need to cope with the details presented here by using.I rpcgen .The.I "Generating XDR Routines"section of that chapter contains the complete source for a working RPCservice\(ema remote directory listing service which uses.I rpcgen to generate XDR routines as well as client and server stubs..LP.LPWhat are remote procedure calls?  Simply put, they are the high-levelcommunications paradigm used in the operating system.RPC presumes the existence oflow-level networking mechanisms (such as TCP/IP and UDP/IP), and upon themit implements a logical client to server communications system designedspecifically for the support of network applications.  With RPC, the clientmakes a procedure call to send a data packet to the server.  When thepacket arrives, the server calls a dispatch routine, performs whateverservice is requested, sends back the reply, and the procedure call returnsto the client..NH 0\&Layers of RPC.IX "layers of RPC".IX "RPC" "layers".LPThe RPC interface can be seen as being divided into three layers.\**.FSFor a complete specification of the routines in the remote procedurecall Library, see the.I rpc(3N) manual page..FE.LP.I "The Highest Layer:".IX RPC "The Highest Layer"The highest layer is totally transparent to the operating system, machine and network upon which is is run.  It's probably best to think of this level as a way of.I usingRPC, rather than asa \fIpart of\fP RPC proper.  Programmers who write RPC routines should (almost) always make this layer available to others by way of a simple C front end that entirely hides the networking..LP To illustrate, at this level a program can simply make a call to.I rnusers (),a C routine which returns the number of users on a remote machine.The user is not explicitly aware of using RPC \(em they simply call a procedure, just as they would call.I malloc() ..LP.I "The Middle Layer:".IX RPC "The Middle Layer"The middle layer is really \*QRPC proper.\*U  Here, the user doesn'tneed to consider details about sockets, the UNIX system, or other low-level implementation mechanisms.  They simply make remote procedure callsto routines on other machines.  The selling point here is simplicity.  It's this layer that allows RPC to pass the \*Qhello world\*U test \(emsimple things should be simple.  The middle-layer routines are used for most applications..LPRPC calls are made with the system routines.I registerrpc().I callrpc()and.I svc_run ().The first two of these are the most fundamental:.I registerrpc() obtains a unique system-wide procedure-identification number, and.I callrpc() actually executes a remote procedure call.  At the middle level, a call to .I rnusers()is implemented by way of these two routines..LPThe middle layer is unfortunately rarely used in serious programming due to its inflexibility (simplicity).  It does not allow timeout specifications or the choice of transport.  It allows no UNIXprocess control or flexibility in case of errors.  It doesn't supportmultiple kinds of call authentication.  The programmer rarely needs all these kinds of control, but one or two of them is often necessary..LP.I "The Lowest Layer:".IX RPC "The Lowest Layer"The lowest layer does allow these details to be controlled by the programmer, and for that reason it is often necessary.  Programs written at this level are also most efficient, but this is rarely areal issue \(em since RPC clients and servers rarely generate heavy network loads..LPAlthough this document only discusses the interface to C,remote procedure calls can be made from any language.Even though this document discusses RPCwhen it is used to communicatebetween processes on different machines,it works just as well for communicationbetween different processes on the same machine..br.KS.NH 2\&The RPC Paradigm.IX RPC paradigm.LPHere is a diagram of the RPC paradigm:.LP\fBFigure 1-1\fI Network Communication with the Remote Reocedure Call\fR.LP.PSL1: arrow down 1i "client " rjust "program " rjustL2: line right 1.5i "\fIcallrpc\fP" "function"move up 1.5i; line dotted down 6i; move up 4.5iarrow right 1iL3: arrow down 1i "invoke " rjust "service " rjustL4: arrow right 1.5i "call" "service"L5: arrow down 1i " service" ljust " executes" ljustL6: arrow left 1.5i "\fIreturn\fP" "answer"L7: arrow down 1i "request " rjust "completed " rjustL8: line left 1iarrow left 1.5i "\fIreturn\fP" "reply"L9: arrow down 1i "program " rjust "continues " rjustline dashed down from L2 to L9line dashed down from L4 to L7line dashed up 1i from L3 "service " rjust "daemon " rjustarrow dashed down 1i from L8move right 1i from L3box invis "Machine B"move left 1.2i from L2; move downbox invis "Machine A".PE.KE.KS.NH 1\&Higher Layers of RPC.NH 2\&Highest Layer.IX "highest layer of RPC".IX RPC "highest layer".LPImagine you're writing a program that needs to knowhow many users are logged into a remote machine.You can do this by calling the RPC library routine.I rnusers()as illustrated below:.ie t .DS.el .DS L.ft CW#include <stdio.h>main(argc, argv)	int argc;	char **argv;{	int num;	if (argc != 2) {		fprintf(stderr, "usage: rnusers hostname\en");		exit(1);	}	if ((num = rnusers(argv[1])) < 0) {		fprintf(stderr, "error: rnusers\en");		exit(-1);	}	printf("%d users on %s\en", num, argv[1]);	exit(0);}.DE.KERPC library routines such as.I rnusers() are in the RPC services library.I librpcsvc.aThus, the program above should be compiled with.DS.ft CW% cc \fIprogram.c -lrpcsvc\fP.DE.I rnusers (),like the other RPC library routines, is documented in section 3R of the.I "System Interface Manual for the Sun Workstation" ,the same section which documents the standard Sun RPC services.  .IX "RPC Services"See the .I intro(3R) manual page for an explanation of the documentation strategy for these services and their RPC protocols..LPHere are some of the RPC service library routines available to the C programmer:.LP\fBTable 3-3\fI RPC Service Library Routines\RP.TSbox tab (&) ;cfI cfIlfL l .Routine&Description_.sp.5rnusers&Return number of users on remote machinerusers&Return information about users on remote machinehavedisk&Determine if remote machine has diskrstats&Get performance data from remote kernelrwall&Write to specified remote machinesyppasswd&Update user password in Yellow Pages.TE.LPOther RPC services \(em for example.I ether().I mount.I rquota()and.I spray\(em are not available to the C programmer as library routines.They do, however,have RPC program numbers so they can be invoked with.I callrpc()which will be discussed in the next section.  Most of them also have compilable .I rpcgen(1) protocol description files.  (The.I rpcgenprotocol compiler radically simplifies the process of developingnetwork applications.  See the \fBrpcgen\fI Programming Guide\fRfor detailed information about .I rpcgen and .I rpcgen protocol description files)..KS.NH 2\&Intermediate Layer.IX "intermediate layer of RPC".IX "RPC" "intermediate layer".LPThe simplest interface, which explicitly makes RPC calls, uses the functions.I callrpc()and.I registerrpc()Using this method, the number of remote users can be gotten as follows:.ie t .DS.el .DS L#include <stdio.h>#include <rpc/rpc.h>#include <utmp.h>#include <rpcsvc/rusers.h>main(argc, argv)	int argc;	char **argv;{	unsigned long nusers;	int stat;	if (argc != 2) {		fprintf(stderr, "usage: nusers hostname\en");		exit(-1);	}	if (stat = callrpc(argv[1],	  RUSERSPROG, RUSERSVERS, RUSERSPROC_NUM,	  xdr_void, 0, xdr_u_long, &nusers) != 0) {		clnt_perrno(stat);		exit(1);	}	printf("%d users on %s\en", nusers, argv[1]);	exit(0);}.DE.KEEach RPC procedure is uniquely defined by a program number, version number, and procedure number.  The program number specifies a group of related remote procedures, each of which has a different procedure number.  Each program also has a version number, so when a minor change is made to a remote service (adding a new procedure, for example), a new program number doesn't have to be assigned.  When you want to call a procedure to find the number of remote users, you look up the appropriate program, version and procedure numbersin a manual, just as you look up the name of a memory allocator when you want to allocate memory..LPThe simplest way of making remote procedure calls is with the the RPC library routine.I callrpc()It has eight parameters.  The first is the name of the remote server machine.  The next three parameters are the program, version, and procedure numbers\(emtogether they identify the procedure to be called.The fifth and sixth parameters are an XDR filter and an argument tobe encoded and passed to the remote procedure.  The final two parameters are a filter for decoding the results returned by the remote procedure and a pointer to the place where the procedure's results are to be stored.  Multiple arguments andresults are handled by embedding them in structures.  If .I callrpc() completes successfully, it returns zero; else it returns a nonzero value.  The return codes (of type.IX "enum clnt_stat (in RPC programming)" "" "\fIenum clnt_stat\fP (in RPC programming)"cast into an integer) are found in .I <rpc/clnt.h> ..LPSince data types may be represented differently on different machines,.I callrpc() needs both the type of the RPC argument, as well asa pointer to the argument itself (and similarly for the result).  For.I RUSERSPROC_NUM ,the return value is an.I "unsigned long"so.I callrpc() has.I xdr_u_long() as its first return parameter, which saysthat the result is of type.I "unsigned long"and.I &nusers as its second return parameter,which is a pointer to where the long result will be placed.  Since.I RUSERSPROC_NUM takes no argument, the argument parameter of.I callrpc() is.I xdr_void ()..LPAfter trying several times to deliver a message, if.I callrpc() gets no answer, it returns with an error code.The delivery mechanism is UDP,which stands for User Datagram Protocol.Methods for adjusting the number of retriesor for using a different protocol require you to use the lowerlayer of the RPC library, discussed later in this document.The remote server procedurecorresponding to the above might look like this:.ie t .DS.el .DS L.ft CW.ft CWchar *nuser(indata)	char *indata;{	unsigned long nusers;.ft I	/*	 * Code here to compute the number of users	 * and place result in variable \fInusers\fP.	 */.ft CW	return((char *)&nusers);}.DE.LPIt takes one argument, which is a pointer to the inputof the remote procedure call (ignored in our example),and it returns a pointer to the result.In the current version of C,character pointers are the generic pointers,so both the input argument and the return value are cast to.I "char *" ..LPNormally, a server registers all of the RPC calls it plansto handle, and then goes into an infinite loop waiting to service requests.In this example, there is only a single procedureto register, so the main body of the server would look like this:.ie t .DS.el .DS L.ft CW#include <stdio.h>#include <rpc/rpc.h>#include <utmp.h>#include <rpcsvc/rusers.h>char *nuser();main(){	registerrpc(RUSERSPROG, RUSERSVERS, RUSERSPROC_NUM,		nuser, xdr_void, xdr_u_long);	svc_run();		/* \fINever returns\fP */	fprintf(stderr, "Error: svc_run returned!\en");	exit(1);}.DE.LPThe.I registerrpc()routine registers a C procedure as corresponding to agiven RPC procedure number.  The first three parameters,.I RUSERPROG ,.I RUSERSVERS ,and.I RUSERSPROC_NUM are the program, version, and procedure numbersof the remote procedure to be registered;.I nuser() is the name of the local procedure that implements the remoteprocedure; and.I xdr_void() and.I xdr_u_long() are the XDR filters for the remote procedure's arguments andresults, respectively.  (Multiple arguments or multiple resultsare passed as structures)..LPOnly the UDP transport mechanism can use.I registerrpc()thus, it is always safe in conjunction with calls generated by.I callrpc() ..SH.IX "UDP 8K warning"Warning: the UDP transport mechanism can only deal witharguments and results less than 8K bytes in length..LP.LPAfter registering the local procedure, the server program'smain procedure calls.I svc_run (),the RPC library's remote procedure dispatcher.  It is this function that calls the remote procedures in response to RPCcall messages.  Note that the dispatcher takes care of decodingremote procedure arguments and encoding results, using the XDRfilters specified when the remote procedure was registered..NH 2\&Assigning Program Numbers.IX "program number assignment".IX "assigning program numbers".LPProgram numbers are assigned in groups of .I 0x20000000 according to the following chart:.DS.ft CW       0x0 - 0x1fffffff	\fRDefined by Sun\fP0x20000000 - 0x3fffffff	\fRDefined by user\fP0x40000000 - 0x5fffffff	\fRTransient\fP0x60000000 - 0x7fffffff	\fRReserved\fP0x80000000 - 0x9fffffff	\fRReserved\fP0xa0000000 - 0xbfffffff	\fRReserved\fP0xc0000000 - 0xdfffffff	\fRReserved\fP0xe0000000 - 0xffffffff	\fRReserved\fP.ft R.DESun Microsystems administers the first group of numbers, whichshould be identical for all Sun customers.  If a customerdevelops an application that might be of general interest, thatapplication should be given an assigned number in the firstrange.  The second group of numbers is reserved for specificcustomer applications.  This range is intended primarily fordebugging new programs.  The third group is reserved forapplications that generate program numbers dynamically.  Thefinal groups are reserved for future use, and should not beused..LPTo register a protocol specification, send a request by network mail to.I rpc@sunor write to:.DSRPC AdministratorSun Microsystems2550 Garcia Ave.Mountain View, CA 94043.DEPlease include a compilable .I rpcgen \*Q.x\*U file describing your protocol.