xdr_reference()--Provide Pointer Chasing within Structures

  #include <rpc/xdr.h>

  bool_t xdr_reference(XDR *xdrs,
                       caddr_t *pp,
                       u_int size,
                       const xdrproc_t proc);

The xdr_reference() function is a filter primitive that provides pointer chasing within structures. This primitive allows the serializing, deserializing, and freeing of any pointers within one structure that are referenced by another structure.

The xdr_reference() function does not attach special meaning to a null pointer during serialization, and passing the address of a null pointer may cause a memory error. Therefore, the programmer must describe data with a two-sided discriminated union. One side is used when the pointer is valid; the other side, when the pointer is null.

Pointer chasing is the substitution of the pointer itself with the actual structure it points to.

Parameters

xdrs  (Input) 

A pointer to the eXternal Data Representation (XDR) stream handle.

pp  (I/O) 

The address of the structure. When you decode data, XDR allocates storage if the pointer is NULL.

size  (Input) 

The byte size of the structure pointed to by the pp parameter.

proc  (Input) 

A translation of the structure between its C form and its external representation. This parameter is the XDR procedure that describes the structure.

Authorities

No authorization is required.

Return Value

Error Conditions

None.

Error Messages

Example

See Code disclaimer information for information pertaining to code examples.

The following example shows how xdr_reference() is used:

#include <xdr.h>

typedef struct node
{
        int              value;
        struct node *p;
} node ;

/*
 * Do not call it with p_node==NULL, because it will fail.
 */
bool_t xdr_list(XDR *xdrs, node **p_node)
{
        return xdr_reference(xdrs,(caddr_t)p_node,
        sizeof(node),(xdrproc_t)xdr_node)
}

bool_t xdr_node(XDR *xdrs, node *p_node)
{
        xdr_int(xdrs,&(p_node->value));
        return xdr_list(xdrs,&(p_node->p));
}