1 .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
3 .\" %%%LICENSE_START(BSD_ONELINE_CDROM)
4 .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
7 .\" @(#)xdr.3n 2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
9 .\" 2007-12-30, mtk, Convert function prototypes to modern C syntax
11 .TH XDR 3 2017-09-15 "" "Linux Programmer's Manual"
13 xdr \- library routines for external data representation
14 .SH SYNOPSIS AND DESCRIPTION
15 These routines allow C programmers to describe
16 arbitrary data structures in a machine-independent fashion.
17 Data for remote procedure calls are transmitted using these
20 The prototypes below are declared in
22 and make use of the following types:
26 .BI "typedef int " bool_t ;
28 .BI "typedef bool_t (*" xdrproc_t ")(XDR *, void *,...);"
32 For the declaration of the
38 .BI "bool_t xdr_array(XDR *" xdrs ", char **" arrp ", unsigned int *" sizep ,
39 .BI " unsigned int " maxsize ", unsigned int " elsize ,
40 .BI " xdrproc_t " elproc );
43 A filter primitive that translates between variable-length arrays
44 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
58 is an XDR filter that translates between
59 the array elements' C form, and their external
61 This routine returns one if it succeeds, zero otherwise.
64 .BI "bool_t xdr_bool(XDR *" xdrs ", bool_t *" bp );
67 A filter primitive that translates between booleans (C
69 and their external representations.
70 When encoding data, this
71 filter produces values of either one or zero.
72 This routine returns one if it succeeds, zero otherwise.
75 .BI "bool_t xdr_bytes(XDR *" xdrs ", char **" sp ", unsigned int *" sizep ,
76 .BI " unsigned int " maxsize );
79 A filter primitive that translates between counted byte
80 strings and their external representations.
83 is the address of the string pointer.
85 string is located at address
87 strings cannot be longer than
89 This routine returns one if it succeeds, zero otherwise.
92 .BI "bool_t xdr_char(XDR *" xdrs ", char *" cp );
95 A filter primitive that translates between C characters
96 and their external representations.
97 This routine returns one if it succeeds, zero otherwise.
98 Note: encoded characters are not packed, and occupy 4 bytes each.
99 For arrays of characters, it is worthwhile to
107 .BI "void xdr_destroy(XDR *" xdrs );
110 A macro that invokes the destroy routine associated with the XDR stream,
112 Destruction usually involves freeing private data structures
113 associated with the stream.
121 .BI "bool_t xdr_double(XDR *" xdrs ", double *" dp );
124 A filter primitive that translates between C
126 precision numbers and their external representations.
127 This routine returns one if it succeeds, zero otherwise.
130 .BI "bool_t xdr_enum(XDR *" xdrs ", enum_t *" ep );
133 A filter primitive that translates between C
135 (actually integers) and their external representations.
136 This routine returns one if it succeeds, zero otherwise.
139 .BI "bool_t xdr_float(XDR *" xdrs ", float *" fp );
142 A filter primitive that translates between C
144 and their external representations.
145 This routine returns one if it succeeds, zero otherwise.
148 .BI "void xdr_free(xdrproc_t " proc ", char *" objp );
151 Generic freeing routine.
152 The first argument is the XDR routine for the object being freed.
153 The second argument is a pointer to the object itself.
154 Note: the pointer passed to this routine is
156 freed, but what it points to
161 .BI "unsigned int xdr_getpos(XDR *" xdrs );
164 A macro that invokes the get-position routine
165 associated with the XDR stream,
167 The routine returns an unsigned integer,
168 which indicates the position of the XDR byte stream.
169 A desirable feature of XDR
170 streams is that simple arithmetic works with this number,
171 although the XDR stream instances need not guarantee this.
174 .BI "long *xdr_inline(XDR *" xdrs ", int " len );
177 A macro that invokes the inline routine associated with the XDR stream,
179 The routine returns a pointer
180 to a contiguous piece of the stream's buffer;
182 is the byte length of the desired buffer.
183 Note: pointer is cast to
189 if it cannot allocate a contiguous piece of a buffer.
190 Therefore the behavior may vary among stream instances;
191 it exists for the sake of efficiency.
194 .BI "bool_t xdr_int(XDR *" xdrs ", int *" ip );
197 A filter primitive that translates between C integers
198 and their external representations.
199 This routine returns one if it succeeds, zero otherwise.
202 .BI "bool_t xdr_long(XDR *" xdrs ", long *" lp );
205 A filter primitive that translates between C
207 integers and their external representations.
208 This routine returns one if it succeeds, zero otherwise.
211 .BI "void xdrmem_create(XDR *" xdrs ", char *" addr ", unsigned int " size ,
212 .BI " enum xdr_op " op );
215 This routine initializes the XDR stream object pointed to by
217 The stream's data is written to, or read from,
218 a chunk of memory at location
220 whose length is no more than
225 determines the direction of the XDR stream (either
232 .BI "bool_t xdr_opaque(XDR *" xdrs ", char *" cp ", unsigned int " cnt );
235 A filter primitive that translates between fixed size opaque data
236 and its external representation.
239 is the address of the opaque object, and
241 is its size in bytes.
242 This routine returns one if it succeeds, zero otherwise.
245 .BI "bool_t xdr_pointer(XDR *" xdrs ", char **" objpp ,
246 .BI " unsigned int " objsize ", xdrproc_t " xdrobj );
251 except that it serializes null pointers, whereas
257 recursive data structures, such as binary trees or
261 .BI "void xdrrec_create(XDR *" xdrs ", unsigned int " sendsize ,
262 .BI " unsigned int " recvsize ", char *" handle ,
263 .BI " int (*" readit ")(char *, char *, int),"
264 .BI " int (*" writeit ")(char *, char *, int));"
267 This routine initializes the XDR stream object pointed to by
269 The stream's data is written to a buffer of size
271 a value of zero indicates the system should use a suitable default.
272 The stream's data is read from a buffer of size
274 it too can be set to a suitable default by passing a zero value.
275 When a stream's output buffer is full,
278 Similarly, when a stream's input buffer is empty,
281 The behavior of these two routines is similar to
288 is passed to the former routines as the first argument.
289 Note: the XDR stream's
291 field must be set by the caller.
293 Warning: to read from an XDR stream created by this API,
295 .BR xdrrec_skiprecord ()
296 first before calling any other XDR APIs.
297 This inserts additional bytes in the stream to provide
298 record boundary information.
299 Also, XDR streams created with different
301 APIs are not compatible for the same reason.
304 .BI "bool_t xdrrec_endofrecord(XDR *" xdrs ", int " sendnow );
307 This routine can be invoked only on streams created by
308 .BR xdrrec_create ().
309 The data in the output buffer is marked as a completed record,
310 and the output buffer is optionally written out if
313 This routine returns one if it succeeds, zero otherwise.
316 .BI "bool_t xdrrec_eof(XDR *" xdrs );
319 This routine can be invoked only on streams created by
320 .BR xdrrec_create ().
321 After consuming the rest of the current record in the stream,
322 this routine returns one if the stream has no more input,
326 .BI "bool_t xdrrec_skiprecord(XDR *" xdrs );
329 This routine can be invoked only on
331 .BR xdrrec_create ().
332 It tells the XDR implementation that the rest of the current record
333 in the stream's input buffer should be discarded.
334 This routine returns one if it succeeds, zero otherwise.
337 .BI "bool_t xdr_reference(XDR *" xdrs ", char **" pp ", unsigned int " size ,
338 .BI " xdrproc_t " proc );
341 A primitive that provides pointer chasing within structures.
344 is the address of the pointer;
352 is an XDR procedure that filters the structure
353 between its C form and its external representation.
354 This routine returns one if it succeeds, zero otherwise.
356 Warning: this routine does not understand null pointers.
362 .BI "xdr_setpos(XDR *" xdrs ", unsigned int " pos );
365 A macro that invokes the set position routine associated with
370 is a position value obtained from
372 This routine returns one if the XDR stream could be repositioned,
375 Warning: it is difficult to reposition some types of XDR
376 streams, so this routine may fail with one
377 type of stream and succeed with another.
380 .BI "bool_t xdr_short(XDR *" xdrs ", short *" sp );
383 A filter primitive that translates between C
385 integers and their external representations.
386 This routine returns one if it succeeds, zero otherwise.
389 .BI "void xdrstdio_create(XDR *" xdrs ", FILE *" file ", enum xdr_op " op );
392 This routine initializes the XDR stream object pointed to by
394 The XDR stream data is written to, or read from, the
400 determines the direction of the XDR stream (either
406 Warning: the destroy routine associated with such XDR streams calls
414 .BI "bool_t xdr_string(XDR *" xdrs ", char **" sp ", unsigned int " maxsize );
417 A filter primitive that translates between C strings and
418 their corresponding external representations.
419 Strings cannot be longer than
423 is the address of the string's pointer.
424 This routine returns one if it succeeds, zero otherwise.
427 .BI "bool_t xdr_u_char(XDR *" xdrs ", unsigned char *" ucp );
430 A filter primitive that translates between
432 C characters and their external representations.
433 This routine returns one if it succeeds, zero otherwise.
436 .BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned int *" up );
439 A filter primitive that translates between C
441 integers and their external representations.
442 This routine returns one if it succeeds, zero otherwise.
445 .BI "bool_t xdr_u_long(XDR *" xdrs ", unsigned long *" ulp );
448 A filter primitive that translates between C
450 integers and their external representations.
451 This routine returns one if it succeeds, zero otherwise.
454 .BI "bool_t xdr_u_short(XDR *" xdrs ", unsigned short *" usp );
457 A filter primitive that translates between C
459 integers and their external representations.
460 This routine returns one if it succeeds, zero otherwise.
463 .BI "bool_t xdr_union(XDR *" xdrs ", int *" dscmp ", char *" unp ,
464 .BI " struct xdr_discrim *" choices ,
465 .BI " xdrproc_t " defaultarm "); /* may equal NULL */"
468 A filter primitive that translates between a discriminated C
470 and its corresponding external representation.
472 translates the discriminant of the union located at
474 This discriminant is always an
476 Next the union located at
481 is a pointer to an array of
484 Each structure contains an ordered pair of
485 .RI [ value , proc ].
486 If the union's discriminant is equal to the associated
490 is called to translate the union.
493 structure array is denoted by a routine of value NULL.
494 If the discriminant is not found in the
498 procedure is called (if it is not NULL).
499 Returns one if it succeeds, zero otherwise.
502 .BI "bool_t xdr_vector(XDR *" xdrs ", char *" arrp ", unsigned int " size ,
503 .BI " unsigned int " elsize ", xdrproc_t " elproc );
506 A filter primitive that translates between fixed-length arrays
507 and their corresponding external representations.
510 is the address of the pointer to the array, while
512 is the element count of the array.
517 each of the array's elements, and
519 is an XDR filter that translates between
520 the array elements' C form, and their external
522 This routine returns one if it succeeds, zero otherwise.
525 .BI "bool_t xdr_void(void);"
528 This routine always returns one.
529 It may be passed to RPC routines that require a function argument,
530 where nothing is to be done.
533 .BI "bool_t xdr_wrapstring(XDR *" xdrs ", char **" sp );
536 A primitive that calls
537 .B "xdr_string(xdrs, sp,MAXUN.UNSIGNED );"
540 is the maximum value of an unsigned integer.
541 .BR xdr_wrapstring ()
542 is handy because the RPC package passes a maximum of two XDR
543 routines as arguments, and
545 one of the most frequently used primitives, requires three.
546 Returns one if it succeeds, zero otherwise.
548 For an explanation of the terms used in this section, see
556 Interface Attribute Value
571 .BR xdrmem_create (),
574 .BR xdrrec_create (),
576 .BR xdrrec_endofrecord (),
577 .BR xdrrec_skiprecord (),
578 .BR xdr_reference (),
581 .BR xdrstdio_create (),
590 .BR xdr_wrapstring ()
591 T} Thread safety MT-Safe
599 The following manuals:
601 eXternal Data Representation Standard: Protocol Specification
603 eXternal Data Representation: Sun Technical Notes
605 .IR "XDR: External Data Representation Standard" ,
606 RFC\ 1014, Sun Microsystems, Inc.,