# Compaq TCP/IP Services for OpenVMS
ONC RPC Programming

Previous | Contents | Index

### 4.2.5.3 Variable-Length Arrays of Arbitrary Data Elements

The XDR library 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` in addition to two more: the size of array elements and an XDR routine to handle each of the elements.

This routine encodes or decodes each array element:

    bool_t
    xdr_array(xdrs, ap, lp, maxlength, elementsiz, xdr_element)
         XDR *xdrs;
         char **ap;
         u_int *lp;
         u_int maxlength;
         u_int elementsiz;
         bool_t (*xdr_element)();

The parameter `ap` is a pointer to 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 allowable number of array elements; `elementsiz` is the byte size of each array element. (You can also use the C function `sizeof` to obtain this value.) The `xdr_element` routine is called to serialize, deserialize, or free each element of the array.

Examples 4_1, 4_2, and 4-3 show the recursiveness of the XDR library routines already discussed.

A user on a networked system can be identified in three ways:

- The system name, such as `krypton` (use the `gethostname` socket routine)
- The user's UID (use the `geteuid` run-time routine)
- On UNIX systems, the group numbers to which the user belongs (not implemented on OpenVMS systems)

Example 4-1 shows how a structure with this information and its associated XDR routine could be coded:

Example 4-1 Structure and Associated XDR Routine

    struct netuser {
         char    *nu_systemname;
         int     nu_uid;
         u_int   nu_glen;
         int     *nu_gids;
    };
    #define NLEN 255        /* system 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_systemname, NLEN) &&
           xdr_int(xdrs, &nup->nu_uid) &&
           xdr_array(xdrs, &nup->nu_gids, &nup->nu_glen,
           NGRPS, sizeof (int), xdr_int));
    }

A party of network users could be implemented as an array of `netuser` structure. Example 4-2 shows the declaration and its associated XDR routines.

Example 4-2 Declaration and Associated XDR Routines

    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));
    }

The parameters to `main` ( `argc` and `argv` ) can be combined into a structure, and an array of these structures can make up a history of commands. Example 4-3 shows how the declarations and XDR routines might look.

Example 4-3 Declarations and XDR Routines

    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));
    }

In Example 4-3, 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` .

### 4.2.5.4 Fixed-Length Arrays of Arbitrary Data Elements

The XDR library provides a primitive, `xdr_vector` , for fixed-length arrays:

    #define NLEN 255        /* system names must be < 256 chars */
    #define NGRPS 20        /* user belongs to exactly 20 groups */

    struct netuser {
         char *nu_systemname;
         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_systemname, 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);
    }

### 4.2.5.5 Opaque Data

Some protocols pass handles from a server to a client. The client later passes back the handles, without first inspecting them; that is, handles are opaque. The `xdr_opaque` primitive describes fixed-size, opaque bytes:

    bool_t xdr_opaque(xdrs, p, len)
         XDR *xdrs;
         char *p;
         u_int len;

The first parameter `xdrs` is the XDR stream handle. The second parameter `p` is the location of the bytes and the third parameter `len` is the number of bytes in the opaque object. By definition, the data within the opaque object is not system-portable.

### 4.2.5.6 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 */

In this example, the routine translates the discriminant of the union at `*dscmp` . The discriminant is always an `enum_t` . Next, the union 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 `proc` is called to translate the union. The end of the `xdr_discrim` structure array is denoted by a routine of value `NULL` . If the discriminant is not in the `arms` array, then the `defaultarm` procedure is called if it is non-null; otherwise, the routine returns FALSE.

Example 4-4 shows how to serialize or deserialize a discriminated union. In the example, suppose that the type of a union is an integer, character pointer (a string), or a `gnumbers` structure (described in Section 4.1.2). Also, assume the union and its current type are declared in a structure, as follows:

    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 4-4 shows the constructs and XDR procedure that serialize or deserialize the discriminated union:

Example 4-4 Constructs and XDR Procedure

    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 discussed in Section 4.1.2 and `xdr_wrapstring` was presented in Example 4-3. The default arm parameter to `xdr_union` (the last parameter) is `NULL` in Example 4-4. Therefore, the value of the union's discriminant can only be a value listed in the `u_tag_arms` array. Example 4-4 also shows that the elements of the arm's array do not need to be sorted.

The values of the discriminant may be sparse, though in Example 4-4 they are not. It is always good practice to explicitly assign integer values to each element of the discriminant's type. This will document the external representation of the discriminant and guarantee that different C compilers provide identical discriminant values.

### 4.2.5.7 Pointers

In C it is useful to put within a structure any pointers to another structure. The `xdr_reference` primitive makes it easy to serialize, deserialize, and free these referenced structures. A structure of structure pointers is shown here:

    bool_t xdr_reference(xdrs, pp, size, proc)
         XDR *xdrs;
         char **pp;
         u_int ssize;
         bool_t (*proc)();

Parameter `xdrs` is the XDR stream handle, `pp` is a pointer to the pointer to the structure, `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 a structure within a structure, because pointers are always sufficient.

Note The `xdr_reference` and `xdr_array` primitives are not interchangeable external representations of data.

The following example describes a structure (and its corresponding XDR routine) that contains an item of data and a pointer to a `gnumbers` structure that has more information about that item of data.

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. This structure has the following construct:

    struct pgn {
         char *name;
         struct gnumbers *gnp;
    };

This structure has the following corresponding XDR routine:

    bool_t
    xdr_pgn(xdrs, pp)
         XDR *xdrs;
         struct pgn *pp;
    {
         if (xdr_string(xdrs, &pp->name, NLEN) &&
           xdr_reference(xdrs, &pp->gnp,
           sizeof(struct gnumbers), xdr_gnumbers))
              return(TRUE);
         return(FALSE);
    }

In many applications, C programmers attach double meaning to the values of a pointer. Typically the value `NULL` means data is not necessary, but 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 example, in the previous structure, 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.

During serialization, the primitive `xdr_reference` cannot attach any special meaning to a pointer with the value `NULL` . That is, passing a pointer to a pointer whose value is `NULL` to `xdr_reference` when serializing data will most likely cause a memory fault and a core dump.

The `xdr_pointer` correctly handles `NULL` pointers. For more information about its use, see Section 4.5.

## 4.2.6 Non-filter Primitives

The non-filter primitives that follow are for manipulating XDR streams:

    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_getpos` returns an unsigned integer that describes the current position in the data stream.

Note In some XDR streams, the returned value of `xdr_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` . However, 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 explicitly out of bounds. The definition of bounds varies according to the stream.

The `xdr_destroy` primitive destroys the XDR stream. Usage of the stream after calling this routine is undefined.

# 4.3 XDR Operation Directions

Though not recommended, you may want to optimize XDR routines by using the direction of the operation: `XDR_ENCODE` , `XDR_DECODE` , or `XDR_FREE` . For example, the value `xdrs->x_op` contains the direction of the XDR operation. An example in Section 4.5 shows the usefulness of the `xdrs->x_op` field.

# 4.4 XDR Stream Access

An XDR stream is obtained by calling the appropriate creation routine, which takes arguments for the specific properties of the stream. Streams currently exist for serialization or deserialization of data to or from standard I/O FILE streams, TCP/IP connections and files, and memory.

## 4.4.1 Standard I/O Streams

XDR streams can be interfaced to standard I/O using the `xdrstdio_create` routine as follows:

    #include <stdio.h>
    #include <rpc/rpc.h>    /* XDR streams part of RPC */

    void
    xdrstdio_create(xdrs, fp, x_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.

## 4.4.2 Memory Streams

A memory stream enables 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 that 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 UDP/IP implementation of ONC RPC uses `xdrmem_create` . Complete call or result messages are built-in memory before calling the `sendto` system routine.

## 4.4.3 Record (TCP/IP) Streams

A record stream is an XDR stream built on top of a record-marking standard that is, in turn, built on top of a file or a Berkeley UNIX 4.2 BSD connection interface, as shown:

    #include <rpc/rpc.h>    /* xdr streams 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 ordinary files.

The parameter `xdrs` is similar to the corresponding parameter described in Section 4.4.1. 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, defaults are used. When a buffer needs to be filled or flushed, the routine `readproc` or `writeproc` is called, respectively.

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 usage of these routines is similar to the system calls `read` and `write` . However, the first parameter to each routine is the opaque parameter `iohandle` . The other two parameters ( `buf` and `nbytes` ) and the results (byte count) are identical to the system routines.

The XDR stream enables you to delimit records in the byte stream. This is discussed in Section 4.5. The following primitives are specific to record streams:

    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. This does not mean that there is no more data in the underlying file descriptor.

## 4.4.4 XDR Stream Implementation

This section provides the abstract data types needed to implement new instances of XDR streams. The following structure defines the interface to an XDR stream:

    enum xdr_op { XDR_ENCODE=0, XDR_DECODE=1, XDR_FREE=2 };

    typedef struct {
         enum xdr_op x_op;             /* operation; fast added param */
         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 */
         } *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 is not expected to affect the implementation of a stream. The fields `x_private` , `x_base` , and `x_handy` pertain to a particular stream implementation. The field `x_public` is for the XDR client and must not be used by the XDR stream implementations or the XDR primitives. The macros `x_getpostn` , `x_setpostn` , and `x_destroy` access operations. The operation `x_inline` takes 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 program can then use the buffer segment for any purpose. To the stream, the bytes in the buffer segment have been consumed or put. The routine may return `NULL` if it cannot return a buffer segment of the requested size. (The `x_inline` routine is for maximizing efficient use of processor cycles. The resulting buffer is not data portable, so using this feature is not recommended.)

The operations `x_getbytes` and `x_putbytes` get and put sequences of bytes from or to the underlying stream; they return TRUE if successful, and FALSE otherwise. The routines have identical parameters (replace `xxx` with either `x_get` or `x_put` ):

    bool_t
    xxxbytes(xdrs, buf, bytecount)
         XDR *xdrs;
         char *buf;
         u_int bytecount;

The `x_getlong` and `x_putlong` routines receive and put long numbers to and from the data stream. These routines must translate the numbers between the system representation and the (standard) external representation. The operating system primitives `htonl` and `ntohl` help to do this. The higher-level XDR implementation assumes that signed and unsigned long 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 if they do not. They have identical parameters (replace `xxx` with either `x_get` or `x_put` ):

    bool_t
    xxxlong(xdrs, lp)
         XDR *xdrs;
         long *lp;

Implementors of new XDR streams must make an XDR structure (with new operation routines) available to clients, using some kind of creation routine.

Previous | Next | Contents | Index