1 '\" te
   2 .\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH XDR_SIMPLE 3NSL "Aug 27, 2001"
   8 .SH NAME
   9 xdr_simple, xdr_bool, xdr_char, xdr_double, xdr_enum, xdr_float, xdr_free,
  10 xdr_hyper, xdr_int, xdr_long, xdr_longlong_t, xdr_quadruple, xdr_short,
  11 xdr_u_char, xdr_u_hyper, xdr_u_int, xdr_u_long, xdr_u_longlong_t, xdr_u_short,
  12 xdr_void \- library routines for external data representation
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 #include <rpc/xdr.h>
  17 
  18 
  19 
  20 \fBbool_t\fR \fBxdr_bool\fR(\fBXDR *\fR\fIxdrs\fR, \fBbool_t *\fR\fIbp\fR);
  21 .fi
  22 
  23 .LP
  24 .nf
  25 \fBbool_t\fR \fBxdr_char\fR(\fBXDR *\fR\fIxdrs\fR, \fBchar *\fR\fIcp\fR);
  26 .fi
  27 
  28 .LP
  29 .nf
  30 \fBbool_t\fR \fBxdr_double\fR(\fBXDR *\fR\fIxdrs\fR, \fBdouble *\fR\fIdp\fR);
  31 .fi
  32 
  33 .LP
  34 .nf
  35 \fBbool_t\fR \fBxdr_enum\fR(\fBXDR *\fR\fIxdrs\fR, \fBenum_t *\fR\fIep\fR);
  36 .fi
  37 
  38 .LP
  39 .nf
  40 \fBbool_t\fR \fBxdr_float\fR(\fBXDR *\fR\fIxdrs\fR, \fBfloat *\fR\fIfp\fR);
  41 .fi
  42 
  43 .LP
  44 .nf
  45 \fBvoid\fR \fBxdr_free\fR(\fBxdrproc_t\fR \fIproc\fR, \fBchar *\fR\fIobjp\fR);
  46 .fi
  47 
  48 .LP
  49 .nf
  50 \fBbool_t\fR \fBxdr_hyper\fR(\fBXDR *\fR\fIxdrs\fR, \fBlonglong_t *\fR\fIllp\fR);
  51 .fi
  52 
  53 .LP
  54 .nf
  55 \fBbool_t\fR \fBxdr_int\fR(\fBXDR *\fR\fIxdrs\fR, \fBint *\fR\fIip\fR);
  56 .fi
  57 
  58 .LP
  59 .nf
  60 \fBbool_t\fR \fBxdr_long\fR(\fBXDR *\fR\fIxdrs\fR, \fBlongt *\fR\fIlp\fR);
  61 .fi
  62 
  63 .LP
  64 .nf
  65 \fBbool_t\fR \fBxdr_longlong_t\fR(\fBXDR *\fR\fIxdrs\fR, \fBlonglong_t *\fR\fIllp\fR);
  66 .fi
  67 
  68 .LP
  69 .nf
  70 \fBbool_t\fR \fBxdr_quadruple\fR(\fBXDR *\fR\fIxdrs\fR, \fBlong double *\fR\fIpq\fR);
  71 .fi
  72 
  73 .LP
  74 .nf
  75 \fBbool_t\fR \fBxdr_short\fR(\fBXDR *\fR\fIxdrs\fR, \fBshort *\fR\fIsp\fR);
  76 .fi
  77 
  78 .LP
  79 .nf
  80 \fBbool_t\fR \fBxdr_u_char\fR(\fBXDR *\fR\fIxdrs\fR, \fBunsigned char *\fR\fIucp\fR);
  81 .fi
  82 
  83 .LP
  84 .nf
  85 \fBbool_t\fR \fBxdr_u_hyper\fR(\fBXDR *\fR\fIxdrs\fR, \fBu_longlong_t *\fR\fIullp\fR);
  86 .fi
  87 
  88 .LP
  89 .nf
  90 \fBbool_t\fR \fBxdr_u_int\fR(\fBXDR *\fR\fIxdrs\fR, \fBunsigned *\fR\fIup\fR);
  91 .fi
  92 
  93 .LP
  94 .nf
  95 \fBbool_t\fR \fBxdr_u_long\fR(\fBXDR *\fR\fIxdrs\fR, \fBunsigned long *\fR\fIulp\fR);
  96 .fi
  97 
  98 .LP
  99 .nf
 100 \fBbool_t\fR \fBxdr_u_longlong_t\fR(\fBXDR *\fR\fIxdrs\fR, \fBu_longlong_t *\fR\fIullp\fR);
 101 .fi
 102 
 103 .LP
 104 .nf
 105 \fBbool_t\fR \fBxdr_u_short\fR(\fBXDR\fR \fIxdrs\fR, \fBunsigned short *\fR\fIusp\fR);
 106 .fi
 107 
 108 .LP
 109 .nf
 110 \fBbool_t\fR \fBxdr_void\fR(void)
 111 .fi
 112 
 113 .SH DESCRIPTION
 114 .sp
 115 .LP
 116 The \fBXDR\fR library routines allow C programmers to describe simple data
 117 structures in a machine-independent fashion. Protocols such as remote procedure
 118 calls (RPC) use these routines to describe the format of the data.
 119 .sp
 120 .LP
 121 These routines require the creation of \fBXDR\fR streams (see
 122 \fBxdr_create\fR(3NSL)).
 123 .SS "Routines"
 124 .sp
 125 .LP
 126 See \fBrpc\fR(3NSL) for the definition of the  \fBXDR\fR data structure. Note
 127 that any buffers passed to the \fBXDR\fR routines must be properly aligned. It
 128 is suggested that \fBmalloc\fR(3C) be used to allocate these buffers or that
 129 the programmer insure  that the buffer address is divisible evenly by four.
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBxdr_bool()\fR\fR
 134 .ad
 135 .RS 22n
 136 \fBxdr_bool()\fR translates between booleans (C integers) and their external
 137 representations. When encoding data, this filter produces values of either
 138 \fB1\fR or \fB0\fR. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR
 139 otherwise.
 140 .RE
 141 
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fBxdr_char()\fR\fR
 146 .ad
 147 .RS 22n
 148 \fBxdr_char()\fR translates between C characters and their external
 149 representations. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR
 150 otherwise. Note: encoded characters are not packed, and occupy 4 bytes each.
 151 For arrays of characters, it is worthwhile to consider \fBxdr_bytes()\fR,
 152 \fBxdr_opaque()\fR, or \fBxdr_string()\fR (see \fBxdr_complex\fR(3NSL)).
 153 .RE
 154 
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBxdr_double()\fR\fR
 159 .ad
 160 .RS 22n
 161 \fBxdr_double()\fR translates between C \fBdouble\fR precision numbers and
 162 their external representations. This routine returns \fBTRUE\fR if it succeeds,
 163 \fBFALSE\fR otherwise.
 164 .RE
 165 
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fBxdr_enum()\fR\fR
 170 .ad
 171 .RS 22n
 172 \fBxdr_enum()\fR translates between C \fBenum\fRs (actually integers) and their
 173 external representations. This routine returns \fBTRUE\fR if it succeeds,
 174 \fBFALSE\fR otherwise.
 175 .RE
 176 
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBxdr_float()\fR\fR
 181 .ad
 182 .RS 22n
 183 \fBxdr_float()\fR translates between C \fBfloat\fRs and their external
 184 representations. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR
 185 otherwise.
 186 .RE
 187 
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fBxdr_free()\fR\fR
 192 .ad
 193 .RS 22n
 194 Generic freeing routine. The first argument is the \fBXDR\fR routine for the
 195 object being freed. The second argument is a pointer to the object itself.
 196 Note: the pointer passed to this routine is not freed, but what it points to is
 197 freed (recursively, depending on the XDR routine).
 198 .RE
 199 
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fBxdr_hyper()\fR\fR
 204 .ad
 205 .RS 22n
 206 \fBxdr_hyper()\fR translates between ANSI C  \fBlong\fR \fBlong\fR integers and
 207 their external representations. This routine returns \fBTRUE\fR if it succeeds,
 208 \fBFALSE\fR otherwise.
 209 .RE
 210 
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fBxdr_int()\fR\fR
 215 .ad
 216 .RS 22n
 217 \fBxdr_int()\fR translates between C integers and their external
 218 representations. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR
 219 otherwise.
 220 .RE
 221 
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBxdr_long()\fR\fR
 226 .ad
 227 .RS 22n
 228 \fBxdr_long()\fR translates between C \fBlong\fR integers and their external
 229 representations. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR
 230 otherwise.
 231 .sp
 232 In a 64-bit environment, this routine returns an error if the value of \fBlp\fR
 233 is outside the range \fB[INT32_MIN, INT32_MAX]\fR.  The \fBxdr_int()\fR routine
 234 is recommended in place of this routine.
 235 .RE
 236 
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fBxdr_longlong_t()\fR\fR
 241 .ad
 242 .RS 22n
 243 \fBxdr_longlong_t()\fR translates between ANSI C  \fBlong\fR \fBlong\fR
 244 integers and their external representations. This routine returns \fBTRUE\fR if
 245 it succeeds, \fBFALSE\fR otherwise. This routine is identical to
 246 \fBxdr_hyper()\fR.
 247 .RE
 248 
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fBxdr_quadruple()\fR\fR
 253 .ad
 254 .RS 22n
 255 \fBxdr_quadruple()\fR translates between IEEE quadruple precision floating
 256 point numbers and their external representations. This routine returns
 257 \fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise.
 258 .RE
 259 
 260 .sp
 261 .ne 2
 262 .na
 263 \fB\fBxdr_short()\fR\fR
 264 .ad
 265 .RS 22n
 266 \fBxdr_short()\fR translates between C \fBshort\fR integers and their external
 267 representations. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR
 268 otherwise.
 269 .RE
 270 
 271 .sp
 272 .ne 2
 273 .na
 274 \fB\fBxdr_u_char()\fR\fR
 275 .ad
 276 .RS 22n
 277 \fBxdr_u_char()\fR translates between \fBunsigned\fR C characters and their
 278 external representations. This routine returns \fBTRUE\fR if it succeeds,
 279 \fBFALSE\fR otherwise.
 280 .RE
 281 
 282 .sp
 283 .ne 2
 284 .na
 285 \fB\fBxdr_u_hyper()\fR\fR
 286 .ad
 287 .RS 22n
 288 \fBxdr_u_hyper()\fR translates between unsigned ANSI C  \fBlong\fR \fBlong\fR
 289 integers and their external representations. This routine returns \fBTRUE\fR if
 290 it succeeds, \fBFALSE\fR otherwise.
 291 .RE
 292 
 293 .sp
 294 .ne 2
 295 .na
 296 \fB\fBxdr_u_int()\fR\fR
 297 .ad
 298 .RS 22n
 299 A filter primitive that translates between a C \fBunsigned\fR integer and its
 300 external representation. This routine returns \fBTRUE\fR if it succeeds,
 301 \fBFALSE\fR otherwise.
 302 .RE
 303 
 304 .sp
 305 .ne 2
 306 .na
 307 \fB\fBxdr_u_long()\fR\fR
 308 .ad
 309 .RS 22n
 310 \fBxdr_u_long()\fR translates between C \fBunsigned long\fR integers and their
 311 external representations. This routine returns \fBTRUE\fR if it succeeds,
 312 \fBFALSE\fR otherwise.
 313 .sp
 314 In a 64-bit environment, this routine returns an error if the value of
 315 \fIulp\fR is outside the range \fB[0, UINT32_MAX]\fR.  The \fBxdr_u_int()\fR
 316 routine is recommended in place of this routine.
 317 .RE
 318 
 319 .sp
 320 .ne 2
 321 .na
 322 \fB\fBxdr_u_longlong_t()\fR\fR
 323 .ad
 324 .RS 22n
 325 \fBxdr_u_longlong_t()\fR translates between unsigned ANSI C  \fBlong\fR
 326 \fBlong\fR integers and their external representations. This routine returns
 327 \fBTRUE\fR if it succeeds, \fBFALSE\fR otherwise. This routine is identical to
 328 \fBxdr_u_hyper()\fR.
 329 .RE
 330 
 331 .sp
 332 .ne 2
 333 .na
 334 \fB\fBxdr_u_short()\fR\fR
 335 .ad
 336 .RS 22n
 337 \fBxdr_u_short()\fR translates between C \fBunsigned short\fR integers and
 338 their external representations. This routine returns \fBTRUE\fR if it succeeds,
 339 \fBFALSE\fR otherwise.
 340 .RE
 341 
 342 .sp
 343 .ne 2
 344 .na
 345 \fB\fBxdr_void()\fR\fR
 346 .ad
 347 .RS 22n
 348 This routine always returns \fBTRUE\fR. It may be passed to \fBRPC\fR routines
 349 that require a function parameter, where nothing is to be done.
 350 .RE
 351 
 352 .SH ATTRIBUTES
 353 .sp
 354 .LP
 355 See \fBattributes\fR(5) for descriptions of the following attributes:
 356 .sp
 357 
 358 .sp
 359 .TS
 360 box;
 361 c | c
 362 l | l .
 363 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 364 _
 365 MT-Level        Safe
 366 .TE
 367 
 368 .SH SEE ALSO
 369 .sp
 370 .LP
 371 \fBmalloc\fR(3C), \fBrpc\fR(3NSL), \fBxdr_admin\fR(3NSL),
 372 \fBxdr_complex\fR(3NSL), \fBxdr_create\fR(3NSL), \fBattributes\fR(5)