[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Communications Programming Concepts

RPC Language

The Remote Procedure Call Language (RPCL) is identical to the eXternal Data Representation (XDR) language, except for the added program definition.

RPC Language Descriptions

Because XDR data types are described in a formal language, procedures that operate on these data types must be described in a formal language. The RPCL, an extension to the XDR language, is used for this purpose.

RPC uses RPCL as the input language for its protocol and routines. RPCL specifies data types used by RPC and generates XDR routines that standardize representation of the types. To implement service protocols and routines, RPCL uses the rpcgen command to compile input in corresponding C language code.

RPC language descriptions include:

See "RPC Language ping Program Example" for more information. Also, see "Exceptions to the RPCL Rules" for instances where these rules do not apply.


An RPCL file consists of a series of definitions in the following format:

      definition ";"
      definition ";" definition-list

RPCL recognizes the following six types of definitions:



The C language structures are usually located in header files in either the /usr/include or /usr/include/sys directory, but they can be located in any directory in the file system. An XDR structure is declared almost exactly like its C language counterpart; for example:

      "struct" struct-ident "{"

      declaration ";"
      declaration ";" declaration-list

Compare the following XDR structure to a two-dimensional coordinate with the C structure that it is compiled into in the output header file.

struct coord {          struct coord {
      int x;      -->          int x;
      int y;                   int y;

};                      };
                        typedef struct coord coord;

Here, the output is identical to the input, except for the added typedef at the end of the output. As a result, the programmer can use coord instead of struct coord when declaring items.


XDR unions are discriminated unions and look different from C unions. XDR unions are more analogous to Pascal variant records than to C unions. Following is an XDR union definition:

      "union" union-ident "switch" "(" declaration ")" "{"

      "case" value ":" declaration ";"
      "default" ":" declaration ";"
      "case" value ":" declaration ";" case-list

Following is an example of a type that might be returned as the result of a read data operation. If there is no error, the type returns a block of data; otherwise, it returns nothing.

union read_result switch (int errno) {
case 0
     opaque data[1024];

The type is compiled into the following structure:

struct read_result {
     int errno;
     union {
          char data[1024];
typedef struct read_result read_result;

Note: The union component of this output structure is identical to the type, except for the trailing _u.


XDR enumerations have the same syntax as C enumerations.

      "enum" enum-ident "{"

      enum-value "," enum-value-list

      enum-value-ident "=" value

Compare the following example of an XDR enumeration with the C enumeration it is compiled into.

enum colortype {       enum colortype {
     RED = 0,               RED = 0,
     GREEN = 1,    -->      GREEN = 1,
     BLUE = 2               BLUE = 2,
};                     };
                       typedef enum colortype colortype;

Type Definitions

XDR type definitions (typedefs) have the same syntax as C typedefs.

      "typedef" declaration

The following example defines an fname_type used for declaring file-name strings with a maximum length of 255 characters.

typedef string fname_type<255>; --> typedef char *fname_type;


XDR constants can be used wherever an integer constant is required. The definition for a constant is:

      "const" const-ident "=" integer

For example, the following defines a constant DOZEN equal to 12.

const DOZEN = 12; --> #define DOZEN 12


RPC programs are declared using the following syntax:

      "program" program-ident "{"
      "}" "=" value

      version ";"
      version ";" version-list

      "version" version-ident "{"
      "}" "=" value

      procedure ";"
      procedure ";" procedure-list

      type-ident procedure-ident "(" type-ident ")" "=" value

The time protocol is defined as follows:

 * time.x: Get or set the time. Time is represented as number
 * of seconds since 0:00, January 1, 1970.
program TIMEPROG {
     version TIMEVERS {
          unsigned int TIMEGET (void) = 1;
          void TIMESET (unsigned) = 2;
     } = 1;
} = 44;

This file compiles into the following #define statements in the output header file:

#define TIMEPROG 44

#define TIMEVERS 1

#define TIMEGET 1

#define TIMESET 2


XDR includes four types of declarations: simple declarations, fixed-length array declarations, variable-length array declarations, and pointer declarations. These declarations have the following forms:


Simple Declarations

Simple XDR declarations are like simple C declarations, as follows:

      type-ident variable-ident

An example of a simple declaration is:

colortype color;  -->  colortype color;

Fixed-length Array Declarations

Fixed-length array declarations are like C array declarations, as follows:

      type-ident variable-ident "[" value "]"

An example of a fixed-length array declaration is:

colortype palette[8];  -->  colortype palette[8]

Variable-length Array Declarations

Variable-length array declarations have no explicit syntax in C, so XDR invents its own syntax using angle brackets. The maximum size is specified between the angle brackets. A specific size can be omitted to indicate that the array may be of any size.

      type-ident variable-ident "<" value ">"
      type-ident variable-ident "<" ">"

An example of a set of variable-length array declarations is:

int heights<12>;          /* at most 12 items     */
int widths<>;             /* any number of items  */

Note: The maximum size is specified between the angle brackets. The number, but not the angle brackets, may be omitted to indicate that the array can be of any size.

Because variable-length arrays have no explicit syntax in C, these declarations are actually compiled into structure definitions, signified by struct. For example, the heights declaration is compiled into the following structure:

struct {
     u_int heights_len;   /* # of items in array */
     int *heights_val;    /* # pointer to array */
} heights;

Pointer Declarations

Pointer declarations are made in XDR exactly as they are in C. The programmer cannot send pointers over a network, but can use XDR pointers for sending recursive data types such as lists and trees. In XDR language, the type is called optional-data, instead of pointer. Pointer declarations have the following form in XDR language:

      type-ident "*" variable-ident

An example of a pointer declaration is:

listitem *next;  -->  listitem *next;

RPCL Syntax Requirements for Program Definition

The RPCL has the following syntax requirements:

Exceptions to the RPCL Rules

Exceptions to the RPC language rules include Booleans, strings, opaque data, and voids.


The C language has no built-in Boolean type. However, the RPC library uses a Boolean type called bool_t, which is either True or False. Objects that are declared as type bool in XDR language are compiled into bool_t in the output header file; for example:

bool married;  -->  bool_t married;


The C language has no built-in string type. Instead, it uses the null-terminated char * convention. In XDR language, strings are declared using the string keyword, and then compiled into char * 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 null character). The maximum size may be left off, indicating a string of arbitrary length.

Compare the following examples:

string name<32>;  -->  char *name;

string longname<>;  -->  char *longname;

Opaque Data

Opaque data is used in RPC and XDR to describe untyped data, which consists of sequences of arbitrary bytes. Opaque data may be declared either as a fixed-length or variable-length array, as in the following examples:

opaque diskblock[512];  -->  char diskblock[512];

opaque filedata<1024>;  -->  struct {
                                 u_int filedata_len;
                                 char *filedata_val;
                              } filedata


In a void declaration, the variable is not named. The declaration is void. Void declarations can occur as the argument or result of a remote procedure in only two places: union definitions and program definitions.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]