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