Developing distributed applications using ONC RPC and XDR

XDR stream access

An XDR stream is obtained by calling the appropriate creation routine. Such creation routines take arguments that are tailored to the specific properties of the stream.

Streams currently exist for the serialization and deserialization of data to or from standard I/O FILE streams, TCP/IP connections, files and memory. The section ``XDR streams implementation'' describes the XDR object and how to make new XDR streams when they are required.

Standard I/O streams

You can interface XDR streams to standard I/O by using the xdrstdio_create():

   #include <stdio.h>
   #include <rpc/rpc.h>  /xdr streams are part of the rpc library/
   
   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.

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;
           uint 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 UDP/IP implementation of RPC uses xdrmem_create(). Complete call or result messages are built into memory before calling the sendto() system 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 an ordinary file or BSD connection interface.

   #include <rpc/rpc.h>  / xdr streams are a part of the rpc library /
   
   xdrrec_create(xdrs, sendsize, recvsize, iohandle, readproc, writeproc)
           XDR xdrs;
           uint 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 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, respectively, is called. The usage and behavior of these routines are similar to the system calls read() and write().

However, the first parameter to each of these routines is the opaque parameter iohandle. The other two parameters (buf 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. 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. This does not imply that there is no more data in the underlying file descriptor.