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