rpc.prog.ms

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

You will be given a unique program number in return.
.IX RPC administration
.IX administration "of RPC"
.LP
The RPC program numbers and protocol specifications 
of standard Sun RPC services can be
found in the include files in 
.I "/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:
.LP
\fBTable 3-2\fI RPC Registered Programs\fR
.TS H
box tab (&) ;
lfBI lfBI lfBI
lfL lfL lfI .
RPC Number&Program&Description
_
.TH
.sp.5
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	
.sp .2i
150001&PCNFSDPROG&pc passwd authorization 
.sp .2i
200000&PYRAMIDLOCKINGPROG&Pyramid-locking         
200001&PYRAMIDSYS5&Pyramid-sys5            
200002&CADDS_IMAGE&CV cadds_image		
.sp .2i
300001&ADT_RFLOCKPROG&ADT file locking	
.TE
.NH 2
\&Passing Arbitrary Data Types
.IX "arbitrary data types"
.LP
In the previous example, the RPC call passes a single
.I "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
.I "External Data Representation"
(XDR) before
sending them over the wire.
The process of converting from a particular machine representation
to XDR format is called
.I serializing ,
and the reverse process is called
.I deserializing .
The type field parameters of
.I callrpc() 
and
.I registerrpc() 
can be a built-in procedure like
.I xdr_u_long() 
in the previous example, or a user supplied one.
XDR has these built-in type routines:
.IX RPC "built-in routines"
.DS
.ft CW
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()
.DE
Note that the routine
.I xdr_string() 
exists, but cannot be used with 
.I callrpc() 
and
.I registerrpc (),
which only pass two parameters to their XDR routines.
.I xdr_wrapstring() 
has only two parameters, and is thus OK.  It calls 
.I xdr_string ().
.LP
As an example of a user-defined type routine,
if you wanted to send the structure
.DS
.ft CW
struct simple {
	int a;
	short b;
} simple;
.DE
then you would call
.I callrpc() 
as
.DS
.ft CW
callrpc(hostname, PROGNUM, VERSNUM, PROCNUM,
        xdr_simple, &simple ...);
.DE
where
.I xdr_simple() 
is written as:
.ie t .DS
.el .DS L
.ft CW
#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);
}
.DE
.LP
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
.I "XDR Protocol Specification" 
section of this manual, only few implementation examples are 
given here.
.LP
In addition to the built-in primitives,
there are also the prefabricated building blocks:
.DS
.ft CW
xdr_array()       xdr_bytes()     xdr_reference()
xdr_vector()      xdr_union()     xdr_pointer()
xdr_string()      xdr_opaque()
.DE
To send a variable array of integers,
you might package them up as a structure like this
.DS
.ft CW
struct varintarr {
	int *data;
	int arrlnth;
} arr;
.DE
and make an RPC call such as
.DS
.ft CW
callrpc(hostname, PROGNUM, VERSNUM, PROCNUM,
        xdr_varintarr, &arr...);
.DE
with
.I xdr_varintarr() 
defined as:
.ie t .DS
.el .DS L
.ft CW
xdr_varintarr(xdrsp, arrp)
	XDR *xdrsp;
	struct varintarr *arrp;
{
	return (xdr_array(xdrsp, &arrp->data, &arrp->arrlnth, 
		MAXLEN, sizeof(int), xdr_int));
}
.DE
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.
.KS
.LP
If the size of the array is known in advance, one can use
.I xdr_vector (),
which serializes fixed-length arrays.
.ie t .DS
.el .DS L
.ft CW
int intarr[SIZE];

xdr_intarr(xdrsp, intarr)
	XDR *xdrsp;
	int intarr[];
{
	int i;

	return (xdr_vector(xdrsp, intarr, SIZE, sizeof(int),
		xdr_int));
}
.DE
.KE
.LP
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
.I xdr_bytes()
which is like
.I xdr_array()
except that it packs characters;
.I xdr_bytes() 
has four parameters, similar to the first four parameters of
.I xdr_array ().
For null-terminated strings, there is also the
.I xdr_string()
routine, which is the same as
.I xdr_bytes() 
without the length parameter.
On serializing it gets the string length from
.I strlen (),
and on deserializing it creates a null-terminated string.
.LP
Here is a final example that calls the previously written
.I xdr_simple() 
as well as the built-in functions
.I xdr_string() 
and
.I xdr_reference (),
which chases pointers:
.ie t .DS
.el .DS L
.ft CW
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);
}
.DE
Note that we could as easily call
.I xdr_simple() 
here instead of
.I xdr_reference ().
.NH 1
\&Lowest Layer of RPC
.IX "lowest layer of RPC"
.IX "RPC" "lowest layer"
.LP
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.
.LP
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
.I 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
.I "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 
.I Authentication
section below.
.NH 2
\&More on the Server Side
.IX RPC "server side"
.LP
The server for the
.I nusers() 
program shown below does the same thing as the one using
.I registerrpc() 
above, but is written using a lower layer of the RPC package:
.ie t .DS
.el .DS L
.ft CW
#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\en");
		exit(1);
	}
	pmap_unset(RUSERSPROG, RUSERSVERS);
	if (!svc_register(transp, RUSERSPROG, RUSERSVERS,
			  nuser, IPPROTO_UDP)) {
		fprintf(stderr, "can't register RUSER service\en");
		exit(1);
	}
	svc_run();  /* \fINever returns\fP */
	fprintf(stderr, "should never reach this point\en");
}

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\en");
		return;
	case RUSERSPROC_NUM:
.ft I
		/*
		 * Code here to compute the number of users
		 * and assign it to the variable \fInusers\fP
		 */
.ft CW
		if (!svc_sendreply(transp, xdr_u_long, &nusers)) 
			fprintf(stderr, "can't reply to RPC call\en");
		return;
	default:
		svcerr_noproc(transp);
		return;
	}
}
.DE
.LP
First, the server gets a transport handle, which is used
for receiving and replying to RPC messages.
.I registerrpc() 
uses
.I svcudp_create()
to get a UDP handle.
If you require a more reliable protocol, call
.I svctcp_create()
instead.
If the argument to
.I svcudp_create() 
is
.I RPC_ANYSOCK
the RPC library creates a socket
on which to receive and reply to RPC calls.  Otherwise,
.I 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
.I svcudp_create() 
and
.I clnttcp_create()
(the low-level client routine) must match.
.LP
If the user specifies the
.I RPC_ANYSOCK 
argument, the RPC library routines will open sockets.
Otherwise they will expect the user to do so.  The routines
.I svcudp_create() 
and 
.I clntudp_create()
will cause the RPC library routines to
.I bind() 
their socket if it is not bound already.
.LP
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
.I 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 
.I clntudp_create() 
or
.I clnttcp_create ().
.LP
After creating an
.I SVCXPRT ,
the next step is to call
.I pmap_unset()
so that if the
.I nusers() 
server crashed earlier,
any previous trace of it is erased before restarting.
More precisely,
.I pmap_unset() 
erases the entry for
.I RUSERSPROG
from the port mapper's tables.
.LP
Finally, we associate the program number for
.I nusers() 
with the procedure
.I nuser ().
The final argument to
.I svc_register() 
is normally the protocol being used,
which, in this case, is
.I IPPROTO_UDP
Notice that unlike
.I registerrpc (),
there are no XDR routines involved
in the registration process.
Also, registration is done on the program,
rather than procedure, level.
.LP
The user routine
.I nuser() 
must call and dispatch the appropriate XDR routines
based on the procedure number.
Note that
two things are handled by
.I nuser() 
that
.I registerrpc() 
handles automatically.
The first is that procedure
.I 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,
.I svcerr_noproc()
is called to handle the error.
.KS
.LP
The user service routine serializes the results and returns
them to the RPC caller via
.I svc_sendreply()
Its first parameter is the
.I 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
.I RUSERSPROC_BOOL
which has an argument
.I nusers (),
and returns
.I TRUE 
or
.I FALSE 
depending on whether there are nusers logged on.
It would look like this:
.ie t .DS
.el .DS L
.ft CW
case RUSERSPROC_BOOL: {
	int bool;
	unsigned nuserquery;

	if (!svc_getargs(transp, xdr_u_int, &nuserquery) {
		svcerr_decode(transp);
		return;
	}
.ft I
	/*
	 * Code to set \fInusers\fP = number of users
	 */
.ft CW
	if (nuserquery == nusers)