Specifications

ManualsBrandsRPC ManualsComputer equipment-WR5441

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 appli-

cations, you can circumvent the need to cope with the details presented here by using rpcgen. The Generat-

ing 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

speciﬁcally 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.

1. Layers of RPC

The RPC interface can be seen as being divided into three layers.

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 num-

ber of users on a remote machine. The user is not explicitly aware of using RPC — they simply call a pro-

cedure, 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 rou-

tines are used for most applications.

RPC calls are made with the system routines registerrpc() callrpc() and svc_run(). The ﬁrst two of these

are the most fundamental: registerrpc() obtains a unique system-wide procedure-identiﬁcation 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 inﬂexibility (simplicity). It

does not allow timeout speciﬁcations or the choice of transport. It allows no UNIX process control or ﬂexi-

bility 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 efﬁcient, 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.

For a complete speciﬁcation of the routines in the remote procedure call Library, see the rpc(3N) manual

page.

-1-

Summary of content (34 pages)

PAGE 1
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.
PAGE 2
Page 2 Remote Procedure Call Programming Guide 1.1.
PAGE 3
Remote Procedure Call Programming Guide Page 3 2. Higher Layers of RPC 2.1. 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
PAGE 4
Page 4 Remote Procedure Call Programming Guide 2.2. 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 #include #include #include
PAGE 5
Remote Procedure Call Programming Guide Page 5 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.
PAGE 6
Page 6 Remote Procedure Call Programming Guide 2.3.
PAGE 7
Remote Procedure Call Programming Guide Page 7 RPC Number 100020 100021 100022 100023 100024 100025 100026 100027 100028 100029 100030 100031 100032 100033 100034 100035 100036 100037 100038 100039 Program LOCKPROG NETLOCKPROG X25PROG STATMON1PROG STATMON2PROG SELNLIBPROG BOOTPARAMPROG MAZEPROG YPUPDATEPROG KEYSERVEPROG SECURECMDPROG NETFWDIPROG NETFWDTPROG SUNLINKMAP_PROG NETMONPROG DBASEPROG PWDAUTHPROG TFSPROG NSEPROG NSE_ACTIVATE_PROG Description local lock manager network lock manager x.
PAGE 8
Page 8 Remote Procedure Call Programming Guide then you would call callrpc() as callrpc(hostname, PROGNUM, VERSNUM, PROCNUM, xdr_simple, &simple ...); where xdr_simple() is written as: #include 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.
PAGE 9
Remote Procedure Call Programming Guide Page 9 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.
PAGE 10
Page 10 Remote Procedure Call Programming Guide 3.1. 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 #include #include #include
PAGE 11
Remote Procedure Call Programming Guide Page 11 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.
PAGE 12
Page 12 Remote Procedure Call Programming Guide 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. 3.2. 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.
PAGE 13
Remote Procedure Call Programming Guide Page 13 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.
PAGE 14
Page 14 Remote Procedure Call Programming Guide 3.3. 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 #include #include #include #include #include #include
PAGE 15
Remote Procedure Call Programming Guide Page 15 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().
PAGE 16
Page 16 Remote Procedure Call Programming Guide 4. Other RPC Features This section discusses some other aspects of RPC that are occasionally useful. 4.1. 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, the process can set an alarm signal before calling svc_run() But if the other activity involves waiting on a a file descriptor, the svc_run() call won’t work.
PAGE 17
Remote Procedure Call Programming Guide Page 17 4.2.1. Broadcast RPC Synopsis #include . . . enum clnt_stat clnt_stat; . . .
PAGE 18
Page 18 Remote Procedure Call Programming Guide #include #include #include
PAGE 19
Remote Procedure Call Programming Guide Page 19 fprintf(stderr, "can’t decode arguments\n"); /* * We are silent in the face of protocol errors */ break; } /* * Code here to render string s, but send no reply! */ break; default: svcerr_noproc(transp); return; } /* * Now free string allocated while decoding arguments */ svc_freeargs(transp, xdr_wrapstring, &s); } Of course the service could have one procedure that takes the string and a boolean to indicate whether or not the procedure should respond.
PAGE 20
Page 20 Remote Procedure Call Programming Guide Here is an example of a client that uses batching to render a bunch of strings; the batching is flushed when the client gets a null string (EOF): #include #include #include #include #include #include
PAGE 21
Remote Procedure Call Programming Guide Page 21 4.4. Authentication In the examples presented so far, the caller never identified itself to the server, and the server never required an ID from the caller. Clearly, some network services, such as a network filesystem, require stronger security than what has been presented so far. In reality, every RPC call is authenticated by the RPC package on the server, and similarly, the RPC client package generates and sends authentication parameters.
PAGE 22
Page 22 Remote Procedure Call Programming Guide /* * An RPC Service request */ struct svc_req { u_long rq_prog; /* service program number */ u_long rq_vers; /* service protocol vers num */ u_long rq_proc; /* desired procedure number */ struct opaque_auth rq_cred; /* raw credentials from wire */ caddr_t rq_clntcred; /* credentials (read only) */ }; The rq_cred is mostly opaque, except for one field of interest: the style or flavor of authentication credentials: /* * Authentication info.
PAGE 23
Remote Procedure Call Programming Guide Page 23 nuser(rqstp, transp) struct svc_req *rqstp; SVCXPRT *transp; { struct authunix_parms *unix_cred; int uid; unsigned long nusers; /* * we don’t care about authentication for null proc */ if (rqstp->rq_proc == NULLPROC) { if (!svc_sendreply(transp, xdr_void, 0)) { fprintf(stderr, "can’t reply to RPC call\n"); return (1); } return; } /* * now get the uid */ switch (rqstp->rq_cred.
PAGE 24
Page 24 Remote Procedure Call Programming Guide call the service primitive svcerr_systemerr() instead. The last point underscores the relation between the RPC authentication package and the services; RPC deals only with authentication and not with individual services’ access control. The services themselves must implement their own access control policies and reflect these policies as return statuses in their protocols. 4.5. DES Authentication UNIX authentication is quite easy to defeat.
PAGE 25
Remote Procedure Call Programming Guide Page 25 The final argument to authdes_create() is the address of a DES encryption key to use for encrypting timestamps and data. If this argument is NULL, as it is in this example, a random key will be chosen. The client may find out the encryption key being used by consulting the ah_key field of the authentication handle. Server Side The server side is a lot simpler than the client side.
PAGE 26
Page 26 Remote Procedure Call Programming Guide 4.6. Using Inetd An RPC server can be started from inetd The only difference from the usual code is that the service creation routine should be called in the following form: transp = svcudp_create(0); /* For UDP */ transp = svctcp_create(0,0,0); /* For listener TCP sockets */ transp = svcfd_create(0,0,0); /* For connected TCP sockets */ since inet passes a socket as file descriptor 0.
PAGE 27
Remote Procedure Call Programming Guide nuser(rqstp, transp) struct svc_req *rqstp; SVCXPRT *transp; { unsigned long nusers; unsigned short nusers2; switch (rqstp->rq_proc) { case NULLPROC: if (!svc_sendreply(transp, xdr_void, 0)) { fprintf(stderr, "can’t reply to RPC call\n"); return (1); } return; case RUSERSPROC_NUM: /* * Code here to compute the number of users * and assign it to the variable nusers */ nusers2 = nusers; switch (rqstp->rq_vers) { case RUSERSVERS_ORIG: if (!svc_sendreply(transp, xdr_u_lo
PAGE 28
Page 28 Remote Procedure Call Programming Guide 5.2. TCP Here is an example that is essentially rcp. The initiator of the RPC snd call takes its standard input and sends it to the server rcv which prints it on standard output. The RPC call uses TCP. This also illustrates an XDR procedure that behaves differently on serialization than on deserialization. /* * The xdr routine: * on decode, read from wire, write onto fp * on encode, read from fp, write onto wire */ #include #include
PAGE 29
Remote Procedure Call Programming Guide /* * The sender routines */ #include #include #include #include #include
PAGE 30
Page 30 Remote Procedure Call Programming Guide return (int)clnt_stat; } /* * The receiving routines */ #include #include
PAGE 31
Remote Procedure Call Programming Guide Page 31 5.3. Callback Procedures Occasionally, it is useful to have a server become a client, and make an RPC call back to the process which is its client. An example is remote debugging, where the client is a window system program, and the server is a debugger running on the remote machine.
PAGE 32
Page 32 Remote Procedure Call Programming Guide #include #include #include
PAGE 33
Remote Procedure Call Programming Guide Page 33 The following pair of programs illustrate how to use the gettransient() routine. The client makes an RPC call to the server, passing it a transient program number. Then the client waits around to receive a callback from the server at that program number. The server registers the program EXAMPLEPROG so that it can receive the RPC call informing it of the callback program number.
PAGE 34
Page 34 Remote Procedure Call Programming Guide fprintf(stderr, "client got callback\n"); if (!svc_sendreply(transp, xdr_void, 0)) { fprintf(stderr, "err: exampleprog"); return (1); } } } /* * server */ #include #include #include