xdr - library routines for external data representation


SYNOPSIS AND DESCRIPTION

       These  routines  allow C programmers to describe arbitrary
       data structures in a  machine-independent  fashion.   Data
       for  remote  procedure  calls  are transmitted using these
       routines.

       xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)
       XDR *xdrs;
       char **arrp;
       u_int *sizep, maxsize, elsize;
       xdrproc_t elproc;

              A filter primitive that  translates  between  vari­
              able-length arrays and their corresponding external
              representations. The parameter arrp is the  address
              of  the  pointer  to  the array, while sizep is the
              address of the element count  of  the  array;  this
              element count cannot exceed maxsize.  The parameter
              elsize is the sizeof each of the array's  elements,
              and elproc is an XDR filter that translates between
              the array elements' C form, and their external rep­
              resentation.   This  routine returns one if it suc­
              ceeds, zero otherwise.

       xdr_bool(xdrs, bp)
       XDR *xdrs;
       bool_t *bp;

              A filter primitive that translates between booleans
              (C  integers)  and  their external representations.
              When encoding data, this filter produces values  of
              either one or zero.  This routine returns one if it
              succeeds, zero otherwise.

       xdr_bytes(xdrs, sp, sizep, maxsize)
       XDR *xdrs;
       char **sp;
       u_int *sizep, maxsize;

              A filter primitive that translates between  counted
              byte  strings  and  their external representations.
              The parameter sp  is  the  address  of  the  string
              pointer.  The  length  of  the string is located at
              address sizep; strings cannot be longer  than  max­
              size.   This  routine  returns  one if it succeeds,
              zero otherwise.

       xdr_char(xdrs, cp)
       XDR *xdrs;
       char *cp;

              acters  and  their  external representations.  This
              routine returns one if it succeeds, zero otherwise.
              Note: encoded characters are not packed, and occupy
              4 bytes each.  For  arrays  of  characters,  it  is
              worthwhile to consider xdr_bytes(), xdr_opaque() or
              xdr_string().

       void
       xdr_destroy(xdrs)
       XDR *xdrs;

              A macro that invokes the destroy routine associated
              with  the  XDR  stream,  xdrs.  Destruction usually
              involves freeing private data structures associated
              with   the   stream.   Using  xdrs  after  invoking
              xdr_destroy() is undefined.

       xdr_double(xdrs, dp)
       XDR *xdrs;
       double *dp;

              A filter primitive that translates between C double
              precision  numbers  and  their external representa­
              tions.  This routine returns one  if  it  succeeds,
              zero otherwise.

       xdr_enum(xdrs, ep)
       XDR *xdrs;
       enum_t *ep;

              A  filter primitive that translates between C enums
              (actually integers) and their external  representa­
              tions.   This  routine  returns one if it succeeds,
              zero otherwise.

       xdr_float(xdrs, fp)
       XDR *xdrs;
       float *fp;

              A filter primitive that translates between C floats
              and  their  external representations.  This routine
              returns one if it succeeds, zero otherwise.

       void
       xdr_free(proc, objp)
       xdrproc_t proc;
       char *objp;

              Generic freeing routine. The first argument is  the
              XDR  routine for the object being freed. The second
              argument is a pointer to the object  itself.  Note:
              the  pointer  passed  to this routine is not freed,
              but what it points to is freed (recursively).

       xdr_getpos(xdrs)
       XDR *xdrs;

              A macro that invokes the get-position routine asso­
              ciated  with  the  XDR  stream,  xdrs.  The routine
              returns an unsigned integer,  which  indicates  the
              position  of the XDR byte stream.  A desirable fea­
              ture of XDR streams is that simple arithmetic works
              with this number, although the XDR stream instances
              need not guarantee this.

       long *
       xdr_inline(xdrs, len)
       XDR *xdrs;
       int len;

              A macro that invokes the in-line routine associated
              with  the  XDR stream, xdrs.  The routine returns a
              pointer to  a  contiguous  piece  of  the  stream's
              buffer;  len  is  the  byte  length  of the desired
              buffer.  Note: pointer is cast to long *.

              Warning: xdr_inline() may return  NULL  (0)  if  it
              cannot  allocate  a  contiguous  piece of a buffer.
              Therefore  the  behavior  may  vary  among   stream
              instances; it exists for the sake of efficiency.

       xdr_int(xdrs, ip)
       XDR *xdrs;
       int *ip;

              A  filter primitive that translates between C inte­
              gers and their external representations.  This rou­
              tine returns one if it succeeds, zero otherwise.

       xdr_long(xdrs, lp)
       XDR *xdrs;
       long *lp;

              A  filter  primitive that translates between C long
              integers and their external representations.   This
              routine returns one if it succeeds, zero otherwise.

       void
       xdrmem_create(xdrs, addr, size, op)
       XDR *xdrs;
       char *addr;
       u_int size;
       enum xdr_op op;

              This routine  initializes  the  XDR  stream  object
              pointed  to  by xdrs.  The stream's data is written
              to, or read from, a chunk  of  memory  at  location

              The op determines the direction of the  XDR  stream
              (either XDR_ENCODE, XDR_DECODE, or XDR_FREE).

       xdr_opaque(xdrs, cp, cnt)
       XDR *xdrs;
       char *cp;
       u_int cnt;

              A  filter  primitive  that translates between fixed
              size opaque data and its  external  representation.
              The  parameter  cp  is  the  address  of the opaque
              object, and cnt is its size in bytes.  This routine
              returns one if it succeeds, zero otherwise.

       xdr_pointer(xdrs, objpp, objsize, xdrobj)
       XDR *xdrs;
       char **objpp;
       u_int objsize;
       xdrproc_t xdrobj;

              Like xdr_reference() execpt that it serializes NULL
              pointers, whereas xdr_reference() does not.   Thus,
              xdr_pointer()  can  represent recursive data struc­
              tures, such as binary trees or linked lists.

       void
       xdrrec_create(xdrs, sendsize, recvsize, handle, readit, writeit)
       XDR *xdrs;
       u_int sendsize, recvsize;
       char *handle;
       int (*readit) (), (*writeit) ();

              This routine  initializes  the  XDR  stream  object
              pointed  to  by xdrs.  The stream's data is written
              to a buffer of size sendsize; a value of zero indi­
              cates the system should use a suitable default. The
              stream's data is read from a buffer of  size  recv­
              size;  it  too  can be set to a suitable default by
              passing a  zero  value.   When  a  stream's  output
              buffer is full, writeit is called.  Similarly, when
              a stream's input buffer is empty, readit is called.
              The  behavior  of  these two routines is similar to
              the system calls read and write, except that handle
              is  passed  to  the  former  routines  as the first
              parameter.  Note: the XDR stream's op field must be
              set by the caller.

              Warning: this XDR stream implements an intermediate
              record  stream.   Therefore  there  are  additional
              bytes  in  the  stream  to  provide record boundary
              information.

       xdrrec_endofrecord(xdrs, sendnow)

       int sendnow;

              This routine can be invoked only on streams created
              by  xdrrec_create().  The data in the output buffer
              is marked as a completed  record,  and  the  output
              buffer is optionally written out if sendnow is non-
              zero. This routine returns one if it succeeds, zero
              otherwise.

       xdrrec_eof(xdrs)
       XDR *xdrs;
       int empty;

              This routine can be invoked only on streams created
              by xdrrec_create().  After consuming  the  rest  of
              the  current  record  in  the  stream, this routine
              returns one if the stream has no more  input,  zero
              otherwise.

       xdrrec_skiprecord(xdrs)
       XDR *xdrs;

              This routine can be invoked only on streams created
              by xdrrec_create().  It tells the  XDR  implementa­
              tion  that  the  rest  of the current record in the
              stream's input buffer should  be  discarded.   This
              routine returns one if it succeeds, zero otherwise.

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

              A primitive that provides  pointer  chasing  within
              structures.  The parameter pp is the address of the
              pointer; size is the sizeof the structure that  *pp
              points  to;  and proc is an XDR procedure that fil­
              ters the structure  between  its  C  form  and  its
              external  representation.  This routine returns one
              if it succeeds, zero otherwise.

              Warning: this  routine  does  not  understand  NULL
              pointers. Use xdr_pointer() instead.

       xdr_setpos(xdrs, pos)
       XDR *xdrs;
       u_int pos;

              A macro that invokes the set position routine asso­
              ciated with the XDR stream xdrs.  The parameter pos
              is  a  position  value  obtained from xdr_getpos().
              This routine returns one if the XDR stream could be


              Warning:  it  is difficult to reposition some types
              of XDR streams, so this routine may fail  with  one
              type of stream and succeed with another.

       xdr_short(xdrs, sp)
       XDR *xdrs;
       short *sp;

              A  filter primitive that translates between C short
              integers and their external representations.   This
              routine returns one if it succeeds, zero otherwise.

       void
       xdrstdio_create(xdrs, file, op)
       XDR *xdrs;
       FILE *file;
       enum xdr_op op;

              This routine  initializes  the  XDR  stream  object
              pointed to by xdrs.  The XDR stream data is written
              to, or read from, the  Standard  I/O  stream  file.
              The  parameter  op  determines the direction of the
              XDR  stream  (either  XDR_ENCODE,  XDR_DECODE,   or
              XDR_FREE).

              Warning:  the  destroy routine associated with such
              XDR streams calls fflush() on the file stream,  but
              never fclose().

       xdr_string(xdrs, sp, maxsize)
       XDR
       *xdrs;
       char **sp;
       u_int maxsize;

              A   filter  primitive  that  translates  between  C
              strings and their corresponding external  represen­
              tations.   Strings  cannot  be longer than maxsize.
              Note: sp is the address of  the  string's  pointer.
              This  routine returns one if it succeeds, zero oth­
              erwise.

       xdr_u_char(xdrs, ucp)
       XDR *xdrs;
       unsigned char *ucp;

              A filter primitive that translates between unsigned
              C  characters  and  their external representations.
              This routine returns one if it succeeds, zero  oth­
              erwise.

       xdr_u_int(xdrs, up)

       unsigned *up;

              A   filter  primitive  that  translates  between  C
              unsigned integers and  their  external  representa­
              tions.   This  routine  returns one if it succeeds,
              zero otherwise.

       xdr_u_long(xdrs, ulp)
       XDR *xdrs;
       unsigned long *ulp;

              A  filter  primitive  that  translates  between   C
              unsigned long integers and their external represen­
              tations.  This routine returns one if it  succeeds,
              zero otherwise.

       xdr_u_short(xdrs, usp)
       XDR *xdrs;
       unsigned short *usp;

              A   filter  primitive  that  translates  between  C
              unsigned short integers and their  external  repre­
              sentations.   This  routine  returns one if it suc­
              ceeds, zero otherwise.

       xdr_union(xdrs, dscmp, unp, choices, dfault)
       XDR *xdrs;
       int *dscmp;
       char *unp;
       struct xdr_discrim *choices;
       bool_t (*defaultarm) ();  /* may equal NULL */

              A filter primitive that translates between  a  dis­
              criminated  C  union and its corresponding external
              representation. It first translates  the  discrimi­
              nant of the union located at dscmp.  This discrimi­
              nant is always an enum_t.  Next the  union  located
              at  unp  is translated.  The parameter choices 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 the 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  found  in  the
              choices  array,  then  the  defaultarm procedure is
              called (if it is not NULL).  Returns one if it suc­
              ceeds, zero otherwise.

       xdr_vector(xdrs, arrp, size, elsize, elproc)
       XDR *xdrs;
       char *arrp;
       u_int size, elsize;


              A  filter  primitive that translates between fixed-
              length arrays and their corresponding external rep­
              resentations.  The parameter arrp is the address of
              the pointer to the array, while size is is the ele­
              ment  count  of the array.  The parameter elsize is
              the sizeof each of the array's elements, and elproc
              is  an XDR filter that translates between the array
              elements' C form, and  their  external  representa­
              tion.   This  routine  returns  one if it succeeds,
              zero otherwise.

       xdr_void()

              This routine always returns one.  It may be  passed
              to  RPC routines that require a function parameter,
              where nothing is to be done.

       xdr_wrapstring(xdrs, sp)
       XDR *xdrs;
       char **sp;

              A    primitive    that    calls    xdr_string(xdrs,
              sp,MAXUN.UNSIGNED  );  where  MAXUN.UNSIGNED is the
              maximum   value    of    an    unsigned    integer.
              xdr_wrapstring()  is  handy because the RPC package
              passes a maximum of two XDR routines as parameters,
              and  xdr_string(),  one of the most frequently used
              primitives, requires three.  Returns one if it suc­
              ceeds, zero otherwise.


SEE ALSO

       rpc(3N)

       The following manuals:
              eXternal  Data  Representation  Standard:  Protocol
              Specification
              eXternal Data Representation: Sun Technical Notes
              XDR:   External   Data   Representation   Standard,
              RFC1014, Sun Microsystems, Inc., USC-ISI.


Man(1) output converted with man2html