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