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
|
| |