man3/xdr.3

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