Specifications

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 <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 proce-
dure number. Each program also has a version number, so when a minor change is made to a remote ser-
vice (adding a new procedure, for example), a new program number doesn’t hav e to be assigned. When
you want to call a procedure to find the number of remote users, you look up the appropriate program, ver-
sion 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 RUSER-
SPROC_NUM, the return value is an unsigned long so callrpc() has xdr_u_long() as its first return parame-
ter, 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 argu-
ment 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,