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
filter 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 oth-
erwise.
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 3.1 February 16, 1988 5