man3/xdr.3

   1 '\" t
   2 .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
   3 .\"
   4 .\" %%%LICENSE_START(BSD_ONELINE_CDROM)
   5 .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
   6 .\" %%%LICENSE_END
   7 .\"
   8 .\" @(#)xdr.3n  2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
   9 .\"
  10 .\" 2007-12-30, mtk, Convert function prototypes to modern C syntax
  11 .\"
  12 .TH xdr 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 xdr \- library routines for external data representation
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS AND DESCRIPTION
  19 These routines allow C programmers to describe
  20 arbitrary data structures in a machine-independent fashion.
  21 Data for remote procedure calls are transmitted using these
  22 routines.
  23 .P
  24 The prototypes below are declared in
  25 .I <rpc/xdr.h>
  26 and make use of the following types:
  27 .P
  28 .RS 4
  29 .EX
  30 .BI "typedef int " bool_t ;
  31 .P
  32 .BI "typedef bool_t (*" xdrproc_t ")(XDR *, void *,...);"
  33 .EE
  34 .RE
  35 .P
  36 For the declaration of the
  37 .I XDR
  38 type, see
  39 .IR <rpc/xdr.h> .
  40 .P
  41 .nf
  42 .BI "bool_t xdr_array(XDR *" xdrs ", char **" arrp ", unsigned int *" sizep ,
  43 .BI "                 unsigned int " maxsize ", unsigned int " elsize ,
  44 .BI "                 xdrproc_t " elproc );
  45 .fi
  46 .IP
  47 A filter primitive that translates between variable-length arrays
  48 and their corresponding external representations.
  49 The argument
  50 .I arrp
  51 is the address of the pointer to the array, while
  52 .I sizep
  53 is the address of the element count of the array;
  54 this element count cannot exceed
  55 .IR maxsize .
  56 The argument
  57 .I elsize
  58 is the
  59 .I sizeof
  60 each of the array's elements, and
  61 .I elproc
  62 is an XDR filter that translates between
  63 the array elements' C form, and their external
  64 representation.
  65 This routine returns one if it succeeds, zero otherwise.
  66 .P
  67 .nf
  68 .BI "bool_t xdr_bool(XDR *" xdrs ", bool_t *" bp );
  69 .fi
  70 .IP
  71 A filter primitive that translates between booleans (C
  72 integers)
  73 and their external representations.
  74 When encoding data, this
  75 filter produces values of either one or zero.
  76 This routine returns one if it succeeds, zero otherwise.
  77 .P
  78 .nf
  79 .BI "bool_t xdr_bytes(XDR *" xdrs ", char **" sp ", unsigned int *" sizep ,
  80 .BI "                 unsigned int " maxsize );
  81 .fi
  82 .IP
  83 A filter primitive that translates between counted byte
  84 strings and their external representations.
  85 The argument
  86 .I sp
  87 is the address of the string pointer.
  88 The length of the
  89 string is located at address
  90 .IR sizep ;
  91 strings cannot be longer than
  92 .IR maxsize .
  93 This routine returns one if it succeeds, zero otherwise.
  94 .P
  95 .nf
  96 .BI "bool_t xdr_char(XDR *" xdrs ", char *" cp );
  97 .fi
  98 .IP
  99 A filter primitive that translates between C characters
 100 and their external representations.
 101 This routine returns one if it succeeds, zero otherwise.
 102 Note: encoded characters are not packed, and occupy 4 bytes each.
 103 For arrays of characters, it is worthwhile to
 104 consider
 105 .BR xdr_bytes (),
 106 .BR xdr_opaque (),
 107 or
 108 .BR xdr_string ().
 109 .P
 110 .nf
 111 .BI "void xdr_destroy(XDR *" xdrs );
 112 .fi
 113 .IP
 114 A macro that invokes the destroy routine associated with the XDR stream,
 115 .IR xdrs .
 116 Destruction usually involves freeing private data structures
 117 associated with the stream.
 118 Using
 119 .I xdrs
 120 after invoking
 121 .BR xdr_destroy ()
 122 is undefined.
 123 .P
 124 .nf
 125 .BI "bool_t xdr_double(XDR *" xdrs ", double *" dp );
 126 .fi
 127 .IP
 128 A filter primitive that translates between C
 129 .I double
 130 precision numbers and their external representations.
 131 This routine returns one if it succeeds, zero otherwise.
 132 .P
 133 .nf
 134 .BI "bool_t xdr_enum(XDR *" xdrs ", enum_t *" ep );
 135 .fi
 136 .IP
 137 A filter primitive that translates between C
 138 .IR enum s
 139 (actually integers) and their external representations.
 140 This routine returns one if it succeeds, zero otherwise.
 141 .P
 142 .nf
 143 .BI "bool_t xdr_float(XDR *" xdrs ", float *" fp );
 144 .fi
 145 .IP
 146 A filter primitive that translates between C
 147 .IR float s
 148 and their external representations.
 149 This routine returns one if it succeeds, zero otherwise.
 150 .P
 151 .nf
 152 .BI "void xdr_free(xdrproc_t " proc ", char *" objp );
 153 .fi
 154 .IP
 155 Generic freeing routine.
 156 The first argument is the XDR routine for the object being freed.
 157 The second argument is a pointer to the object itself.
 158 Note: the pointer passed to this routine is
 159 .I not
 160 freed, but what it points to
 161 .I is
 162 freed (recursively).
 163 .P
 164 .nf
 165 .BI "unsigned int xdr_getpos(XDR *" xdrs );
 166 .fi
 167 .IP
 168 A macro that invokes the get-position routine
 169 associated with the XDR stream,
 170 .IR xdrs .
 171 The routine returns an unsigned integer,
 172 which indicates the position of the XDR byte stream.
 173 A desirable feature of XDR
 174 streams is that simple arithmetic works with this number,
 175 although the XDR stream instances need not guarantee this.
 176 .P
 177 .nf
 178 .BI "long *xdr_inline(XDR *" xdrs ", int " len );
 179 .fi
 180 .IP
 181 A macro that invokes the inline routine associated with the XDR stream,
 182 .IR xdrs .
 183 The routine returns a pointer
 184 to a contiguous piece of the stream's buffer;
 185 .I len
 186 is the byte length of the desired buffer.
 187 Note: pointer is cast to
 188 .IR "long\ *" .
 189 .IP
 190 Warning:
 191 .BR xdr_inline ()
 192 may return NULL (0)
 193 if it cannot allocate a contiguous piece of a buffer.
 194 Therefore the behavior may vary among stream instances;
 195 it exists for the sake of efficiency.
 196 .P
 197 .nf
 198 .BI "bool_t xdr_int(XDR *" xdrs ", int *" ip );
 199 .fi
 200 .IP
 201 A filter primitive that translates between C integers
 202 and their external representations.
 203 This routine returns one if it succeeds, zero otherwise.
 204 .P
 205 .nf
 206 .BI "bool_t xdr_long(XDR *" xdrs ", long *" lp );
 207 .fi
 208 .IP
 209 A filter primitive that translates between C
 210 .I long
 211 integers and their external representations.
 212 This routine returns one if it succeeds, zero otherwise.
 213 .P
 214 .nf
 215 .BI "void xdrmem_create(XDR *" xdrs ", char *" addr ", unsigned int " size ,
 216 .BI "                   enum xdr_op " op );
 217 .fi
 218 .IP
 219 This routine initializes the XDR stream object pointed to by
 220 .IR xdrs .
 221 The stream's data is written to, or read from,
 222 a chunk of memory at location
 223 .I addr
 224 whose length is no more than
 225 .I size
 226 bytes long.
 227 The
 228 .I op
 229 determines the direction of the XDR stream (either
 230 .BR XDR_ENCODE ,
 231 .BR XDR_DECODE ,
 232 or
 233 .BR XDR_FREE ).
 234 .P
 235 .nf
 236 .BI "bool_t xdr_opaque(XDR *" xdrs ", char *" cp ", unsigned int " cnt );
 237 .fi
 238 .IP
 239 A filter primitive that translates between fixed size opaque data
 240 and its external representation.
 241 The argument
 242 .I cp
 243 is the address of the opaque object, and
 244 .I cnt
 245 is its size in bytes.
 246 This routine returns one if it succeeds, zero otherwise.
 247 .P
 248 .nf
 249 .BI "bool_t xdr_pointer(XDR *" xdrs ", char **" objpp ,
 250 .BI "                   unsigned int " objsize ", xdrproc_t " xdrobj );
 251 .fi
 252 .IP
 253 Like
 254 .BR xdr_reference ()
 255 except that it serializes null pointers, whereas
 256 .BR xdr_reference ()
 257 does not.
 258 Thus,
 259 .BR xdr_pointer ()
 260 can represent
 261 recursive data structures, such as binary trees or
 262 linked lists.
 263 .P
 264 .nf
 265 .BI "void xdrrec_create(XDR *" xdrs ", unsigned int " sendsize ,
 266 .BI "                   unsigned int " recvsize ", char *" handle ,
 267 .BI "                   int (*" readit ")(char *, char *, int),"
 268 .BI "                   int (*" writeit ")(char *, char *, int));"
 269 .fi
 270 .IP
 271 This routine initializes the XDR stream object pointed to by
 272 .IR xdrs .
 273 The stream's data is written to a buffer of size
 274 .IR sendsize ;
 275 a value of zero indicates the system should use a suitable default.
 276 The stream's data is read from a buffer of size
 277 .IR recvsize ;
 278 it too can be set to a suitable default by passing a zero value.
 279 When a stream's output buffer is full,
 280 .I writeit
 281 is called.
 282 Similarly, when a stream's input buffer is empty,
 283 .I readit
 284 is called.
 285 The behavior of these two routines is similar to
 286 the system calls
 287 .BR read (2)
 288 and
 289 .BR write (2),
 290 except that
 291 .I handle
 292 is passed to the former routines as the first argument.
 293 Note: the XDR stream's
 294 .I op
 295 field must be set by the caller.
 296 .IP
 297 Warning: to read from an XDR stream created by this API,
 298 you'll need to call
 299 .BR xdrrec_skiprecord ()
 300 first before calling any other XDR APIs.
 301 This inserts additional bytes in the stream to provide
 302 record boundary information.
 303 Also, XDR streams created with different
 304 .B xdr*_create
 305 APIs are not compatible for the same reason.
 306 .P
 307 .nf
 308 .BI "bool_t xdrrec_endofrecord(XDR *" xdrs ", int " sendnow );
 309 .fi
 310 .IP
 311 This routine can be invoked only on streams created by
 312 .BR xdrrec_create ().
 313 The data in the output buffer is marked as a completed record,
 314 and the output buffer is optionally written out if
 315 .I sendnow
 316 is nonzero.
 317 This routine returns one if it succeeds, zero otherwise.
 318 .P
 319 .nf
 320 .BI "bool_t xdrrec_eof(XDR *" xdrs );
 321 .fi
 322 .IP
 323 This routine can be invoked only on streams created by
 324 .BR xdrrec_create ().
 325 After consuming the rest of the current record in the stream,
 326 this routine returns one if the stream has no more input,
 327 zero otherwise.
 328 .P
 329 .nf
 330 .BI "bool_t xdrrec_skiprecord(XDR *" xdrs );
 331 .fi
 332 .IP
 333 This routine can be invoked only on
 334 streams created by
 335 .BR xdrrec_create ().
 336 It tells the XDR implementation that the rest of the current record
 337 in the stream's input buffer should be discarded.
 338 This routine returns one if it succeeds, zero otherwise.
 339 .P
 340 .nf
 341 .BI "bool_t xdr_reference(XDR *" xdrs ", char **" pp ", unsigned int " size ,
 342 .BI "                     xdrproc_t " proc );
 343 .fi
 344 .IP
 345 A primitive that provides pointer chasing within structures.
 346 The argument
 347 .I pp
 348 is the address of the pointer;
 349 .I size
 350 is the
 351 .I sizeof
 352 the structure that
 353 .I *pp
 354 points to; and
 355 .I 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 .IP
 360 Warning: this routine does not understand null pointers.
 361 Use
 362 .BR xdr_pointer ()
 363 instead.
 364 .P
 365 .nf
 366 .BI "xdr_setpos(XDR *" xdrs ", unsigned int " pos );
 367 .fi
 368 .IP
 369 A macro that invokes the set position routine associated with
 370 the XDR stream
 371 .IR xdrs .
 372 The argument
 373 .I pos
 374 is a position value obtained from
 375 .BR xdr_getpos ().
 376 This routine returns one if the XDR stream could be repositioned,
 377 and zero otherwise.
 378 .IP
 379 Warning: it is difficult to reposition some types of XDR
 380 streams, so this routine may fail with one
 381 type of stream and succeed with another.
 382 .P
 383 .nf
 384 .BI "bool_t xdr_short(XDR *" xdrs ", short *" sp );
 385 .fi
 386 .IP
 387 A filter primitive that translates between C
 388 .I short
 389 integers and their external representations.
 390 This routine returns one if it succeeds, zero otherwise.
 391 .P
 392 .nf
 393 .BI "void xdrstdio_create(XDR *" xdrs ", FILE *" file ", enum xdr_op " op );
 394 .fi
 395 .IP
 396 This routine initializes the XDR stream object pointed to by
 397 .IR xdrs .
 398 The XDR stream data is written to, or read from, the
 399 .I stdio
 400 stream
 401 .IR file .
 402 The argument
 403 .I op
 404 determines the direction of the XDR stream (either
 405 .BR XDR_ENCODE ,
 406 .BR XDR_DECODE ,
 407 or
 408 .BR XDR_FREE ).
 409 .IP
 410 Warning: the destroy routine associated with such XDR streams calls
 411 .BR fflush (3)
 412 on the
 413 .I file
 414 stream, but never
 415 .BR fclose (3).
 416 .P
 417 .nf
 418 .BI "bool_t xdr_string(XDR *" xdrs ", char **" sp ", unsigned int " maxsize );
 419 .fi
 420 .IP
 421 A filter primitive that translates between C strings and
 422 their corresponding external representations.
 423 Strings cannot be longer than
 424 .IR maxsize .
 425 Note:
 426 .I sp
 427 is the address of the string's pointer.
 428 This routine returns one if it succeeds, zero otherwise.
 429 .P
 430 .nf
 431 .BI "bool_t xdr_u_char(XDR *" xdrs ", unsigned char *" ucp );
 432 .fi
 433 .IP
 434 A filter primitive that translates between
 435 .I unsigned
 436 C characters and their external representations.
 437 This routine returns one if it succeeds, zero otherwise.
 438 .P
 439 .nf
 440 .BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned int *" up );
 441 .fi
 442 .IP
 443 A filter primitive that translates between C
 444 .I unsigned
 445 integers and their external representations.
 446 This routine returns one if it succeeds, zero otherwise.
 447 .P
 448 .nf
 449 .BI "bool_t xdr_u_long(XDR *" xdrs ", unsigned long *" ulp );
 450 .fi
 451 .IP
 452 A filter primitive that translates between C
 453 .I "unsigned long"
 454 integers and their external representations.
 455 This routine returns one if it succeeds, zero otherwise.
 456 .P
 457 .nf
 458 .BI "bool_t xdr_u_short(XDR *" xdrs ", unsigned short *" usp );
 459 .fi
 460 .IP
 461 A filter primitive that translates between C
 462 .I "unsigned short"
 463 integers and their external representations.
 464 This routine returns one if it succeeds, zero otherwise.
 465 .P
 466 .nf
 467 .BI "bool_t xdr_union(XDR *" xdrs ", enum_t *" dscmp ", char *" unp ,
 468 .BI "                 const struct xdr_discrim *" choices ,
 469 .BI "                 xdrproc_t " defaultarm ");     /* may equal NULL */"
 470 .fi
 471 .IP
 472 A filter primitive that translates between a discriminated C
 473 .I union
 474 and its corresponding external representation.
 475 It first
 476 translates the discriminant of the union located at
 477 .IR dscmp .
 478 This discriminant is always an
 479 .IR enum_t .
 480 Next the union located at
 481 .I unp
 482 is translated.
 483 The argument
 484 .I choices
 485 is a pointer to an array of
 486 .BR xdr_discrim ()
 487 structures.
 488 Each structure contains an ordered pair of
 489 .RI [ value , proc ].
 490 If the union's discriminant is equal to the associated
 491 .IR value ,
 492 then the
 493 .I proc
 494 is called to translate the union.
 495 The end of the
 496 .BR xdr_discrim ()
 497 structure array is denoted by a routine of value NULL.
 498 If the discriminant is not found in the
 499 .I choices
 500 array, then the
 501 .I defaultarm
 502 procedure is called (if it is not NULL).
 503 Returns one if it succeeds, zero otherwise.
 504 .P
 505 .nf
 506 .BI "bool_t xdr_vector(XDR *" xdrs ", char *" arrp ", unsigned int " size ,
 507 .BI "                  unsigned int " elsize ", xdrproc_t " elproc );
 508 .fi
 509 .IP
 510 A filter primitive that translates between fixed-length arrays
 511 and their corresponding external representations.
 512 The argument
 513 .I arrp
 514 is the address of the pointer to the array, while
 515 .I size
 516 is the element count of the array.
 517 The argument
 518 .I elsize
 519 is the
 520 .I sizeof
 521 each of the array's elements, and
 522 .I elproc
 523 is an XDR filter that translates between
 524 the array elements' C form, and their external
 525 representation.
 526 This routine returns one if it succeeds, zero otherwise.
 527 .P
 528 .nf
 529 .B bool_t xdr_void(void);
 530 .fi
 531 .IP
 532 This routine always returns one.
 533 It may be passed to RPC routines that require a function argument,
 534 where nothing is to be done.
 535 .P
 536 .nf
 537 .BI "bool_t xdr_wrapstring(XDR *" xdrs ", char **" sp );
 538 .fi
 539 .IP
 540 A primitive that calls
 541 .B "xdr_string(xdrs, sp,MAXUN.UNSIGNED );"
 542 where
 543 .B MAXUN.UNSIGNED
 544 is the maximum value of an unsigned integer.
 545 .BR xdr_wrapstring ()
 546 is handy because the RPC package passes a maximum of two XDR
 547 routines as arguments, and
 548 .BR xdr_string (),
 549 one of the most frequently used primitives, requires three.
 550 Returns one if it succeeds, zero otherwise.
 551 .SH ATTRIBUTES
 552 For an explanation of the terms used in this section, see
 553 .BR attributes (7).
 554 .TS
 555 allbox;
 556 lbx lb lb
 557 l l l.
 558 Interface       Attribute       Value
 559 T{
 560 .na
 561 .nh
 562 .BR xdr_array (),
 563 .BR xdr_bool (),
 564 .BR xdr_bytes (),
 565 .BR xdr_char (),
 566 .BR xdr_destroy (),
 567 .BR xdr_double (),
 568 .BR xdr_enum (),
 569 .BR xdr_float (),
 570 .BR xdr_free (),
 571 .BR xdr_getpos (),
 572 .BR xdr_inline (),
 573 .BR xdr_int (),
 574 .BR xdr_long (),
 575 .BR xdrmem_create (),
 576 .BR xdr_opaque (),
 577 .BR xdr_pointer (),
 578 .BR xdrrec_create (),
 579 .BR xdrrec_eof (),
 580 .BR xdrrec_endofrecord (),
 581 .BR xdrrec_skiprecord (),
 582 .BR xdr_reference (),
 583 .BR xdr_setpos (),
 584 .BR xdr_short (),
 585 .BR xdrstdio_create (),
 586 .BR xdr_string (),
 587 .BR xdr_u_char (),
 588 .BR xdr_u_int (),
 589 .BR xdr_u_long (),
 590 .BR xdr_u_short (),
 591 .BR xdr_union (),
 592 .BR xdr_vector (),
 593 .BR xdr_void (),
 594 .BR xdr_wrapstring ()
 595 T}      Thread safety   MT-Safe
 596 .TE
 597 .SH SEE ALSO
 598 .BR rpc (3)
 599 .P
 600 The following manuals:
 601 .RS
 602 eXternal Data Representation Standard: Protocol Specification
 603 .br
 604 eXternal Data Representation: Sun Technical Notes
 605 .br
 606 .IR "XDR: External Data Representation Standard" ,
 607 RFC\ 1014, Sun Microsystems, Inc.,
 608 USC-ISI.
 609 .RE