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

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