Remote Procedure Call Programming Guide

This document assumes a working knowledge of network theory. It is intended for programmers who wish to write network applications using remote procedure calls (explained below), and who want to understand the RPC mechanisms usually hidden by the rpcgen(1) protocol compiler. rpcgen is described in detail in the previous chapter, the rpcgen Programming Guide .

Note:
Before attempting to write a network application, or to convert an existing non-network application to run over the network, you may want to understand the material in this chapter. However, for most applications, you can circumvent the need to cope with the details presented here by using rpcgen . The Generating XDR Routines section of that chapter contains the complete source for a working RPC service—a remote directory listing service which uses rpcgen to generate XDR routines as well as client and server stubs.

What are remote procedure calls? Simply put, they are the high-level communications paradigm used in the operating system. RPC presumes the existence of low-level networking mechanisms (such as TCP/IP and UDP/IP), and upon them it implements a logical client to server communications system designed specifically for the support of network applications. With RPC, the client makes a procedure call to send a data packet to the server. When the packet arrives, the server calls a dispatch routine, performs whatever service is requested, sends back the reply, and the procedure call returns to the client. Layers of RPC

The RPC interface can be seen as being divided into three layers. For a complete specification of the routines in the remote procedure call Library, see the rpc(3N) manual page.

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 using RPC, rather than as a part of 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.

To illustrate, at this level a program can simply make a call to rnusers (), a C routine which returns the number of users on a remote machine. The user is not explicitly aware of using RPC — they simply call a procedure, just as they would call malloc() .

The Middle Layer: The middle layer is really RPC proper. Here, the user doesn't need to consider details about sockets, the UNIX system, or other low-level implementation mechanisms. They simply make remote procedure calls to routines on other machines. The selling point here is simplicity. It's this layer that allows RPC to pass the hello world test — simple things should be simple. The middle-layer routines are used for most applications.

RPC calls are made with the system routines registerrpc() callrpc() and svc_run (). The first two of these are the most fundamental: registerrpc() obtains a unique system-wide procedure-identification number, and callrpc() actually executes a remote procedure call. At the middle level, a call to rnusers() is implemented by way of these two routines.

The 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 UNIX process control or flexibility in case of errors. It doesn't support multiple kinds of call authentication. The programmer rarely needs all these kinds of control, but one or two of them is often necessary.

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 a real issue — since RPC clients and servers rarely generate heavy network loads.

Although this document only discusses the interface to C, remote procedure calls can be made from any language. Even though this document discusses RPC when it is used to communicate between processes on different machines, it works just as well for communication between different processes on the same machine.
The RPC Paradigm

Here is a diagram of the RPC paradigm:

Figure 1-1 Network Communication with the Remote Reocedure Call

Higher Layers of RPC Highest Layer

Imagine you're writing a program that needs to know how many users are logged into a remote machine. You can do this by calling the RPC library routine rnusers() as illustrated below: #include <stdio.h> main(argc, argv)
    int argc;
    char **argv; {
    int num;
    if (argc != 2) {
        fprintf(stderr, "usage: rnusers hostname\n");
        exit(1);
    }
    if ((num = rnusers(argv[1])) < 0) {
        fprintf(stderr, "error: rnusers\n");
        exit(-1);
    }
    printf("%d users on %s\n", num, argv[1]);
    exit(0); } RPC library routines such as rnusers() are in the RPC services library librpcsvc.a Thus, the program above should be compiled with % cc program.c -lrpcsvc rnusers (), like the other RPC library routines, is documented in section 3R of the System Interface Manual for the Sun Workstation , the same section which documents the standard Sun RPC services. See the intro(3R) manual page for an explanation of the documentation strategy for these services and their RPC protocols.

Here are some of the RPC service library routines available to the C programmer:

Table 3-3 RPC Service Library Routines
Routine | Description
rnusers | Return number of users on remote machine
rusers | Return information about users on remote machine
havedisk | Determine if remote machine has disk
rstats | Get performance data from remote kernel
rwall | Write to specified remote machines
yppasswd | Update user password in Yellow Pages

Other RPC services — for example ether() mount rquota() and spray — are not available to the C programmer as library routines. They do, however, have RPC program numbers so they can be invoked with callrpc() which will be discussed in the next section. Most of them also have compilable rpcgen(1) protocol description files. (The rpcgen protocol compiler radically simplifies the process of developing network applications. See the rpcgen Programming Guide for detailed information about rpcgen and rpcgen protocol description files). Intermediate Layer

The simplest interface, which explicitly makes RPC calls, uses the functions callrpc() and registerrpc() Using this method, the number of remote users can be gotten as follows: #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\n");
        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\n", nusers, argv[1]);
    exit(0); } Each 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 numbers in a manual, just as you look up the name of a memory allocator when you want to allocate memory.

The simplest way of making remote procedure calls is with the the RPC library routine 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—together they identify the procedure to be called. The fifth and sixth parameters are an XDR filter and an argument to be 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 and results are handled by embedding them in structures. If callrpc() completes successfully, it returns zero; else it returns a nonzero value. The return codes (of type cast into an integer) are found in <rpc/clnt.h> .

Since data types may be represented differently on different machines, callrpc() needs both the type of the RPC argument, as well as a pointer to the argument itself (and similarly for the result). For RUSERSPROC_NUM , the return value is an unsigned long so callrpc() has xdr_u_long() as its first return parameter, which says that the result is of type unsigned long and &nusers as its second return parameter, which is a pointer to where the long result will be placed. Since RUSERSPROC_NUM takes no argument, the argument parameter of callrpc() is xdr_void ().

After trying several times to deliver a message, if 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 retries or for using a different protocol require you to use the lower layer of the RPC library, discussed later in this document. The remote server procedure corresponding to the above might look like this: char * nuser(indata)
    char *indata; {
    unsigned long nusers;
    /*
     * Code here to compute the number of users
     * and place result in variable nusers.
     */
    return((char *)&nusers); }

It takes one argument, which is a pointer to the input of 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 char * .

Normally, a server registers all of the RPC calls it plans to handle, and then goes into an infinite loop waiting to service requests. In this example, there is only a single procedure to register, so the main body of the server would look like this: #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();    /* Never returns */
    fprintf(stderr, "Error: svc_run returned!\n");
    exit(1); }

The registerrpc() routine registers a C procedure as corresponding to a given RPC procedure number. The first three parameters, RUSERPROG , RUSERSVERS , and RUSERSPROC_NUM are the program, version, and procedure numbers of the remote procedure to be registered; nuser() is the name of the local procedure that implements the remote procedure; and xdr_void() and xdr_u_long() are the XDR filters for the remote procedure's arguments and results, respectively. (Multiple arguments or multiple results are passed as structures).

Only the UDP transport mechanism can use registerrpc() thus, it is always safe in conjunction with calls generated by callrpc() .

Warning: the UDP transport mechanism can only deal with
arguments and results less than 8K bytes in length.

After registering the local procedure, the server program's main procedure calls svc_run (), the RPC library's remote procedure dispatcher. It is this function that calls the remote procedures in response to RPC call messages. Note that the dispatcher takes care of decoding remote procedure arguments and encoding results, using the XDR filters specified when the remote procedure was registered. Assigning Program Numbers

Program numbers are assigned in groups of 0x20000000 according to the following chart:
       0x0 - 0x1fffffff    Defined by Sun
0x20000000 - 0x3fffffff    Defined by user
0x40000000 - 0x5fffffff    Transient
0x60000000 - 0x7fffffff    Reserved
0x80000000 - 0x9fffffff    Reserved
0xa0000000 - 0xbfffffff    Reserved
0xc0000000 - 0xdfffffff    Reserved
0xe0000000 - 0xffffffff    Reserved
Sun Microsystems administers the first group of numbers, which should be identical for all Sun customers. If a customer develops an application that might be of general interest, that application should be given an assigned number in the first range. The second group of numbers is reserved for specific customer applications. This range is intended primarily for debugging new programs. The third group is reserved for applications that generate program numbers dynamically. The final groups are reserved for future use, and should not be used.

To register a protocol specification, send a request by network mail to rpc@sun or write to: RPC Administrator Sun Microsystems 2550 Garcia Ave. Mountain View, CA 94043 Please include a compilable rpcgen .x file describing your protocol. You will be given a unique program number in return.

The RPC program numbers and protocol specifications of standard Sun RPC services can be found in the include files in /usr/include/rpcsvc . These services, however, constitute only a small subset of those which have been registered. The complete list of registered programs, as of the time when this manual was printed, is:

Table 3-2 RPC Registered Programs
RPC Number | Program | Description
100000 | PMAPPROG | portmapper
100001 | RSTATPROG | remote stats
100002 | RUSERSPROG | remote users
100003 | NFSPROG | nfs
100004 | YPPROG | Yellow Pages
100005 | MOUNTPROG | mount demon
100006 | DBXPROG | remote dbx
100007 | YPBINDPROG | yp binder
100008 | WALLPROG | shutdown msg
100009 | YPPASSWDPROG | yppasswd server
100010 | ETHERSTATPROG | ether stats
100011 | RQUOTAPROG | disk quotas
100012 | SPRAYPROG | spray packets
100013 | IBM3270PROG | 3270 mapper
100014 | IBMRJEPROG | RJE mapper
100015 | SELNSVCPROG | selection service
100016 | RDATABASEPROG | remote database access
100017 | REXECPROG | remote execution
100018 | ALICEPROG | Alice Office Automation
100019 | SCHEDPROG | scheduling service
100020 | LOCKPROG | local lock manager
100021 | NETLOCKPROG | network lock manager
100022 | X25PROG | x.25 inr protocol
100023 | STATMON1PROG | status monitor 1
100024 | STATMON2PROG | status monitor 2
100025 | SELNLIBPROG | selection library
100026 | BOOTPARAMPROG | boot parameters service
100027 | MAZEPROG | mazewars game
100028 | YPUPDATEPROG | yp update
100029 | KEYSERVEPROG | key server
100030 | SECURECMDPROG | secure login
100031 | NETFWDIPROG | nfs net forwarder init
100032 | NETFWDTPROG | nfs net forwarder trans
100033 | SUNLINKMAP_PROG | sunlink MAP
100034 | NETMONPROG | network monitor
100035 | DBASEPROG | lightweight database
100036 | PWDAUTHPROG | password authorization
100037 | TFSPROG | translucent file svc
100038 | NSEPROG | nse server
100039 | NSE_ACTIVATE_PROG | nse activate daemon
150001 | PCNFSDPROG | pc passwd authorization
200000 | PYRAMIDLOCKINGPROG | Pyramid-locking
200001 | PYRAMIDSYS5 | Pyramid-sys5
200002 | CADDS_IMAGE | CV cadds_image
300001 | ADT_RFLOCKPROG | ADT file locking
Passing Arbitrary Data Types

In the previous example, the RPC call passes a single unsigned long RPC can handle arbitrary data structures, regardless of different machines' byte orders or structure layout conventions, by always converting them to a network standard called External Data Representation (XDR) before sending them over the wire. The process of converting from a particular machine representation to XDR format is called serializing , and the reverse process is called deserializing . The type field parameters of callrpc() and registerrpc() can be a built-in procedure like xdr_u_long() in the previous example, or a user supplied one. XDR has these built-in type routines: xdr_int() xdr_u_int() xdr_enum() xdr_long() xdr_u_long() xdr_bool() xdr_short() xdr_u_short() xdr_wrapstring() xdr_char() xdr_u_char() Note that the routine xdr_string() exists, but cannot be used with callrpc() and registerrpc (), which only pass two parameters to their XDR routines. xdr_wrapstring() has only two parameters, and is thus OK. It calls xdr_string ().

As an example of a user-defined type routine, if you wanted to send the structure struct simple {
    int a;
    short b; } simple; then you would call callrpc() as callrpc(hostname, PROGNUM, VERSNUM, PROCNUM,
        xdr_simple, &simple ...); where xdr_simple() is written as: #include <rpc/rpc.h> xdr_simple(xdrsp, simplep)
    XDR *xdrsp;
    struct simple *simplep; {
    if (!xdr_int(xdrsp, &simplep->a))
        return (0);
    if (!xdr_short(xdrsp, &simplep->b))
        return (0);
    return (1); }

An XDR routine returns nonzero (true in the sense of C) if it completes successfully, and zero otherwise. A complete description of XDR is in the XDR Protocol Specification section of this manual, only few implementation examples are given here.

In addition to the built-in primitives, there are also the prefabricated building blocks: xdr_array() xdr_bytes() xdr_reference() xdr_vector() xdr_union() xdr_pointer() xdr_string() xdr_opaque() To send a variable array of integers, you might package them up as a structure like this struct varintarr {
    int *data;
    int arrlnth; } arr; and make an RPC call such as callrpc(hostname, PROGNUM, VERSNUM, PROCNUM,
        xdr_varintarr, &arr...); with xdr_varintarr() defined as: xdr_varintarr(xdrsp, arrp)
    XDR *xdrsp;
    struct varintarr *arrp; {
    return (xdr_array(xdrsp, &arrp->data, &arrp->arrlnth,
        MAXLEN, sizeof(int), xdr_int)); } This routine takes as parameters the XDR handle, a pointer to the array, a pointer to the size of the array, the maximum allowable array size, the size of each array element, and an XDR routine for handling each array element.

If the size of the array is known in advance, one can use xdr_vector (), which serializes fixed-length arrays. int intarr[SIZE]; xdr_intarr(xdrsp, intarr)
    XDR *xdrsp;
    int intarr[]; {
    int i;
    return (xdr_vector(xdrsp, intarr, SIZE, sizeof(int),
        xdr_int)); }

XDR always converts quantities to 4-byte multiples when serializing. Thus, if either of the examples above involved characters instead of integers, each character would occupy 32 bits. That is the reason for the XDR routine xdr_bytes() which is like xdr_array() except that it packs characters; xdr_bytes() has four parameters, similar to the first four parameters of xdr_array (). For null-terminated strings, there is also the xdr_string() routine, which is the same as xdr_bytes() without the length parameter. On serializing it gets the string length from strlen (), and on deserializing it creates a null-terminated string.

Here is a final example that calls the previously written xdr_simple() as well as the built-in functions xdr_string() and xdr_reference (), which chases pointers: struct finalexample {
    char *string;
    struct simple *simplep; } finalexample; xdr_finalexample(xdrsp, finalp)
    XDR *xdrsp;
    struct finalexample *finalp; {
    if (!xdr_string(xdrsp, &finalp->string, MAXSTRLEN))
        return (0);
    if (!xdr_reference(xdrsp, &finalp->simplep,
      sizeof(struct simple), xdr_simple);
        return (0);
    return (1); } Note that we could as easily call xdr_simple() here instead of xdr_reference (). Lowest Layer of RPC

In the examples given so far, RPC takes care of many details automatically for you. In this section, we'll show you how you can change the defaults by using lower layers of the RPC library. It is assumed that you are familiar with sockets and the system calls for dealing with them.

There are several occasions when you may need to use lower layers of RPC. First, you may need to use TCP, since the higher layer uses UDP, which restricts RPC calls to 8K bytes of data. Using TCP permits calls to send long streams of data. For an example, see the TCP section below. Second, you may want to allocate and free memory while serializing or deserializing with XDR routines. There is no call at the higher level to let you free memory explicitly. For more explanation, see the Memory Allocation with XDR section below. Third, you may need to perform authentication on either the client or server side, by supplying credentials or verifying them. See the explanation in the Authentication section below. More on the Server Side

The server for the nusers() program shown below does the same thing as the one using registerrpc() above, but is written using a lower layer of the RPC package: #include <stdio.h> #include <rpc/rpc.h> #include <utmp.h> #include <rpcsvc/rusers.h> main() {
    SVCXPRT *transp;
    int nuser();
    transp = svcudp_create(RPC_ANYSOCK);
    if (transp == NULL){
        fprintf(stderr, "can't create an RPC server\n");
        exit(1);
    }
    pmap_unset(RUSERSPROG, RUSERSVERS);
    if (!svc_register(transp, RUSERSPROG, RUSERSVERS,
              nuser, IPPROTO_UDP)) {
        fprintf(stderr, "can't 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, "can't reply to RPC call\n");
        return;
    case RUSERSPROC_NUM:
        /*
         * Code here to compute the number of users
         * and assign it to the variable nusers
         */
        if (!svc_sendreply(transp, xdr_u_long, &nusers))
            fprintf(stderr, "can't reply to RPC call\n");
        return;
    default:
        svcerr_noproc(transp);
        return;
    } }

First, the server gets a transport handle, which is used for receiving and replying to RPC messages. registerrpc() uses svcudp_create() to get a UDP handle. If you require a more reliable protocol, call svctcp_create() instead. If the argument to svcudp_create() is RPC_ANYSOCK the RPC library creates a socket on which to receive and reply to 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 clnttcp_create() (the low-level client routine) must match.

If the user specifies the RPC_ANYSOCK argument, the RPC library routines will open sockets. Otherwise they will expect the user to do so. The routines svcudp_create() and clntudp_create() will cause the RPC library routines to bind() their socket if it is not bound already.

A service may choose to register its port number with the local portmapper service. This is done is done by specifying a non-zero protocol number in svc_register (). Incidently, a client can discover the server's port number by consulting the portmapper on their server's machine. This can be done automatically by specifying a zero port number in clntudp_create() or clnttcp_create ().

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 RUSERSPROG from the port mapper's tables.

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

The user routine nuser() must call and dispatch the appropriate XDR routines based on the procedure number. Note that two things are handled by nuser() that registerrpc() handles automatically. The first is that procedure NULLPROC (currently zero) returns with no results. This can be used as a simple test for detecting if a remote program is running. Second, there is a check for invalid procedure numbers. If one is detected, svcerr_noproc() is called to handle the error.

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 receives data. As an example, we can add a procedure RUSERSPROC_BOOL which has an argument nusers (), and returns TRUE or FALSE depending on whether there are nusers logged on. It would look like this: case RUSERSPROC_BOOL: {
    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, "can't reply to RPC call\n");
         return (1);
    }
    return; }

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

XDR routines not only do input and output, they also do memory allocation. 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)); } If space has already been allocated in chararr , it can be called from a server like this: char chararr[SIZE]; svc_getargs(transp, xdr_chararr1, chararr); 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, charrarrp, &len, SIZE)); } Then the RPC call might look like this: char *arrptr; arrptr = NULL; svc_getargs(transp, xdr_chararr2, &arrptr); /*
 * Use the result here
 */ svc_freeargs(transp, xdr_chararr2, &arrptr); Note that, after being used, the character array can be freed with svc_freeargs() svc_freeargs() will not attempt to free any memory if the variable indicating it is NULL. For example, in the the routine xdr_finalexample (), given earlier, if finalp->string was NULL, then it would not be freed. The same is true for finalp->simplep .

To summarize, each XDR routine is responsible for serializing, deserializing, and freeing memory. When an XDR routine is called from callrpc() the serializing part is used. When called from svc_getargs() the deserializer is used. And when called from svc_freeargs() the memory deallocator is used. When building simple examples like those in this section, a user doesn't have to worry about the three modes. See the External Data Representation: Sun Technical Notes for examples of more sophisticated XDR routines that determine which of the three modes they are in and adjust their behavior accordingly. The Calling Side

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 lets you adjust these parameters, consider the following code to call the nusers service: #include <stdio.h> #include <rpc/rpc.h> #include <utmp.h> #include <rpcsvc/rusers.h> #include <sys/socket.h> #include <sys/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 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, "can't get addr for %s\n",argv[1]);
        exit(-1);
    }
    pertry_timeout.tv_sec = 3;
    pertry_timeout.tv_usec = 0;
    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) {
        clnt_pcreateerror("clntudp_create");
        exit(-1);
    }
    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");
        exit(-1);
    }
    clnt_destroy(client);
    close(sock);
    exit(0); } 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 a CLIENT pointer, the procedure number, the XDR routine for serializing the argument, a pointer to the argument, the XDR routine for deserializing the return value, a pointer to where the return value will be placed, and the time in seconds to wait for a reply.

The CLIENT pointer is encoded with the transport mechanism. callrpc() uses UDP, thus it calls clntudp_create() to get a CLIENT pointer. To get TCP (Transmission Control Protocol), you would use clnttcp_create() .

The parameters to clntudp_create() are the server address, the program number, the version number, a timeout value (between tries), and a pointer to a socket. 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 always deallocates the space associated with the CLIENT handle. It closes the socket associated with the CLIENT handle, however, only if the RPC library opened it. It the socket was opened by the user, it stays open. This makes it possible, in cases where there are multiple client handles using the same socket, to destroy one handle without closing 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, &sock,
               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() . transp = svctcp_create(RPC_ANYSOCK, 0, 0); The last two arguments to svctcp_create() are send and receive sizes respectively. If `0' is specified for either of these, the system chooses a reasonable default. Other RPC Features

This section discusses some other aspects of RPC that are occasionally useful. Select on the Server Side

Suppose a process is processing RPC requests while performing some other activity. If the other activity involves periodically updating a data structure,