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 $
30 .Nm xdrrec_endofrecord ,
32 .Nm xdrrec_skiprecord ,
42 .Nm xdr_u_longlong_t ,
49 .Nd "library routines for external data representation"
58 for function declarations.
60 These routines allow C programmers to describe
61 arbitrary data structures in a machine-independent fashion.
62 Data for remote procedure calls are transmitted using these
65 .Bl -tag -width indent -compact
76 .Fa "xdrproc_t elproc"
80 A filter primitive that translates between variable-length
82 and their corresponding external representations.
86 is the address of the pointer to the array, while
88 is the address of the element count of the array;
89 this element count cannot exceed
96 each of the array's elements, and
100 filter that translates between
101 the array elements' C form, and their external
103 This routine returns one if it succeeds, zero otherwise.
109 .Fn xdr_bool "XDR *xdrs" "bool_t *bp"
112 A filter primitive that translates between booleans (C
114 and their external representations.
115 When encoding data, this
116 filter produces values of either one or zero.
117 This routine returns one if it succeeds, zero otherwise.
123 .Fn xdr_bytes "XDR *xdrs" "char **sp" "u_int *sizep" "u_int maxsize"
126 A filter primitive that translates between counted byte
127 strings and their external representations.
131 is the address of the string pointer.
133 string is located at address
135 strings cannot be longer than
137 This routine returns one if it succeeds, zero otherwise.
143 .Fn xdr_char "XDR *xdrs" "char *cp"
146 A filter primitive that translates between C characters
147 and their external representations.
148 This routine returns one if it succeeds, zero otherwise.
149 Note: encoded characters are not packed, and occupy 4 bytes
151 For arrays of characters, it is worthwhile to
162 .Fn xdr_destroy "XDR *xdrs"
165 A macro that invokes the destroy routine associated with the
169 Destruction usually involves freeing private data structures
170 associated with the stream.
181 .Fn xdr_double "XDR *xdrs" "double *dp"
184 A filter primitive that translates between C
186 precision numbers and their external representations.
187 This routine returns one if it succeeds, zero otherwise.
193 .Fn xdr_enum "XDR *xdrs" "enum_t *ep"
196 A filter primitive that translates between C
198 (actually integers) and their external representations.
199 This routine returns one if it succeeds, zero otherwise.
205 .Fn xdr_float "XDR *xdrs" "float *fp"
208 A filter primitive that translates between C
210 and their external representations.
211 This routine returns one if it succeeds, zero otherwise.
217 .Fn xdr_free "xdrproc_t proc" "void *objp"
220 Generic freeing routine.
221 The first argument is the
223 routine for the object being freed.
225 is a pointer to the object itself.
226 Note: the pointer passed
229 freed, but what it points to
237 .Fn xdr_getpos "XDR *xdrs"
240 A macro that invokes the get\-position routine
245 The routine returns an unsigned integer,
246 which indicates the position of the
249 A desirable feature of
251 streams is that simple arithmetic works with this number,
254 stream instances need not guarantee this.
260 .Fn xdr_hyper "XDR *xdrs" "quad_t *llp"
262 A filter primitive that translates between ANSI C
264 integers and their external representations.
265 This routine returns one if it succeeds, zero otherwise.
271 .Fn xdr_inline "XDR *xdrs" "int len"
274 A macro that invokes the in-line routine associated with the
278 The routine returns a pointer
279 to a contiguous piece of the stream's buffer;
281 is the byte length of the desired buffer.
282 Note: pointer is cast to
290 if it cannot allocate a contiguous piece of a buffer.
291 Therefore the behavior may vary among stream instances;
292 it exists for the sake of efficiency.
298 .Fn xdr_int "XDR *xdrs" "int *ip"
301 A filter primitive that translates between C integers
302 and their external representations.
303 This routine returns one if it succeeds, zero otherwise.
309 .Fn xdr_long "XDR *xdrs" "long *lp"
312 A filter primitive that translates between C
314 integers and their external representations.
315 This routine returns one if it succeeds, zero otherwise.
321 .Fn xdr_longlong_t "XDR *xdrs" "quad_t *llp"
323 A filter primitive that translates between ANSI C
325 integers and their external representations.
326 This routine returns one if it succeeds, zero otherwise.
332 .Fn xdr_int64_t "XDR *xdrs" "int64_t *llp"
334 A filter primitive that translates between ANSI C
336 integers and their external representations.
337 This routine returns one if it succeeds, zero otherwise.
343 .Fn xdrmem_create "XDR *xdrs" "char *addr" "u_int size" "enum xdr_op op"
346 This routine initializes the
348 stream object pointed to by
350 The stream's data is written to, or read from,
351 a chunk of memory at location
353 whose length is no more than
359 determines the direction of the
372 .Fn xdr_opaque "XDR *xdrs" "char *cp" "u_int cnt"
375 A filter primitive that translates between fixed size opaque
377 and its external representation.
381 is the address of the opaque object, and
383 is its size in bytes.
384 This routine returns one if it succeeds, zero otherwise.
390 .Fn xdr_pointer "XDR *xdrs" "char **objpp" "u_int objsize" "xdrproc_t xdrobj"
395 except that it serializes
403 recursive data structures, such as binary trees or
415 .Fa "int \*(lp*readit\*(rp\*(lp\*(rp"
416 .Fa "int \*(lp*writeit\*(rp\*(lp\*(rp"
420 This routine initializes the
422 stream object pointed to by
424 The stream's data is written to a buffer of size
426 a value of zero indicates the system should use a suitable
428 The stream's data is read from a buffer of size
430 it too can be set to a suitable default by passing a zero
432 When a stream's output buffer is full,
435 Similarly, when a stream's input buffer is empty,
438 The behavior of these two routines is similar to
446 is passed to the former routines as the first argument.
451 field must be set by the caller.
455 stream implements an intermediate record stream.
456 Therefore there are additional bytes in the stream
457 to provide record boundary information.
463 .Fn xdrrec_endofrecord "XDR *xdrs" "int sendnow"
466 This routine can be invoked only on
469 The data in the output buffer is marked as a completed
471 and the output buffer is optionally written out if
474 This routine returns one if it succeeds, zero
481 .Fn xdrrec_eof "XDR *xdrs"
484 This routine can be invoked only on
487 After consuming the rest of the current record in the stream,
488 this routine returns one if the stream has no more input,
495 .Fn xdrrec_skiprecord "XDR *xdrs"
498 This routine can be invoked only on
503 implementation that the rest of the current record
504 in the stream's input buffer should be discarded.
505 This routine returns one if it succeeds, zero otherwise.
511 .Fn xdr_reference "XDR *xdrs" "char **pp" "u_int size" "xdrproc_t proc"
514 A primitive that provides pointer chasing within structures.
518 is the address of the pointer;
528 procedure that filters the structure
529 between its C form and its external representation.
530 This routine returns one if it succeeds, zero otherwise.
532 Warning: this routine does not understand
543 .Fn xdr_setpos "XDR *xdrs" "u_int pos"
546 A macro that invokes the set position routine associated with
554 is a position value obtained from
556 This routine returns one if the
558 stream could be repositioned,
561 Warning: it is difficult to reposition some types of
563 streams, so this routine may fail with one
564 type of stream and succeed with another.
570 .Fn xdr_short "XDR *xdrs" "short *sp"
573 A filter primitive that translates between C
575 integers and their external representations.
576 This routine returns one if it succeeds, zero otherwise.
578 .It Li "#ifdef _STDIO_H_"
579 .It Li "/* XDR using stdio library */"
584 .Fn xdrstdio_create "XDR *xdrs" "FILE *file" "enum xdr_op op"
588 This routine initializes the
590 stream object pointed to by
594 stream data is written to, or read from, the Standard
601 determines the direction of the
609 Warning: the destroy routine associated with such
622 .Fn xdr_string "XDR *xdrs" "char **sp" "u_int maxsize"
625 A filter primitive that translates between C strings and
627 corresponding external representations.
628 Strings cannot be longer than
632 is the address of the string's pointer.
633 This routine returns one if it succeeds, zero otherwise.
639 .Fn xdr_u_char "XDR *xdrs" "unsigned char *ucp"
642 A filter primitive that translates between
644 C characters and their external representations.
645 This routine returns one if it succeeds, zero otherwise.
651 .Fn xdr_u_hyper "XDR *xdrs" "u_quad_t *ullp"
653 A filter primitive that translates between
657 integers and their external representations.
658 This routine returns one if it succeeds, zero otherwise.
664 .Fn xdr_u_int "XDR *xdrs" "unsigned *up"
667 A filter primitive that translates between C
669 integers and their external representations.
670 This routine returns one if it succeeds, zero otherwise.
676 .Fn xdr_u_long "XDR *xdrs" "unsigned long *ulp"
679 A filter primitive that translates between C
681 integers and their external representations.
682 This routine returns one if it succeeds, zero otherwise.
688 .Fn xdr_u_longlong_t "XDR *xdrs" "u_quad_t *ullp"
690 A filter primitive that translates between
694 integers and their external representations.
695 This routine returns one if it succeeds, zero otherwise.
701 .Fn xdr_u_int64_t "XDR *xdrs" "u_int64_t *llp"
703 A filter primitive that translates between C
705 integers and their external representations.
706 This routine returns one if it succeeds, zero otherwise.
712 .Fn xdr_u_short "XDR *xdrs" "unsigned short *usp"
715 A filter primitive that translates between C
717 integers and their external representations.
718 This routine returns one if it succeeds, zero otherwise.
728 .Fa "const struct xdr_discrim *choices"
729 .Fa "xdrproc_t defaultarm"
733 A filter primitive that translates between a discriminated C
735 and its corresponding external representation.
737 translates the discriminant of the union located at
739 This discriminant is always an
741 Next the union located at
747 is a pointer to an array of
750 Each structure contains an ordered pair of
751 .Bq Va value , proc .
752 If the union's discriminant is equal to the associated
756 is called to translate the union.
759 structure array is denoted by a routine of value
761 If the discriminant is not found in the
765 procedure is called (if it is not
767 Returns one if it succeeds, zero otherwise.
778 .Fa "xdrproc_t elproc"
782 A filter primitive that translates between fixed-length
784 and their corresponding external representations.
788 is the address of the pointer to the array, while
790 is the element count of the array.
796 each of the array's elements, and
800 filter that translates between
801 the array elements' C form, and their external
803 This routine returns one if it succeeds, zero otherwise.
812 This routine always returns one.
815 routines that require a function argument,
816 where nothing is to be done.
822 .Fn xdr_wrapstring "XDR *xdrs" "char **sp"
825 A primitive that calls
826 .Fn xdr_string xdrs sp MAXUN.UNSIGNED ;
829 is the maximum value of an unsigned integer.
835 package passes a maximum of two
837 routines as arguments, and
839 one of the most frequently used primitives, requires three.
840 Returns one if it succeeds, zero otherwise.
845 .%T "eXternal Data Representation Standard: Protocol Specification"
848 .%T "eXternal Data Representation: Sun Technical Notes"
851 .%T "XDR: External Data Representation Standard"
853 .%Q "Sun Microsystems, Inc., USC\-ISI"