xdr.nts.ms

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

and their corresponding external representations.
Primitives cover the set of numbers in:
.DS
.ft CW
[signed, unsigned] * [short, int, long]
.DE
.ne 2i
Specifically, the eight primitives are:
.DS
.ft CW
bool_t xdr_char(xdrs, cp)
	XDR *xdrs;
	char *cp;
.sp.5
bool_t xdr_u_char(xdrs, ucp)
	XDR *xdrs;
	unsigned char *ucp;
.sp.5
bool_t xdr_int(xdrs, ip)
	XDR *xdrs;
	int *ip;
.sp.5
bool_t xdr_u_int(xdrs, up)
	XDR *xdrs;
	unsigned *up;
.sp.5
bool_t xdr_long(xdrs, lip)
	XDR *xdrs;
	long *lip;
.sp.5
bool_t xdr_u_long(xdrs, lup)
	XDR *xdrs;
	u_long *lup;
.sp.5
bool_t xdr_short(xdrs, sip)
	XDR *xdrs;
	short *sip;
.sp.5
bool_t xdr_u_short(xdrs, sup)
	XDR *xdrs;
	u_short *sup;
.DE
The first parameter,
.I xdrs ,
is an XDR stream handle.
The second parameter is the address of the number
that provides data to the stream or receives data from it.
All routines return
.I TRUE 
if they complete successfully, and
.I FALSE 
otherwise.
.NH 2
\&Floating Point Filters
.IX "XDR library" "floating point filters"
.LP
The XDR library also provides primitive routines
for C's floating point types:
.DS
.ft CW
bool_t xdr_float(xdrs, fp)
	XDR *xdrs;
	float *fp;
.sp.5
bool_t xdr_double(xdrs, dp)
	XDR *xdrs;
	double *dp;
.DE
The first parameter,
.I xdrs 
is an XDR stream handle.
The second parameter is the address
of the floating point number that provides data to the stream
or receives data from it.
Both routines return
.I TRUE 
if they complete successfully, and
.I FALSE 
otherwise.
.LP
Note: Since the numbers are represented in IEEE floating point,
routines may fail when decoding a valid IEEE representation
into a machine-specific representation, or vice-versa.
.NH 2
\&Enumeration Filters
.IX "XDR library" "enumeration filters"
.LP
The XDR library provides a primitive for generic enumerations.
The primitive assumes that a C
.I enum 
has the same representation inside the machine as a C integer.
The boolean type is an important instance of the
.I enum .
The external representation of a boolean is always
.I TRUE 
(1) or 
.I FALSE 
(0).
.DS
.ft CW
#define bool_t	int
#define FALSE	0
#define TRUE	1
.sp.5
#define enum_t int
.sp.5
bool_t xdr_enum(xdrs, ep)
	XDR *xdrs;
	enum_t *ep;
.sp.5
bool_t xdr_bool(xdrs, bp)
	XDR *xdrs;
	bool_t *bp;
.DE
The second parameters
.I ep
and
.I bp
are addresses of the associated type that provides data to, or 
receives data from, the stream
.I xdrs .
.NH 2
\&No Data
.IX "XDR library" "no data"
.LP
Occasionally, an XDR routine must be supplied to the RPC system,
even when no data is passed or required.
The library provides such a routine:
.DS
.ft CW
bool_t xdr_void();  /* \fIalways returns TRUE\fP */
.DE
.NH 2
\&Constructed Data Type Filters
.IX "XDR library" "constructed data type filters"
.LP
Constructed or compound data type primitives
require more parameters and perform more complicated functions
then the primitives discussed above.
This section includes primitives for
strings, arrays, unions, and pointers to structures.
.LP
Constructed data type primitives may use memory management.
In many cases, memory is allocated when deserializing data with
.I XDR_DECODE
Therefore, the XDR package must provide means to deallocate memory.
This is done by an XDR operation,
.I XDR_FREE
To review, the three XDR directional operations are
.I XDR_ENCODE ,
.I XDR_DECODE
and
.I XDR_FREE .
.NH 3
\&Strings
.IX "XDR library" "strings"
.LP
In C, a string is defined as a sequence of bytes
terminated by a null byte,
which is not considered when calculating string length.
However, when a string is passed or manipulated,
a pointer to it is employed.
Therefore, the XDR library defines a string to be a
.I "char *"
and not a sequence of characters.
The external representation of a string is drastically different
from its internal representation.
Externally, strings are represented as
sequences of ASCII characters,
while internally, they are represented with character pointers.
Conversion between the two representations
is accomplished with the routine
.I xdr_string ():
.IX xdr_string() "" \fIxdr_string()\fP
.DS
.ft CW
bool_t xdr_string(xdrs, sp, maxlength)
	XDR *xdrs;
	char **sp;
	u_int maxlength;
.DE
The first parameter
.I xdrs 
is the XDR stream handle.
The second parameter
.I sp 
is a pointer to a string (type
.I "char **" .
The third parameter
.I maxlength 
specifies the maximum number of bytes allowed during encoding or decoding.
its value is usually specified by a protocol.  For example, a protocol
specification may say that a file name may be no longer than 255 characters.
.LP
The routine returns
.I FALSE 
if the number of characters exceeds
.I maxlength ,
and
.I TRUE 
if it doesn't.
.SH
Keep
.I maxlength 
small.  If it is too big you can blow the heap, since
.I xdr_string() 
will call
.I malloc() 
for space.
.LP
The behavior of
.I xdr_string() 
.IX xdr_string() "" \fIxdr_string()\fP
is similar to the behavior of other routines
discussed in this section.  The direction
.I XDR_ENCODE 
is easiest to understand.  The parameter
.I sp 
points to a string of a certain length;
if the string does not exceed
.I maxlength ,
the bytes are serialized.
.LP
The effect of deserializing a string is subtle.
First the length of the incoming string is determined;
it must not exceed
.I maxlength .
Next
.I sp 
is dereferenced; if the the value is
.I NULL ,
then a string of the appropriate length is allocated and
.I *sp 
is set to this string.
If the original value of
.I *sp 
is non-null, then the XDR package assumes
that a target area has been allocated,
which can hold strings no longer than
.I maxlength .
In either case, the string is decoded into the target area.
The routine then appends a null character to the string.
.LP
In the
.I XDR_FREE 
operation, the string is obtained by dereferencing
.I sp .
If the string is not
.I NULL ,
it is freed and
.I *sp 
is set to
.I NULL .
In this operation,
.I xdr_string() 
ignores the
.I maxlength 
parameter.
.NH 3
\&Byte Arrays
.IX "XDR library" "byte arrays"
.LP
Often variable-length arrays of bytes are preferable to strings.
Byte arrays differ from strings in the following three ways: 
1) the length of the array (the byte count) is explicitly
located in an unsigned integer,
2) the byte sequence is not terminated by a null character, and
3) the external representation of the bytes is the same as their
internal representation.
The primitive
.I xdr_bytes() 
.IX xdr_bytes() "" \fIxdr_bytes()\fP
converts between the internal and external
representations of byte arrays:
.DS
.ft CW
bool_t xdr_bytes(xdrs, bpp, lp, maxlength)
    XDR *xdrs;
    char **bpp;
    u_int *lp;
    u_int maxlength;
.DE
The usage of the first, second and fourth parameters
are identical to the first, second and third parameters of
.I xdr_string (),
respectively.
The length of the byte area is obtained by dereferencing
.I lp 
when serializing;
.I *lp 
is set to the byte length when deserializing.
.NH 3
\&Arrays
.IX "XDR library" "arrays"
.LP
The XDR library package provides a primitive
for handling arrays of arbitrary elements.
The
.I xdr_bytes() 
routine treats a subset of generic arrays,
in which the size of array elements is known to be 1,
and the external description of each element is built-in.
The generic array primitive,
.I xdr_array() ,
.IX xdr_array() "" \fIxdr_array()\fP
requires parameters identical to those of
.I xdr_bytes() 
plus two more:
the size of array elements,
and an XDR routine to handle each of the elements.
This routine is called to encode or decode
each element of the array.
.DS
.ft CW
bool_t
xdr_array(xdrs, ap, lp, maxlength, elementsiz, xdr_element)
    XDR *xdrs;
    char **ap;
    u_int *lp;
    u_int maxlength;
    u_int elementsiz;
    bool_t (*xdr_element)();
.DE
The parameter
.I ap 
is the address of the pointer to the array.
If
.I *ap 
is
.I NULL 
when the array is being deserialized,
XDR allocates an array of the appropriate size and sets
.I *ap 
to that array.
The element count of the array is obtained from
.I *lp 
when the array is serialized;
.I *lp 
is set to the array length when the array is deserialized. 
The parameter
.I maxlength 
is the maximum number of elements that the array is allowed to have;
.I elementsiz
is the byte size of each element of the array
(the C function
.I sizeof()
can be used to obtain this value).
The
.I xdr_element() 
.IX xdr_element() "" \fIxdr_element()\fP
routine is called to serialize, deserialize, or free
each element of the array.
.br
.LP
Before defining more constructed data types, it is appropriate to 
present three examples.
.LP
.I "Example A:"
.br
A user on a networked machine can be identified by 
(a) the machine name, such as
.I krypton :
see the
.I gethostname 
man page; (b) the user's UID: see the
.I geteuid 
man page; and (c) the group numbers to which the user belongs: 
see the
.I getgroups 
man page.  A structure with this information and its associated 
XDR routine could be coded like this:
.ie t .DS
.el .DS L
.ft CW
struct netuser {
    char    *nu_machinename;
    int     nu_uid;
    u_int   nu_glen;
    int     *nu_gids;
};
#define NLEN 255    /* \fImachine names < 256 chars\fP */
#define NGRPS 20    /* \fIuser can't be in > 20 groups\fP */
.sp.5
bool_t
xdr_netuser(xdrs, nup)
    XDR *xdrs;
    struct netuser *nup;
{
    return(xdr_string(xdrs, &nup->nu_machinename, NLEN) &&
        xdr_int(xdrs, &nup->nu_uid) &&
        xdr_array(xdrs, &nup->nu_gids, &nup->nu_glen, 
        NGRPS, sizeof (int), xdr_int));
}
.DE
.LP
.I "Example B:"
.br
A party of network users could be implemented
as an array of
.I netuser
structure.
The declaration and its associated XDR routines
are as follows:
.ie t .DS
.el .DS L
.ft CW
struct party {
    u_int p_len;
    struct netuser *p_nusers;
};
#define PLEN 500    /* \fImax number of users in a party\fP */
.sp.5
bool_t
xdr_party(xdrs, pp)
    XDR *xdrs;
    struct party *pp;
{
    return(xdr_array(xdrs, &pp->p_nusers, &pp->p_len, PLEN,
        sizeof (struct netuser), xdr_netuser));
}
.DE
.LP
.I "Example C:"
.br
The well-known parameters to
.I main ,
.I argc
and
.I argv
can be combined into a structure.
An array of these structures can make up a history of commands.
The declarations and XDR routines might look like:
.ie t .DS
.el .DS L
.ft CW
struct cmd {
    u_int c_argc;
    char **c_argv;
};
#define ALEN 1000   /* \fIargs cannot be > 1000 chars\fP */
#define NARGC 100   /* \fIcommands cannot have > 100 args\fP */

struct history {
    u_int h_len;
    struct cmd *h_cmds;
};
#define NCMDS 75    /* \fIhistory is no more than 75 commands\fP */

bool_t
xdr_wrap_string(xdrs, sp)
    XDR *xdrs;
    char **sp;
{
    return(xdr_string(xdrs, sp, ALEN));
}
.DE
.ie t .DS
.el .DS L
.ft CW
bool_t
xdr_cmd(xdrs, cp)
    XDR *xdrs;
    struct cmd *cp;
{
    return(xdr_array(xdrs, &cp->c_argv, &cp->c_argc, NARGC,
        sizeof (char *), xdr_wrap_string));
}
.DE
.ie t .DS
.el .DS L
.ft CW
bool_t
xdr_history(xdrs, hp)
    XDR *xdrs;
    struct history *hp;
{
    return(xdr_array(xdrs, &hp->h_cmds, &hp->h_len, NCMDS,
        sizeof (struct cmd), xdr_cmd));
}
.DE
The most confusing part of this example is that the routine
.I xdr_wrap_string() 
is needed to package the
.I xdr_string() 
routine, because the implementation of
.I xdr_array() 
only passes two parameters to the array element description routine;
.I xdr_wrap_string() 
supplies the third parameter to
.I xdr_string ().
.LP
By now the recursive nature of the XDR library should be obvious.