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