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