xref: /freebsd/lib/libc/xdr/xdr.3 (revision 2be1a816b9ff69588e55be0a84cbe2a31efc0f2f) 
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
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
81.Fa arrp
82argument
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
89.Fa elsize
90argument
91is the
92.Ic sizeof
93each of the array's elements, and
94.Fa elproc
95is an
96.Tn XDR
97filter that translates between
98the array elements' C form, and their external
99representation.
100This 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
109A filter primitive that translates between booleans (C
110integers)
111and their external representations.
112When encoding data, this
113filter produces values of either one or zero.
114This 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
123A filter primitive that translates between counted byte
124strings and their external representations.
125The
126.Fa sp
127argument
128is the address of the string pointer.
129The length of the
130string is located at address
131.Fa sizep ;
132strings cannot be longer than
133.Fa maxsize .
134This 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
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
147each.
148For arrays of characters, it is worthwhile to
149consider
150.Fn xdr_bytes ,
151.Fn xdr_opaque
152or
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
162A macro that invokes the destroy routine associated with the
163.Tn XDR
164stream,
165.Fa xdrs .
166Destruction usually involves freeing private data structures
167associated with the stream.
168Using
169.Fa xdrs
170after invoking
171.Fn xdr_destroy
172is 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
181A filter primitive that translates between C
182.Vt double
183precision numbers and their external representations.
184This 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
193A filter primitive that translates between C
194.Vt enum Ns s
195(actually integers) and their external representations.
196This 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
205A filter primitive that translates between C
206.Vt float Ns s
207and their external representations.
208This 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
224to this routine is
225.Em not
226freed, but what it points to
227.Em is
228freed (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
238associated with the
239.Tn XDR
240stream,
241.Fa xdrs .
242The routine returns an unsigned integer,
243which indicates the position of the
244.Tn XDR
245byte stream.
246A desirable feature of
247.Tn XDR
248streams is that simple arithmetic works with this number,
249although the
250.Tn XDR
251stream 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
271A macro that invokes the in-line routine associated with the
272.Tn XDR
273stream,
274.Fa xdrs .
275The routine returns a pointer
276to a contiguous piece of the stream's buffer;
277.Fa len
278is the byte length of the desired buffer.
279Note: pointer is cast to
280.Vt "long *" .
281.Pp
282Warning:
283.Fn xdr_inline
284may return
285.Dv 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.
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
298A filter primitive that translates between C integers
299and their external representations.
300This 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
309A filter primitive that translates between C
310.Vt long
311integers and their external representations.
312This 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
332This routine initializes the
333.Tn XDR
334stream object pointed to by
335.Fa xdrs .
336The stream's data is written to, or read from,
337a chunk of memory at location
338.Fa addr
339whose length is no more than
340.Fa size
341bytes long.
342The
343.Fa op
344argument
345determines the direction of the
346.Tn XDR
347stream
348(either
349.Dv XDR_ENCODE ,
350.Dv XDR_DECODE ,
351or
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
361A filter primitive that translates between fixed size opaque
362data
363and its external representation.
364The
365.Fa cp
366argument
367is the address of the opaque object, and
368.Fa cnt
369is its size in bytes.
370This 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
379Like
380.Fn xdr_reference
381except that it serializes
382.Dv NULL
383pointers, whereas
384.Fn xdr_reference
385does not.
386Thus,
387.Fn xdr_pointer
388can represent
389recursive data structures, such as binary trees or
390linked 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
406This routine initializes the
407.Tn XDR
408stream object pointed to by
409.Fa xdrs .
410The stream's data is written to a buffer of size
411.Fa sendsize ;
412a 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 ;
416it too can be set to a suitable default by passing a zero
417value.
418When 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
425the
426system calls
427.Xr read 2
428and
429.Xr write 2 ,
430except that
431.Fa handle
432is passed to the former routines as the first argument.
433Note: the
434.Tn XDR
435stream's
436.Fa op
437field must be set by the caller.
438.Pp
439Warning: this
440.Tn XDR
441stream implements an intermediate record stream.
442Therefore there are additional bytes in the stream
443to 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
452This routine can be invoked only on
453streams created by
454.Fn xdrrec_create .
455The data in the output buffer is marked as a completed
456record,
457and the output buffer is optionally written out if
458.Fa sendnow
459is non-zero.
460This routine returns one if it succeeds, zero
461otherwise.
462.Pp
463.It Xo
464.Ft int
465.Xc
466.It Xo
467.Fn xdrrec_eof "XDR *xdrs"
468.Xc
469.Pp
470This routine can be invoked only on
471streams created by
472.Fn 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.
476.Pp
477.It Xo
478.Ft int
479.Xc
480.It Xo
481.Fn xdrrec_skiprecord "XDR *xdrs"
482.Xc
483.Pp
484This routine can be invoked only on
485streams created by
486.Fn xdrrec_create .
487It tells the
488.Tn 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.
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
500A primitive that provides pointer chasing within structures.
501The
502.Fa pp
503argument
504is the address of the pointer;
505.Fa size
506is the
507.Ic sizeof
508the structure that
509.Fa *pp
510points to; and
511.Fa proc
512is an
513.Tn XDR
514procedure that filters the structure
515between its C form and its external representation.
516This routine returns one if it succeeds, zero otherwise.
517.Pp
518Warning: this routine does not understand
519.Dv NULL
520pointers.
521Use
522.Fn xdr_pointer
523instead.
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
532A macro that invokes the set position routine associated with
533the
534.Tn XDR
535stream
536.Fa xdrs .
537The
538.Fa pos
539argument
540is a position value obtained from
541.Fn xdr_getpos .
542This routine returns one if the
543.Tn XDR
544stream could be repositioned,
545and zero otherwise.
546.Pp
547Warning: it is difficult to reposition some types of
548.Tn XDR
549streams, so this routine may fail with one
550type 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
559A filter primitive that translates between C
560.Vt short
561integers and their external representations.
562This 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
574This routine initializes the
575.Tn XDR
576stream object pointed to by
577.Fa xdrs .
578The
579.Tn XDR
580stream data is written to, or read from, the Standard
581.Tn I/O
582stream
583.Fa file .
584The
585.Fa op
586argument
587determines the direction of the
588.Tn XDR
589stream (either
590.Dv XDR_ENCODE ,
591.Dv XDR_DECODE ,
592or
593.Dv XDR_FREE ) .
594.Pp
595Warning: the destroy routine associated with such
596.Tn XDR
597streams calls
598.Xr fflush 3
599on the
600.Fa file
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
611A filter primitive that translates between C strings and
612their
613corresponding external representations.
614Strings cannot be longer than
615.Fa maxsize .
616Note:
617.Fa sp
618is the address of the string's pointer.
619This 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
628A filter primitive that translates between
629.Vt unsigned
630C characters and their external representations.
631This 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
653A filter primitive that translates between C
654.Vt unsigned
655integers and their external representations.
656This 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
665A filter primitive that translates between C
666.Vt "unsigned long"
667integers and their external representations.
668This 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
690A filter primitive that translates between C
691.Vt "unsigned short"
692integers and their external representations.
693This 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
708A filter primitive that translates between a discriminated C
709.Vt union
710and its corresponding external representation.
711It first
712translates the discriminant of the union located at
713.Fa dscmp .
714This discriminant is always an
715.Vt enum_t .
716Next the union located at
717.Fa unp
718is translated.
719The
720.Fa choices
721argument
722is a pointer to an array of
723.Vt xdr_discrim
724structures.
725Each structure contains an ordered pair of
726.Bq Va value , proc .
727If the union's discriminant is equal to the associated
728.Va value ,
729then the
730.Fn proc
731is called to translate the union.
732The end of the
733.Vt xdr_discrim
734structure array is denoted by a routine of value
735.Dv NULL .
736If the discriminant is not found in the
737.Fa choices
738array, then the
739.Fn defaultarm
740procedure is called (if it is not
741.Dv NULL ) .
742Returns 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
757A filter primitive that translates between fixed-length
758arrays
759and their corresponding external representations.
760The
761.Fa arrp
762argument
763is the address of the pointer to the array, while
764.Fa size
765is the element count of the array.
766The
767.Fa elsize
768argument
769is the
770.Ic sizeof
771each of the array's elements, and
772.Fa elproc
773is an
774.Tn XDR
775filter that translates between
776the array elements' C form, and their external
777representation.
778This 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
787This routine always returns one.
788It may be passed to
789.Tn RPC
790routines that require a function argument,
791where 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
800A primitive that calls
801.Fn xdr_string xdrs sp MAXUN.UNSIGNED ;
802where
803.Dv MAXUN.UNSIGNED
804is the maximum value of an unsigned integer.
805The
806.Fn xdr_wrapstring
807function
808is handy because the
809.Tn RPC
810package passes a maximum of two
811.Tn XDR
812routines as arguments, and
813.Fn xdr_string ,
814one of the most frequently used primitives, requires three.
815Returns 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
830