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