lib/libc/xdr/xdr.3

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