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