ABCDEFGHIJKLMNOPQRSTUVWXYZ

xdr_free

XDR(3)                                                                  XDR(3)



NAME
       xdr - library routines for external data representation

SYNOPSIS AND DESCRIPTION
       These  routines  allow  C programmers to describe arbitrary data struc-
       tures 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  variable-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 representation.  This routine returns one  if  it
              succeeds, 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 maxsize.
              This routine returns one if it succeeds, zero otherwise.

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

              A filter primitive that  translates  between  C  characters  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  representations.   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  representations.   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 suc-
              ceeds, 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).

       u_int
       xdr_getpos(xdrs)
       XDR *xdrs;

              A  macro  that  invokes the get-position routine associated with
              the XDR stream, xdrs.  The routine returns an unsigned  integer,
              which  indicates  the position of the XDR byte stream.  A desir-
              able feature of XDR streams is that simple arithmetic works with
              this  number, although the XDR stream instances need not guaran-
              tee 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 integers and their
              external  representations.   This  routine  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 addr whose length is no more than size bytes
              long.  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() except that it  serializes  NULL  pointers,
              whereas  xdr_reference() does not.  Thus, xdr_pointer() can rep-
              resent recursive data structures, 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  send-
              size; a value of zero indicates 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, rea-
              dit 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)
       XDR *xdrs;
       int sendnow;

              This  routine  can  be  invoked  only on streams created by xdr-
              rec_create().  The data in the output buffer is marked as a com-
              pleted  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 xdr-
              rec_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  xdr-
              rec_create().   It tells the XDR implementation that the rest of
              the current record in the stream's input buffer should  be  dis-
              carded.   This  routine  returns one if it succeeds, zero other-
              wise.

       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 pro-
              cedure  that  filters  the  structure between its C form and its
              external representation.  This routine returns one  if  it  suc-
              ceeds, 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  associated  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 repositioned, and zero otherwise.

              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  representations.   Strings  cannot  be
              longer than maxsize.  Note: sp is the address  of  the  string's
              pointer.   This  routine returns one if it succeeds, zero other-
              wise.

       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 otherwise.

       xdr_u_int(xdrs, up)
       XDR *xdrs;
       unsigned *up;

              A filter primitive that translates between C  unsigned  integers
              and their external representations.  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 inte-
              gers  and  their external representations.  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  representations.   This  routine
              returns one if it succeeds, 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  discriminated  C
              union  and  its  corresponding external representation. It first
              translates the discriminant of the union located at dscmp.  This
              discriminant 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 succeeds, zero otherwise.

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

              A  filter  primitive that translates between fixed-length arrays
              and their corresponding external representations.  The parameter
              arrp  is  the address of the pointer to the array, while size is
              is the element 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  representation.   This  routine returns one if it suc-
              ceeds, zero otherwise.

       xdr_void()

              This routine always returns one.  It may be passed to  RPC  rou-
              tines  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 inte-
              ger.  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 succeeds, zero otherwise.

SEE ALSO
       rpc(3)

       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.



                                  1988-02-16                            XDR(3)