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 $
10 .Nd "library routines for external data representation"
19 for function declarations.
21 These routines allow C programmers to describe
22 arbitrary data structures in a machine-independent fashion.
23 Data for remote procedure calls are transmitted using these
26 .Bl -tag -width indent -compact
37 .Fa "xdrproc_t elproc"
41 A filter primitive that translates between variable-length
43 and their corresponding external representations.
47 is the address of the pointer to the array, while
49 is the address of the element count of the array;
50 this element count cannot exceed
56 each of the array's elements, and
60 filter that translates between
61 the array elements' C form, and their external
63 This routine returns one if it succeeds, zero otherwise.
69 .Fn xdr_bool "XDR *xdrs" "bool_t *bp"
72 A filter primitive that translates between booleans (C
74 and their external representations.
75 When encoding data, this
76 filter produces values of either one or zero.
77 This routine returns one if it succeeds, zero otherwise.
83 .Fn xdr_bytes "XDR *xdrs" "char **sp" "u_int *sizep" "u_int maxsize"
86 A filter primitive that translates between counted byte
87 strings and their external representations.
90 is the address of the string pointer.
92 string is located at address
94 strings cannot be longer than
96 This routine returns one if it succeeds, zero otherwise.
102 .Fn xdr_char "XDR *xdrs" "char *cp"
105 A filter primitive that translates between C characters
106 and their external representations.
107 This routine returns one if it succeeds, zero otherwise.
108 Note: encoded characters are not packed, and occupy 4 bytes
110 For arrays of characters, it is worthwhile to
121 .Fn xdr_destroy "XDR *xdrs"
124 A macro that invokes the destroy routine associated with the
128 Destruction usually involves freeing private data structures
129 associated with the stream.
140 .Fn xdr_double "XDR *xdrs" "double *dp"
143 A filter primitive that translates between C
145 precision numbers and their external representations.
146 This routine returns one if it succeeds, zero otherwise.
152 .Fn xdr_enum "XDR *xdrs" "enum_t *ep"
155 A filter primitive that translates between C
157 (actually integers) and their external representations.
158 This routine returns one if it succeeds, zero otherwise.
164 .Fn xdr_float "XDR *xdrs" "float *fp"
167 A filter primitive that translates between C
169 and their external representations.
170 This routine returns one if it succeeds, zero otherwise.
176 .Fn xdr_free "xdrproc_t proc" "char *objp"
179 Generic freeing routine.
180 The first argument is the
182 routine for the object being freed.
184 is a pointer to the object itself.
185 Note: the pointer passed
188 freed, but what it points to
196 .Fn xdr_getpos "XDR *xdrs"
199 A macro that invokes the get\-position routine
204 The routine returns an unsigned integer,
205 which indicates the position of the
208 A desirable feature of
210 streams is that simple arithmetic works with this number,
213 stream instances need not guarantee this.
219 .Fn xdr_inline "XDR *xdrs" "int len"
222 A macro that invokes the in-line routine associated with the
226 The routine returns a pointer
227 to a contiguous piece of the stream's buffer;
229 is the byte length of the desired buffer.
230 Note: pointer is cast to
238 if it cannot allocate a contiguous piece of a buffer.
239 Therefore the behavior may vary among stream instances;
240 it exists for the sake of efficiency.
246 .Fn xdr_int "XDR *xdrs" "int *ip"
249 A filter primitive that translates between C integers
250 and their external representations.
251 This routine returns one if it succeeds, zero otherwise.
257 .Fn xdr_long "XDR *xdrs" "long *lp"
260 A filter primitive that translates between C
262 integers and their external representations.
263 This routine returns one if it succeeds, zero otherwise.
269 .Fn xdrmem_create "XDR *xdrs" "char *addr" "u_int size" "enum xdr_op op"
272 This routine initializes the
274 stream object pointed to by
276 The stream's data is written to, or read from,
277 a chunk of memory at location
279 whose length is no more than
284 determines the direction of the
297 .Fn xdr_opaque "XDR *xdrs" "char *cp" "u_int cnt"
300 A filter primitive that translates between fixed size opaque
302 and its external representation.
305 is the address of the opaque object, and
307 is its size in bytes.
308 This routine returns one if it succeeds, zero otherwise.
314 .Fn xdr_pointer "XDR *xdrs" "char **objpp" "u_int objsize" "xdrproc_t xdrobj"
319 except that it serializes
327 recursive data structures, such as binary trees or
339 .Fa "int \*(lp*readit\*(rp\*(lp\*(rp"
340 .Fa "int \*(lp*writeit\*(rp\*(lp\*(rp"
344 This routine initializes the
346 stream object pointed to by
348 The stream's data is written to a buffer of size
350 a value of zero indicates the system should use a suitable
352 The stream's data is read from a buffer of size
354 it too can be set to a suitable default by passing a zero
356 When a stream's output buffer is full,
359 Similarly, when a stream's input buffer is empty,
362 The behavior of these two routines is similar to
370 is passed to the former routines as the first parameter.
375 field must be set by the caller.
379 stream implements an intermediate record stream.
380 Therefore there are additional bytes in the stream
381 to provide record boundary information.
387 .Fn xdrrec_endofrecord "XDR *xdrs" "int sendnow"
390 This routine can be invoked only on
393 The data in the output buffer is marked as a completed
395 and the output buffer is optionally written out if
398 This routine returns one if it succeeds, zero
405 .Fn xdrrec_eof "XDR *xdrs"
408 This routine can be invoked only on
411 After consuming the rest of the current record in the stream,
412 this routine returns one if the stream has no more input,
419 .Fn xdrrec_skiprecord "XDR *xdrs"
422 This routine can be invoked only on
427 implementation that the rest of the current record
428 in the stream's input buffer should be discarded.
429 This routine returns one if it succeeds, zero otherwise.
435 .Fn xdr_reference "XDR *xdrs" "char **pp" "u_int size" "xdrproc_t proc"
438 A primitive that provides pointer chasing within structures.
441 is the address of the pointer;
451 procedure that filters the structure
452 between its C form and its external representation.
453 This routine returns one if it succeeds, zero otherwise.
455 Warning: this routine does not understand
466 .Fn xdr_setpos "XDR *xdrs" "u_int pos"
469 A macro that invokes the set position routine associated with
476 is a position value obtained from
478 This routine returns one if the
480 stream could be repositioned,
483 Warning: it is difficult to reposition some types of
485 streams, so this routine may fail with one
486 type of stream and succeed with another.
492 .Fn xdr_short "XDR *xdrs" "short *sp"
495 A filter primitive that translates between C
497 integers and their external representations.
498 This routine returns one if it succeeds, zero otherwise.
500 .It Li "#ifdef _STDIO_H_"
501 .It Li "/* XDR using stdio library */"
506 .Fn xdrstdio_create "XDR *xdrs" "FILE *file" "enum xdr_op op"
510 This routine initializes the
512 stream object pointed to by
516 stream data is written to, or read from, the Standard
522 determines the direction of the
530 Warning: the destroy routine associated with such
543 .Fn xdr_string "XDR *xdrs" "char **sp" "u_int maxsize"
546 A filter primitive that translates between C strings and
548 corresponding external representations.
549 Strings cannot be longer than
553 is the address of the string's pointer.
554 This routine returns one if it succeeds, zero otherwise.
560 .Fn xdr_u_char "XDR *xdrs" "unsigned char *ucp"
563 A filter primitive that translates between
565 C characters and their external representations.
566 This routine returns one if it succeeds, zero otherwise.
572 .Fn xdr_u_int "XDR *xdrs" "unsigned *up"
575 A filter primitive that translates between C
577 integers and their external representations.
578 This routine returns one if it succeeds, zero otherwise.
584 .Fn xdr_u_long "XDR *xdrs" "unsigned long *ulp"
587 A filter primitive that translates between C
589 integers and their external representations.
590 This routine returns one if it succeeds, zero otherwise.
596 .Fn xdr_u_short "XDR *xdrs" "unsigned short *usp"
599 A filter primitive that translates between C
601 integers and their external representations.
602 This routine returns one if it succeeds, zero otherwise.
612 .Fa "struct xdr_discrim *choices"
613 .Fa "bool_t \*(lp*defaultarm\*(rp\*(lp\*(rp"
617 A filter primitive that translates between a discriminated C
619 and its corresponding external representation.
621 translates the discriminant of the union located at
623 This discriminant is always an
625 Next the union located at
630 is a pointer to an array of
633 Each structure contains an ordered pair of
634 .Bq Va value , proc .
635 If the union's discriminant is equal to the associated
639 is called to translate the union.
642 structure array is denoted by a routine of value
644 If the discriminant is not found in the
648 procedure is called (if it is not
650 Returns one if it succeeds, zero otherwise.
661 .Fa "xdrproc_t elproc"
665 A filter primitive that translates between fixed-length
667 and their corresponding external representations.
671 is the address of the pointer to the array, while
673 is the element count of the array.
678 each of the array's elements, and
682 filter that translates between
683 the array elements' C form, and their external
685 This routine returns one if it succeeds, zero otherwise.
694 This routine always returns one.
697 routines that require a function parameter,
698 where nothing is to be done.
704 .Fn xdr_wrapstring "XDR *xdrs" "char **sp"
707 A primitive that calls
708 .Fn xdr_string xdrs sp MAXUN.UNSIGNED ;
711 is the maximum value of an unsigned integer.
715 package passes a maximum of two
717 routines as parameters, and
719 one of the most frequently used primitives, requires three.
720 Returns one if it succeeds, zero otherwise.
725 .%T "eXternal Data Representation Standard: Protocol Specification"
728 .%T "eXternal Data Representation: Sun Technical Notes"
731 .%T "XDR: External Data Representation Standard"
733 .%Q "Sun Microsystems, Inc., USC\-ISI"