XDR(3)                    OpenBSD Programmer's Manual                   XDR(3)

NAME
     xdr_array, xdr_bool, xdr_bytes, xdr_char, xdr_destroy, xdr_double,
     xdr_enum, xdr_float, xdr_free, xdr_getpos, xdr_inline, xdr_int, xdr_long,
     xdrmem_create, xdr_opaque, xdr_pointer, xdrrec_create,
     xdrrec_endofrecord, xdrrec_eof, xdrrec_skiprecord, xdr_reference,
     xdr_setpos, xdr_short, xdrstdio_create, xdr_string, xdr_u_char,
     xdr_u_int, xdr_u_long, xdr_u_short, xdr_union, xdr_vector, xdr_void,
     xdr_wrapstring - library routines for external data representation



SYNOPSIS
     #include <sys/types.h>
     #include <rpc/xdr.h>

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

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

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

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

     void
     xdr_destroy(XDR *xdrs);

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

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

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

     void
     xdr_free(xdrproc_t proc, char *objp);

     u_int
     xdr_getpos(XDR *xdrs);

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

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

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

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

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

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

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

     int
     xdrrec_endofrecord(XDR *xdrs, int sendnow);

     int
     xdrrec_eof(XDR *xdrs, int empty);

     int
     xdrrec_skiprecord(XDR *xdrs);

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

     int
     xdr_setpos(XDR *xdrs, u_int pos);

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

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

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

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

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

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

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

     int
     xdr_union(XDR *xdrs, int *dscmp, char *unp, struct xdr_discrim *choices,
             bool_t (*defaultarm)());

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

     int
     xdr_void(void);

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

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() is 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 ad-
     dress of the element count of the array; this element count cannot exceed
     maxsize. The parameter elsize is the size of each of the array's ele-
     ments, and elproc is an XDR filter that translates between the array ele-
     ments' C form, and their external representation.  This routine returns
     one if it succeeds, zero otherwise.
     xdr_bool() is a filter primitive that translates between booleans (C in-
     tegers) and their external representations. When encoding data, this fil-
     ter produces values of either one or zero.  This routine returns one if
     it succeeds, zero otherwise.

     xdr_bytes() is a filter primitive that translates between counted byte
     strings and their external representations.  The parameter sp is the ad-
     dress of the string pointer. The length of the string is located at ad-
     dress sizep; strings cannot be longer than maxsize. This routine returns
     one if it succeeds, zero otherwise.

     xdr_char() is 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().

     xdr_destroy() is 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() is a filter primitive that translates between C double pre-
     cision numbers and their external representations.  This routine returns
     one if it succeeds, zero otherwise.

     xdr_enum() is a filter primitive that translates between the C enum type
     (actually an integer) and its external representations.  This routine re-
     turns one if it succeeds, zero otherwise.

     xdr_float() is a filter primitive that translates between the C float
     type and its external representations.  This routine returns one if it
     succeeds, zero otherwise.

     xdr_free() is a 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() is 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 desirable feature of
     XDR streams is that simple arithmetic works with this number, although
     the XDR stream instances need not guarantee this.

     xdr_inline() is 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 if
     it cannot allocate a contiguous piece of a buffer.  Therefore the behav-
     ior may vary among stream instances; it exists for the sake of efficien-
     cy.

     xdr_int() is a filter primitive that translates between C integers and
     their external representations.  This routine returns one if it succeeds,
     zero otherwise.

     xdr_long() is a filter primitive that translates between C long integers
     and their external representations.  This routine returns one if it suc-
     ceeds, zero otherwise.

     xdrmem_create() is a routine which 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() is a filter primitive that translates between fixed size
     opaque data and its external representation.  The parameter cp is the ad-
     dress of the opaque object, and cnt is its size in bytes.  This routine
     returns one if it succeeds, zero otherwise.

     xdr_pointer() is like xdr_reference() execpt 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.

     xdrrec_create() is a routine which 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 indicates the system should use a suitable de-
     fault. The stream's data is read from a buffer of size recvsize; 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(), ex-
     cept 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() is a routine which 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 other-
     wise.

     xdrrec_eof() is a routine which 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() is a routine which can be invoked only on streams
     created by xdrrec_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 otherwise.

     xdr_reference() is a primitive that provides pointer chasing within
     structures.  The parameter pp is the address of the pointer; size is the
     size of the structure that *pp points to; and proc is an XDR procedure
     that filters the structure between its C form and its external represen-
     tation.  This routine returns one if it succeeds, zero otherwise.  Warn-
     ing: this routine does not understand NULL pointers. Use xdr_pointer()
     instead.

     xdr_setpos() is 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() is a filter primitive that translates between C short inte-
     gers and their external representations.  This routine returns one if it
     succeeds, zero otherwise.

     xdrstdio_create() is a routine which 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() is 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 rou-
     tine returns one if it succeeds, zero otherwise.

     xdr_u_char() is 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() is a filter primitive that translates between C unsigned in-
     tegers and their external representations.  This routine returns one if
     it succeeds, zero otherwise.

     xdr_u_long() is a filter primitive that translates between C unsigned
     long integers and their external representations.  This routine returns
     one if it succeeds, zero otherwise.

     xdr_u_short() is 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() is a filter primitive that translates between a discriminated
     C union and its corresponding external representation. It first trans-
     lates 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 struct xdr_discrim struc-
     tures. 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 struct xdr_discrim
     structure array is denoted by a routine of value NULL. If the discrimi-
     nant is not found in the choices array, then the (*defaultarm)() proce-
     dure is called (if it is not NULL). Returns one if it succeeds, zero oth-
     erwise.

     xdr_vector() is 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 the ele-
     ment count of the array.  The parameter elsize is the size of 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_void() is a routine which always returns one. It may be passed to RPC
     routines that require a function parameter, but where nothing is to be
     done.

     xdr_wrapstring() is a primitive that calls xdr_string(xdrs, sp,
     MAXUN.UNSIGNED ); where MAXUN.UNSIGNED is the maximum value of an un-
     signed 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(3)

     eXternal Data Representation Standard: Protocol Specification.

     eXternal Data Representation: Sun Technical Notes.

     Sun Microsystems, Inc., XDR: External Data Representation Standard,
     RFC1014, USC-ISI.

OpenBSD 2.6                    February 16, 1988                             5