'\" te
.\"  Copyright 1989 AT&T  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH XDR_ADMIN 3NSL "Dec 30, 1996"
.SH NAME
xdr_admin, xdr_control, xdr_getpos, xdr_inline, xdrrec_endofrecord, xdrrec_eof,
xdrrec_readbytes, xdrrec_skiprecord, xdr_setpos, xdr_sizeof \- library routines
for external data representation
.SH DESCRIPTION
.sp
.LP
\fBXDR\fR library routines allow C programmers to describe arbitrary data
structures in a machine-independent fashion. Protocols such as remote procedure
calls (RPC) use these routines to describe the format of the data.
.sp
.LP
These routines deal specifically with the management of the \fBXDR\fR stream.
.SS "Routines"
.sp
.LP
See \fBrpc\fR(3NSL) for the definition of the \fBXDR\fR data structure. Note
that any buffers passed to the \fBXDR\fR routines must be properly aligned.  It
is suggested either that \fBmalloc\fR(3C) be used to allocate these buffers, or
that the programmer insure  that the buffer address is divisible evenly by
four.
.sp
.LP
\fB#include <rpc/xdr.h>\fR
.sp
.ne 2
.na
\fB\fBbool_t xdr_control( XDR *\fR\fIxdrs\fR\fB, int\fR\fI req\fR\fB, void
*\fR\fIinfo\fR\fB);\fR\fR
.ad
.sp .6
.RS 4n
A function macro to change or retrieve various information about an  \fBXDR\fR
stream. \fIreq\fR indicates the type of operation and \fIinfo\fR is a pointer
to the information. The supported values of \fIreq\fR is
\fBXDR_GET_BYTES_AVAIL\fR and its argument type is \fBxdr_bytesrec *\fR. They
return the number of bytes left unconsumed in the stream and a flag indicating
whether or not this is the last fragment.
.RE

.sp
.ne 2
.na
\fB\fBuint_t xdr_getpos(const XDR *\fR\fIxdrs\fR\fB);\fR\fR
.ad
.sp .6
.RS 4n
A macro that invokes the get-position routine associated with the \fBXDR\fR
stream, \fIxdrs\fR. The routine returns an unsigned integer, which indicates
the position of the \fBXDR\fR byte stream. A desirable feature of \fBXDR\fR
streams is that simple arithmetic works with this number, although the
\fBXDR\fR stream instances need not guarantee this. Therefore, applications
written for portability should not depend on this feature.
.RE

.sp
.ne 2
.na
\fB\fBlong *xdr_inline(XDR *\fR\fIxdrs\fR\fB, const int \fR\fIlen\fR\fB);\fR\fR
.ad
.sp .6
.RS 4n
A macro that invokes the in-line routine associated with the \fBXDR\fR stream,
\fIxdrs\fR. The routine returns a pointer to a contiguous piece of the stream's
buffer; \fIlen\fR is the byte length of the desired buffer. Note: pointer is
cast to \fBlong *\fR.
.sp
Warning: \fBxdr_inline()\fR may return \fINULL\fR (\fB0\fR) 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, and applications
written for portability should not depend on this feature.
.RE

.sp
.ne 2
.na
\fB\fBbool_t xdrrec_endofrecord(XDR *xdrs, int \fR\fIsendnow\fR\fB);\fR\fR
.ad
.sp .6
.RS 4n
This routine can be invoked only on streams created by \fBxdrrec_create()\fR.
See \fBxdr_create\fR(3NSL). The data in the output buffer is marked as a
completed record, and the output buffer is optionally written out if
\fIsendnow\fR is non-zero. This routine returns \fBTRUE\fR if it succeeds,
\fBFALSE\fR otherwise.
.RE

.sp
.ne 2
.na
\fB\fBbool_t xdrrec_eof(XDR *\fR\fIxdrs\fR\fB);\fR\fR
.ad
.sp .6
.RS 4n
This routine can be invoked only on streams created by \fBxdrrec_create()\fR.
After consuming the rest of the current record in the stream, this routine
returns \fBTRUE\fR if there is no more data in the stream's input buffer. It
returns  \fBFALSE\fR if there is additional data in the stream's input buffer.
.RE

.sp
.ne 2
.na
\fB\fBint xdrrec_readbytes(XDR *\fR\fIxdrs\fR\fB, caddr_t\fR\fI addr\fR\fB,
uint_t\fR\fI nbytes\fR\fB);\fR\fR
.ad
.sp .6
.RS 4n
This routine can be invoked only on streams created by \fBxdrrec_create()\fR.
It attempts to read \fInbytes\fR bytes from the \fBXDR\fR stream into the
buffer pointed to by \fIaddr\fR. Upon success this routine returns the number
of bytes read. Upon  failure, it returns \fB\(mi1\fR\&. A return value of
\fB0\fR indicates an end of record.
.RE

.sp
.ne 2
.na
\fB\fBbool_t xdrrec_skiprecord(XDR *\fR\fIxdrs\fR\fB);\fR\fR
.ad
.sp .6
.RS 4n
This routine can be invoked only on streams created by \fBxdrrec_create()\fR.
See \fBxdr_create\fR(3NSL). It tells the   \fBXDR\fR implementation that the
rest of the current record in the stream's input buffer should be discarded.
This routine returns \fBTRUE\fR if it succeeds,   \fBFALSE\fR otherwise.
.RE

.sp
.ne 2
.na
\fB\fBbool_t xdr_setpos(XDR *\fR\fIxdrs\fR\fB, const uint_t
\fR\fIpos\fR\fB);\fR\fR
.ad
.sp .6
.RS 4n
A macro that invokes the set position routine associated with the \fBXDR\fR
stream \fIxdrs\fR. The parameter \fIpos\fR is a position value obtained from
\fBxdr_getpos()\fR. This routine returns \fBTRUE\fR if the \fBXDR\fR stream was
repositioned, and \fBFALSE\fR otherwise.
.sp
Warning: it is difficult to reposition some types of \fBXDR\fR streams, so this
routine may fail with one type of stream and succeed with another. Therefore,
applications written for portability should not depend on this feature.
.RE

.sp
.ne 2
.na
\fB\fBunsigned long xdr_sizeof(xdrproc_t \fR\fIfunc\fR\fB, void
*\fR\fIdata\fR\fB);\fR\fR
.ad
.sp .6
.RS 4n
This routine returns the number of bytes required to encode \fIdata\fR using
the \fBXDR\fR filter function \fIfunc\fR, excluding potential overhead such as
\fBRPC\fR headers or record markers. \fB0\fR is returned on error. This
information might be used to select between transport protocols, or to
determine the buffer size for various lower levels of \fBRPC\fR client and
server creation routines, or to allocate storage when  \fBXDR\fR is used
outside of the \fBRPC\fR subsystem.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBmalloc\fR(3C), \fBrpc\fR(3NSL), \fBxdr_complex\fR(3NSL),
\fBxdr_create\fR(3NSL), \fBxdr_simple\fR(3NSL), \fBattributes\fR(5)