xdr.rfc.ms

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

The constant m would normally be found in a protocol specification.
For example, a filing protocol may state that the maximum data
transfer size is 8192 bytes, as follows:
.DS
.ft CW
opaque filedata<8192>;
.DE
This can be illustrated as follows:
.ie t .DS
.el .DS L
\fIVariable-Length Opaque\fP

\f(CW0     1     2     3     4     5   ...
+-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+
|        length n       |byte0|byte1|...| n-1 |  0  |...|  0  |
+-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+
|<-------4 bytes------->|<------n bytes------>|<---r bytes--->|
|<----n+r (where (n+r) mod 4 = 0)---->|\fP
.DE
.LP
It   is  an error  to  encode  a  length  greater  than the maximum
described in the specification.
.NH 2
\&String
.IX XDR string
.LP
The standard defines a string of n (numbered 0 through n-1) ASCII
bytes to be the number n encoded as an unsigned integer (as described
above), and followed by the n bytes of the string.  Byte m of the
string always precedes byte m+1 of the string, and byte 0 of the
string always follows the string's length.  If n is not a multiple of
four, then the n bytes are followed by enough (0 to 3) residual zero
bytes, r, to make the total byte count a multiple of four.  Counted
byte strings are declared as follows:
.DS
.ft CW
string object<m>;
.DE
or
.DS
.ft CW
string object<>;
.DE
The constant m denotes an upper bound of the number of bytes that a
string may contain.  If m is not specified, as in the second
declaration, it is assumed to be (2**32) - 1, the maximum length.
The constant m would normally be found in a protocol specification.
For example, a filing protocol may state that a file name can be no
longer than 255 bytes, as follows:
.DS
.ft CW
string filename<255>;
.DE
Which can be illustrated as:
.ie t .DS
.el .DS L
\fIA String\fP

\f(CW0     1     2     3     4     5   ...
+-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+
|        length n       |byte0|byte1|...| n-1 |  0  |...|  0  |
+-----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+
|<-------4 bytes------->|<------n bytes------>|<---r bytes--->|
|<----n+r (where (n+r) mod 4 = 0)---->|\fP
.DE
.LP
It   is an  error  to  encode  a length greater  than   the maximum
described in the specification.
.NH 2
\&Fixed-length Array
.IX XDR "fixed-length array"
.IX XDR "array, fixed length"
.LP
Declarations for fixed-length arrays of homogeneous elements are in
the following form:
.DS
.ft CW
type-name identifier[n];
.DE
Fixed-length arrays of elements numbered 0 through n-1 are encoded by
individually encoding the elements of the array in their natural
order, 0 through n-1.  Each element's size is a multiple of four
bytes. Though all elements are of the same type, the elements may
have different sizes.  For example, in a fixed-length array of
strings, all elements are of type "string", yet each element will
vary in its length.
.ie t .DS
.el .DS L
\fIFixed-Length Array\fP

\f(CW+---+---+---+---+---+---+---+---+...+---+---+---+---+
|   element 0   |   element 1   |...|  element n-1  |
+---+---+---+---+---+---+---+---+...+---+---+---+---+
|<--------------------n elements------------------->|\fP
.DE
.NH 2
\&Variable-length Array
.IX XDR "variable-length array"
.IX XDR "array, variable length"
.LP
Counted arrays provide the ability to encode variable-length arrays
of homogeneous elements.  The array is encoded as the element count n
(an unsigned integer) followed by the encoding of each of the array's
elements, starting with element 0 and progressing through element n-
1.  The declaration for variable-length arrays follows this form:
.DS
.ft CW
type-name identifier<m>;
.DE
or
.DS
.ft CW
type-name identifier<>;
.DE
The constant m specifies the maximum acceptable element count of an
array; if  m is not specified, as  in the second declaration, it is
assumed to be (2**32) - 1.
.ie t .DS
.el .DS L
\fICounted Array\fP

\f(CW0  1  2  3
+--+--+--+--+--+--+--+--+--+--+--+--+...+--+--+--+--+
|     n     | element 0 | element 1 |...|element n-1|
+--+--+--+--+--+--+--+--+--+--+--+--+...+--+--+--+--+
|<-4 bytes->|<--------------n elements------------->|\fP
.DE
It is  an error to  encode  a  value of n that  is greater than the
maximum described in the specification.
.NH 2
\&Structure
.IX XDR structure
.LP
Structures are declared as follows:
.DS
.ft CW
struct {
	component-declaration-A;
	component-declaration-B;
	\&...
} identifier;
.DE
The components of the structure are encoded in the order of their
declaration in the structure.  Each component's size is a multiple of
four bytes, though the components may be different sizes.
.ie t .DS
.el .DS L
\fIStructure\fP

\f(CW+-------------+-------------+...
| component A | component B |...
+-------------+-------------+...\fP
.DE
.NH 2
\&Discriminated Union
.IX XDR "discriminated union"
.IX XDR union discriminated
.LP
A discriminated union is a type composed of a discriminant followed
by a type selected from a set of prearranged types according to the
value of the discriminant.  The type of discriminant is either "int",
"unsigned int", or an enumerated type, such as "bool".  The component
types are called "arms" of the union, and are preceded by the value
of the discriminant which implies their encoding.  Discriminated
unions are declared as follows:
.DS
.ft CW
union switch (discriminant-declaration) {
	case discriminant-value-A:
	arm-declaration-A;
	case discriminant-value-B:
	arm-declaration-B;
	\&...
	default: default-declaration;
} identifier;
.DE
Each "case" keyword is followed by a legal value of the discriminant.
The default arm is optional.  If it is not specified, then a valid
encoding of the union cannot take on unspecified discriminant values.
The size of the implied arm is always a multiple of four bytes.
.LP
The discriminated union is encoded as its discriminant followed by
the encoding of the implied arm.
.ie t .DS
.el .DS L
\fIDiscriminated Union\fP

\f(CW0   1   2   3
+---+---+---+---+---+---+---+---+
|  discriminant |  implied arm  |
+---+---+---+---+---+---+---+---+
|<---4 bytes--->|\fP
.DE
.NH 2
\&Void
.IX XDR void
.LP
An XDR void is a 0-byte quantity.  Voids are useful for describing
operations that take no data as input or no data as output. They are
also useful in unions, where some arms may contain data and others do
not.  The declaration is simply as follows:
.DS
.ft CW
void;
.DE
Voids are illustrated as follows:
.ie t .DS
.el .DS L
\fIVoid\fP

\f(CW  ++
  ||
  ++
--><-- 0 bytes\fP
.DE
.NH 2
\&Constant
.IX XDR constant
.LP
The data declaration for a constant follows this form:
.DS
.ft CW
const name-identifier = n;
.DE
"const" is used to define a symbolic name for a constant; it does not
declare any data.  The symbolic constant may be used anywhere a
regular constant may be used.  For example, the following defines a
symbolic constant DOZEN, equal to 12.
.DS
.ft CW
const DOZEN = 12;
.DE
.NH 2
\&Typedef
.IX XDR typedef
.LP
"typedef" does not declare any data either, but serves to define new
identifiers for declaring data. The syntax is:
.DS
.ft CW
typedef declaration;
.DE
The new type name is actually the variable name in the declaration
part of the typedef.  For example, the following defines a new type
called "eggbox" using an existing type called "egg":
.DS
.ft CW
typedef egg eggbox[DOZEN];
.DE
Variables declared using the new type name have the same type as the
new type name would have in the typedef, if it was considered a
variable.  For example, the following two declarations are equivalent
in declaring the variable "fresheggs":
.DS
.ft CW
eggbox  fresheggs;
egg     fresheggs[DOZEN];
.DE
When a typedef involves a struct, enum, or union definition, there is
another (preferred) syntax that may be used to define the same type.
In general, a typedef of the following form:
.DS
.ft CW
typedef <<struct, union, or enum definition>> identifier;
.DE
may be converted to the alternative form by removing the "typedef"
part and placing the identifier after the "struct", "union", or
"enum" keyword, instead of at the end.  For example, here are the two
ways to define the type "bool":
.DS
.ft CW
typedef enum {    /* \fIusing typedef\fP */
	FALSE = 0,
	TRUE = 1
	} bool;

enum bool {       /* \fIpreferred alternative\fP */
	FALSE = 0,
	TRUE = 1
	};
.DE
The reason this syntax is preferred is one does not have to wait
until the end of a declaration to figure out the name of the new
type.
.NH 2
\&Optional-data
.IX XDR "optional data"
.IX XDR "data, optional"
.LP
Optional-data is one kind of union that occurs so frequently that we
give it a special syntax of its own for declaring it.  It is declared
as follows:
.DS
.ft CW
type-name *identifier;
.DE
This is equivalent to the following union:
.DS
.ft CW
union switch (bool opted) {
	case TRUE:
	type-name element;
	case FALSE:
	void;
} identifier;
.DE
It is also equivalent to the following variable-length array
declaration, since the boolean "opted" can be interpreted as the
length of the array:
.DS
.ft CW
type-name identifier<1>;
.DE
Optional-data is not so interesting in itself, but it is very useful
for describing recursive data-structures such as linked-lists and
trees.  For example, the following defines a type "stringlist" that
encodes lists of arbitrary length strings:
.DS
.ft CW
struct *stringlist {
	string item<>;
	stringlist next;
};
.DE
It could have been equivalently declared as the following union:
.DS
.ft CW
union stringlist switch (bool opted) {
	case TRUE:
		struct {
			string item<>;
			stringlist next;
		} element;
	case FALSE:
		void;
};
.DE
or as a variable-length array:
.DS
.ft CW
struct stringlist<1> {
	string item<>;
	stringlist next;
};
.DE
Both of these declarations obscure the intention of the stringlist
type, so the optional-data declaration is preferred over both of
them.  The optional-data type also has a close correlation to how
recursive data structures are represented in high-level languages
such as Pascal or C by use of pointers. In fact, the syntax is the
same as that of the C language for pointers.
.NH 2
\&Areas for Future Enhancement