man3/xdr.3

   1 .\" @(#)xdr.3n  2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
   2 .TH XDR 3 1988-02-16
   3 .SH NAME
   4 xdr \- library routines for external data representation
   5 .SH "SYNOPSIS AND DESCRIPTION"
   6 .LP
   7 These routines allow C programmers to describe
   8 arbitrary data structures in a machine-independent fashion.
   9 Data for remote procedure calls are transmitted using these
  10 routines.
  11 .LP
  12 .ft B
  13 .nf
  14 .sp .5
  15 xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)
  16 \s-1XDR\s0 *xdrs;
  17 char **arrp;
  18 u_int *sizep, maxsize, elsize;
  19 xdrproc_t elproc;
  20 .fi
  21 .ft R
  22 .IP
  23 A filter primitive that translates between variable-length
  24 arrays
  25 and their corresponding external representations. The
  26 parameter
  27 .I arrp
  28 is the address of the pointer to the array, while
  29 .I sizep
  30 is the address of the element count of the array;
  31 this element count cannot exceed
  32 .IR maxsize .
  33 The parameter
  34 .I elsize
  35 is the
  36 .I sizeof
  37 each of the array's elements, and
  38 .I elproc
  39 is an
  40 .SM XDR
  41 filter that translates between
  42 the array elements' C form, and their external
  43 representation.
  44 This routine returns one if it succeeds, zero otherwise.
  45 .br
  46 .if t .ne 8
  47 .LP
  48 .ft B
  49 .nf
  50 .sp .5
  51 xdr_bool(xdrs, bp)
  52 \s-1XDR\s0 *xdrs;
  53 bool_t *bp;
  54 .fi
  55 .ft R
  56 .IP
  57 A filter primitive that translates between booleans (C
  58 integers)
  59 and their external representations. When encoding data, this
  60 filter produces values of either one or zero.
  61 This routine returns one if it succeeds, zero otherwise.
  62 .br
  63 .if t .ne 10
  64 .LP
  65 .ft B
  66 .nf
  67 .sp .5
  68 xdr_bytes(xdrs, sp, sizep, maxsize)
  69 \s-1XDR\s0 *xdrs;
  70 char **sp;
  71 u_int *sizep, maxsize;
  72 .fi
  73 .ft R
  74 .IP
  75 A filter primitive that translates between counted byte
  76 strings and their external representations.
  77 The parameter
  78 .I sp
  79 is the address of the string pointer. The length of the
  80 string is located at address
  81 .IR sizep ;
  82 strings cannot be longer than
  83 .IR maxsize .
  84 This routine returns one if it succeeds, zero otherwise.
  85 .br
  86 .if t .ne 7
  87 .LP
  88 .ft B
  89 .nf
  90 .sp .5
  91 xdr_char(xdrs, cp)
  92 \s-1XDR\s0 *xdrs;
  93 char *cp;
  94 .fi
  95 .ft R
  96 .IP
  97 A filter primitive that translates between C characters
  98 and their external representations.
  99 This routine returns one if it succeeds, zero otherwise.
 100 Note: encoded characters are not packed, and occupy 4 bytes
 101 each. For arrays of characters, it is worthwhile to
 102 consider
 103 .BR xdr_bytes() ,
 104 .B xdr_opaque()
 105 or
 106 .BR xdr_string() .
 107 .br
 108 .if t .ne 8
 109 .LP
 110 .ft B
 111 .nf
 112 .sp .5
 113 void
 114 xdr_destroy(xdrs)
 115 \s-1XDR\s0 *xdrs;
 116 .fi
 117 .ft R
 118 .IP
 119 A macro that invokes the destroy routine associated with the
 120 .SM XDR
 121 stream,
 122 .IR xdrs .
 123 Destruction usually involves freeing private data structures
 124 associated with the stream.  Using
 125 .I xdrs
 126 after invoking
 127 .B xdr_destroy()
 128 is undefined.
 129 .br
 130 .if t .ne 7
 131 .LP
 132 .ft B
 133 .nf
 134 .sp .5
 135 xdr_double(xdrs, dp)
 136 \s-1XDR\s0 *xdrs;
 137 double *dp;
 138 .fi
 139 .ft R
 140 .IP
 141 A filter primitive that translates between C
 142 .B double
 143 precision numbers and their external representations.
 144 This routine returns one if it succeeds, zero otherwise.
 145 .br
 146 .if t .ne 7
 147 .LP
 148 .ft B
 149 .nf
 150 .sp .5
 151 xdr_enum(xdrs, ep)
 152 \s-1XDR\s0 *xdrs;
 153 enum_t *ep;
 154 .fi
 155 .ft R
 156 .IP
 157 A filter primitive that translates between C
 158 .BR enum s
 159 (actually integers) and their external representations.
 160 This routine returns one if it succeeds, zero otherwise.
 161 .br
 162 .if t .ne 8
 163 .LP
 164 .ft B
 165 .nf
 166 .sp .5
 167 xdr_float(xdrs, fp)
 168 \s-1XDR\s0 *xdrs;
 169 float *fp;
 170 .fi
 171 .ft R
 172 .IP
 173 A filter primitive that translates between C
 174 .BR float s
 175 and their external representations.
 176 This routine returns one if it succeeds, zero otherwise.
 177 .br
 178 .if t .ne 9
 179 .LP
 180 .ft B
 181 .nf
 182 .sp .5
 183 void
 184 xdr_free(proc, objp)
 185 xdrproc_t proc;
 186 char *objp;
 187 .fi
 188 .ft R
 189 .IP
 190 Generic freeing routine. The first argument is the
 191 .SM XDR
 192 routine for the object being freed. The second argument
 193 is a pointer to the object itself. Note: the pointer passed
 194 to this routine is
 195 .I not
 196 freed, but what it points to
 197 .I is
 198 freed (recursively).
 199 .br
 200 .if t .ne 8
 201 .LP
 202 .ft B
 203 .nf
 204 .sp .5
 205 u_int
 206 xdr_getpos(xdrs)
 207 \s-1XDR\s0 *xdrs;
 208 .fi
 209 .ft R
 210 .IP
 211 A macro that invokes the get-position routine
 212 associated with the
 213 .SM XDR
 214 stream,
 215 .IR xdrs .
 216 The routine returns an unsigned integer,
 217 which indicates the position of the
 218 .SM XDR
 219 byte stream.
 220 A desirable feature of
 221 .SM XDR
 222 streams is that simple arithmetic works with this number,
 223 although the
 224 .SM XDR
 225 stream instances need not guarantee this.
 226 .br
 227 .if t .ne 4
 228 .LP
 229 .ft B
 230 .nf
 231 .sp .5
 232 .br
 233 long *
 234 xdr_inline(xdrs, len)
 235 \s-1XDR\s0 *xdrs;
 236 int len;
 237 .fi
 238 .ft R
 239 .IP
 240 A macro that invokes the in-line routine associated with the
 241 .SM XDR
 242 stream,
 243 .IR xdrs .
 244 The routine returns a pointer
 245 to a contiguous piece of the stream's buffer;
 246 .I len
 247 is the byte length of the desired buffer.
 248 Note: pointer is cast to
 249 .BR "long *" .
 250 .IP
 251 Warning:
 252 .B xdr_inline()
 253 may return
 254 .SM NULL
 255 (0)
 256 if it cannot allocate a contiguous piece of a buffer.
 257 Therefore the behavior may vary among stream instances;
 258 it exists for the sake of efficiency.
 259 .br
 260 .if t .ne 7
 261 .LP
 262 .ft B
 263 .nf
 264 .sp .5
 265 xdr_int(xdrs, ip)
 266 \s-1XDR\s0 *xdrs;
 267 int *ip;
 268 .fi
 269 .ft R
 270 .IP
 271 A filter primitive that translates between C integers
 272 and their external representations.
 273 This routine returns one if it succeeds, zero otherwise.
 274 .br
 275 .if t .ne 7
 276 .LP
 277 .ft B
 278 .nf
 279 .sp .5
 280 xdr_long(xdrs, lp)
 281 \s-1XDR\s0 *xdrs;
 282 long *lp;
 283 .fi
 284 .ft R
 285 .IP
 286 A filter primitive that translates between C
 287 .B long
 288 integers and their external representations.
 289 This routine returns one if it succeeds, zero otherwise.
 290 .br
 291 .if t .ne 12
 292 .LP
 293 .ft B
 294 .nf
 295 .sp .5
 296 void
 297 xdrmem_create(xdrs, addr, size, op)
 298 \s-1XDR\s0 *xdrs;
 299 char *addr;
 300 u_int size;
 301 enum xdr_op op;
 302 .fi
 303 .ft R
 304 .IP
 305 This routine initializes the
 306 .SM XDR
 307 stream object pointed to by
 308 .IR xdrs .
 309 The stream's data is written to, or read from,
 310 a chunk of memory at location
 311 .I addr
 312 whose length is no more than
 313 .I size
 314 bytes long.  The
 315 .I op
 316 determines the direction of the
 317 .SM XDR
 318 stream
 319 (either
 320 .BR \s-1XDR_ENCODE\s0 ,
 321 .BR \s-1XDR_DECODE\s0 ,
 322 or
 323 .BR \s-1XDR_FREE\s0 ).
 324 .br
 325 .if t .ne 10
 326 .LP
 327 .ft B
 328 .nf
 329 .sp .5
 330 xdr_opaque(xdrs, cp, cnt)
 331 \s-1XDR\s0 *xdrs;
 332 char *cp;
 333 u_int cnt;
 334 .fi
 335 .ft R
 336 .IP
 337 A filter primitive that translates between fixed size opaque data
 338 and its external representation.
 339 The parameter
 340 .I cp
 341 is the address of the opaque object, and
 342 .I cnt
 343 is its size in bytes.
 344 This routine returns one if it succeeds, zero otherwise.
 345 .br
 346 .if t .ne 10
 347 .LP
 348 .ft B
 349 .nf
 350 .sp .5
 351 xdr_pointer(xdrs, objpp, objsize, xdrobj)
 352 \s-1XDR\s0 *xdrs;
 353 char **objpp;
 354 u_int objsize;
 355 xdrproc_t xdrobj;
 356 .fi
 357 .ft R
 358 .IP
 359 Like
 360 .B xdr_reference()
 361 except that it serializes
 362 .SM NULL
 363 pointers, whereas
 364 .B xdr_reference()
 365 does not.  Thus,
 366 .B xdr_pointer()
 367 can represent
 368 recursive data structures, such as binary trees or
 369 linked lists.
 370 .br
 371 .if t .ne 15
 372 .LP
 373 .ft B
 374 .nf
 375 .sp .5
 376 void
 377 xdrrec_create(xdrs, sendsize, recvsize, handle, readit, writeit)
 378 \s-1XDR\s0 *xdrs;
 379 u_int sendsize, recvsize;
 380 char *handle;
 381 int (*readit) (), (*writeit) ();
 382 .fi
 383 .ft R
 384 .IP
 385 This routine initializes the
 386 .SM XDR
 387 stream object pointed to by
 388 .IR xdrs .
 389 The stream's data is written to a buffer of size
 390 .IR sendsize ;
 391 a value of zero indicates the system should use a suitable
 392 default. The stream's data is read from a buffer of size
 393 .IR recvsize ;
 394 it too can be set to a suitable default by passing a zero
 395 value.
 396 When a stream's output buffer is full,
 397 .I writeit
 398 is called.  Similarly, when a stream's input buffer is empty,
 399 .I readit
 400 is called.  The behavior of these two routines is similar to
 401 the
 402 system calls
 403 .B read
 404 and
 405 .BR write ,
 406 except that
 407 .I handle
 408 is passed to the former routines as the first parameter.
 409 Note: the
 410 .SM XDR
 411 stream's
 412 .I op
 413 field must be set by the caller.
 414 .IP
 415 Warning: this
 416 .SM XDR
 417 stream implements an intermediate record stream.
 418 Therefore there are additional bytes in the stream
 419 to provide record boundary information.
 420 .br
 421 .if t .ne 9
 422 .LP
 423 .ft B
 424 .nf
 425 .sp .5
 426 xdrrec_endofrecord(xdrs, sendnow)
 427 \s-1XDR\s0 *xdrs;
 428 int sendnow;
 429 .fi
 430 .ft R
 431 .IP
 432 This routine can be invoked only on
 433 streams created by
 434 .BR xdrrec_create() .
 435 The data in the output buffer is marked as a completed
 436 record,
 437 and the output buffer is optionally written out if
 438 .I sendnow
 439 is non-zero. This routine returns one if it succeeds, zero
 440 otherwise.
 441 .br
 442 .if t .ne 8
 443 .LP
 444 .ft B
 445 .nf
 446 .sp .5
 447 xdrrec_eof(xdrs)
 448 \s-1XDR\s0 *xdrs;
 449 int empty;
 450 .fi
 451 .ft R
 452 .IP
 453 This routine can be invoked only on
 454 streams created by
 455 .BR xdrrec_create() .
 456 After consuming the rest of the current record in the stream,
 457 this routine returns one if the stream has no more input,
 458 zero otherwise.
 459 .br
 460 .if t .ne 3
 461 .LP
 462 .ft B
 463 .nf
 464 .sp .5
 465 xdrrec_skiprecord(xdrs)
 466 \s-1XDR\s0 *xdrs;
 467 .fi
 468 .ft R
 469 .IP
 470 This routine can be invoked only on
 471 streams created by
 472 .BR xdrrec_create() .
 473 It tells the
 474 .SM XDR
 475 implementation that the rest of the current record
 476 in the stream's input buffer should be discarded.
 477 This routine returns one if it succeeds, zero otherwise.
 478 .br
 479 .if t .ne 11
 480 .LP
 481 .ft B
 482 .nf
 483 .sp .5
 484 xdr_reference(xdrs, pp, size, proc)
 485 \s-1XDR\s0 *xdrs;
 486 char **pp;
 487 u_int size;
 488 xdrproc_t proc;
 489 .fi
 490 .ft R
 491 .IP
 492 A primitive that provides pointer chasing within structures.
 493 The parameter
 494 .I pp
 495 is the address of the pointer;
 496 .I size
 497 is the
 498 .I sizeof
 499 the structure that
 500 .I *pp
 501 points to; and
 502 .I proc
 503 is an
 504 .SM XDR
 505 procedure that filters the structure
 506 between its C form and its external representation.
 507 This routine returns one if it succeeds, zero otherwise.
 508 .IP
 509 Warning: this routine does not understand
 510 .SM NULL
 511 pointers. Use
 512 .B xdr_pointer()
 513 instead.
 514 .br
 515 .if t .ne 10
 516 .LP
 517 .ft B
 518 .nf
 519 .sp .5
 520 xdr_setpos(xdrs, pos)
 521 \s-1XDR\s0 *xdrs;
 522 u_int pos;
 523 .fi
 524 .ft R
 525 .IP
 526 A macro that invokes the set position routine associated with
 527 the
 528 .SM XDR
 529 stream
 530 .IR xdrs .
 531 The parameter
 532 .I pos
 533 is a position value obtained from
 534 .BR xdr_getpos() .
 535 This routine returns one if the
 536 .SM XDR
 537 stream could be repositioned,
 538 and zero otherwise.
 539 .IP
 540 Warning: it is difficult to reposition some types of
 541 .SM XDR
 542 streams, so this routine may fail with one
 543 type of stream and succeed with another.
 544 .br
 545 .if t .ne 8
 546 .LP
 547 .ft B
 548 .nf
 549 .sp .5
 550 xdr_short(xdrs, sp)
 551 \s-1XDR\s0 *xdrs;
 552 short *sp;
 553 .fi
 554 .ft R
 555 .IP
 556 A filter primitive that translates between C
 557 .B short
 558 integers and their external representations.
 559 This routine returns one if it succeeds, zero otherwise.
 560 .br
 561 .if t .ne 10
 562 .LP
 563 .ft B
 564 .nf
 565 .sp .5
 566 void
 567 xdrstdio_create(xdrs, file, op)
 568 \s-1XDR\s0 *xdrs;
 569 \s-1FILE\s0 *file;
 570 enum xdr_op op;
 571 .fi
 572 .ft R
 573 .IP
 574 This routine initializes the
 575 .SM XDR
 576 stream object pointed to by
 577 .IR xdrs .
 578 The
 579 .SM XDR
 580 stream data is written to, or read from, the Standard
 581 .B I/O
 582 stream
 583 .IR file .
 584 The parameter
 585 .I op
 586 determines the direction of the
 587 .SM XDR
 588 stream (either
 589 .BR \s-1XDR_ENCODE\s0 ,
 590 .BR \s-1XDR_DECODE\s0 ,
 591 or
 592 .BR \s-1XDR_FREE\s0 ).
 593 .IP
 594 Warning: the destroy routine associated with such
 595 .SM XDR
 596 streams calls
 597 .B fflush()
 598 on the
 599 .I file
 600 stream, but never
 601 .BR fclose() .
 602 .br
 603 .if t .ne 9
 604 .LP
 605 .ft B
 606 .nf
 607 .sp .5
 608 xdr_string(xdrs, sp, maxsize)
 609 \s-1XDR\s0
 610 *xdrs;
 611 char **sp;
 612 u_int maxsize;
 613 .fi
 614 .ft R
 615 .IP
 616 A filter primitive that translates between C strings and
 617 their
 618 corresponding external representations.
 619 Strings cannot be longer than
 620 .IR maxsize .
 621 Note:
 622 .I sp
 623 is the address of the string's pointer.
 624 This routine returns one if it succeeds, zero otherwise.
 625 .br
 626 .if t .ne 8
 627 .LP
 628 .ft B
 629 .nf
 630 .sp .5
 631 xdr_u_char(xdrs, ucp)
 632 \s-1XDR\s0 *xdrs;
 633 unsigned char *ucp;
 634 .fi
 635 .ft R
 636 .IP
 637 A filter primitive that translates between
 638 .B unsigned
 639 C characters and their external representations.
 640 This routine returns one if it succeeds, zero otherwise.
 641 .br
 642 .if t .ne 9
 643 .LP
 644 .ft B
 645 .nf
 646 .sp .5
 647 xdr_u_int(xdrs, up)
 648 \s-1XDR\s0 *xdrs;
 649 unsigned *up;
 650 .fi
 651 .ft R
 652 .IP
 653 A filter primitive that translates between C
 654 .B unsigned
 655 integers and their external representations.
 656 This routine returns one if it succeeds, zero otherwise.
 657 .br
 658 .if t .ne 7
 659 .LP
 660 .ft B
 661 .nf
 662 .sp .5
 663 xdr_u_long(xdrs, ulp)
 664 \s-1XDR\s0 *xdrs;
 665 unsigned long *ulp;
 666 .fi
 667 .ft R
 668 .IP
 669 A filter primitive that translates between C
 670 .B "unsigned long"
 671 integers and their external representations.
 672 This routine returns one if it succeeds, zero otherwise.
 673 .br
 674 .if t .ne 7
 675 .LP
 676 .ft B
 677 .nf
 678 .sp .5
 679 xdr_u_short(xdrs, usp)
 680 \s-1XDR\s0 *xdrs;
 681 unsigned short *usp;
 682 .fi
 683 .ft R
 684 .IP
 685 A filter primitive that translates between C
 686 .B "unsigned short"
 687 integers and their external representations.
 688 This routine returns one if it succeeds, zero otherwise.
 689 .br
 690 .if t .ne 16
 691 .LP
 692 .ft B
 693 .nf
 694 .sp .5
 695 xdr_union(xdrs, dscmp, unp, choices, dfault)
 696 \s-1XDR\s0 *xdrs;
 697 int *dscmp;
 698 char *unp;
 699 struct xdr_discrim *choices;
 700 bool_t (*defaultarm) ();  /* may equal \s-1NULL\s0 */
 701 .fi
 702 .ft R
 703 .IP
 704 A filter primitive that translates between a discriminated C
 705 .B union
 706 and its corresponding external representation. It first
 707 translates the discriminant of the union located at
 708 .IR dscmp .
 709 This discriminant is always an
 710 .BR enum_t .
 711 Next the union located at
 712 .I unp
 713 is translated.  The parameter
 714 .I choices
 715 is a pointer to an array of
 716 .B xdr_discrim()
 717 structures. Each structure contains an ordered pair of
 718 .RI [ value , proc ].
 719 If the union's discriminant is equal to the associated
 720 .IR value ,
 721 then the
 722 .I proc
 723 is called to translate the union.  The end of the
 724 .B xdr_discrim()
 725 structure array is denoted by a routine of value
 726 .SM NULL\s0.
 727 If the discriminant is not found in the
 728 .I choices
 729 array, then the
 730 .I defaultarm
 731 procedure is called (if it is not
 732 .SM NULL\s0).
 733 Returns one if it succeeds, zero otherwise.
 734 .br
 735 .if t .ne 6
 736 .LP
 737 .ft B
 738 .nf
 739 .sp .5
 740 xdr_vector(xdrs, arrp, size, elsize, elproc)
 741 \s-1XDR\s0 *xdrs;
 742 char *arrp;
 743 u_int size, elsize;
 744 xdrproc_t elproc;
 745 .fi
 746 .ft R
 747 .IP
 748 A filter primitive that translates between fixed-length
 749 arrays
 750 and their corresponding external representations.  The
 751 parameter
 752 .I arrp
 753 is the address of the pointer to the array, while
 754 .I size
 755 is is the element count of the array.  The parameter
 756 .I elsize
 757 is the
 758 .I sizeof
 759 each of the array's elements, and
 760 .I elproc
 761 is an
 762 .SM XDR
 763 filter that translates between
 764 the array elements' C form, and their external
 765 representation.
 766 This routine returns one if it succeeds, zero otherwise.
 767 .br
 768 .if t .ne 5
 769 .LP
 770 .ft B
 771 .nf
 772 .sp .5
 773 xdr_void()
 774 .fi
 775 .ft R
 776 .IP
 777 This routine always returns one.
 778 It may be passed to
 779 .SM RPC
 780 routines that require a function parameter,
 781 where nothing is to be done.
 782 .br
 783 .if t .ne 10
 784 .LP
 785 .ft B
 786 .nf
 787 .sp .5
 788 xdr_wrapstring(xdrs, sp)
 789 \s-1XDR\s0 *xdrs;
 790 char **sp;
 791 .fi
 792 .ft R
 793 .IP
 794 A primitive that calls
 795 .B "xdr_string(xdrs, sp,\s-1MAXUN.UNSIGNED\s0 );"
 796 where
 797 .B
 798 .SM MAXUN.UNSIGNED
 799 is the maximum value of an unsigned integer.
 800 .B xdr_wrapstring()
 801 is handy because the
 802 .SM RPC
 803 package passes a maximum of two
 804 .SM XDR
 805 routines as parameters, and
 806 .BR xdr_string() ,
 807 one of the most frequently used primitives, requires three.
 808 Returns one if it succeeds, zero otherwise.
 809 .SH "SEE ALSO"
 810 .BR rpc (3)
 811 .LP
 812 The following manuals:
 813 .RS
 814 .ft I
 815 eXternal Data Representation Standard: Protocol Specification
 816 .br
 817 eXternal Data Representation: Sun Technical Notes
 818 .ft R
 819 .br
 820 .IR "\s-1XDR\s0: External Data Representation Standard" ,
 821 .SM RFC\ 1014, Sun Microsystems, Inc.,
 822 .SM USC-ISI\s0.