original/man3/xdr.3

   1 .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
   2 .\"
   3 .\" @(#)xdr.3n  2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
   4 .\"
   5 .\" 2007-12-30, mtk, Convert function prototypes to modern C syntax
   6 .\"
   7 .TH XDR 3 2007-12-30 "" "Linux Programmer's Manual"
   8 .SH NAME
   9 xdr \- library routines for external data representation
  10 .SH "SYNOPSIS AND DESCRIPTION"
  11 .LP
  12 These routines allow C programmers to describe
  13 arbitrary data structures in a machine-independent fashion.
  14 Data for remote procedure calls are transmitted using these
  15 routines.
  16
  17 The prototypes below are declared in
  18 .I <rpc/xdr.h>
  19 and make use of the following types:
  20 .in +4n
  21 .nf
  22
  23 typedef int \fIbool_t\fP;
  24
  25 typedef bool_t (*\fIxdrproc_t\fP) (XDR *, void *,...);
  26 .fi
  27 .in
  28 .LP
  29 For the declaration of the
  30 .I XDR
  31 type, see
  32 .IR <rpc/xdr.h> .
  33 .LP
  34 .nf
  35 .BI "bool_t xdr_array(XDR *" xdrs ", char **" arrp ", unsigned int *" sizep ,
  36 .BI "                 unsigned int " maxsize ", unsigned int " elsize ,
  37 .BI "                 xdrproc_t " elproc );
  38 .fi
  39 .IP
  40 A filter primitive that translates between variable-length arrays
  41 and their corresponding external representations.
  42 The argument
  43 .I arrp
  44 is the address of the pointer to the array, while
  45 .I sizep
  46 is the address of the element count of the array;
  47 this element count cannot exceed
  48 .IR maxsize .
  49 The argument
  50 .I elsize
  51 is the
  52 .I sizeof
  53 each of the array's elements, and
  54 .I elproc
  55 is an XDR filter that translates between
  56 the array elements' C form, and their external
  57 representation.
  58 This routine returns one if it succeeds, zero otherwise.
  59 .LP
  60 .nf
  61 .BI "bool_t xdr_bool(XDR *" xdrs ", bool_t *" bp );
  62 .fi
  63 .IP
  64 A filter primitive that translates between booleans (C
  65 integers)
  66 and their external representations.
  67 When encoding data, this
  68 filter produces values of either one or zero.
  69 This routine returns one if it succeeds, zero otherwise.
  70 .LP
  71 .nf
  72 .BI "bool_t xdr_bytes(XDR *" xdrs ", char **" sp ", unsigned int *" sizep ,
  73 .BI "                 unsigned int " maxsize );
  74 .fi
  75 .IP
  76 A filter primitive that translates between counted byte
  77 strings and their external representations.
  78 The argument
  79 .I sp
  80 is the address of the string pointer.
  81 The length of the
  82 string is located at address
  83 .IR sizep ;
  84 strings cannot be longer than
  85 .IR maxsize .
  86 This routine returns one if it succeeds, zero otherwise.
  87 .LP
  88 .nf
  89 .BI "bool_t xdr_char(XDR *" xdrs ", char *" cp );
  90 .fi
  91 .IP
  92 A filter primitive that translates between C characters
  93 and their external representations.
  94 This routine returns one if it succeeds, zero otherwise.
  95 Note: encoded characters are not packed, and occupy 4 bytes each.
  96 For arrays of characters, it is worthwhile to
  97 consider
  98 .BR xdr_bytes (),
  99 .BR xdr_opaque ()
 100 or
 101 .BR xdr_string ().
 102 .LP
 103 .nf
 104 .BI "void xdr_destroy(XDR *" xdrs );
 105 .fi
 106 .IP
 107 A macro that invokes the destroy routine associated with the XDR stream,
 108 .IR xdrs .
 109 Destruction usually involves freeing private data structures
 110 associated with the stream.
 111 Using
 112 .I xdrs
 113 after invoking
 114 .BR xdr_destroy ()
 115 is undefined.
 116 .LP
 117 .nf
 118 .BI "bool_t xdr_double(XDR *" xdrs ", double *" dp );
 119 .fi
 120 .IP
 121 A filter primitive that translates between C
 122 .I double
 123 precision numbers and their external representations.
 124 This routine returns one if it succeeds, zero otherwise.
 125 .LP
 126 .nf
 127 .BI "bool_t xdr_enum(XDR *" xdrs ", enum_t *" ep );
 128 .fi
 129 .IP
 130 A filter primitive that translates between C
 131 .IR enum s
 132 (actually integers) and their external representations.
 133 This routine returns one if it succeeds, zero otherwise.
 134 .LP
 135 .nf
 136 .BI "bool_t xdr_float(XDR *" xdrs ", float *" fp );
 137 .fi
 138 .IP
 139 A filter primitive that translates between C
 140 .IR float s
 141 and their external representations.
 142 This routine returns one if it succeeds, zero otherwise.
 143 .LP
 144 .nf
 145 .BI "void xdr_free(xdrproc_t " proc ", char *" objp );
 146 .fi
 147 .IP
 148 Generic freeing routine.
 149 The first argument is the XDR routine for the object being freed.
 150 The second argument is a pointer to the object itself.
 151 Note: the pointer passed to this routine is
 152 .I not
 153 freed, but what it points to
 154 .I is
 155 freed (recursively).
 156 .LP
 157 .nf
 158 .BI "unsigned int xdr_getpos(XDR *" xdrs );
 159 .fi
 160 .IP
 161 A macro that invokes the get-position routine
 162 associated with the XDR stream,
 163 .IR xdrs .
 164 The routine returns an unsigned integer,
 165 which indicates the position of the XDR byte stream.
 166 A desirable feature of XDR
 167 streams is that simple arithmetic works with this number,
 168 although the XDR stream instances need not guarantee this.
 169 .LP
 170 .nf
 171 .BI "long *xdr_inline(XDR *" xdrs ", int " len );
 172 .fi
 173 .IP
 174 A macro that invokes the inline routine associated with the XDR stream,
 175 .IR xdrs .
 176 The routine returns a pointer
 177 to a contiguous piece of the stream's buffer;
 178 .I len
 179 is the byte length of the desired buffer.
 180 Note: pointer is cast to
 181 .IR "long *" .
 182 .IP
 183 Warning:
 184 .BR xdr_inline ()
 185 may return NULL (0)
 186 if it cannot allocate a contiguous piece of a buffer.
 187 Therefore the behavior may vary among stream instances;
 188 it exists for the sake of efficiency.
 189 .LP
 190 .nf
 191 .BI "bool_t xdr_int(XDR *" xdrs ", int *" ip );
 192 .fi
 193 .IP
 194 A filter primitive that translates between C integers
 195 and their external representations.
 196 This routine returns one if it succeeds, zero otherwise.
 197 .LP
 198 .nf
 199 .BI "bool_t xdr_long(XDR *" xdrs ", long *" lp );
 200 .fi
 201 .IP
 202 A filter primitive that translates between C
 203 .I long
 204 integers and their external representations.
 205 This routine returns one if it succeeds, zero otherwise.
 206 .LP
 207 .nf
 208 .BI "void xdrmem_create(XDR *" xdrs ", char *" addr ", unsigned int " size ,
 209 .BI "                   enum xdr_op " op );
 210 .fi
 211 .IP
 212 This routine initializes the XDR stream object pointed to by
 213 .IR xdrs .
 214 The stream's data is written to, or read from,
 215 a chunk of memory at location
 216 .I addr
 217 whose length is no more than
 218 .I size
 219 bytes long.
 220 The
 221 .I op
 222 determines the direction of the XDR stream (either
 223 .BR XDR_ENCODE ,
 224 .BR XDR_DECODE ,
 225 or
 226 .BR XDR_FREE ).
 227 .LP
 228 .nf
 229 .BI "bool_t xdr_opaque(XDR *" xdrs ", char *" cp ", unsigned int " cnt );
 230 .fi
 231 .IP
 232 A filter primitive that translates between fixed size opaque data
 233 and its external representation.
 234 The argument
 235 .I cp
 236 is the address of the opaque object, and
 237 .I cnt
 238 is its size in bytes.
 239 This routine returns one if it succeeds, zero otherwise.
 240 .LP
 241 .nf
 242 .BI "bool_t xdr_pointer(XDR *" xdrs ", char **" objpp ,
 243 .BI "                   unsigned int " objsize ", xdrproc_t " xdrobj );
 244 .fi
 245 .IP
 246 Like
 247 .BR xdr_reference ()
 248 except that it serializes NULL pointers, whereas
 249 .BR xdr_reference ()
 250 does not.
 251 Thus,
 252 .BR xdr_pointer ()
 253 can represent
 254 recursive data structures, such as binary trees or
 255 linked lists.
 256 .LP
 257 .nf
 258 .BI "void xdrrec_create(XDR *" xdrs ", unsigned int " sendsize ,
 259 .BI "                   unsigned int " recvsize ", char *" handle ,
 260 .BI "                   int (*" readit ") (char *, char *, int),"
 261 .BI "                   int (*" writeit ") (char *, char *, int));"
 262 .fi
 263 .IP
 264 This routine initializes the XDR stream object pointed to by
 265 .IR xdrs .
 266 The stream's data is written to a buffer of size
 267 .IR sendsize ;
 268 a value of zero indicates the system should use a suitable default.
 269 The stream's data is read from a buffer of size
 270 .IR recvsize ;
 271 it too can be set to a suitable default by passing a zero value.
 272 When a stream's output buffer is full,
 273 .I writeit
 274 is called.
 275 Similarly, when a stream's input buffer is empty,
 276 .I readit
 277 is called.
 278 The behavior of these two routines is similar to
 279 the system calls
 280 .BR read (2)
 281 and
 282 .BR write (2),
 283 except that
 284 .I handle
 285 is passed to the former routines as the first argument.
 286 Note: the XDR stream's
 287 .I op
 288 field must be set by the caller.
 289 .IP
 290 Warning: this XDR stream implements an intermediate record stream.
 291 Therefore there are additional bytes in the stream
 292 to provide record boundary information.
 293 .LP
 294 .nf
 295 .BI "bool_t xdrrec_endofrecord(XDR *" xdrs ", int " sendnow );
 296 .fi
 297 .IP
 298 This routine can be invoked only on streams created by
 299 .BR xdrrec_create ().
 300 The data in the output buffer is marked as a completed record,
 301 and the output buffer is optionally written out if
 302 .I sendnow
 303 is nonzero.
 304 This routine returns one if it succeeds, zero otherwise.
 305 .LP
 306 .nf
 307 .BI "bool_t xdrrec_eof(XDR *" xdrs );
 308 .fi
 309 .IP
 310 This routine can be invoked only on streams created by
 311 .BR xdrrec_create ().
 312 After consuming the rest of the current record in the stream,
 313 this routine returns one if the stream has no more input,
 314 zero otherwise.
 315 .LP
 316 .nf
 317 .BI "bool_t xdrrec_skiprecord(XDR *" xdrs );
 318 .fi
 319 .IP
 320 This routine can be invoked only on
 321 streams created by
 322 .BR xdrrec_create ().
 323 It tells the XDR implementation that the rest of the current record
 324 in the stream's input buffer should be discarded.
 325 This routine returns one if it succeeds, zero otherwise.
 326 .LP
 327 .nf
 328 .BI "bool_t xdr_reference(XDR *" xdrs ", char **" pp ", unsigned int " size ,
 329 .BI "                     xdrproc_t " proc );
 330 .fi
 331 .IP
 332 A primitive that provides pointer chasing within structures.
 333 The argument
 334 .I pp
 335 is the address of the pointer;
 336 .I size
 337 is the
 338 .I sizeof
 339 the structure that
 340 .I *pp
 341 points to; and
 342 .I proc
 343 is an XDR procedure that filters the structure
 344 between its C form and its external representation.
 345 This routine returns one if it succeeds, zero otherwise.
 346 .IP
 347 Warning: this routine does not understand NULL pointers.
 348 Use
 349 .BR xdr_pointer ()
 350 instead.
 351 .LP
 352 .nf
 353 .BI "xdr_setpos(XDR *" xdrs ", unsigned int " pos );
 354 .fi
 355 .IP
 356 A macro that invokes the set position routine associated with
 357 the XDR stream
 358 .IR xdrs .
 359 The argument
 360 .I pos
 361 is a position value obtained from
 362 .BR xdr_getpos ().
 363 This routine returns one if the XDR stream could be repositioned,
 364 and zero otherwise.
 365 .IP
 366 Warning: it is difficult to reposition some types of XDR
 367 streams, so this routine may fail with one
 368 type of stream and succeed with another.
 369 .LP
 370 .nf
 371 .BI "bool_t xdr_short(XDR *" xdrs ", short *" sp );
 372 .fi
 373 .IP
 374 A filter primitive that translates between C
 375 .I short
 376 integers and their external representations.
 377 This routine returns one if it succeeds, zero otherwise.
 378 .LP
 379 .nf
 380 .BI "void xdrstdio_create(XDR *" xdrs ", FILE *" file ", enum xdr_op " op );
 381 .fi
 382 .IP
 383 This routine initializes the XDR stream object pointed to by
 384 .IR xdrs .
 385 The XDR stream data is written to, or read from, the
 386 .I stdio
 387 stream
 388 .IR file .
 389 The argument
 390 .I op
 391 determines the direction of the XDR stream (either
 392 .BR XDR_ENCODE ,
 393 .BR XDR_DECODE ,
 394 or
 395 .BR XDR_FREE ).
 396 .IP
 397 Warning: the destroy routine associated with such XDR streams calls
 398 .BR fflush (3)
 399 on the
 400 .I file
 401 stream, but never
 402 .BR fclose (3).
 403 .LP
 404 .nf
 405 .BI "bool_t xdr_string(XDR *" xdrs ", char **" sp ", unsigned int " maxsize );
 406 .fi
 407 .IP
 408 A filter primitive that translates between C strings and
 409 their corresponding external representations.
 410 Strings cannot be longer than
 411 .IR maxsize .
 412 Note:
 413 .I sp
 414 is the address of the string's pointer.
 415 This routine returns one if it succeeds, zero otherwise.
 416 .LP
 417 .nf
 418 .BI "bool_t xdr_u_char(XDR *" xdrs ", unsigned char *" ucp );
 419 .fi
 420 .IP
 421 A filter primitive that translates between
 422 .I unsigned
 423 C characters and their external representations.
 424 This routine returns one if it succeeds, zero otherwise.
 425 .LP
 426 .nf
 427 .BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned *" up );
 428 .fi
 429 .IP
 430 A filter primitive that translates between C
 431 .I unsigned
 432 integers and their external representations.
 433 This routine returns one if it succeeds, zero otherwise.
 434 .LP
 435 .nf
 436 .BI "bool_t xdr_u_long(XDR *" xdrs ", unsigned long *" ulp );
 437 .fi
 438 .IP
 439 A filter primitive that translates between C
 440 .I "unsigned long"
 441 integers and their external representations.
 442 This routine returns one if it succeeds, zero otherwise.
 443 .LP
 444 .nf
 445 .BI "bool_t xdr_u_short(XDR *" xdrs ", unsigned short *" usp );
 446 .fi
 447 .IP
 448 A filter primitive that translates between C
 449 .I "unsigned short"
 450 integers and their external representations.
 451 This routine returns one if it succeeds, zero otherwise.
 452 .LP
 453 .nf
 454 .BI "bool_t xdr_union(XDR *" xdrs ", int *" dscmp ", char *" unp ,
 455 .BI "                 struct xdr_discrim *" choices ,
 456 .BI "                 xdrproc_t " defaultarm ");     /* may equal NULL */"
 457 .fi
 458 .IP
 459 A filter primitive that translates between a discriminated C
 460 .I union
 461 and its corresponding external representation.
 462 It first
 463 translates the discriminant of the union located at
 464 .IR dscmp .
 465 This discriminant is always an
 466 .IR enum_t .
 467 Next the union located at
 468 .I unp
 469 is translated.
 470 The argument
 471 .I choices
 472 is a pointer to an array of
 473 .BR xdr_discrim ()
 474 structures.
 475 Each structure contains an ordered pair of
 476 .RI [ value , proc ].
 477 If the union's discriminant is equal to the associated
 478 .IR value ,
 479 then the
 480 .I proc
 481 is called to translate the union.
 482 The end of the
 483 .BR xdr_discrim ()
 484 structure array is denoted by a routine of value NULL.
 485 If the discriminant is not found in the
 486 .I choices
 487 array, then the
 488 .I defaultarm
 489 procedure is called (if it is not NULL).
 490 Returns one if it succeeds, zero otherwise.
 491 .LP
 492 .nf
 493 .BI "bool_t xdr_vector(XDR *" xdrs ", char *" arrp ", unsigned int " size ,
 494 .BI "                  unsigned int " elsize ", xdrproc_t " elproc );
 495 .fi
 496 .IP
 497 A filter primitive that translates between fixed-length arrays
 498 and their corresponding external representations.
 499 The argument
 500 .I arrp
 501 is the address of the pointer to the array, while
 502 .I size
 503 is the element count of the array.
 504 The argument
 505 .I elsize
 506 is the
 507 .I sizeof
 508 each of the array's elements, and
 509 .I elproc
 510 is an XDR filter that translates between
 511 the array elements' C form, and their external
 512 representation.
 513 This routine returns one if it succeeds, zero otherwise.
 514 .LP
 515 .nf
 516 .BI "bool_t xdr_void(void);"
 517 .fi
 518 .IP
 519 This routine always returns one.
 520 It may be passed to RPC routines that require a function argument,
 521 where nothing is to be done.
 522 .LP
 523 .nf
 524 .BI "bool_t xdr_wrapstring(XDR *" xdrs ", char **" sp );
 525 .fi
 526 .IP
 527 A primitive that calls
 528 .B "xdr_string(xdrs, sp,MAXUN.UNSIGNED );"
 529 where
 530 .B MAXUN.UNSIGNED
 531 is the maximum value of an unsigned integer.
 532 .BR xdr_wrapstring ()
 533 is handy because the RPC package passes a maximum of two XDR
 534 routines as arguments, and
 535 .BR xdr_string (),
 536 one of the most frequently used primitives, requires three.
 537 Returns one if it succeeds, zero otherwise.
 538 .SH "SEE ALSO"
 539 .BR rpc (3)
 540 .LP
 541 The following manuals:
 542 .RS
 543 eXternal Data Representation Standard: Protocol Specification
 544 .br
 545 eXternal Data Representation: Sun Technical Notes
 546 .br
 547 .IR "XDR: External Data Representation Standard" ,
 548 RFC\ 1014, Sun Microsystems, Inc.,
 549 USC-ISI.
 550 .RE