rpc.prog.ms

RTEMS (Real-Time Executive for Multiprocessor Systems) is a free open source real-time operating sys

.\"
.\" Must use -- tbl and pic -- with this one
.\"
.\" @(#)rpc.prog.ms	2.3 88/08/11 4.0 RPCSRC
.de BT
.if \\n%=1 .tl ''- % -''
..
.IX "Network Programming" "" "" "" PAGE MAJOR
.nr OF 0
.ND
.\" prevent excess underlining in nroff
.if n .fp 2 R
.OH 'Remote Procedure Call Programming Guide''Page %'
.EH 'Page %''Remote Procedure Call Programming Guide'
.SH
\&Remote Procedure Call Programming Guide
.nr OF 1
.IX "RPC Programming Guide"
.LP
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
.I rpcgen(1) 
protocol compiler.
.I rpcgen 
is described in detail in the previous chapter, the
.I "\fBrpcgen\fP \fIProgramming Guide\fP".
.SH
Note:
.I
.IX rpcgen "" \fIrpcgen\fP
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
.I rpcgen .
The
.I "Generating XDR Routines"
section of that chapter contains the complete source for a working RPC
service\(ema remote directory listing service which uses
.I rpcgen 
to generate XDR routines as well as client and server stubs.
.LP
.LP
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.
.NH 0
\&Layers of RPC
.IX "layers of RPC"
.IX "RPC" "layers"
.LP
The RPC interface can be seen as being divided into three layers.\**
.FS
For a complete specification of the routines in the remote procedure
call Library, see the
.I rpc(3N) 
manual page.
.FE
.LP
.I "The Highest Layer:"
.IX RPC "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
.I using
RPC, rather than as
a \fIpart of\fP 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.
.LP 
To illustrate, at this level a program can simply make a call to
.I rnusers (),
a C routine which returns the number of users on a remote machine.
The user is not explicitly aware of using RPC \(em they simply 
call a procedure, just as they would call
.I malloc() .
.LP
.I "The Middle Layer:"
.IX RPC "The Middle Layer"
The middle layer is really \*QRPC proper.\*U  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 \*Qhello world\*U test \(em
simple things should be simple.  The middle-layer routines are used 
for most applications.
.LP
RPC calls are made with the system routines
.I registerrpc()
.I callrpc()
and
.I svc_run ().
The first two of these are the most fundamental:
.I registerrpc() 
obtains a unique system-wide procedure-identification number, and
.I callrpc() 
actually executes a remote procedure call.  At the middle level, a 
call to 
.I rnusers()
is implemented by way of these two routines.
.LP
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.
.LP
.I "The Lowest Layer:"
.IX RPC "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 \(em since RPC clients and servers rarely generate 
heavy network loads.
.LP
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.
.br
.KS
.NH 2
\&The RPC Paradigm
.IX RPC paradigm
.LP
Here is a diagram of the RPC paradigm:
.LP
\fBFigure 1-1\fI Network Communication with the Remote Reocedure Call\fR
.LP
.PS
L1: arrow down 1i "client " rjust "program " rjust
L2: line right 1.5i "\fIcallrpc\fP" "function"
move up 1.5i; line dotted down 6i; move up 4.5i
arrow right 1i
L3: arrow down 1i "invoke " rjust "service " rjust
L4: arrow right 1.5i "call" "service"
L5: arrow down 1i " service" ljust " executes" ljust
L6: arrow left 1.5i "\fIreturn\fP" "answer"
L7: arrow down 1i "request " rjust "completed " rjust
L8: line left 1i
arrow left 1.5i "\fIreturn\fP" "reply"
L9: arrow down 1i "program " rjust "continues " rjust
line dashed down from L2 to L9
line dashed down from L4 to L7
line dashed up 1i from L3 "service " rjust "daemon " rjust
arrow dashed down 1i from L8
move right 1i from L3
box invis "Machine B"
move left 1.2i from L2; move down
box invis "Machine A"
.PE
.KE
.KS
.NH 1
\&Higher Layers of RPC
.NH 2
\&Highest Layer
.IX "highest layer of RPC"
.IX RPC "highest layer"
.LP
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
.I rnusers()
as illustrated below:
.ie t .DS
.el .DS L
.ft CW
#include <stdio.h>

main(argc, argv)
	int argc;
	char **argv;
{
	int num;

	if (argc != 2) {
		fprintf(stderr, "usage: rnusers hostname\en");
		exit(1);
	}
	if ((num = rnusers(argv[1])) < 0) {
		fprintf(stderr, "error: rnusers\en");
		exit(-1);
	}
	printf("%d users on %s\en", num, argv[1]);
	exit(0);
}
.DE
.KE
RPC library routines such as
.I rnusers() 
are in the RPC services library
.I librpcsvc.a
Thus, the program above should be compiled with
.DS
.ft CW
% cc \fIprogram.c -lrpcsvc\fP
.DE
.I rnusers (),
like the other RPC library routines, is documented in section 3R 
of the
.I "System Interface Manual for the Sun Workstation" ,
the same section which documents the standard Sun RPC services.  
.IX "RPC Services"
See the 
.I intro(3R) 
manual page for an explanation of the documentation strategy 
for these services and their RPC protocols.
.LP
Here are some of the RPC service library routines available to the 
C programmer:
.LP
\fBTable 3-3\fI RPC Service Library Routines\RP
.TS
box tab (&) ;
cfI cfI
lfL l .
Routine&Description
_
.sp.5
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
.TE
.LP
Other RPC services \(em for example
.I ether()
.I mount
.I rquota()
and
.I spray
\(em are not available to the C programmer as library routines.
They do, however,
have RPC program numbers so they can be invoked with
.I callrpc()
which will be discussed in the next section.  Most of them also 
have compilable 
.I rpcgen(1) 
protocol description files.  (The
.I rpcgen
protocol compiler radically simplifies the process of developing
network applications.  
See the \fBrpcgen\fI Programming Guide\fR
for detailed information about 
.I rpcgen 
and 
.I rpcgen 
protocol description files).
.KS
.NH 2
\&Intermediate Layer
.IX "intermediate layer of RPC"
.IX "RPC" "intermediate layer"
.LP
The simplest interface, which explicitly makes RPC calls, uses the 
functions
.I callrpc()
and
.I registerrpc()
Using this method, the number of remote users can be gotten as follows:
.ie t .DS
.el .DS L
#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\en");
		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\en", nusers, argv[1]);
	exit(0);
}
.DE
.KE
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.
.LP
The simplest way of making remote procedure calls is with the the RPC 
library routine
.I 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\(emtogether 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 
.I callrpc() 
completes successfully, it returns zero; else it returns a nonzero 
value.  The return codes (of type
.IX "enum clnt_stat (in RPC programming)" "" "\fIenum clnt_stat\fP (in RPC programming)"
cast into an integer) are found in 
.I <rpc/clnt.h> .
.LP
Since data types may be represented differently on different machines,
.I callrpc() 
needs both the type of the RPC argument, as well as
a pointer to the argument itself (and similarly for the result).  For
.I RUSERSPROC_NUM ,
the return value is an
.I "unsigned long"
so
.I callrpc() 
has
.I xdr_u_long() 
as its first return parameter, which says
that the result is of type
.I "unsigned long"
and
.I &nusers 
as its second return parameter,
which is a pointer to where the long result will be placed.  Since
.I RUSERSPROC_NUM 
takes no argument, the argument parameter of
.I callrpc() 
is
.I xdr_void ().
.LP
After trying several times to deliver a message, if
.I 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:
.ie t .DS
.el .DS L
.ft CW
.ft CW
char *
nuser(indata)
	char *indata;
{
	unsigned long nusers;

.ft I
	/*
	 * Code here to compute the number of users
	 * and place result in variable \fInusers\fP.
	 */
.ft CW
	return((char *)&nusers);
}
.DE
.LP
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
.I "char *" .
.LP
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:
.ie t .DS
.el .DS L
.ft CW
#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();		/* \fINever returns\fP */
	fprintf(stderr, "Error: svc_run returned!\en");
	exit(1);
}
.DE
.LP
The
.I registerrpc()
routine registers a C procedure as corresponding to a
given RPC procedure number.  The first three parameters,
.I RUSERPROG ,
.I RUSERSVERS ,
and
.I RUSERSPROC_NUM 
are the program, version, and procedure numbers
of the remote procedure to be registered;
.I nuser() 
is the name of the local procedure that implements the remote
procedure; and
.I xdr_void() 
and
.I 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).
.LP
Only the UDP transport mechanism can use
.I registerrpc()
thus, it is always safe in conjunction with calls generated by
.I callrpc() .
.SH
.IX "UDP 8K warning"
Warning: the UDP transport mechanism can only deal with
arguments and results less than 8K bytes in length.
.LP
.LP
After registering the local procedure, the server program's
main procedure calls
.I 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.
.NH 2
\&Assigning Program Numbers
.IX "program number assignment"
.IX "assigning program numbers"
.LP
Program numbers are assigned in groups of 
.I 0x20000000 
according to the following chart:
.DS
.ft CW
       0x0 - 0x1fffffff	\fRDefined by Sun\fP
0x20000000 - 0x3fffffff	\fRDefined by user\fP
0x40000000 - 0x5fffffff	\fRTransient\fP
0x60000000 - 0x7fffffff	\fRReserved\fP
0x80000000 - 0x9fffffff	\fRReserved\fP
0xa0000000 - 0xbfffffff	\fRReserved\fP
0xc0000000 - 0xdfffffff	\fRReserved\fP
0xe0000000 - 0xffffffff	\fRReserved\fP
.ft R
.DE
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.
.LP
To register a protocol specification, send a request by network 
mail to
.I rpc@sun
or write to:
.DS
RPC Administrator
Sun Microsystems
2550 Garcia Ave.
Mountain View, CA 94043
.DE
Please include a compilable 
.I rpcgen 
\*Q.x\*U file describing your protocol.