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