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