Developing distributed applications using ONC RPC and XDR

Using the lower layers

In the examples given so far, RPC takes care of many details automatically. This section shows how to change the defaults by using lower layers of the RPC library. It is assumed that the reader is familiar with sockets and the system calls for dealing with them.

In general, you should avoid using the lower layers of RPC. If you want to perform any of the following tasks, however, you must use the lower layers:

Sample server program

A number of assumptions are built into registerrpc:

The server for the nusers program shown on the next page is written using a lower layer of the RPC package, which does not make these assumptions.
   #include <stdio.h>
   #include <rpc/rpc.h>
   #include <rpcsvc/rusers.h>

int nuser();

main() { SVCXPRT *transp; transp = svcudp_create(RPC_ANYSOCK); if (transp == NULL){ fprintf(stderr, "could not create an RPC server\n"); exit(1); } pmap_unset(RUSERSPROG, RUSERSVERS); if (!svc_register(transp, RUSERSPROG, RUSERSVERS, nuser, IPPROTO_UDP)) { fprintf(stderr, "could not register RUSER service\n"); exit(1); } svc_run(); /* never returns */ fprintf(stderr, "should never reach this point\n"); } nuser(rqstp, transp) struct svc_req *rqstp; SVCXPRT *transp; { unsigned long nusers; switch (rqstp->rq_proc) { case NULLPROC: if (!svc_sendreply(transp, xdr_void, 0)) { fprintf(stderr, "could not reply to RPC call\n"); exit(1); } return; case RUSERSPROC_NUM: /* * code here to compute the number of users * and put in variable nusers */ if (!svc_sendreply(transp, xdr_u_long, &nusers) { fprintf(stderr, "could not reply to RPC call\n"); exit(1); } return; default: svcerr_noproc(transp); return; } }

First, the server gets a transport handle, which is used for sending out RPC messages. The procedure registerrpc() uses svcudp_create to get a UDP handle. If you require a reliable protocol, call svctcp_create instead. If the argument to svcudp_create is RPC_ANYSOCK, the RPC library creates a socket on which to send out RPC calls. Otherwise, svcudp_create expects its argument to be a valid socket number. If you specify your own socket, it can be bound or unbound. If it is bound to a port by the user, the port numbers of svcudp_create and clntudp_create (the low-level client routine) must match.

When the user specifies RPC_ANYSOCK for a socket or gives an unbound socket, the system determines port numbers in the following way: when a server starts up, it advertises to a port mapper demon on its local machine, which picks a port number for the RPC procedure if the socket specified to svcudp_create is not already bound. When the clntudp_create call is made with an unbound socket, the system queries the port mapper on the machine to which the call is being made and gets the appropriate port number. If the port mapper is not running or has no port corresponding to the RPC call, the RPC call fails. Users can make RPC calls to the port mapper themselves. The appropriate procedure numbers are in the include file <rpc/pmap_prot.h>.

After creating an SVCXPRT, the next step is to call pmap_unset so that if the nusers server crashed earlier, any previous trace of it is erased before restarting. More precisely, pmap_unset erases the entry for RUSERS from the port mapper's tables.

Finally, the program number for nusers is associated with the procedure nuser. The final argument to svc_register is normally the protocol being used, which in this case is IPPROTO_UDP. Unlike registerrpc, there are no XDR routines involved in the registration process. Also, registration is done on the program level, rather than the procedure level.

The user routine nuser must call and dispatch the appropriate XDR routines, based on the procedure number. Two things are handled by nuser that are handled automatically by registerrpc:

The user service routine serializes the results and returns them to the RPC caller via svc_sendreply. Its first parameter is the SVCXPRT handle, the second is the XDR routine, and the third is a pointer to the data to be returned. Not illustrated above is how a server handles an RPC program that passes data. As an example, you can add the following procedure named RUSERSPROC_BOOL, which has an argument nusers, and returns TRUE or FALSE depending on whether there are nusers logged on:
           int bool;
           unsigned nuserquery;

if (!svc_getargs(transp, xdr_u_int, &nuserquery)) { svcerr_decode(transp); return; } /* * code to set nusers = number of users */ if (nuserquery == nusers) bool = TRUE; else bool = FALSE; if (!svc_sendreply(transp, xdr_bool, &bool)){ fprintf(stderr, "could not reply to RPC call\n"); exit(1); } return; }

The relevant routine is svc_getargs, which takes as arguments an SVCXPRT handle, the XDR routine, and a pointer to where the input is to be placed.

Using XDR to allocate memory

XDR routines do memory allocation in addition to doing input and output. This is why the second parameter of xdr_array is a pointer to an array, rather than the array itself. If it is NULL, then xdr_array allocates space for the array and returns a pointer to it, putting the size of the array in the third argument. As an example, consider the following XDR routine xdr_chararr1, which deals with a fixed array of bytes with length SIZE:

   xdr_chararr1(xdrsp, chararr)
           XDR *xdrsp;
           char chararr[];
           char *p;
           int len;

p = chararr; len = SIZE; return (xdr_bytes(xdrsp, &p, &len, SIZE)); }

You can call it from a server like this:
   char chararr[SIZE];

svc_getargs(transp, xdr_chararr1, chararr);

where chararr has already allocated space.

If you want XDR to do the allocation, you would have to rewrite this routine in the following way:

   xdr_chararr2(xdrsp, chararrp)
           XDR *xdrsp;
           char **chararrp;
           int len;

len = SIZE; return (xdr_bytes(xdrsp, chararrp, &len, SIZE)); }

The RPC call might then look like this:
   char *arrptr;

arrptr = NULL; svc_getargs(transp, xdr_chararr2, &arrptr); /* * use the result here */ svc_freeargs(xdrsp, xdr_chararr2, &arrptr);

After using the character array, it can be freed with svc_freeargs. In the routine xdr_finalexample given earlier, if finalp->string was NULL in the call
   svc_getargs(transp, xdr_finalexample, &finalp);
   svc_freeargs(xdrsp, xdr_finalexample, &finalp);
frees the array allocated to hold finalp->string; otherwise, it frees nothing. The same is true for finalp->simplep.

To summarize, each XDR routine is responsible for serializing, deserializing, and allocating memory. When an XDR routine is called from callrpc, the serializing part is used. When called from svc_getargs, the deserializer is used. When called from svc_freeargs, the memory deallocator is used. When building simple examples like those in this section, a user does not have to worry about the three modes.

Sample client program

When you use callrpc, you have no control over the RPC delivery mechanism or the socket used to transport the data. To illustrate the layer of RPC that allows adjustment of these parameters, consider the following code to call the nusers service:

   #include <stdio.h>
   #include <rpc/rpc.h>
   #include <rpcsvc/rusers.h>
   #include <sys/socket.h>
   #include <sys/fs/nfs/time.h>
   #include <netdb.h>

main(argc, argv) int argc; char **argv; { struct hostent *hp; struct timeval pertry_timeout, total_timeout; struct sockaddr_in server_addr; int addrlen, sock = RPC_ANYSOCK; register CLIENT *client; enum clnt_stat clnt_stat; unsigned long nusers;

if (argc < 2) { fprintf(stderr, "usage: nusers hostname\n"); exit(-1); } if ((hp = gethostbyname(argv[1])) == NULL) { fprintf(stderr, "cannot get addr for '%s'\n", argv[1]); exit(-1); }

           pertry_timeout.tv_sec = 3;
           pertry_timeout.tv_usec = 0;
           addrlen = sizeof(struct sockaddr_in);
           bcopy(hp->h_addr, (caddr_t)&server_addr.sin_addr, hp->h_length);
           server_addr.sin_family = AF_INET;
           server_addr.sin_port =  0;
           if ((client = clntudp_create(&server_addr, RUSERSPROG,
               RUSERSVERS, pertry_timeout, &sock)) == NULL) {
           total_timeout.tv_sec = 20;
           total_timeout.tv_usec = 0;
           clnt_stat = clnt_call(client, RUSERSPROC_NUM, xdr_void, 0,
               xdr_u_long, &nusers, total_timeout);
           if (clnt_stat != RPC_SUCCESS) {
                   clnt_perror(client, "rpc");
The low-level version of callrpc is clnt_call, which takes a CLIENT pointer rather than a host name. The parameters to clnt_call are as follows: The CLIENT pointer is encoded with the transport mechanism. The procedure callrpc uses UDP; thus it calls clntudp_create to get a CLIENT pointer. To get TCP (Transmission Control Protocol), use clnttcp_create.

The parameters to clntudp_create are as follows:

The final argument to clnt_call is the total time to wait for a response. Thus, the number of tries is the clnt_call timeout divided by the clntudp_create timeout.

Note that the clnt_destroy call deallocates any space associated with the CLIENT handle, but it does not close the socket associated with it, which was passed as an argument to clntudp_create. The reason is that if there are multiple client handles using the same socket, then it is possible to close one handle without destroying the socket that other handles are using.

To make a stream connection, the call to clntudp_create is replaced with a call to clnttcp_create.

   clnttcp_create(&server_addr, prognum, versnum, &socket,
   	inputsize, outputsize);
There is no timeout argument; instead, the receive and send buffer sizes must be specified. When the clnttcp_create call is made, a TCP connection is established. All RPC calls using that CLIENT handle would use this connection. The server side of an RPC call using TCP has svcudp_create replaced by svctcp_create.
Next topic: Using RPC/XDR for other tasks
Previous topic: Using XDR to pass arbitrary data types

© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003