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