xref: /dragonfly/lib/libc/xdr/xdr.3 (revision e98bdfd3) 
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 July 30, 2015
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 xdr_sizeof ,
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 (*readit)(void)"
416.Fa "int (*writeit)(void)"
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 Xo
579.Ft unsigned long
580.Xc
581.It Xo
582.Fn xdr_sizeof "xdrproc_t func" "void *data"
583.Xc
584.Pp
585This routine returns the amount of memory required to encode
586.Fa data
587using filter
588.Fa func .
589.Pp
590.It Li "#ifdef _STDIO_H_"
591.It Li "/* XDR using stdio library */"
592.It Xo
593.Ft void
594.Xc
595.It Xo
596.Fn xdrstdio_create "XDR *xdrs" "FILE *file" "enum xdr_op op"
597.Xc
598.It Li "#endif"
599.Pp
600This routine initializes the
601.Tn XDR
602stream object pointed to by
603.Fa xdrs .
604The
605.Tn XDR
606stream data is written to, or read from, the Standard
607.Tn I/O
608stream
609.Fa file .
610The
611.Fa op
612argument
613determines the direction of the
614.Tn XDR
615stream (either
616.Dv XDR_ENCODE ,
617.Dv XDR_DECODE ,
618or
619.Dv XDR_FREE ) .
620.Pp
621Warning: the destroy routine associated with such
622.Tn XDR
623streams calls
624.Xr fflush 3
625on the
626.Fa file
627stream, but never
628.Xr fclose 3 .
629.Pp
630.It Xo
631.Ft int
632.Xc
633.It Xo
634.Fn xdr_string "XDR *xdrs" "char **sp" "u_int maxsize"
635.Xc
636.Pp
637A filter primitive that translates between C strings and
638their
639corresponding external representations.
640Strings cannot be longer than
641.Fa maxsize .
642Note:
643.Fa sp
644is the address of the string's pointer.
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_char "XDR *xdrs" "unsigned char *ucp"
652.Xc
653.Pp
654A filter primitive that translates between
655.Vt unsigned
656C characters 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_hyper "XDR *xdrs" "u_quad_t *ullp"
664.Xc
665A filter primitive that translates between
666.Vt unsigned
667ANSI C
668.Vt long long
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_int "XDR *xdrs" "unsigned *up"
677.Xc
678.Pp
679A filter primitive that translates between C
680.Vt unsigned
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_long "XDR *xdrs" "unsigned long *ulp"
689.Xc
690.Pp
691A filter primitive that translates between C
692.Vt "unsigned 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_longlong_t "XDR *xdrs" "u_quad_t *ullp"
701.Xc
702A filter primitive that translates between
703.Vt unsigned
704ANSI C
705.Vt "long long"
706integers and their external representations.
707This routine returns one if it succeeds, zero otherwise.
708.Pp
709.It Xo
710.Ft int
711.Xc
712.It Xo
713.Fn xdr_u_int64_t "XDR *xdrs" "u_int64_t *llp"
714.Xc
715A filter primitive that translates between C
716.Vt u_int64_t
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.Fn xdr_u_short "XDR *xdrs" "unsigned short *usp"
725.Xc
726.Pp
727A filter primitive that translates between C
728.Vt "unsigned short"
729integers and their external representations.
730This routine returns one if it succeeds, zero otherwise.
731.Pp
732.It Xo
733.Ft int
734.Xc
735.It Xo
736.Fo xdr_union
737.Fa "XDR *xdrs"
738.Fa "enum_t *dscmp"
739.Fa "char *unp"
740.Fa "const struct xdr_discrim *choices"
741.Fa "xdrproc_t defaultarm"
742.Fc
743.Xc
744.Pp
745A filter primitive that translates between a discriminated C
746.Vt union
747and its corresponding external representation.
748It first
749translates the discriminant of the union located at
750.Fa dscmp .
751This discriminant is always an
752.Vt enum_t .
753Next the union located at
754.Fa unp
755is translated.
756The
757.Fa choices
758argument
759is a pointer to an array of
760.Vt xdr_discrim
761structures.
762Each structure contains an ordered pair of
763.Bq Va value , proc .
764If the union's discriminant is equal to the associated
765.Va value ,
766then the
767.Fn proc
768is called to translate the union.
769The end of the
770.Vt xdr_discrim
771structure array is denoted by a routine of value
772.Dv NULL .
773If the discriminant is not found in the
774.Fa choices
775array, then the
776.Fn defaultarm
777procedure is called (if it is not
778.Dv NULL ) .
779Returns one if it succeeds, zero otherwise.
780.Pp
781.It Xo
782.Ft int
783.Xc
784.It Xo
785.Fo xdr_vector
786.Fa "XDR *xdrs"
787.Fa "char *arrp"
788.Fa "u_int size"
789.Fa "u_int elsize"
790.Fa "xdrproc_t elproc"
791.Fc
792.Xc
793.Pp
794A filter primitive that translates between fixed-length
795arrays
796and their corresponding external representations.
797The
798.Fa arrp
799argument
800is the address of the pointer to the array, while
801.Fa size
802is the element count of the array.
803The
804.Fa elsize
805argument
806is the
807.Ic sizeof
808each of the array's elements, and
809.Fa elproc
810is an
811.Tn XDR
812filter that translates between
813the array elements' C form, and their external
814representation.
815This routine returns one if it succeeds, zero otherwise.
816.Pp
817.It Xo
818.Ft int
819.Xc
820.It Xo
821.Fn xdr_void void
822.Xc
823.Pp
824This routine always returns one.
825It may be passed to
826.Tn RPC
827routines that require a function argument,
828where nothing is to be done.
829.Pp
830.It Xo
831.Ft int
832.Xc
833.It Xo
834.Fn xdr_wrapstring "XDR *xdrs" "char **sp"
835.Xc
836.Pp
837A primitive that calls
838.Fn xdr_string xdrs sp MAXUN.UNSIGNED ;
839where
840.Dv MAXUN.UNSIGNED
841is the maximum value of an unsigned integer.
842The
843.Fn xdr_wrapstring
844function
845is handy because the
846.Tn RPC
847package passes a maximum of two
848.Tn XDR
849routines as arguments, and
850.Fn xdr_string ,
851one of the most frequently used primitives, requires three.
852Returns one if it succeeds, zero otherwise.
853.El
854.Sh SEE ALSO
855.Xr rpc 3
856.Rs
857.%T "eXternal Data Representation Standard: Protocol Specification"
858.Re
859.Rs
860.%T "eXternal Data Representation: Sun Technical Notes"
861.Re
862.Rs
863.%T "XDR: External Data Representation Standard"
864.%O RFC 1014
865.%Q "Sun Microsystems, Inc., USC\-ISI"
866.Re
867