1 .\" @(#)xdr.3n 2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
27 .Nm xdrrec_endofrecord ,
29 .Nm xdrrec_skiprecord ,
40 .Nm xdr_u_longlong_t ,
46 .Nd "library routines for external data representation"
55 for function declarations.
57 These routines allow C programmers to describe
58 arbitrary data structures in a machine-independent fashion.
59 Data for remote procedure calls are transmitted using these
62 .Bl -tag -width indent -compact
73 .Fa "xdrproc_t elproc"
77 A filter primitive that translates between variable-length
79 and their corresponding external representations.
83 is the address of the pointer to the array, while
85 is the address of the element count of the array;
86 this element count cannot exceed
93 each of the array's elements, and
97 filter that translates between
98 the array elements' C form, and their external
100 This routine returns one if it succeeds, zero otherwise.
106 .Fn xdr_bool "XDR *xdrs" "bool_t *bp"
109 A filter primitive that translates between booleans (C
111 and their external representations.
112 When encoding data, this
113 filter produces values of either one or zero.
114 This routine returns one if it succeeds, zero otherwise.
120 .Fn xdr_bytes "XDR *xdrs" "char **sp" "u_int *sizep" "u_int maxsize"
123 A filter primitive that translates between counted byte
124 strings and their external representations.
128 is the address of the string pointer.
130 string is located at address
132 strings cannot be longer than
134 This routine returns one if it succeeds, zero otherwise.
140 .Fn xdr_char "XDR *xdrs" "char *cp"
143 A filter primitive that translates between C characters
144 and their external representations.
145 This routine returns one if it succeeds, zero otherwise.
146 Note: encoded characters are not packed, and occupy 4 bytes
148 For arrays of characters, it is worthwhile to
159 .Fn xdr_destroy "XDR *xdrs"
162 A macro that invokes the destroy routine associated with the
166 Destruction usually involves freeing private data structures
167 associated with the stream.
178 .Fn xdr_double "XDR *xdrs" "double *dp"
181 A filter primitive that translates between C
183 precision numbers and their external representations.
184 This routine returns one if it succeeds, zero otherwise.
190 .Fn xdr_enum "XDR *xdrs" "enum_t *ep"
193 A filter primitive that translates between C
195 (actually integers) and their external representations.
196 This routine returns one if it succeeds, zero otherwise.
202 .Fn xdr_float "XDR *xdrs" "float *fp"
205 A filter primitive that translates between C
207 and their external representations.
208 This routine returns one if it succeeds, zero otherwise.
214 .Fn xdr_free "xdrproc_t proc" "void *objp"
217 Generic freeing routine.
218 The first argument is the
220 routine for the object being freed.
222 is a pointer to the object itself.
223 Note: the pointer passed
226 freed, but what it points to
234 .Fn xdr_getpos "XDR *xdrs"
237 A macro that invokes the get\-position routine
242 The routine returns an unsigned integer,
243 which indicates the position of the
246 A desirable feature of
248 streams is that simple arithmetic works with this number,
251 stream instances need not guarantee this.
257 .Fn xdr_hyper "XDR *xdrs" "quad_t *llp"
259 A filter primitive that translates between ANSI C
261 integers and their external representations.
262 This routine returns one if it succeeds, zero otherwise.
268 .Fn xdr_inline "XDR *xdrs" "int len"
271 A macro that invokes the in-line routine associated with the
275 The routine returns a pointer
276 to a contiguous piece of the stream's buffer;
278 is the byte length of the desired buffer.
279 Note: pointer is cast to
287 if it cannot allocate a contiguous piece of a buffer.
288 Therefore the behavior may vary among stream instances;
289 it exists for the sake of efficiency.
295 .Fn xdr_int "XDR *xdrs" "int *ip"
298 A filter primitive that translates between C integers
299 and their external representations.
300 This routine returns one if it succeeds, zero otherwise.
306 .Fn xdr_long "XDR *xdrs" "long *lp"
309 A filter primitive that translates between C
311 integers and their external representations.
312 This routine returns one if it succeeds, zero otherwise.
318 .Fn xdr_longlong_t "XDR *xdrs" "quad_t *llp"
320 A filter primitive that translates between ANSI C
322 integers and their external representations.
323 This routine returns one if it succeeds, zero otherwise.
329 .Fn xdrmem_create "XDR *xdrs" "char *addr" "u_int size" "enum xdr_op op"
332 This routine initializes the
334 stream object pointed to by
336 The stream's data is written to, or read from,
337 a chunk of memory at location
339 whose length is no more than
345 determines the direction of the
358 .Fn xdr_opaque "XDR *xdrs" "char *cp" "u_int cnt"
361 A filter primitive that translates between fixed size opaque
363 and its external representation.
367 is the address of the opaque object, and
369 is its size in bytes.
370 This routine returns one if it succeeds, zero otherwise.
376 .Fn xdr_pointer "XDR *xdrs" "char **objpp" "u_int objsize" "xdrproc_t xdrobj"
381 except that it serializes
389 recursive data structures, such as binary trees or
401 .Fa "int \*(lp*readit\*(rp\*(lp\*(rp"
402 .Fa "int \*(lp*writeit\*(rp\*(lp\*(rp"
406 This routine initializes the
408 stream object pointed to by
410 The stream's data is written to a buffer of size
412 a value of zero indicates the system should use a suitable
414 The stream's data is read from a buffer of size
416 it too can be set to a suitable default by passing a zero
418 When a stream's output buffer is full,
421 Similarly, when a stream's input buffer is empty,
424 The behavior of these two routines is similar to
432 is passed to the former routines as the first argument.
437 field must be set by the caller.
441 stream implements an intermediate record stream.
442 Therefore there are additional bytes in the stream
443 to provide record boundary information.
449 .Fn xdrrec_endofrecord "XDR *xdrs" "int sendnow"
452 This routine can be invoked only on
455 The data in the output buffer is marked as a completed
457 and the output buffer is optionally written out if
460 This routine returns one if it succeeds, zero
467 .Fn xdrrec_eof "XDR *xdrs"
470 This routine can be invoked only on
473 After consuming the rest of the current record in the stream,
474 this routine returns one if the stream has no more input,
481 .Fn xdrrec_skiprecord "XDR *xdrs"
484 This routine can be invoked only on
489 implementation that the rest of the current record
490 in the stream's input buffer should be discarded.
491 This routine returns one if it succeeds, zero otherwise.
497 .Fn xdr_reference "XDR *xdrs" "char **pp" "u_int size" "xdrproc_t proc"
500 A primitive that provides pointer chasing within structures.
504 is the address of the pointer;
514 procedure that filters the structure
515 between its C form and its external representation.
516 This routine returns one if it succeeds, zero otherwise.
518 Warning: this routine does not understand
529 .Fn xdr_setpos "XDR *xdrs" "u_int pos"
532 A macro that invokes the set position routine associated with
540 is a position value obtained from
542 This routine returns one if the
544 stream could be repositioned,
547 Warning: it is difficult to reposition some types of
549 streams, so this routine may fail with one
550 type of stream and succeed with another.
556 .Fn xdr_short "XDR *xdrs" "short *sp"
559 A filter primitive that translates between C
561 integers and their external representations.
562 This routine returns one if it succeeds, zero otherwise.
568 .Fn xdr_sizeof "xdrproc_t func" "void *data"
571 This routine returns the amount of memory required to encode
576 .It Li "#ifdef _STDIO_H_"
577 .It Li "/* XDR using stdio library */"
582 .Fn xdrstdio_create "XDR *xdrs" "FILE *file" "enum xdr_op op"
586 This routine initializes the
588 stream object pointed to by
592 stream data is written to, or read from, the Standard
599 determines the direction of the
607 Warning: the destroy routine associated with such
620 .Fn xdr_string "XDR *xdrs" "char **sp" "u_int maxsize"
623 A filter primitive that translates between C strings and
625 corresponding external representations.
626 Strings cannot be longer than
630 is the address of the string's pointer.
631 This routine returns one if it succeeds, zero otherwise.
637 .Fn xdr_u_char "XDR *xdrs" "unsigned char *ucp"
640 A filter primitive that translates between
642 C characters and their external representations.
643 This routine returns one if it succeeds, zero otherwise.
649 .Fn xdr_u_hyper "XDR *xdrs" "u_quad_t *ullp"
651 A filter primitive that translates between
655 integers and their external representations.
656 This routine returns one if it succeeds, zero otherwise.
662 .Fn xdr_u_int "XDR *xdrs" "unsigned *up"
665 A filter primitive that translates between C
667 integers and their external representations.
668 This routine returns one if it succeeds, zero otherwise.
674 .Fn xdr_u_long "XDR *xdrs" "unsigned long *ulp"
677 A filter primitive that translates between C
679 integers and their external representations.
680 This routine returns one if it succeeds, zero otherwise.
686 .Fn xdr_u_longlong_t "XDR *xdrs" "u_quad_t *ullp"
688 A filter primitive that translates between
692 integers and their external representations.
693 This routine returns one if it succeeds, zero otherwise.
699 .Fn xdr_u_short "XDR *xdrs" "unsigned short *usp"
702 A filter primitive that translates between C
704 integers and their external representations.
705 This routine returns one if it succeeds, zero otherwise.
715 .Fa "const struct xdr_discrim *choices"
716 .Fa "xdrproc_t defaultarm"
720 A filter primitive that translates between a discriminated C
722 and its corresponding external representation.
724 translates the discriminant of the union located at
726 This discriminant is always an
728 Next the union located at
734 is a pointer to an array of
737 Each structure contains an ordered pair of
738 .Bq Va value , proc .
739 If the union's discriminant is equal to the associated
743 is called to translate the union.
746 structure array is denoted by a routine of value
748 If the discriminant is not found in the
752 procedure is called (if it is not
754 Returns one if it succeeds, zero otherwise.
765 .Fa "xdrproc_t elproc"
769 A filter primitive that translates between fixed-length
771 and their corresponding external representations.
775 is the address of the pointer to the array, while
777 is the element count of the array.
783 each of the array's elements, and
787 filter that translates between
788 the array elements' C form, and their external
790 This routine returns one if it succeeds, zero otherwise.
799 This routine always returns one.
802 routines that require a function argument,
803 where nothing is to be done.
809 .Fn xdr_wrapstring "XDR *xdrs" "char **sp"
812 A primitive that calls
813 .Fn xdr_string xdrs sp MAXUN.UNSIGNED ;
816 is the maximum value of an unsigned integer.
822 package passes a maximum of two
824 routines as arguments, and
826 one of the most frequently used primitives, requires three.
827 Returns one if it succeeds, zero otherwise.
832 .%T "eXternal Data Representation Standard: Protocol Specification"
835 .%T "eXternal Data Representation: Sun Technical Notes"
838 .%T "XDR: External Data Representation Standard"
840 .%Q "Sun Microsystems, Inc., USC\-ISI"
845 function first appeared in