rpcgen.ms

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

	/*
	 * return non-null pointer so RPC will send out a reply
	 */
.ft L
	return ((void *)&notnull);
}
.DE
Note that if procedure returns type \*Qvoid *\*U, they must return a non-NULL
pointer if they want RPC to reply for them.
.NH 2
\&Other Information Passed to Server Procedures
.LP
Server procedures will often want to know more about an RPC call
than just its arguments.  For example, getting authentication information
is important to procedures that want to implement some level of security.
This extra information is actually supplied to the server procedure as a
second argument.  Here is an example to demonstrate its use.  What we've
done here is rewrite the previous
.I printmessage_1() 
procedure to only allow root users to print a message to the console.
.ID
int *
printmessage_1(msg, rq)
	char **msg;
	struct svc_req	*rq;
{
	static in result;	/* \fIMust be static\fP */
	FILE *f;
	struct suthunix_parms *aup;
.sp .5
	aup = (struct authunix_parms *)rq->rq_clntcred;
	if (aup->aup_uid != 0) {
		result = 0;
		return (&result);
	}
.sp
.ft I
	/*
	 * Same code as before.
	 */
.ft L
}
.DE
.NH 1
\&RPC Language
.IX RPCL
.IX rpcgen "RPC Language" \fIrpcgen\fP
.LP
RPC language is an extension of XDR  language.   The sole extension is
the addition of the
.I program 
type.  For a complete description of the XDR language syntax, see the
.I "External Data Representation Standard: Protocol Specification"
chapter.  For a description of the RPC extensions to the XDR language,
see the
.I "Remote Procedure Calls: Protocol Specification"
chapter.
.LP
However, XDR language is so close to C that if you know C, you know most
of it already.  We describe here  the syntax of the RPC language,
showing a  few examples along the way.   We also show how  the various
RPC and XDR type definitions get  compiled into C  type definitions in
the output header file.
.KS
.NH 2
Definitions
\&
.IX rpcgen definitions \fIrpcgen\fP
.LP
An RPC language file consists of a series of definitions.
.DS L
.ft CW
    definition-list:
        definition ";"
        definition ";" definition-list
.DE
.KE
It recognizes five types of definitions. 
.DS L
.ft CW
    definition:
        enum-definition
        struct-definition
        union-definition
        typedef-definition
        const-definition
        program-definition
.DE
.NH 2
Structures
\&
.IX rpcgen structures \fIrpcgen\fP
.LP
An XDR struct  is declared almost exactly like  its C counterpart.  It
looks like the following:
.DS L
.ft CW
    struct-definition:
        "struct" struct-ident "{"
            declaration-list
        "}"

    declaration-list:
        declaration ";"
        declaration ";" declaration-list
.DE
As an example, here is an XDR structure to a two-dimensional
coordinate, and the C structure  that it  gets compiled into  in the
output header file.
.DS
.ft CW
   struct coord {             struct coord {
        int x;       -->           int x;
        int y;                     int y;
   };                         };
                              typedef struct coord coord;
.DE
The output is identical to the  input, except  for the added
.I typedef
at the end of the output.  This allows one to use \*Qcoord\*U instead of
\*Qstruct coord\*U when declaring items.
.NH 2
Unions
\&
.IX rpcgen unions \fIrpcgen\fP
.LP
XDR unions are discriminated unions, and look quite different from C
unions. They are more analogous to  Pascal variant records than they
are to C unions.
.DS L
.ft CW
    union-definition:
        "union" union-ident "switch" "(" declaration ")" "{"
            case-list
        "}"

    case-list:
        "case" value ":" declaration ";"
        "default" ":" declaration ";"
        "case" value ":" declaration ";" case-list
.DE
Here is an example of a type that might be returned as the result of a
\*Qread data\*U operation.  If there is no error, return a block of data.
Otherwise, don't return anything.
.DS L
.ft CW
    union read_result switch (int errno) {
    case 0:
        opaque data[1024];
    default:
        void;
    };
.DE
It gets compiled into the following:
.DS L
.ft CW
    struct read_result {
        int errno;
        union {
            char data[1024];
        } read_result_u;
    };
    typedef struct read_result read_result;
.DE
Notice that the union component of the  output struct  has the name as
the type name, except for the trailing \*Q_u\*U.
.NH 2
Enumerations
\&
.IX rpcgen enumerations \fIrpcgen\fP
.LP
XDR enumerations have the same syntax as C enumerations.
.DS L
.ft CW
    enum-definition:
        "enum" enum-ident "{"
            enum-value-list
        "}"

    enum-value-list:
        enum-value
        enum-value "," enum-value-list

    enum-value:
        enum-value-ident 
        enum-value-ident "=" value
.DE
Here is a short example of  an XDR enum,  and the C enum that  it gets
compiled into.
.DS L
.ft CW
     enum colortype {      enum colortype {
          RED = 0,              RED = 0,
          GREEN = 1,   -->      GREEN = 1,
          BLUE = 2              BLUE = 2,
     };                    };
                           typedef enum colortype colortype;
.DE
.NH 2
Typedef
\&
.IX rpcgen typedef \fIrpcgen\fP
.LP
XDR typedefs have the same syntax as C typedefs.
.DS L
.ft CW
    typedef-definition:
        "typedef" declaration
.DE
Here  is an example  that defines a  
.I fname_type 
used  for declaring
file name strings that have a maximum length of 255 characters.
.DS L
.ft CW
typedef string fname_type<255>; --> typedef char *fname_type;
.DE
.NH 2
Constants
\&
.IX rpcgen constants \fIrpcgen\fP
.LP
XDR constants  symbolic constants  that may be  used wherever  a
integer constant is used, for example, in array size specifications.
.DS L
.ft CW
    const-definition:
        "const" const-ident "=" integer
.DE
For example, the following defines a constant
.I DOZEN 
equal to 12.
.DS L
.ft CW
    const DOZEN = 12;  -->  #define DOZEN 12
.DE
.NH 2
Programs
\&
.IX rpcgen programs \fIrpcgen\fP
.LP
RPC programs are declared using the following syntax:
.DS L
.ft CW
    program-definition:
        "program" program-ident "{" 
            version-list
        "}" "=" value 

    version-list:
        version ";"
        version ";" version-list

    version:
        "version" version-ident "{"
            procedure-list 
        "}" "=" value

    procedure-list:
        procedure ";"
        procedure ";" procedure-list

    procedure:
        type-ident procedure-ident "(" type-ident ")" "=" value
.DE
For example, here is the time protocol, revisited:
.ie t .DS
.el .DS L
.ft I
/*
 * time.x: Get or set the time. Time is represented as number of seconds
 * since 0:00, January 1, 1970.
 */
.ft CW
program TIMEPROG {
    version TIMEVERS {
        unsigned int TIMEGET(void) = 1;
        void TIMESET(unsigned) = 2;
    } = 1;
} = 44;        
.DE
This file compiles into #defines in the output header file:
.ie t .DS
.el .DS L
.ft CW
#define TIMEPROG 44
#define TIMEVERS 1
#define TIMEGET 1
#define TIMESET 2
.DE
.NH 2
Declarations
\&
.IX rpcgen declarations \fIrpcgen\fP
.LP
In XDR, there are only four kinds of declarations.  
.DS L
.ft CW
    declaration:
        simple-declaration
        fixed-array-declaration
        variable-array-declaration
        pointer-declaration
.DE
\fB1) Simple declarations\fP are just like simple C declarations.
.DS L
.ft CW
    simple-declaration:
        type-ident variable-ident
.DE
Example:
.DS L
.ft CW
    colortype color;    --> colortype color;
.DE
\fB2) Fixed-length Array Declarations\fP are just like C array declarations:
.DS L
.ft CW
    fixed-array-declaration:
        type-ident variable-ident "[" value "]"
.DE
Example:
.DS L
.ft CW
    colortype palette[8];    --> colortype palette[8];
.DE
\fB3) Variable-Length Array Declarations\fP have no explicit syntax 
in C, so XDR invents its own using angle-brackets.
.DS L
.ft CW
variable-array-declaration:
    type-ident variable-ident "<" value ">"
    type-ident variable-ident "<" ">"
.DE
The maximum size is specified between the angle brackets. The size may
be omitted, indicating that the array may be of any size.
.DS L
.ft CW
    int heights<12>;    /* \fIat most 12 items\fP */
    int widths<>;       /* \fIany number of items\fP */
.DE
Since  variable-length  arrays have no  explicit  syntax in  C,  these
declarations are actually compiled into \*Qstruct\*Us.  For example, the
\*Qheights\*U declaration gets compiled into the following struct:
.DS L
.ft CW
    struct {
        u_int heights_len;  /* \fI# of items in array\fP */
        int *heights_val;   /* \fIpointer to array\fP */
    } heights;
.DE
Note that the number of items in the array is stored in the \*Q_len\*U
component and the pointer to the array is stored in the \*Q_val\*U
component. The first part of each of these component's names is the
same as the name of the declared XDR variable.
.LP
\fB4) Pointer Declarations\fP are made in 
XDR  exactly as they  are  in C.  You  can't
really send pointers over the network,  but  you  can use XDR pointers
for sending recursive data types such as lists and trees.  The type is
actually called \*Qoptional-data\*U, not \*Qpointer\*U, in XDR language.
.DS L
.ft CW
    pointer-declaration:
        type-ident "*" variable-ident
.DE
Example:
.DS L
.ft CW
    listitem *next;  -->  listitem *next;
.DE
.NH 2
\&Special Cases
.IX rpcgen "special cases" \fIrpcgen\fP
.LP
There are a few exceptions to the rules described above.
.LP
.B Booleans:
C has no built-in boolean type. However, the RPC library does  a
boolean type   called 
.I bool_t 
that   is either  
.I TRUE 
or  
.I FALSE .
Things declared as  type 
.I bool 
in  XDR language  are  compiled  into
.I bool_t 
in the output header file.
.LP
Example:
.DS L
.ft CW
    bool married;  -->  bool_t married;
.DE
.B Strings:
C has  no built-in string  type, but  instead uses the null-terminated
\*Qchar *\*U convention.  In XDR language, strings are declared using the
\*Qstring\*U keyword, and compiled into \*Qchar *\*Us in the output header
file. The  maximum size contained  in the angle brackets specifies the
maximum number of characters allowed in the  strings (not counting the
.I NULL 
character). The maximum size may be left off, indicating a string
of arbitrary length.
.LP
Examples:
.DS L
.ft CW
    string name<32>;    -->  char *name;
    string longname<>;  -->  char *longname;
.DE
.B "Opaque  Data:"
Opaque data is used in RPC and XDR to describe untyped  data, that is,
just  sequences of arbitrary  bytes.  It may be  declared  either as a
fixed or variable length array.
.DS L
Examples:
.ft CW
    opaque diskblock[512];  -->  char diskblock[512];

    opaque filedata<1024>;  -->  struct {
                                    u_int filedata_len;
                                    char *filedata_val;
                                 } filedata;
.DE
.B Voids:
In a void declaration, the variable is  not named.  The declaration is
just \*Qvoid\*U and nothing else.  Void declarations can only occur in two
places: union definitions and program definitions (as the  argument or
result of a remote procedure).