xdr.nts.ms

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

Let's continue with more constructed data types.
.NH 3
\&Opaque Data
.IX "XDR library" "opaque data"
.LP
In some protocols, handles are passed from a server to client.
The client passes the handle back to the server at some later time.
Handles are never inspected by clients;
they are obtained and submitted.
That is to say, handles are opaque.
The
.I xdr_opaque() 
.IX xdr_opaque() "" \fIxdr_opaque()\fP
primitive is used for describing fixed sized, opaque bytes.
.DS
.ft CW
bool_t xdr_opaque(xdrs, p, len)
    XDR *xdrs;
    char *p;
    u_int len;
.DE
The parameter
.I p 
is the location of the bytes;
.I len
is the number of bytes in the opaque object.
By definition, the actual data
contained in the opaque object are not machine portable.
.NH 3
\&Fixed Sized Arrays
.IX "XDR library" "fixed sized arrays"
.LP
The XDR library provides a primitive,
.I xdr_vector (),
for fixed-length arrays.
.ie t .DS
.el .DS L
.ft CW
#define NLEN 255    /* \fImachine names must be < 256 chars\fP */
#define NGRPS 20    /* \fIuser belongs to exactly 20 groups\fP */
.sp.5
struct netuser {
    char *nu_machinename;
    int nu_uid;
    int nu_gids[NGRPS];
};
.sp.5
bool_t
xdr_netuser(xdrs, nup)
    XDR *xdrs;
    struct netuser *nup;
{
    int i;
.sp.5
    if (!xdr_string(xdrs, &nup->nu_machinename, NLEN))
        return(FALSE);
    if (!xdr_int(xdrs, &nup->nu_uid))
        return(FALSE);
    if (!xdr_vector(xdrs, nup->nu_gids, NGRPS, sizeof(int), 
        xdr_int)) {
            return(FALSE);
    }
    return(TRUE);
}
.DE
.NH 3
\&Discriminated Unions
.IX "XDR library" "discriminated unions"
.LP
The XDR library supports discriminated unions.
A discriminated union is a C union and an
.I enum_t
value that selects an \*Qarm\*U of the union.
.DS
.ft CW
struct xdr_discrim {
    enum_t value;
    bool_t (*proc)();
};
.sp.5
bool_t xdr_union(xdrs, dscmp, unp, arms, defaultarm)
    XDR *xdrs;
    enum_t *dscmp;
    char *unp;
    struct xdr_discrim *arms;
    bool_t (*defaultarm)();  /* \fImay equal NULL\fP */
.DE
First the routine translates the discriminant of the union located at 
.I *dscmp .
The discriminant is always an
.I enum_t .
Next the union located at
.I *unp 
is translated.
The parameter
.I arms
is a pointer to an array of
.I xdr_discrim
structures. 
Each structure contains an ordered pair of
.I [value,proc] .
If the union's discriminant is equal to the associated
.I value ,
then the
.I proc
is called to translate the union.
The end of the
.I xdr_discrim
structure array is denoted by a routine of value
.I NULL 
(0).  If the discriminant is not found in the
.I arms
array, then the
.I defaultarm
procedure is called if it is non-null;
otherwise the routine returns
.I FALSE .
.LP
.I "Example D:"
Suppose the type of a union may be integer,
character pointer (a string), or a
.I gnumbers 
structure.
Also, assume the union and its current type
are declared in a structure.
The declaration is:
.ie t .DS
.el .DS L
.ft CW
enum utype { INTEGER=1, STRING=2, GNUMBERS=3 };
.sp.5
struct u_tag {
    enum utype utype;   /* \fIthe union's discriminant\fP */
    union {
        int ival;
        char *pval;
        struct gnumbers gn;
    } uval;
};
.DE
The following constructs and XDR procedure (de)serialize
the discriminated union:
.ie t .DS
.el .DS L
.ft CW
struct xdr_discrim u_tag_arms[4] = {
    { INTEGER, xdr_int },
    { GNUMBERS, xdr_gnumbers }
    { STRING, xdr_wrap_string },
    { __dontcare__, NULL }
    /* \fIalways terminate arms with a NULL xdr_proc\fP */
}
.sp.5
bool_t
xdr_u_tag(xdrs, utp)
    XDR *xdrs;
    struct u_tag *utp;
{
    return(xdr_union(xdrs, &utp->utype, &utp->uval,
        u_tag_arms, NULL));
}
.DE
The routine
.I xdr_gnumbers() 
was presented above in 
.I "The XDR Library"
section.
.I xdr_wrap_string() 
was presented in example C.
The default 
.I arm 
parameter to
.I xdr_union() 
(the last parameter) is
.I NULL 
in this example.  Therefore the value of the union's discriminant
may legally take on only values listed in the
.I u_tag_arms 
array.  This example also demonstrates that
the elements of the arm's array do not need to be sorted.
.LP
It is worth pointing out that the values of the discriminant
may be sparse, though in this example they are not.
It is always good
practice to assign explicitly integer values to each element of the
discriminant's type.
This practice both documents the external
representation of the discriminant and guarantees that different
C compilers emit identical discriminant values.
.LP
Exercise: Implement
.I xdr_union() 
using the other primitives in this section.
.NH 3
\&Pointers
.IX "XDR library" "pointers"
.LP
In C it is often convenient to put pointers
to another structure within a structure.
The
.I xdr_reference() 
.IX xdr_reference() "" \fIxdr_reference()\fP
primitive makes it easy to serialize, deserialize, and free
these referenced structures.
.DS
.ft CW
bool_t xdr_reference(xdrs, pp, size, proc)
    XDR *xdrs;
    char **pp;
    u_int ssize;
    bool_t (*proc)();
.DE
.LP
Parameter
.I pp 
is the address of
the pointer to the structure;
parameter
.I ssize
is the size in bytes of the structure (use the C function
.I sizeof() 
to obtain this value); and
.I proc
is the XDR routine that describes the structure.
When decoding data, storage is allocated if
.I *pp 
is
.I NULL .
.LP
There is no need for a primitive
.I xdr_struct() 
to describe structures within structures,
because pointers are always sufficient.
.LP
Exercise: Implement
.I xdr_reference() 
using
.I xdr_array ().
Warning:
.I xdr_reference() 
and
.I xdr_array() 
are NOT interchangeable external representations of data.
.LP
.I "Example E:"
Suppose there is a structure containing a person's name
and a pointer to a
.I gnumbers 
structure containing the person's gross assets and liabilities.
The construct is:
.DS
.ft CW
struct pgn {
    char *name;
    struct gnumbers *gnp;
};
.DE
The corresponding XDR routine for this structure is:
.DS
.ft CW
bool_t
xdr_pgn(xdrs, pp)
    XDR *xdrs;
    struct pgn *pp;
{
    if (xdr_string(xdrs, &pp->name, NLEN) &&
      xdr_reference(xdrs, &pp->gnp,
      sizeof(struct gnumbers), xdr_gnumbers))
        return(TRUE);
    return(FALSE);
}
.DE
.IX "pointer semantics and XDR"
.I "Pointer Semantics and XDR" 
.LP
In many applications, C programmers attach double meaning to 
the values of a pointer.  Typically the value
.I NULL 
(or zero) means data is not needed,
yet some application-specific interpretation applies.
In essence, the C programmer is encoding
a discriminated union efficiently
by overloading the interpretation of the value of a pointer.
For instance, in example E a
.I NULL 
pointer value for
.I gnp
could indicate that
the person's assets and liabilities are unknown.
That is, the pointer value encodes two things:
whether or not the data is known;
and if it is known, where it is located in memory.
Linked lists are an extreme example of the use
of application-specific pointer interpretation.
.LP
The primitive
.I xdr_reference() 
.IX xdr_reference() "" \fIxdr_reference()\fP
cannot and does not attach any special
meaning to a null-value pointer during serialization.
That is, passing an address of a pointer whose value is
.I NULL 
to
.I xdr_reference() 
when serialing data will most likely cause a memory fault and, on the UNIX
system, a core dump.
.LP
.I xdr_pointer() 
correctly handles 
.I NULL 
pointers.  For more information about its use, see 
the
.I "Linked Lists"
topics below.
.LP
.I Exercise:
After reading the section on
.I "Linked Lists" ,
return here and extend example E so that
it can correctly deal with 
.I NULL 
pointer values.
.LP
.I Exercise:
Using the
.I xdr_union (),
.I xdr_reference() 
and
.I xdr_void() 
primitives, implement a generic pointer handling primitive
that implicitly deals with
.I NULL 
pointers.  That is, implement
.I xdr_pointer ().
.NH 2
\&Non-filter Primitives
.IX "XDR" "non-filter primitives"
.LP
XDR streams can be manipulated with
the primitives discussed in this section.
.DS
.ft CW
u_int xdr_getpos(xdrs)
    XDR *xdrs;
.sp.5
bool_t xdr_setpos(xdrs, pos)
    XDR *xdrs;
    u_int pos;
.sp.5
xdr_destroy(xdrs)
    XDR *xdrs;
.DE
The routine
.I xdr_getpos() 
.IX xdr_getpos() "" \fIxdr_getpos()\fP
returns an unsigned integer
that describes the current position in the data stream.
Warning: In some XDR streams, the returned value of
.I xdr_getpos() 
is meaningless;
the routine returns a \-1 in this case
(though \-1 should be a legitimate value).
.LP
The routine
.I xdr_setpos() 
.IX xdr_setpos() "" \fIxdr_setpos()\fP
sets a stream position to
.I pos .
Warning: In some XDR streams, setting a position is impossible;
in such cases,
.I xdr_setpos() 
will return
.I FALSE .
This routine will also fail if the requested position is out-of-bounds.
The definition of bounds varies from stream to stream.
.LP
The
.I xdr_destroy() 
.IX xdr_destroy() "" \fIxdr_destroy()\fP
primitive destroys the XDR stream.
Usage of the stream
after calling this routine is undefined.
.NH 2
\&XDR Operation Directions
.IX XDR "operation directions"
.IX "direction of XDR operations"
.LP
At times you may wish to optimize XDR routines by taking
advantage of the direction of the operation \(em
.I XDR_ENCODE
.I XDR_DECODE
or
.I XDR_FREE
The value
.I xdrs->x_op
always contains the direction of the XDR operation.
Programmers are not encouraged to take advantage of this information.
Therefore, no example is presented here.  However, an example in the
.I "Linked Lists"
topic below, demonstrates the usefulness of the
.I xdrs->x_op
field.
.NH 2
\&XDR Stream Access
.IX "XDR" "stream access"
.LP
An XDR stream is obtained by calling the appropriate creation routine.
These creation routines take arguments that are tailored to the
specific properties of the stream.
.LP
Streams currently exist for (de)serialization of data to or from
standard I/O
.I FILE
streams, TCP/IP connections and UNIX files, and memory.
.NH 3
\&Standard I/O Streams
.IX "XDR" "standard I/O streams"
.LP
XDR streams can be interfaced to standard I/O using the
.I xdrstdio_create() 
.IX xdrstdio_create() "" \fIxdrstdio_create()\fP
routine as follows:
.DS
.ft CW
#include <stdio.h>
#include <rpc/rpc.h>    /* \fIxdr streams part of rpc\fP */
.sp.5
void
xdrstdio_create(xdrs, fp, x_op)
    XDR *xdrs;
    FILE *fp;
    enum xdr_op x_op;
.DE
The routine
.I xdrstdio_create() 
initializes an XDR stream pointed to by
.I xdrs .
The XDR stream interfaces to the standard I/O library.
Parameter
.I fp
is an open file, and
.I x_op
is an XDR direction.
.NH 3
\&Memory Streams
.IX "XDR" "memory streams"
.LP
Memory streams allow the streaming of data into or out of
a specified area of memory:
.DS
.ft CW
#include <rpc/rpc.h>
.sp.5
void
xdrmem_create(xdrs, addr, len, x_op)
    XDR *xdrs;
    char *addr;
    u_int len;
    enum xdr_op x_op;
.DE
The routine
.I xdrmem_create() 
.IX xdrmem_create() "" \fIxdrmem_create()\fP
initializes an XDR stream in local memory.
The memory is pointed to by parameter
.I addr ;
parameter
.I len
is the length in bytes of the memory.
The parameters
.I xdrs
and
.I x_op
are identical to the corresponding parameters of
.I xdrstdio_create ().
Currently, the UDP/IP implementation of RPC uses
.I xdrmem_create ().
Complete call or result messages are built in memory before calling the
.I sendto() 
system routine.
.NH 3
\&Record (TCP/IP) Streams
.IX "XDR" "record (TCP/IP) streams"
.LP
A record stream is an XDR stream built on top of
a record marking standard that is built on top of the
UNIX file or 4.2 BSD connection interface.
.DS
.ft CW
#include <rpc/rpc.h>    /* \fIxdr streams part of rpc\fP */
.sp.5
xdrrec_create(xdrs,