usr/src/man/man3nsl/xdr_complex.3nsl

   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_COMPLEX 3NSL "Dec 30, 1996"
   7 .SH NAME
   8 xdr_complex, xdr_array, xdr_bytes, xdr_opaque, xdr_pointer, xdr_reference,
   9 xdr_string, xdr_union, xdr_vector, xdr_wrapstring \- library routines for
  10 external data representation
  11 .SH DESCRIPTION
  12 .sp
  13 .LP
  14 \fBXDR\fR library routines allow C programmers to describe complex 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. These
  17 routines are the \fBXDR\fR library routines for complex data structures. They
  18 require the creation of \fBXDR\fR streams. See \fBxdr_create\fR(3NSL).
  19 .SS "Routines"
  20 .sp
  21 .LP
  22 See \fBrpc\fR(3NSL) for the definition of the \fBXDR\fR data structure. Note
  23 that any buffers passed to the \fBXDR\fR routines must be properly aligned. It
  24 is suggested either that \fBmalloc()\fR be used to allocate these buffers, or
  25 that the programmer insure  that the buffer address is divisible evenly by
  26 four.
  27 .sp
  28 .LP
  29 \fB#include <rpc/xdr.h>\fR
  30 .sp
  31 .ne 2
  32 .na
  33 \fBbool_t xdr_array(XDR *\fIxdrs\fR, caddr_t *\fIarrp\fR, uint_t *\fIsizep\fR,
  34 const uint_t \fImaxsize\fR, const uint_t \fIelsize\fR, const xdrproc_t
  35 \fIelproc\fR);\fR
  36 .ad
  37 .sp .6
  38 .RS 4n
  39 \fBxdr_array()\fR translates between variable-length arrays and their
  40 corresponding external representations. The parameter \fIarrp\fR is the address
  41 of the pointer to the array, while \fIsizep\fR is the address of the element
  42 count of the array; this element count cannot exceed \fImaxsize\fR. The
  43 parameter \fIelsize\fR is the size of each of the array's elements, and
  44 \fIelproc\fR is an \fBXDR\fR routine that translates between the array
  45 elements' C form and their external representation. If \fB*\fR\fIaarp\fR is
  46 \fINULL\fR when decoding, \fB xdr_array()\fR allocates memory and
  47 \fB*\fR\fIaarp\fR points to it. This routine returns \fBTRUE\fR if it succeeds,
  48 \fBFALSE\fR otherwise.
  49 .RE
  50
  51 .sp
  52 .ne 2
  53 .na
  54 \fBbool_t xdr_bytes(XDR *\fIxdrs\fR, char **\fIsp\fR, uint_t *\fIsizep\fR,
  55 const uint_t \fImaxsize\fR);\fR
  56 .ad
  57 .sp .6
  58 .RS 4n
  59 \fBxdr_bytes()\fR translates between counted byte strings and their external
  60 representations. The parameter \fIsp\fR is the address of the string pointer.
  61 The length of the string is located at address \fIsizep\fR; strings cannot be
  62 longer than \fImaxsize\fR. If \fB*\fR\fIsp\fR is  \fINULL\fR when decoding,
  63 \fBxdr_bytes()\fR allocates memory and \fB*\fR\fIsp\fR points to it. This
  64 routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fBbool_t xdr_opaque(XDR *\fIxdrs\fR, caddr_t \fIcp\fR, const uint_t
  71 \fIcnt\fR);\fR
  72 .ad
  73 .sp .6
  74 .RS 4n
  75 \fBxdr_opaque()\fR translates between fixed size opaque data and its external
  76 representation. The parameter \fBcp\fR is the address of the opaque object, and
  77 \fIcnt\fR is its size in bytes. This routine returns \fBTRUE\fR if it succeeds,
  78 \fBFALSE\fR otherwise.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fBbool_t xdr_pointer(XDR *\fIxdrs\fR, char **objpp, uint_t \fIobjsize\fR,
  85 const xdrproc_t \fIxdrobj\fR);\fR
  86 .ad
  87 .sp .6
  88 .RS 4n
  89 Like \fBxdr_reference()\fR except that it serializes null pointers, whereas
  90 \fBxdr_reference()\fR does not.  Thus, \fBxdr_pointer()\fR can represent
  91 recursive data structures, such as binary trees or linked lists. If
  92 \fB*\fR\fIobjpp\fR is  \fINULL\fR when decoding, \fBxdr_pointer()\fR allocates
  93 memory and \fB*\fR\fIobjpp\fR points to it.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fBbool_t xdr_reference(XDR *\fIxdrs\fR, caddr_t *\fIpp\fR, uint_t \fIsize\fR,
 100 const xdrproc_t \fIproc\fR);\fR
 101 .ad
 102 .sp .6
 103 .RS 4n
 104 \fBxdr_reference()\fR provides pointer chasing within structures.  The
 105 parameter \fIpp\fR is the address of the pointer; \fBsize\fR is the
 106 \fBsizeof\fR the structure that \fI*pp\fR points to; and \fBproc\fR is an
 107 \fBXDR\fR procedure that translates the structure between its C form and its
 108 external representation. If \fB*\fR\fIpp\fR is  \fINULL\fR when decoding,
 109 \fBxdr_reference()\fR allocates memory and \fB*\fR\fIpp\fR points to it.  This
 110 routine returns \fB1\fR if it succeeds, \fB0\fR otherwise.
 111 .sp
 112 Warning: this routine does not understand null pointers. Use
 113 \fBxdr_pointer()\fR instead.
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fBbool_t xdr_string(XDR *\fIxdrs\fR, char **\fIsp\fR, const uint_t
 120 \fImaxsize\fR);\fR
 121 .ad
 122 .sp .6
 123 .RS 4n
 124 \fBxdr_string()\fR translates between C strings and their corresponding
 125 external representations. Strings cannot be longer than \fImaxsize\fR. Note:
 126 \fIsp\fR is the address of the string's pointer. If \fB*\fR\fIsp\fR is
 127 \fINULL\fR when decoding, \fBxdr_string()\fR allocates memory and
 128 \fB*\fR\fIsp\fR points to it. This routine returns \fBTRUE\fR if it succeeds,
 129 \fBFALSE\fR otherwise. Note: \fBxdr_string()\fR can be used to send an empty
 130 string ("\|"), but not a null string.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fBbool_t xdr_union(XDR *\fIxdrs\fR, enum_t *\fIdscmp\fR, char *\fIunp\fR,
 137 const struct xdr_discrim *\fIchoices\fR, const xdrproc_t
 138 (*\fIdefaultarm\fR));\fR
 139 .ad
 140 .sp .6
 141 .RS 4n
 142 \fBxdr_union()\fR translates between a discriminated C \fBunion\fR and its
 143 corresponding external representation. It first translates the discriminant of
 144 the union located at \fIdscmp\fR. This discriminant is always an \fBenum_t\fR.
 145 Next the union located at \fIunp\fR is translated.  The parameter \fIchoices\fR
 146 is a pointer to an array of \fBxdr_discrim\fR structures. Each structure
 147 contains an ordered pair of [\fIvalue, proc\fR]. If the union's discriminant is
 148 equal to the associated \fIvalue\fR, then the \fBproc\fR is called to translate
 149 the union. The end of the \fBxdr_discrim\fR structure array is denoted by a
 150 routine of value \fINULL\fR. If the discriminant is not found in the
 151 \fIchoices\fR array, then the \fIdefaultarm\fR procedure is called (if it is
 152 not \fINULL\fR). It returns \fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise.
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fBbool_t xdr_vector(XDR *\fIxdrs\fR, char *\fIarrp\fR, const uint_t
 159 \fIsize\fR, const uint_t \fIelsize\fR, const xdrproc_t \fIelproc\fR);\fR
 160 .ad
 161 .sp .6
 162 .RS 4n
 163 \fBxdr_vector()\fR translates between fixed-length arrays and their
 164 corresponding external representations. The parameter \fIarrp\fR is the address
 165 of the pointer to the array, while \fBsize\fR is the element count of the
 166 array. The parameter \fIelsize\fR is the \fBsizeof\fR each of the array's
 167 elements, and \fIelproc\fR is an \fBXDR\fR routine that translates between the
 168 array elements' C form and their external representation. This routine returns
 169 \fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise.
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fBbool_t xdr_wrapstring(XDR *\fIxdrs\fR, char **\fIsp\fR);\fR
 176 .ad
 177 .sp .6
 178 .RS 4n
 179 A routine that calls \fBxdr_string(\fR\fIxdrs\fR\fB,\fR \fIsp\fR\fB,
 180 \fR\fImaxuint\fR\fB);\fR where \fImaxuint\fR is the maximum value of an
 181 unsigned integer.
 182 .sp
 183 Many routines, such as \fBxdr_array()\fR, \fBxdr_pointer()\fR, and
 184 \fBxdr_vector()\fR take a function pointer of type \fBxdrproc_t()\fR, which
 185 takes two arguments. \fBxdr_string()\fR, one of the most frequently used
 186 routines, requires three arguments, while \fBxdr_wrapstring()\fR only requires
 187 two. For these routines, \fBxdr_wrapstring()\fR is desirable. This routine
 188 returns \fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise.
 189 .RE
 190
 191 .SH ATTRIBUTES
 192 .sp
 193 .LP
 194 See \fBattributes\fR(5) for descriptions of the following attributes:
 195 .sp
 196
 197 .sp
 198 .TS
 199 box;
 200 c | c
 201 l | l .
 202 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 203 _
 204 MT-Level        Safe
 205 .TE
 206
 207 .SH SEE ALSO
 208 .sp
 209 .LP
 210 \fBmalloc\fR(3C), \fBrpc\fR(3NSL), \fBxdr_admin\fR(3NSL),
 211 \fBxdr_create\fR(3NSL), \fBxdr_simple\fR(3NSL), \fBattributes\fR(5)