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