b6cbf7203b
This patch imports the unmodified current version of NetBSD libc. The NetBSD includes are in /nbsd_include, while the libc code itself is split between lib/nbsd_libc and common/lib/libc.
515 lines
14 KiB
Groff
515 lines
14 KiB
Groff
.\" @(#)xdr.3n 2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
|
|
.\" $NetBSD: xdr.3,v 1.12 2009/10/13 21:39:55 joerg Exp $
|
|
.\"
|
|
.Dd April 17, 2003
|
|
.Dt XDR 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm xdr ,
|
|
.Nm xdr_array ,
|
|
.Nm xdr_bool ,
|
|
.Nm xdr_bytes ,
|
|
.Nm xdr_char ,
|
|
.Nm xdr_destroy ,
|
|
.Nm xdr_double ,
|
|
.Nm xdr_enum ,
|
|
.Nm xdr_float ,
|
|
.Nm xdr_free ,
|
|
.Nm xdr_getpos ,
|
|
.Nm xdr_hyper ,
|
|
.Nm xdr_inline ,
|
|
.Nm xdr_int ,
|
|
.Nm xdr_long ,
|
|
.Nm xdr_longlong_t ,
|
|
.Nm xdrmem_create ,
|
|
.Nm xdr_opaque ,
|
|
.Nm xdr_pointer ,
|
|
.Nm xdrrec_create ,
|
|
.Nm xdrrec_endofrecord ,
|
|
.Nm xdrrec_eof ,
|
|
.Nm xdrrec_skiprecord ,
|
|
.Nm xdr_reference ,
|
|
.Nm xdr_setpos ,
|
|
.Nm xdr_short ,
|
|
.Nm xdrstdio_create ,
|
|
.Nm xdr_string ,
|
|
.Nm xdr_u_char ,
|
|
.Nm xdr_u_hyper ,
|
|
.Nm xdr_u_long ,
|
|
.Nm xdr_u_longlong_t ,
|
|
.Nm xdr_u_short ,
|
|
.Nm xdr_union ,
|
|
.Nm xdr_vector ,
|
|
.Nm xdr_void ,
|
|
.Nm xdr_wrapstring
|
|
.Nd library routines for external data representation
|
|
.Sh SYNOPSIS
|
|
.Ft int
|
|
.Fn xdr_array "XDR *xdrs" "char **arrp" "u_int *sizep" "u_int maxsize" \
|
|
"u_int elsize" "xdrproc_t elproc"
|
|
.Ft int
|
|
.Fn xdr_bool "XDR *xdrs" "bool_t *bp"
|
|
.Ft int
|
|
.Fn xdr_bytes "XDR *xdrs" "char **sp" "u_int *sizep" "u_int maxsize"
|
|
.Ft int
|
|
.Fn xdr_char "XDR *xdrs" "char *cp"
|
|
.Ft void
|
|
.Fn xdr_destroy "XDR *xdrs"
|
|
.Ft int
|
|
.Fn xdr_double "XDR *xdrs" "double *dp"
|
|
.Ft int
|
|
.Fn xdr_enum "XDR *xdrs" "enum_t *ep"
|
|
.Ft int
|
|
.Fn xdr_float "XDR *xdrs" "float *fp"
|
|
.Ft void
|
|
.Fn xdr_free "xdrproc_t proc" "char *objp"
|
|
.Ft u_int
|
|
.Fn xdr_getpos "XDR *xdrs"
|
|
.Ft int
|
|
.Fn xdr_hyper "XDR *xdrs" "longlong_t *llp"
|
|
.Ft long *
|
|
.Fn xdr_inline "XDR *xdrs" "int len"
|
|
.Ft int
|
|
.Fn xdr_int "XDR *xdrs" "int *ip"
|
|
.Ft int
|
|
.Fn xdr_long "XDR *xdrs" "long *lp"
|
|
.Ft int
|
|
.Fn xdr_longlong_t "XDR *xdrs" "longlong_t *llp"
|
|
.Ft void
|
|
.Fn xdrmem_create "XDR *xdrs" "char *addr" "u_int size" \
|
|
"enum xdr_op op"
|
|
.Ft int
|
|
.Fn xdr_opaque "XDR *xdrs" "char *cp" "u_int cnt"
|
|
.Ft int
|
|
.Fn xdr_pointer "XDR *xdrs" "char **objpp" "u_int objsize" \
|
|
"xdrproc_t xdrobj"
|
|
.Ft void
|
|
.Fn xdrrec_create "XDR *xdrs" "u_int sendsize" "u_int recvsize" \
|
|
"char *handle" "int (*readit)()" "int (*writeit)()"
|
|
.Ft int
|
|
.Fn xdrrec_endofrecord "XDR *xdrs" "int sendnow"
|
|
.Ft int
|
|
.Fn xdrrec_eof "XDR *xdrs"
|
|
.Ft int
|
|
.Fn xdrrec_skiprecord "XDR *xdrs"
|
|
.Ft int
|
|
.Fn xdr_reference "XDR *xdrs" "char **pp" "u_int size" \
|
|
"xdrproc_t proc"
|
|
.Ft int
|
|
.Fn xdr_setpos "XDR *xdrs" "u_int pos"
|
|
.Ft int
|
|
.Fn xdr_short "XDR *xdrs" "short *sp"
|
|
.Ft void
|
|
.Fn xdrstdio_create "XDR *xdrs" "FILE *file" "enum xdr_op op"
|
|
.Ft int
|
|
.Fn xdr_string "XDR *xdrs" "char **sp" "u_int maxsize"
|
|
.Ft int
|
|
.Fn xdr_u_char "XDR *xdrs" "unsigned char *ucp"
|
|
.Ft int
|
|
.Fn xdr_u_hyper "XDR *xdrs" "u_longlong_t *ullp"
|
|
.Ft int
|
|
.Fn xdr_u_int "XDR *xdrs" "unsigned *up"
|
|
.Ft int
|
|
.Fn xdr_u_long "XDR *xdrs" "unsigned long *ulp"
|
|
.Ft int
|
|
.Fn xdr_u_longlong_t "XDR *xdrs" "u_longlong_t *ullp"
|
|
.Ft int
|
|
.Fn xdr_u_short "XDR *xdrs" "unsigned short *usp"
|
|
.Ft int
|
|
.Fn xdr_union "XDR *xdrs" "int *dscmp" "char *unp" \
|
|
"struct xdr_discrim *choices" "bool_t (*defaultarm)(\|)"
|
|
.Ft int
|
|
.Fn xdr_vector "XDR *xdrs" "char *arrp" "u_int size" \
|
|
"u_int elsize" "xdrproc_t elproc"
|
|
.Ft int
|
|
.Fn xdr_void "void"
|
|
.Ft int
|
|
.Fn xdr_wrapstring "XDR *xdrs" "char **sp"
|
|
.Sh 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.
|
|
.Bl -tag -width xxx
|
|
.It Fn xdr_array
|
|
A filter primitive that translates between variable-length
|
|
arrays and their corresponding external representations.
|
|
The parameter
|
|
.Fa arrp
|
|
is the address of the pointer to the array, while
|
|
.Fa sizep
|
|
is the address of the element count of the array;
|
|
this element count cannot exceed
|
|
.Fa maxsize .
|
|
The parameter
|
|
.Fa elsize
|
|
is the
|
|
.Em sizeof
|
|
each of the array's elements, and
|
|
.Fa 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.
|
|
.It Fn xdr_bool
|
|
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.
|
|
.It Fn xdr_bytes
|
|
A filter primitive that translates between counted byte
|
|
strings and their external representations.
|
|
The parameter
|
|
.Fa sp
|
|
is the address of the string pointer.
|
|
The length of the string is located at address
|
|
.Fa sizep ;
|
|
strings cannot be longer than
|
|
.Fa maxsize .
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_char
|
|
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
|
|
.Fn xdr_bytes ,
|
|
.Fn xdr_opaque
|
|
or
|
|
.Fn xdr_string .
|
|
.It Fn xdr_destroy
|
|
A macro that invokes the destroy routine associated with the XDR
|
|
stream,
|
|
.Fa xdrs .
|
|
Destruction usually involves freeing private data structures
|
|
associated with the stream.
|
|
Using
|
|
.Fa xdrs
|
|
after invoking
|
|
.Fn xdr_destroy
|
|
is undefined.
|
|
.It Fn xdr_double
|
|
A filter primitive that translates between C double precision numbers
|
|
and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_enum
|
|
A filter primitive that translates between C enums (actually integers)
|
|
and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_float
|
|
A filter primitive that translates between C floats
|
|
and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_free
|
|
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
|
|
.Em not
|
|
freed, but what it points to
|
|
.Em is
|
|
freed (recursively).
|
|
.It Fn xdr_getpos
|
|
A macro that invokes the get-position routine associated with the XDR
|
|
stream,
|
|
.Fa 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.
|
|
.It Fn xdr_hyper
|
|
A filter primitive that translates between ANSI C long long integers
|
|
and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_inline
|
|
A macro that invokes the in-line routine associated with the XDR
|
|
stream,
|
|
.Fa xdrs .
|
|
The routine returns a pointer
|
|
to a contiguous piece of the stream's buffer;
|
|
.Fa len
|
|
is the byte length of the desired buffer.
|
|
Note: pointer is cast to
|
|
.Vt "long *" .
|
|
.Pp
|
|
Warning:
|
|
.Fn xdr_inline
|
|
may return
|
|
.Dv NULL
|
|
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.
|
|
.It Fn xdr_int
|
|
A filter primitive that translates between C integers
|
|
and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_long
|
|
A filter primitive that translates between C long integers
|
|
and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_longlong_t
|
|
A filter primitive that translates between ANSI C long long integers
|
|
and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdrmem_create
|
|
This routine initializes the XDR stream object pointed to by
|
|
.Fa xdrs .
|
|
The stream's data is written to, or read from,
|
|
a chunk of memory at location
|
|
.Fa addr
|
|
whose length is no more than
|
|
.Fa size
|
|
bytes long.
|
|
The
|
|
.Fa op
|
|
determines the direction of the XDR stream (either
|
|
.Dv XDR_ENCODE ,
|
|
.Dv XDR_DECODE ,
|
|
or
|
|
.Dv XDR_FREE ) .
|
|
.It Fn xdr_opaque
|
|
A filter primitive that translates between fixed size opaque data
|
|
and its external representation.
|
|
The parameter
|
|
.Fa cp
|
|
is the address of the opaque object, and
|
|
.Fa cnt
|
|
is its size in bytes.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_pointer
|
|
Like
|
|
.Fn xdr_reference
|
|
except that it serializes
|
|
.Dv NULL
|
|
pointers, whereas
|
|
.Fn xdr_reference
|
|
does not.
|
|
Thus,
|
|
.Fn xdr_pointer
|
|
can represent recursive data structures, such as binary trees or
|
|
linked lists.
|
|
.It Fn xdrrec_create
|
|
This routine initializes the XDR stream object pointed to by
|
|
.Fa xdrs .
|
|
The stream's data is written to a buffer of size
|
|
.Fa sendsize ;
|
|
a value of zero indicates the system should use a suitable default.
|
|
The stream's data is read from a buffer of size
|
|
.Fa recvsize ;
|
|
it too can be set to a suitable default by passing a zero value.
|
|
When a stream's output buffer is full,
|
|
.Fa writeit
|
|
is called.
|
|
Similarly, when a stream's input buffer is empty,
|
|
.Fa readit
|
|
is called.
|
|
The behavior of these two routines is similar to the system calls
|
|
.Xr read 2
|
|
and
|
|
.Xr write 2 ,
|
|
except that
|
|
.Fa handle
|
|
is passed to the former routines as the first parameter.
|
|
Note: the XDR stream's
|
|
.Fa op
|
|
field must be set by the caller.
|
|
.Pp
|
|
Warning: this XDR stream implements an intermediate record stream.
|
|
Therefore there are additional bytes in the stream
|
|
to provide record boundary information.
|
|
.It Fn xdrrec_endofrecord
|
|
This routine can be invoked only on streams created by
|
|
.Fn xdrrec_create .
|
|
The data in the output buffer is marked as a completed record,
|
|
and the output buffer is optionally written out if
|
|
.Fa sendnow
|
|
is non-zero.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdrrec_eof
|
|
This routine can be invoked only on streams created by
|
|
.Fn 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.
|
|
.It Fn xdrrec_skiprecord
|
|
This routine can be invoked only on streams created by
|
|
.Fn xdrrec_create .
|
|
It tells the XDR implementation 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.
|
|
.It Fn xdr_reference
|
|
A primitive that provides pointer chasing within structures.
|
|
The parameter
|
|
.Fa pp
|
|
is the address of the pointer;
|
|
.Fa size
|
|
is the
|
|
.Em sizeof
|
|
the structure that
|
|
.Fa *pp
|
|
points to; and
|
|
.Fa proc
|
|
is an XDR procedure that filters the structure
|
|
between its C form and its external representation.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.Pp
|
|
Warning: this routine does not understand
|
|
.Dv NULL
|
|
pointers.
|
|
Use
|
|
.Fn xdr_pointer
|
|
instead.
|
|
.It Fn xdr_setpos
|
|
A macro that invokes the set position routine associated with the XDR
|
|
stream
|
|
.Fa xdrs .
|
|
The parameter
|
|
.Fa pos
|
|
is a position value obtained from
|
|
.Fn xdr_getpos .
|
|
This routine returns one if the XDR stream could be repositioned,
|
|
and zero otherwise.
|
|
.Pp
|
|
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.
|
|
.It Fn xdr_short
|
|
A filter primitive that translates between C short integers
|
|
and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdrstdio_create
|
|
This routine initializes the XDR stream object pointed to by
|
|
.Fa xdrs .
|
|
The XDR stream data is written to, or read from, the Standard I/O
|
|
stream
|
|
.Fa file .
|
|
The parameter
|
|
.Fa op
|
|
determines the direction of the XDR stream (either
|
|
.Dv XDR_ENCODE ,
|
|
.Dv XDR_DECODE ,
|
|
or
|
|
.Dv XDR_FREE ) .
|
|
.Pp
|
|
Warning: the destroy routine associated with such XDR streams calls
|
|
.Xr fflush 3
|
|
on the file stream, but never
|
|
.Xr fclose 3 .
|
|
.It Fn xdr_string
|
|
A filter primitive that translates between C strings and
|
|
their corresponding external representations.
|
|
Strings cannot be longer than
|
|
.Fa maxsize .
|
|
Note:
|
|
.Fa sp
|
|
is the address of the string's pointer.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_u_char
|
|
A filter primitive that translates between unsigned C characters
|
|
and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_u_hyper
|
|
A filter primitive that translates between unsigned ANSI C long long
|
|
integers and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_u_int
|
|
A filter primitive that translates between C unsigned integers
|
|
and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_u_long
|
|
A filter primitive that translates between C unsigned long integers
|
|
and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_u_longlong_t
|
|
A filter primitive that translates between unsigned ANSI C long long
|
|
integers and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_u_short
|
|
A filter primitive that translates between C unsigned short integers
|
|
and their external representations.
|
|
This routine returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_union
|
|
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
|
|
.Fa dscmp .
|
|
This discriminant is always an enum_t.
|
|
Next the union located at
|
|
.Fa unp
|
|
is translated.
|
|
The parameter
|
|
.Fa choices
|
|
is a pointer to an array of
|
|
.Fn xdr_discrim
|
|
structures.
|
|
Each structure contains an ordered pair of
|
|
.Fa [ value ,
|
|
.Fa proc ] .
|
|
If the union's discriminant is equal to the associated
|
|
.Fa value ,
|
|
then the
|
|
.Fa proc
|
|
is called to translate the union.
|
|
The end of the
|
|
.Fn xdr_discrim
|
|
structure array is denoted by a routine of value
|
|
.Dv NULL .
|
|
If the discriminant is not found in the
|
|
.Fa choices
|
|
array, then the
|
|
.Fa defaultarm
|
|
procedure is called (if it is not
|
|
.Dv NULL ) .
|
|
Returns one if it succeeds, zero otherwise.
|
|
.It Fn xdr_vector
|
|
A filter primitive that translates between fixed-length
|
|
arrays and their corresponding external representations.
|
|
The parameter
|
|
.Fa arrp
|
|
is the address of the pointer to the array, while
|
|
.Fa size
|
|
is the element count of the array.
|
|
The parameter
|
|
.Fa elsize
|
|
is the
|
|
.Em sizeof
|
|
each of the array's elements, and
|
|
.Fa 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.
|
|
.It Fn 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.
|
|
.It Fn xdr_wrapstring
|
|
A primitive that calls
|
|
.Fn xdr_string "xdrs" "sp" "MAXUN.UNSIGNED" ;
|
|
where
|
|
.Dv MAXUN.UNSIGNED
|
|
is the maximum value of an unsigned integer.
|
|
.Fn xdr_wrapstring
|
|
is handy because the RPC package passes a maximum of two XDR
|
|
routines as parameters, and
|
|
.Fn xdr_string ,
|
|
one of the most frequently used primitives, requires three.
|
|
Returns one if it succeeds, zero otherwise.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr rpc 3
|
|
.Pp
|
|
The following manuals:
|
|
.Rs
|
|
.%B "eXternal Data Representation Standard: Protocol Specification"
|
|
.Re
|
|
.Rs
|
|
.%B "eXternal Data Representation: Sun Technical Notes"
|
|
.Re
|
|
.Rs
|
|
.%A Sun Microsystems, Inc., USC-ISI
|
|
.%T "XDR: External Data Representation Standard"
|
|
.%R "RFC 1014, USC-ISI"
|
|
.%V 1014
|
|
.Re
|