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