XDR Library Primitives
This section gives 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, there is sometimes a need to pre-allocate memory (or to determine memory requirements). In these instances where the developer needs to control the allocation and de-allocation of memory for XDR conversion routines to use there is a routine, xdr_sizeof(), that is used to return the number of bytes needed to encode and decode data using one of the XDR filter functions (func()). xdr_sizeof()'s output does not include RPC headers or record markers and they must be added in to get a complete accounting of the memory required. xdr_sizeof() returns a zero on error.
xdr_sizeof(xdrproc_t func, void *data)
xdr_sizeof() is specifically useful 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.
Example A-5 and Example A-6 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);
}
}
|
Example A-6 is the second xdr_sizeof() example.
Example A-6 xdr_sizeof Example #2
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 -
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.
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 may use memory management. In many cases, memory is allocated when deserializing data with XDR_DECODE. Therefore, the XDR package must provide means to de-allocate memory. This is done by an XDR operation, XDR_FREE. 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, while internally they 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 may say that a file name may 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. The direction XDR_ENCODE is easiest to understand. 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, which 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: (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 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() respectively. 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, it is appropriate to present three examples.
Array Example 1
A user on a networked machine can be identified by (a) the machine name, such as krypton; (b) the user's UID: see the geteuid man page; and (c) the group numbers to which the user belongs: see the getgroups man page. A structure with this information and its associated XDR routine could be coded as in Example A-7.
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
A party of network users could be implemented as an array of netuser structure. The declaration and its associated XDR routines are as shown in Example A-8.
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
The well-known parameters to main, argc and 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 Example A-9.
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));
}
The most confusing part of this example is that the routine xdr_wrapstring() is needed 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. Let's continue with more constructed data types.
Opaque Data
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 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 are not machine portable.
In SunOS/SVR4 there is another routine for manipulating opaque data. This routine, xdr_netobj sends counted opaque data, much like xdr_opaque(). Example A-10 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 Example A-11.
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 may be 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;
};
Example A-12 constructs and XDR procedure (de)serialize 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 above in the XDR Library section. xdr_wrapstring() was presented in example C. The default arm parameter to xdr_union() (the last parameter) is NULL in this example. Therefore the value of the union's discriminant may legally take on only values listed in the u_tag_arms array. This example also demonstrates that the elements of the arm's array do not need to be sorted.
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.
Exercise
Implement xdr_union() using the other primitives in this section.
Pointers
In C it is often convenient to put pointers to another structure within a structure. 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.
There is no need for a primitive xdr_struct() to describe structures within structures, because pointers are always sufficient.
Exercise
Implement xdr_reference() using xdr_array().
Caution - xdr_reference() and xdr_array() are NOT interchangeable external representations of data.
Pointer Example
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. 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, in example E 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 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.
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 whose value is NULL to xdr_reference() when serializing data will most likely cause a memory fault and, on the UNIX system, a core dump.
xdr_pointer() correctly handles NULL pointers.
Nonfilter Primitives
XDR streams can be manipulated 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. Warning: 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. Warning: In some XDR streams, setting a position is impossible; in such cases, xdr_setpos() will return FALSE. This routine will also fail 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 may 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 (de)serialization of data to or from standard I/O FILE streams, record streams, and UNIX files, and memory.
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 above. 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 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 as follows:
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. That is not to say that there is no more data in the underlying file descriptor.
- © 2010, Oracle Corporation and/or its affiliates