1.\" @(#)xdr.3n 2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI 2.\" $NetBSD: xdr.3,v 1.14 2011/07/08 19:28:22 wiz Exp $ 3.\" 4.Dd July 4, 2011 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_long , 40.Nm xdr_u_longlong_t , 41.Nm xdr_u_short , 42.Nm xdr_union , 43.Nm xdr_vector , 44.Nm xdr_void , 45.Nm xdr_wrapstring 46.Nd library routines for external data representation 47.Sh SYNOPSIS 48.Ft int 49.Fn xdr_array "XDR *xdrs" "char **arrp" "u_int *sizep" "u_int maxsize" \ 50"u_int elsize" "xdrproc_t elproc" 51.Ft int 52.Fn xdr_bool "XDR *xdrs" "bool_t *bp" 53.Ft int 54.Fn xdr_bytes "XDR *xdrs" "char **sp" "u_int *sizep" "u_int maxsize" 55.Ft int 56.Fn xdr_char "XDR *xdrs" "char *cp" 57.Ft void 58.Fn xdr_destroy "XDR *xdrs" 59.Ft int 60.Fn xdr_double "XDR *xdrs" "double *dp" 61.Ft int 62.Fn xdr_enum "XDR *xdrs" "enum_t *ep" 63.Ft int 64.Fn xdr_float "XDR *xdrs" "float *fp" 65.Ft void 66.Fn xdr_free "xdrproc_t proc" "char *objp" 67.Ft u_int 68.Fn xdr_getpos "XDR *xdrs" 69.Ft int 70.Fn xdr_hyper "XDR *xdrs" "longlong_t *llp" 71.Ft long * 72.Fn xdr_inline "XDR *xdrs" "int len" 73.Ft int 74.Fn xdr_int "XDR *xdrs" "int *ip" 75.Ft int 76.Fn xdr_long "XDR *xdrs" "long *lp" 77.Ft int 78.Fn xdr_longlong_t "XDR *xdrs" "longlong_t *llp" 79.Ft void 80.Fn xdrmem_create "XDR *xdrs" "char *addr" "u_int size" \ 81"enum xdr_op op" 82.Ft int 83.Fn xdr_opaque "XDR *xdrs" "char *cp" "u_int cnt" 84.Ft int 85.Fn xdr_pointer "XDR *xdrs" "char **objpp" "u_int objsize" \ 86"xdrproc_t xdrobj" 87.Ft void 88.Fn xdrrec_create "XDR *xdrs" "u_int sendsize" "u_int recvsize" \ 89"char *handle" "int (*readit)()" "int (*writeit)()" 90.Ft int 91.Fn xdrrec_endofrecord "XDR *xdrs" "int sendnow" 92.Ft int 93.Fn xdrrec_eof "XDR *xdrs" 94.Ft int 95.Fn xdrrec_skiprecord "XDR *xdrs" 96.Ft int 97.Fn xdr_reference "XDR *xdrs" "char **pp" "u_int size" \ 98"xdrproc_t proc" 99.Ft int 100.Fn xdr_setpos "XDR *xdrs" "u_int pos" 101.Ft int 102.Fn xdr_short "XDR *xdrs" "short *sp" 103.Ft nsigned long 104.Fn xdr_sizeof "xdrproc_t func" "void *data" 105.Ft void 106.Fn xdrstdio_create "XDR *xdrs" "FILE *file" "enum xdr_op op" 107.Ft int 108.Fn xdr_string "XDR *xdrs" "char **sp" "u_int maxsize" 109.Ft int 110.Fn xdr_u_char "XDR *xdrs" "unsigned char *ucp" 111.Ft int 112.Fn xdr_u_hyper "XDR *xdrs" "u_longlong_t *ullp" 113.Ft int 114.Fn xdr_u_int "XDR *xdrs" "unsigned *up" 115.Ft int 116.Fn xdr_u_long "XDR *xdrs" "unsigned long *ulp" 117.Ft int 118.Fn xdr_u_longlong_t "XDR *xdrs" "u_longlong_t *ullp" 119.Ft int 120.Fn xdr_u_short "XDR *xdrs" "unsigned short *usp" 121.Ft int 122.Fn xdr_union "XDR *xdrs" "int *dscmp" "char *unp" \ 123"struct xdr_discrim *choices" "bool_t (*defaultarm)(\|)" 124.Ft int 125.Fn xdr_vector "XDR *xdrs" "char *arrp" "u_int size" \ 126"u_int elsize" "xdrproc_t elproc" 127.Ft int 128.Fn xdr_void "void" 129.Ft int 130.Fn xdr_wrapstring "XDR *xdrs" "char **sp" 131.Sh DESCRIPTION 132These routines allow C programmers to describe 133arbitrary data structures in a machine-independent fashion. 134Data for remote procedure calls are transmitted using these 135routines. 136.Bl -tag -width xxx 137.It Fn xdr_array 138A filter primitive that translates between variable-length 139arrays and their corresponding external representations. 140The parameter 141.Fa arrp 142is the address of the pointer to the array, while 143.Fa sizep 144is the address of the element count of the array; 145this element count cannot exceed 146.Fa maxsize . 147The parameter 148.Fa elsize 149is the 150.Em sizeof 151each of the array's elements, and 152.Fa elproc 153is an XDR filter that translates between the array elements' C form, 154and their external representation. 155This routine returns one if it succeeds, zero otherwise. 156.It Fn xdr_bool 157A filter primitive that translates between booleans (C integers) 158and their external representations. 159When encoding data, this filter produces values of either one or 160zero. 161This routine returns one if it succeeds, zero otherwise. 162.It Fn xdr_bytes 163A filter primitive that translates between counted byte 164strings and their external representations. 165The parameter 166.Fa sp 167is the address of the string pointer. 168The length of the string is located at address 169.Fa sizep ; 170strings cannot be longer than 171.Fa maxsize . 172This routine returns one if it succeeds, zero otherwise. 173.It Fn xdr_char 174A filter primitive that translates between C characters 175and their external representations. 176This routine returns one if it succeeds, zero otherwise. 177Note: encoded characters are not packed, and occupy 4 bytes each. 178For arrays of characters, it is worthwhile to consider 179.Fn xdr_bytes , 180.Fn xdr_opaque 181or 182.Fn xdr_string . 183.It Fn xdr_destroy 184A macro that invokes the destroy routine associated with the XDR 185stream, 186.Fa xdrs . 187Destruction usually involves freeing private data structures 188associated with the stream. 189Using 190.Fa xdrs 191after invoking 192.Fn xdr_destroy 193is undefined. 194.It Fn xdr_double 195A filter primitive that translates between C double precision numbers 196and their external representations. 197This routine returns one if it succeeds, zero otherwise. 198.It Fn xdr_enum 199A filter primitive that translates between C enums (actually integers) 200and their external representations. 201This routine returns one if it succeeds, zero otherwise. 202.It Fn xdr_float 203A filter primitive that translates between C floats 204and their external representations. 205This routine returns one if it succeeds, zero otherwise. 206.It Fn xdr_free 207Generic freeing routine. 208The first argument is the XDR routine for the object being freed. 209The second argument is a pointer to the object itself. 210Note: the pointer passed to this routine is 211.Em not 212freed, but what it points to 213.Em is 214freed (recursively). 215.It Fn xdr_getpos 216A macro that invokes the get-position routine associated with the XDR 217stream, 218.Fa xdrs . 219The routine returns an unsigned integer, which indicates the position 220of the XDR byte stream. 221A desirable feature of XDR streams is that simple arithmetic works 222with this number, although the XDR stream instances need not guarantee 223this. 224.It Fn xdr_hyper 225A filter primitive that translates between ANSI C long long integers 226and their external representations. 227This routine returns one if it succeeds, zero otherwise. 228.It Fn xdr_inline 229A macro that invokes the in-line routine associated with the XDR 230stream, 231.Fa xdrs . 232The routine returns a pointer 233to a contiguous piece of the stream's buffer; 234.Fa len 235is the byte length of the desired buffer. 236Note: pointer is cast to 237.Vt "long *" . 238.Pp 239Warning: 240.Fn xdr_inline 241may return 242.Dv NULL 243if it cannot allocate a contiguous piece of a buffer. 244Therefore the behavior may vary among stream instances; 245it exists for the sake of efficiency. 246.It Fn xdr_int 247A filter primitive that translates between C integers 248and their external representations. 249This routine returns one if it succeeds, zero otherwise. 250.It Fn xdr_long 251A filter primitive that translates between C long integers 252and their external representations. 253This routine returns one if it succeeds, zero otherwise. 254.It Fn xdr_longlong_t 255A filter primitive that translates between ANSI C long long integers 256and their external representations. 257This routine returns one if it succeeds, zero otherwise. 258.It Fn xdrmem_create 259This routine initializes the XDR stream object pointed to by 260.Fa xdrs . 261The stream's data is written to, or read from, 262a chunk of memory at location 263.Fa addr 264whose length is no more than 265.Fa size 266bytes long. 267The 268.Fa op 269determines the direction of the XDR stream (either 270.Dv XDR_ENCODE , 271.Dv XDR_DECODE , 272or 273.Dv XDR_FREE ) . 274.It Fn xdr_opaque 275A filter primitive that translates between fixed size opaque data 276and its external representation. 277The parameter 278.Fa cp 279is the address of the opaque object, and 280.Fa cnt 281is its size in bytes. 282This routine returns one if it succeeds, zero otherwise. 283.It Fn xdr_pointer 284Like 285.Fn xdr_reference 286except that it serializes 287.Dv NULL 288pointers, whereas 289.Fn xdr_reference 290does not. 291Thus, 292.Fn xdr_pointer 293can represent recursive data structures, such as binary trees or 294linked lists. 295.It Fn xdrrec_create 296This routine initializes the XDR stream object pointed to by 297.Fa xdrs . 298The stream's data is written to a buffer of size 299.Fa sendsize ; 300a value of zero indicates the system should use a suitable default. 301The stream's data is read from a buffer of size 302.Fa recvsize ; 303it too can be set to a suitable default by passing a zero value. 304When a stream's output buffer is full, 305.Fa writeit 306is called. 307Similarly, when a stream's input buffer is empty, 308.Fa readit 309is called. 310The behavior of these two routines is similar to the system calls 311.Xr read 2 312and 313.Xr write 2 , 314except that 315.Fa handle 316is passed to the former routines as the first parameter. 317Note: the XDR stream's 318.Fa op 319field must be set by the caller. 320.Pp 321Warning: this XDR stream implements an intermediate record stream. 322Therefore there are additional bytes in the stream 323to provide record boundary information. 324.It Fn xdrrec_endofrecord 325This routine can be invoked only on streams created by 326.Fn xdrrec_create . 327The data in the output buffer is marked as a completed record, 328and the output buffer is optionally written out if 329.Fa sendnow 330is non-zero. 331This routine returns one if it succeeds, zero otherwise. 332.It Fn xdrrec_eof 333This routine can be invoked only on streams created by 334.Fn xdrrec_create . 335After consuming the rest of the current record in the stream, 336this routine returns one if the stream has no more input, 337zero otherwise. 338.It Fn xdrrec_skiprecord 339This routine can be invoked only on streams created by 340.Fn xdrrec_create . 341It tells the XDR implementation that the rest of the current record 342in the stream's input buffer should be discarded. 343This routine returns one if it succeeds, zero otherwise. 344.It Fn xdr_reference 345A primitive that provides pointer chasing within structures. 346The parameter 347.Fa pp 348is the address of the pointer; 349.Fa size 350is the 351.Em sizeof 352the structure that 353.Fa *pp 354points to; and 355.Fa proc 356is an XDR procedure that filters the structure 357between its C form and its external representation. 358This routine returns one if it succeeds, zero otherwise. 359.Pp 360Warning: this routine does not understand 361.Dv NULL 362pointers. 363Use 364.Fn xdr_pointer 365instead. 366.It Fn xdr_setpos 367A macro that invokes the set position routine associated with the XDR 368stream 369.Fa xdrs . 370The parameter 371.Fa pos 372is a position value obtained from 373.Fn xdr_getpos . 374This routine returns one if the XDR stream could be repositioned, 375and zero otherwise. 376.Pp 377Warning: it is difficult to reposition some types of XDR streams, so 378this routine may fail with one type of stream and succeed with 379another. 380.It Fn xdr_short 381A filter primitive that translates between C short integers 382and their external representations. 383This routine returns one if it succeeds, zero otherwise. 384.It Fn xdr_sizeof 385This routine returns the amount of memory required to encode 386.Fa data 387using filter 388.Fa func . 389.It Fn xdrstdio_create 390This routine initializes the XDR stream object pointed to by 391.Fa xdrs . 392The XDR stream data is written to, or read from, the Standard I/O 393stream 394.Fa file . 395The parameter 396.Fa op 397determines the direction of the XDR stream (either 398.Dv XDR_ENCODE , 399.Dv XDR_DECODE , 400or 401.Dv XDR_FREE ) . 402.Pp 403Warning: the destroy routine associated with such XDR streams calls 404.Xr fflush 3 405on the file stream, but never 406.Xr fclose 3 . 407.It Fn xdr_string 408A filter primitive that translates between C strings and 409their corresponding external representations. 410Strings cannot be longer than 411.Fa maxsize . 412Note: 413.Fa sp 414is the address of the string's pointer. 415This routine returns one if it succeeds, zero otherwise. 416.It Fn xdr_u_char 417A filter primitive that translates between unsigned C characters 418and their external representations. 419This routine returns one if it succeeds, zero otherwise. 420.It Fn xdr_u_hyper 421A filter primitive that translates between unsigned ANSI C long long 422integers and their external representations. 423This routine returns one if it succeeds, zero otherwise. 424.It Fn xdr_u_int 425A filter primitive that translates between C unsigned integers 426 and their external representations. 427This routine returns one if it succeeds, zero otherwise. 428.It Fn xdr_u_long 429A filter primitive that translates between C unsigned long integers 430and their external representations. 431This routine returns one if it succeeds, zero otherwise. 432.It Fn xdr_u_longlong_t 433A filter primitive that translates between unsigned ANSI C long long 434integers and their external representations. 435This routine returns one if it succeeds, zero otherwise. 436.It Fn xdr_u_short 437A filter primitive that translates between C unsigned short integers 438and their external representations. 439This routine returns one if it succeeds, zero otherwise. 440.It Fn xdr_union 441A filter primitive that translates between a discriminated C union 442and its corresponding external representation. 443It first translates the discriminant of the union located at 444.Fa dscmp . 445This discriminant is always an enum_t. 446Next the union located at 447.Fa unp 448is translated. 449The parameter 450.Fa choices 451is a pointer to an array of 452.Fn xdr_discrim 453structures. 454Each structure contains an ordered pair of 455.Fa [ value , 456.Fa proc ] . 457If the union's discriminant is equal to the associated 458.Fa value , 459then the 460.Fa proc 461is called to translate the union. 462The end of the 463.Fn xdr_discrim 464structure array is denoted by a routine of value 465.Dv NULL . 466If the discriminant is not found in the 467.Fa choices 468array, then the 469.Fa defaultarm 470procedure is called (if it is not 471.Dv NULL ) . 472Returns one if it succeeds, zero otherwise. 473.It Fn xdr_vector 474A filter primitive that translates between fixed-length 475arrays and their corresponding external representations. 476The parameter 477.Fa arrp 478is the address of the pointer to the array, while 479.Fa size 480is the element count of the array. 481The parameter 482.Fa elsize 483is the 484.Em sizeof 485each of the array's elements, and 486.Fa elproc 487is an XDR filter that translates between the array elements' C form, 488and their external representation. 489This routine returns one if it succeeds, zero otherwise. 490.It Fn xdr_void 491This routine always returns one. 492It may be passed to RPC routines that require a function parameter, 493where nothing is to be done. 494.It Fn xdr_wrapstring 495A primitive that calls 496.Fn xdr_string "xdrs" "sp" "MAXUN.UNSIGNED" ; 497where 498.Dv MAXUN.UNSIGNED 499is the maximum value of an unsigned integer. 500.Fn xdr_wrapstring 501is handy because the RPC package passes a maximum of two XDR 502routines as parameters, and 503.Fn xdr_string , 504one of the most frequently used primitives, requires three. 505Returns one if it succeeds, zero otherwise. 506.El 507.Sh SEE ALSO 508.Xr rpc 3 509.Pp 510The following manuals: 511.Rs 512.%B "eXternal Data Representation Standard: Protocol Specification" 513.Re 514.Rs 515.%B "eXternal Data Representation: Sun Technical Notes" 516.Re 517.Rs 518.%A Sun Microsystems, Inc., USC-ISI 519.%T "XDR: External Data Representation Standard" 520.%R "RFC 1014, USC-ISI" 521.%V 1014 522.Re 523