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