| blob | 99c822d34816003a656e9560426738d75dca69a7 |
1 .\" @(#)xdr.3n 2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
2 .\" $NetBSD: xdr.3,v 1.14 2011/07/08 19:28:22 wiz Exp $
3 .\"
4 .Dd July 4, 2011
5 .Dt XDR 3
6 .Os
7 .Sh NAME
8 .Nm xdr ,
9 .Nm xdr_array ,
10 .Nm xdr_bool ,
11 .Nm xdr_bytes ,
12 .Nm xdr_char ,
13 .Nm xdr_destroy ,
14 .Nm xdr_double ,
15 .Nm xdr_enum ,
16 .Nm xdr_float ,
17 .Nm xdr_free ,
18 .Nm xdr_getpos ,
19 .Nm xdr_hyper ,
20 .Nm xdr_inline ,
21 .Nm xdr_int ,
22 .Nm xdr_long ,
23 .Nm xdr_longlong_t ,
24 .Nm xdrmem_create ,
25 .Nm xdr_opaque ,
26 .Nm xdr_pointer ,
27 .Nm xdrrec_create ,
28 .Nm xdrrec_endofrecord ,
29 .Nm xdrrec_eof ,
30 .Nm xdrrec_skiprecord ,
31 .Nm xdr_reference ,
32 .Nm xdr_setpos ,
33 .Nm xdr_short ,
34 .Nm xdr_sizeof ,
35 .Nm xdrstdio_create ,
36 .Nm xdr_string ,
37 .Nm xdr_u_char ,
38 .Nm xdr_u_hyper ,
39 .Nm xdr_u_long ,
40 .Nm xdr_u_longlong_t ,
41 .Nm xdr_u_short ,
42 .Nm xdr_union ,
43 .Nm xdr_vector ,
44 .Nm xdr_void ,
45 .Nm xdr_wrapstring
46 .Nd library routines for external data representation
47 .Sh SYNOPSIS
48 .Ft int
49 .Fn xdr_array "XDR *xdrs" "char **arrp" "u_int *sizep" "u_int maxsize" \
50 "u_int elsize" "xdrproc_t elproc"
51 .Ft int
52 .Fn xdr_bool "XDR *xdrs" "bool_t *bp"
53 .Ft int
54 .Fn xdr_bytes "XDR *xdrs" "char **sp" "u_int *sizep" "u_int maxsize"
55 .Ft int
56 .Fn xdr_char "XDR *xdrs" "char *cp"
57 .Ft void
58 .Fn xdr_destroy "XDR *xdrs"
59 .Ft int
60 .Fn xdr_double "XDR *xdrs" "double *dp"
61 .Ft int
62 .Fn xdr_enum "XDR *xdrs" "enum_t *ep"
63 .Ft int
64 .Fn xdr_float "XDR *xdrs" "float *fp"
65 .Ft void
66 .Fn xdr_free "xdrproc_t proc" "char *objp"
67 .Ft u_int
68 .Fn xdr_getpos "XDR *xdrs"
69 .Ft int
70 .Fn xdr_hyper "XDR *xdrs" "longlong_t *llp"
71 .Ft long *
72 .Fn xdr_inline "XDR *xdrs" "int len"
73 .Ft int
74 .Fn xdr_int "XDR *xdrs" "int *ip"
75 .Ft int
76 .Fn xdr_long "XDR *xdrs" "long *lp"
77 .Ft int
78 .Fn xdr_longlong_t "XDR *xdrs" "longlong_t *llp"
79 .Ft void
80 .Fn xdrmem_create "XDR *xdrs" "char *addr" "u_int size" \
81 "enum xdr_op op"
82 .Ft int
83 .Fn xdr_opaque "XDR *xdrs" "char *cp" "u_int cnt"
84 .Ft int
85 .Fn xdr_pointer "XDR *xdrs" "char **objpp" "u_int objsize" \
86 "xdrproc_t xdrobj"
87 .Ft void
88 .Fn xdrrec_create "XDR *xdrs" "u_int sendsize" "u_int recvsize" \
89 "char *handle" "int (*readit)()" "int (*writeit)()"
90 .Ft int
91 .Fn xdrrec_endofrecord "XDR *xdrs" "int sendnow"
92 .Ft int
93 .Fn xdrrec_eof "XDR *xdrs"
94 .Ft int
95 .Fn xdrrec_skiprecord "XDR *xdrs"
96 .Ft int
97 .Fn xdr_reference "XDR *xdrs" "char **pp" "u_int size" \
98 "xdrproc_t proc"
99 .Ft int
100 .Fn xdr_setpos "XDR *xdrs" "u_int pos"
101 .Ft int
102 .Fn xdr_short "XDR *xdrs" "short *sp"
103 .Ft nsigned long
104 .Fn xdr_sizeof "xdrproc_t func" "void *data"
105 .Ft void
106 .Fn xdrstdio_create "XDR *xdrs" "FILE *file" "enum xdr_op op"
107 .Ft int
108 .Fn xdr_string "XDR *xdrs" "char **sp" "u_int maxsize"
109 .Ft int
110 .Fn xdr_u_char "XDR *xdrs" "unsigned char *ucp"
111 .Ft int
112 .Fn xdr_u_hyper "XDR *xdrs" "u_longlong_t *ullp"
113 .Ft int
114 .Fn xdr_u_int "XDR *xdrs" "unsigned *up"
115 .Ft int
116 .Fn xdr_u_long "XDR *xdrs" "unsigned long *ulp"
117 .Ft int
118 .Fn xdr_u_longlong_t "XDR *xdrs" "u_longlong_t *ullp"
119 .Ft int
120 .Fn xdr_u_short "XDR *xdrs" "unsigned short *usp"
121 .Ft int
122 .Fn xdr_union "XDR *xdrs" "int *dscmp" "char *unp" \
123 "struct xdr_discrim *choices" "bool_t (*defaultarm)(\|)"
124 .Ft int
125 .Fn xdr_vector "XDR *xdrs" "char *arrp" "u_int size" \
126 "u_int elsize" "xdrproc_t elproc"
127 .Ft int
128 .Fn xdr_void "void"
129 .Ft int
130 .Fn xdr_wrapstring "XDR *xdrs" "char **sp"
131 .Sh DESCRIPTION
132 These routines allow C programmers to describe
133 arbitrary data structures in a machine-independent fashion.
134 Data for remote procedure calls are transmitted using these
135 routines.
136 .Bl -tag -width xxx
137 .It Fn xdr_array
138 A filter primitive that translates between variable-length
139 arrays and their corresponding external representations.
140 The parameter
141 .Fa arrp
142 is the address of the pointer to the array, while
143 .Fa sizep
144 is the address of the element count of the array;
145 this element count cannot exceed
146 .Fa maxsize .
147 The parameter
148 .Fa elsize
149 is the
150 .Em sizeof
151 each of the array's elements, and
152 .Fa elproc
153 is an XDR filter that translates between the array elements' C form,
154 and their external representation.
155 This routine returns one if it succeeds, zero otherwise.
156 .It Fn xdr_bool
157 A filter primitive that translates between booleans (C integers)
158 and their external representations.
159 When encoding data, this filter produces values of either one or
160 zero.
161 This routine returns one if it succeeds, zero otherwise.
162 .It Fn xdr_bytes
163 A filter primitive that translates between counted byte
164 strings and their external representations.
165 The parameter
166 .Fa sp
167 is the address of the string pointer.
168 The length of the string is located at address
169 .Fa sizep ;
170 strings cannot be longer than
171 .Fa maxsize .
172 This routine returns one if it succeeds, zero otherwise.
173 .It Fn xdr_char
174 A filter primitive that translates between C characters
175 and their external representations.
176 This routine returns one if it succeeds, zero otherwise.
177 Note: encoded characters are not packed, and occupy 4 bytes each.
178 For arrays of characters, it is worthwhile to consider
179 .Fn xdr_bytes ,
180 .Fn xdr_opaque
181 or
182 .Fn xdr_string .
183 .It Fn xdr_destroy
184 A macro that invokes the destroy routine associated with the XDR
185 stream,
186 .Fa xdrs .
187 Destruction usually involves freeing private data structures
188 associated with the stream.
189 Using
190 .Fa xdrs
191 after invoking
192 .Fn xdr_destroy
193 is undefined.
194 .It Fn xdr_double
195 A filter primitive that translates between C double precision numbers
196 and their external representations.
197 This routine returns one if it succeeds, zero otherwise.
198 .It Fn xdr_enum
199 A filter primitive that translates between C enums (actually integers)
200 and their external representations.
201 This routine returns one if it succeeds, zero otherwise.
202 .It Fn xdr_float
203 A filter primitive that translates between C floats
204 and their external representations.
205 This routine returns one if it succeeds, zero otherwise.
206 .It Fn xdr_free
207 Generic freeing routine.
208 The first argument is the XDR routine for the object being freed.
209 The second argument is a pointer to the object itself.
210 Note: the pointer passed to this routine is
211 .Em not
212 freed, but what it points to
213 .Em is
214 freed (recursively).
215 .It Fn xdr_getpos
216 A macro that invokes the get-position routine associated with the XDR
217 stream,
218 .Fa xdrs .
219 The routine returns an unsigned integer, which indicates the position
220 of the XDR byte stream.
221 A desirable feature of XDR streams is that simple arithmetic works
222 with this number, although the XDR stream instances need not guarantee
223 this.
224 .It Fn xdr_hyper
225 A filter primitive that translates between ANSI C long long integers
226 and their external representations.
227 This routine returns one if it succeeds, zero otherwise.
228 .It Fn xdr_inline
229 A macro that invokes the in-line routine associated with the XDR
230 stream,
231 .Fa xdrs .
232 The routine returns a pointer
233 to a contiguous piece of the stream's buffer;
234 .Fa len
235 is the byte length of the desired buffer.
236 Note: pointer is cast to
237 .Vt "long *" .
238 .Pp
239 Warning:
240 .Fn xdr_inline
241 may return
242 .Dv NULL
243 if it cannot allocate a contiguous piece of a buffer.
244 Therefore the behavior may vary among stream instances;
245 it exists for the sake of efficiency.
246 .It Fn xdr_int
247 A filter primitive that translates between C integers
248 and their external representations.
249 This routine returns one if it succeeds, zero otherwise.
250 .It Fn xdr_long
251 A filter primitive that translates between C long integers
252 and their external representations.
253 This routine returns one if it succeeds, zero otherwise.
254 .It Fn xdr_longlong_t
255 A filter primitive that translates between ANSI C long long integers
256 and their external representations.
257 This routine returns one if it succeeds, zero otherwise.
258 .It Fn xdrmem_create
259 This routine initializes the XDR stream object pointed to by
260 .Fa xdrs .
261 The stream's data is written to, or read from,
262 a chunk of memory at location
263 .Fa addr
264 whose length is no more than
265 .Fa size
266 bytes long.
267 The
268 .Fa op
269 determines the direction of the XDR stream (either
270 .Dv XDR_ENCODE ,
271 .Dv XDR_DECODE ,
272 or
273 .Dv XDR_FREE ) .
274 .It Fn xdr_opaque
275 A filter primitive that translates between fixed size opaque data
276 and its external representation.
277 The parameter
278 .Fa cp
279 is the address of the opaque object, and
280 .Fa cnt
281 is its size in bytes.
282 This routine returns one if it succeeds, zero otherwise.
283 .It Fn xdr_pointer
284 Like
285 .Fn xdr_reference
286 except that it serializes
287 .Dv NULL
288 pointers, whereas
289 .Fn xdr_reference
290 does not.
291 Thus,
292 .Fn xdr_pointer
293 can represent recursive data structures, such as binary trees or
294 linked lists.
295 .It Fn xdrrec_create
296 This routine initializes the XDR stream object pointed to by
297 .Fa xdrs .
298 The stream's data is written to a buffer of size
299 .Fa sendsize ;
300 a value of zero indicates the system should use a suitable default.
301 The stream's data is read from a buffer of size
302 .Fa recvsize ;
303 it too can be set to a suitable default by passing a zero value.
304 When a stream's output buffer is full,
305 .Fa writeit
306 is called.
307 Similarly, when a stream's input buffer is empty,
308 .Fa readit
309 is called.
310 The behavior of these two routines is similar to the system calls
311 .Xr read 2
312 and
313 .Xr write 2 ,
314 except that
315 .Fa handle
316 is passed to the former routines as the first parameter.
317 Note: the XDR stream's
318 .Fa op
319 field must be set by the caller.
320 .Pp
321 Warning: this XDR stream implements an intermediate record stream.
322 Therefore there are additional bytes in the stream
323 to provide record boundary information.
324 .It Fn xdrrec_endofrecord
325 This routine can be invoked only on streams created by
326 .Fn xdrrec_create .
327 The data in the output buffer is marked as a completed record,
328 and the output buffer is optionally written out if
329 .Fa sendnow
330 is non-zero.
331 This routine returns one if it succeeds, zero otherwise.
332 .It Fn xdrrec_eof
333 This routine can be invoked only on streams created by
334 .Fn xdrrec_create .
335 After consuming the rest of the current record in the stream,
336 this routine returns one if the stream has no more input,
337 zero otherwise.
338 .It Fn xdrrec_skiprecord
339 This routine can be invoked only on streams created by
340 .Fn xdrrec_create .
341 It tells the XDR implementation that the rest of the current record
342 in the stream's input buffer should be discarded.
343 This routine returns one if it succeeds, zero otherwise.
344 .It Fn xdr_reference
345 A primitive that provides pointer chasing within structures.
346 The parameter
347 .Fa pp
348 is the address of the pointer;
349 .Fa size
350 is the
351 .Em sizeof
352 the structure that
353 .Fa *pp
354 points to; and
355 .Fa proc
356 is an XDR procedure that filters the structure
357 between its C form and its external representation.
358 This routine returns one if it succeeds, zero otherwise.
359 .Pp
360 Warning: this routine does not understand
361 .Dv NULL
362 pointers.
363 Use
364 .Fn xdr_pointer
365 instead.
366 .It Fn xdr_setpos
367 A macro that invokes the set position routine associated with the XDR
368 stream
369 .Fa xdrs .
370 The parameter
371 .Fa pos
372 is a position value obtained from
373 .Fn xdr_getpos .
374 This routine returns one if the XDR stream could be repositioned,
375 and zero otherwise.
376 .Pp
377 Warning: it is difficult to reposition some types of XDR streams, so
378 this routine may fail with one type of stream and succeed with
379 another.
380 .It Fn xdr_short
381 A filter primitive that translates between C short integers
382 and their external representations.
383 This routine returns one if it succeeds, zero otherwise.
384 .It Fn xdr_sizeof
385 This routine returns the amount of memory required to encode
386 .Fa data
387 using filter
388 .Fa func .
389 .It Fn xdrstdio_create
390 This routine initializes the XDR stream object pointed to by
391 .Fa xdrs .
392 The XDR stream data is written to, or read from, the Standard I/O
393 stream
394 .Fa file .
395 The parameter
396 .Fa op
397 determines the direction of the XDR stream (either
398 .Dv XDR_ENCODE ,
399 .Dv XDR_DECODE ,
400 or
401 .Dv XDR_FREE ) .
402 .Pp
403 Warning: the destroy routine associated with such XDR streams calls
404 .Xr fflush 3
405 on the file stream, but never
406 .Xr fclose 3 .
407 .It Fn xdr_string
408 A filter primitive that translates between C strings and
409 their corresponding external representations.
410 Strings cannot be longer than
411 .Fa maxsize .
412 Note:
413 .Fa sp
414 is the address of the string's pointer.
415 This routine returns one if it succeeds, zero otherwise.
416 .It Fn xdr_u_char
417 A filter primitive that translates between unsigned C characters
418 and their external representations.
419 This routine returns one if it succeeds, zero otherwise.
420 .It Fn xdr_u_hyper
421 A filter primitive that translates between unsigned ANSI C long long
422 integers and their external representations.
423 This routine returns one if it succeeds, zero otherwise.
424 .It Fn xdr_u_int
425 A filter primitive that translates between C unsigned integers
426 and their external representations.
427 This routine returns one if it succeeds, zero otherwise.
428 .It Fn xdr_u_long
429 A filter primitive that translates between C unsigned long integers
430 and their external representations.
431 This routine returns one if it succeeds, zero otherwise.
432 .It Fn xdr_u_longlong_t
433 A filter primitive that translates between unsigned ANSI C long long
434 integers and their external representations.
435 This routine returns one if it succeeds, zero otherwise.
436 .It Fn xdr_u_short
437 A filter primitive that translates between C unsigned short integers
438 and their external representations.
439 This routine returns one if it succeeds, zero otherwise.
440 .It Fn xdr_union
441 A filter primitive that translates between a discriminated C union
442 and its corresponding external representation.
443 It first translates the discriminant of the union located at
444 .Fa dscmp .
445 This discriminant is always an enum_t.
446 Next the union located at
447 .Fa unp
448 is translated.
449 The parameter
450 .Fa choices
451 is a pointer to an array of
452 .Fn xdr_discrim
453 structures.
454 Each structure contains an ordered pair of
455 .Fa [ value ,
456 .Fa proc ] .
457 If the union's discriminant is equal to the associated
458 .Fa value ,
459 then the
460 .Fa proc
461 is called to translate the union.
462 The end of the
463 .Fn xdr_discrim
464 structure array is denoted by a routine of value
465 .Dv NULL .
466 If the discriminant is not found in the
467 .Fa choices
468 array, then the
469 .Fa defaultarm
470 procedure is called (if it is not
471 .Dv NULL ) .
472 Returns one if it succeeds, zero otherwise.
473 .It Fn xdr_vector
474 A filter primitive that translates between fixed-length
475 arrays and their corresponding external representations.
476 The parameter
477 .Fa arrp
478 is the address of the pointer to the array, while
479 .Fa size
480 is the element count of the array.
481 The parameter
482 .Fa elsize
483 is the
484 .Em sizeof
485 each of the array's elements, and
486 .Fa elproc
487 is an XDR filter that translates between the array elements' C form,
488 and their external representation.
489 This routine returns one if it succeeds, zero otherwise.
490 .It Fn xdr_void
491 This routine always returns one.
492 It may be passed to RPC routines that require a function parameter,
493 where nothing is to be done.
494 .It Fn xdr_wrapstring
495 A primitive that calls
496 .Fn xdr_string "xdrs" "sp" "MAXUN.UNSIGNED" ;
497 where
498 .Dv MAXUN.UNSIGNED
499 is the maximum value of an unsigned integer.
500 .Fn xdr_wrapstring
501 is handy because the RPC package passes a maximum of two XDR
502 routines as parameters, and
503 .Fn xdr_string ,
504 one of the most frequently used primitives, requires three.
505 Returns one if it succeeds, zero otherwise.
506 .El
507 .Sh SEE ALSO
508 .Xr rpc 3
509 .Pp
510 The following manuals:
511 .Rs
512 .%B "eXternal Data Representation Standard: Protocol Specification"
513 .Re
514 .Rs
515 .%B "eXternal Data Representation: Sun Technical Notes"
516 .Re
517 .Rs
518 .%A Sun Microsystems, Inc., USC-ISI
519 .%T "XDR: External Data Representation Standard"
520 .%R "RFC 1014, USC-ISI"
521 .%V 1014
522 .Re