Remote Procedure Calls (RPC)

This chapter provides an overview of Remote Procedure Calls (RPC) RPC.

What Is RPC
RPC is a powerful technique for constructing distributed, client-server based
applications. It is based on extending the notion of conventional, or local procedure
calling, so that the called procedure need not exist in the same address space as the
calling procedure. The two processes may be on the same system, or they may be on
different systems with a network connecting them. By using RPC, programmers of
distributed applications avoid the details of the interface with the network. The
transport independence of RPC isolates the application from the physical and logical
elements of the data communications mechanism and allows the application to use a
variety of transports.
RPC makes the client/server model of computing more powerful and easier to
program. When combined with the ONC RPCGEN protocol compiler (Chapter 33)
clients transparently make remote calls through a local procedure interface.
How RPC Works
An RPC is analogous to a function call. Like a function call, when an RPC is made, the
calling arguments are passed to the remote procedure and the caller waits for a
response to be returned from the remote procedure. Figure 32.1 shows the flow of
activity that takes place during an RPC call between two networked systems. The
client makes a procedure call that sends a request to the server and waits. The
thread is blocked from processing until either a reply is received, or it times out.
When the request arrives, the server calls a dispatch routine that performs the
requested service, and sends the reply to the client. After the RPC call is completed,
the client program continues. RPC specifically supports network applications.

Fig. 32.1 Remote Procedure Calling Mechanism A remote procedure is uniquely
identified by the triple: (program number, version number, procedure number) The
program number identifies a group of related remote procedures, each of which has
a unique procedure number. A program may consist of one or more versions. Each
version consists of a collection of procedures which are available to be called
remotely. Version numbers enable multiple versions of an RPC protocol to be
available simultaneously. Each version contains a a number of procedures that can
be called remotely. Each procedure has a procedure number.
RPC Application Development
Consider an example:
A client/server lookup in a personal database on a remote machine. Assuming that
we cannot access the database from the local machine (via NFS).
We use UNIX to run a remote shell and execute the command this way. There are
some problems with this method:
the command may be slow to execute.
You require an login account on the remote machine.
The RPC alternative is to
establish an server on the remote machine that can repond to queries.
Retrieve information by calling a query which will be quicker than previous approach.
To develop an RPC application the following steps are needed:
Specify the protocol for client server communication
Develop the client program
Develop the server program
The programs will be compiled seperately. The communication protocol is achieved
by generated stubs and these stubs and rpc (and other libraries) will need to be
linked in.
Defining the Protocol
The easiest way to define and generate the protocol is to use a protocol complier
such as rpcgen which we discuss is Chapter 33.
For the protocol you must identify the name of the service procedures, and data
types of parameters and return arguments.
The protocol compiler reads a definitio and automatically generates client and server
stubs.
rpcgen uses its own language (RPC language or RPCL) which looks very similar to
preprocessor directives.
rpcgen exists as a standalone executable compiler that reads special files denoted by
a .x prefix.
So to compile a RPCL file you simply do
rpcgen rpcprog.x
This will generate possibly four files:
rpcprog_clnt.c -- the client stub
rpcprog_svc.c -- the server stub
rpcprog_xdr.c -- If necessary XDR (external data representation) filters
rpcprog.h -- the header file needed for any XDR filters.
The external data representation (XDR) is an data abstraction needed for machine
independent communication. The client and server need not be machines of the
same type.
Defining Client and Server Application Code
We must now write the the client and application code. They must communicate via
procedures and data types specified in the Protocol.
The service side will have to register the procedures that may be called by the client
and receive and return any data required for processing.
The client application call the remote procedure pass any required data and will
receive the retruned data.
There are several levels of application interfaces that may be used to develop RPC
applications. We will briefly disuss these below before exapnading thhe most
common of these in later chapters.
Compliling and running the application
Let us consider the full compilation model required to run a RPC application.
Makefiles are useful for easing the burden of compiling RPC applications but it is
necessary to understand the complete model before one can assemble a convenient
makefile.
Assume the the client program is called rpcprog.c, the service program is rpcsvc.c and
that the protocol has been defined in rpcprog.x and that rpcgen has been used to
produce the stub and filter files: rpcprog_clnt.c, rpcprog_svc.c, rpcprog_xdr.c, rpcprog.h.
The client and server program must include (#include "rpcprog.h"
You must then:
compile the client code:
cc -c rpcprog.c
compile the client stub:
cc -c rpcprog_clnt.c
compile the XDR filter:
cc -c rpcprog_xdr.c
build the client executable:
cc -o rpcprog rpcprog.o rpcprog_clnt.o rpcprog_xdr.c
compile the service procedures:
cc -c rpcsvc.c
compile the server stub:
cc -c rpcprog_svc.c
build the server executable:
cc -o rpcsvc rpcsvc.o rpcprog_svc.o rpcprog_xdr.c
Now simply run the programs rpcprog and rpcsvc on the client and server respectively.
The server procedures must be registered before the client can call them.
Overview of Interface Routines
RPC has multiple levels of application interface to its services. These levels provide
different degrees of control balanced with different amounts of interface code to
implement. In order of increasing control and complexity. This section gives a
summary of the routines available at each level. Simplified Interface Routines
The simplified interfaces are used to make remote procedure calls to routines on
other machines, and specify only the type of transport to use. The routines at this
level are used for most applications. Descriptions and code samples can be found in
the section, Simplified Interface @ 3-2.
Simplified Level Routine Function
rpc_reg() -- Registers a procedure as an RPC program on all transports of the specified
type.
rpc_call() -- Remote calls the specified procedure on the specified remote host.
rpc_broadcast() -- Broadcasts a call message across all transports of the specified type.
Standard Interface Routines The standard interfaces are divided into top level,
intermediate level, expert level, and bottom level. These interfaces give a developer
much greater control over communication parameters such as the transport being
used, how long to wait beforeresponding to errors and retransmitting requests, and
so on.
Top Level Routines
At the top level, the interface is still simple, but the program has to create a client
handle before making a call or create a server handle before receiving calls. If you
want the application to run on all transports, use this interface. Use of these routines
and code samples can be found in Top Level Interface
clnt_create() -- Generic client creation. The program tells clnt_create() where the server is
located and the type of transport to use.
clnt_create_timed() Similar to clnt_create() but lets the programmer specify the maximum
time allowed for each type of transport tried during the creation attempt.
svc_create() -- Creates server handles for all transports of the specified type. The
program tells svc_create() which dispatch function to use.
clnt_call() -- Client calls a procedure to send a request to the server.
Intermediate Level Routines
The intermediate level interface of RPC lets you control details. Programs written at
these lower levels are more complicated but run more efficiently. The intermediate
level enables you to specify the transport to use.
clnt_tp_create() -- Creates a client handle for the specified transport.
clnt_tp_create_timed() -- Similar to clnt_tp_create() but lets the programmer specify the
maximum time allowed. svc_tp_create() Creates a server handle for the specified
transport.
clnt_call() -- Client calls a procedure to send a request to the server.
Expert Level Routines
The expert level contains a larger set of routines with which to specify transport-
related parameters. Use of these routines
clnt_tli_create() -- Creates a client handle for the specified transport.
svc_tli_create() -- Creates a server handle for the specified transport.
rpcb_set() -- Calls rpcbind to set a map between an RPC service and a network address.
rpcb_unset() -- Deletes a mapping set by rpcb_set().
rpcb_getaddr() -- Calls rpcbind to get the transport addresses of specified RPC services.
svc_reg() -- Associates the specified program and version number pair with the
specified dispatch routine.
svc_unreg() -- Deletes an association set by svc_reg().
clnt_call() -- Client calls a procedure to send a request to the server.
Bottom Level Routines
The bottom level contains routines used for full control of transport options.
clnt_dg_create() -- Creates an RPC client handle for the specified remote program, using
a connectionless transport.
svc_dg_create() -- Creates an RPC server handle, using a connectionless transport.
clnt_vc_create() -- Creates an RPC client handle for the specified remote program, using a
connection-oriented transport.
svc_vc_create() -- Creates an RPC server handle, using a connection-oriented transport.
clnt_call() -- Client calls a procedure to send a request to the server.
The Programmer's Interface to RPC
This section addresses the C interface to RPC and describes how to write network
applications using RPC. For a complete specification of the routines in the RPC
library, see the rpc and related man pages.
Simplified Interface
The simplified interface is the easiest level to use because it does not require the use
of any other RPC routines. It also limits control of the underlying communications
mechanisms. Program development at this level can be rapid, and is directly
supported by the rpcgen compiler. For most applications, rpcgen and its facilities are
sufficient. Some RPC services are not available as C functions, but they are available
as RPC programs. The simplified interface library routines provide direct access to
the RPC facilities for programs that do not require fine levels of control.
Routines such as rusers are in the RPC services library librpcsvc. rusers.c, below, is a
program that displays the number of users on a remote host. It calls the RPC library
routine, rusers.
The program.c program listing:
#include <rpc/rpc.h>
#include <rpcsvc/rusers.h>
#include <stdio.h>

/*
* a program that calls the
* rusers() service
*/

main(int argc,char **argv)

{
int num;
if (argc != 2) {
fprintf(stderr, "usage: %s hostname\n",
argv[0]);
exit(1);
}

if ((num = rnusers(argv[1])) < 0) {
fprintf(stderr, "error: rusers\n");
exit(1);
}

fprintf(stderr, "%d users on %s\n", num, argv[1] );
exit(0);
}
Compile the program with:
cc program.c -lrpcsvc -lnsl
The Client Side
There is just one function on the client side of the simplified interface rpc_call().
It has nine parameters:
int
rpc_call (char *host /* Name of server host */,
u_long prognum /* Server program number */,
u_long versnum /* Server version number */,
xdrproc_t inproc /* XDR filter to encode arg */,
char *in /* Pointer to argument */,
xdr_proc_t outproc /* Filter to decode result */,
char *out /* Address to store result */,
char *nettype /* For transport selection */);
This function calls the procedure specified by prognum, versum, and procnum on the host.
The argument to be passed to the remote procedure is pointed to by
the in parameter, and inproc is the XDR filter to encode this argument.
The out parameter is an address where the result from the remote procedure is to be
placed. outproc is an XDR filter which will decode the result and place it at this address.
The client blocks on rpc_call() until it receives a reply from the server. If the server
accepts, it returns RPC_SUCCESS with the value of zero. It will return a non-zero value if
the call was unsuccessful. This value can be cast to the type clnt_stat, an enumerated
type defined in the RPC include files (<rpc/rpc.h>) and interpreted by
the clnt_sperrno() function. This function returns a pointer to a standard RPC error
message corresponding to the error code. In the example, all "visible" transports
listed in /etc/netconfig are tried. Adjusting the number of retries requires use of the
lower levels of the RPC library. Multiple arguments and results are handled by
collecting them in structures.
The example changed to use the simplified interface, looks like
#include <stdio.h>
#include <utmp.h>
#include <rpc/rpc.h>
#include <rpcsvc/rusers.h>

/* a program that calls the RUSERSPROG
* RPC program
*/

main(int argc, char **argv)

{
unsigned long nusers;
enum clnt_stat cs;
if (argc != 2) {
fprintf(stderr, "usage: rusers hostname\n");
exit(1);
}

if( cs = rpc_call(argv[1], RUSERSPROG,
RUSERSVERS, RUSERSPROC_NUM, xdr_void,
(char *)0, xdr_u_long, (char *)&nusers,
"visible") != RPC_SUCCESS ) {
clnt_perrno(cs);
exit(1);
}

fprintf(stderr, "%d users on %s\n", nusers, argv[1] );
exit(0);
}
Since data types may be represented differently on different machines, rpc_call() needs
both the type of, and a pointer to, the RPC argument (similarly for the result).
For RUSERSPROC_NUM, the return value is an unsigned long, so the first return
parameter of rpc_call() is xdr_u_long (which is for an unsigned long) and the second
is &nusers (which points to unsigned long storage). Because RUSERSPROC_NUM has no
argument, the XDR encoding function of rpc_call() is xdr_void() and its argument is NULL.
The Server Side
The server program using the simplified interface is very straightforward. It simply
calls rpc_reg() to register the procedure to be called, and then it calls svc_run(), the RPC
library's remote procedure dispatcher, to wait for requests to come in.
rpc_reg() has the following prototype:
rpc_reg(u_long prognum /* Server program number */,
u_long versnum /* Server version number */,
u_long procnum /* server procedure number */,
char *procname /* Name of remote function */,
xdrproc_t inproc /* Filter to encode arg */,
xdrproc_t outproc /* Filter to decode result */,
char *nettype /* For transport selection */);
svc_run() invokes service procedures in response to RPC call messages. The dispatcher
in rpc_reg() takes care of decoding remote procedure arguments and encoding results,
using the XDR filters specified when the remote procedure was registered. Some
notes about the server program:
Most RPC applications follow the naming convention of appending a _1 to the
function name. The sequence _n is added to the procedure names to indicate the
version number n of the service.
The argument and result are passed as addresses. This is true for all functions that
are called remotely. If you pass NULL as a result of a function, then no reply is sent to
the client. It is assumed that there is no reply to send.
The result must exist in static data space because its value is accessed after the
actual procedure has exited. The RPC library function that builds the RPC reply
message accesses the result and sends the value back to the client.
Only a single argument is allowed. If there are multiple elements of data, they should
be wrapped inside a structure which can then be passed as a single entity.
The procedure is registered for each transport of the specified type. If the type
parameter is (char *)NULL, the procedure is registered for all transports specified
in NETPATH.
You can sometimes implement faster or more compact code than
can rpcgen. rpcgen handles the generic code-generation cases. The following program is
an example of a hand-coded registration routine. It registers a single procedure and
enters svc_run() to service requests.
#include <stdio.h>
#include <rpc/rpc.h>
#include <rpcsvc/rusers.h>

void *rusers();

main()
{
if(rpc_reg(RUSERSPROG, RUSERSVERS,
RUSERSPROC_NUM, rusers,
xdr_void, xdr_u_long,
"visible") == -1) {
fprintf(stderr, "Couldn't Register\n");
exit(1);
}
svc_run(); /* Never returns */
fprintf(stderr, "Error: svc_run returned!\n");
exit(1);
}
rpc_reg() can be called as many times as is needed to register different programs,
versions, and procedures.
Passing Arbitrary Data Types
Data types passed to and received from remote procedures can be any of a set of
predefined types, or can be programmer-defined types. RPC handles arbitrary data
structures, regardless of different machines' byte orders or structure layout
conventions, by always converting them to a standard transfer format called external
data representation (XDR) before sending them over the transport. The conversion
from a machine representation to XDR is called serializing, and the reverse process is
called deserializing. The translator arguments of rpc_call() and rpc_reg()can specify an
XDR primitive procedure, like xdr_u_long(), or a programmer-supplied routine that
processes a complete argument structure. Argument processing routines must take
only two arguments: a pointer to the result and a pointer to the XDR handle.
The following XDR Primitive Routines are available:
xdr_int() xdr_netobj() xdr_u_long() xdr_enum()
xdr_long() xdr_float() xdr_u_int() xdr_bool()
xdr_short() xdr_double() xdr_u_short() xdr_wrapstring()
xdr_char() xdr_quadruple() xdr_u_char() xdr_void()
The nonprimitive xdr_string(), which takes more than two parameters, is called
from xdr_wrapstring().
For an example of a programmer-supplied routine, the structure:
struct simple {
int a;
short b;
} simple;
contains the calling arguments of a procedure. The XDR routine xdr_simple() translates
the argument structure as shown below:
#include <rpc/rpc.h>
#include "simple.h"

bool_t xdr_simple(XDR *xdrsp, struct simple *simplep)

{
if (!xdr_int(xdrsp, &simplep->a))
return (FALSE);
if (!xdr_short(xdrsp, &simplep->b))
return (FALSE);
return (TRUE);
}
An equivalent routine can be generated automatically by rpcgen (See Chapter 33).
An XDR routine returns nonzero (a C TRUE) if it completes successfully, and zero
otherwise.
For more complex data structures use the XDR prefabricated routines:
xdr_array() xdr_bytes() xdr_reference()
xdr_vector() xdr_union() xdr_pointer()
xdr_string() xdr_opaque()
For example, to send a variable-sized array of integers, it is packaged in a structure
containing the array and its length:
struct varintarr {
int *data;
int arrlnth;
} arr;
Translate the array with xdr_array(), as shown below:
bool_t xdr_varintarr(XDR *xdrsp, struct varintarr *arrp)

{
return(xdr_array(xdrsp, (caddr_t)&arrp->data,
(u_int *)&arrp->arrlnth, MAXLEN, sizeof(int), xdr_int));
}
The arguments of xdr_array() are the XDR handle, a pointer to the array, a pointer to
the size of the array, the maximum array size, the size of each array element, and a
pointer to the XDR routine to translate each array element. If the size of the array is
known in advance, use xdr_vector() instread as is more efficient:
int intarr[SIZE];

bool_t xdr_intarr(XDR *xdrsp, int intarr[])
{
return (xdr_vector(xdrsp, intarr, SIZE, sizeof(int), xdr_int));
}
XDR converts quantities to 4-byte multiples when serializing. For arrays of
characters, each character occupies 32 bits. xdr_bytes() packs characters. It has four
parameters similar to the first four parameters of xdr_array().
Null-terminated strings are translated by xdr_string(). It is like xdr_bytes() with no length
parameter. On serializing it gets the string length from strlen(), and on deserializing it
creates a null-terminated string.
xdr_reference() calls the built-in functions xdr_string() and xdr_reference(), which translates
pointers to pass a string, and struct simple from the previous examples. An example
use ofxdr_reference() is as follows:
struct finalexample {
char *string;
struct simple *simplep;
} finalexample;

bool_t xdr_finalexample(XDR *xdrsp, struct finalexample *finalp)

{ if (!xdr_string(xdrsp, &finalp->string, MAXSTRLEN))
return (FALSE);
if (!xdr_reference( xdrsp, &finalp->simplep, sizeof(struct simple), xdr_simple))
return (FALSE);
return (TRUE);
}
Note thatxdr_simple() could have been called here instead of xdr_reference() .
Developing High Level RPC Applications
Let us now introduce some further functions and see how we develop an application
using high level RPC routines. We will do this by studying an example.
We will develop a remote directory reading utility.
Let us first consider how we would write a local directory reader. We have seem how
to do this already in Chapter 19.
Consider the program to consist of two files:
lls.c -- the main program which calls a routine in a local module read_dir.c
/*
* ls.c: local directory listing main - before RPC
*/
#include <stdio.h>
#include <strings.h>
#include "rls.h"

main (int argc, char **argv)

{
char dir[DIR_SIZE];

/* call the local procedure */
strcpy(dir, argv[1]); /* char dir[DIR_SIZE] is coming and going... */
read_dir(dir);

/* spew-out the results and bail out of here! */
printf("%s\n", dir);

exit(0);
}
read_dir.c -- the file containing the local routine read_dir().
/* note - RPC compliant procedure calls take one input and
return one output. Everything is passed by pointer. Return
values should point to static data, as it might have to
survive some while. */
#include <stdio.h>
#include <sys/types.h>
#include <sys/dir.h> /* use <xpg2include/sys/dirent.h> (SunOS4.1) or
<sys/dirent.h> for X/Open Portability Guide, issue 2 conformance */
#include "rls.h"

read_dir(char *dir)
/* char dir[DIR_SIZE] */
{
DIR * dirp;
struct direct *d;
printf("beginning ");

/* open directory */
dirp = opendir(dir);
if (dirp == NULL)
return(NULL);

/* stuff filenames into dir buffer */
dir[0] = NULL;
while (d = readdir(dirp))
sprintf(dir, "%s%s\n", dir, d->d_name);

/* return the result */
printf("returning ");
closedir(dirp);
return((int)dir); /* this is the only new line from Example 4-3 */
}
the header file rls.h contains only the following (for now at least)
#define DIR_SIZE 8192
Clearly we need to share the size between the files. Later when we develop RPC
versions more information will need to be added to this file.
This local program would be compiled as follows:
cc lls.c read_dir.c -o lls
Now we want to modify this program to work over a network: Allowing us to inspect
directories of a remote server accross a network.
The following steps will be required:
We will have to convert the read_dir.c, to run on the server.
We will have to register the server and the routine read_dir() on the server/.
The client lls.c will have to call the routine as a remote procedure.
We will have to define the protocol for communication between the client and the
server programs.
Defining the protocol
We can can use simple NULL-terminated strings for passing and receivong the
directory name and directory contents. Furthermore, we can embed the passing of
these parameters directly in the client and server code.
We therefore need to specify the program, procedure and version numbers for client
and servers. This can be done automatically using rpcgen or relying on prdefined
macros in the simlified interface. Here we will specify them manually.
The server and client must agree ahead of time what logical adresses thney will use
(The physical addresses do not matter they are hidden from the application
developer)
Program numbers are defined in a standard way:
0x00000000 - 0x1FFFFFFF: Defined by Sun
0x20000000 - 0x3FFFFFFF: User Defined
0x40000000 - 0x5FFFFFFF: Transient
0x60000000 - 0xFFFFFFFF: Reserved
We will simply choose a user deifnined value for our program number. The version
and procedure numbers are set according to standard practice.
We still have the DIR_SIZE definition required from the local version as the size of the
directory buffer is rewquired by bith client and server programs.
Our new rls.h file contains:
#define DIR_SIZE 8192
#define DIRPROG ((u_long) 0x20000001) /* server program (suite) number */
#define DIRVERS ((u_long) 1) /* program version number */
#define READDIR ((u_long) 1) /* procedure number for look-up */
Sharing the data
We have mentioned previously that we can pass the data a simple strings. We need
to define an XDR filter routine xdr_dir() that shares the data. Recall that only one
encoding and decoding argument can be handled. This is easy and defined via the
standard xdr_string() routine.
The XDR file, rls_xrd.c, is as follows:
#include <rpc/rpc.h>

#include "rls.h"

bool_t xdr_dir(XDR *xdrs, char *objp)

{ return ( xdr_string(xdrs, &objp, DIR_SIZE) ); }
The Server Side
We can use the original read_dir.c file. All we need to do is register the procedure and
start the server.
The procedure is registered with registerrpc() function. This is prototypes by:
registerrpc(u_long prognum /* Server program number */,
u_long versnum /* Server version number */,
u_long procnum /* server procedure number */,
char *procname /* Name of remote function */,
xdrproc_t inproc /* Filter to encode arg */,
xdrproc_t outproc /* Filter to decode result */);
The parameters a similarly defined as in the rpc_reg simplified interface function. We
have already discussed the setting of the parametere with the protocol rls.h header
files and therls_xrd.c XDR filter file.
The svc_run() routine has also been discussed previously.
The full rls_svc.c code is as follows:
#include <rpc/rpc.h>
#include "rls.h"

main()
{
extern bool_t xdr_dir();
extern char * read_dir();

registerrpc(DIRPROG, DIRVERS, READDIR,
read_dir, xdr_dir, xdr_dir);

svc_run();
}
The Client Side
At the client side we simply need to call the remote procedure. The
function callrpc() does this. It is prototyped as follows:
callrpc(char *host /* Name of server host */,
u_long prognum /* Server program number */,
u_long versnum /* Server version number */,
char *in /* Pointer to argument */,
xdrproc_t inproc /* XDR filter to encode arg */,
char *out /* Address to store result */
xdr_proc_t outproc /* Filter to decode result */);
We call a local function read_dir() which uses callrpc() to call the remote procedure that
has been registered READDIR at the server.
The full rls.c program is as follows:
/*
* rls.c: remote directory listing client
*/
#include <stdio.h>
#include <strings.h>
#include <rpc/rpc.h>
#include "rls.h"

main (argc, argv)
int argc; char *argv[];
{
char dir[DIR_SIZE];

/* call the remote procedure if registered */
strcpy(dir, argv[2]);
read_dir(argv[1], dir); /* read_dir(host, directory) */

/* spew-out the results and bail out of here! */
printf("%s\n", dir);

exit(0);
}

read_dir(host, dir)
char *dir, *host;
{
extern bool_t xdr_dir();
enum clnt_stat clnt_stat;

clnt_stat = callrpc ( host, DIRPROG, DIRVERS, READDIR,
xdr_dir, dir, xdr_dir, dir);
if (clnt_stat != 0) clnt_perrno (clnt_stat);
}
Exercise
Exercise 12833
Compile and run the remote directory example rls.c etc. Run both the client ande
srever locally and if possible over a network.