1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH XDR_ADMIN 3NSL "Dec 30, 1996"
   7 .SH NAME
   8 xdr_admin, xdr_control, xdr_getpos, xdr_inline, xdrrec_endofrecord, xdrrec_eof,
   9 xdrrec_readbytes, xdrrec_skiprecord, xdr_setpos, xdr_sizeof \- library routines
  10 for external data representation
  11 .SH DESCRIPTION
  12 .sp
  13 .LP
  14 \fBXDR\fR library routines allow C programmers to describe arbitrary data
  15 structures in a machine-independent fashion. Protocols such as remote procedure
  16 calls (RPC) use these routines to describe the format of the data.
  17 .sp
  18 .LP
  19 These routines deal specifically with the management of the \fBXDR\fR stream.
  20 .SS "Routines"
  21 .sp
  22 .LP
  23 See \fBrpc\fR(3NSL) for the definition of the \fBXDR\fR data structure. Note
  24 that any buffers passed to the \fBXDR\fR routines must be properly aligned.  It
  25 is suggested either that \fBmalloc\fR(3C) be used to allocate these buffers, or
  26 that the programmer insure  that the buffer address is divisible evenly by
  27 four.
  28 .sp
  29 .LP
  30 \fB#include <rpc/xdr.h>\fR
  31 .sp
  32 .ne 2
  33 .na
  34 \fB\fBbool_t xdr_control(XDR *\fR\fIxdrs\fR\fB, int\fR\fI req\fR\fB, void
  35 *\fR\fIinfo\fR\fB);\fR\fR
  36 .ad
  37 .sp .6
  38 .RS 4n
  39 A function macro to change or retrieve various information about an  \fBXDR\fR
  40 stream. \fIreq\fR indicates the type of operation and \fIinfo\fR is a pointer
  41 to the information. The supported values of \fIreq\fR is
  42 \fBXDR_GET_BYTES_AVAIL\fR and its argument type is \fBxdr_bytesrec *\fR. They
  43 return the number of bytes left unconsumed in the stream and a flag indicating
  44 whether or not this is the last fragment.
  45 .RE
  46 
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fBuint_t xdr_getpos(const XDR *\fR\fIxdrs\fR\fB);\fR\fR
  51 .ad
  52 .sp .6
  53 .RS 4n
  54 A macro that invokes the get-position routine associated with the \fBXDR\fR
  55 stream, \fIxdrs\fR. The routine returns an unsigned integer, which indicates
  56 the position of the \fBXDR\fR byte stream. A desirable feature of \fBXDR\fR
  57 streams is that simple arithmetic works with this number, although the
  58 \fBXDR\fR stream instances need not guarantee this. Therefore, applications
  59 written for portability should not depend on this feature.
  60 .RE
  61 
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBlong *xdr_inline(XDR *\fR\fIxdrs\fR\fB, const int \fR\fIlen\fR\fB);\fR\fR
  66 .ad
  67 .sp .6
  68 .RS 4n
  69 A macro that invokes the in-line routine associated with the \fBXDR\fR stream,
  70 \fIxdrs\fR. The routine returns a pointer to a contiguous piece of the stream's
  71 buffer; \fIlen\fR is the byte length of the desired buffer. Note: pointer is
  72 cast to \fBlong *\fR.
  73 .sp
  74 Warning: \fBxdr_inline()\fR may return \fINULL\fR (\fB0\fR) if it cannot
  75 allocate a contiguous piece of a buffer. Therefore the behavior may vary among
  76 stream instances; it exists for the sake of efficiency, and applications
  77 written for portability should not depend on this feature.
  78 .RE
  79 
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBbool_t xdrrec_endofrecord(XDR *xdrs, int \fR\fIsendnow\fR\fB);\fR\fR
  84 .ad
  85 .sp .6
  86 .RS 4n
  87 This routine can be invoked only on streams created by \fBxdrrec_create()\fR.
  88 See \fBxdr_create\fR(3NSL). The data in the output buffer is marked as a
  89 completed record, and the output buffer is optionally written out if
  90 \fIsendnow\fR is non-zero. This routine returns \fBTRUE\fR if it succeeds,
  91 \fBFALSE\fR otherwise.
  92 .RE
  93 
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBbool_t xdrrec_eof(XDR *\fR\fIxdrs\fR\fB);\fR\fR
  98 .ad
  99 .sp .6
 100 .RS 4n
 101 This routine can be invoked only on streams created by \fBxdrrec_create()\fR.
 102 After consuming the rest of the current record in the stream, this routine
 103 returns \fBTRUE\fR if there is no more data in the stream's input buffer. It
 104 returns  \fBFALSE\fR if there is additional data in the stream's input buffer.
 105 .RE
 106 
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBint xdrrec_readbytes(XDR *\fR\fIxdrs\fR\fB, caddr_t\fR\fI addr\fR\fB,
 111 uint_t\fR\fI nbytes\fR\fB);\fR\fR
 112 .ad
 113 .sp .6
 114 .RS 4n
 115 This routine can be invoked only on streams created by \fBxdrrec_create()\fR.
 116 It attempts to read \fInbytes\fR bytes from the \fBXDR\fR stream into the
 117 buffer pointed to by \fIaddr\fR. Upon success this routine returns the number
 118 of bytes read. Upon  failure, it returns \fB\(mi1\fR\&. A return value of
 119 \fB0\fR indicates an end of record.
 120 .RE
 121 
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBbool_t xdrrec_skiprecord(XDR *\fR\fIxdrs\fR\fB);\fR\fR
 126 .ad
 127 .sp .6
 128 .RS 4n
 129 This routine can be invoked only on streams created by \fBxdrrec_create()\fR.
 130 See \fBxdr_create\fR(3NSL). It tells the   \fBXDR\fR implementation that the
 131 rest of the current record in the stream's input buffer should be discarded.
 132 This routine returns \fBTRUE\fR if it succeeds,   \fBFALSE\fR otherwise.
 133 .RE
 134 
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBbool_t xdr_setpos(XDR *\fR\fIxdrs\fR\fB, const uint_t
 139 \fR\fIpos\fR\fB);\fR\fR
 140 .ad
 141 .sp .6
 142 .RS 4n
 143 A macro that invokes the set position routine associated with the \fBXDR\fR
 144 stream \fIxdrs\fR. The parameter \fIpos\fR is a position value obtained from
 145 \fBxdr_getpos()\fR. This routine returns \fBTRUE\fR if the \fBXDR\fR stream was
 146 repositioned, and \fBFALSE\fR otherwise.
 147 .sp
 148 Warning: it is difficult to reposition some types of \fBXDR\fR streams, so this
 149 routine may fail with one type of stream and succeed with another. Therefore,
 150 applications written for portability should not depend on this feature.
 151 .RE
 152 
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBunsigned long xdr_sizeof(xdrproc_t \fR\fIfunc\fR\fB, void
 157 *\fR\fIdata\fR\fB);\fR\fR
 158 .ad
 159 .sp .6
 160 .RS 4n
 161 This routine returns the number of bytes required to encode \fIdata\fR using
 162 the \fBXDR\fR filter function \fIfunc\fR, excluding potential overhead such as
 163 \fBRPC\fR headers or record markers. \fB0\fR is returned on error. This
 164 information might be used to select between transport protocols, or to
 165 determine the buffer size for various lower levels of \fBRPC\fR client and
 166 server creation routines, or to allocate storage when  \fBXDR\fR is used
 167 outside of the \fBRPC\fR subsystem.
 168 .RE
 169 
 170 .SH ATTRIBUTES
 171 .sp
 172 .LP
 173 See \fBattributes\fR(5) for descriptions of the following attributes:
 174 .sp
 175 
 176 .sp
 177 .TS
 178 box;
 179 c | c
 180 l | l .
 181 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 182 _
 183 MT-Level        Safe
 184 .TE
 185 
 186 .SH SEE ALSO
 187 .sp
 188 .LP
 189 \fBmalloc\fR(3C), \fBrpc\fR(3NSL), \fBxdr_complex\fR(3NSL),
 190 \fBxdr_create\fR(3NSL), \fBxdr_simple\fR(3NSL), \fBattributes\fR(5)