1XDR(3) Library Functions Manual XDR(3)
2
6 xdr - library routines for external data representation
7
9 These routines allow C programmers to describe arbitrary data struc‐
10 tures in a machine-independent fashion. Data for remote procedure
11 calls are transmitted using these routines.
12 xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)
14 XDR *xdrs;
15 char **arrp;
16 u_int *sizep, maxsize, elsize;
17 xdrproc_t elproc;
18 A filter primitive that translates between variable-length
20 arrays and their corresponding external representations. The
21 parameter arrp is the address of the pointer to the array, while
22 sizep is the address of the element count of the array; this
23 element count cannot exceed maxsize. The parameter elsize is
24 the sizeof each of the array's elements, and elproc is an XDR
25 filter that translates between the array elements' C form, and
26 their external representation. This routine returns one if it
27 succeeds, zero otherwise.
28 xdr_bool(xdrs, bp)
30 XDR *xdrs;
31 bool_t *bp;
32 A filter primitive that translates between booleans (C integers)
34 and their external representations. When encoding data, this
35 filter produces values of either one or zero. This routine
36 returns one if it succeeds, zero otherwise.
37 xdr_bytes(xdrs, sp, sizep, maxsize)
39 XDR *xdrs;
40 char **sp;
41 u_int *sizep, maxsize;
42 A filter primitive that translates between counted byte strings
44 and their external representations. The parameter sp is the
45 address of the string pointer. The length of the string is
46 located at address sizep; strings cannot be longer than maxsize.
47 This routine returns one if it succeeds, zero otherwise.
48 xdr_char(xdrs, cp)
50 XDR *xdrs;
51 char *cp;
52 A filter primitive that translates between C characters and
54 their external representations. This routine returns one if it
55 succeeds, zero otherwise. Note: encoded characters are not
56 packed, and occupy 4 bytes each. For arrays of characters, it is
57 worthwhile to consider xdr_bytes(), xdr_opaque() or
58 xdr_string().
59 void
61 xdr_destroy(xdrs)
62 XDR *xdrs;
63 A macro that invokes the destroy routine associated with the XDR
65 stream, xdrs. Destruction usually involves freeing private data
66 structures associated with the stream. Using xdrs after invok‐
67 ing xdr_destroy() is undefined.
68 xdr_double(xdrs, dp)
70 XDR *xdrs;
71 double *dp;
72 A filter primitive that translates between C double precision
74 numbers and their external representations. This routine
75 returns one if it succeeds, zero otherwise.
76 xdr_enum(xdrs, ep)
78 XDR *xdrs;
79 enum_t *ep;
80 A filter primitive that translates between C enums (actually
82 integers) and their external representations. This routine
83 returns one if it succeeds, zero otherwise.
84 xdr_float(xdrs, fp)
86 XDR *xdrs;
87 float *fp;
88 A filter primitive that translates between C floats and their
90 external representations. This routine returns one if it suc‐
91 ceeds, zero otherwise.
92 void
94 xdr_free(proc, objp)
95 xdrproc_t proc;
96 char *objp;
97 Generic freeing routine. The first argument is the XDR routine
99 for the object being freed. The second argument is a pointer to
100 the object itself. Note: the pointer passed to this routine is
101 not freed, but what it points to is freed (recursively).
102 u_int
104 xdr_getpos(xdrs)
105 XDR *xdrs;
106 A macro that invokes the get-position routine associated with
108 the XDR stream, xdrs. The routine returns an unsigned integer,
109 which indicates the position of the XDR byte stream. A desir‐
110 able feature of XDR streams is that simple arithmetic works with
111 this number, although the XDR stream instances need not guaran‐
112 tee this.
113 long *
115 xdr_inline(xdrs, len)
116 XDR *xdrs;
117 int len;
118 A macro that invokes the in-line routine associated with the XDR
120 stream, xdrs. The routine returns a pointer to a contiguous
121 piece of the stream's buffer; len is the byte length of the
122 desired buffer. Note: pointer is cast to long *.
123 Warning: xdr_inline() may return NULL (0) if it cannot allocate
125 a contiguous piece of a buffer. Therefore the behavior may vary
126 among stream instances; it exists for the sake of efficiency.
127 xdr_int(xdrs, ip)
129 XDR *xdrs;
130 int *ip;
131 A filter primitive that translates between C integers and their
133 external representations. This routine returns one if it suc‐
134 ceeds, zero otherwise.
135 xdr_long(xdrs, lp)
137 XDR *xdrs;
138 long *lp;
139 A filter primitive that translates between C long integers and
141 their external representations. This routine returns one if it
142 succeeds, zero otherwise.
143 void
145 xdrmem_create(xdrs, addr, size, op)
146 XDR *xdrs;
147 char *addr;
148 u_int size;
149 enum xdr_op op;
150 This routine initializes the XDR stream object pointed to by
152 xdrs. The stream's data is written to, or read from, a chunk of
153 memory at location addr whose length is no more than size bytes
154 long. The op determines the direction of the XDR stream (either
155 XDR_ENCODE, XDR_DECODE, or XDR_FREE).
156 xdr_opaque(xdrs, cp, cnt)
158 XDR *xdrs;
159 char *cp;
160 u_int cnt;
161 A filter primitive that translates between fixed size opaque
163 data and its external representation. The parameter cp is the
164 address of the opaque object, and cnt is its size in bytes.
165 This routine returns one if it succeeds, zero otherwise.
166 xdr_pointer(xdrs, objpp, objsize, xdrobj)
168 XDR *xdrs;
169 char **objpp;
170 u_int objsize;
171 xdrproc_t xdrobj;
172 Like xdr_reference() except that it serializes NULL pointers,
174 whereas xdr_reference() does not. Thus, xdr_pointer() can rep‐
175 resent recursive data structures, such as binary trees or linked
176 lists.
177 void
179 xdrrec_create(xdrs, sendsize, recvsize, handle, readit, writeit)
180 XDR *xdrs;
181 u_int sendsize, recvsize;
182 char *handle;
183 int (*readit) (), (*writeit) ();
184 This routine initializes the XDR stream object pointed to by
186 xdrs. The stream's data is written to a buffer of size send‐
187 size; a value of zero indicates the system should use a suitable
188 default. The stream's data is read from a buffer of size recv‐
189 size; it too can be set to a suitable default by passing a zero
190 value. When a stream's output buffer is full, writeit is
191 called. Similarly, when a stream's input buffer is empty, rea‐
192 dit is called. The behavior of these two routines is similar to
193 the system calls read() and write(), except that handle is
194 passed to the former routines as the first parameter. Note: the
195 XDR stream's op field must be set by the caller.
196 Warning: this XDR stream implements an intermediate record
198 stream. Therefore there are additional bytes in the stream to
199 provide record boundary information.
200 xdrrec_endofrecord(xdrs, sendnow)
202 XDR *xdrs;
203 int sendnow;
204 This routine can be invoked only on streams created by xdr‐
206 rec_create(). The data in the output buffer is marked as a com‐
207 pleted record, and the output buffer is optionally written out
208 if sendnow is non-zero. This routine returns one if it succeeds,
209 zero otherwise.
210 xdrrec_eof(xdrs)
212 XDR *xdrs;
213 int empty;
214 This routine can be invoked only on streams created by xdr‐
216 rec_create(). After consuming the rest of the current record in
217 the stream, this routine returns one if the stream has no more
218 input, zero otherwise.
219 xdrrec_skiprecord(xdrs)
221 XDR *xdrs;
222 This routine can be invoked only on streams created by xdr‐
224 rec_create(). It tells the XDR implementation that the rest of
225 the current record in the stream's input buffer should be dis‐
226 carded. This routine returns one if it succeeds, zero other‐
227 wise.
228 xdr_reference(xdrs, pp, size, proc)
230 XDR *xdrs;
231 char **pp;
232 u_int size;
233 xdrproc_t proc;
234 A primitive that provides pointer chasing within structures.
236 The parameter pp is the address of the pointer; size is the
237 sizeof the structure that *pp points to; and proc is an XDR pro‐
238 cedure that filters the structure between its C form and its
239 external representation. This routine returns one if it suc‐
240 ceeds, zero otherwise.
241 Warning: this routine does not understand NULL pointers. Use
243 xdr_pointer() instead.
244 xdr_setpos(xdrs, pos)
246 XDR *xdrs;
247 u_int pos;
248 A macro that invokes the set position routine associated with
250 the XDR stream xdrs. The parameter pos is a position value
251 obtained from xdr_getpos(). This routine returns one if the XDR
252 stream could be repositioned, and zero otherwise.
253 Warning: it is difficult to reposition some types of XDR
255 streams, so this routine may fail with one type of stream and
256 succeed with another.
257 xdr_short(xdrs, sp)
259 XDR *xdrs;
260 short *sp;
261 A filter primitive that translates between C short integers and
263 their external representations. This routine returns one if it
264 succeeds, zero otherwise.
265 void
267 xdrstdio_create(xdrs, file, op)
268 XDR *xdrs;
269 FILE *file;
270 enum xdr_op op;
271 This routine initializes the XDR stream object pointed to by
273 xdrs. The XDR stream data is written to, or read from, the
274 Standard I/O stream file. The parameter op determines the
275 direction of the XDR stream (either XDR_ENCODE, XDR_DECODE, or
276 XDR_FREE).
277 Warning: the destroy routine associated with such XDR streams
279 calls fflush() on the file stream, but never fclose().
280 xdr_string(xdrs, sp, maxsize)
282 XDR
283 *xdrs;
284 char **sp;
285 u_int maxsize;
286 A filter primitive that translates between C strings and their
288 corresponding external representations. Strings cannot be
289 longer than maxsize. Note: sp is the address of the string's
290 pointer. This routine returns one if it succeeds, zero other‐
291 wise.
292 xdr_u_char(xdrs, ucp)
294 XDR *xdrs;
295 unsigned char *ucp;
296 A filter primitive that translates between unsigned C characters
298 and their external representations. This routine returns one if
299 it succeeds, zero otherwise.
300 xdr_u_int(xdrs, up)
302 XDR *xdrs;
303 unsigned *up;
304 A filter primitive that translates between C unsigned integers
306 and their external representations. This routine returns one if
307 it succeeds, zero otherwise.
308 xdr_u_long(xdrs, ulp)
310 XDR *xdrs;
311 unsigned long *ulp;
312 A filter primitive that translates between C unsigned long inte‐
314 gers and their external representations. This routine returns
315 one if it succeeds, zero otherwise.
316 xdr_u_short(xdrs, usp)
318 XDR *xdrs;
319 unsigned short *usp;
320 A filter primitive that translates between C unsigned short
322 integers and their external representations. This routine
323 returns one if it succeeds, zero otherwise.
324 xdr_union(xdrs, dscmp, unp, choices, dfault)
326 XDR *xdrs;
327 int *dscmp;
328 char *unp;
329 struct xdr_discrim *choices;
330 bool_t (*defaultarm) (); /* may equal NULL */
331 A filter primitive that translates between a discriminated C
333 union and its corresponding external representation. It first
334 translates the discriminant of the union located at dscmp. This
335 discriminant is always an enum_t. Next the union located at unp
336 is translated. The parameter choices is a pointer to an array
337 of xdr_discrim() structures. Each structure contains an ordered
338 pair of [value,proc]. If the union's discriminant is equal to
339 the associated value, then the proc is called to translate the
340 union. The end of the xdr_discrim() structure array is denoted
341 by a routine of value NULL. If the discriminant is not found in
342 the choices array, then the defaultarm procedure is called (if
343 it is not NULL). Returns one if it succeeds, zero otherwise.
344 xdr_vector(xdrs, arrp, size, elsize, elproc)
346 XDR *xdrs;
347 char *arrp;
348 u_int size, elsize;
349 xdrproc_t elproc;
350 A filter primitive that translates between fixed-length arrays
352 and their corresponding external representations. The parameter
353 arrp is the address of the pointer to the array, while size is
354 is the element count of the array. The parameter elsize is the
355 sizeof each of the array's elements, and elproc is an XDR filter
356 that translates between the array elements' C form, and their
357 external representation. This routine returns one if it suc‐
358 ceeds, zero otherwise.
359 xdr_void()
361 This routine always returns one. It may be passed to RPC rou‐
363 tines that require a function parameter, where nothing is to be
364 done.
365 xdr_wrapstring(xdrs, sp)
367 XDR *xdrs;
368 char **sp;
369 A primitive that calls xdr_string(xdrs, sp,MAXUN.UNSIGNED );
371 where MAXUN.UNSIGNED is the maximum value of an unsigned inte‐
372 ger. xdr_wrapstring() is handy because the RPC package passes a
373 maximum of two XDR routines as parameters, and xdr_string(), one
374 of the most frequently used primitives, requires three. Returns
375 one if it succeeds, zero otherwise.
376
378 rpc(3)
379 The following manuals:
381 eXternal Data Representation Standard: Protocol Specification
382 eXternal Data Representation: Sun Technical Notes
383 XDR: External Data Representation Standard, RFC 1014, Sun
384 Microsystems, Inc., USC-ISI.
385 1988-02-16 XDR(3)