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