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.