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