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