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