rpcgen.ms

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

.\"
.\" Must use  --  tbl -- for this one
.\"
.\" @(#)rpcgen.ms	2.2 88/08/04 4.0 RPCSRC
.de BT
.if \\n%=1 .tl ''- % -''
..
.ND
.\" prevent excess underlining in nroff
.if n .fp 2 R
.OH '\fBrpcgen\fP Programming Guide''Page %'
.EH 'Page %''\fBrpcgen\fP Programming Guide'
.if \\n%=1 .bp
.SH
\&\fBrpcgen\fP Programming Guide
.NH 0
\&The \fBrpcgen\fP Protocol Compiler
.IX rpcgen "" \fIrpcgen\fP "" PAGE MAJOR
.LP
.IX RPC "" "" \fIrpcgen\fP
The details of programming applications to use Remote Procedure Calls 
can be overwhelming.  Perhaps most daunting is the writing of the XDR 
routines necessary to convert procedure arguments and results into 
their network format and vice-versa.  
.LP
Fortunately, 
.I rpcgen(1) 
exists to help programmers write RPC applications simply and directly.
.I rpcgen 
does most of the dirty work, allowing programmers to debug 
the  main  features of their application, instead of requiring them to
spend most of their time debugging their network interface code.
.LP
.I rpcgen 
is a  compiler.  It accepts a remote program interface definition written
in a language, called RPC Language, which is similar to C.  It produces a C
language output which includes stub versions of the client routines, a
server skeleton, XDR filter routines for both parameters and results, and a
header file that contains common definitions. The client stubs interface
with the RPC library and effectively hide the network from their callers.
The server stub similarly hides the network from the server procedures that
are to be invoked by remote clients.
.I rpcgen 's
output files can be compiled and linked in the usual way.  The developer
writes server procedures\(emin any language that observes Sun calling
conventions\(emand links them with the server skeleton produced by
.I rpcgen 
to get an executable server program.  To use a remote program, a programmer
writes an ordinary main program that makes local procedure calls to the 
client stubs produced by
.I rpcgen .
Linking this program with 
.I rpcgen 's
stubs creates an executable program.  (At present the main program must be 
written in C).
.I rpcgen 
options can be used to suppress stub generation and to specify the transport
to be used by the server stub.
.LP
Like all compilers, 
.I rpcgen 
reduces development time
that would otherwise be spent coding and debugging low-level routines.
All compilers, including 
.I rpcgen ,
do this at a small cost in efficiency
and flexibility.  However,   many compilers allow  escape  hatches for
programmers to  mix low-level code with  high-level code. 
.I rpcgen 
is no exception.  In speed-critical applications, hand-written routines 
can be linked with the 
.I rpcgen 
output without any difficulty.  Also, one may proceed by using
.I rpcgen 
output as a starting point, and then rewriting it as necessary.
(If you need a discussion of RPC programming without
.I rpcgen ,
see the
.I "Remote Procedure Call Programming Guide)\.
.NH 1
\&Converting Local Procedures into Remote Procedures
.IX rpcgen "local procedures" \fIrpcgen\fP
.IX rpcgen "remote procedures" \fIrpcgen\fP
.LP
Assume an application that runs on a single machine, one which we want 
to convert to run over the network.  Here we will demonstrate such a 
conversion by way of a simple example\(ema program that prints a 
message to the console:
.ie t .DS
.el .DS L
.ft I
/*
 * printmsg.c: print a message on the console
 */
.ft CW
#include <stdio.h>

main(argc, argv)
	int argc;
	char *argv[];
{
	char *message;

	if (argc < 2) {
		fprintf(stderr, "usage: %s <message>\en", argv[0]);
		exit(1);
	}
	message = argv[1];

	if (!printmessage(message)) {
		fprintf(stderr, "%s: couldn't print your message\en",
			argv[0]);
		exit(1);
	} 
	printf("Message Delivered!\en");
	exit(0);
}
.ft I
/*
 * Print a message to the console.
 * Return a boolean indicating whether the message was actually printed.
 */
.ft CW
printmessage(msg)
	char *msg;
{
	FILE *f;

	f = fopen("/dev/console", "w");
	if (f == NULL) {
		return (0);
	}
	fprintf(f, "%s\en", msg);
	fclose(f);
	return(1);
}
.DE
.LP
And then, of course:
.ie t .DS
.el .DS L
.ft CW
example%  \fBcc printmsg.c -o printmsg\fP
example%  \fBprintmsg "Hello, there."\fP
Message delivered!
example%
.DE
.LP
If  
.I printmessage() 
was turned into  a remote procedure,
then it could be  called from anywhere in   the network.  
Ideally,  one would just  like to stick   a  keyword like  
.I remote 
in  front  of a
procedure to turn it into a  remote procedure.  Unfortunately,
we  have to live  within the  constraints of  the   C language, since 
it existed   long before  RPC did.  But   even without language 
support, it's not very difficult to make a procedure remote.
.LP
In  general, it's necessary to figure  out  what the types are for
all procedure inputs and outputs.  In  this case,   we  have a 
procedure
.I printmessage() 
which takes a  string as input, and returns  an integer
as output.  Knowing  this, we can write a  protocol specification in RPC
language that  describes the remote  version of 
.I printmessage ().
Here it is:
.ie t .DS
.el .DS L
.ft I
/*
 * msg.x: Remote message printing protocol
 */
.ft CW

program MESSAGEPROG {
	version MESSAGEVERS {
		int PRINTMESSAGE(string) = 1;
	} = 1;
} = 99;
.DE
.LP
Remote procedures are part of remote programs, so we actually declared
an  entire  remote program  here  which contains  the single procedure
.I PRINTMESSAGE .
This procedure was declared to be  in version  1 of the
remote program.  No null procedure (procedure 0) is necessary because
.I rpcgen 
generates it automatically.
.LP
Notice that everything is declared with all capital  letters.  This is
not required, but is a good convention to follow.
.LP
Notice also that the argument type is \*Qstring\*U and not \*Qchar *\*U.  This
is because a \*Qchar *\*U in C is ambiguous.  Programmers usually intend it
to mean  a null-terminated string   of characters, but  it  could also
represent a pointer to a single character or a  pointer to an array of
characters.  In  RPC language,  a  null-terminated  string is 
unambiguously called a \*Qstring\*U.
.LP
There are  just two more things to  write.  First, there is the remote
procedure itself.  Here's the definition of a remote procedure
to implement the
.I PRINTMESSAGE
procedure we declared above:
.ie t .DS
.el .DS L
.vs 11
.ft I
/*
 * msg_proc.c: implementation of the remote procedure "printmessage"
 */
.ft CW

#include <stdio.h>
#include <rpc/rpc.h>    /* \fIalways needed\fP  */
#include "msg.h"        /* \fIneed this too: msg.h will be generated by rpcgen\fP */

.ft I
/*
 * Remote verson of "printmessage"
 */
.ft CW
int *
printmessage_1(msg)
	char **msg;
{
	static int result;  /* \fImust be static!\fP */
	FILE *f;

	f = fopen("/dev/console", "w");
	if (f == NULL) {
		result = 0;
		return (&result);
	}
	fprintf(f, "%s\en", *msg);
	fclose(f);
	result = 1;
	return (&result);
}
.vs
.DE
.LP
Notice here that the declaration of the remote procedure
.I printmessage_1() 
differs from that of the local procedure
.I printmessage() 
in three ways:
.IP  1.
It takes a pointer to a string instead of a string itself.  This
is true of all  remote procedures:  they always take pointers to  their
arguments rather than the arguments themselves.
.IP  2.
It returns a pointer to an  integer instead of  an integer itself. This is
also generally true of remote procedures: they always return a pointer
to their results.
.IP  3.
It has an \*Q_1\*U appended to its name.  In general, all remote
procedures called by 
.I rpcgen 
are named by  the following rule: the name in the program  definition  
(here 
.I PRINTMESSAGE )
is converted   to all
lower-case letters, an underbar (\*Q_\*U) is appended to it, and
finally the version number (here 1) is appended.
.LP
The last thing to do is declare the main client program that will call
the remote procedure. Here it is:
.ie t .DS
.el .DS L
.ft I
/*
 * rprintmsg.c: remote version of "printmsg.c"
 */
.ft CW
#include <stdio.h>
#include <rpc/rpc.h>     /* \fIalways needed\fP  */
#include "msg.h"         /* \fIneed this too: msg.h will be generated by rpcgen\fP */

main(argc, argv)
	int argc;
	char *argv[];
{
	CLIENT *cl;
	int *result;
	char *server;
	char *message;

	if (argc < 3) {
		fprintf(stderr, "usage: %s host message\en", argv[0]);
		exit(1);
	}

.ft I
	/*
	 * Save values of command line arguments 
	 */
.ft CW
	server = argv[1];
	message = argv[2];

.ft I
	/*
	 * Create client "handle" used for calling \fIMESSAGEPROG\fP on the
	 * server designated on the command line. We tell the RPC package
	 * to use the "tcp" protocol when contacting the server.
	 */
.ft CW
	cl = clnt_create(server, MESSAGEPROG, MESSAGEVERS, "tcp");
	if (cl == NULL) {
.ft I
		/*
		 * Couldn't establish connection with server.
		 * Print error message and die.
		 */
.ft CW
		clnt_pcreateerror(server);
		exit(1);
	}

.ft I
	/*
	 * Call the remote procedure "printmessage" on the server
	 */
.ft CW
	result = printmessage_1(&message, cl);
	if (result == NULL) {
.ft I
		/*
		 * An error occurred while calling the server. 
	 	 * Print error message and die.
		 */
.ft CW
		clnt_perror(cl, server);
		exit(1);
	}

.ft I
	/*
	 * Okay, we successfully called the remote procedure.
	 */
.ft CW
	if (*result == 0) {
.ft I
		/*
		 * Server was unable to print our message. 
		 * Print error message and die.
		 */
.ft CW
		fprintf(stderr, "%s: %s couldn't print your message\en", 
			argv[0], server);	
		exit(1);
	} 

.ft I
	/*
	 * The message got printed on the server's console
	 */
.ft CW
	printf("Message delivered to %s!\en", server);
}
.DE
There are two things to note here:
.IP  1.
.IX "client handle, used by rpcgen" "" "client handle, used by \fIrpcgen\fP"
First a client \*Qhandle\*U is created using the RPC library routine
.I clnt_create ().
This client handle will be passed  to the stub routines
which call the remote procedure.
.IP  2.
The remote procedure  
.I printmessage_1() 
is called exactly  the same way as it is  declared in 
.I msg_proc.c 
except for the inserted client handle as the first argument.
.LP
Here's how to put all of the pieces together:
.ie t .DS
.el .DS L
.ft CW
example%  \fBrpcgen msg.x\fP
example%  \fBcc rprintmsg.c msg_clnt.c -o rprintmsg\fP
example%  \fBcc msg_proc.c msg_svc.c -o msg_server\fP
.DE
Two programs were compiled here: the client program 
.I rprintmsg 
and the server  program 
.I msg_server .
Before doing this  though,  
.I rpcgen 
was used to fill in the missing pieces.  
.LP
Here is what 
.I rpcgen 
did with the input file 
.I msg.x :
.IP  1.
It created a header file called 
.I msg.h 
that contained
.I #define 's
for
.I MESSAGEPROG ,
.I MESSAGEVERS 
and    
.I PRINTMESSAGE 
for use in  the  other modules.
.IP  2.
It created client \*Qstub\*U routines in the
.I msg_clnt.c 
file.   In this case there is only one, the 
.I printmessage_1() 
that was referred to from the
.I printmsg 
client program.  The name  of the output file for
client stub routines is always formed in this way:  if the name of the
input file is  
.I FOO.x ,
the   client  stubs   output file is    called
.I FOO_clnt.c .
.IP  3.
It created  the  server   program which calls   
.I printmessage_1() 
in
.I msg_proc.c .
This server program is named  
.I msg_svc.c .
The rule for naming the server output file is similar  to the 
previous one:  for an input  file   called  
.I FOO.x ,
the   output   server   file is  named