source: rtems/cpukit/librpc/src/xdr/xdr.3 @ f26145b

4.104.114.84.95
Last change on this file since f26145b was df49c60, checked in by Joel Sherrill <joel.sherrill@…>, on 06/12/00 at 15:00:15

Merged from 4.5.0-beta3a

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