Appendix A XDR Technical Note
This appendix is a technical note on the Sun Microsystems implementation of the external data representation (XDR) standard, which is a set of library routines that enable C programmers to describe arbitrary data structures in a machine-independent manner.
What Is XDR?
XDR is the backbone of the Sun Microsystems Remote Procedure Call package. Data for RPCs are transmitted using this standard. XDR library routines should be used to transmit data accessed (read or written) by more than one type of machine.
XDR works across different languages, operating systems, and machine architectures. Most users (particularly RPC users) only need the information in the sections on number filters, floating point filters, and enumeration filters. Programmers who want to implement RPC and XDR on new machines should read this technical note and the protocol specification.
You can use rpcgen to write XDR routines even in cases where no RPC calls are being made.
C programs that use XDR routines must include the file <rpc/xdr.h>, which contains all the necessary interfaces to the XDR system. Because the library libnsl.a contains all the XDR routines, you compile it by typing:
example% cc program.c
In many environments, several criteria must be observed to accomplish porting. The ramifications of a small programmatic change are not always apparent, but they can often have far-reaching implications. Consider the program to read/write a line of text that is shown in the next two code examples.
Example A–1 Writer Example (initial)
#include <stdio.h>
main() /* writer.c */
{ int i;
for (i = 0; i < 8; i++) {
if (fwrite((char *) &i, sizeof(i), 1, stdout) != 1) {
fprintf(stderr, "failed!\n");
exit(1);
}
}
exit(0);
}
Example A–2 Reader Example (initial)
#include <stdio.h>
main() /* reader.c */
{
int i, j;
for (j = 0; j < 8; j++) {
if (fread((char *) &i, sizeof(i), 1, stdin) != 1) {
fprintf(stderr, "failed!\n");
exit(1);
}
printf("%ld ", i);
}
printf("\n");
exit(0);
}
The two programs appear to be portable because they:
-
Pass lint checking
-
Exhibit the same behavior when executed locally on any hardware architecture
Piping the output of the writer program to the reader program gives identical results on a SPARC or Intel machine.
sun% writer | reader 0 1 2 3 4 5 6 7 sun% intel% writer | reader 0 1 2 3 4 5 6 7 intel%
With the advent of local area networks and 4.2BSD came the concept of “network pipes,” which is a process that produces data on one machine and a second process that consumes data on another machine. You can construct a network pipe with writer and reader. Here are the results if the writer produces data on a SPARC system, and the reader consumes data on Intel architecture.
sun% writer | rsh intel reader 0 16777216 33554432 50331648 67108864 83886080 100663296 117440512 sun%
Executing writer on the Intel and reader on the SPARC system produces identical results. These results occur because the byte ordering of data differs between the Intel and the SPARC, even though the word size is the same.
Note –
16777216 is 224. When 4 bytes are reversed, the 1 is placed in the 24th bit.
Whenever data is shared by two or more machine types, a need exists for portable data. You can make data portable by replacing the read() and write() calls with calls to an XDR library routine, xdr_int(), a filter that knows the standard representation of an int integer in its external form. The revised versions of writer are shown in the following code example.
Example A–3 Writer Example (XDR modified)
#include <stdio.h>
#include <rpc/rpc.h> /* xdr is a sub-library of rpc */
main() /* writer.c */
{
XDR xdrs;
int i;
xdrstdio_create(&xdrs, stdout, XDR_ENCODE);
for (i = 0; i < 8; i++) {
if (!xdr_int(&xdrs, &i)) {
fprintf(stderr, "failed!\n");
exit(1);
}
}
exit(0);
}
The following code example shows the revised versions of reader.
Example A–4 Reader Example (XDR modified)
#include <stdio.h>
#include <rpc/rpc.h> /* xdr is a sub-library of rpc */
main() /* reader.c */
{
XDR xdrs;
int i, j;
xdrstdio_create(&xdrs, stdin, XDR_DECODE);
for (j = 0; j < 8; j++) {
if (!xdr_int(&xdrs, &i)) {
fprintf(stderr, "failed!\n");
exit(1);
}
printf("%ld ", i);
}
printf("\n");
exit(0);
}
The new programs were executed on a SPARC system, on an Intel, and from a SPARC to an Intel. The results follow.
sun% writer | reader 0 1 2 3 4 5 6 7 sun% intel% writer | reader 0 1 2 3 4 5 6 7 intel% sun% writer | rsh intel reader 0 1 2 3 4 5 6 7 sun%
Note –
Arbitrary data structures can create portability issues, particularly with respect to alignment and pointers. Alignment on word boundaries cause the size of a structure to vary from machine to machine. Pointers, which are very convenient to use, have no meaning outside the machine where they are defined.
Canonical Standard
The XDR approach to standardizing data representations is canonical. That is, XDR defines a single byte order, a single floating-point representation (IEEE), and so on. Any program running on any machine can use XDR to create portable data by translating its local representation to the XDR standard representations. Similarly, any program running on any machine can read portable data by translating the XDR standard representations to its local equivalents.
The single standard completely decouples programs that create or send portable data from those that use or receive portable data. A new machine learns how to convert the standard representations and its local representations. The local representations of other machines are irrelevant. Conversely, the local representations of the new machine are also irrelevant to existing programs running on other machines. Such programs can immediately read portable data produced by the new machine because such data conforms to the canonical standards that they already understand.
Strong precedents are in place for XDR's canonical approach. For example, TCP/IP, UDP/IP, XNS, Ethernet, and, indeed, all protocols below layer five of the ISO model, are canonical protocols. The advantage of any canonical approach is simplicity. In the case of XDR, a single set of conversion routines is written once and is never touched again.
The canonical approach has the disadvantage of unnecessary conversion to and from the XDR standard when data is transferred between two machines with identical byte order. Suppose two Intel machines are transferring integers according to the XDR standard. The sending machine converts the integers from Intel host byte order to XDR byte order. The receiving machine performs the reverse conversion. Because both machines observe the same byte order, their conversions are unnecessary.
The time spent converting to and from a canonical representation is insignificant, especially in distributed applications. Most of the time required to prepare a data structure for transfer is not spent in conversion but in traversing the elements of the data structure.
To transmit a tree, for example, each leaf must be visited and each element in a leaf record must be copied to a buffer and aligned there. Storage for the leaf might have to be de-allocated as well. Similarly, to receive a tree, you must allocate storage for each leaf, move data from the buffer to the leaf and properly align it, and construct pointers to link the leaves together.
Every machine pays the cost of traversing and copying data structures whether or not conversion is required. In distributed applications, communications overhead, which is the time required to move the data down the sender's protocol layers, across the network, and up the receiver's protocol layers, dwarfs conversion overhead.
XDR Library
The XDR library solves data portability problems, and also enables you to write and read arbitrary C constructs in a consistent, specified, well-documented manner. Thus, using the library can be helpful even when the data is not shared among machines on a network.
The XDR library has filter routines for strings (null-terminated arrays of bytes), structures, unions, and arrays, to name a few. Using more primitive routines, you can write your own specific XDR routines to describe arbitrary data structures, including elements of arrays, arms of unions, or objects pointed at from other structures. The structures themselves might contain arrays of arbitrary elements, or pointers to other structures.
Look closely at Example A–3 and Example A–4. A family of XDR stream-creation routines has each member treat the stream of bits differently. In the example, data is manipulated using standard I/O routines, so you use xdrstdio_create(). The parameters to XDR stream-creation routines vary according to their function. In the example, xdrstdio_create() takes a pointer to an XDR structure that it initializes, a pointer to a FILE that the input or output is performed on, and the operation. The operation might be XDR_ENCODE for serializing in the writer program, or XDR_DECODE for deserializing in the reader program.
Note –
RPC users never need to create XDR streams. The RPC system itself creates these streams, which are then passed to the users.
The xdr_int() primitive is characteristic of most
XDR library primitives and all client XDR routines. First, the routine returns FALSE (0) if it fails, and TRUE (1)
if it succeeds. Second, for each data type, xxx, there is an
associated XDR routine of the form:
xdr_xxx(xdrs, xp)
XDR *xdrs;
xxx *xp;
{
}
In this case, xxx is int, and the corresponding XDR routine
is a primitive, xdr_int(). The client could also define
an arbitrary structure xxx, in which case the client
would also supply the routine xdr_xxx(), describing each
field by calling XDR routines of the appropriate type. In all cases the first
parameter, xdrs, can be treated as an opaque handle
and passed to the primitive routines.
An XDR routine is direction independent. That is, the same routine is called to serialize or deserialize data. This feature is critical to software engineering of portable data. The idea is to call the same routine for either operation. This practice almost guarantees that serialized data can also be deserialized.
This one routine is used by both producer and consumer of networked data. This concept is implemented by always passing the address of an object rather than the object itself. Only in the case of deserialization is the object modified. This feature is not shown in the example, but its value becomes obvious when nontrivial data structures are passed among machines. If needed, the user can obtain the direction of the XDR operation. For details, see the sectionOperation Directions.
A slightly more complicated example follows. Assume that a person's gross assets and liabilities are to be exchanged among processes. Also assume that these values are important enough to warrant their own data type.
struct gnumbers {
int g_assets;
int g_liabilities;
};
The corresponding XDR routine describing this structure is as follows.
bool_t /* TRUE is success, FALSE is failure */
xdr_gnumbers(xdrs, gp)
XDR *xdrs;
struct gnumbers *gp;
{
if (xdr_int(xdrs, &gp->g_assets) &&
xdr_int(xdrs, &gp->g_liabilities))
return(TRUE);
return(FALSE);
}
Note that the parameter xdrs is never inspected or modified. It is only passed on to the subcomponent routines. The routine must inspect the return value of each XDR routine call, and to halt immediately and return FALSE if the subroutine fails.
This example also shows that the type bool_t is declared as an integer that has only the values TRUE (1) and FALSE (0). This document uses the following definitions:
#define bool_t int #define TRUE 1 #define FALSE 0
By observing these conventions, you can rewrite xdr_gnumbers() as follows:
xdr_gnumbers(xdrs, gp)
XDR *xdrs;
struct gnumbers *gp;
{
return(xdr_int(xdrs, &gp->g_assets) &&
xdr_int(xdrs, &gp->g_liabilities));
}
This document uses both coding styles.
XDR Library Primitives
This section provides a synopsis of each XDR primitive. It starts with memory allocation and the basic data types, then moves on to constructed data types. Finally, XDR utilities are discussed. The interface to these primitives and utilities is defined in the include file <rpc/xdr.h>, automatically included by <rpc/rpc.h>.
Memory Requirements for XDR Routines
When using XDR routines, you sometimes need to to pre-allocate memory, or to determine memory requirements. When you need to control the allocation and de-allocation of memory for XDR conversion routines, you can use a routine, xdr_sizeof(). This routine returns the number of bytes needed to encode and decode data with one of the XDR filter functions (func()). The output of the xdr_sizeof() function does not include RPC headers or record markers. You must add them to get a complete accounting of the memory required. xdr_sizeof() returns a zero on error.
xdr_sizeof(xdrproc_t func, void *data)
Use xdr_sizeof() for the allocation of memory in applications that use XDR outside of the RPC environment, to select between transport protocols, and at the lower levels of RPC to perform client and server creation functions.
The next two code examples illustrate two uses of xdr_sizeof().
Example A–5 xdr_sizeof Example #1
#include <rpc/rpc.h>
/*
* This function takes as input a CLIENT handle, an XDR function
and
* a pointer to data to be XDR'd. It returns TRUE if the amount of
* data to be XDR'd may be sent using the transport associated
with
* the CLIENT handle, and false otherwise.
*/
bool_t
cansend(cl, xdrfunc, xdrdata)
CLIENT *cl;
xdrproc_t xdrfunc;
void *xdrdata;
{
int fd;
struct t_info tinfo;
if (clnt_control(cl, CLGET_FD, &fd) == -1) {
/* handle clnt_control() error */
return (FALSE);
}
if (t_getinfo(fd, &tinfo) == -1) {
/* handle t_getinfo() error */
return (FALSE);
} else {
if (tinfo.servtype == T_CLTS) {
/*
* This is a connectionless transport. Use xdr_sizeof()
* to compute the size of this request to see whether it
* is too large for this transport.
*/
switch(tinfo.tsdu) {
case 0: /* no concept of TSDUs */
case -2: /* can't send normal data */
return (FALSE);
break;
case -1: /* no limit on TSDU size */
return (TRUE);
break;
default:
if (tinfo.tsdu < xdr_sizeof(xdrfunc, xdrdata))
return (FALSE);
else
return (TRUE);
}
} else
return (TRUE);
}
}
The second xdr_sizeof() example follows.
Example A–6 xdr_sizeof Example #2
#include <sys/statvfs.h>
#include <sys/sysmacros.h>
/*
* This function takes as input a file name, an XDR function, and
a
* pointer to data to be XDR'd. It returns TRUE if the filesystem
* on which the file resides has room for the additional amount
of
* data to be XDR'd. Note that since the information statvfs(2)
* returns about the filesystem is in blocks you must convert the
* value returned by xdr_sizeof() from bytes to disk blocks.
*/
bool_t
canwrite(file, xdrfunc, xdrdata)
char *file;
xdrproc_t xdrfunc;
void *xdrdata;
{
struct statvfs s;
if (statvfs(file, &s) == -1) {
/* handle statvfs() error */
return (FALSE);
}
if (s.f_bavail >= btod(xdr_sizeof(xdrfunc, xdrdata)))
return (TRUE);
else
return (FALSE);
}
Number Filters
The XDR library provides primitives to translate between numbers and their corresponding external representations. Primitives cover the set of numbers in the types:
[signed, unsigned] * [short, int, long]
Specifically, the eight primitives are:
bool_t xdr_char(xdrs, op) XDR *xdrs; char *cp; bool_t xdr_u_char(xdrs, ucp) XDR *xdrs; unsigned char *ucp; bool_t xdr_int(xdrs, ip) XDR *xdrs; int *ip; bool_t xdr_u_int(xdrs, up) XDR *xdrs; unsigned *up; bool_t xdr_long(xdrs, lip) XDR *xdrs; long *lip; bool_t xdr_u_long(xdrs, lup) XDR *xdrs; u_long *lup; bool_t xdr_short(xdrs, sip) XDR *xdrs; short *sip; bool_t xdr_u_short(xdrs, sup) XDR *xdrs; u_short *sup;
The first parameter, 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 TRUE if they complete successfully, and FALSE otherwise.
Floating-Point Filters
The XDR library also provides primitive routines for C floating-point types.
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 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 TRUE if they complete successfully, and FALSE otherwise.
Note –
Because the numbers are represented in IEEE floating point, routines might fail when decoding a valid IEEE representation into a machine-specific representation, or the reverse.
Enumeration Filters
The XDR library provides a primitive for generic enumerations. The primitive
assumes that a C enum has the same representation inside the
machine as a C integer. The Boolean type is an important instance of the enum. The external representation of a Boolean is always TRUE (1) or FALSE (0).
#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 addresses of the associated type that provides data to or receives data from the stream xdrs.
No-Data Routine
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.
bool_t xdr_void(); /* always returns TRUE */
Constructed Data Type Filters
Constructed or compound data type primitives require more parameters and perform more complicated functions than the primitives discussed previously. This section includes primitives for strings, arrays, unions, and pointers to structures.
Constructed data type primitives can use memory management. In many cases, memory is allocated when deserializing data with XDR_DECODE. Therefore, the XDR package must provide a means to de-allocate memory. The XDR operation, XDR_FREE provides this means. To review, the three XDR directional operations are XDR_ENCODE, XDR_DECODE, and XDR_FREE.
Strings
In the C language, 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 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. Internally, strings are represented with character pointers. Conversion between the two representations is accomplished with the routine xdr_string():
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 parameter 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 specification might say that a file name can be no longer than 255 characters. The routine returns FALSE if the number of characters exceeds maxlength, and TRUE if it doesn't.
The behavior of xdr_string() is similar to the behavior of other routines discussed in this section. For example, in 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.
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, a string of the appropriate length is allocated and *sp is set to this string. If the original value of *sp is nonnull, the XDR package assumes that a target area has been allocated that can hold strings no longer than maxlength. In either case, the string is decoded into the target area. The routine then appends a null character to the string.
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.
Note that you can use XDR on an empty string ("") but not on a NULL string.
Byte Arrays
Often variable-length arrays of bytes are preferable to strings. Byte arrays differ from strings in the following three ways:
-
The length of the array, the byte count, is explicitly located in an unsigned integer.
-
The byte sequence is not terminated by a null character.
-
The external representation of the bytes is the same as their internal representation.
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 is identical to the first, second, and third parameters of xdr_string(). The length of the byte area is obtained by dereferencing lp when serializing; *lp is set to the byte length when deserializing.
Arrays
The XDR library package 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() 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.
bool_t xdr_array(xdrs, ap, lp, maxlength, elementsize, xdr_element) XDR *xdrs; char **ap; u_int *lp; u_int maxlength; u_int elementsize; bool_t (*xdr_element)();
The parameter ap is the address of 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 number of elements that the array is allowed to have; elementsiz is the byte size of each element of the array (the C function sizeof() can be used to obtain this value). The xdr_element() routine is called to serialize, deserialize, or free each element of the array.
Before defining more constructed data types, three examples are presented.
Array Example 1
A user on a networked machine can be identified by
-
The machine name.
-
The user's UID. See the getuid(2) man page.
-
The group numbers to which the user belongs. See the getgroups(2) man page.
Example A–7 Array Example #1
struct netuser {
char *nu_machinename;
int nu_uid;
u_int nu_glen;
int *nu_gids;
};
#define NLEN 255 /* machine 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_machinename, NLEN) &&
xdr_int(xdrs, &nup->nu_uid) &&
xdr_array(xdrs, &nup->nu_gids, &nup->nu_glen, NGRPS,
sizeof (int), xdr_int));
}
Array Example 2
You could implement a party of network users as an array of netuser structure. The declaration and its associated XDR routines are as shown in the following code example.
Example A–8 Array Example #2
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));
}
Array Example 3
You can combine the well-known parameters to main, argc and argv, into a structure. An array of these structures can make up a history of commands. The declarations and XDR routines might look like the following example.
Example A–9 Array Example #3
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));
}
Some confusion in this example is that you need the routine xdr_wrapstring() to package the xdr_string() routine, because the implementation of xdr_array() passes only two parameters to the array element description routine. xdr_wrapstring() supplies the third parameter to xdr_string().
By now, the recursive nature of the XDR library should be obvious. A discussion follows of more constructed data types.
Opaque Data
In some protocols, handles are passed from a server to the 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, handles are opaque. The xdr_opaque() primitive is used for describing fixed-sized opaque bytes.
bool_t xdr_opaque(xdrs, p, len) XDR *xdrs; char *p; u_int len;
The parameter p is the location of the bytes, len is the number of bytes in the opaque object. By definition, the actual data contained in the opaque object is not machine portable.
In the SunOS/SVR4 system is another routine for manipulating opaque data. This routine, the xdr_netobj, sends counted opaque data, much like xdr_opaque(). The following code example illustrates the syntax of xdr_netobj().
Example A–10 xdr_netobj Routine
struct netobj {
u_int n_len;
char *n_bytes;
};
typedef struct netobj netobj;
bool_t
xdr_netobj(xdrs, np)
XDR *xdrs;
struct netobj *np;
The xdr_netobj() routine is a filter primitive that translates between variable-length opaque data and its external representation. The parameter np is the address of the netobj structure containing both a length and a pointer to the opaque data. The length may be no more than MAX_NETOBJ_SZ bytes. This routine returns TRUE if it succeeds, FALSE otherwise.
Fixed-Length Arrays
The XDR library provides a primitive, xdr_vector(), for fixed-length arrays, shown in the following code example.
Example A–11 xdr_vector Routine
#define NLEN 255 /* machine names must be < 256 chars */
#define NGRPS 20 /* user belongs to exactly 20 groups */
struct netuser {
char *nu_machinename;
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_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);
}
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 */
First the routine translates the discriminant of the union located at *dscmp. The discriminant is always an enum_t. Next the union located 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 the proc is called to translate the union. The end of the xdr_discrim structure array is denoted by a routine of value NULL (0). If the discriminant is not found in the arms array, then the defaultarm() procedure is called if it is nonnull. Otherwise the routine returns FALSE.
Discriminated Union Example
Suppose the type of a union is integer, character pointer (a string), or a gnumbers structure. Also, assume the union and its current type are declared in a structure. The declaration is:
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;
};
The following code example constructs an XDR procedure to deserialize the discriminated union.
Example A–12 XDR Discriminated Union
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 presented previously in XDR Library. The default arm parameter to xdr_union(), the last parameter, is NULL in this example. Therefore, the value of the union's discriminant can legally take on only values listed in the u_tag_arms array. Example A–12 also demonstrates that the elements of the arm's array do not need to be sorted.
The values of the discriminant can be sparse, though in Example A–12 they are not. Make a practice of assigning 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.
Pointers
In C, putting pointers to another structure within a structure is often convenient. The xdr_reference() primitive makes it easy to serialize, deserialize, and free these referenced structures.
bool_t xdr_reference(xdrs, pp, size, proc) XDR *xdrs; char **pp; u_int ssize; bool_t (*proc)();
Parameter pp is the address of the pointer to the structure; parameter 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.
A primitive xdr_struct() does not need to describe structures within structures because pointers are always sufficient.
Pointer Example
Suppose you have a structure containing a person's name and a pointer to a gnumbers structure containing the person's gross assets and liabilities. The construct is:
struct pgn {
char *name;
struct gnumbers *gnp;
};
The corresponding XDR routine for this structure is:
bool_t
xdr_pgn(xdrs, pp)
XDR *xdrs;
struct pgn *pp;
{
return(xdr_string(xdrs, &pp->name, NLEN) &&
xdr_reference(xdrs, &pp->gnp, sizeof(struct gnumbers),
xdr_gnumbers));
}
Pointer Semantics
In many applications, C programmers attach double meaning to the values of a pointer. Typically the value 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, 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.
The primitive xdr_reference() cannot and does not attach any special meaning to a null-value pointer during serialization. That is, passing an address of a pointer that has a value of value of NULL to xdr_reference() when serializing data most likely causes a memory fault and, on the UNIX system, a core dump.
xdr_pointer() correctly handles NULL pointers.
Nonfilter Primitives
You can manipulate XDR streams with the primitives discussed in this section.
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_getpo()s() returns an unsigned integer that describes the current position in the data stream.
Caution – In some XDR streams, the value returned by x()dr_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. 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 out-of-bounds. The definition of bounds varies from stream to stream.
The xdr_destroy() primitive destroys the XDR stream. Usage of the stream after calling this routine is undefined.
Operation Directions
At times, you might want to optimize XDR routines by taking advantage of the direction of the operation: XDR_ENCODE, XDR_DECODE or XDR_FREE. The value xdrs->x_op always contains the direction of the XDR operation. An example in Linked Lists demonstrates the usefulness of the xdrs->x_op field.
Stream Access
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. Streams currently exist for deserialization of data to or from standard I/O FILE streams, record streams, memory, and UNIX files.
Standard I/O Streams
XDR streams can be interfaced to standard I/O using the xdrstdio_create() routine.
#include <stdio.h> #include <rpc/rpc.h> /* xdr is part of rpc */ void xdrstdio_create(xdrs, fp, xdr_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.
Memory Streams
Memory streams allow 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. The memory 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 datagram implementation of RPC uses xdrmem_create(). Complete call or result messages are built in memory before calling the t_sndndata() TLI routine.
Record TCP/IP Streams
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.
#include <rpc/rpc.h> /* xdr is 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 normal UNIX files.
The parameter xdrs is similar to the corresponding parameter described previously. 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 (0), then predetermined defaults are used.
When a buffer needs to be filled or flushed, the routine readproc() or writeproc() is called respectively. The usage and behavior of these routines are similar to the UNIX system calls read() and write(). However, the first parameter to each of these routines is the opaque parameter iohandle. The other two parameters, and nbytes and the results, byte count, are identical to the system routines. 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 XDR stream provides a means for delimiting records in the byte stream. Abstract data types needed to implement the XDR stream mechanism are discussed in XDR Stream Implementation. The protocol RPC uses to delimit XDR stream records is discussed in Record-Marking Standard.
The primitives that are specific to record streams are:
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() is called. Otherwise, writeproc() is called when the output buffer is full.
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 no more data is in the stream's input buffer, then the routine xdrrec_eof() returns TRUE. That does not mean that no more data is in the underlying file descriptor.
XDR Stream Implementation
This section provides the abstract data types needed to implement new instances of XDR streams.
XDR Object
The structure in the following code example defines the interface to an XDR stream.
Example A–13 XDR Stream Interface Example
enum xdr_op {XDR_ENCODE=0, XDR_DECODE=1, XDR_FREE=2};
typedef struct {
enum xdr_op x_op;
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 */
bool_t (*x_control)(); /* change, retrieve client info */
bool_t (*x_getint32)(); /* get int from stream */
bool_t (*x_putint32)(); /* put intto stream */
} *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 should not affect a stream's implementation. That is, a stream's implementation should not depend on this value. The fields x_private, x_base, and x_handy are private to the particular stream's implementation. The field x_public is for the XDR client and should never be used by the XDR stream implementations or the XDR primitives. x_getpostn(), x_setpostn(), and x_destroy() are macros for accessing operations.
The operation x_inline() has 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 caller can then use the buffer segment for any purpose. The stream's interpretation is that the bytes in the buffer segment have been consumed. The routine can return NULL if it cannot return a buffer segment of the requested size.
Caution – The x_inline() routine is used to squeeze cycles, and the resulting buffer is not data portable. Do not use this feature.
The operations x_getbytes() and x_putbytes() routinely get and put sequences of bytes from or to the underlying stream. They return TRUE if they are successful, and FALSE otherwise. The routines have identical parameters (replace xxx with the same string in each case.)
bool_t xxxbytes(xdrs, buf, bytecount) XDR *xdrs; char *buf; u_int bytecount;
The operations x_getint32() and x_putint32() receive and put int numbers from and to the data stream. These routines are responsible for translating the numbers between the machine representation and the (standard) external representation. The UNIX primitives htonl() and ntohl() can be helpful in accomplishing this objective. The higher-level XDR implementation assumes that signed and unsigned 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 otherwise.
The x_getint() and x_putint() functions make use of these operations. They have identical parameters:
bool_t xxxint(xdrs, ip) XDR *xdrs; int32_t *ip;
The long version of these operations (x_getlong() and x_putlong()) also call x_getint32() and x_putint32(), ensuring that a 4–byte quantity is operated on, no matter what machine the program is running on.
Implementors of new XDR streams must make an XDR structure with new operation routines available to clients, using some kind of create routine.
Advanced XDR Topics
This section describes techniques for passing data structures that are not covered in the preceding sections. Such structures include linked lists of arbitrary lengths. Unlike the simpler examples covered in the previous sections, the following examples are written using both the XDR C library routines and the XDR data description language. Appendix C, XDR Protocol Specification describes this language in detail.
Linked Lists
The Pointer Example presented a C data structure and its associated XDR routines for an individual's gross assets and liabilities. The following code example uses a linked list to duplicate the pointer example.
Example A–14 Linked List
struct gnumbers {
int g_assets;
int g_liabilities;
};
bool_t
xdr_gnumbers(xdrs, gp)
XDR *xdrs;
struct gnumbers *gp;
{
return(xdr_int(xdrs, &(gp->g_assets) &&
xdr_int(xdrs, &(gp->g_liabilities)));
}
Now assume that you want to implement a linked list of such information. A data structure could be constructed as follows.
struct gnumbers_node {
struct gnumbers gn_numbers;
struct gnumbers_node *gn_next;
};
typedef struct gnumbers_node *gnumbers_list;
Think of the head of the linked list as the data object. That is, the head is not merely a convenient shorthand for a structure. Similarly, the gn_next field is used to indicate whether the object has terminated. Unfortunately, if the object continues, the gn_next field is also the address of where it continues. The link addresses carry no useful information when the object is serialized.
The XDR data description of this linked list is described by the recursive declaration of gnumbers_list.
struct gnumbers {
int g_assets;
int g_liabilities;
};
struct gnumbers_node {
gnumbers gn_numbers;
gnumbers_node *gn_next;
};
In this description, the Boolean indicates more data follows. If the Boolean is FALSE, it is the last data field of the structure. If it is TRUE, it is followed by a gnumbers structure and, recursively, by a gnumbers_list. Note that the C declaration has no Boolean explicitly declared in it, though the gn_next field implicitly carries the information. The XDR data description has no pointer explicitly declared in it.
Hints for writing the XDR routines for a gnumbers_list follow easily from the preceding XDR description. Note how the primitive xdr_pointer() is used to implement the preceding XDR union.
Example A–15 xdr_pointer
bool_t
xdr_gnumbers_node(xdrs, gn)
XDR *xdrs;
gnumbers_node *gn;
{
return(xdr_gnumbers(xdrs, &gn->gn_numbers) &&
xdr_gnumbers_list(xdrs, &gn->gn_next));
}
bool_t
xdr_gnumbers_list(xdrs, gnp)
XDR *xdrs;
gnumbers_list *gnp;
{
return(xdr_pointer(xdrs, gnp, sizeof(struct gnumbers_node),
xdr_gnumbers_node));
xdr_pointer}
The side effect of using XDR on a list with these routines is that the C stack grows linearly with respect to the number of nodes in the list. This growth is due to the recursion. The following example collapses the last two mutually recursive routines into a single, nonrecursive one.
Example A–16 Nonrecursive Stack in XDR
bool_t
xdr_gnumbers_list(xdrs, gnp)
XDR *xdrs;
gnumbers_list *gnp;
{
bool_t more_data;
gnumbers_list *nextp;
for(;;) {
more_data = (*gnp != NULL);
if (!xdr_bool(xdrs, &more_data))
return(FALSE);
if (! more_data)
break;
if (xdrs->x_op == XDR_FREE)
nextp = &(*gnp)->gn_next;
if (!xdr_reference(xdrs, gnp,
sizeof(struct gnumbers_node), xdr_gnumbers))
return(FALSE);
gnp = (xdrs->x_op == XDR_FREE) ? nextp : &(*gnp)->gn_next;
}
*gnp = NULL;
return(TRUE);
}
The first task is to find out whether more data exists, so that this Boolean information can be serialized. Notice that this statement is unnecessary in the XDR_DECODE case, because the value of more_data is not known until you deserialize it in the next statement.
The next statement implements XDR on the more_data field of the XDR union. Then if no more data exists, you set this last pointer to NULL to indicate the end of the list, and return TRUE because you are done. Note that setting the pointer to NULL is only important in the XDR_DECODE case, because the pointer is already NULL in the XDR_ENCODE and XDR_FREE cases.
Next, if the direction is XDR_FREE, set the value of nextp to indicate the location of the next pointer in the list. You set this value now because you need to dereference gnp to find the location of the next item in the list. After the next statement, the storage pointed to by gnp is freed up and no longer valid. You cannot set this value for all directions, though, because in the XDR_DECODE direction the value of gnp is not set until the next statement.
Next, you use XDR on the data in the node using the primitive xdr_reference(). xdr_reference() is like xdr_pointer(), which you used before, but it does not send over the Boolean indicating whether more data exists. You use xdr_reference() instead of xdr_pointer() because you have already
used XDR on this information yourself.
Notice that the XDR routine passed is not the same type as an element in the list. The routine passed is xdr_gnumbers(), but each element in the list is actually of type gnumbers_node. You don't pass xdr_gnumbers_node() because it is recursive. Instead, use xdr_gnumbers(), which uses XDR on all of the nonrecursive part. Note that this trick works only if the gn_numbers field is the first item in each element, so that their addresses are identical when passed to xdr_reference().
Finally, you update gnp to point to the next item in the list. If the direction is XDR_FREE, you set it to the previously saved value. Otherwise, you can dereference gnp to get the proper value. Though harder to understand than the recursive version, this nonrecursive routine runs more efficiently because much of the procedure call overhead has been removed. Most lists are small, in the hundreds of items or less, and the recursive version should be sufficient for them.
- © 2010, Oracle Corporation and/or its affiliates