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