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