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