ONC+ Developer's Guide

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.