'\" te
.\"  Copyright 1989 AT&T
.\" Copyright (C) 2000, 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_CREATE 3NSL "Sep 26, 2000"
.SH NAME
xdr_create, xdr_destroy, xdrmem_create, xdrrec_create, xdrstdio_create \-
library routines for external data representation stream creation
.SH SYNOPSIS
.LP
.nf
#include <rpc/xdr.h>

\fBvoid\fR \fBxdr_destroy\fR(\fBXDR *\fR\fIxdrs\fR);
.fi

.LP
.nf
\fBvoid\fR \fBxdrmem_create\fR(\fBXDR *\fR\fIxdrs\fR, \fBconst caddr_t\fR \fIaddr\fR, \fBconst uint_t\fR \fIsize\fR,
     \fBconst enum xdr_op\fR \fIop\fR);
.fi

.LP
.nf
\fBvoid\fR \fBxdrrec_create\fR(\fBXDR *\fR\fIxdrs\fR, \fBconst uint_t\fR \fIsendsz\fR, \fBconst uint_t\fR \fIrecvsz\fR,
     \fBconst caddr_t\fR \fIhandle\fR, \fBconst int (*\fR\fIreadit\fR)const void *\fIread_handle\fR,
     char *\fIbuf\fR, const int \fIlen\fR, \fBconst int (*\fR\fIwriteit\fR)
     const void *\fIwrite_handle\fR, const char *\fIbuf\fR, const int \fIlen\fR);
.fi

.LP
.nf
\fBvoid\fR \fBxdrstdio_create\fR(\fBXDR *\fR\fIxdrs\fR, \fBFILE *\fR
     \fIfile\fR, \fBconst enum xdr_op\fR \fIop\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \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 with the creation of  \fBXDR\fR streams, which must be
created before any data can be translated into \fBXDR\fR format.
.SS "Routines"
.sp
.LP
See \fBrpc\fR(3NSL) for the definition of the \fBXDR\fR \fBCLIENT\fR and
\fBSVCXPRT\fR data structures. Any buffers passed to the \fBXDR\fR routines
must be properly aligned. Use \fBmalloc\fR(3C) to allocate these buffers or be
sure that the buffer address is divisible evenly by four.
.sp
.ne 2
.na
\fB\fBxdr_destroy()\fR\fR
.ad
.RS 21n
A macro that invokes the destroy routine associated with the \fBXDR\fR stream,
\fIxdrs\fR. Private data structures associated with the stream are freed.
Using \fIxdrs\fR after \fBxdr_destroy()\fR is invoked is undefined.
.RE

.sp
.ne 2
.na
\fB\fBxdrmem_create()\fR\fR
.ad
.RS 21n
This routine initializes the \fBXDR\fR stream object pointed to by \fIxdrs\fR.
The stream's data is written to or read from a chunk of memory at location
\fIaddr\fR whose length is no less than \fIsize\fR bytes long.  The \fIop\fR
determines the direction of the \fBXDR\fR stream. The value of \fIop\fR can be
either \fBXDR_ENCODE\fR, \fBXDR_DECODE\fR, or \fBXDR_FREE\fR.
.RE

.sp
.ne 2
.na
\fB\fBxdrrec_create()\fR\fR
.ad
.RS 21n
This routine initializes the read-oriented \fBXDR\fR stream object pointed to
by \fIxdrs\fR. The stream's data is written to a buffer of size \fIsendsz\fR. A
value of \fB0\fR indicates the system should use a suitable default.  The
stream's data is read from a buffer of size \fIrecvsz\fR. It too can be set to
a suitable default by passing a \fB0\fR value.  When a stream's output buffer
is full, \fIwriteit\fR is called.  Similarly, when a stream's input buffer is
empty, \fBxdrrec_create()\fR calls \fIreadit\fR. The behavior of these two
routines is similar to the system calls \fBread()\fR and \fBwrite()\fR,  except
that an appropriate handle, \fIread_handle\fR or \fIwrite_handle\fR, is passed
to the former routines as the first parameter instead of a file descriptor. See
\fBread\fR(2) and \fBwrite\fR(2), respectively. The \fBXDR\fR stream's \fIop\fR
field must be set by the caller.
.sp
This \fBXDR\fR stream implements an intermediate record stream. Therefore,
additional bytes in the stream are provided for record boundary information.
.RE

.sp
.ne 2
.na
\fB\fBxdrstdio_create()\fR\fR
.ad
.RS 21n
This routine initializes the \fBXDR\fR stream object pointed to by \fIxdrs\fR.
The \fBXDR\fR stream data is written to or read from the standard \fBI/O\fR
stream \fBfile\fR. The parameter \fIop\fR determines the direction of the
\fBXDR\fR stream. The value of \fIop\fR can be either \fBXDR_ENCODE\fR,
\fBXDR_DECODE\fR, or \fBXDR_FREE\fR.
.sp
The destroy routine associated with \fBXDR\fR streams calls \fBfflush()\fR on
the \fIfile\fR stream, but never \fBfclose()\fR. See \fBfclose\fR(3C).
.RE

.sp
.LP
A failure of any of these functions can be detected by first initializing  the
\fIx_ops\fR field in the \fBXDR\fR structure (\fIxdrs\fR-> \fIx_ops\fR) to
\fINULL\fR before calling the  \fBxdr*_create()\fR function.  If the
\fIx_ops\fR field is still  \fINULL,\fR after the return from the
\fBxdr*_create()\fR function, the call has failed.  If the \fIx_ops\fR field
contains some other value, assume that the call has succeeded.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

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

.SH SEE ALSO
.sp
.LP
.BR read (2),
.BR write (2),
.BR fclose (3C),
.BR malloc (3C),
.BR rpc (3NSL),
.BR xdr_admin (3NSL),
.BR xdr_complex (3NSL),
.BR xdr_simple (3NSL),
.BR attributes (7)