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