1 .\" @(#)xdr.3n 2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
28 .Nm xdrrec_endofrecord ,
30 .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.
569 .Fn xdr_sizeof "xdrproc_t func" "void *data"
572 This routine returns the amount of memory required to encode
577 .It Li "#ifdef _STDIO_H_"
578 .It Li "/* XDR using stdio library */"
583 .Fn xdrstdio_create "XDR *xdrs" "FILE *file" "enum xdr_op op"
587 This routine initializes the
589 stream object pointed to by
593 stream data is written to, or read from, the Standard
600 determines the direction of the
608 Warning: the destroy routine associated with such
621 .Fn xdr_string "XDR *xdrs" "char **sp" "u_int maxsize"
624 A filter primitive that translates between C strings and
626 corresponding external representations.
627 Strings cannot be longer than
631 is the address of the string's pointer.
632 This routine returns one if it succeeds, zero otherwise.
638 .Fn xdr_u_char "XDR *xdrs" "unsigned char *ucp"
641 A filter primitive that translates between
643 C characters and their external representations.
644 This routine returns one if it succeeds, zero otherwise.
650 .Fn xdr_u_hyper "XDR *xdrs" "u_quad_t *ullp"
652 A filter primitive that translates between
656 integers and their external representations.
657 This routine returns one if it succeeds, zero otherwise.
663 .Fn xdr_u_int "XDR *xdrs" "unsigned *up"
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_long "XDR *xdrs" "unsigned long *ulp"
678 A filter primitive that translates between C
680 integers and their external representations.
681 This routine returns one if it succeeds, zero otherwise.
687 .Fn xdr_u_longlong_t "XDR *xdrs" "u_quad_t *ullp"
689 A filter primitive that translates between
693 integers and their external representations.
694 This routine returns one if it succeeds, zero otherwise.
700 .Fn xdr_u_short "XDR *xdrs" "unsigned short *usp"
703 A filter primitive that translates between C
705 integers and their external representations.
706 This routine returns one if it succeeds, zero otherwise.
716 .Fa "const struct xdr_discrim *choices"
717 .Fa "xdrproc_t defaultarm"
721 A filter primitive that translates between a discriminated C
723 and its corresponding external representation.
725 translates the discriminant of the union located at
727 This discriminant is always an
729 Next the union located at
735 is a pointer to an array of
738 Each structure contains an ordered pair of
739 .Bq Va value , proc .
740 If the union's discriminant is equal to the associated
744 is called to translate the union.
747 structure array is denoted by a routine of value
749 If the discriminant is not found in the
753 procedure is called (if it is not
755 Returns one if it succeeds, zero otherwise.
766 .Fa "xdrproc_t elproc"
770 A filter primitive that translates between fixed-length
772 and their corresponding external representations.
776 is the address of the pointer to the array, while
778 is the element count of the array.
784 each of the array's elements, and
788 filter that translates between
789 the array elements' C form, and their external
791 This routine returns one if it succeeds, zero otherwise.
800 This routine always returns one.
803 routines that require a function argument,
804 where nothing is to be done.
810 .Fn xdr_wrapstring "XDR *xdrs" "char **sp"
813 A primitive that calls
814 .Fn xdr_string xdrs sp MAXUN.UNSIGNED ;
817 is the maximum value of an unsigned integer.
823 package passes a maximum of two
825 routines as arguments, and
827 one of the most frequently used primitives, requires three.
828 Returns one if it succeeds, zero otherwise.
833 .%T "eXternal Data Representation Standard: Protocol Specification"
836 .%T "eXternal Data Representation: Sun Technical Notes"
839 .%T "XDR: External Data Representation Standard"
841 .%Q "Sun Microsystems, Inc., USC\-ISI"
846 function first appeared in