The first parameter, xdrs, is a pointer to an XDR stream handle. The second parameter is a pointer to the number that provides data to the stream or receives data from it. All routines return TRUE if they complete successfully, and FALSE if they do not.
For more information on number filters, see Chapter 8.
4.2.2 Floating-Point Filters
The XDR library also provides primitive routines for floating-point types in C:
bool_t xdr_float(xdrs, fp)
XDR *xdrs;
float *fp;
bool_t xdr_double(xdrs, dp)
XDR *xdrs;
double *dp;
The first parameter, xdrs, is a pointer to an XDR stream handle. The second parameter is a pointer to the floating-point number that provides data to the stream or receives data from it. Both routines return TRUE if they complete successfully, and FALSE if they do not.
Note
Because the numbers are represented in IEEE floating point format over the network, routines may fail when decoding a valid IEEE representation into a system-specific representation, or vice versa.To control the local representation of floating point numbers, you can choose the floating point type when you compile your RPC program or you can use different XDR routines to explicitly control the local representation. For more information on floating-point filters, see the xdr_double and xdr_float routines in Chapter 8.
The XDR library provides a primitive for generic enumerations; it assumes that a C enum has the same representation inside the system as a C integer. The bool_t (boolean) type is an important instance of the enum type. The external representation of a bool_t type is always TRUE (1) or FALSE (0) as shown here:
#define bool_t int
#define FALSE 0
#define TRUE 1
#define enum_t int
bool_t xdr_enum(xdrs, ep)
XDR *xdrs;
enum_t *ep;
bool_t xdr_bool(xdrs, bp)
XDR *xdrs;
bool_t *bp;
The second parameters ep and bp are pointers to the enumerations or booleans that provide data to, or receive data from, the stream xdrs.
For more information on enumeration filters, see Chapter 8.
4.2.4 Possibility of No Data
Occasionally, an XDR routine must be supplied to the RPC system, even when no data is passed or required. The following routine does this:
bool_t xdr_void(); /* always returns TRUE */
Constructed or compound data type primitives require more parameters and perform more complicated functions than the primitives previously discussed. The following sections include primitives for strings, arrays, unions, and pointers to structures.
Constructed data type primitives may use memory management. In many cases, memory is allocated when deserializing data with XDR_DECODE. XDR enables memory deallocation through the XDR_FREE operation. The three XDR directional operations are XDR_ENCODE, XDR_DECODE, and XDR_FREE.
For more information on constructed data filters, see Chapter 8.
4.2.5.1 Strings
In C, a string is defined as a sequence of bytes terminated by a NULL byte, which is not considered when calculating string length. When a string is passed or manipulated, there must be a pointer to it. Therefore, the XDR library defines a string to be a char*, not a sequence of characters. The external and internal representations of a string are different. Externally, strings are represented as sequences of ASCII characters; internally, with character pointers. The xdr_string routine converts between the two, as shown:
bool_t xdr_string(xdrs, sp, maxlength)
XDR *xdrs;
char **sp;
u_int maxlength;
The first parameter, xdrs, is the XDR stream handle; the second, sp, is a pointer to a string (type char **). The third parameter, maxlength, specifies the maximum number of bytes allowed during encoding or decoding; its value is usually specified by a protocol. For example, a protocol may specify that a file name cannot be longer than 255 characters. Keep maxlength small because overflow conditions may occur if xdr_string has to call malloc for space. The routine returns FALSE if the number of characters exceeds maxlength; otherwise, it returns TRUE.
The behavior of xdr_string is similar to that of other routines in this section. For the direction XDR_ENCODE, the parameter sp points to a string of a certain length; if the string does not exceed maxlength, the bytes are serialized.
For the direction XDR_DECODE, the effect of deserializing a string is subtle. First, the length of the incoming string is determined; it must not exceed maxlength. Next, sp is dereferenced; if the value is NULL, then a string of the appropriate length is allocated and *sp is set to this string. If the original value of *sp is not NULL, then XDR assumes that a target area (which can hold strings no longer than maxlength) has been allocated. In either case, the string is decoded into the target area, and the routine appends a NULL character to it.
In the XDR_FREE operation, the string is obtained by
dereferencing sp. If the string is not NULL, it is
freed and *sp is set to NULL. In this operation,
xdr_string ignores the maxlength parameter.
4.2.5.2 Variable-Length Byte Arrays
Often, variable-length arrays of bytes are preferable to strings. Byte arrays differ from strings in the following three ways:
The primitive xdr_bytes converts between the internal and external representations of byte arrays:
bool_t xdr_bytes(xdrs, bpp, lp, maxlength)
XDR *xdrs;
char **bpp;
u_int *lp;
u_int maxlength;
The usage of the first, second, and fourth parameters are identical to
the same parameters of xdr_string (Section 4.2.5.1). The length
of the byte area is obtained by dereferencing lp when
serializing; *lp is set to the byte length when deserializing.
4.2.5.3 Variable-Length Arrays of Arbitrary Data Elements
The XDR library provides a primitive for handling arrays of arbitrary elements. The 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, xdr_array, requires parameters identical to those of xdr_bytes in addition to two more: the size of array elements and an XDR routine to handle each of the elements.
This routine encodes or decodes each array element:
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)();
The parameter ap is a pointer to the pointer to the array. If *ap is NULL when the array is being deserialized, XDR allocates an array of the appropriate size and sets *ap to that array. The element count of the array is obtained from *lp when the array is serialized; *lp is set to the array length when the array is deserialized. The parameter maxlength is the maximum allowable number of array elements; elementsiz is the byte size of each array element. (You can also use the C function sizeof to obtain this value.) The xdr_element routine is called to serialize, deserialize, or free each element of the array.
Examples 4-1, 4-2, and 4-3 show the recursiveness of the XDR library routines already discussed.
A user on a networked system can be identified in three ways:
Examples
4-1 shows how a structure with this information and its
associated XDR routine could be coded:
Examples
4-1 Structure and Associated XDR
Routine
struct netuser {
char *nu_systemname;
int nu_uid;
u_int nu_glen;
int *nu_gids;
};
#define NLEN 255 /* system names < 256 chars */
#define NGRPS 20 /* user can't be in > 20 groups */
bool_t
xdr_netuser(xdrs, nup)
XDR *xdrs;
struct netuser *nup;
{
return(xdr_string(xdrs, &nup->nu_systemname, NLEN) &&
xdr_int(xdrs, &nup->nu_uid) &&
xdr_array(xdrs, &nup->nu_gids, &nup->nu_glen,
NGRPS, sizeof (int), xdr_int));
}
A party of network users could be implemented as an array of
netuser structure. Examples
4-2 shows the declaration and its
associated XDR routines:
Examples
4-2 Declaration and Associated XDR
Routines
struct party {
u_int p_len;
struct netuser *p_nusers;
};
#define PLEN 500 /* max number of users in a party */
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));
}
The parameters to main (argc and argv) can
be combined into a structure, and an array of these structures can make
up a history of commands. Examples
4-3 shows how the declarations and
XDR routines might look:
Examples
4-3 Declarations and XDR Routines
struct cmd {
u_int c_argc;
char **c_argv;
};
#define ALEN 1000 /* args cannot be > 1000 chars */
#define NARGC 100 /* commands cannot have > 100 args */
struct history {
u_int h_len;
struct cmd *h_cmds;
};
#define NCMDS 75 /* history is no more than 75 commands */
bool_t
xdr_wrapstring(xdrs, sp)
XDR *xdrs;
char **sp;
{
return(xdr_string(xdrs, sp, ALEN));
}
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_wrapstring));
}
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));
}
In Examples
4-3, the routine xdr_wrapstring is needed to
package the xdr_string routine, because the implementation of
xdr_array only passes two parameters to the array element
description routine; xdr_wrapstring supplies the third
parameter to xdr_string.
4.2.5.4 Fixed-Length Arrays of Arbitrary Data Elements
The XDR library provides a primitive, xdr_vector, for fixed-length arrays:
#define NLEN 255 /* system names must be < 256 chars */
#define NGRPS 20 /* user belongs to exactly 20 groups */
struct netuser {
char *nu_systemname;
int nu_uid;
int nu_gids[NGRPS];
};
bool_t
xdr_netuser(xdrs, nup)
XDR *xdrs;
struct netuser *nup;
{
int i;
if (!xdr_string(xdrs, &nup->nu_systemname, 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);
}
Some protocols pass handles from a server to a client. The client later passes back the handles, without first inspecting them; that is, handles are opaque. The xdr_opaque primitive describes fixed-size, opaque bytes:
bool_t xdr_opaque(xdrs, p, len)
XDR *xdrs;
char *p;
u_int len;
The first parameter xdrs is the XDR stream handle. The second
parameter p is the location of the bytes and the third
paramter len is the number of bytes in the opaque object. By
definition, the data within the opaque object is not system-portable.
4.2.5.6 Discriminated Unions
The XDR library supports discriminated unions. A discriminated union is a C union and an enum_t value that selects an arm of the union:
struct xdr_discrim {
enum_t value;
bool_t (*proc)();
};
bool_t xdr_union(xdrs, dscmp, unp, arms, defaultarm)
XDR *xdrs;
enum_t *dscmp;
char *unp;
struct xdr_discrim *arms;
bool_t (*defaultarm)(); /* may equal NULL */
In this example, the routine translates the discriminant of the union at *dscmp. The discriminant is always an enum_t. Next, the union at *unp is translated. The parameter arms is a pointer to an array of xdr_discrim structures. Each structure contains an ordered pair of [value,proc].
If the union's discriminant is equal to the associated value, then proc is called to translate the union. The end of the xdr_discrim structure array is denoted by a routine of value NULL. If the discriminant is not in the arms array, then the defaultarm procedure is called if it is non-null; otherwise, the routine returns FALSE.
Examples
4-4 shows how to serialize or deserialize a discriminated
union. In the example, suppose that the type of a union is an integer,
character pointer (a string), or a gnumbers structure
(described in Section 4.1.2). Also, assume the union and its current
type are declared in a structure, as follows:
enum utype { INTEGER=1, STRING=2, GNUMBERS=3 };
struct u_tag {
enum utype utype; /* the union's discriminant */
union {
int ival;
char *pval;
struct gnumbers gn;
} uval;
};
Examples
4-4 shows the constructs and XDR procedure that serialize or
deserialize the discriminated union:
Examples
4-4 Constructs and XDR Procedure
struct xdr_discrim u_tag_arms[4] = {
{ INTEGER, xdr_int },
{ GNUMBERS, xdr_gnumbers }
{ STRING, xdr_wrapstring },
{ __dontcare__, NULL }
/* always terminate arms with a NULL xdr_proc */
}
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));
}
The routine xdr_gnumbers was discussed in Section 4.1.2 and
xdr_wrapstring was presented in Examples
4-3. The default arm
parameter to xdr_union (the last parameter) is NULL
in Examples
4-4. Therefore, the value of the union's discriminant can
only be a value listed in the u_tag_arms array. Examples
4-4
also shows that the elements of the arm's array do not need to be
sorted.
The values of the discriminant may be sparse, though in Examples
4-4
they are not. It is always good practice to explicitly assign integer
values to each element of the discriminant's type. This will document
the external representation of the discriminant and guarantee that
different C compilers provide identical discriminant values.
4.2.5.7 Pointers
In C it is useful to put within a structure any pointers to another structure. The xdr_reference primitive makes it easy to serialize, deserialize, and free these referenced structures. A structure of structure pointers is shown here:
bool_t xdr_reference(xdrs, pp, size, proc)
XDR *xdrs;
char **pp;
u_int ssize;
bool_t (*proc)();
Parameter xdrs is the XDR stream handle, pp is a pointer to the pointer to the structure, ssize is the size in bytes of the structure (use the C function sizeof to obtain this value), and proc is the XDR routine that describes the structure. When decoding data, storage is allocated if *pp is NULL.
There is no need for a primitive xdr_struct to describe a structure within a structure, because pointers are always sufficient.
Note
The xdr_reference and xdr_array primitives are not interchangeable external representations of data.
The following example describes a structure (and its corresponding XDR routine) that contains an item of data and a pointer to a gnumbers structure that has more information about that item of data.
Suppose there is a structure containing a person's name and a pointer to a gnumbers structure containing the person's gross assets and liabilities. This structure has the following construct:
struct pgn {
char *name;
struct gnumbers *gnp;
};
This structure has the following corresponding XDR routine:
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);
}
In many applications, C programmers attach double meaning to the values of a pointer. Typically the value NULL means data is not necessary, but 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 example, in the previous structure, a NULL pointer value for gnp could indicate that the person's assets and liabilities are unknown; that is, the pointer value encodes two things: whether 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.
During serialization, the primitive xdr_reference cannot attach any special meaning to a pointer with the value NULL. That is, passing a pointer to a pointer whose value is NULL to xdr_reference when serializing data will most likely cause a memory fault and a core dump.
The xdr_pointer correctly handles NULL pointers. For
more information about its use, see Section 4.5.
4.2.6 Non-filter Primitives
The non-filter primitives that follow are for manipulating XDR streams:
u_int xdr_getpos(xdrs)
XDR *xdrs;
bool_t xdr_setpos(xdrs, pos)
XDR *xdrs;
u_int pos;
xdr_destroy(xdrs)
XDR *xdrs;
The routine xdr_getpos returns an unsigned integer that describes the current position in the data stream.
Note
In some XDR streams, the returned value of xdr_getpos is meaningless; the routine returns a -1 in this case (though -1 should be a legitimate value).The routine xdr_setpos sets a stream position to pos. However, in some XDR streams, setting a position is impossible; in such cases, xdr_setpos returns FALSE.
This routine also fails if the requested position is explicitly out of bounds. The definition of bounds varies according to the stream.
The xdr_destroy primitive destroys the XDR stream. Usage of
the stream after calling this routine is undefined.
4.3 XDR Operation Directions
Though not recommended, you may want to optimize XDR routines by using
the direction of the operation: XDR_ENCODE,
XDR_DECODE, or XDR_FREE. For example, the value
xdrs->x_op contains the direction of the XDR operation. An
example in Section 4.5 shows the usefulness of the
xdrs->x_op field.
4.4 XDR Stream Access
An XDR stream is obtained by calling the appropriate creation routine,
which takes arguments for the specific properties of the stream.
Streams currently exist for serialization or deserialization of data to
or from standard I/O FILE streams, TCP/IP connections and files, and
memory.
4.4.1 Standard I/O Streams
XDR streams can be interfaced to standard I/O using the xdrstdio_create routine as follows:
#include <stdio.h>
#include <rpc/rpc.h> /* XDR streams part of RPC */
void
xdrstdio_create(xdrs, fp, x_op)
XDR *xdrs;
FILE *fp;
enum xdr_op x_op;
The routine xdrstdio_create initializes an XDR stream pointed
to by xdrs. The XDR stream interfaces to the standard I/O
library. Parameter fp is an open file, and x_op is an
XDR direction.
4.4.2 Memory Streams
A memory stream enables the streaming of data into or out of a specified area of memory:
#include <rpc/rpc.h>
void
xdrmem_create(xdrs, addr, len, x_op)
XDR *xdrs;
char *addr;
u_int len;
enum xdr_op x_op;
The routine xdrmem_create initializes an XDR stream in local
memory that is pointed to by parameter addr; parameter
len is the length in bytes of the memory. The parameters
xdrs and x_op are identical to the corresponding
parameters of xdrstdio_create. Currently, the UDP/IP
implementation of ONC RPC uses xdrmem_create. Complete call or
result messages are built-in memory before calling the sendto
system routine.
4.4.3 Record (TCP/IP) Streams
A record stream is an XDR stream built on top of a record-marking standard that is, in turn, built on top of a file or a Berkeley UNIX 4.2 BSD connection interface, as shown:
#include <rpc/rpc.h> /* xdr streams part of rpc */
xdrrec_create(xdrs, sendsize, recvsize, iohandle, readproc, writeproc)
XDR *xdrs;
u_int sendsize, recvsize;
char *iohandle;
int (*readproc)(), (*writeproc)();
The routine xdrrec_create provides an XDR stream interface that allows for a bidirectional, arbitrarily long sequence of records. The contents of the records are meant to be data in XDR form. The stream's primary use is for interfacing RPC to TCP connections. However, it can be used to stream data into or out of ordinary files.
The parameter xdrs is similar to the corresponding parameter described in Section 4.4.1. The stream does its own data buffering, similar to that of standard I/O. The parameters sendsize and recvsize determine the size in bytes of the output and input buffers, respectively; if their values are zero, defaults are used. When a buffer needs to be filled or flushed, the routine readproc or writeproc is called, respectively.
If xxx is readproc or writeproc, then it has the following form:
/* returns the actual number of bytes transferred;
* -1 is an error
*/
int
xxx(iohandle, buf, len)
char *iohandle;
char *buf;
int nbytes;
The usage of these routines is similar to the system calls read and write. However, the first parameter to each routine is the opaque parameter iohandle. The other two parameters (buf and nbytes) and the results (byte count) are identical to the system routines.
The XDR stream enables you to delimit records in the byte stream. This is discussed in Section 4.5. The following primitives are specific to record streams:
bool_t
xdrrec_endofrecord(xdrs, flushnow)
XDR *xdrs;
bool_t flushnow;
bool_t
xdrrec_skiprecord(xdrs)
XDR *xdrs;
bool_t
xdrrec_eof(xdrs)
XDR *xdrs;
The routine xdrrec_endofrecord causes the current outgoing data to be marked as a record. If the parameter flushnow is TRUE, then the stream's writeproc will be called; otherwise, writeproc will be called when the output buffer has been filled.
The routine xdrrec_skiprecord causes an input stream's
position to be moved past the current record boundary and onto the
beginning of the next record in the stream. If there is no more data in
the stream's input buffer, then the routine xdrrec_eof returns
TRUE. This does not mean that there is no more data in the underlying
file descriptor.
4.4.4 XDR Stream Implementation
This section provides the abstract data types needed to implement new instances of XDR streams. The following structure defines the interface to an XDR stream:
enum xdr_op { XDR_ENCODE=0, XDR_DECODE=1, XDR_FREE=2 };
typedef struct {
enum xdr_op x_op; /* operation; fast added param */
struct xdr_ops {
bool_t (*x_getlong)(); /* get long from stream */
bool_t (*x_putlong)(); /* put long to stream */
bool_t (*x_getbytes)(); /* get bytes from stream */
bool_t (*x_putbytes)(); /* put bytes to stream */
u_int (*x_getpostn)(); /* return stream offset */
bool_t (*x_setpostn)(); /* reposition offset */
caddr_t (*x_inline)(); /* ptr to buffered data */
VOID (*x_destroy)(); /* free private area */
} *x_ops;
caddr_t x_public; /* users' data */
caddr_t x_private; /* pointer to private data */
caddr_t x_base; /* private for position info */
int x_handy; /* extra private word */
} XDR;
The x_op field is the current operation being performed on the stream. This field is important to the XDR primitives, but is not expected to affect the implementation of a stream. The fields x_private, x_base, and x_handy pertain to a particular stream implementation. The field x_public is for the XDR client and must not be used by the XDR stream implementations or the XDR primitives. The macros x_getpostn, x_setpostn, and x_destroy, access operations. The operation x_inline takes two parameters: an XDR*, and an unsigned integer, which is a byte count. The routine returns a pointer to a piece of the stream's internal buffer. The program can then use the buffer segment for any purpose. To the stream, the bytes in the buffer segment have been consumed or put. The routine may return NULL if it cannot return a buffer segment of the requested size. (The x_inline routine is for maximizing efficient use of processor cycles. The resulting buffer is not data-portable, so using this feature is not recommended.)
The operations x_getbytes and x_putbytes get and put sequences of bytes from or to the underlying stream; they return TRUE if successful, and FALSE otherwise. The routines have identical parameters (replace xxx with either x_get or x_put):
bool_t
xxxbytes(xdrs, buf, bytecount)
XDR *xdrs;
char *buf;
u_int bytecount;
The x_getlong and x_putlong routines receive and put long numbers to and from the data stream. These routines must translate the numbers between the system representation and the (standard) external representation. The operating system primitives htonl and ntohl help to do this. The higher-level XDR implementation assumes that signed and unsigned long integers contain the same number of bits, and that nonnegative integers have the same bit representations as unsigned integers. The routines return TRUE if they succeed, and FALSE if they do not. They have identical parameters (replace xxx with either x_get or x_put):
bool_t
xxxlong(xdrs, lp)
XDR *xdrs;
long *lp;