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)