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