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 $
29 .Nm xdrrec_endofrecord ,
31 .Nm xdrrec_skiprecord ,
41 .Nm xdr_u_longlong_t ,
47 .Nd "library routines for external data representation"
56 for function declarations.
58 These routines allow C programmers to describe
59 arbitrary data structures in a machine-independent fashion.
60 Data for remote procedure calls are transmitted using these
63 .Bl -tag -width indent -compact
74 .Fa "xdrproc_t elproc"
78 A filter primitive that translates between variable-length
80 and their corresponding external representations.
84 is the address of the pointer to the array, while
86 is the address of the element count of the array;
87 this element count cannot exceed
94 each of the array's elements, and
98 filter that translates between
99 the array elements' C form, and their external
101 This routine returns one if it succeeds, zero otherwise.
107 .Fn xdr_bool "XDR *xdrs" "bool_t *bp"
110 A filter primitive that translates between booleans (C
112 and their external representations.
113 When encoding data, this
114 filter produces values of either one or zero.
115 This routine returns one if it succeeds, zero otherwise.
121 .Fn xdr_bytes "XDR *xdrs" "char **sp" "u_int *sizep" "u_int maxsize"
124 A filter primitive that translates between counted byte
125 strings and their external representations.
129 is the address of the string pointer.
131 string is located at address
133 strings cannot be longer than
135 This routine returns one if it succeeds, zero otherwise.
141 .Fn xdr_char "XDR *xdrs" "char *cp"
144 A filter primitive that translates between C characters
145 and their external representations.
146 This routine returns one if it succeeds, zero otherwise.
147 Note: encoded characters are not packed, and occupy 4 bytes
149 For arrays of characters, it is worthwhile to
160 .Fn xdr_destroy "XDR *xdrs"
163 A macro that invokes the destroy routine associated with the
167 Destruction usually involves freeing private data structures
168 associated with the stream.
179 .Fn xdr_double "XDR *xdrs" "double *dp"
182 A filter primitive that translates between C
184 precision numbers and their external representations.
185 This routine returns one if it succeeds, zero otherwise.
191 .Fn xdr_enum "XDR *xdrs" "enum_t *ep"
194 A filter primitive that translates between C
196 (actually integers) and their external representations.
197 This routine returns one if it succeeds, zero otherwise.
203 .Fn xdr_float "XDR *xdrs" "float *fp"
206 A filter primitive that translates between C
208 and their external representations.
209 This routine returns one if it succeeds, zero otherwise.
215 .Fn xdr_free "xdrproc_t proc" "void *objp"
218 Generic freeing routine.
219 The first argument is the
221 routine for the object being freed.
223 is a pointer to the object itself.
224 Note: the pointer passed
227 freed, but what it points to
235 .Fn xdr_getpos "XDR *xdrs"
238 A macro that invokes the get\-position routine
243 The routine returns an unsigned integer,
244 which indicates the position of the
247 A desirable feature of
249 streams is that simple arithmetic works with this number,
252 stream instances need not guarantee this.
258 .Fn xdr_hyper "XDR *xdrs" "quad_t *llp"
260 A filter primitive that translates between ANSI C
262 integers and their external representations.
263 This routine returns one if it succeeds, zero otherwise.
269 .Fn xdr_inline "XDR *xdrs" "int len"
272 A macro that invokes the in-line routine associated with the
276 The routine returns a pointer
277 to a contiguous piece of the stream's buffer;
279 is the byte length of the desired buffer.
280 Note: pointer is cast to
288 if it cannot allocate a contiguous piece of a buffer.
289 Therefore the behavior may vary among stream instances;
290 it exists for the sake of efficiency.
296 .Fn xdr_int "XDR *xdrs" "int *ip"
299 A filter primitive that translates between C integers
300 and their external representations.
301 This routine returns one if it succeeds, zero otherwise.
307 .Fn xdr_long "XDR *xdrs" "long *lp"
310 A filter primitive that translates between C
312 integers and their external representations.
313 This routine returns one if it succeeds, zero otherwise.
319 .Fn xdr_longlong_t "XDR *xdrs" "quad_t *llp"
321 A filter primitive that translates between ANSI C
323 integers and their external representations.
324 This routine returns one if it succeeds, zero otherwise.
330 .Fn xdrmem_create "XDR *xdrs" "char *addr" "u_int size" "enum xdr_op op"
333 This routine initializes the
335 stream object pointed to by
337 The stream's data is written to, or read from,
338 a chunk of memory at location
340 whose length is no more than
346 determines the direction of the
359 .Fn xdr_opaque "XDR *xdrs" "char *cp" "u_int cnt"
362 A filter primitive that translates between fixed size opaque
364 and its external representation.
368 is the address of the opaque object, and
370 is its size in bytes.
371 This routine returns one if it succeeds, zero otherwise.
377 .Fn xdr_pointer "XDR *xdrs" "char **objpp" "u_int objsize" "xdrproc_t xdrobj"
382 except that it serializes
390 recursive data structures, such as binary trees or
402 .Fa "int \*(lp*readit\*(rp\*(lp\*(rp"
403 .Fa "int \*(lp*writeit\*(rp\*(lp\*(rp"
407 This routine initializes the
409 stream object pointed to by
411 The stream's data is written to a buffer of size
413 a value of zero indicates the system should use a suitable
415 The stream's data is read from a buffer of size
417 it too can be set to a suitable default by passing a zero
419 When a stream's output buffer is full,
422 Similarly, when a stream's input buffer is empty,
425 The behavior of these two routines is similar to
433 is passed to the former routines as the first argument.
438 field must be set by the caller.
442 stream implements an intermediate record stream.
443 Therefore there are additional bytes in the stream
444 to provide record boundary information.
450 .Fn xdrrec_endofrecord "XDR *xdrs" "int sendnow"
453 This routine can be invoked only on
456 The data in the output buffer is marked as a completed
458 and the output buffer is optionally written out if
461 This routine returns one if it succeeds, zero
468 .Fn xdrrec_eof "XDR *xdrs"
471 This routine can be invoked only on
474 After consuming the rest of the current record in the stream,
475 this routine returns one if the stream has no more input,
482 .Fn xdrrec_skiprecord "XDR *xdrs"
485 This routine can be invoked only on
490 implementation that the rest of the current record
491 in the stream's input buffer should be discarded.
492 This routine returns one if it succeeds, zero otherwise.
498 .Fn xdr_reference "XDR *xdrs" "char **pp" "u_int size" "xdrproc_t proc"
501 A primitive that provides pointer chasing within structures.
505 is the address of the pointer;
515 procedure that filters the structure
516 between its C form and its external representation.
517 This routine returns one if it succeeds, zero otherwise.
519 Warning: this routine does not understand
530 .Fn xdr_setpos "XDR *xdrs" "u_int pos"
533 A macro that invokes the set position routine associated with
541 is a position value obtained from
543 This routine returns one if the
545 stream could be repositioned,
548 Warning: it is difficult to reposition some types of
550 streams, so this routine may fail with one
551 type of stream and succeed with another.
557 .Fn xdr_short "XDR *xdrs" "short *sp"
560 A filter primitive that translates between C
562 integers and their external representations.
563 This routine returns one if it succeeds, zero otherwise.
565 .It Li "#ifdef _STDIO_H_"
566 .It Li "/* XDR using stdio library */"
571 .Fn xdrstdio_create "XDR *xdrs" "FILE *file" "enum xdr_op op"
575 This routine initializes the
577 stream object pointed to by
581 stream data is written to, or read from, the Standard
588 determines the direction of the
596 Warning: the destroy routine associated with such
609 .Fn xdr_string "XDR *xdrs" "char **sp" "u_int maxsize"
612 A filter primitive that translates between C strings and
614 corresponding external representations.
615 Strings cannot be longer than
619 is the address of the string's pointer.
620 This routine returns one if it succeeds, zero otherwise.
626 .Fn xdr_u_char "XDR *xdrs" "unsigned char *ucp"
629 A filter primitive that translates between
631 C characters and their external representations.
632 This routine returns one if it succeeds, zero otherwise.
638 .Fn xdr_u_hyper "XDR *xdrs" "u_quad_t *ullp"
640 A filter primitive that translates between
644 integers and their external representations.
645 This routine returns one if it succeeds, zero otherwise.
651 .Fn xdr_u_int "XDR *xdrs" "unsigned *up"
654 A filter primitive that translates between C
656 integers and their external representations.
657 This routine returns one if it succeeds, zero otherwise.
663 .Fn xdr_u_long "XDR *xdrs" "unsigned long *ulp"
666 A filter primitive that translates between C
668 integers and their external representations.
669 This routine returns one if it succeeds, zero otherwise.
675 .Fn xdr_u_longlong_t "XDR *xdrs" "u_quad_t *ullp"
677 A filter primitive that translates between
681 integers and their external representations.
682 This routine returns one if it succeeds, zero otherwise.
688 .Fn xdr_u_short "XDR *xdrs" "unsigned short *usp"
691 A filter primitive that translates between C
693 integers and their external representations.
694 This routine returns one if it succeeds, zero otherwise.
704 .Fa "const struct xdr_discrim *choices"
705 .Fa "xdrproc_t defaultarm"
709 A filter primitive that translates between a discriminated C
711 and its corresponding external representation.
713 translates the discriminant of the union located at
715 This discriminant is always an
717 Next the union located at
723 is a pointer to an array of
726 Each structure contains an ordered pair of
727 .Bq Va value , proc .
728 If the union's discriminant is equal to the associated
732 is called to translate the union.
735 structure array is denoted by a routine of value
737 If the discriminant is not found in the
741 procedure is called (if it is not
743 Returns one if it succeeds, zero otherwise.
754 .Fa "xdrproc_t elproc"
758 A filter primitive that translates between fixed-length
760 and their corresponding external representations.
764 is the address of the pointer to the array, while
766 is the element count of the array.
772 each of the array's elements, and
776 filter that translates between
777 the array elements' C form, and their external
779 This routine returns one if it succeeds, zero otherwise.
788 This routine always returns one.
791 routines that require a function argument,
792 where nothing is to be done.
798 .Fn xdr_wrapstring "XDR *xdrs" "char **sp"
801 A primitive that calls
802 .Fn xdr_string xdrs sp MAXUN.UNSIGNED ;
805 is the maximum value of an unsigned integer.
811 package passes a maximum of two
813 routines as arguments, and
815 one of the most frequently used primitives, requires three.
816 Returns one if it succeeds, zero otherwise.
821 .%T "eXternal Data Representation Standard: Protocol Specification"
824 .%T "eXternal Data Representation: Sun Technical Notes"
827 .%T "XDR: External Data Representation Standard"
829 .%Q "Sun Microsystems, Inc., USC\-ISI"